Skip to content

AGENTS.md

Latest commit

 

History

History
123 lines (106 loc) · 8.23 KB

AGENTS.md

File metadata and controls

123 lines (106 loc) · 8.23 KB
Raw

PROJECT KNOWLEDGE BASE

Generated: 2026-07-18 Branch: main Package version: 6.9.1

OVERVIEW

oc-codex-multi-auth is an OpenCode plugin for ChatGPT Plus/Pro OAuth, Codex/GPT-5 request routing (including GPT-5.6 Sol/Terra/Luna responses-lite), multi-account rotation, account switching, health checks, quota status, diagnostics, and recovery tools. The npm bin is an installer that manages OpenCode provider/TUI config and also runs standalone CLI commands (doctor, status, list, limits, dashboard, health, diag, warm). OpenCode loads index.ts as the provider plugin and tui.ts as the prompt quota status plugin. Runtime account state stays local under ~/.opencode with per-project pools enabled by default.

STRUCTURE

./
├── index.ts              # OpenCode provider plugin entry: auth loader, fetch pipeline, tool registry context
├── tui.ts                # OpenCode TUI plugin: prompt quota status and quota details
├── lib/                  # core runtime logic (see lib/AGENTS.md)
├── test/                 # vitest suites (see test/AGENTS.md)
├── scripts/              # installer, standalone CLI, build, audit, and validation helpers
├── config/               # opencode.json examples (modern/full/legacy/minimal)
├── docs/                 # public docs, architecture, audits, maintainer guides
├── skills/               # repo-local setup skill
├── assets/               # static assets
├── .codex-plugin/        # plugin metadata for Codex skill/plugin tooling
└── dist/                 # build output (generated, do not edit)

WHERE TO LOOK

Task Location Notes
Installer + standalone CLI scripts/install-oc-codex-multi-auth.js, scripts/install-oc-codex-multi-auth-core.js npm bin, config merge, cache cleanup, TUI enablement; standalone doctor/status/list/limits/dashboard/health/diag/warm
Plugin orchestration index.ts OAuth loader, request pipeline, metrics, recovery, ToolContext assembly
TUI quota status tui.ts, lib/tui-status.ts, lib/tui-quota-cache.ts, lib/codex-usage.ts prompt quota status, quota details, shared quota cache
Tool registry lib/tools/index.ts + lib/tools/codex-*.ts 24 registered codex-* tools
OAuth flow + PKCE lib/auth/auth.ts, lib/auth/server.ts, lib/auth/device-code.ts, lib/auth/login-runner.ts browser/device/manual login, token refresh, workspace selection
OAuth scopes lib/auth/scopes.ts connector scope validation and re-auth checks
Multi-account rotation lib/accounts.ts, lib/accounts/, lib/rotation.ts rotationStrategy hybrid/sticky/round-robin, health scoring, cooldowns, token bucket, recovery
Account storage lib/storage.ts, lib/storage/ V3 facade, per-project/global paths, keychain, backup/import/export
Request transformation lib/request/request-transformer.ts model normalization, prompt injection, stateless compatibility
Responses-lite (GPT-5.6) lib/request/helpers/responses-lite.ts lite body reshape + header for Sol/Terra/Luna
Client identity lib/request/helpers/client-identity.ts default opencode for 5.6, codex_cli_rs otherwise
Headers + rate limits lib/request/fetch-helpers.ts Codex headers, error mapping, fallback, token refresh
Retry budgets lib/request/retry-budget.ts, lib/request/rate-limit-backoff.ts bounded retry classes, exponential backoff
SSE to JSON lib/request/response-handler.ts stream parsing and empty-response detection
Prompt templates lib/prompts/codex.ts, lib/prompts/opencode-codex.ts, lib/prompts/codex-opencode-bridge.ts model-family detection, Codex prompt cache, bridge prompts
Config parsing lib/config.ts, lib/schemas.ts plugin config and environment overrides (bool env truthy only "1")
Session recovery lib/recovery/, lib/recovery.ts recoverable error handling and auto-resume
Health monitoring lib/health.ts, lib/parallel-probe.ts account health status and concurrent probes
Circuit breaker lib/circuit-breaker.ts failure isolation
Public architecture docs/architecture.md user-facing architecture overview
Maintainer architecture docs/development/ARCHITECTURE.md current subsystem map and invariants
Discoverability guide docs/development/GITHUB_DISCOVERABILITY.md repo description/topics/search wording
Tests test/ Vitest, property tests, docs parity, installer, tool modules, TUI quota

CONVENTIONS

  • Source: root index.ts, tui.ts, lib/, and scripts/; dist/ is generated output.
  • ESLint flat config: no-explicit-any enforced, unused args prefixed _.
  • ESM only ("type": "module"), Node >= 18.
  • Canonical package/plugin name is oc-codex-multi-auth.
  • The npm bin is an installer and thin standalone CLI, not a long-running runtime daemon.
  • OpenCode loads the provider plugin and TUI plugin from built package exports.
  • Default installer mode writes compact modern OpenCode config (12 bases / 53 variants); --full adds 53 explicit selector IDs; --legacy writes legacy explicit-only config; --dry-run and --no-cache-clear are supported.
  • Runtime requests preserve Codex stateless requirements: store: false and reasoning.encrypted_content.
  • GPT-5.6 uses responses-lite shaping and default client identity opencode; other models default to codex_cli_rs.
  • Account selection uses rotationStrategy (hybrid default) with health scoring in lib/rotation.ts.
  • Per-project account storage is enabled by default.
  • Optional OS keychain backend is opt-in with CODEX_KEYCHAIN=1.

ANTI-PATTERNS (THIS PROJECT)

  • Do not edit dist/ or tmp* directories.
  • Do not use as any, @ts-ignore, or @ts-expect-error.
  • Do not open public security issues; see SECURITY.md.
  • Do not hardcode ports other than OAuth callback port 1455; use existing constants/helpers.
  • Do not remove store: false or reasoning.encrypted_content from shipped config templates.
  • Do not treat oc-chatgpt-multi-auth as current except in migration/cleanup logic.
  • Do not expose account emails, access tokens, refresh tokens, or raw prompt/response bodies in normal diagnostics.
  • Do not silently delete JSON credentials when keychain operations fail.
  • Do not document boolean env overrides as truthy for "true" / "yes" — only "1" is truthy.

COMMANDS

npm run build            # clean dist + tsc + copy oauth-success.html
npm run typecheck        # type checking only
npm test                 # vitest once
npm run test:coverage    # vitest coverage
npm run audit:ci         # prod audit + dev allowlist
npm run test:watch       # vitest watch mode
npm run lint             # eslint

Standalone CLI examples:

npx -y oc-codex-multi-auth@latest
npx -y oc-codex-multi-auth@latest --full
oc-codex-multi-auth warm
oc-codex-multi-auth status --json
oc-codex-multi-auth doctor

NOTES

  • OAuth callback: http://127.0.0.1:1455/auth/callback.
  • ChatGPT backend requires store: false, include reasoning.encrypted_content.
  • OpenCode config: ~/.config/opencode/opencode.json.
  • OpenCode TUI config: ~/.config/opencode/tui.json.
  • OpenCode auth tokens: ~/.opencode/auth/openai.json.
  • Plugin config: ~/.opencode/openai-codex-auth-config.json.
  • Per-project accounts: ~/.opencode/projects/<project-key>/oc-codex-multi-auth-accounts.json.
  • Global accounts: ~/.opencode/oc-codex-multi-auth-accounts.json.
  • Flagged accounts: ~/.opencode/oc-codex-multi-auth-flagged-accounts.json.
  • Request logs: ~/.opencode/logs/codex-plugin/ when logging is enabled.
  • Model catalog: 12 modern bases / 53 variants; legacy 53 explicit.
  • Bases: 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.
  • Prompt templates sync from Codex CLI GitHub releases with ETag caching; 5.6 instructions come from the Codex model catalog.
  • 5xx server errors trigger account rotation and health penalty like network errors.
  • API deprecation/sunset headers (RFC 8594) are logged as warnings.
  • StorageError preserves original stack traces via cause parameter.
  • saveToDiskDebounced errors are logged but do not crash the plugin.