@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/engine/output/stream-json.mjs

@@ -0,0 +1,266 @@
+/**
+ * lib/engine/output/stream-json.mjs — `--output-format stream-json`.
+ *
+ * One JSON object per line (NDJSON) on stdout, following the publicly
+ * documented stream-json event contract:
+ *
+ *   {type:'system', subtype:'init', session_id, model, tools, mcp_servers, permission_mode, cwd, agents}
+ *   {type:'system', subtype:'cohort_quota', quota, session_id, parent_tool_use_id}   when a response carries quota
+ *   {type:'stream_event', event, session_id, parent_tool_use_id}                     --include-partial-messages
+ *   {type:'assistant', message:{role, content, model?}, session_id, parent_tool_use_id}
+ *   {type:'user', message:{role:'user', content:[tool_result…]}, session_id, parent_tool_use_id}
+ *   {type:'system', subtype:'cohort_todos', todos, session_id}                       when TodoWrite changes the list
+ *   {type:'system', subtype:'cohort_late_permission_denials', turn, permission_denials, session_id}
+ *                                                                                   a subagent's refusals arriving after its turn's result
+ *   {type:'result', …the --output-format json result…}                               once per turn (a no_input error result when
+ *                                                                                   stream-json input ends before any user message)
+ *
+ * `parent_tool_use_id` is null for the main run and the Task call's id for a
+ * subagent's events. User turns that carry no tool result (the prompt, a hook's
+ * continuation, a background-task notification) are not echoed.
+ *
+ * Partial messages are Anthropic-style stream events on both wires: the
+ * Anthropic wire's events pass through; OpenAI chunks are translated
+ * (`createPartialTranslator`) into message_start, content_block_start/delta/stop,
+ * message_delta and message_stop.
+ *
+ * Event builders and the translator are pure; `createStreamJsonWriter` is the edge.
+ *
+ * @module lib/engine/output/stream-json
+ */
+
+/** Strip engine-internal block fields (inputError, rawInput). @param {any} b */
+function publicBlock(b) {
+  if (!b || typeof b !== "object") return b;
+  if (b.type === "tool_use") return { type: "tool_use", id: b.id, name: b.name, input: b.input ?? {} };
+  if (b.type === "tool_result") return b.is_error ? { type: "tool_result", tool_use_id: b.tool_use_id, content: b.content, is_error: true } : { type: "tool_result", tool_use_id: b.tool_use_id, content: b.content };
+  return b;
+}
+
+/**
+ * @param {{sessionId:string, model:string, tools:string[], mcpServers:Array<{name:string, status:string}>, permissionMode:string, cwd:string, agents?:string[], wire?:string}} p
+ */
+export function initEvent({ sessionId, model, tools, mcpServers, permissionMode, cwd, agents = [], wire }) {
+  return {
+    type: "system",
+    subtype: "init",
+    session_id: sessionId,
+    cwd,
+    model,
+    tools,
+    mcp_servers: mcpServers.map((s) => ({ name: s.name, status: s.status })),
+    permission_mode: permissionMode,
+    agents,
+    ...(wire ? { cohort: { wire } } : {}),
+  };
+}
+
+/**
+ * The event for a message the run appended, or null when it is not echoed.
+ * @param {{role:string, content:any[]}} message
+ * @param {{sessionId:string, parentToolUseId?:string|null, model?:string|null}} o
+ */
+export function messageEvent(message, { sessionId, parentToolUseId = null, model = null }) {
+  const content = Array.isArray(message?.content) ? message.content : [];
+  if (message.role === "assistant") {
+    return { type: "assistant", message: { role: "assistant", content: content.map(publicBlock), ...(model ? { model } : {}) }, session_id: sessionId, parent_tool_use_id: parentToolUseId };
+  }
+  const results = content.filter((b) => b?.type === "tool_result");
+  if (results.length === 0) return null;
+  return { type: "user", message: { role: "user", content: results.map(publicBlock) }, session_id: sessionId, parent_tool_use_id: parentToolUseId };
+}
+
+/** @param {any} quota @param {{sessionId:string, parentToolUseId?:string|null}} o */
+export function quotaEvent(quota, { sessionId, parentToolUseId = null }) {
+  return { type: "system", subtype: "cohort_quota", quota, session_id: sessionId, parent_tool_use_id: parentToolUseId };
+}
+
+/** @param {any[]} todos @param {string} sessionId */
+export function todosEvent(todos, sessionId) {
+  return { type: "system", subtype: "cohort_todos", todos, session_id: sessionId };
+}
+
+/** Does a response's cohort block carry any quota? @param {any} q */
+export function quotaPresent(q) {
+  return Boolean(q && (Object.keys(q.windows || {}).length > 0 || q.creditsRemainingMicros != null || q.funding != null));
+}
+
+const OPENAI_STOP = { stop: "end_turn", tool_calls: "tool_use", function_call: "tool_use", length: "max_tokens", content_filter: "refusal" };
+
+/**
+ * SSE frames → Anthropic-style stream events. A fresh translator per model call.
+ * @param {'openai'|'anthropic'} wire
+ * @returns {(frame:{event?:string, data:string}) => any[]}
+ */
+export function createPartialTranslator(wire) {
+  if (wire === "anthropic") {
+    return (frame) => {
+      try {
+        const ev = JSON.parse(frame.data);
+        return ev && typeof ev.type === "string" && ev.type !== "ping" && ev.type !== "error" ? [ev] : [];
+      } catch {
+        return [];
+      }
+    };
+  }
+  let started = false;
+  let stopped = false;
+  let next = 0;
+  /** @type {number|null} */
+  let textIndex = null;
+  /** @type {Map<number, number>} */
+  const toolIndex = new Map();
+  const open = new Set();
+  return (frame) => {
+    if (stopped) return [];
+    if (frame.data === "[DONE]") {
+      stopped = true;
+      return [...[...open].map((index) => ({ type: "content_block_stop", index })), { type: "message_stop" }];
+    }
+    let chunk;
+    try {
+      chunk = JSON.parse(frame.data);
+    } catch {
+      return [];
+    }
+    if (!chunk || chunk.error) return [];
+    const out = [];
+    if (!started) {
+      started = true;
+      out.push({ type: "message_start", message: { role: "assistant", model: chunk.model ?? null, content: [] } });
+    }
+    for (const choice of Array.isArray(chunk.choices) ? chunk.choices : []) {
+      const d = choice.delta || {};
+      if (typeof d.content === "string" && d.content !== "") {
+        if (textIndex === null) {
+          textIndex = next++;
+          open.add(textIndex);
+          out.push({ type: "content_block_start", index: textIndex, content_block: { type: "text", text: "" } });
+        }
+        out.push({ type: "content_block_delta", index: textIndex, delta: { type: "text_delta", text: d.content } });
+      }
+      for (const tc of Array.isArray(d.tool_calls) ? d.tool_calls : []) {
+        const key = Number.isInteger(tc.index) ? tc.index : toolIndex.size;
+        let index = toolIndex.get(key);
+        if (index === undefined) {
+          index = next++;
+          toolIndex.set(key, index);
+          open.add(index);
+          out.push({ type: "content_block_start", index, content_block: { type: "tool_use", id: tc.id ?? `call_${key}`, name: tc.function?.name ?? "", input: {} } });
+        }
+        if (typeof tc.function?.arguments === "string" && tc.function.arguments !== "") {
+          out.push({ type: "content_block_delta", index, delta: { type: "input_json_delta", partial_json: tc.function.arguments } });
+        }
+      }
+      if (typeof choice.finish_reason === "string" && choice.finish_reason) {
+        for (const index of open) out.push({ type: "content_block_stop", index });
+        open.clear();
+        out.push({ type: "message_delta", delta: { stop_reason: OPENAI_STOP[/** @type {keyof OPENAI_STOP} */ (choice.finish_reason)] ?? "end_turn" } });
+      }
+    }
+    return out;
+  };
+}
+
+/**
+ * @param {{write:(s:string)=>unknown, sessionId:string, includePartialMessages?:boolean, wire:'openai'|'anthropic'}} p
+ */
+export function createStreamJsonWriter({ write, sessionId, includePartialMessages = false, wire }) {
+  const emit = (/** @type any */ ev) => {
+    if (ev) write(`${JSON.stringify(ev)}\n`);
+  };
+  return {
+    emit,
+    /** @param {Omit<Parameters<typeof initEvent>[0], 'sessionId'>} p */
+    init: (p) => emit(initEvent({ ...p, sessionId })),
+    /** @param {any} message @param {string|null} [parentToolUseId] */
+    message: (message, parentToolUseId = null) => emit(messageEvent(message, { sessionId, parentToolUseId })),
+    /** @param {any} quota @param {string|null} [parentToolUseId] */
+    quota: (quota, parentToolUseId = null) => emit(quotaEvent(quota, { sessionId, parentToolUseId })),
+    /** @param {any[]} todos */
+    todos: (todos) => emit(todosEvent(todos, sessionId)),
+    /** @param {any} result */
+    result: (result) => emit(result),
+    /**
+     * An `onFrame` for one model caller, or undefined without partial messages.
+     * A new translator starts at each message_start / first chunk of a call.
+     * @param {string|null} parentToolUseId
+     */
+    partialFrames(parentToolUseId = null) {
+      if (!includePartialMessages) return undefined;
+      let translate = createPartialTranslator(wire);
+      let ended = false;
+      return (/** @type {{event?:string, data:string}} */ frame) => {
+        if (ended) {
+          translate = createPartialTranslator(wire);
+          ended = false;
+        }
+        for (const event of translate(frame)) {
+          emit({ type: "stream_event", event, session_id: sessionId, parent_tool_use_id: parentToolUseId });
+          if (event.type === "message_stop") ended = true;
+        }
+      };
+    },
+  };
+}
+
+/**
+ * One NDJSON input line (`--input-format stream-json`) as a turn. Pure.
+ *   {type:'user', message:{role:'user', content: string | [{type:'text', text}, …]}}
+ * Blank lines are skipped (null). Non-text blocks are not accepted yet; the turn
+ * keeps its text and says what was left out.
+ * @param {string} line
+ * @returns {null | {ok:true, text:string} | {ok:false, error:string}}
+ */
+export function parseInputLine(line) {
+  const s = String(line).trim();
+  if (s === "") return null;
+  let ev;
+  try {
+    ev = JSON.parse(s);
+  } catch (e) {
+    return { ok: false, error: `input line is not JSON (${e instanceof Error ? e.message : e})` };
+  }
+  if (!ev || ev.type !== "user" || !ev.message || typeof ev.message !== "object") return { ok: false, error: `input line is not a {type:"user", message} event` };
+  const content = ev.message.content;
+  if (typeof content === "string") return content.trim() === "" ? { ok: false, error: "the user message is empty" } : { ok: true, text: content };
+  if (!Array.isArray(content)) return { ok: false, error: "message.content must be a string or an array of content blocks" };
+  const texts = content.filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text);
+  const skipped = content.filter((b) => b?.type !== "text").map((b) => String(b?.type ?? "unknown"));
+  const note = skipped.length ? `\n\n[Not included: ${skipped.join(", ")} content, which this engine does not accept yet.]` : "";
+  const text = texts.join("\n\n") + note;
+  return text.trim() === "" ? { ok: false, error: "the user message has no text" } : { ok: true, text };
+}
+
+/**
+ * Turns from NDJSON lines, in order; ends at EOF.
+ * @param {AsyncIterable<string>|Iterable<string>} lines
+ */
+export async function* readStreamJsonInput(lines) {
+  for await (const line of lines) {
+    const turn = parseInputLine(line);
+    if (turn) yield turn;
+  }
+}
+
+/**
+ * Wrap a model caller so each response's quota is reported.
+ * @template {(turn:any)=>Promise<any>} F
+ * @param {F} callModel @param {(quota:any)=>void} onQuota
+ * @returns {F}
+ */
+export function observeQuota(callModel, onQuota) {
+  return /** @type {F} */ (
+    async (/** @type any */ turn) => {
+      const res = await callModel(turn);
+      if (quotaPresent(res?.cohort?.quota)) {
+        try {
+          onQuota(res.cohort.quota);
+        } catch {
+          /* an output observer must not fail a model call */
+        }
+      }
+      return res;
+    }
+  );
+}