@magpie-community/opencode-zen-free-auth 0.1.1 → 0.1.9

package/README.md

@@ -3,6 +3,12 @@
 OpenCode Zen's free models in magpie and OpenCode. Provider id:
 `opencode-zen-free`.
 
+Since 2026-10-13 Zen's free tier answers 403 FreeTierError ("can only be
+used from within OpenCode") to a request that isn't OpenCode's. From
+0.1.6 the plugin sends a free-model request with exactly the headers
+OpenCode 1.19.0 sends to Zen, and a session id of OpenCode's own form.
+Older versions (0.1.1 on npm before it) get the 403: update the plugin.
+
 ## Install
 
 ```sh
@@ -22,12 +28,21 @@ The plugin discovers Zen's current free models, including their context
 windows and reasoning levels. Use `opencode-zen-free/<model>`, for example
 `opencode-zen-free/big-pickle`.
 
-Retired models and SystemOne models are excluded. Availability and rate
-limits are set by Zen; the plugin has no remaining-quota data.
+Retired models and SystemOne models are excluded. The list is asked
+again each time the host lists models (magpie does this on start and every
+hour): a model Zen no longer gives free leaves it, and a new free one joins
+it. A model Zen lists as `-free` that OpenCode's catalog and docs don't
+describe yet (or can't be read) is offered too, on Chat Completions, as
+OpenCode asks a model with no package of its own. When Zen's list can't be
+read, the last list is kept. A request for a
+model that isn't free now gets a 404 naming the free ones; one made free
+since the last list is served after the list is asked again (at most once a
+minute). Availability and rate limits are set by Zen; the plugin has no
+remaining-quota data.
 
 ## Requests
 
-Requests go to `https://opencode.ai/zen/v1` using each model's native
+Requests go to `https://opencode.ai/inference/v1` using each model's native
 Chat Completions, Responses or Anthropic Messages API. Streaming and
 ordinary JSON replies are supported.
 
@@ -35,5 +50,21 @@ The agent's tools are preserved. Zen's models often call OpenCode's own
 tool names; such a call is given the agent's tool whose name differs only
 in case (`bash` to `Bash`), or else only in case and `_`/`-` (`todowrite`
 to `todo_write`, `webfetch` to `web_fetch`), when exactly one does. A
-call with no such tool returns an error that names it. Tools run in the
-agent.
+call with no such tool (or with no name) is left out of the reply, and
+the reply's text says which name was left out; a turn whose every call
+was left out ends as an ordinary answer. Tools run in the agent.
+
+Zen's free tier only answers a request that carries tools, so a request
+is sent with the five core OpenCode tools the agent doesn't declare
+itself (`bash`, `edit`, `glob`, `grep`, `read`), described as not
+available. A call of one of them the agent doesn't have is left out like
+any other.
+
+Now and then Zen closes a streamed Chat Completions reply before its
+`[DONE]`. When the reply has said something and no tool call of it is
+unfinished, it ends there as an ordinary answer, and its text says it was
+cut short; asking again goes on. A reply cut short with a tool call
+unfinished, with nothing said, or collapsed for a client that doesn't
+stream fails with an error naming the reply's id and how much of it came.
+An Anthropic Messages or Responses reply cut short fails too: magpie
+tells it from a whole one and, where the model can, goes on with it.

package/models.mjs

@@ -41,13 +41,31 @@ export function isFree(id, model = {}) {
   );
 }
 
+// A model Zen lists whose id says it is free (Zen names them "-free"), and
+// that neither the catalog nor the docs describe yet: Zen made it free
+// after they were last written (deepseek-v4.1-flash-free, yetone/magpie#2385),
+// or they couldn't be read. It is asked as OpenCode asks a model with no
+// package of its own, through the provider's (openai-compatible, chat), so
+// a new free model is offered the hour Zen lists it, not when the catalog
+// or this plugin catch up. A paid or zero-cost id the id doesn't call free
+// still needs the catalog's word.
+function listedFree(id) {
+  return /-free$/.test(id);
+}
+
 export function buildModels(ids, provider, protocols, baseURL) {
   const result = {};
   for (const id of ids) {
     if (typeof id !== "string" || !id || id === "__proto__") continue;
     const raw = provider.models?.[id];
     const model = raw ?? {};
-    const protocol = protocols[id] ?? (raw && sdkProtocol(model.provider?.npm ?? provider.npm));
+    const protocol =
+      protocols[id] ??
+      (raw
+        ? sdkProtocol(model.provider?.npm ?? provider.npm)
+        : listedFree(id)
+          ? (sdkProtocol(provider.npm) ?? "chat")
+          : undefined);
     if (!isFree(id, model) || !Object.hasOwn(SDK, protocol)) continue;
     const input = model.modalities?.input ?? ["text"];
     const output = model.modalities?.output ?? ["text"];
@@ -85,10 +103,73 @@ export function buildModels(ids, provider, protocols, baseURL) {
   return result;
 }
 
-// Offline bootstrap metadata from the OpenCode catalog, 2026-10-06.
+// What each free model is asked at, from OpenCode's console docs
+// (services/www/src/docs/content/console/models.mdx) on 2026-10-15: used for
+// a listed model when the docs can't be read, so the catalog or the docs
+// being out of reach never leaves a listed free model out. Jev is a
+// SystemOne decision model, not one to chat with.
+export const bootstrapProtocols = {
+  "big-pickle": "chat",
+  "space-bunny-free": "chat",
+  "cat-jam-free": "chat",
+  "longcat-2.5-preview-free": "chat",
+  "step-5-preview-free": "chat",
+  "mimo-v2.6-flash-free": "chat",
+  "nemotron-3.5-lightning-free": "chat",
+  "muse-spark-1.3-contributor-free": "responses",
+  "jev-1.13-free": "systemone",
+};
+
+// Offline bootstrap metadata from the OpenCode catalog, 2026-10-06; the
+// free models listed since added on 2026-10-15.
 export const bootstrapProvider = {
   npm: SDK.chat,
   models: {
+    "cat-jam-free": {
+      name: "Cat Jam Free",
+      cost: { input: 0, output: 0 },
+      limit: { context: 262144, output: 131072 },
+      reasoning: true,
+      tool_call: true,
+      interleaved: { field: "reasoning_content" },
+      reasoning_options: [{ type: "effort", values: ["low", "medium", "high", "xhigh", "max"] }],
+    },
+    "step-5-preview-free": {
+      name: "Step 5 Preview Free",
+      cost: { input: 0, output: 0 },
+      limit: { context: 1000000, input: 1000000, output: 65536 },
+      reasoning: true,
+      tool_call: true,
+      interleaved: { field: "reasoning_content" },
+      modalities: { input: ["text", "image", "video"], output: ["text"] },
+      reasoning_options: [{ type: "effort", values: ["low", "medium", "high"] }],
+    },
+    "longcat-2.5-preview-free": {
+      name: "LongCat 2.5 Preview Free",
+      cost: { input: 0, output: 0 },
+      limit: { context: 1000000, output: 131072 },
+      reasoning: true,
+      tool_call: true,
+      interleaved: { field: "reasoning_content" },
+      modalities: { input: ["text", "image"], output: ["text"] },
+    },
+    "mimo-v2.6-flash-free": {
+      name: "MiMo-V2.6-Flash Free",
+      cost: { input: 0, output: 0 },
+      limit: { context: 200000, output: 32000 },
+      reasoning: true,
+      tool_call: true,
+      interleaved: { field: "reasoning_content" },
+      modalities: { input: ["text", "image", "audio", "video"], output: ["text"] },
+    },
+    "nemotron-3.5-lightning-free": {
+      name: "Nemotron 3.5 Lightning Free",
+      cost: { input: 0, output: 0 },
+      limit: { context: 262144, output: 262144 },
+      reasoning: true,
+      tool_call: true,
+      interleaved: { field: "reasoning_content" },
+    },
     "big-pickle": {
       name: "Big Pickle",
       cost: { input: 0, output: 0 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magpie-community/opencode-zen-free-auth",
-  "version": "0.1.1",
+  "version": "0.1.9",
   "description": "OpenCode Zen free models through the public credential, with native streaming protocols",
   "type": "module",
   "main": "./index.mjs",

package/provider.mjs

@@ -1,7 +1,8 @@
-import { createHash, randomUUID } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import {
   PROVIDER,
   SDK,
+  bootstrapProtocols,
   bootstrapProvider,
   buildModels,
   configModels,
@@ -10,13 +11,40 @@ import {
 import { collapseResponse } from "./stream.mjs";
 import { guardToolResponse } from "./tool-response.mjs";
 
-const DEFAULT_BASE = "https://opencode.ai/zen/v1";
+// Zen's free models answer only at the inference API since mid-October
+// 2026: the same request OpenCode 1.19.0 sends answers 403 FreeTierError
+// at /zen/v1 and 200 here, and models.dev gives OpenCode this URL. A model
+// listed before then still names /zen/v1 (LEGACY_BASE), which is asked here.
+const DEFAULT_BASE = "https://opencode.ai/inference/v1";
+const LEGACY_BASE = "https://opencode.ai/zen/v1";
 const CATALOG = "https://models.opencode.ai/api.json";
+// OpenCode's table of what each model is asked at; packages/web's zen.mdx,
+// read before, was removed on 2026-10-12 (anomalyco/opencode#54761)
 const DOCS =
-  "https://raw.githubusercontent.com/anomalyco/opencode/dev/packages/web/src/content/docs/zen.mdx";
+  "https://raw.githubusercontent.com/anomalyco/opencode/dev/services/www/src/docs/content/console/models.mdx";
 const PATHS = { chat: "/chat/completions", responses: "/responses", anthropic: "/messages" };
 const CORE_TOOLS = ["bash", "edit", "glob", "grep", "read"];
-const OPENCODE_VERSION = "1.18.34";
+// The parameter each stand-in takes, OpenCode's own first one: Zen's free
+// tier answers 403 FreeTierError to bash or read offered with none.
+const CORE_PARAMETER = {
+  bash: "command",
+  edit: "filePath",
+  glob: "pattern",
+  grep: "pattern",
+  read: "filePath",
+};
+const OPENCODE_VERSION = "1.19.0";
+// What OpenCode 1.19.0 sends as its User-Agent, ai-sdk and Bun included.
+// Each protocol's ai-sdk package bundles its own provider-utils, so the
+// version differs by protocol (captured from the release binary's requests).
+const PROVIDER_UTILS = { chat: "4.0.23", responses: "4.0.40", anthropic: "4.0.46" };
+export function userAgent(protocol) {
+  return `opencode/${OPENCODE_VERSION} ai-sdk/provider-utils/${PROVIDER_UTILS[protocol]} runtime/bun/1.3.14`;
+}
+// How long a request for a model the last list didn't have waits before it
+// asks Zen's list again: a model Zen made free since is served at once,
+// and a model typed in by hand doesn't ask the list on every request.
+const RELIST_AFTER = 60_000;
 
 function httpURL(value) {
   const url = new URL(value);
@@ -63,11 +91,13 @@ function normalizeTools(body, protocol) {
   if (protocol === "chat" && Array.isArray(body.functions)) {
     for (const tool of body.functions) if (typeof tool?.name === "string") declared.add(tool.name);
   }
-  const injected = new Set();
   for (const name of CORE_TOOLS) {
     if (present.has(name)) continue;
-    injected.add(name);
-    const parameters = { type: "object", properties: {}, additionalProperties: false };
+    const parameters = {
+      type: "object",
+      properties: { [CORE_PARAMETER[name]]: { type: "string" } },
+      additionalProperties: false,
+    };
     const definition = { name, description: "Not available. Never call this tool." };
     body.tools.push(
       protocol === "chat"
@@ -77,13 +107,48 @@ function normalizeTools(body, protocol) {
           : { type: "function", ...definition, parameters },
     );
   }
-  return { declared, injected };
+  return { declared };
+}
+
+const ALPHABET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+let lastStamp = 0;
+let counter = 0;
+
+// An id the way OpenCode makes one (packages/schema/src/identifier.ts):
+// 12 hex of Date.now() * 0x1000 + a per-millisecond counter (bit-inverted
+// for a session, so newer sorts first), then 14 random base62 characters.
+// Zen's free tier checks a session id has this shape, a small counter
+// included, and answers 403 FreeTierError to one that doesn't (#100).
+export function opencodeID(prefix, descending, now = Date.now()) {
+  if (now !== lastStamp) {
+    lastStamp = now;
+    counter = 0;
+  }
+  counter++;
+  const current = BigInt(now) * 0x1000n + BigInt(counter);
+  const value = (descending ? ~current : current) & 0xffffffffffffn;
+  const random = randomBytes(14);
+  let tail = "";
+  for (const byte of random) tail += ALPHABET[byte % 62];
+  return `${prefix}_${value.toString(16).padStart(12, "0")}${tail}`;
+}
+
+// A session id OpenCode itself could have made: its counter (the low 12
+// bits, inverted) is small. A hash cut to the same shape isn't one.
+export function realSessionID(value) {
+  const match = /^ses_[0-9a-f]{9}([0-9a-f]{3})[0-9A-Za-z]{14}$/.exec(value ?? "");
+  return !!match && 0xfff - Number.parseInt(match[1], 16) < 16;
 }
 
-function sessionID(headers, body) {
+// One made-up session per conversation, so its turns keep one session.
+const SESSIONS = new Map();
+const KEEP_SESSIONS = 1000;
+
+export function sessionID(headers, body) {
   let signal;
   for (const name of [
     "x-opencode-session",
+    "x-opencode-session-id",
     "x-session-affinity",
     "x-session-id",
     "conversation-id",
@@ -94,34 +159,41 @@ function sessionID(headers, body) {
     }
   }
   if (!signal && typeof body.metadata?.session_id === "string") signal = body.metadata.session_id;
+  if (realSessionID(signal)) return signal;
   if (!signal) {
     const messages = body.messages ?? body.input;
     const first = Array.isArray(messages)
       ? messages.find((message) => message.role === "user")?.content
       : messages;
-    signal = first ? JSON.stringify(first) : randomUUID();
+    if (!first) return opencodeID("ses", true);
+    signal = JSON.stringify(first);
   }
-  if (/^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$/.test(signal)) return signal;
-  // Keep conversation affinity using OpenCode's canonical session format.
-  const hash = createHash("sha256").update(`ses\0${signal}`).digest("hex");
-  let value = BigInt(`0x${hash.slice(12, 32)}`);
-  let suffix = "";
-  const alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
-  for (let i = 0; i < 14; i++) {
-    suffix = alphabet[Number(value % 62n)] + suffix;
-    value /= 62n;
+  const key = createHash("sha256").update(`ses\0${signal}`).digest("hex");
+  let session = SESSIONS.get(key);
+  if (session) {
+    SESSIONS.delete(key);
+  } else {
+    session = opencodeID("ses", true);
+    if (SESSIONS.size >= KEEP_SESSIONS) SESSIONS.delete(SESSIONS.keys().next().value);
   }
-  return `ses_${hash.slice(0, 12)}${suffix}`;
+  SESSIONS.set(key, session);
+  return session;
 }
 
 async function server(_input, options = {}) {
   const baseURL = httpURL(options.baseURL ?? DEFAULT_BASE);
   const catalogURL = httpURL(options.catalogURL ?? CATALOG);
   const docsURL = httpURL(options.docsURL ?? DOCS);
-  let known = buildModels(Object.keys(bootstrapProvider.models), bootstrapProvider, {}, baseURL);
+  let known = buildModels(
+    Object.keys(bootstrapProvider.models),
+    bootstrapProvider,
+    bootstrapProtocols,
+    baseURL,
+  );
   let metadata = bootstrapProvider;
-  let protocols = {};
+  let protocols = { ...bootstrapProtocols };
   let listed = false;
+  let listedAt = 0;
 
   async function discover(signal) {
     const headers = { authorization: "Bearer public", "x-opencode-client": "cli" };
@@ -138,7 +210,7 @@ async function server(_input, options = {}) {
       partial = true;
     }
     if (docs.status === "fulfilled" && Object.keys(parseProtocolDocs(docs.value)).length) {
-      protocols = parseProtocolDocs(docs.value);
+      protocols = { ...bootstrapProtocols, ...parseProtocolDocs(docs.value) };
     } else {
       partial = true;
     }
@@ -156,10 +228,15 @@ async function server(_input, options = {}) {
           discovered[id] = known[id];
         }
       }
-      discovered[Symbol.for("magpie.fellBack")] = true;
+      // Not said as fallen back: Zen's own list was read, and what it
+      // lists is what is offered. Said so, magpie kept the last list read
+      // in full instead, and a user who can't reach the catalog or the
+      // docs (GitHub's raw host, from mainland China) never saw a model
+      // Zen made free since (yetone/magpie#2385).
     }
     known = discovered;
     listed = true;
+    listedAt = Date.now();
     return discovered;
   }
 
@@ -198,7 +275,9 @@ async function server(_input, options = {}) {
             requirePublic(await getAuth());
             const request = new Request(input, init);
             const protocol = Object.keys(PATHS).find(
-              (key) => request.url === `${baseURL}${PATHS[key]}`,
+              (key) =>
+                request.url === `${baseURL}${PATHS[key]}` ||
+                (baseURL === DEFAULT_BASE && request.url === `${LEGACY_BASE}${PATHS[key]}`),
             );
             if (!protocol || request.method !== "POST")
               throw new Error("Unsupported Zen endpoint or method");
@@ -206,11 +285,31 @@ async function server(_input, options = {}) {
             const body = await request.json();
             if (!body || typeof body !== "object" || Array.isArray(body))
               throw new Error("Expected a JSON request object");
-            if (!listed && !Object.hasOwn(known, body.model)) {
+            if (
+              !Object.hasOwn(known, body.model) &&
+              (!listed || Date.now() - listedAt >= RELIST_AFTER)
+            ) {
               await discover(request.signal);
             }
-            const model = known[body.model];
-            if (!model || model.api.npm !== SDK[protocol]) {
+            const model = Object.hasOwn(known, body.model) ? known[body.model] : undefined;
+            if (!model) {
+              // Zen no longer gives it free, or never did: said as a model
+              // not served, so the caller sets this model aside and not the
+              // account, whose other free models are still served.
+              const free = Object.keys(known).sort().join(", ");
+              const name = typeof body.model === "string" ? body.model : "";
+              return new Response(
+                JSON.stringify({
+                  type: "error",
+                  error: {
+                    type: "not_found_error",
+                    message: `Model ${name} is not available as an OpenCode Zen free model now. Free models: ${free || "none"}.`,
+                  },
+                }),
+                { status: 404, headers: { "content-type": "application/json" } },
+              );
+            }
+            if (model.api.npm !== SDK[protocol]) {
               throw new Error(
                 "Model is not an available free model for this protocol. Refresh the model list.",
               );
@@ -220,47 +319,42 @@ async function server(_input, options = {}) {
             const toolPolicy = normalizeTools(body, protocol);
             if (protocol === "chat")
               body.stream_options = { ...body.stream_options, include_usage: true };
-            const headers = new Headers(request.headers);
-            for (const name of [
-              "authorization",
-              "x-api-key",
-              "x-goog-api-key",
-              "content-length",
-              "content-encoding",
-              "host",
-              "cookie",
-            ]) {
-              headers.delete(name);
-            }
-            headers.set("content-type", "application/json");
-            headers.set("accept", "text/event-stream");
-            headers.set("user-agent", `opencode/${OPENCODE_VERSION}`);
-            headers.set("x-opencode-client", "cli");
-            headers.set("x-opencode-request", `req_${randomUUID().replaceAll("-", "")}`);
-            if (!headers.has("x-opencode-project")) {
-              const project = _input?.project;
-              headers.set(
-                "x-opencode-project",
-                project?.vcs === "git" && project.id ? project.id : "global",
-              );
-            }
-            const session = sessionID(headers, body);
-            for (const name of ["x-session-id", "x-opencode-session", "x-session-affinity"])
-              headers.set(name, session);
+            // Only what OpenCode 1.19.0 itself sends to its gateway, so a
+            // caller's own headers (an agent's User-Agent, x-stainless-*,
+            // x-session-affinity, ...) never mark the request as not
+            // OpenCode's (packages/opencode/src/session/llm/request.ts).
+            const given = request.headers;
+            const session = sessionID(given, body);
+            const project = _input?.project;
+            const headers = new Headers({
+              "content-type": "application/json",
+              accept: "*/*",
+              "user-agent": userAgent(protocol),
+              "x-opencode-project":
+                given.get("x-opencode-project") ||
+                (project?.vcs === "git" && project.id ? project.id : "global"),
+              "x-opencode-session": session,
+              "x-opencode-request": opencodeID("msg", false),
+              "x-opencode-client": "cli",
+              "x-opencode-session-id": session,
+            });
             if (protocol === "anthropic") {
               headers.set("x-api-key", "public");
-              if (!headers.has("anthropic-version")) headers.set("anthropic-version", "2023-06-01");
+              headers.set("anthropic-version", given.get("anthropic-version") || "2023-06-01");
+              if (given.get("anthropic-beta")) headers.set("anthropic-beta", given.get("anthropic-beta"));
             } else {
               headers.set("authorization", "Bearer public");
             }
-            const response = await fetch(request.url, {
+            const response = await fetch(`${baseURL}${PATHS[protocol]}`, {
               method: "POST",
               headers,
               body: JSON.stringify(body),
               signal: request.signal,
               redirect: "error",
             });
-            const guarded = await guardToolResponse(response, protocol, toolPolicy);
+            const guarded = await guardToolResponse(response, protocol, toolPolicy, {
+              endCutShort: streaming,
+            });
             return streaming ? guarded : collapseResponse(guarded, protocol);
           },
         };

package/tool-response.mjs

@@ -40,11 +40,16 @@ function foldsTo(declared, key) {
   const folded = new Map();
   for (const name of declared) {
     const k = key(name);
+    // A name of separators only folds to nothing, and would be handed any
+    // other such call ("_" for "--"): it matches only itself.
+    if (!k) continue;
     folded.set(k, folded.has(k) ? null : name);
   }
   return folded;
 }
 
+// nameGuard answers the agent's name for a call, or null for a call of no
+// tool the agent has (a missing name included).
 function nameGuard(policy) {
   const declared = new Set(policy.declared);
   const lower = (name) => name.toLowerCase();
@@ -52,49 +57,135 @@ function nameGuard(policy) {
   const byCase = foldsTo(declared, lower);
   const byShape = foldsTo(declared, bare);
   return (name) => {
-    if (typeof name !== "string" || !name) throw new GuardError("Missing upstream tool name");
+    if (typeof name !== "string" || !name) return null;
     if (declared.has(name)) return name;
-    const match = byCase.get(lower(name)) ?? (byCase.has(lower(name)) ? null : byShape.get(bare(name)));
-    if (match) return match;
-    throw new GuardError(
-      `Upstream called a tool not declared by the client: ${JSON.stringify(name.slice(0, 128))}`,
-    );
+    const match =
+      byCase.get(lower(name)) ?? (byCase.has(lower(name)) ? null : byShape.get(bare(name)));
+    return match || null;
   };
 }
 
-function checkFunction(value, checkName) {
-  if (!object(value)) throw new GuardError("Invalid upstream function call");
-  const name = checkName(value.name);
-  const changed = name !== value.name;
-  value.name = name;
-  return changed;
+// The models also call tools no agent has: bedit, bcp, ash, a mangled
+// mcp__netcatcatty__unused (#76). Such a call can't be run or named onto
+// one the agent has, and failing the reply for it threw away the whole
+// turn. It is left out instead, and the reply says so in its text, where
+// the agent's user and the model's next turn both read it. A reply left
+// with no call ends as a plain stop.
+export function droppedNote(name) {
+  return typeof name === "string" && name
+    ? `(The model called a tool this agent doesn't have: ${JSON.stringify(name.slice(0, 128))}. The call was left out.)`
+    : "(The model called a tool without a name. The call was left out.)";
 }
 
+function appendNotes(message, notes) {
+  const text = notes.join("\n\n");
+  if (typeof message.content === "string" && message.content) {
+    message.content = `${message.content}\n\n${text}`;
+  } else if (Array.isArray(message.content)) {
+    message.content.push({ type: "text", text });
+  } else {
+    message.content = text;
+  }
+}
+
+// checkChatMessage renames message's calls to the agent's tools and leaves
+// out the rest, answering the notes for those left out.
 function checkChatMessage(message, checkName) {
-  if (!object(message)) return false;
-  let changed = false;
-  if (message.function_call != null) changed = checkFunction(message.function_call, checkName);
-  for (const call of list(message.tool_calls)) {
-    if (!object(call) || (call.type != null && call.type !== "function")) {
-      throw new GuardError("Unsupported upstream tool call");
+  const result = { changed: false, notes: [] };
+  if (!object(message)) return result;
+  if (message.function_call != null) {
+    const value = message.function_call;
+    if (!object(value)) throw new GuardError("Invalid upstream function call");
+    const name = checkName(value.name);
+    if (name == null) {
+      result.notes.push(droppedNote(value.name));
+      delete message.function_call;
+      result.changed = true;
+    } else if (name !== value.name) {
+      value.name = name;
+      result.changed = true;
+    }
+  }
+  if (message.tool_calls != null) {
+    const calls = list(message.tool_calls);
+    const kept = [];
+    for (const call of calls) {
+      if (!object(call) || (call.type != null && call.type !== "function")) {
+        throw new GuardError("Unsupported upstream tool call");
+      }
+      if (!object(call.function)) throw new GuardError("Invalid upstream function call");
+      const name = checkName(call.function.name);
+      if (name == null) {
+        result.notes.push(droppedNote(call.function.name));
+        result.changed = true;
+        continue;
+      }
+      if (name !== call.function.name) {
+        call.function.name = name;
+        result.changed = true;
+      }
+      kept.push(call);
+    }
+    if (kept.length !== calls.length) {
+      if (kept.length) message.tool_calls = kept;
+      else delete message.tool_calls;
     }
-    changed = checkFunction(call.function, checkName) || changed;
   }
-  return changed;
+  return result;
+}
+
+const callFinish = new Set(["tool_calls", "function_call"]);
+function hasCalls(message) {
+  return message.function_call != null || (message.tool_calls?.length ?? 0) > 0;
+}
+
+function isCall(protocol, value) {
+  return (
+    (protocol === "responses" && value.type === "function_call") ||
+    (protocol === "anthropic" && ["tool_use", "server_tool_use"].includes(value.type))
+  );
 }
 
+// What a call left out of a Responses or Messages reply becomes: text
+// saying so, in the call's place, so no later index moves.
+function inPlaceOf(protocol, call, note) {
+  if (protocol === "anthropic") return { type: "text", text: note };
+  return {
+    type: "message",
+    id: typeof call.id === "string" && call.id ? call.id : `msg_${call.call_id ?? "dropped"}`,
+    role: "assistant",
+    status: call.status ?? "completed",
+    content: [{ type: "output_text", text: note, annotations: [] }],
+  };
+}
+
+// checkSnapshots checks every call in a reply or event: renamed to the
+// agent's tool, or (Responses, Messages) put in place of by a note. It
+// answers whether data changed, how many calls it kept and how many it
+// left out.
 function checkSnapshots(data, protocol, checkName) {
   let changed = false;
   if (protocol === "chat") {
     for (const choice of list(data.choices)) {
       if (!object(choice)) throw new GuardError("Invalid upstream choice");
-      changed = checkChatMessage(choice.message, checkName) || changed;
+      const message = choice.message;
+      const checked = checkChatMessage(message, checkName);
+      changed = checked.changed || changed;
+      if (checked.notes.length) {
+        appendNotes(message, checked.notes);
+        if (!hasCalls(message) && callFinish.has(choice.finish_reason))
+          choice.finish_reason = "stop";
+      }
     }
-    return changed;
+    return { changed, kept: 0, left: 0 };
   }
-  const stack = [data];
+  let kept = 0;
+  let left = 0;
+  if (!object(data)) throw new GuardError("Invalid upstream tool snapshot");
+  // Each entry is a value and where it sits, so a call can be replaced.
+  const stack = [[data, null, null]];
   while (stack.length) {
-    const value = stack.pop();
+    const [value, holder, key] = stack.pop();
     if (!object(value)) throw new GuardError("Invalid upstream tool snapshot");
     if (
       protocol === "responses" &&
@@ -104,25 +195,44 @@ function checkSnapshots(data, protocol, checkName) {
     ) {
       throw new GuardError("Unsupported upstream tool call type");
     }
-    if (
-      (protocol === "responses" && value.type === "function_call") ||
-      (protocol === "anthropic" && ["tool_use", "server_tool_use"].includes(value.type))
-    ) {
-      changed = checkFunction(value, checkName) || changed;
+    if (isCall(protocol, value)) {
+      const name = checkName(value.name);
+      if (name == null) {
+        if (!holder) throw new GuardError(droppedNote(value.name));
+        holder[key] = inPlaceOf(protocol, value, droppedNote(value.name));
+        changed = true;
+        left++;
+        continue;
+      }
+      if (name !== value.name) {
+        value.name = name;
+        changed = true;
+      }
+      kept++;
     }
     const arrays = protocol === "responses" ? ["output", "content"] : ["content"];
     const objects =
       protocol === "responses" ? ["response", "item", "part"] : ["message", "content_block"];
-    for (const key of arrays) {
+    for (const name of arrays) {
       // Text content is not a snapshot container.
-      if (typeof value[key] === "string") continue;
-      for (const item of list(value[key])) stack.push(item);
+      if (typeof value[name] === "string") continue;
+      const items = list(value[name]);
+      for (let i = 0; i < items.length; i++) stack.push([items[i], items, i]);
     }
-    for (const key of objects) {
-      if (value[key] != null) stack.push(value[key]);
+    for (const name of objects) {
+      if (value[name] != null) stack.push([value[name], value, name]);
     }
   }
-  return changed;
+  if (
+    protocol === "anthropic" &&
+    left &&
+    !kept &&
+    data.type === "message" &&
+    data.stop_reason === "tool_use"
+  ) {
+    data.stop_reason = "end_turn";
+  }
+  return { changed, kept, left };
 }
 
 function position(value) {
@@ -178,13 +288,24 @@ function chatBuffer(checkName) {
     }
     return pending.get(index);
   }
-  function complete(state) {
+  // Choices that streamed text, and those whose every call was left out
+  // (whose later "tool_calls" finish is a stop).
+  const wrote = new Set();
+  const ended = new Set();
+  function complete(state, index) {
     const delta = {};
     if (state.calls.size) {
       delta.tool_calls = [...state.calls].sort(([a], [b]) => a - b).map(([, value]) => value);
     }
     if (state.legacy) delta.function_call = state.legacy;
-    checkChatMessage(delta, checkName);
+    const { notes } = checkChatMessage(delta, checkName);
+    if (notes.length) {
+      delta.tool_calls?.forEach((call, i) => {
+        call.index = i;
+      });
+      delta.content = (wrote.has(index) ? "\n\n" : "") + notes.join("\n\n");
+      if (!hasCalls(delta)) ended.add(index);
+    }
     return delta;
   }
   function remove(index) {
@@ -201,11 +322,12 @@ function chatBuffer(checkName) {
       bytes = 0;
     },
     apply(data) {
-      let changed = checkSnapshots(data, "chat", checkName);
+      let { changed } = checkSnapshots(data, "chat", checkName);
       const choices = list(data.choices);
       for (const choice of choices) {
         const delta = choice.delta;
         if (!object(delta)) continue;
+        if (typeof delta.content === "string" && delta.content) wrote.add(position(choice.index));
         if (delta.tool_calls == null && delta.function_call == null) continue;
         changed = true;
         const state = stateFor(position(choice.index), data);
@@ -234,10 +356,20 @@ function chatBuffer(checkName) {
         const index = position(choice.index);
         const state = pending.get(index);
         if (!state) continue;
-        choice.delta = { ...choice.delta, ...complete(state) };
+        const own = object(choice.delta) ? choice.delta : {};
+        const delta = complete(state, index);
+        if (typeof own.content === "string" && delta.content)
+          delta.content = own.content + delta.content;
+        choice.delta = { ...own, ...delta };
         remove(index);
         changed = true;
       }
+      for (const choice of choices) {
+        if (callFinish.has(choice.finish_reason) && ended.has(position(choice.index))) {
+          choice.finish_reason = "stop";
+          changed = true;
+        }
+      }
       if (!changed) return { data, changed: false };
       data.choices = choices.filter(
         (choice) =>
@@ -251,7 +383,7 @@ function chatBuffer(checkName) {
       if (!pending.size) return null;
       const choices = [...pending]
         .sort(([a], [b]) => a - b)
-        .map(([index, state]) => ({ index, delta: complete(state), finish_reason: null }));
+        .map(([index, state]) => ({ index, delta: complete(state, index), finish_reason: null }));
       const metadata = pending.values().next().value.metadata;
       pending.clear();
       bytes = 0;
@@ -260,6 +392,99 @@ function chatBuffer(checkName) {
   };
 }
 
+// snapshotStream checks a Responses or Messages stream event by event. A
+// call left out is streamed as text in its place: its item or block starts
+// as text carrying the note, and its arguments are never sent. A message
+// whose every call was left out stops as a turn's end, not as tool use.
+function snapshotStream(protocol, checkName) {
+  const left = new Map(); // output_index or content block index → true
+  const leftIDs = new Set(); // Responses item ids left out
+  let kept = 0;
+  let dropped = 0;
+  return {
+    apply(data, type) {
+      if (protocol === "responses") {
+        const item = data.item;
+        if (
+          type === "response.output_item.added" &&
+          object(item) &&
+          item.type === "function_call" &&
+          checkName(item.name) == null
+        ) {
+          const note = droppedNote(item.name);
+          const message = inPlaceOf(protocol, item, note);
+          left.set(data.output_index, true);
+          leftIDs.add(message.id);
+          if (typeof item.id === "string") leftIDs.add(item.id);
+          dropped++;
+          const where = { item_id: message.id, output_index: data.output_index, content_index: 0 };
+          const part = { type: "output_text", text: "", annotations: [] };
+          return {
+            changed: true,
+            data: { ...data, item: { ...message, status: "in_progress", content: [] } },
+            extra: [
+              { type: "response.content_part.added", ...where, part },
+              { type: "response.output_text.delta", ...where, delta: note },
+              { type: "response.output_text.done", ...where, text: note },
+              { type: "response.content_part.done", ...where, part: { ...part, text: note } },
+            ],
+          };
+        }
+        if (
+          typeof type === "string" &&
+          type.startsWith("response.function_call_arguments.") &&
+          ((data.output_index != null && left.has(data.output_index)) || leftIDs.has(data.item_id))
+        ) {
+          return { changed: true, data: null };
+        }
+      } else {
+        if (type === "message_start") {
+          left.clear();
+          kept = 0;
+          dropped = 0;
+        }
+        const block = data.content_block;
+        if (
+          type === "content_block_start" &&
+          object(block) &&
+          isCall(protocol, block) &&
+          checkName(block.name) == null
+        ) {
+          left.set(data.index, true);
+          dropped++;
+          return {
+            changed: true,
+            data: { ...data, content_block: { type: "text", text: "" } },
+            extra: [
+              {
+                type: "content_block_delta",
+                index: data.index,
+                delta: { type: "text_delta", text: droppedNote(block.name) },
+              },
+            ],
+          };
+        }
+        if (type === "content_block_delta" && left.has(data.index))
+          return { changed: true, data: null };
+        if (
+          type === "message_delta" &&
+          object(data.delta) &&
+          data.delta.stop_reason === "tool_use" &&
+          dropped &&
+          !kept
+        ) {
+          data.delta.stop_reason = "end_turn";
+          return { changed: true, data };
+        }
+      }
+      const checked = checkSnapshots(data, protocol, checkName);
+      kept += checked.kept;
+      dropped += checked.left;
+      return { changed: checked.changed, data };
+    },
+  };
+}
+
 function parseJSON(text) {
   let value;
   try {
@@ -399,9 +624,89 @@ async function* framesFrom(reader) {
   }
 }
 
-function guardedStream(response, protocol, checkName) {
-  const reader = response.body?.getReader();
+// A Chat stream Zen closed before its [DONE] (#91: space-bunny-free, about
+// 0.1% of turns) is ended as a turn cut short when it has said something
+// and no tool call of it is pending: each choice still open gets a note
+// saying so and a stop, then [DONE]. Failing it threw away the reasoning
+// and text the agent already had, and a Chat reply through Zen can't be
+// asked to go on from there. A pending call's arguments may be half
+// written, and a reply that said nothing is an empty one, so both still
+// fail, as does one collapsed for a client that doesn't stream, which can
+// still be asked again. Anthropic and Responses streams cut short fail
+// too: magpie's gateway tells such a reply from a whole one itself
+// (#370), and goes on with it where the upstream can (an Anthropic one),
+// which a made-up end here would stop.
+export const cutShortNote =
+  "(The reply was cut short: Zen closed the stream before it finished. Ask again to go on.)";
+
+function chatTrack() {
+  const open = new Set();
+  const finished = new Set();
+  const wrote = new Set();
+  let said = false;
+  let meta = null;
+  return {
+    see(data) {
+      if (!object(data)) return;
+      meta = {
+        id: data.id ?? meta?.id,
+        created: data.created ?? meta?.created,
+        model: data.model ?? meta?.model,
+      };
+      for (const choice of Array.isArray(data.choices) ? data.choices : []) {
+        if (!object(choice)) continue;
+        const index = position(choice.index);
+        const delta = object(choice.delta) ? choice.delta : {};
+        for (const key of ["content", "reasoning_content", "reasoning"]) {
+          if (typeof delta[key] === "string" && delta[key]) said = true;
+        }
+        if (typeof delta.content === "string" && delta.content) wrote.add(index);
+        if (choice.finish_reason != null) {
+          finished.add(index);
+          open.delete(index);
+        } else if (!finished.has(index)) open.add(index);
+      }
+    },
+    // ending answers the frames that end the reply as cut short, or null
+    // when it can't be.
+    ending() {
+      if (!said) return null;
+      const choices = [...open]
+        .sort((a, b) => a - b)
+        .map((index) => ({
+          index,
+          delta: { content: (wrote.has(index) ? "\n\n" : "") + cutShortNote },
+          finish_reason: "stop",
+        }));
+      const head = {
+        id: meta?.id ?? "chatcmpl-cut-short",
+        object: "chat.completion.chunk",
+        created: meta?.created ?? Math.floor(Date.now() / 1000),
+        model: meta?.model ?? "",
+      };
+      return (choices.length ? encodeEvent({ ...head, choices }) : "") + "data: [DONE]\n\n";
+    },
+  };
+}
+
+function guardedStream(response, protocol, checkName, endCutShort) {
+  const source = response.body?.getReader();
+  // What came before a stream cut short, for its error to say (#91).
+  let bytes = 0;
+  let events = 0;
+  let replyID;
+  const reader = source && {
+    async read() {
+      const result = await source.read();
+      if (result.value) bytes += result.value.byteLength;
+      return result;
+    },
+    releaseLock: () => source.releaseLock(),
+    cancel: (reason) => source.cancel(reason),
+  };
   const chat = protocol === "chat" ? chatBuffer(checkName) : null;
+  const track = chat && endCutShort ? chatTrack() : null;
+  const snapshots = chat ? null : snapshotStream(protocol, checkName);
   let frames = reader ? framesFrom(reader) : null;
   let completed = false;
   let stopped = false;
@@ -433,8 +738,25 @@ function guardedStream(response, protocol, checkName) {
             const next = frames ? await frames.next() : { done: true };
             if (stopped) return;
             if (next.done) {
-              if (!completed || chat?.size)
-                throw new GuardError("Upstream SSE ended without a completion marker");
+              const ending = !completed && !chat?.size ? track?.ending() : null;
+              if (ending) {
+                stopped = true;
+                release();
+                controller.enqueue(encoder.encode(ending));
+                controller.close();
+                return;
+              }
+              if (!completed || chat?.size) {
+                const came = [
+                  replyID ? `reply ${String(replyID).slice(0, 128)}` : "",
+                  `${events} event${events === 1 ? "" : "s"}`,
+                  `${bytes} bytes received`,
+                  chat?.size ? "a tool call unfinished" : "",
+                ].filter(Boolean);
+                throw new GuardError(
+                  `Upstream SSE ended without a completion marker (${came.join(", ")})`,
+                );
+              }
               stopped = true;
               release();
               controller.close();
@@ -453,8 +775,10 @@ function guardedStream(response, protocol, checkName) {
               controller.enqueue(encoder.encode((final ? encodeEvent(final) : "") + frame.raw));
               return;
             }
+            events++;
             const data = frame.name === "error" ? null : parseJSON(frame.text);
             const type = data?.type ?? frame.name;
+            replyID = data?.id ?? data?.message?.id ?? data?.response?.id ?? replyID;
             if (
               frame.name === "error" ||
               type === "error" ||
@@ -473,23 +797,19 @@ function guardedStream(response, protocol, checkName) {
               controller.close();
               return;
             }
-            let changed;
-            let result = data;
-            if (chat) {
-              const checked = chat.apply(data);
-              changed = checked.changed;
-              result = checked.data;
-            } else {
-              changed = checkSnapshots(data, protocol, checkName);
-            }
+            const checked = chat ? chat.apply(data) : snapshots.apply(data, type);
+            const { changed, data: result, extra = [] } = checked;
+            if (result) track?.see(result);
             if (
               (protocol === "responses" &&
                 ["response.completed", "response.incomplete"].includes(type)) ||
               (protocol === "anthropic" && type === "message_stop")
             )
               completed = true;
-            if (result) {
-              controller.enqueue(encoder.encode(changed ? rewrite(frame, result) : frame.raw));
+            if (result || extra.length) {
+              const own = !result ? "" : changed ? rewrite(frame, result) : frame.raw;
+              const added = extra.map((value) => encodeEvent(value, value.type)).join("");
+              controller.enqueue(encoder.encode(own + added));
               return;
             }
           }
@@ -527,7 +847,11 @@ function guardedStream(response, protocol, checkName) {
   );
 }
 
-export async function guardToolResponse(response, protocol, policy) {
+// options.endCutShort lets a Chat stream cut short end as one (#91): for a
+// client that streams, which has the reply's start already. A reply
+// collapsed for a client that doesn't stream fails instead, so it can be
+// asked again before anything reached the client.
+export async function guardToolResponse(response, protocol, policy, options = {}) {
   if (!response.ok) return response;
   if (!["chat", "responses", "anthropic"].includes(protocol))
     throw new TypeError(`Unsupported protocol: ${protocol}`);
@@ -535,7 +859,7 @@ export async function guardToolResponse(response, protocol, policy) {
   const headers = headersFor(response);
   const contentType = response.headers.get("content-type")?.split(";", 1)[0].trim().toLowerCase();
   if (contentType === "text/event-stream") {
-    return new Response(guardedStream(response, protocol, checkName), {
+    return new Response(guardedStream(response, protocol, checkName, options.endCutShort === true), {
       status: response.status,
       statusText: response.statusText,
       headers,