opencode-zen-freex 0.2.8 → 0.2.9

package/provider.mjs

@@ -10,7 +10,7 @@ import {
   parseProtocolDocs,
 } from "./models.mjs";
 import { observeRouteStatement } from "./limits.mjs";
-import { collapseResponse } from "./stream.mjs";
+import { STALE_BODY_HEADERS, collapseResponse } from "./stream.mjs";
 import { guardToolResponse } from "./tool-response.mjs";
 
 // Zen moved behind opencode.ai/inference; everything under /zen/ answers 403
@@ -36,12 +36,28 @@ const PLACEHOLDER =
 // says which one it is, and that answer is above whatever floor Zen is holding,
 // so it is passed through; otherwise the generation is taken from the tools
 // the request actually carries, which is what the gate compares anyway.
-const RELEASE = /^opencode\/(?:latest|stable|beta)\/\d[^/]*\/[^/]+$/;
+//
+// Both current shapes answer to this: 1.x sends
+// `opencode/<version> ai-sdk/provider-utils/<version> runtime/bun/<version>`,
+// 2.x sends `opencode/<channel>/<version>/<client>`. Testing only the channel
+// form — which is what this did — silently re-pinned every 1.x host to the
+// version in fingerprint.json, so a host newer than the floor was told, on a
+// 426 or a refusal, that this package was too old to update. A host's own
+// answer is passed through whichever shape it comes in.
+//
+// The version has to start at 1-9 in both: that is what tells a release from a
+// development build (`opencode/dev/0.0.0-dev-1/cli`), whose word is not one Zen
+// would serve and so is not taken.
+const RELEASE = /^opencode\/(?:[a-z-]+\/[1-9][^/]*\/[^/]+|[1-9][^ ]*\s+ai-sdk\/\S+\s+\S+)$/;
 
-function agentForRequest(protocol, tools, given) {
+// The generation and the agent belong together: the agent says which OpenCode
+// this is, and the generation is what the tools in the request say. Deciding
+// them in one place is what `normalizeTools` reports back, so the User-Agent
+// cannot describe a generation the body does not.
+function agentForRequest(protocol, generation, given) {
   const said = given?.get("user-agent");
   if (said && RELEASE.test(said)) return said;
-  return agentFor(generationOf(tools) ?? DEFAULT_GENERATION, protocol);
+  return agentFor(generation, protocol);
 }
 
 // The complete set of headers that leaves here, and nothing else: one owner for
@@ -83,6 +99,21 @@ export function outboundHeaders({
   return headers;
 }
 
+// The headers a reply's bytes are described by, for a reply whose body is
+// written again. A response rebuilt from a body this package read no longer is
+// the response that arrived: a length, an encoding and the validators a cache
+// or a conditional request compares against all describe the old bytes only.
+// `stream.mjs` keeps the list, and the two places that write an upstream body
+// again (here, and `tool-response.mjs`) must both use it — a body re-served
+// under the upstream's `content-encoding` cannot be read by the caller at all,
+// which for a refusal is the one message a user has to be able to read.
+function rewrittenHeaders(response) {
+  const headers = new Headers(response.headers);
+  for (const name of STALE_BODY_HEADERS) headers.delete(name);
+  headers.set("content-type", "application/json");
+  return headers;
+}
+
 // 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.
@@ -133,9 +164,16 @@ function normalizeTools(body, protocol) {
   const nameOf = (tool) => tool?.function?.name ?? tool?.name;
   const present = new Set(body.tools.map(nameOf));
   const declared = new Set([...present].filter((value) => typeof value === "string"));
-  if (protocol === "chat" && Array.isArray(body.functions)) {
-    for (const tool of body.functions) if (typeof tool?.name === "string") declared.add(tool.name);
-  }
+  // The legacy top-level `functions` array is the older way of declaring the
+  // same tools, and one a chat host may still use. Its names are declarations,
+  // so they count as declared — and, since they are not in `body.tools`, they
+  // are also remembered as "do not stand in for this name": the fill loop
+  // below looks at where a name already sits, and a name that only arrived
+  // through `functions` has no index there. Without this the same tool would go
+  // out twice, which is what the note on `nameOf` says must not happen.
+  const legacy = Array.isArray(body.functions) && protocol === "chat" ? body.functions : [];
+  for (const tool of legacy) if (typeof tool?.name === "string") declared.add(tool.name);
+  const declaredElsewhere = new Set(legacy.map((tool) => tool?.name));
   // Zen takes a request for one generation of OpenCode or the other, and the tools
   // it carries say which: `shell` is 2.x, `bash` is 1.x. Names move far less
   // often than descriptions do, so this survives a rewording that a pinned
@@ -169,6 +207,9 @@ function normalizeTools(body, protocol) {
     // tokens of a tool it will not call, and they are the first thing a
     // tightened check would otherwise find missing.
     if (!profile.required.includes(name)) continue;
+    // Declared through `functions` rather than `tools`: this host does have the
+    // tool, so it is not one to stand in for.
+    if (declaredElsewhere.has(name)) continue;
     filled.push(name);
     // A tool added here has nothing behind it: the agent has no such tool and
     // a call to it is dropped. Describing it as OpenCode describes it is what
@@ -205,19 +246,31 @@ function shapeOf(definition, protocol) {
 // sends apart from the tool wording is what Zen expects — the endpoint, the
 // shape of the User-Agent, both session headers — so a refusal this far in is
 // about the wording, and this says so, and says which wording went out.
-async function explain(response, toolPolicy) {
-  if (response.status !== 403 && response.status !== 426) return response;
-  const text = await response.text().catch(() => "");
-  // A 403 that is not Zen's free tier is somebody else's; it is left as sent.
-  if (response.status === 403 && !text.includes("FreeTierError"))
-    return new Response(text, response);
+//
+// The body arrives already read: on this path the refusal has to be read for
+// the window it may name before the message that replaces it is built (see
+// limits.mjs), and a response body can only be read once. So the text is passed
+// in rather than read here, and every reply this function rebuilds is built
+// under headers that describe the bytes it returns. A refusal that is not this
+// route's — or one whose body could not be read at all — is handed on as it
+// arrived.
+function explain(text, source, toolPolicy) {
+  if (source.status !== 403 && source.status !== 426) return source;
+  // Zen's free tier names itself in the body. Without the body there is no way
+  // to tell its refusal from anybody else's 403, and this is an error path on a
+  // request whose caller is waiting, so the answer is passed on rather than
+  // guessed at.
+  if (text === null) return source;
+  // A 403 that is not Zen's free tier is somebody else's; it is left as sent —
+  // its bytes are what arrived, and so are the headers describing them.
+  if (source.status === 403 && !text.includes("FreeTierError")) return source;
   const profile = PROFILES[toolPolicy.generation];
   const names = Object.keys(profile.tools).join(", ");
   const { filled } = toolPolicy;
   // 426 is not a refusal of the wording: it is this plugin presenting itself as
   // an OpenCode older than Zen accepts, which only a newer copy of it answers.
   const message =
-    response.status === 426
+    source.status === 426
       ? `OpenCode Zen answered 426 Upgrade Required: this plugin presents itself as OpenCode ${profile.agent.opencode} and Zen now wants a newer one. Update the plugin, or run inside a newer OpenCode.`
       : [
           "OpenCode Zen's free tier refused this request as not coming from OpenCode.",
@@ -230,9 +283,9 @@ async function explain(response, toolPolicy) {
   return new Response(
     JSON.stringify({
       type: "error",
-      error: { type: response.status === 426 ? "upgrade_required" : "FreeTierError", message },
+      error: { type: source.status === 426 ? "upgrade_required" : "FreeTierError", message },
     }),
-    { status: response.status, statusText: response.statusText, headers: response.headers },
+    { status: source.status, statusText: source.statusText, headers: rewrittenHeaders(source) },
   );
 }
 
@@ -245,12 +298,19 @@ let counter = 0;
 // 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).
+//
+// The counter is the low 12 bits of the id and realSessionID reads it back as
+// a counter, so it is kept inside the 4 bits OpenCode's own counter lives in
+// and wraps there rather than carrying into the time field: the 16th id of one
+// millisecond would otherwise say it was made later than it was, and stop
+// reading as an id OpenCode could have made. A millisecond that produces
+// sixteen ids is a burst, and every id of it still has the shape Zen checks.
 export function opencodeID(prefix, descending, now = Date.now()) {
   if (now !== lastStamp) {
     lastStamp = now;
     counter = 0;
   }
-  counter++;
+  counter = counter >= 15 ? 1 : counter + 1;
   const current = BigInt(now) * 0x1000n + BigInt(counter);
   const value = (descending ? ~current : current) & 0xffffffffffffn;
   const random = randomBytes(14);
@@ -284,13 +344,18 @@ export function sessionID(headers, body) {
       break;
     }
   }
-  if (!signal && typeof body.metadata?.session_id === "string") signal = body.metadata.session_id;
+  if (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;
+    // Nothing names this conversation: no session header, no metadata, and no
+    // user message to key one by. There is no identity to keep for the next
+    // turn, so this one gets an id of its own rather than being folded into
+    // whichever conversation happened to arrive first — but it is still an id
+    // of OpenCode's shape, because that shape is what the tier checks.
     if (!first) return opencodeID("ses", true);
     signal = JSON.stringify(first);
   }
@@ -456,7 +521,10 @@ async function server(_input, options = {}) {
             const project = _input?.project;
             const headers = outboundHeaders({
               session,
-              agent: agentForRequest(protocol, body.tools, given),
+              // The generation the tools in this request say, which is the one
+              // normalizeTools has already decided: deciding it twice is how a
+              // User-Agent and a body come to describe different generations.
+              agent: agentForRequest(protocol, toolPolicy.generation, given),
               protocol,
               given,
               project:
@@ -474,10 +542,31 @@ async function server(_input, options = {}) {
             // it has to be read before explain() replaces the body. See
             // limits.mjs: an under-declared window is never refused, it is just
             // quietly never used.
-            await observeRouteStatement(body.model, response);
-            const guarded = await guardToolResponse(await explain(response, toolPolicy), protocol, toolPolicy, {
-              endCutShort: streaming,
+            //
+            // A response body can only be read once, so what the limits reader
+            // took is handed on as the response the rest of the path works with:
+            // the bytes are the ones that arrived, under headers that still
+            // describe them, and nothing re-reads a body that is already gone.
+            // A response the reader did not consume is used as it arrived.
+            const observed = await observeRouteStatement(body.model, response, undefined, {
+              // The caller's own cancellation reaches this read as well: a host
+              // that has given up is not waiting for a number out of a refusal.
+              signal: request.signal,
             });
+            const answered =
+              observed === undefined
+                ? response
+                : new Response(observed.text, {
+                    status: response.status,
+                    statusText: response.statusText,
+                    headers: response.headers,
+                  });
+            const guarded = await guardToolResponse(
+              explain(observed?.text ?? null, answered, toolPolicy),
+              protocol,
+              toolPolicy,
+              { endCutShort: streaming },
+            );
             return streaming ? guarded : collapseResponse(guarded, protocol);
           },
         };

package/stream.mjs

@@ -1,4 +1,8 @@
-const MAX_BYTES = 32 * 1024 * 1024;
+// The one byte limit a reply held in memory is read through: a streamed one
+// event by event, a whole one in one read. Exported because tool-response.mjs
+// reads the same bytes through the same limit and names the same number in its
+// failures — a second copy of it is a second thing to keep in step.
+export const MAX_BYTES = 32 * 1024 * 1024;
 
 // The headers that describe the bytes a reply arrived as. A reply whose body
 // is written again — a stream collapsed into one JSON document, or a guarded
@@ -57,6 +61,39 @@ function appendFunction(target, delta) {
   }
 }
 
+// The rule every streamed text field follows: a .delta appends to what came
+// before it, a .done replaces it with the whole text. Written once, so a
+// protocol tweak is applied to all of them together rather than five times.
+function applyText(target, field, value, isDelta) {
+  if (isDelta) target[field] = (target[field] ?? "") + (value ?? "");
+  else if (value !== undefined) target[field] = value;
+}
+
+// How much of a streamed reply a snapshot carries, counted over the fields a
+// stream fills in.
+function weight(snapshot, fields) {
+  let total = 0;
+  for (const field of fields) {
+    const value = snapshot?.[field];
+    if (typeof value === "string") total += value.length;
+    else if (Array.isArray(value)) total += value.length;
+    else if (value && typeof value === "object") total += Object.keys(value).length;
+  }
+  return total;
+}
+
+// Whether a snapshot may stand in for what was accumulated. An upstream puts
+// snapshots beside the deltas they describe — a repeated response.created, a
+// message_start whose block has not been filled in, a terminal response — and
+// one that carries nothing where the accumulation has content is a partial
+// view of it rather than a newer one: taking it would discard what the stream
+// already delivered. One that does carry the collection settles it, which is
+// how response.output_item.done and a whole terminal response replace
+// accumulated arguments with the complete ones.
+function carries(snapshot, accumulated, fields) {
+  return weight(snapshot, fields) > 0 || weight(accumulated, fields) === 0;
+}
+
 function chatAccumulator() {
   const body = { object: "chat.completion", choices: [] };
   const choices = new Map();
@@ -99,7 +136,11 @@ function chatAccumulator() {
           }
           if (fragment.function) appendFunction(call.function, fragment.function);
         }
-        if (part.finish_reason != null) choice.finish_reason = part.finish_reason;
+        // Both null and undefined are "this chunk carried no finish reason";
+        // a loose comparison is the only way to say that in one test, and the
+        // project's rules do not allow it.
+        if (part.finish_reason !== null && part.finish_reason !== undefined)
+          choice.finish_reason = part.finish_reason;
         if (part.logprobs) {
           choice.logprobs ??= {};
           for (const [key, value] of Object.entries(part.logprobs)) {
@@ -124,13 +165,28 @@ function responsesAccumulator() {
   let body = { object: "response", output: [] };
   let final;
   const output = new Map();
+  // The fields a streamed item fills in: a message its content, a call its
+  // arguments, a reasoning item its summary.
+  const fields = ["content", "arguments", "summary", "text"];
   // The slot a frame belongs to: the output_index it carries, or the slot
-  // of the item it names when the upstream left output_index out.
+  // of the item it names when the upstream left output_index out. A frame
+  // naming an item the stream never opened has no slot at all — slot 0 is
+  // only for a frame that names nothing, which a stream that never indexed
+  // its items means as the first one. Merging an unknown item into slot 0
+  // was measured handing a function_call there the text of a message.
   function slot(data, id) {
     if (data.output_index !== undefined) return index(data.output_index);
-    const position = id ? [...output].find(([, value]) => value.id === id)?.[0] : undefined;
+    if (id === undefined || id === null || id === "") return index(undefined);
+    const position = [...output].find(([, value]) => value.id === id)?.[0];
+    if (position === undefined)
+      throw new Error("Upstream frame names an unknown item without an output index");
     return index(position);
   }
+  // A snapshot replaces the item in its slot only when it is a whole view of
+  // it; a partial one leaves what the deltas delivered standing.
+  function keep(position, value) {
+    if (carries(value, output.get(position), fields)) output.set(position, value);
+  }
   function item(data, type = "message") {
     const position = slot(data, data.item_id);
     if (!output.has(position)) {
@@ -148,11 +204,14 @@ function responsesAccumulator() {
       if (type === "response.created" || type === "response.in_progress") {
         if (data.response) {
           body = { ...body, ...data.response };
+          // A snapshot that carries an item where the reply already has one
+          // adds only what it actually carries: the accumulated items stand
+          // against an output list it does not carry, or carries empty.
           for (const [position, value] of (data.response.output ?? []).entries())
-            output.set(position, value);
+            keep(position, value);
         }
       } else if (type === "response.output_item.added" || type === "response.output_item.done") {
-        if (data.item) output.set(slot(data, data.item.id), data.item);
+        if (data.item) keep(slot(data, data.item.id), data.item);
       } else if (type === "response.content_part.added" || type === "response.content_part.done") {
         const value = item(data);
         value.content ??= [];
@@ -170,15 +229,15 @@ function responsesAccumulator() {
         const part = (value.content[index(data.content_index)] ??= refusal
           ? { type: "refusal", refusal: "" }
           : { type: "output_text", text: "", annotations: [] });
-        if (type.endsWith(".delta")) part[field] = (part[field] ?? "") + (data.delta ?? "");
-        else if (data[field] !== undefined) part[field] = data[field];
+        const isDelta = type.endsWith(".delta");
+        applyText(part, field, isDelta ? data.delta : data[field], isDelta);
       } else if (
         type === "response.function_call_arguments.delta" ||
         type === "response.function_call_arguments.done"
       ) {
         const value = item(data, "function_call");
-        if (type.endsWith(".delta")) value.arguments = (value.arguments ?? "") + (data.delta ?? "");
-        else if (data.arguments !== undefined) value.arguments = data.arguments;
+        const isDelta = type.endsWith(".delta");
+        applyText(value, "arguments", isDelta ? data.delta : data.arguments, isDelta);
       } else if (
         type === "response.reasoning_summary_part.added" ||
         type === "response.reasoning_summary_part.done"
@@ -189,14 +248,18 @@ function responsesAccumulator() {
       } else if (/^response\.reasoning_(summary_)?text\.(delta|done)$/.test(type)) {
         const value = item(data, "reasoning");
         const summary = type.includes("summary");
-        const field = summary ? "summary" : "content";
-        value[field] ??= [];
-        const part = (value[field][index(summary ? data.summary_index : data.content_index)] ??= {
+        const collection = summary ? "summary" : "content";
+        value[collection] ??= [];
+        const at = index(summary ? data.summary_index : data.content_index);
+        const part = (value[collection][at] ??= {
           type: summary ? "summary_text" : "reasoning_text",
           text: "",
         });
-        if (type.endsWith(".delta")) part.text += data.delta ?? "";
-        else if (data.text !== undefined) part.text = data.text;
+        // A summary's whole text arrives in `summary` and a reasoning text's
+        // in `text`. Reading `text` for a summary lost a done event that had
+        // no delta before it (measured: the summary came back empty).
+        const isDelta = type.endsWith(".delta");
+        applyText(part, "text", isDelta ? data.delta : summary ? data.summary : data.text, isDelta);
       } else if (type === "response.reasoning_content.delta") {
         body.reasoning_content = (body.reasoning_content ?? "") + (data.delta ?? "");
       } else if (type === "response.completed" || type === "response.incomplete") {
@@ -209,9 +272,23 @@ function responsesAccumulator() {
       if (data.usage) body.usage = { ...body.usage, ...data.usage };
     },
     finish() {
-      if (final) return final;
-      body.output = sorted(output);
-      return body;
+      if (!final) {
+        body.output = sorted(output);
+        return body;
+      }
+      const kept = sorted(output);
+      // A terminal object that carries no output of its own — absent, or
+      // empty while the stream accumulated some — is not a whole view of the
+      // reply: returning it verbatim discards every delta already delivered,
+      // and the client reads a 200 as a model that said nothing. The
+      // accumulation stands in for the collection it lost; everything else
+      // about the terminal is what the upstream said last, and comes back
+      // exactly as it arrived.
+      const whole = Array.isArray(final.output)
+        ? final.output.length > 0
+        : final.output !== null && final.output !== undefined;
+      if (whole || !kept.length || Array.isArray(final)) return final;
+      return { ...final, output: kept };
     },
   };
 }
@@ -226,12 +303,19 @@ function anthropicAccumulator() {
   };
   const blocks = new Map();
   const argumentsJSON = new Map();
+  // The fields a Messages block fills in: its text, thinking, signature, or
+  // the input a tool call opened with.
+  const fields = ["text", "thinking", "signature", "partial_json", "input"];
   return {
     apply(data, type) {
       if (type === "message_start") {
         body = { ...body, ...data.message };
+        // A message_start that repeats beside the deltas it opened, or one
+        // whose block has not been filled in yet, is a partial view of the
+        // reply: a block that carries nothing where the accumulated one has
+        // content leaves it standing.
         for (const [position, block] of (data.message?.content ?? []).entries())
-          blocks.set(position, block);
+          if (carries(block, blocks.get(position), fields)) blocks.set(position, block);
       } else if (type === "content_block_start") {
         blocks.set(index(data.index), data.content_block);
       } else if (type === "content_block_delta") {
@@ -244,7 +328,7 @@ function anthropicAccumulator() {
           thinking_delta: "thinking",
           signature_delta: "signature",
         }[delta.type];
-        if (field) block[field] = (block[field] ?? "") + (delta[field] ?? "");
+        if (field) applyText(block, field, delta[field], true);
         if (delta.type === "input_json_delta") {
           argumentsJSON.set(
             position,
@@ -252,7 +336,13 @@ function anthropicAccumulator() {
           );
         }
       } else if (type === "message_delta") {
-        Object.assign(body, data.delta);
+        // Only the fields a message_delta is defined to carry are taken from
+        // it. Object.assign copied with [[Set]] semantics: a "__proto__" key
+        // in the upstream's delta re-parented the message being accumulated,
+        // and any other key silently overwrote its id, role, type or content.
+        for (const field of ["stop_reason", "stop_sequence"]) {
+          if (data.delta?.[field] !== undefined) body[field] = data.delta[field];
+        }
         if (data.usage) body.usage = { ...body.usage, ...data.usage };
       }
     },
@@ -312,7 +402,15 @@ export async function collapseResponse(response, protocol) {
     }
     if (!text.trim()) return;
     if (text.trim() === "[DONE]") {
+      // [DONE] is what ends a Chat stream, and it is a valid end-of-stream
+      // sentinel for a Responses or Messages one that has already reported
+      // its own terminal event (response.completed, response.incomplete,
+      // message_stop) — a gateway in front of the upstream may append it.
+      // Before that event it is an ending the protocol never reported, so
+      // what was streamed is not a whole reply: the guard refuses the same
+      // bytes with the same words rather than reading them as a success.
       if (protocol === "chat") completed = true;
+      else if (!completed) failure = "Unexpected upstream completion marker";
       return;
     }
     let data;

package/tool-response.mjs

@@ -1,7 +1,7 @@
-import { STALE_BODY_HEADERS } from "./stream.mjs";
+import { MAX_BYTES, STALE_BODY_HEADERS } from "./stream.mjs";
 
-const MAX_BYTES = 32 * 1024 * 1024;
-// The limit as a failure's message names it, from the one place it is set.
+// The limit as a failure's message names it, from the one place it is set:
+// stream.mjs owns the number, and this guard reads the same bytes through it.
 const LIMIT = `${MAX_BYTES / (1024 * 1024)} MiB`;
 const encoder = new TextEncoder();
 
@@ -301,7 +301,10 @@ function chatBuffer(checkName) {
     return pending.get(index);
   }
   // Choices that streamed text, and those whose every call was left out
-  // (whose later "tool_calls" finish is a stop).
+  // (whose later "tool_calls" finish is a stop). The second is per round: a
+  // later round that buffers a call for the same choice is judged on what it
+  // holds, not on the round before it, so the mark is dropped as soon as that
+  // call arrives.
   const wrote = new Set();
   const ended = new Set();
   function complete(state, index) {
@@ -320,6 +323,14 @@ function chatBuffer(checkName) {
     }
     return delta;
   }
+  // What a choice the buffer flushes at [DONE] ended as: tool use when the
+  // delta it publishes carries calls, the legacy field when it carries that,
+  // and a plain stop otherwise.
+  function ending(delta) {
+    if (delta.tool_calls?.length) return "tool_calls";
+    if (delta.function_call) return "function_call";
+    return "stop";
+  }
   function remove(index) {
     const state = pending.get(index);
     if (state) bytes -= state.bytes;
@@ -331,6 +342,10 @@ function chatBuffer(checkName) {
     },
     clear() {
       pending.clear();
+      // Everything this buffer holds, not only the bytes: a cleared buffer
+      // has no round to judge.
+      wrote.clear();
+      ended.clear();
       bytes = 0;
     },
     apply(data) {
@@ -342,7 +357,12 @@ function chatBuffer(checkName) {
         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);
+        // A call buffered now opens a round of its own for this choice: a
+        // choice that finished as a plain stop because every call of an
+        // earlier round was left out is judged again on what this one holds.
+        const at = position(choice.index);
+        ended.delete(at);
+        const state = stateFor(at, data);
         for (const fragment of list(delta.tool_calls)) {
           if (!object(fragment) || (fragment.type != null && fragment.type !== "function")) {
             throw new GuardError("Unsupported upstream tool delta");
@@ -393,9 +413,16 @@ function chatBuffer(checkName) {
     },
     finish() {
       if (!pending.size) return null;
-      const choices = [...pending]
-        .sort(([a], [b]) => a - b)
-        .map(([index, state]) => ({ index, delta: complete(state, index), finish_reason: null }));
+      const choices = [...pending].sort(([a], [b]) => a - b).map(([index, state]) => {
+        const delta = complete(state, index);
+        // The case this buffer exists for is an upstream that closes with
+        // [DONE] before sending a finish chunk: the calls it buffered are
+        // published here, and the choice has to say the turn ended in tool
+        // use. A null reason reads as no ending at all, and "stop" as a plain
+        // one — either way a client keyed on finish_reason never runs a call
+        // it was handed.
+        return { index, delta, finish_reason: ending(delta) };
+      });
       const metadata = pending.values().next().value.metadata;
       pending.clear();
       bytes = 0;
@@ -515,7 +542,18 @@ async function readBounded(response) {
       parts.push(value);
     }
   } finally {
-    reader.releaseLock();
+    // Whatever ended the read — the limit, a malformed body, or the end of
+    // it — this body is never read again, so the reader is loosed and the
+    // stream cancelled. This was the one place in the package that abandoned
+    // a body without cancelling it (measured: no cancellation past the limit,
+    // and the source still pulled after the 502), which leaves an upstream
+    // writing into a socket nobody reads. The cancel's own failure is not
+    // swallowed, and the lock is released whether it threw or not.
+    try {
+      await reader.cancel();
+    } finally {
+      reader.releaseLock();
+    }
   }
   const all = new Uint8Array(bytes);
   let offset = 0;
@@ -809,9 +847,16 @@ function guardedStream(response, protocol, checkName, endCutShort) {
               return;
             }
             if (frame.name !== "error" && frame.text.trim() === "[DONE]") {
-              if (protocol !== "chat")
+              // [DONE] is what ends a Chat stream, and a valid end-of-stream
+              // sentinel for a Responses or Messages one that has already
+              // reported its own terminal event (response.completed,
+              // response.incomplete, message_stop) — a gateway in front of the
+              // upstream may append it. Before that event it claims an ending
+              // the protocol never reported, and the frame is refused; the
+              // collapse path reads the same bytes the same way.
+              if (protocol !== "chat" && !completed)
                 throw new GuardError("Unexpected upstream completion marker");
-              const final = chat.finish();
+              const final = chat ? chat.finish() : null;
               completed = true;
               controller.enqueue(encoder.encode((final ? encodeEvent(final) : "") + frame.raw));
               return;