@cohortapp/agent-sdk 2.17.0 → 2.18.4

package/lib/engine/wire/anthropic-messages.mjs

@@ -0,0 +1,263 @@
+/**
+ * lib/engine/wire/anthropic-messages.mjs — the Anthropic Messages wire.
+ *
+ * cohort-llm's `/v1/messages` serves the engine's Anthropic mode and closed
+ * fallbacks (design §4.2). Same three layers as the OpenAI wire:
+ *   · `buildAnthropicRequest`      canonical history → body (pure)
+ *   · `createAnthropicAccumulator` SSE events → one assistant turn (pure state)
+ *   · `callAnthropicMessages`      the edge, over `postStream`
+ *
+ * Cache breakpoints. This wire caches only where the request says so, and the
+ * prefix order is tools → system → messages. `planAnthropicBreakpoints`
+ * (context/cache.mjs) places at most the four allowed `cache_control` markers:
+ *   1. the last tool definition   — tools rarely change within a session;
+ *   2. the last system block      — the end of the stable prefix;
+ *   3. the last user message of the previous turn — what the previous request
+ *      ended with, so this turn reads it even when many blocks were added since;
+ *   4. the last block of the final message — a rolling breakpoint that writes
+ *      the prefix the next turn reads.
+ * Placement is a pure function of the request shape, so it is identical on
+ * every turn and testable without a server.
+ *
+ * Images. A tool result carrying `images` (MCP image content) is sent as a
+ * tool_result whose content is a text block followed by base64 image blocks.
+ * With `images:false` the images are dropped and the text says so.
+ *
+ * Usage (design §4.5): `input_tokens` EXCLUDES cache. `message_start` carries
+ * the opening usage; `message_delta` carries cumulative fields — each field's
+ * last reported value wins.
+ *
+ * @module lib/engine/wire/anthropic-messages
+ */
+
+import { classifyStreamError, protocolError } from "./errors.mjs";
+import { postStream, joinUrl } from "./http.mjs";
+import { normaliseAnthropicUsage, emptyUsage } from "./usage.mjs";
+import { normaliseHistory } from "../messages.mjs";
+import { parseToolArguments, imageFallbackNote } from "./openai-chat.mjs";
+import { planAnthropicBreakpoints, markableBlockIndex } from "../context/cache.mjs";
+
+export const ANTHROPIC_MESSAGES_ROUTE = "/v1/messages";
+export const ANTHROPIC_VERSION = "2023-06-01";
+
+const EPHEMERAL = Object.freeze({ type: "ephemeral" });
+
+/**
+ * Where the cache markers go, as a pure description of the request shape.
+ * @param {{ toolCount:number, hasSystem:boolean, messageCount:number }} shape
+ * @returns {{ tool: number|null, system: boolean, message: number|null }}
+ */
+export function planCacheBreakpoints({ toolCount, hasSystem, messageCount }) {
+  return {
+    tool: toolCount > 0 ? toolCount - 1 : null,
+    system: hasSystem,
+    message: messageCount > 0 ? messageCount - 1 : null,
+  };
+}
+
+/**
+ * Strip engine-internal fields from a block before it goes on the wire.
+ * @param {any} b @param {boolean} [images]
+ */
+function wireBlock(b, images = true) {
+  switch (b.type) {
+    case "text":
+      return { type: "text", text: b.text };
+    case "tool_use":
+      return { type: "tool_use", id: b.id, name: b.name, input: b.input && typeof b.input === "object" ? b.input : {} };
+    case "tool_result": {
+      /** @type {any} */
+      const r = { type: "tool_result", tool_use_id: b.tool_use_id, content: b.content };
+      const imgs = Array.isArray(b.images) ? b.images : [];
+      if (imgs.length > 0 && images) {
+        r.content = [
+          { type: "text", text: String(b.content ?? "") },
+          ...imgs.map((i) => ({ type: "image", source: { type: "base64", media_type: i.mediaType, data: i.data } })),
+        ];
+      } else if (imgs.length > 0) {
+        r.content = `${b.content}${imageFallbackNote(imgs.length)}`;
+      }
+      if (b.is_error) r.is_error = true;
+      return r;
+    }
+    case "thinking": {
+      const r = { type: "thinking", thinking: b.thinking };
+      if (b.signature) r.signature = b.signature;
+      return r;
+    }
+    default:
+      return null;
+  }
+}
+
+/**
+ * @param {object} p
+ * @param {string} p.model
+ * @param {string} p.system
+ * @param {Array<{role:string, content:any[]}>} p.messages
+ * @param {Array<{name:string, description:string, input_schema:object}>} [p.tools]
+ * @param {number} p.maxTokens
+ * @param {boolean} [p.cacheBreakpoints] default true
+ * @param {boolean} [p.images] default true: tool-result images as image blocks
+ */
+export function buildAnthropicRequest({ model, system, messages, tools = [], maxTokens, cacheBreakpoints = true, images = true }) {
+  const history = normaliseHistory(messages).map((m) => ({
+    role: m.role,
+    content: m.content.map((b) => wireBlock(b, images)).filter(Boolean),
+  }));
+  const wireTools = tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.input_schema }));
+  const systemBlocks = system ? [{ type: "text", text: system }] : [];
+
+  if (cacheBreakpoints) {
+    const plan = planAnthropicBreakpoints({ toolCount: wireTools.length, hasSystem: systemBlocks.length > 0, messages: history });
+    if (plan.tool !== null) wireTools[plan.tool] = { ...wireTools[plan.tool], cache_control: EPHEMERAL };
+    if (plan.system) systemBlocks[systemBlocks.length - 1].cache_control = EPHEMERAL;
+    for (const index of plan.messages) {
+      const m = history[index];
+      const at = markableBlockIndex(m);
+      if (at >= 0) m.content[at] = { ...m.content[at], cache_control: EPHEMERAL };
+    }
+  }
+
+  /** @type {any} */
+  const body = { model, max_tokens: maxTokens, messages: history, stream: true };
+  if (systemBlocks.length > 0) body.system = systemBlocks;
+  if (wireTools.length > 0) body.tools = wireTools;
+  return body;
+}
+
+/**
+ * Accumulate one streamed Messages response into a canonical assistant turn.
+ * @param {{ now?: () => number }} [opts]
+ */
+export function createAnthropicAccumulator(opts = {}) {
+  const now = opts.now || Date.now;
+  /** @type {Map<number, any>} */
+  const blocks = new Map();
+  let usage = null;
+  let stopReason = null;
+  let model = null;
+  let started = false;
+  let stopped = false;
+
+  function mergeUsage(u) {
+    if (!u || typeof u !== "object") return;
+    usage = { ...(usage || {}) };
+    for (const [k, v] of Object.entries(u)) if (v !== null && v !== undefined) usage[k] = v;
+  }
+
+  return {
+    /** @param {import('./sse.mjs').SseFrame} frame */
+    onFrame(frame) {
+      let ev;
+      try {
+        ev = JSON.parse(frame.data);
+      } catch {
+        return { ok: false, error: protocolError(`unparseable stream event: ${frame.data.slice(0, 120)}`) };
+      }
+      const type = ev?.type || frame.event;
+      switch (type) {
+        case "message_start":
+          started = true;
+          if (typeof ev.message?.model === "string") model = ev.message.model;
+          mergeUsage(ev.message?.usage);
+          return { ok: true };
+        case "content_block_start": {
+          const cb = ev.content_block || {};
+          if (cb.type === "text") blocks.set(ev.index, { type: "text", text: cb.text || "" });
+          else if (cb.type === "tool_use") blocks.set(ev.index, { type: "tool_use", id: cb.id, name: cb.name, json: "" });
+          else if (cb.type === "thinking") blocks.set(ev.index, { type: "thinking", thinking: cb.thinking || "", signature: cb.signature || "" });
+          return { ok: true };
+        }
+        case "content_block_delta": {
+          const b = blocks.get(ev.index);
+          const d = ev.delta || {};
+          if (!b) return { ok: true };
+          if (d.type === "text_delta" && b.type === "text") b.text += d.text || "";
+          else if (d.type === "input_json_delta" && b.type === "tool_use") b.json += d.partial_json || "";
+          else if (d.type === "thinking_delta" && b.type === "thinking") b.thinking += d.thinking || "";
+          else if (d.type === "signature_delta" && b.type === "thinking") b.signature += d.signature || "";
+          return { ok: true };
+        }
+        case "content_block_stop":
+        case "ping":
+          return { ok: true };
+        case "message_delta":
+          if (typeof ev.delta?.stop_reason === "string") stopReason = ev.delta.stop_reason;
+          mergeUsage(ev.usage);
+          return { ok: true };
+        case "message_stop":
+          stopped = true;
+          return { ok: true, done: true };
+        case "error":
+          return { ok: false, error: classifyStreamError(ev, null, now()) };
+        default:
+          // Unknown event types are forward-compatible additions; ignore them.
+          return { ok: true };
+      }
+    },
+
+    finish() {
+      if (!started || !stopped) return { ok: false, error: protocolError("stream ended before message_stop") };
+      /** @type {any[]} */
+      const content = [];
+      for (const [, b] of [...blocks.entries()].sort((a, c) => a[0] - c[0])) {
+        if (b.type === "text") {
+          if (b.text !== "") content.push({ type: "text", text: b.text });
+        } else if (b.type === "tool_use") {
+          content.push({ type: "tool_use", id: b.id, name: b.name, ...parseToolArguments(b.json) });
+        } else if (b.type === "thinking") {
+          const t = { type: "thinking", thinking: b.thinking };
+          if (b.signature) t.signature = b.signature;
+          content.push(t);
+        }
+      }
+      const hasTools = content.some((b) => b.type === "tool_use");
+      return {
+        ok: true,
+        value: {
+          message: { role: "assistant", content },
+          // max_tokens is kept even when tool_use blocks exist: the last call's
+          // input may be cut off, and the loop must not run a truncated call.
+          stopReason: stopReason === "max_tokens" ? "max_tokens" : hasTools ? "tool_use" : stopReason || "end_turn",
+          usage: usage ? normaliseAnthropicUsage(usage) : emptyUsage("estimated"),
+          model,
+        },
+      };
+    },
+  };
+}
+
+/**
+ * One model turn over the Anthropic wire. Same parameters as `callOpenAIChat`.
+ * @param {Parameters<typeof import('./openai-chat.mjs').callOpenAIChat>[0]} p
+ */
+export async function callAnthropicMessages(p) {
+  const body = buildAnthropicRequest({
+    model: p.model,
+    system: p.system,
+    messages: p.messages,
+    tools: p.tools,
+    maxTokens: p.maxTokens ?? 16000,
+    cacheBreakpoints: p.cacheBreakpoints ?? true,
+    images: p.images ?? true,
+  });
+  return postStream({
+    url: joinUrl(p.baseUrl, ANTHROPIC_MESSAGES_ROUTE),
+    headers: { "anthropic-version": ANTHROPIC_VERSION, ...(p.headers || {}) },
+    body,
+    token: p.token,
+    createAccumulator: () => createAnthropicAccumulator({ now: p.now }),
+    onFrame: p.onFrame,
+    signal: p.signal,
+    fetchImpl: p.fetchImpl,
+    maxRetries: p.maxRetries,
+    now: p.now,
+    sleep: p.sleep,
+    idleTimeoutMs: p.idleTimeoutMs,
+    slowStreamMs: p.slowStreamMs,
+    onStreamDiagnostic: p.onStreamDiagnostic,
+    wire: "anthropic",
+    tier: p.model,
+  });
+}

package/lib/engine/wire/effort.mjs

@@ -0,0 +1,36 @@
+/**
+ * lib/engine/wire/effort.mjs — `--effort` → the request's reasoning-effort field (pure).
+ *
+ * The engine accepts the claude-compatible `--effort low|medium|high|xhigh|max`.
+ * It becomes a request parameter only where it can mean something:
+ *
+ *   · OpenAI wire, on a tier whose legs take a reasoning-effort hint →
+ *     `reasoning_effort` (low | medium | high; xhigh and max send "high").
+ *   · Anthropic wire, or a tier without such legs → not sent. The flag is still
+ *     accepted, and the caller gets a note to print under --verbose.
+ *
+ * REASONING_EFFORT_TIERS follows the provisional slot map (design §4.7): the
+ * reasoning-class legs (Kimi-K3, GLM-5.3, DeepSeek-V4-Pro) behind
+ * cohort-reason and cohort-agentic. It is revisited with the slot map at W4-C.
+ *
+ * @module lib/engine/wire/effort
+ */
+
+export const EFFORT_LEVELS = Object.freeze(["low", "medium", "high", "xhigh", "max"]);
+export const REASONING_EFFORT_TIERS = Object.freeze(new Set(["cohort-reason", "cohort-agentic"]));
+
+/** @param {unknown} v */
+export function isEffortLevel(v) {
+  return typeof v === "string" && EFFORT_LEVELS.includes(v);
+}
+
+/**
+ * @param {{effort:string|null|undefined, wire:string, tier:string}} p
+ * @returns {{param:'low'|'medium'|'high'|null, note:string|null}}
+ */
+export function resolveEffort({ effort, wire, tier }) {
+  if (!effort) return { param: null, note: null };
+  if (wire !== "openai") return { param: null, note: `--effort ${effort} is not sent on the ${wire} wire (accepted and ignored)` };
+  if (!REASONING_EFFORT_TIERS.has(tier)) return { param: null, note: `--effort ${effort} is ignored: tier ${tier} takes no reasoning-effort hint` };
+  return { param: effort === "low" || effort === "medium" ? effort : "high", note: null };
+}