[PLATFORM] Release versioned Codex account-transition bridge
- 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
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