convez.ai
MCP Server
Jesssullivan

oauth-mux

Jesssullivan/oauth-mux

Ver no GitHub
InicialPluginScore · de 0 a 100

WIP! Experimental! Sophisticated grand-scale oauth multiplexing for shiny autonomous robots and productive humans.

Instalação

$npx convez-ai Jesssullivan/oauth-mux

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 3 semanas
Versão
v0.1.15
Issues abertas
13
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

oauth-mux

oauth-mux is OAuth/account multiplexing for professional AI harnesses and autonomous agents.

Developers and agents now operate across personal, work, team, subscription, API-key, and service identities. Most CLIs still expose a brittle single-account path: one local auth store, one active subscription, one opaque 401/429 failure surface. oauth-mux puts a broker in front of that path so a harness session can stay usable when auth, quota, tier, or local runtime state changes.

The product bar is intentionally narrow and hard:

The user runs oauth-mux <harness> such as oauth-mux codex. The harness behaves like the real one. The active subscription account exhausts quota. Another credited account is substituted in place. The harness process is not restarted. The user is not prompted.

Restart, supervised relaunch, route warming, and prepared_fallback are diagnostic infrastructure. They are not product success.

Current Truth

Public install lanes are versioned by channel. 0.1.13 is the current verified public release for GitHub Release, curl installer, deb/rpm assets, and the Homebrew tap. It is the first release carrying the home-is-store managed-Codex session-authority default (canonical bridge is explicit opt-in), the flock unlink-on-release race fix with the macOS runtime-dir move (restart long-lived managed sessions after upgrading), the default-mode native resume chooser, and corrected Claude OAuth endpoint constants. The npm lane is retired as of 2026-06-12 (the published package remains stale at 0.1.9); install via Homebrew, the curl installer, or system packages. Homebrew remains binary-only by default: brew install jesssullivan/omux/oauth-mux installs oauth-mux and must not install or link a managed codex shim.

What works today:

  • Managed Codex launch and resume through oauth-mux codex and oauth-mux codex resume, including the native resume chooser against the selected account's route-local persistent home in the default mode.
  • Current source/user-local dogfood can include a managed codex shim, so a bare codex command is managed only when PATH resolves that shim. Admin commands such as codex login and codex --version must pass through to native Codex. Direct native Codex binaries and already-running native sessions are not globally protected.
  • Route-local persistent Codex session authority for managed muxed runs. Current managed Codex uses the selected account home as CODEX_HOME, keeps muxed state_5.sqlite* / logs_2.sqlite* out of canonical ~/.codex by default, and preserves Codex's built-in openai provider namespace for proxy routing. Legacy canonical bridge behavior is explicit opt-in via shared_canonical.
  • Managed Codex config is written fresh per launch in the default mode (proxy override plus managed feature defaults) and scrubbed on exit; root-partitioned user-config passthrough ([features], legacy experimental_*, MCP servers, approval/sandbox policy, profiles, model defaults, non-managed provider definitions) currently applies on the legacy shared_canonical bridge path only.
  • Lazy account refresh at credential materialization or explicit repair time; managed launch reports pre_spawn_network_refresh:false.
  • Managed Codex launch/resume auto-revalidates expired Codex quota/rate windows under the Codex stay-afloat policy before route election. Interactive login remains user-mediated.
  • Live managed Codex quota handoff for installed oauth-mux codex resume, with the strongest preserved proof in docs/evidence/codex-engineered-quota-handoff-20260509/.
  • Redacted JSON diagnostics and opt-in trace JSONL for agents and operators.

Still research or open:

  • Same-thread provider semantic continuity across account boundaries.
  • Mid-turn streaming recovery.
  • Unmanaged bare-codex daemon hot-swap.
  • Non-Codex provider stay-afloat proof.
  • Long-window soak and negative permutation cassette coverage.

Lifecycle

flowchart LR
    install["Install"] --> init["init"]
    init --> enroll["Enroll accounts"]
    enroll --> diagnose["Local diagnostics"]
    diagnose --> route["Route selection"]
    route --> launch["Managed harness launch"]
    launch --> signal["Provider signal observed"]
    signal --> decision["Broker decision"]
    decision --> materialize["Fallback materialization"]
    materialize --> status["Redacted status artifact"]
    status --> repair["Repair / revalidate loop"]
    repair --> diagnose
sequenceDiagram
    participant User
    participant Mux as oauth-mux
    participant Codex
    participant Proxy
    participant Provider

    User->>Mux: oauth-mux codex resume
    Mux->>Mux: select route
    Mux->>Mux: build auth/config overlay
    Mux->>Mux: bridge canonical session authority
    Mux->>Codex: spawn managed Codex
    Codex->>Proxy: responses request
    Proxy->>Provider: selected account request
    Provider-->>Proxy: 200 / 401 / 429 usage_limit_reached / tier or rate error
    Proxy->>Mux: classify signal
    Mux-->>Proxy: retry fallback when eligible
    Proxy-->>Codex: successful response or typed terminal result
    Mux->>Mux: write redacted evidence

Route-state labels are stable public vocabulary: available, quota_exhausted, rate_limited, tier_insufficient, auth_permanently_failed, credential_unavailable, revalidation_needed, and not_afloat.

See docs/lifecycle.md for the deeper lifecycle, agent control-plane, and claim ladder diagrams.

Install

Public install lanes:

brew install jesssullivan/omux/oauth-mux

The Homebrew formula is intentionally binary-only. It should not change command -v codex; use the explicit local, Nix, or future opt-in package shim lanes when testing managed bare-codex behavior.

Nix users can choose the binary-only package or the managed-shim package:

nix build .#oauth-mux
nix build .#withCodexShim

Home Manager users should import inputs.oauth-mux.homeManagerModules.default. The module installs only oauth-mux by default; set programs.oauth-mux.codexShim.enable = true to intentionally put the managed codex shim on PATH. See docs/home-manager.md.

Unreleased source dogfood should keep provenance explicit:

just install-local-dogfood
which -a oauth-mux
which -a codex
oauth-mux version
oauth-mux version --json
oauth-mux codex preflight --profile codex-max --capability codex-max --json

If which -a oauth-mux resolves Homebrew before the user-local dogfood binary, adjust PATH or invoke ./zig-out/bin/oauth-mux directly for source-tree proof.

version --json prints the active executable path classification, SHA-256, and compiled build_id under runtime_identity. Use it when public packages and local dogfood have nearby version strings and you need machine-readable proof of the exact binary that will run.

codex preflight prints the active oauth-mux path, all visible oauth-mux and codex PATH candidates, whether active codex is the managed oauth-mux shim, the first native Codex binary, and the OMUX_CODEX_BIN escape hatch. Use that before debugging stale package or managed-versus-unmanaged Codex behavior. It also reports redacted shell context, including whether CODEX_HOME is set, whether it is an oauth-mux managed overlay, and whether inherited OMUX_* managed-session variables are present. If a shell refresh changes the result, start a fresh shell or use the shell's native reload path. For example, fish cannot safely source ~/.bashrc; bash syntax can fail partway through and leave a misleading mixed environment. Its JSON separates agent_safe_next_actions from spend_confirmed_next_actions; text output uses matching diagnostics and spend-confirmed repair sections. The same JSON includes repair_summary, a compact blocked-route rollup for agents that need to distinguish expired quota-window revalidation, auth handoff, runtime repair, and wait-only states without scraping per-route diagnostics.

On macOS, do not overwrite the old Mach-O in place. A direct cp over the installed binary can leave stale taskgated/code-signing state on the old vnode and produce an immediate SIGKILL / status 137.

just install-local-dogfood stages the new binary in the install directory, renames it into place, verifies the installed hash against ./zig-out/bin/oauth-mux, prints the installed version, and leaves the native codex command unshadowed by default. Before replacing the binary, it refuses when active managed oauth-mux codex sessions are visible and prints a redacted parent/child PID and listener-port report. Re-run with OMUX_DOGFOOD_ALLOW_ACTIVE_SESSIONS=1 only after explicitly accepting that already-running sessions keep their current process image.

Use just install-local-dogfood-shim or set OMUX_DOGFOOD_INSTALL_CODEX_SHIM=1 only when you intentionally want ~/.local/bin/codex to enter managed Codex sessions through oauth-mux. The shim resolves the native upstream Codex executable, passes native admin commands through, and enters oauth-mux codex for managed session commands. It refuses to replace a non-oauth-mux codex already in that directory unless OMUX_DOGFOOD_REPLACE_CODEX=1 is set. Use just uninstall-local-dogfood to remove the local dogfood binary and any oauth-mux-marked codex shim without touching a native Codex executable. Public packages may carry a managed codex shim, but installed behavior must still be proven with version --json, which -a codex, and codex preflight when you need to distinguish a package binary from a worktree dogfood binary. The installer warns if the copied user-local binary is still shadowed by a Homebrew or other PATH entry.

Usage

Human first run:

oauth-mux init --codex-max
oauth-mux doctor
oauth-mux route explain --profile codex-max --capability codex-max
oauth-mux codex resume

Managed oauth-mux codex launch/resume reads defaults.profile and defaults.capability when they are configured. Existing Codex Max configs also fall back to the conventional codex-max profile, so explicit profile flags are needed only for diagnostics, alternate profiles, or scripted proof.

If a route needs upstream auth, run the labeled handoff reported by route explain, for example:

oauth-mux codex login-device max-3

Agent-safe inspection:

oauth-mux doctor runtime --profile codex-max --capability codex-max --json
oauth-mux accounts list --provider codex --json
oauth-mux route explain --profile codex-max --capability codex-max --json
oauth-mux repair-plan --profile codex-max --capability codex-max --json
oauth-mux codex preflight --profile codex-max --capability codex-max --json
oauth-mux codex status-latest --json

When shell, install, auth, and route-health state disagree, enable the redacted trace sink:

OMUX_TRACE=1 \
OMUX_TRACE_FILE=/tmp/oauth-mux-trace.ndjson \
oauth-mux codex preflight --profile codex-max --capability codex-max --json

See docs/tracing.md for the trace schema and redaction contract.

Those inspection commands do not spend provider calls. In the current release, managed Codex launch/resume and admitted stay-afloat execution may spend provider calls only to revalidate expired Codex quota/rate windows before route election. Live probes, broad revalidation, and non-Codex provider-spend paths remain explicit.

UX / DX / AX Contract

UX:

  • The managed harness should feel native.
  • There is no hidden daemon dependency for the current Codex path.
  • Handoffs are labeled and user-mediated when upstream login is required.

DX:

just build
just test
just check
just e2e

The explicit aliases remain available:

just remote-build
just remote-test
just remote-check
just remote-e2e

Use just release-proof <version> [ref] or just remote-release-proof <ref> <version> before any registry mutation. Local zig build, just build-local, just test-local, just check-local, and just e2e-local are debugging tools only; they are not the proof path for PR, release, or dogfood readiness on low-power developer machines.

AX:

  • JSON surfaces are redacted and account-label based.
  • Trace events are opt-in and must not print token bytes, raw provider account ids, raw Codex session ids, or local auth/config file paths.
  • Agents do not need token files or raw provider stores to choose a next action.
  • Provider-spend behavior is policy-labeled; diagnostic inspection surfaces stay separate from managed Codex auto-revalidation and live probes.
  • Diagnostic output should include exact next-action commands.

Proof

Keep the claim ladder tied to evidence:

  • docs/qa-handoff-matrix.md: route states, handoff patterns, and current Codex truth.
  • docs/productionization-ledger.md: UX/DX/AX stance, feature ledger, adapter strategy, daemon beta boundary, release posture, and tracker map.
  • docs/release-install-lanes.md: public package lanes versus local dogfood lanes.
  • docs/dogfood-process-fanout.md: diagnostic agent process topology snapshots and cleanup rules for suspected helper fanout or RSS growth.
  • docs/lifecycle.md: application lifecycle, managed Codex flow, agent-safe control plane, and claim levels.
  • docs/spec/in-agent-reauth-handoff-contract-2026-05-14.md: agent/MCP contract for user-mediated reauth prompts, consent, and redaction.
  • docs/tracing.md: opt-in trace schema, sink selection, and redaction rules.
  • docs/evidence/codex-engineered-quota-handoff-20260509/: current headline managed Codex quota-handoff proof.

The product anchor is docs/spec/broker-mcp-contract-2026-05-03.md. The Codex adapter contract is docs/spec/codex-adapter-contract-2026-05-03.md.

Ver o original no GitHub

Bom para

Relacionados