maestro-agent-sdk 0.1.26 → 0.1.28

package/dist/providers/codex-translators.js

@@ -0,0 +1,244 @@
+/**
+ * Maestro ↔ Codex Responses API format translators.
+ *
+ * The Responses API is OpenAI's newer thread-style endpoint. It speaks a
+ * different shape than Chat Completions:
+ *
+ *   - Messages aren't a `messages` array — they're "input items" with
+ *     polymorphic types (`message`, `function_call`, `function_call_output`,
+ *     `reasoning`).
+ *   - Tools live as top-level items, not inside an assistant message.
+ *   - Text parts split by direction: user → `input_text`, assistant →
+ *     `output_text`. Mixing them yields 400.
+ *   - There is no `system` role; the instructions ride in a top-level
+ *     `instructions` field on the request body.
+ *
+ * This module owns those translations and nothing else — the provider class
+ * stays focused on HTTP / streaming concerns.
+ *
+ * Hermes reference: `agent/codex_responses_adapter.py::_chat_messages_to_responses_input`
+ * and `_responses_tools`. We diverge from hermes in two places:
+ *
+ *   1. We start from Maestro's Anthropic-shaped `ProviderContentBlock[]`, not
+ *      from OpenAI Chat Completions messages. Hermes does this conversion in
+ *      two hops (Anthropic → ChatCompletions → Responses); we do it in one to
+ *      keep the data path shorter and the type signatures honest.
+ *
+ *   2. We don't replay `codex_reasoning_items` / `codex_message_items` from
+ *      prior turns yet. Reasoning replay (with `encrypted_content`) is what
+ *      lets the Responses API maintain a coherent reasoning chain across
+ *      turns — but maestro's loop currently drops the encrypted blobs after
+ *      each turn, so there's nothing to replay. A future PR can extend
+ *      `ProviderContentBlock` with a `codex_encrypted_reasoning` variant and
+ *      wire the replay here.
+ */
+export function translateToolsToResponses(tools) {
+    if (!tools || tools.length === 0)
+        return undefined;
+    const out = [];
+    for (const t of tools) {
+        if (!t?.name || t.name.length === 0)
+            continue;
+        out.push({
+            type: "function",
+            name: t.name,
+            description: t.description ?? "",
+            strict: false,
+            parameters: t.input_schema ?? {
+                type: "object",
+                properties: {},
+            },
+        });
+    }
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Convert one Maestro message into one-or-more Responses input items.
+ *
+ * Why one message can produce multiple items:
+ *   - An assistant message with `text` + `tool_use` emits a `message` item AND
+ *     one `function_call` per tool_use, in that exact order.
+ *   - A user message with `tool_result` blocks emits a separate
+ *     `function_call_output` per result. Text/image blocks accompanying the
+ *     tool_results are flushed as their own `message` item before each result
+ *     so call-result ordering with surrounding text is preserved (matches
+ *     DeepSeek/Anthropic intent).
+ */
+export function translateMessageToResponsesItems(msg) {
+    // String-content fast path covers DeepSeek-style plain text replays.
+    if (typeof msg.content === "string") {
+        return [
+            {
+                type: "message",
+                role: msg.role,
+                content: msg.content,
+            },
+        ];
+    }
+    if (msg.role === "user") {
+        return translateUserBlocks(msg.content);
+    }
+    return translateAssistantBlocks(msg.content);
+}
+function translateUserBlocks(blocks) {
+    const out = [];
+    let buffered = [];
+    const flush = () => {
+        if (buffered.length === 0)
+            return;
+        out.push({
+            type: "message",
+            role: "user",
+            content: condenseUserParts(buffered),
+        });
+        buffered = [];
+    };
+    for (const block of blocks) {
+        if (block.type === "text") {
+            if (block.text.length > 0)
+                buffered.push({ type: "input_text", text: block.text });
+        }
+        else if (block.type === "image") {
+            const url = imageBlockToDataUrl(block.source);
+            if (url)
+                buffered.push({ type: "input_image", image_url: url });
+        }
+        else if (block.type === "document") {
+            // Responses API doesn't accept PDF blocks directly at user message
+            // level — placeholder so the model knows the attachment existed.
+            // Caller should pre-extract text (e.g. via Read tool) for real content.
+            buffered.push({
+                type: "input_text",
+                text: `[document ${block.source.media_type}; PDF not visible to GPT-5 directly — extract text first.]`,
+            });
+        }
+        else if (block.type === "tool_result") {
+            // tool_result MUST be its own item; flush any accumulated user content
+            // first so ordering with surrounding text/image is preserved.
+            flush();
+            out.push({
+                type: "function_call_output",
+                call_id: block.tool_use_id,
+                output: toolResultToResponsesOutput(block.content),
+            });
+        }
+        // Other block types (tool_use, thinking) don't legally appear on user
+        // messages — silently skip if encountered.
+    }
+    flush();
+    return out;
+}
+function translateAssistantBlocks(blocks) {
+    const out = [];
+    const textParts = [];
+    // Collect text first so the assistant message lands once, before any
+    // function_calls. The Responses API doesn't require this order strictly
+    // (it tolerates [function_call, message] too) but the matching chat-side
+    // semantics are "the assistant said X, then called tool Y" — we keep that
+    // narrative order in the replay.
+    for (const block of blocks) {
+        if (block.type === "text" && block.text.length > 0) {
+            textParts.push({ type: "output_text", text: block.text });
+        }
+        // We could surface `thinking` blocks here as `reasoning` items, but doing
+        // so without the `encrypted_content` blob the model originally produced
+        // would just be plain-text reasoning the API treats as ordinary assistant
+        // output — that hurts more than it helps (reveals chain-of-thought to
+        // anything that later reads the rollout). Drop until we plumb encrypted
+        // replay end-to-end.
+    }
+    if (textParts.length > 0) {
+        out.push({ type: "message", role: "assistant", content: textParts });
+    }
+    for (const block of blocks) {
+        if (block.type === "tool_use") {
+            out.push({
+                type: "function_call",
+                call_id: block.id,
+                name: block.name,
+                arguments: JSON.stringify(block.input ?? {}),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * If a user message ends up as a single text part, collapse to a plain string
+ * — keeps the wire shape predictable and avoids tripping any validator that
+ * expects a string when no image is attached. Mixed / image-bearing messages
+ * keep the array form. Mirrors DeepSeek's `condenseUserParts`.
+ */
+function condenseUserParts(parts) {
+    if (parts.length === 1 && parts[0].type === "input_text")
+        return parts[0].text;
+    return parts;
+}
+/**
+ * Build a `data:<mime>;base64,<data>` URL from a Maestro image source. The
+ * Responses API accepts either a hosted URL or a data URL — we always emit
+ * the latter so the host doesn't need to publish a temporary URL.
+ *
+ * Returns `undefined` for malformed sources rather than throwing — the
+ * containing message still flows, just without the image part.
+ */
+function imageBlockToDataUrl(source) {
+    if (source.type === "url" && source.url)
+        return source.url;
+    if (source.type === "base64" && source.data) {
+        const mime = source.media_type ?? "image/png";
+        return `data:${mime};base64,${source.data}`;
+    }
+    return undefined;
+}
+/**
+ * Convert a `tool_result.content` value into the shape the Responses API
+ * accepts inside `function_call_output.output`.
+ *
+ * - String → string (fast path; the majority of tools return plain text).
+ * - Block array of only text → joined string (smaller wire payload).
+ * - Mixed array (text + image) → structured array; image blocks become
+ *   `input_image` parts. Document blocks become a text placeholder for the
+ *   same reason as user-message documents.
+ */
+function toolResultToResponsesOutput(content) {
+    if (typeof content === "string")
+        return content;
+    const parts = [];
+    for (const b of content) {
+        if (b.type === "text") {
+            parts.push({ type: "input_text", text: b.text });
+        }
+        else if (b.type === "image") {
+            const url = imageBlockToDataUrl(b.source);
+            if (url)
+                parts.push({ type: "input_image", image_url: url });
+        }
+        else if (b.type === "document") {
+            const bytes = b.source.data ? Math.floor((b.source.data.length * 3) / 4) : 0;
+            parts.push({
+                type: "input_text",
+                text: `[document ${b.source.media_type} ${bytes} bytes — extract text first.]`,
+            });
+        }
+    }
+    // All-text → collapse to a single string for compactness.
+    if (parts.every((p) => p.type === "input_text")) {
+        return parts.map((p) => p.text).join("\n");
+    }
+    return parts;
+}
+/**
+ * Top-level: translate the full Maestro message history into a flat array of
+ * Responses input items. The `system` string is consumed by the provider into
+ * the request's `instructions` field — it does NOT appear here.
+ */
+export function translateMessagesToResponses(messages) {
+    const out = [];
+    for (const msg of messages) {
+        for (const item of translateMessageToResponsesItems(msg)) {
+            out.push(item);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=codex-translators.js.map

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

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

package/dist/providers/codex.d.ts

@@ -0,0 +1,145 @@
+/**
+ * CodexResponsesProvider — call OpenAI's Responses API through the ChatGPT
+ * Codex backend using a `codex login` OAuth token.
+ *
+ * High-level shape:
+ *
+ *   ┌────────────────────────┐    ┌──────────────────────────────────────┐
+ *   │  AIAgent loop          │    │  CodexResponsesProvider              │
+ *   │  ProviderMessage[]    ─┼───▶│  - resolveAccessToken (refresh-aware)│
+ *   │                        │    │  - translateMessagesToResponses      │
+ *   │                        │    │  - translateToolsToResponses         │
+ *   │                        │    │  - POST /responses (stream:true)     │
+ *   │  ProviderStreamChunk  ◀┼────│  - parseCodexStream                  │
+ *   └────────────────────────┘    └──────────────────────────────────────┘
+ *
+ * Pinned constraints (verified empirically against
+ * `https://chatgpt.com/backend-api/codex/responses` on 2026-05-23):
+ *
+ *   - **Stream is required**: non-streaming requests return
+ *     `400 {"detail":"Stream must be set to true"}`.
+ *   - **Model whitelist**: ChatGPT-account requests are limited to a small
+ *     set of codex-issued model slugs (`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`,
+ *     `gpt-5.3-codex`, `gpt-5.2`, ...). Passing `gpt-5` returns 400 with
+ *     `not supported when using Codex with a ChatGPT account`.
+ *   - **Cloudflare headers required**: `originator: codex_cli_rs` plus a
+ *     codex-shaped `User-Agent` are mandatory on non-residential IPs.
+ *   - **`store: false`**: required when the rollout lives on the client side.
+ *     Without it, the server expects subsequent requests to look items up
+ *     by `id` and 404s when they can't.
+ *
+ * What this provider does NOT cover (deliberate scope cuts):
+ *
+ *   - Reasoning chain replay across turns (would need `encrypted_content`
+ *     plumbed into the message history). Reasoning summaries flow through
+ *     as `thinking` blocks for the current turn only.
+ *   - Built-in hosted tools (`web_search`, `file_search`). Only
+ *     user-supplied function tools are wired.
+ *   - Token-bucket rate-limit handling. The backend rate-limits aggressively
+ *     for free accounts; surfacing a structured retry hint can be a follow-up.
+ *
+ * Hermes reference: `agent/transports/codex.py` + `_run_codex_stream`. We
+ * implement the same wire contract using only `fetch` and the SSE parser in
+ * `codex-stream.ts`, with no httpx / OpenAI SDK dependency.
+ */
+import { type CodexAuthError } from "../providers/codex-auth.js";
+import type { Provider, ProviderCompleteOptions, ProviderResponse, ProviderStreamChunk } from "../providers/base.js";
+import type { EffortLevel } from "../types.js";
+/**
+ * Map maestro's `EffortLevel` to the Responses API `reasoning.effort` string.
+ *
+ * Codex backend accepts `low | medium | high | xhigh`. The 5-tier maestro
+ * scale collapses as follows:
+ *   - `low` / `medium` / `high` → direct passthrough.
+ *   - `xhigh` → passthrough (Codex actually supports this tier on gpt-5.x).
+ *   - `max`  → `xhigh`. Codex has no `max`; we pick the deepest tier the
+ *     backend exposes rather than silently dropping the user's intent.
+ */
+export declare function effortForCodex(e: EffortLevel | undefined): string | undefined;
+export interface CodexProviderOptions {
+    /** Override the Codex backend URL. Defaults to the ChatGPT-hosted
+     *  endpoint. The `/responses` suffix is appended automatically. */
+    baseUrl?: string;
+    /** Override the timeout for the OAuth refresh round-trip. The streaming
+     *  request itself uses `fetchTimeoutMs` (see below) — the agent loop also
+     *  owns abort via signal. */
+    refreshTimeoutMs?: number;
+    /**
+     * Skew window (seconds) for the refresh decision. When the cached access
+     * token is within this many seconds of `exp`, the next provider call
+     * refreshes before making the API request. Defaults to 5 minutes — large
+     * enough to cover one long streaming turn without rolling over mid-stream.
+     */
+    refreshSkewSeconds?: number;
+    /**
+     * Wall-clock ceiling on a single `/responses` POST before we abort and
+     * surface a TimeoutError. Default 600_000 ms (10 minutes) — Bun's bundled
+     * undici otherwise enforces a 5-minute `headersTimeout` that fires on
+     * gpt-5.5 with ~1MB+ request bodies (v0.1.28 production repro). Raising
+     * the wall to 10 min gives the model breathing room while keeping a
+     * bounded worst case if the server hangs entirely. Combined with the
+     * caller's `abortSignal` via `AbortSignal.any`, so a user-initiated abort
+     * still wins immediately.
+     */
+    fetchTimeoutMs?: number;
+}
+/**
+ * Provider implementation. Construct once per process; safe to share across
+ * concurrent agent turns (token refresh is best-effort idempotent under the
+ * skew check + on-disk persistence).
+ */
+export declare class CodexResponsesProvider implements Provider {
+    private readonly baseUrl;
+    private readonly refreshTimeoutMs;
+    private readonly refreshSkewSeconds;
+    private readonly fetchTimeoutMs;
+    constructor(opts?: CodexProviderOptions);
+    /**
+     * Build the AbortSignal we pass to `fetch`. Combines an explicit
+     * wall-clock timeout (`this.fetchTimeoutMs`) with the caller's optional
+     * abort signal so either path can short-circuit the request:
+     *   - User abort fires → request cancels immediately.
+     *   - Timeout fires → DOMException(name="TimeoutError") surfaces, which
+     *     the v0.1.28 `isTimeoutError` helper catches in `provider.ts`.
+     *
+     * Why explicit timeout: Bun's undici default `headersTimeout` is 300_000
+     * ms (5 min) and fires regardless of user signal. Long requests on the
+     * heavy gpt-5.* tiers with large bodies blew through that wall in
+     * production. We raise the ceiling to 10 minutes (configurable) and pin
+     * the same value across the initial POST and the 401-refresh retry below.
+     */
+    private buildFetchSignal;
+    /**
+     * Factory parity with `DeepseekProvider.fromEnv()` — for Codex the "env"
+     * inputs are really the on-disk `~/.codex/auth.json` (no API key env var
+     * makes sense for OAuth). The factory still throws early if the auth file
+     * is missing or stale, so a host can fail fast at startup instead of on
+     * the first user message.
+     */
+    static fromEnv(opts?: CodexProviderOptions): CodexResponsesProvider;
+    /**
+     * Streaming entry point. The Codex backend rejects non-streaming requests
+     * outright, so this is the load-bearing method — `complete()` is just a
+     * convenience wrapper around it.
+     */
+    stream(opts: ProviderCompleteOptions): AsyncGenerator<ProviderStreamChunk>;
+    /**
+     * Non-streaming entry point. The Codex backend doesn't support
+     * `stream: false`, so we drain `stream()` into a single `ProviderResponse`.
+     * Callers that want progressive UI updates should use `stream()` directly.
+     *
+     * The reconstruction follows DeepseekProvider's convention:
+     *   - text deltas collapse into one `text` content block per stream;
+     *   - tool_use_start + tool_use_input_delta + tool_use_complete bundle
+     *     into one `tool_use` block with parsed JSON args;
+     *   - thinking_complete blocks are forwarded verbatim.
+     *
+     * Block order in the returned `content`: thinking → text → tool_use,
+     * matching the assistant-history convention the loop expects on replay.
+     */
+    complete(opts: ProviderCompleteOptions): Promise<ProviderResponse>;
+}
+export { CodexAuthError } from "../providers/codex-auth.js";
+export type { CodexProviderOptions as _CodexProviderOptions };
+export type _CodexAuthError = CodexAuthError;
+//# sourceMappingURL=codex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/providers/codex.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,QAAQ,EACR,uBAAuB,EAEvB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAO1B,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,SAAS,CAAC;AAOvD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAe7E;AAED,MAAM,WAAW,oBAAoB;IACnC;uEACmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;iCAE6B;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,QAAQ;IACrD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,IAAI,GAAE,oBAAyB;IAO3C;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;;;;;OAMG;IACH,MAAM,CAAC,OAAO,CAAC,IAAI,GAAE,oBAAyB,GAAG,sBAAsB;IAIvE;;;;OAIG;IACI,MAAM,CAAC,IAAI,EAAE,uBAAuB,GAAG,cAAc,CAAC,mBAAmB,CAAC;IA4IjF;;;;;;;;;;;;;OAaG;IACG,QAAQ,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAsDzE;AAgGD,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,YAAY,EAAE,oBAAoB,IAAI,qBAAqB,EAAE,CAAC;AAE9D,MAAM,MAAM,eAAe,GAAG,cAAc,CAAC"}