maestro-agent-sdk 0.1.26 → 0.1.27

package/dist/providers/codex-auth.js

@@ -0,0 +1,312 @@
+/**
+ * Codex OAuth loader + refresh.
+ *
+ * Reads `~/.codex/auth.json` (the file the upstream `codex` CLI maintains) and
+ * surfaces the access token in the shape the Codex Responses provider needs.
+ * Handles JWT-claim extraction for the `ChatGPT-Account-ID` Cloudflare header
+ * and refreshes the access token against `https://auth.openai.com/oauth/token`
+ * when it is past the configured skew threshold.
+ *
+ * Why we read codex's own file rather than running our own OAuth flow:
+ *   - The user already authenticated via `codex login`. Forcing a second
+ *     OAuth dance just to use the same backend would be hostile UX.
+ *   - codex CLI rotates refresh tokens periodically and writes them back to
+ *     `auth.json`. We write the rotated refresh token back to the same file
+ *     so both clients stay in sync — single source of truth.
+ *
+ * Hermes reference: `hermes_cli/auth.py::refresh_codex_oauth_pure` and
+ * `agent/auxiliary_client.py::_codex_cloudflare_headers`. Behavioral parity
+ * with those two functions is the bar — diverge only when a TS-specific
+ * concern (no httpx, no JWT lib) forces it.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * OAuth `client_id` the upstream codex CLI registered with OpenAI's OAuth
+ * server. Pinned because the refresh endpoint validates it; rotating without
+ * coordinating with codex CLI would break tokens for both clients.
+ */
+const CODEX_OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+const CODEX_OAUTH_TOKEN_URL = "https://auth.openai.com/oauth/token";
+/** Refresh when the access token has < this many seconds left. The hermes
+ *  default is 5 minutes; we match so a long-running maestro turn doesn't
+ *  pass through the expiry boundary mid-stream. */
+const DEFAULT_REFRESH_SKEW_SECONDS = 300;
+/** Path to `auth.json`. Honors `CODEX_HOME` env var for parity with
+ *  upstream codex CLI; falls back to `~/.codex/auth.json`. */
+export function codexAuthPath() {
+    const home = process.env.CODEX_HOME?.trim();
+    const root = home && home.length > 0 ? home : join(homedir(), ".codex");
+    return join(root, "auth.json");
+}
+/** Read the auth file. Throws a structured error if the file is missing or
+ *  malformed — callers can map this to a "run `codex login`" message. */
+export function readCodexAuth(path) {
+    const p = path ?? codexAuthPath();
+    if (!existsSync(p)) {
+        throw new CodexAuthError(`Codex auth file not found at ${p}. Run \`codex login\` first.`, "codex_auth_missing", true);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch (e) {
+        throw new CodexAuthError(`Codex auth file at ${p} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`, "codex_auth_invalid_json", true);
+    }
+    if (parsed.auth_mode !== "chatgpt") {
+        throw new CodexAuthError(`Codex auth_mode is "${parsed.auth_mode}", expected "chatgpt". Use a regular OpenAI provider for API-key auth.`, "codex_auth_wrong_mode", false);
+    }
+    if (!parsed.tokens?.access_token || !parsed.tokens?.refresh_token) {
+        throw new CodexAuthError(`Codex auth file at ${p} is missing access_token or refresh_token. Run \`codex login\` again.`, "codex_auth_missing_tokens", true);
+    }
+    return parsed;
+}
+/**
+ * Decode a JWT access token (no signature verification — we only need the
+ * `chatgpt_account_id` claim for an HTTP header). Returns `undefined` if the
+ * token isn't a parseable JWT; callers must tolerate that case and fall back
+ * to omitting the `ChatGPT-Account-ID` header (the request still succeeds for
+ * most account types — only Cloudflare-edge mitigation rules require it).
+ */
+export function decodeJwtClaims(accessToken) {
+    try {
+        const parts = accessToken.split(".");
+        if (parts.length < 2)
+            return undefined;
+        const payload = parts[1];
+        // base64url → base64 + padding
+        const b64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = b64.padEnd(b64.length + ((4 - (b64.length % 4)) % 4), "=");
+        const json = Buffer.from(padded, "base64").toString("utf8");
+        return JSON.parse(json);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Pull the `chatgpt_account_id` value out of a Codex JWT. The claim path
+ * (`https://api.openai.com/auth.chatgpt_account_id`) is what hermes pins
+ * against codex-rs `auth.rs`; we copy it verbatim.
+ */
+export function extractAccountId(accessToken) {
+    const claims = decodeJwtClaims(accessToken);
+    if (!claims)
+        return undefined;
+    const authClaim = claims["https://api.openai.com/auth"];
+    if (!authClaim || typeof authClaim !== "object")
+        return undefined;
+    const acct = authClaim.chatgpt_account_id;
+    return typeof acct === "string" && acct.length > 0 ? acct : undefined;
+}
+/**
+ * Return the access-token `exp` claim as an absolute epoch-seconds value, or
+ * `undefined` if not present / unparseable. Used by `accessTokenIsExpiring`.
+ */
+export function accessTokenExpiresAt(accessToken) {
+    const claims = decodeJwtClaims(accessToken);
+    if (!claims)
+        return undefined;
+    const exp = claims.exp;
+    return typeof exp === "number" && Number.isFinite(exp) ? exp : undefined;
+}
+/**
+ * `true` when the access token is within `skewSeconds` of its `exp` claim
+ * (or already expired). Tokens with no `exp` claim are conservatively treated
+ * as "always refresh" — better to round-trip the refresh endpoint than to
+ * leak a stale token into a long-running stream.
+ */
+export function accessTokenIsExpiring(accessToken, skewSeconds = DEFAULT_REFRESH_SKEW_SECONDS) {
+    const exp = accessTokenExpiresAt(accessToken);
+    if (exp === undefined)
+        return true;
+    const now = Math.floor(Date.now() / 1000);
+    return exp - now <= skewSeconds;
+}
+/**
+ * Required Cloudflare-bypass headers for `chatgpt.com/backend-api/codex`.
+ *
+ * The edge in front of the Codex endpoint allowlists requests whose
+ * `originator` is one of `codex_cli_rs`, `codex_vscode`, `codex_sdk_ts`, or
+ * anything starting with `Codex`. Non-residential IPs without an allowlisted
+ * originator get a 403 with `cf-mitigated: challenge` regardless of auth
+ * correctness — meaning the request never reaches the application layer and
+ * the bug looks like an auth problem when it isn't.
+ *
+ * We pin `originator: codex_cli_rs` (the upstream codex-rs CLI value) and
+ * shape the User-Agent to match codex-rs's fingerprint. The
+ * `ChatGPT-Account-ID` header is conditional — most accounts don't need it,
+ * but Enterprise / Team accounts will 403 without it.
+ */
+export function cloudflareHeaders(accessToken) {
+    const h = {
+        Authorization: `Bearer ${accessToken}`,
+        "User-Agent": "codex_cli_rs/0.0.0 (maestro-agent-sdk)",
+        originator: "codex_cli_rs",
+    };
+    const acct = extractAccountId(accessToken);
+    if (acct)
+        h["ChatGPT-Account-ID"] = acct;
+    return h;
+}
+/**
+ * Error type for all OAuth-related failures. `reloginRequired` indicates the
+ * user must run `codex login` again — the refresh-token chain is unrecoverable.
+ * Other failures (network, 5xx) are retryable in-process.
+ */
+export class CodexAuthError extends Error {
+    code;
+    reloginRequired;
+    constructor(message, code, reloginRequired) {
+        super(message);
+        this.code = code;
+        this.reloginRequired = reloginRequired;
+        this.name = "CodexAuthError";
+    }
+}
+/**
+ * Refresh the access token using the stored refresh token. Returns the new
+ * tokens (access + possibly rotated refresh) without touching the on-disk
+ * file. Callers that want to persist call `writeRefreshedTokens()` below.
+ *
+ * Behavior mirrors hermes's `refresh_codex_oauth_pure` — same client_id,
+ * same form-encoded body, same error-mapping rules. The notable difference is
+ * that we leave timeouts to the platform `fetch` (Node 22+ supports
+ * `signal: AbortSignal.timeout(ms)`); we don't pull in a `httpx` analog.
+ */
+export async function refreshAccessToken(refreshToken, timeoutMs = 20_000) {
+    if (!refreshToken || refreshToken.length === 0) {
+        throw new CodexAuthError("Cannot refresh — refresh_token is empty. Run `codex login` again.", "codex_auth_missing_refresh_token", true);
+    }
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: refreshToken,
+        client_id: CODEX_OAUTH_CLIENT_ID,
+    });
+    let response;
+    try {
+        response = await fetch(CODEX_OAUTH_TOKEN_URL, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (e) {
+        throw new CodexAuthError(`Codex token refresh network error: ${e instanceof Error ? e.message : String(e)}`, "codex_refresh_network", false);
+    }
+    if (!response.ok) {
+        // Parse the error body to decide whether the user needs to re-login.
+        // OpenAI returns two distinct shapes here — OAuth spec ({error,error_description})
+        // and OpenAI's own ({error:{code,message,type}}) — we accept either.
+        let code = "codex_refresh_failed";
+        let message = `Codex token refresh failed (HTTP ${response.status})`;
+        try {
+            const err = (await response.json());
+            const errObj = err.error;
+            if (typeof errObj === "string" && errObj.length > 0) {
+                code = errObj;
+                const desc = err.error_description ?? err.message;
+                if (typeof desc === "string" && desc.length > 0)
+                    message = `Codex token refresh: ${desc}`;
+            }
+            else if (errObj && typeof errObj === "object") {
+                const nested = errObj;
+                const nestedCode = nested.code ?? nested.type;
+                if (typeof nestedCode === "string" && nestedCode.length > 0)
+                    code = nestedCode;
+                const nestedMsg = nested.message;
+                if (typeof nestedMsg === "string" && nestedMsg.length > 0)
+                    message = `Codex token refresh: ${nestedMsg}`;
+            }
+        }
+        catch {
+            // Non-JSON body — keep the default message.
+        }
+        const reloginRequired = code === "invalid_grant" ||
+            code === "invalid_token" ||
+            code === "invalid_request" ||
+            code === "refresh_token_reused" ||
+            response.status === 401 ||
+            response.status === 403;
+        throw new CodexAuthError(message, code, reloginRequired);
+    }
+    let payload;
+    try {
+        payload = (await response.json());
+    }
+    catch (e) {
+        throw new CodexAuthError(`Codex token refresh returned non-JSON body: ${e instanceof Error ? e.message : String(e)}`, "codex_refresh_invalid_json", true);
+    }
+    const newAccess = payload.access_token;
+    if (typeof newAccess !== "string" || newAccess.length === 0) {
+        throw new CodexAuthError("Codex token refresh response was missing access_token.", "codex_refresh_missing_access_token", true);
+    }
+    // Rotate the refresh token only when the server returned a fresh one.
+    // OAuth servers vary — some always rotate, some only on certain conditions.
+    // Keeping the old one when the server omits it matches OAuth 2.0 spec §6.
+    const newRefresh = typeof payload.refresh_token === "string" && payload.refresh_token.length > 0
+        ? payload.refresh_token
+        : refreshToken;
+    return { access_token: newAccess, refresh_token: newRefresh };
+}
+/**
+ * Persist a freshly refreshed token pair back to `~/.codex/auth.json` while
+ * preserving the other fields (auth_mode, OPENAI_API_KEY, account_id,
+ * id_token). Updates `last_refresh` to "now". Best-effort — if the write
+ * fails the in-process token is still usable for the lifetime of the
+ * process; we just won't share it with codex CLI.
+ *
+ * Note: this is racy with codex CLI running in parallel. The upstream
+ * codex-rs implementation uses an advisory file lock; we don't bother
+ * because typical maestro usage doesn't overlap with `codex` invocations
+ * on the same machine. If lock contention becomes a real problem, lift
+ * the lockfile pattern from hermes's `_auth_store_lock`.
+ */
+export function writeRefreshedTokens(newTokens, path) {
+    const p = path ?? codexAuthPath();
+    const current = readCodexAuth(p);
+    const updated = {
+        ...current,
+        last_refresh: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+        tokens: {
+            ...current.tokens,
+            access_token: newTokens.access_token,
+            refresh_token: newTokens.refresh_token,
+        },
+    };
+    writeFileSync(p, `${JSON.stringify(updated, null, 2)}\n`, { mode: 0o600 });
+}
+/**
+ * The top-level helper a Provider uses on every turn. Reads the on-disk
+ * tokens; refreshes if expiring; writes the refreshed pair back to disk;
+ * returns the live access token. Idempotent under concurrent calls within
+ * one process — repeated calls in the same expiry window just hit the
+ * `isExpiring` short-circuit. Cross-process concurrency is best-effort
+ * (see `writeRefreshedTokens`).
+ *
+ * `forceRefresh` is exposed for tests and for hosts that want to recover
+ * from a 401 mid-stream by minting a fresh token and retrying once.
+ */
+export async function resolveAccessToken(opts) {
+    const skew = opts?.skewSeconds ?? DEFAULT_REFRESH_SKEW_SECONDS;
+    const auth = readCodexAuth();
+    if (!opts?.forceRefresh && !accessTokenIsExpiring(auth.tokens.access_token, skew)) {
+        return auth.tokens.access_token;
+    }
+    const refreshed = await refreshAccessToken(auth.tokens.refresh_token, opts?.timeoutMs);
+    try {
+        writeRefreshedTokens(refreshed);
+    }
+    catch (e) {
+        // Disk write failed but the in-memory token is still good — log via
+        // console.warn rather than crashing the agent.
+        console.warn(`[codex-auth] Could not persist refreshed tokens: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return refreshed.access_token;
+}
+//# sourceMappingURL=codex-auth.js.map

package/dist/providers/codex-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-auth.js","sourceRoot":"","sources":["../../src/providers/codex-auth.ts"],"names":[],"mappings":"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"}

package/dist/providers/codex-stream.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Codex Responses API SSE stream → Maestro `ProviderStreamChunk` adapter.
+ *
+ * The Responses API SSE protocol is event-typed (each event has a `type`
+ * field plus a `data` JSON payload). The events of interest:
+ *
+ *   - `response.output_item.added` — a new top-level output item began
+ *     (message | function_call | reasoning). Use to learn the item's
+ *     `id` / `name` / kind before deltas start arriving.
+ *   - `response.output_text.delta` — text chunk for the current message item.
+ *   - `response.function_call_arguments.delta` — JSON-args chunk for the
+ *     current function_call item.
+ *   - `response.function_call_arguments.done` — args finalized.
+ *   - `response.output_item.done` — the item is closed; carries the full
+ *     completed item (with final args, content, status).
+ *   - `response.reasoning_summary_text.delta` / `.done` — reasoning summary
+ *     stream (only when `reasoning.summary` was enabled).
+ *   - `response.completed` — terminal. Carries `response.usage` and the
+ *     full output array.
+ *   - `response.incomplete` / `response.failed` — terminal failures.
+ *
+ * The codex backend has a known bug where `get_final_response()` returns an
+ * empty `output` even after valid items streamed — hermes patches this with
+ * "synthesize from deltas" backfill. We do the same here: keep a parallel
+ * accumulator and use it as the source of truth for `message_complete`,
+ * ignoring the `response.completed.response.output` array.
+ *
+ * The output is the same `ProviderStreamChunk` vocabulary the agent loop
+ * already consumes for Anthropic / DeepSeek, so adding Codex requires no
+ * changes to `core/loop.ts`.
+ */
+import type { ProviderStreamChunk } from "../providers/base.js";
+/**
+ * Convert a Responses API SSE stream (the raw `Response.body` from `fetch`)
+ * into the maestro `ProviderStreamChunk` async iterable.
+ *
+ * Aborts when `abortSignal` fires by cancelling the underlying reader; the
+ * generator yields nothing further and any in-progress items become stale
+ * (the agent loop will reconcile on its end via the abort flag).
+ */
+export declare function parseCodexStream(body: ReadableStream<Uint8Array>, abortSignal?: AbortSignal): AsyncGenerator<ProviderStreamChunk>;
+//# sourceMappingURL=codex-stream.d.ts.map

package/dist/providers/codex-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-stream.d.ts","sourceRoot":"","sources":["../../src/providers/codex-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAwB,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AA2ClF;;;;;;;GAOG;AACH,wBAAuB,gBAAgB,CACrC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,WAAW,CAAC,EAAE,WAAW,GACxB,cAAc,CAAC,mBAAmB,CAAC,CA6MrC"}