maestro-agent-sdk 0.1.26 → 0.1.27

package/dist/providers/codex-stream.js

@@ -0,0 +1,330 @@
+/**
+ * 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`.
+ */
+// ── Public entry point ──────────────────────────────────────────────────────
+/**
+ * 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 async function* parseCodexStream(body, abortSignal) {
+    // Per-item accumulators keyed by output_index. We can't key by
+    // `item_id` because text deltas reference `item_id` while
+    // function_call arg deltas reference `output_index` only in older
+    // backend builds — output_index is the one field both shapes ship
+    // reliably.
+    const itemsByIndex = new Map();
+    let stopReason = "end_turn";
+    let usage = { inputTokens: 0, outputTokens: 0 };
+    // Reasoning summary lives outside the item map because it can arrive
+    // interleaved across multiple reasoning items in one turn; the loop
+    // only wants one consolidated `thinking_complete` block at the end.
+    let reasoningSummaryBuf = "";
+    let sawReasoning = false;
+    for await (const evt of parseSseFrames(body, abortSignal)) {
+        const t = evt.type ?? "";
+        // ── 1. New item begins ────────────────────────────────────────────────
+        if (t === "response.output_item.added" && typeof evt.output_index === "number" && evt.item) {
+            const kind = evt.item.type === "message"
+                ? "message"
+                : evt.item.type === "function_call"
+                    ? "function_call"
+                    : evt.item.type === "reasoning"
+                        ? "reasoning"
+                        : "unknown";
+            itemsByIndex.set(evt.output_index, {
+                kind,
+                id: evt.item.id ?? "",
+                callId: evt.item.call_id ?? "",
+                name: evt.item.name ?? "",
+                argsBuf: "",
+                textBuf: "",
+                reasoningBuf: "",
+                toolStartEmitted: false,
+                toolCompleteEmitted: false,
+            });
+            // For tool calls we can emit `tool_use_start` immediately — `call_id`
+            // and `name` arrive in the same event. Arg deltas follow.
+            if (kind === "function_call") {
+                const entry = itemsByIndex.get(evt.output_index);
+                const id = entry.callId || entry.id;
+                if (id && entry.name && !entry.toolStartEmitted) {
+                    entry.toolStartEmitted = true;
+                    yield { type: "tool_use_start", id, name: entry.name };
+                }
+            }
+            continue;
+        }
+        // ── 2. Text deltas ────────────────────────────────────────────────────
+        if (t === "response.output_text.delta" && typeof evt.delta === "string" && evt.delta.length > 0) {
+            // text_delta is fire-and-forget — the loop accumulates per-message
+            // text on its own side. We also accumulate locally so the final
+            // `message_complete` event's optional backfill has a source.
+            const entry = typeof evt.output_index === "number" ? itemsByIndex.get(evt.output_index) : undefined;
+            if (entry)
+                entry.textBuf += evt.delta;
+            yield { type: "text_delta", text: evt.delta };
+            continue;
+        }
+        // ── 3. Function-call argument deltas ─────────────────────────────────
+        if (t === "response.function_call_arguments.delta" &&
+            typeof evt.output_index === "number") {
+            const entry = itemsByIndex.get(evt.output_index);
+            if (!entry || entry.kind !== "function_call")
+                continue;
+            const chunk = evt.delta ?? evt.arguments ?? "";
+            if (chunk.length === 0)
+                continue;
+            entry.argsBuf += chunk;
+            const id = entry.callId || entry.id;
+            if (id) {
+                yield { type: "tool_use_input_delta", id, partial_json: chunk };
+            }
+            continue;
+        }
+        if (t === "response.function_call_arguments.done" &&
+            typeof evt.output_index === "number") {
+            const entry = itemsByIndex.get(evt.output_index);
+            if (!entry || entry.kind !== "function_call")
+                continue;
+            // The .done event sometimes carries the FULL arguments string. If our
+            // accumulator is empty (no deltas arrived — codex's chatgpt backend
+            // occasionally streams the args only at completion), backfill from
+            // the .done payload.
+            if (entry.argsBuf.length === 0 && typeof evt.arguments === "string") {
+                entry.argsBuf = evt.arguments;
+                const id = entry.callId || entry.id;
+                if (id) {
+                    yield { type: "tool_use_input_delta", id, partial_json: evt.arguments };
+                }
+            }
+            continue;
+        }
+        // ── 4. Reasoning summary deltas ──────────────────────────────────────
+        // Only fired when `reasoning.summary` was requested. The raw reasoning
+        // content (encrypted) arrives on the closing `output_item.done` for the
+        // reasoning item — we keep that in the entry for a potential future
+        // encrypted-replay path.
+        if (typeof t === "string" &&
+            t.startsWith("response.reasoning_summary_text") &&
+            typeof evt.delta === "string") {
+            sawReasoning = true;
+            reasoningSummaryBuf += evt.delta;
+            continue;
+        }
+        if (typeof t === "string" &&
+            t.startsWith("response.reasoning_text") &&
+            typeof evt.delta === "string") {
+            sawReasoning = true;
+            reasoningSummaryBuf += evt.delta;
+            continue;
+        }
+        // ── 5. Item closed ────────────────────────────────────────────────────
+        if (t === "response.output_item.done" && typeof evt.output_index === "number") {
+            const entry = itemsByIndex.get(evt.output_index);
+            if (!entry)
+                continue;
+            if (entry.kind === "function_call" && !entry.toolCompleteEmitted) {
+                entry.toolCompleteEmitted = true;
+                const id = entry.callId || entry.id;
+                if (id && entry.name) {
+                    // Backfill args from the closed item payload if our accumulator
+                    // is empty (some codex builds skip the delta phase entirely).
+                    if (entry.argsBuf.length === 0 && typeof evt.item?.arguments === "string") {
+                        entry.argsBuf = evt.item.arguments;
+                        yield {
+                            type: "tool_use_input_delta",
+                            id,
+                            partial_json: entry.argsBuf,
+                        };
+                    }
+                    yield { type: "tool_use_complete", id, name: entry.name };
+                }
+            }
+            continue;
+        }
+        // ── 6. Terminal events ────────────────────────────────────────────────
+        if (t === "response.completed") {
+            if (evt.response?.usage)
+                usage = mapUsage(evt.response.usage);
+            // codex's chatgpt backend sometimes returns status "incomplete" here
+            // (e.g. context cap hit). Treat the granular reason as the stop_reason
+            // so the loop sees a familiar value.
+            const status = evt.response?.status;
+            if (status === "incomplete") {
+                stopReason = mapIncompleteReason(evt.response?.incomplete_details?.reason);
+            }
+            break;
+        }
+        if (t === "response.incomplete") {
+            stopReason = mapIncompleteReason(evt.response?.incomplete_details?.reason);
+            if (evt.response?.usage)
+                usage = mapUsage(evt.response.usage);
+            break;
+        }
+        if (t === "response.failed") {
+            stopReason = "error";
+            if (evt.response?.usage)
+                usage = mapUsage(evt.response.usage);
+            break;
+        }
+        // Other event types (response.created, response.in_progress,
+        // response.content_part.added/done, etc.) carry no information the
+        // loop needs — drop silently.
+    }
+    // ── 7. Flush reasoning summary as a single thinking block ─────────────
+    // Convention matches DeepseekProvider: emit thinking BEFORE
+    // message_complete so the loop appends it to assistantBlocks alongside
+    // text + tool_use.
+    if (sawReasoning && reasoningSummaryBuf.length > 0) {
+        const block = {
+            type: "thinking",
+            thinking: reasoningSummaryBuf,
+        };
+        yield { type: "thinking_complete", block };
+    }
+    yield { type: "message_complete", stopReason, usage };
+}
+// ── Usage / stopReason helpers ──────────────────────────────────────────────
+function mapUsage(u) {
+    const out = {
+        inputTokens: u.input_tokens ?? 0,
+        outputTokens: u.output_tokens ?? 0,
+    };
+    const cached = u.input_tokens_details?.cached_tokens;
+    if (typeof cached === "number")
+        out.cacheReadInputTokens = cached;
+    return out;
+}
+/**
+ * Map a codex `response.incomplete_details.reason` value to the loose
+ * stop_reason string the agent loop / conversation log carries. The loop
+ * itself doesn't branch on the value — it just propagates it into the
+ * `result` event — but the host display layer asserts on familiar names
+ * (`max_tokens`, `end_turn`, `tool_use`), so we normalize here.
+ */
+function mapIncompleteReason(reason) {
+    switch (reason) {
+        case "max_output_tokens":
+        case "max_tokens":
+            return "max_tokens";
+        case "content_filter":
+            return "stop";
+        default:
+            return reason ?? "end_turn";
+    }
+}
+// ── SSE framing ─────────────────────────────────────────────────────────────
+/**
+ * Parse the raw HTTP body as an SSE stream and yield one event payload per
+ * `\n\n`-delimited frame. Honours `event: <type>` lines so the caller can
+ * dispatch on event type even though all data lines are JSON.
+ *
+ * Unlike OpenAI Chat Completions' SSE (which uses `data: [DONE]` to signal
+ * end-of-stream), the Responses API terminates with a `response.completed`
+ * (or `.failed`/`.incomplete`) event and then closes the connection — there
+ * is no `[DONE]` sentinel. We tolerate one if it shows up anyway.
+ */
+async function* parseSseFrames(body, abortSignal) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    let buf = "";
+    const onAbort = () => {
+        reader.cancel("aborted").catch(() => { });
+    };
+    abortSignal?.addEventListener("abort", onAbort, { once: true });
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            let idx = buf.indexOf("\n\n");
+            while (idx >= 0) {
+                const frame = buf.slice(0, idx);
+                buf = buf.slice(idx + 2);
+                const parsed = parseOneFrame(frame);
+                if (parsed)
+                    yield parsed;
+                idx = buf.indexOf("\n\n");
+            }
+        }
+        // Tail flush — some servers don't terminate the final frame with `\n\n`.
+        if (buf.trim().length > 0) {
+            const parsed = parseOneFrame(buf);
+            if (parsed)
+                yield parsed;
+        }
+    }
+    finally {
+        abortSignal?.removeEventListener("abort", onAbort);
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // Reader may already be cancelled / released — ignore.
+        }
+    }
+}
+function parseOneFrame(frame) {
+    let eventType = "";
+    const dataLines = [];
+    for (const rawLine of frame.split("\n")) {
+        const line = rawLine.trimEnd();
+        if (line.startsWith("event:")) {
+            eventType = line.slice("event:".length).trim();
+        }
+        else if (line.startsWith("data:")) {
+            dataLines.push(line.slice("data:".length).trim());
+        }
+        // Comment lines (`: keep-alive`) and id: lines are ignored.
+    }
+    if (dataLines.length === 0)
+        return undefined;
+    const dataStr = dataLines.join("");
+    if (dataStr === "[DONE]")
+        return undefined;
+    try {
+        const parsed = JSON.parse(dataStr);
+        // Prefer the event:-line type when the JSON payload omits it (some
+        // intermediate proxies strip the `type` field).
+        if (!parsed.type && eventType)
+            parsed.type = eventType;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=codex-stream.js.map

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

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

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

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+import type { ProviderMessage, ProviderToolSchema } from "../providers/base.js";
+/**
+ * Function-tool entry as the Responses API expects it at top level.
+ *
+ * Differences from Chat Completions function format:
+ *   - No `function` wrapper — `name` / `description` / `parameters` are flat.
+ *   - `strict: false` is the safe default. `strict: true` would constrain the
+ *     model's tool arguments to a JSON-Schema subset (no `additionalProperties`,
+ *     no enums on objects, etc.). Maestro tool schemas vary in shape and
+ *     several would 400 under strict mode, so we punt that decision.
+ */
+export interface ResponsesFunctionTool {
+    type: "function";
+    name: string;
+    description: string;
+    strict: boolean;
+    parameters: Record<string, unknown>;
+}
+export declare function translateToolsToResponses(tools: readonly ProviderToolSchema[] | undefined): ResponsesFunctionTool[] | undefined;
+/**
+ * Union of every input-item shape we currently produce. The Responses API
+ * supports more (built-in tools, web_search hosted tools, file_search), but
+ * Maestro only emits these four — adding more is a one-discriminant extension.
+ */
+export type ResponsesInputItem = {
+    type?: "message";
+    role: "user" | "assistant";
+    /** String content (legacy fast path) OR a parts array (multimodal). */
+    content: string | ResponsesContentPart[];
+} | {
+    type: "function_call";
+    call_id: string;
+    name: string;
+    arguments: string;
+} | {
+    type: "function_call_output";
+    call_id: string;
+    /** String for text-only tool results; array for multimodal results. */
+    output: string | ResponsesContentPart[];
+};
+export type ResponsesContentPart = {
+    type: "input_text";
+    text: string;
+} | {
+    type: "output_text";
+    text: string;
+} | {
+    type: "input_image";
+    image_url: string;
+    detail?: string;
+};
+/**
+ * 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 declare function translateMessageToResponsesItems(msg: ProviderMessage): ResponsesInputItem[];
+/**
+ * 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 declare function translateMessagesToResponses(messages: readonly ProviderMessage[]): ResponsesInputItem[];
+//# sourceMappingURL=codex-translators.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codex-translators.d.ts","sourceRoot":"","sources":["../../src/providers/codex-translators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAGV,eAAe,EACf,kBAAkB,EACnB,MAAM,kBAAkB,CAAC;AAI1B;;;;;;;;;GASG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,UAAU,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,kBAAkB,EAAE,GAAG,SAAS,GAC/C,qBAAqB,EAAE,GAAG,SAAS,CAiBrC;AAID;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IACE,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,uEAAuE;IACvE,OAAO,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAAC;CAC1C,GACD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC3E;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,MAAM,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAAC;CACzC,CAAC;AAEN,MAAM,MAAM,oBAAoB,GAC5B;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,eAAe,GACnB,kBAAkB,EAAE,CAgBtB;AA2JD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,SAAS,eAAe,EAAE,GACnC,kBAAkB,EAAE,CAQtB"}