stablyai / stablyai/orca

[PLATFORM] Release versioned Codex account-transition bridge

Open
#18,643 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
72.1k
Forks
4.7k
Avg merge
14h 54m
Merged PRs (30d)
520

Description

## Problem or use case

Orca 1.4.190 exposes authenticated agent-hook protocol v1, but Codex hook events contain no account-switch event. `accounts.subscribe` exposes only an unversioned current snapshot, and terminal list/show expose no account or switch metadata. A caller therefore cannot prove that a real Orca-managed Codex account transition happened or bind it to the launch and SessionStart that followed it without inventing caller authority.

Work key: `orca-codex-account-transition-bridge`

This is a platform prerequisite for `GStrix/GreedyAutoBrauser#220`, transitively blocking `GStrix/GreedyAutoBrauser#132`. Orca issue #10137 is related account failover/conversation-handoff work, but it does not own this general authenticated transition-receipt contract. Issue #10947 is related hook-scope work, not a transition producer.

Observed source basis: `stablyai/orca@637dc30a3211ec0667c55118a4d17edbee5cff80` (`main`).

## Proposed solution

Release an authenticated, non-caller-derived receipt schema named `orca-codex-account-transition-receipt/v1`.

The Orca-owned bridge should:

- establish the first authenticated account snapshot as a baseline, never as a transition;
- observe a subsequent committed Codex active-account change inside Orca;
- mint opaque, equality-comparable previous/current account references without exposing raw account identity;
- persist a strictly monotonic transition boundary across restart and concurrency;
- join that boundary only to the first matching authenticated Codex SessionStart using exact terminal, launch, session, current-account, and ordering predicates;
- expose the raw typed receipt through the existing authenticated agent-hook boundary;
- emit no proof when the transition or join is missing, ambiguous, stale, reordered, replayed, or mismatched.

The receipt should carry a schema/version, transition identity and sequence, bounded timestamps, opaque previous/current references, exact terminal/launch/session/SessionStart identities, producer version, and a canonical integrity digest. The exact shape should remain additive and follow Orca's remote-wire compatibility rules.

### Acceptance criteria

- The initial unversioned snapshot cannot become account-switch proof.
- A real active-account change produces one durable monotonic boundary; no-op selection produces none.
- Missing persistence or post-acquire revalidation fails closed without publishing success.
- The join accepts only the first exact authenticated matching SessionStart.
- Wrong account, terminal, launch, session, ordering, replay, rapid A→B→A, restart, and concurrency cases are covered by focused tests.
- Opaque references do not disclose account IDs, email, credentials, tokens, home paths, or other authentication material.
- The typed receipt is consumable directly by a repository observer without trusting caller-provided booleans, hashes, or JSON authority.
- Cross-platform, local/folder-workspace, SSH/remote, mixed-version, performance, and basic security behavior receive explicit review.
- Release/version changes remain maintainer-managed under the existing Orca release workflow.

### Bounded implementation envelope

- `src/shared/agent-hook-types.ts`
- `src/main/agent-hooks/server.ts`
- `src/main/agent-hooks/codex-account-transition-bridge.ts` (new)
- `src/main/agent-hooks/codex-account-transition-bridge.test.ts` (new)
- `src/main/agent-hooks/server.test.ts` (new only if the focused server join cannot live in the bridge test)
- Existing maintainer-owned release metadata only if requested by a maintainer

Any need to modify the account manager, generic terminal APIs, relay protocol, remote runtime, or other source paths must be justified and reviewed as a separate scope decision before implementation.

### Non-goals

- No caller-asserted AccountSwitch JSON, booleans, hashes, environment claims, or direct-script proof.
- No inference from an initial or otherwise unversioned account-list snapshot.
- No raw account identity or credential material.
- No automatic failover, conversation migration, account-pool policy, or account-manager redesign.
- No generic terminal, relay, remote-runtime, or agent-hook redesign.
- No live account switching, production lifecycle run, deployment, or credential access as part of development verification.
- No change to the downstream GAB acceptance state merely because this issue exists or a patch merges.

## Alternatives or additional context

Keeping account switch as an unproved downstream facet is safe but permanently blocks the intended lifecycle acceptance. Treating the current account snapshot as a transition is rejected because it has neither a versioned boundary nor a launch/SessionStart join.

Contributor guide

Open the contributing guide

Research direction

Start with src/shared/agent-hook-types.ts and src/main/agent-hooks/server.ts, then review the proposed bridge and focused test paths in src/main/agent-hooks/codex-account-transition-bridge.ts and its test file. Trace the existing authenticated agent-hook boundary and release compatibility rules before defining the additive receipt contract. Done means focused tests cover durable transitions, exact SessionStart joining, restart/concurrency and mismatch cases without exposing account identity.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
backend-api-design, devtools
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
40/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.