Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
323 lines (254 loc) · 17.4 KB

ARCHITECTURE.md

File metadata and controls

323 lines (254 loc) · 17.4 KB
Raw

Architecture

Runtime architecture for the oc-codex-multi-auth OpenCode plugin, installer, ChatGPT Plus/Pro OAuth flow, Codex/GPT-5 request bridge (including GPT-5.6 responses-lite), multi-account rotation, codex-* tool registry, TUI quota status plugin, and local storage model.

Reflects the codebase as of the current main branch. Historical audit section markers are retained in the docs tree for traceability, but this file is the current maintainer architecture source.

Design Goals

  1. Make OpenCode ChatGPT OAuth setup short and repeatable (npx -y oc-codex-multi-auth@latest).
  2. Keep OpenCode as the host runtime while the plugin owns only the OAuth-backed Codex routing layer.
  3. Preserve Codex backend invariants: stream: true, store: false, and reasoning.encrypted_content.
  4. Make multi-account state visible through account switching, health checks, diagnostics, quota status, and recovery commands.
  5. Keep account storage local by default, with explicit export/import and optional OS keychain migration.
  6. Keep the broad OpenCode tool surface modular: every registered codex-* tool is its own file under lib/tools/.
  7. Keep public docs search-friendly without overstating support, affiliation, or production/commercial use.

System Diagram

Install / refresh / standalone CLI
  |
  | npx -y oc-codex-multi-auth@latest
  |   default compact modern | --full | --legacy
  |   [--dry-run] [--no-cache-clear]
  | standalone: doctor | status | list | limits | dashboard | health | diag | warm
  v
scripts/install-oc-codex-multi-auth.js
  |- delegates to scripts/install-oc-codex-multi-auth-core.js
  |- writes ~/.config/opencode/opencode.json
  |- writes ~/.config/opencode/tui.json
  |- merges config/opencode-modern.json and/or config/opencode-legacy.json
  |- normalizes old package/plugin entries
  |- clears OpenCode plugin cache (unless --no-cache-clear)

OpenCode runtime
  |
  | loads plugin package
  v
index.ts
  |- auth loader: browser callback, device code, manual URL paste
  |- account manager + V3 storage + optional keychain
  |- custom provider fetch pipeline
  |- runtime metrics, retry budgets, circuit breaker, recovery hooks
  |- ToolContext construction
  v
lib/tools/index.ts
  |- registers 24 OpenCode tools
  |- each tool delegates to lib/tools/codex-*.ts

Request path
  |
  | OpenCode OpenAI SDK request
  v
lib/request/fetch-helpers.ts + lib/request/request-transformer.ts
  |- rewrite URL to Codex/ChatGPT backend
  |- native mode: preserve host payload shape
  |- legacy mode: apply compatibility rewrites
  |- force store:false and include reasoning.encrypted_content
  |- GPT-5.6: responses-lite reshape + opencode client identity
  |- other models: codex_cli_rs client identity (default)
  |- resolve modelAccountPools preferred accounts
  |- select/refresh account (hybrid health scoring)
  |- attach OAuth headers
  v
ChatGPT-backed Codex endpoint
  |
  v
lib/request/response-handler.ts
  |- SSE parsing
  |- error mapping
  |- quota/rate-limit/header extraction
  |- empty-response retries

OpenCode TUI runtime
  |
  v
tui.ts
  |- reads account/quota snapshots
  |- refreshes compact usage state when possible
  |- renders prompt quota status and details

Core Subsystems

Subsystem Key files Responsibility
Installer CLI scripts/install-oc-codex-multi-auth.js, scripts/install-oc-codex-multi-auth-core.js npm bin; config merge; cache cleanup; modern/full/legacy catalog selection; standalone doctor/status/list/limits/dashboard/health/diag/warm; TUI plugin enablement
OpenCode plugin entry index.ts auth loader, runtime wiring, custom fetch pipeline, account manager lifecycle, ToolContext, OpenCode plugin export
TUI plugin entry tui.ts, lib/tui-status.ts, lib/tui-quota-cache.ts, lib/codex-usage.ts prompt quota status, account-aware quota snapshots, usage refresh, details rendering
Auth flow lib/auth/auth.ts, lib/auth/server.ts, lib/auth/browser.ts, lib/auth/device-code.ts, lib/auth/login-runner.ts, lib/auth/scopes.ts PKCE OAuth, callback server, device/manual login, workspace/account selection, scope validation
Account manager lib/accounts.ts, lib/accounts/ account state facade, persistence, rotation, recovery, rate-limit tracking, workspace identity preservation, warm
Storage lib/storage.ts, lib/storage/ V3 JSON storage, atomic writes, migrations, per-project paths, backups, import/export, keychain opt-in, flagged accounts
Request bridge lib/request/fetch-helpers.ts, lib/request/request-transformer.ts, lib/request/response-handler.ts, lib/request/retry-budget.ts, lib/request/rate-limit-backoff.ts, lib/request/helpers/ URL/body/header shaping, Codex invariants, responses-lite, client identity, SSE conversion, retry budgets, backoff, error mapping
Model/prompt mapping lib/prompts/codex.ts, lib/prompts/opencode-codex.ts, lib/prompts/codex-opencode-bridge.ts, lib/request/helpers/model-map.ts model-family detection, Codex instructions cache, OpenCode prompt adaptation, fallback aliases
Tool registry lib/tools/index.ts, lib/tools/codex-*.ts 24 OpenCode tools for setup, account switching, status, health, quota resets, diagnostics, backup, keychain, and recovery
Runtime support lib/runtime.ts, lib/circuit-breaker.ts, lib/proactive-refresh.ts, lib/parallel-probe.ts, lib/recovery/, lib/rotation.ts, lib/shutdown.ts pure runtime helpers, failure isolation, refresh scheduling, health probing, hybrid selection scoring, session recovery, cleanup
UI helpers lib/ui/ terminal formatting, auth menu, select/confirm prompts, theme/color handling, beginner checklist
Config templates config/opencode-modern.json, config/opencode-legacy.json, config/minimal-opencode.json, config/README.md copy-paste OpenCode provider templates and model catalog guidance
Tests test/ Vitest suites for auth, request transforms, storage, rotation, tools, TUI quota, installer, docs parity, and release regressions

Documentation Layout

The current docs tree mirrors the codebase boundaries above: user docs cover setup and operations, maintainer docs cover internal architecture and validation, and the regenerated audit corpus records point-in-time architecture findings.

docs/
├── index.md                  # docs landing page
├── README.md                 # docs portal navigation
├── DOCUMENTATION.md          # repository documentation map
├── architecture.md           # public architecture overview
├── getting-started.md        # install, auth, and first-run guide
├── configuration.md          # public config reference
├── troubleshooting.md        # operational failure modes and fixes
├── faq.md                    # short common answers
├── privacy.md                # local data and upstream request notes
├── OPENCODE_PR_PROPOSAL.md   # upstream OpenCode proposal notes
├── _config.yml               # docs site config
├── development/              # maintainer architecture and validation docs
│   ├── ARCHITECTURE.md
│   ├── GITHUB_DISCOVERABILITY.md
│   ├── CONFIG_FIELDS.md
│   ├── CONFIG_FLOW.md
│   ├── TESTING.md
│   └── TUI_PARITY_CHECKLIST.md
└── audits/                   # current-structure audit corpus
    ├── INDEX.md
    ├── 01-executive-summary.md ... 16-verdict.md
    ├── _findings/            # T01 through T16 detailed findings
    └── _meta/                # audit rubric, ledger, environment, verification

Request Pipeline

High-level provider fetch flow:

  1. Parse OpenCode request URL and body.
  2. Resolve plugin config from defaults, ~/.opencode/openai-codex-auth-config.json, and environment overrides (boolean env truthy only for "1").
  3. Choose request transform mode:
    • native keeps OpenCode payloads unchanged except required Codex invariants.
    • legacy fetches Codex/OpenCode prompts and applies compatibility rewrites.
  4. Enforce ChatGPT-backed Codex invariants:
    • stream: true
    • store: false
    • include: ["reasoning.encrypted_content"] or equivalent inclusion
  5. Normalize model aliases and fallback candidates (including GPT-5.6 Sol/Terra/Luna tiers).
  6. For GPT-5.6 models, apply the responses-lite reshape (lib/request/helpers/responses-lite.ts): tools move into input as additional_tools, instructions become a developer message, top-level tools/instructions are cleared for lite shape, image detail is stripped, and x-openai-internal-codex-responses-lite: true is set.
  7. Resolve client identity (lib/request/helpers/client-identity.ts): GPT-5.6 defaults to originator: opencode; other models default to codex_cli_rs. Override with CODEX_AUTH_CLIENT_IDENTITY.
  8. Resolve preferred accounts from modelAccountPools for the effective model; fall back to the general pool when the preferred pool is empty or unavailable.
  9. Resolve account/workspace selection with the configured rotationStrategy (default hybrid health scoring), cooldown, token bucket, and explicit CODEX_AUTH_ACCOUNT_ID constraints.
  10. Refresh tokens through the queued refresh path when needed.
  11. Attach OAuth/Codex headers and forward the request.
  12. Parse SSE responses, quota headers, retryable errors, empty responses, and unsupported-model details.
  13. Update runtime metrics, account health, circuit breaker state, TUI quota cache, and persisted storage.
  14. On recoverable failures, apply session recovery / auto-resume hooks when enabled.

Stateless Codex Contract

The ChatGPT-backed Codex path rejects server-side storage for this plugin's request shape, so the runtime keeps requests stateless with store: false.

Context is preserved through:

  • full message history supplied by OpenCode
  • tool call and tool output history in that message history
  • reasoning.encrypted_content returned by the backend and sent back on later turns

Legacy mode exists for compatibility with older OpenCode/AI SDK payload behavior. It removes unsupported item_reference items and message IDs that cannot be looked up when store: false is active. Native mode is the default and preserves the host payload shape as much as possible.

GPT-5.6 responses-lite is a separate body shape layered on top of the same stateless contract: tool definitions live in the input prefix rather than the top-level tools field.

Tool Registry Architecture

The plugin exposes 24 OpenCode tools through lib/tools/index.ts. index.ts builds one ToolContext from plugin-closure state and helper functions, then passes it to createToolRegistry(ctx).

Why this shape exists:

  • per-tool modules keep index.ts from absorbing every command implementation
  • mutable refs let tools invalidate or replace account-manager state without global singletons
  • shared helpers keep formatting, routing visibility, and beginner diagnostics consistent
  • schema helpers stay close to each tool to avoid leaking bundled zod type identities across module boundaries

Tool groups:

Group Tools
Setup and help codex-setup, codex-help, codex-next
Daily account use codex-list, codex-switch, codex-warm, codex-status, codex-limits, codex-reset, codex-dashboard
Account metadata and routing codex-label, codex-tag, codex-note, codex-pool, codex-remove, codex-refresh
Diagnostics codex-health, codex-metrics, codex-doctor, codex-diag, codex-diff
Backup/secrets codex-export, codex-import, codex-keychain

Standalone CLI mirrors a subset without loading the agent: doctor, status, list, limits, dashboard, health, diag, warm.

Storage Model

Canonical OpenCode plugin state lives under ~/.opencode, while OpenCode config lives under ~/.config/opencode.

File Purpose
~/.config/opencode/opencode.json OpenCode provider/plugin config managed by installer
~/.config/opencode/tui.json OpenCode TUI plugin config managed by installer
~/.opencode/auth/openai.json OpenCode auth token file
~/.opencode/openai-codex-auth-config.json plugin runtime config
~/.opencode/oc-codex-multi-auth-accounts.json global V3 account pool
~/.opencode/projects/<project-key>/oc-codex-multi-auth-accounts.json project-scoped V3 account pool
~/.opencode/oc-codex-multi-auth-flagged-accounts.json flagged/deactivated account metadata
~/.opencode/backups/ account backup/export target
~/.opencode/logs/codex-plugin/ request/debug logs when enabled

Storage invariants:

  1. V1/V2 account files migrate into V3 on load/save paths (V2 surfaces a typed recovery error rather than silent discard).
  2. Per-project storage is enabled by default and keyed by detected project identity.
  3. JSON files are written atomically where supported.
  4. Optional keychain storage is opt-in via CODEX_KEYCHAIN=1.
  5. Import supports dry-run preview and creates pre-import backups when existing accounts are present.

Session Recovery Storage

When sessionRecovery is true (default), lib/recovery/ may rewrite OpenCode host storage:

Path Purpose
$XDG_DATA_HOME/opencode/storage (or %APPDATA%/opencode/storage on Windows; else ~/.local/share/opencode/storage) Root
…/message/{sessionID}/… Session messages
…/part/{messageID}/*.json Message parts (thinking inject/strip, synthetic tool results)

Recovered classes: tool_result_missing, thinking_block_order, thinking_disabled_violation. Optional autoResume re-prompts after thinking recovery.

TUI Quota Status Flow

tui.ts is loaded by OpenCode's TUI plugin system after the installer writes ~/.config/opencode/tui.json.

  1. Resolve the active account fingerprint from stored accounts.
  2. Read OpenCode KV quota state and the shared quota cache.
  3. Refresh usage data when enough time has passed and the active account is eligible.
  4. Render compact prompt status only inside active sessions.
  5. Expose quota details without leaking account tokens.

The request path also writes quota snapshots from response headers, so the TUI can reflect the account/workspace used by the latest request.

Model Catalog and Fallback Notes

The default installer writes the modern OpenCode template (config/opencode-modern.json):

  • 12 base model families in the picker:
    • gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna
    • gpt-5.5, gpt-5.5-fast
    • gpt-5.4-mini, gpt-5.4-nano
    • gpt-5.1-codex-max, gpt-5.1-codex, gpt-5.1-codex-mini, gpt-5.1, gpt-5-codex
  • 53 effective variants through OpenCode's variant selector
  • store: false
  • reasoning.encrypted_content
  • large context/output metadata for supported model families

--full adds 53 explicit selector IDs for scripts. --legacy writes the explicit-only template (53 entries) for older OpenCode versions.

Unsupported-model behavior is strict by default. Default auto-fallbacks still cover common entitlement gates for GPT-5.6 tiers → gpt-5.5, and for gpt-5.5 / gpt-5-codex through the GPT-5.4 family. Full generic fallback can be enabled through config or environment variables.

Rotation and Reliability

  • rotationStrategy default hybrid: stick while healthy, otherwise score-select (health + tokens + freshness). Alternatives: sticky, round-robin.
  • lib/rotation.ts owns hybrid health scoring; lib/accounts/rotation.ts wires it into account manager state.
  • Circuit breaker isolates repeated failures per account/path.
  • Empty-response retries use emptyResponseMaxRetries / emptyResponseRetryDelayMs.
  • Optional parallelProbing can probe account health concurrently (default off).

Invariants

  1. OAuth callback port remains 1455.
  2. Dist output is generated; source of truth is index.ts, tui.ts, lib/, scripts/, config/, and docs/.
  3. The canonical package and plugin entry is oc-codex-multi-auth (exports "." and "./tui").
  4. The installer should normalize stale oc-chatgpt-multi-auth entries rather than preserve duplicates.
  5. ChatGPT-backed Codex requests use store: false.
  6. reasoning.encrypted_content must stay available for multi-turn continuity.
  7. Account emails and tokens must not be exposed in diagnostic payloads or response headers.
  8. Keychain failures must not silently delete JSON credentials.
  9. Account pool limits stay at ACCOUNT_LIMITS (max 20, 30s auth cooldown, remove after 3 consecutive auth failures).
  10. Codex CLI hydrate from ~/.codex stays on unless CODEX_AUTH_SYNC_CODEX_CLI=0.
  11. Startup prewarm runs only for legacy request transform when not disabled via CODEX_AUTH_PREWARM=0.
  12. Installer help/post-install strings must match the live catalog (12 modern bases / 53 variants; 53 legacy explicit).
  13. Tool additions require a per-file factory, registry wiring, and focused test/docs updates.
  14. Boolean environment overrides are truthy only for the literal string "1".
  15. Docs, package metadata, GitHub About text, and plugin metadata should lead with OpenCode, ChatGPT OAuth, Codex/GPT-5 routing, multi-account rotation, account switching, health checks, diagnostics, and recovery tools.

Verification

Recommended local validation for architecture/docs/metadata changes:

npm test -- test/doc-parity.test.ts
npm run typecheck
npm run lint
npm run build
git diff --check

Use npm test when source behavior changes or when documentation edits touch tested runtime contracts.