mslxdff 0.1.132 → 0.1.134

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mslxdff",
-  "version": "0.1.132",
+  "version": "0.1.134",
   "description": "测试项目，请勿使用。",
   "type": "module",
   "bin": {

package/src/free-lane.js

@@ -0,0 +1,131 @@
+// zen 免费层"agent 形状"门禁（2026-09-18 上线，bisect 实测）：
+//   403 FreeTierError ≤ 请求必须同时满足：① stream:true ② tools 含 bash/edit/glob/grep/read 五个核心名。
+//   另 UA 版本需 ≥ opencode/1.18.0（低版本返回 426 UpgradeRequired，见 opencode-identity.js）。
+// 官方客户端自带这五个工具天然通过；-chat 直连（非流式、工具名不同）与裸 API 客户端需补形状。
+// 逃生阀：MSLXDFF_FREE_LANE=0 关闭（注入与强制流式都跳过），上游若撤门禁可回退。
+
+export const CORE_AGENT_TOOL_NAMES = ["bash", "edit", "glob", "grep", "read"];
+
+function laneDisabled(env = process.env) {
+  const raw = env.MSLXDFF_FREE_LANE;
+  if (raw === undefined || raw === null || raw === "") return false;
+  const s = String(raw).trim().toLowerCase();
+  return s === "0" || s === "false" || s === "off" || s === "no";
+}
+
+const chatTool = (name) => ({
+  type: "function",
+  function: { name, description: `The ${name} tool.`, parameters: { type: "object", properties: {} } },
+});
+
+const responsesTool = (name) => ({
+  type: "function",
+  name,
+  description: `The ${name} tool.`,
+  parameters: { type: "object", properties: {} },
+});
+
+function toolName(tool, responses) {
+  return responses ? tool?.name : tool?.function?.name;
+}
+
+/**
+ * 给免费层请求补 agent 形状（幂等，原地改 body）。
+ * @returns {{injected: string[], forcedStream: boolean, disabled: boolean}}
+ */
+export function ensureFreeLaneShape(body, { responses = false, env = process.env } = {}) {
+  if (!body || typeof body !== "object") return { injected: [], forcedStream: false, disabled: true };
+  if (laneDisabled(env)) return { injected: [], forcedStream: false, disabled: true };
+  const forcedStream = body.stream !== true;
+  body.stream = true;
+  const mk = responses ? responsesTool : chatTool;
+  const list = Array.isArray(body.tools) ? body.tools : [];
+  const have = new Set(list.map((t) => toolName(t, responses)).filter(Boolean));
+  const injected = CORE_AGENT_TOOL_NAMES.filter((n) => !have.has(n));
+  if (injected.length) body.tools = [...list, ...injected.map(mk)];
+  return { injected, forcedStream, disabled: false };
+}
+
+function mergeToolCall(target, idx, delta) {
+  const cur = target[idx] || (target[idx] = { index: idx, id: undefined, type: "function", function: { name: undefined, arguments: "" } });
+  if (delta?.id) cur.id = delta.id;
+  if (delta?.type) cur.type = delta.type;
+  if (delta?.function?.name) cur.function.name = delta.function.name;
+  if (delta?.function?.arguments) cur.function.arguments += delta.function.arguments;
+}
+
+function finishSseJson(acc) {
+  const message = { role: "assistant", content: acc.content };
+  if (acc.reasoning) message.reasoning_content = acc.reasoning;
+  if (acc.toolCalls.length) {
+    message.tool_calls = acc.toolCalls
+      .filter(Boolean)
+      .map((c, i) => ({ ...c, index: undefined, id: c.id || `call_${i}`, function: { name: c.function.name || "", arguments: c.function.arguments || "{}" } }));
+    if (!message.content) message.content = "";
+  }
+  const json = {
+    id: acc.id || "chatcmpl-aggregated",
+    object: "chat.completion",
+    created: Math.floor(Date.now() / 1000),
+    model: acc.model,
+    choices: [{ index: 0, message, finish_reason: acc.finishReason || (acc.toolCalls.length ? "tool_calls" : "stop"), logprobs: null }],
+  };
+  if (acc.usage) json.usage = acc.usage;
+  return json;
+}
+
+/**
+ * 把上游 SSE 流聚合回非流式 chat completion JSON。
+ * 仅消费 body，不改状态；解析失败时抛错（调用方自行回退）。
+ */
+export async function aggregateChatSse(res) {
+  const reader = res.body?.getReader?.();
+  if (!reader) return res;
+  const acc = { id: null, model: null, content: "", reasoning: "", toolCalls: [], finishReason: null, usage: null, error: null };
+  const decoder = new TextDecoder();
+  let buf = "";
+  const eat = (frame) => {
+    for (const line of frame.split("\n")) {
+      const s = line.trim();
+      if (!s.startsWith("data:")) continue;
+      const payload = s.slice(5).trim();
+      if (!payload || payload === "[DONE]") continue;
+      let j;
+      try { j = JSON.parse(payload); } catch { continue; }
+      if (j?.error) { acc.error = acc.error || j.error; continue; }
+      if (j?.id) acc.id = j.id;
+      if (j?.model) acc.model = j.model;
+      if (j?.usage) acc.usage = j.usage;
+      const ch = j?.choices?.[0];
+      if (!ch) continue;
+      const d = ch.delta || {};
+      if (typeof d.content === "string") acc.content += d.content;
+      if (typeof d.reasoning_content === "string") acc.reasoning += d.reasoning_content;
+      else if (typeof d.reasoning === "string") acc.reasoning += d.reasoning;
+      if (Array.isArray(d.tool_calls)) for (const tc of d.tool_calls) mergeToolCall(acc.toolCalls, tc.index ?? 0, tc);
+      if (ch.finish_reason) acc.finishReason = ch.finish_reason;
+      if (ch.message && typeof ch.message.content === "string" && !acc.content) {
+        acc.content = ch.message.content;
+        if (Array.isArray(ch.message.tool_calls)) for (const tc of ch.message.tool_calls) mergeToolCall(acc.toolCalls, tc.index ?? 0, tc);
+      }
+    }
+  };
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const frames = buf.split("\n\n");
+      buf = frames.pop() || "";
+      for (const f of frames) eat(f);
+    }
+    if (buf.trim()) eat(buf);
+  } finally {
+    try { reader.releaseLock?.(); } catch {}
+  }
+  if (acc.error && !acc.content && !acc.toolCalls.length) {
+    const body = JSON.stringify({ error: acc.error });
+    return new Response(body, { status: 502, headers: { "content-type": "application/json" } });
+  }
+  return new Response(JSON.stringify(finishSseJson(acc)), { status: res.status, headers: { "content-type": "application/json" } });
+}

package/src/opencode-identity.js

@@ -3,9 +3,10 @@ import crypto from "node:crypto";
 // opencode 客户端身份规格单一来源（源码 packages/schema/src/identifier.ts +
 // packages/opencode/src/session/llm/request.ts）：id = <prefix>_ + 12 位 hex
 // (timestamp*4096+同毫秒计数，截 48bit) + 14 位 base62，共 26 字符；UA 必须 "opencode/<semver>"。
-// zen 免费层 2026-09-17 起按该规格放行（缺版本 UA 或 id 形状不符 → 403 FreeTierError）。
+// zen 免费层 2026-09-17 起按该规格放行（缺版本 UA 或 id 形状不符 → 403 FreeTierError）；
+// 2026-09-18 起还要求 UA 版本 ≥ 1.18.0（低版本 426 UpgradeRequired），默认跟 npm latest。
 const ID_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
-const DEFAULT_OPENCODE_UA = "opencode/1.17.20";
+const DEFAULT_OPENCODE_UA = "opencode/1.18.31";
 let idLastTs = 0;
 let idCounter = 0;
 

package/src/routes/chat/broadband-handler.js

@@ -25,13 +25,15 @@ export async function handleBroadbandRelay({
   res,
   startedAt,
   plugins,
+  deps = {},
 }) {
-  const bb = await tryBroadbandRelay({ groups, token, model, body, hops, bus, logs, reqId: handlerCtx.reqId, evt, res, mark, perf0, stages });
+  const { createPipeline = createRelayPipeline, tryBroadbandRelay: tryRelay = tryBroadbandRelay } = deps;
+  const bb = await tryRelay({ groups, token, model, body, hops, bus, logs, reqId: handlerCtx.reqId, evt, res, mark, perf0, stages });
   if (!bb) {
     evt("relay-miss", { reqId: handlerCtx.reqId, model });
     return { handled: false };
   }
-  const pipeline = createRelayPipeline({
+  const pipeline = createPipeline({
     relay,
     buildFallbackInfo,
     auto,
@@ -46,7 +48,8 @@ export async function handleBroadbandRelay({
   });
   const isResponse = bb.result && typeof bb.result.status === "number" && typeof bb.result.headers?.get === "function";
   if (isResponse) {
-    await pipeline.execute({ res, upRes: bb.result, body, requested, actual: model, lastErr, via: "broadband", lockModel, useAuto, handlerCtx, mark, perf0, stages, startedAt });
+    const r = await pipeline.execute({ res, upRes: bb.result, body, requested, actual: model, lastErr, via: "broadband", lockModel, useAuto, handlerCtx, mark, perf0, stages, startedAt });
+    if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
     return { handled: true };
   }
   if (bb.result && typeof bb.result.status === "number") {
@@ -59,7 +62,8 @@ export async function handleBroadbandRelay({
       text: async () => str,
       body: isSSE ? (async function* () { yield Buffer.from(str); })() : null,
     };
-    await pipeline.execute({ res, upRes: fakeRes, body, requested, actual: model, lastErr, via: "broadband-local", lockModel, useAuto, handlerCtx, mark, perf0, stages, startedAt });
+    const r = await pipeline.execute({ res, upRes: fakeRes, body, requested, actual: model, lastErr, via: "broadband-local", lockModel, useAuto, handlerCtx, mark, perf0, stages, startedAt });
+    if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
     return { handled: true };
   }
   evt("relay-miss", { reqId: handlerCtx.reqId, model });

package/src/routes/chat/exhausted-handler.js

@@ -2,18 +2,23 @@ import { relay } from "../stream.js";
 import { json } from "../helpers.js";
 import { performance } from "node:perf_hooks";
 
-export async function handleExhaustedLocal({ res, body, lastErr, order, handlerCtx, evt, logCall, mark, perf0, stages, done, requested, useAuto }) {
+export async function handleExhaustedLocal({ res, body, lastErr, order, handlerCtx, evt, logCall, mark, perf0, stages, done, requested, useAuto, deps = {} }) {
+  const { relay: relayImpl = relay } = deps;
   const model = lastErr?.model ?? handlerCtx.model;
   evt("exhausted-local", { reqId: handlerCtx.reqId, lastModel: lastErr?.model ?? model, lastStatus: lastErr?.status ?? 502, order });
   logCall(lastErr?.model ?? model, lastErr?.status ?? 502);
   if (lastErr?.upstream) {
     evt("relay-start", { reqId: handlerCtx.reqId, model: lastErr.model, via: "local-exhausted", isStream: Boolean(body.stream) });
-    const out = await relay(res, lastErr.upstream, body, {
+    const out = await relayImpl(res, lastErr.upstream, body, {
       onFirstChunk: (d) => mark(`ttf-${lastErr.model}`),
       onDownstreamAbort: () => evt("client-abort", { reqId: handlerCtx.reqId, model: lastErr.model, totalMs: Math.round(performance.now() - perf0), stages: [...stages] }),
     });
     evt("relay-done", { reqId: handlerCtx.reqId, model: lastErr.model, via: "local-exhausted", status: out.status, ttfMs: out.ttfMs, totalMs: out.totalMs, aborted: out.aborted, interrupted: out.interrupted ?? false, detail: out.detail ?? null });
     evt("result", { reqId: handlerCtx.reqId, model: lastErr.model, status: out.status, via: "local", timing: lastErr.upstream._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, detail: out.detail ?? null });
+    // 最后一站：relay 超时路径不写响应（设计留给上层 failover），这里没有上层，必须自己收尾
+    if (out.timedOut) {
+      json(res, 502, { error: out.detail?.upstreamError ? `upstream error: ${out.detail.upstreamError}` : `stream timed out after ${out.totalMs}ms` });
+    }
     return true;
   }
   evt("result", { reqId: handlerCtx.reqId, model, status: lastErr?.status ?? 502, via: "none", timing: null });
@@ -22,17 +27,22 @@ export async function handleExhaustedLocal({ res, body, lastErr, order, handlerC
   return true;
 }
 
-export async function handleExhaustedAll({ res, body, lastErr, order, requested, handlerCtx, evt, logCall, mark, perf0, stages }) {
+export async function handleExhaustedAll({ res, body, lastErr, order, requested, handlerCtx, evt, logCall, mark, perf0, stages, deps = {} }) {
+  const { relay: relayImpl = relay } = deps;
   evt("exhausted-all", { reqId: handlerCtx.reqId, lastModel: lastErr?.model ?? requested, lastStatus: lastErr?.status ?? 502, order });
   logCall(lastErr?.model ?? requested, lastErr?.status ?? 502);
   if (lastErr?.upstream) {
     evt("relay-start", { reqId: handlerCtx.reqId, model: lastErr.model, via: "local-final", isStream: Boolean(body.stream) });
-    const out = await relay(res, lastErr.upstream, body, {
+    const out = await relayImpl(res, lastErr.upstream, body, {
       onFirstChunk: (d) => mark(`ttf-${lastErr.model}`),
       onDownstreamAbort: () => evt("client-abort", { reqId: handlerCtx.reqId, model: lastErr.model, totalMs: Math.round(performance.now() - perf0), stages: [...stages] }),
     });
     evt("relay-done", { reqId: handlerCtx.reqId, model: lastErr.model, via: "local-final", status: out.status, ttfMs: out.ttfMs, totalMs: out.totalMs, aborted: out.aborted, interrupted: out.interrupted ?? false, detail: out.detail ?? null });
     evt("result", { reqId: handlerCtx.reqId, model: lastErr.model, status: out.status, via: "local", timing: lastErr.upstream._t ?? null, ttfMs: out.ttfMs, totalMs: out.totalMs, detail: out.detail ?? null });
+    // 最后一站：relay 超时路径不写响应，这里没有上层 failover，必须自己收尾
+    if (out.timedOut) {
+      json(res, 502, { error: out.detail?.upstreamError ? `upstream error: ${out.detail.upstreamError}` : `stream timed out after ${out.totalMs}ms` });
+    }
     return true;
   }
   evt("result", { reqId: handlerCtx.reqId, model: lastErr?.model ?? requested, status: lastErr?.status ?? 502, via: "none", timing: null });

package/src/routes/chat/hedge-handler.js

@@ -27,14 +27,16 @@ export async function handleHedge({
   plugins,
   res,
   hedgeDelayMs,
+  deps = {},
 }) {
+  const { createPipeline = createRelayPipeline, hedgedFirstChunkRace: race = hedgedFirstChunkRace } = deps;
   const d = hedgeDelayMs;
   try {
-    const hedged = await hedgedFirstChunkRace({ localUpRes: upRes, peers, handlerCtx, hedgeDelayMs: d, evt });
+    const hedged = await race({ localUpRes: upRes, peers, handlerCtx, hedgeDelayMs: d, evt });
     if (hedged && hedged.winner) {
       if (hedged.winner === "local") {
         const bufferedUpRes = { ...upRes, body: hedged.bufferedBody, headers: upRes.headers, status: upRes.status, _t: upRes._t };
-        const pipeline = createRelayPipeline({
+        const pipeline = createPipeline({
           relay,
           buildFallbackInfo,
           auto,
@@ -72,7 +74,7 @@ export async function handleHedge({
         evt("peer-race-win", { reqId: handlerCtx.reqId, model, winPeer: win.peer.url, winTarget: win.target, latencyMs: win.latencyMs, hedged: true, ttfMs: hedged.ttfMs });
         await peers.recordResult(win.peer.url, { ok: true, latencyMs: win.latencyMs, model: win.target });
         const bufferedPeerRes = { ...win.res, body: hedged.bufferedBody, headers: win.res.headers, status: win.res.status, _t: win.res._t };
-        const pipeline = createRelayPipeline({
+        const pipeline = createPipeline({
           relay,
           buildFallbackInfo,
           auto,
@@ -85,7 +87,7 @@ export async function handleHedge({
           startedAt,
           stages,
         });
-        await pipeline.execute({
+        const r = await pipeline.execute({
           res,
           upRes: bufferedPeerRes,
           body,
@@ -101,6 +103,7 @@ export async function handleHedge({
           stages,
           startedAt,
         });
+        if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
         return { handled: true };
       }
     }

package/src/routes/chat/peer-handler.js

@@ -22,14 +22,16 @@ export async function handlePeerRelay({
   startedAt,
   plugins,
   res,
+  deps = {},
 }) {
+  const { createPipeline = createRelayPipeline, racePeerCandidates: race = racePeerCandidates } = deps;
   evt("peer-race-start", { reqId: handlerCtx.reqId, model, peers: peers.ordered().length });
   const peerErrors = [];
   const pctx = { ...handlerCtx, peerErrors };
   const win =
-    (await racePeerCandidates(peers.ordered(), pctx)) ||
-    (await racePeerCandidates(peers.orderedByLastError(), pctx)) ||
-    (await racePeerCandidates(peers.coolingByLastError(), pctx));
+    (await race(peers.ordered(), pctx)) ||
+    (await race(peers.orderedByLastError(), pctx)) ||
+    (await race(peers.coolingByLastError(), pctx));
   if (!win) {
     evt("peer-race-lose", { reqId: handlerCtx.reqId, model });
     // 组员全失败：把每个组员的真实返回汇总给调用者（否则只剩一个无信息的 429/502）
@@ -42,7 +44,7 @@ export async function handlePeerRelay({
   evt("peer-race-win", { reqId: handlerCtx.reqId, model, winPeer: win.peer.url, winTarget: win.target, latencyMs: win.latencyMs });
   await peers.recordResult(win.peer.url, { ok: true, latencyMs: win.latencyMs, model: win.target });
 
-  const pipeline = createRelayPipeline({
+  const pipeline = createPipeline({
     relay,
     buildFallbackInfo,
     auto,
@@ -55,7 +57,7 @@ export async function handlePeerRelay({
     startedAt,
     stages,
   });
-  await pipeline.execute({
+  const r = await pipeline.execute({
     res,
     upRes: win.res,
     body,
@@ -71,5 +73,7 @@ export async function handlePeerRelay({
     stages,
     startedAt,
   });
+  // Note: 超时/失败必须把 handled:false 交回上层换候选（丢弃 → 响应永不 end）— 见 .agents/notes/implemented/bug-fix/2026-09-17-relay-first-chunk-gate-real-cancel.md
+  if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
   return { handled: true };
-}
+}

package/src/routes/chat/relay-pipeline.js

@@ -5,7 +5,7 @@ import { computeMetrics } from "../../metrics.js";
 
 // 唯一/最后候选没有 failover 去向：首块闸门退化为纯"防连接泄漏"，放宽避免误杀慢模型
 // （参考 opencode：zen 通道不设超时；openai responses 硬编码 300s headerTimeout）
-const LAST_CANDIDATE_TIMEOUT_MS = (() => {
+export const LAST_CANDIDATE_TIMEOUT_MS = (() => {
   const n = Number(process.env.MSLXDFF_LAST_CANDIDATE_TIMEOUT_MS);
   return Number.isInteger(n) && n >= 0 ? n : 120_000;
 })();
@@ -60,6 +60,7 @@ export function createRelayPipeline({
     perf0,
     stages: s2,
     startedAt: sa2,
+    streamTimeoutMs: ctxStreamTimeoutMs,
   } = {}) {
     const markFn = m2 || _mark;
     const curStartedAt = sa2 ?? defaultStartedAt ?? Date.now();
@@ -79,13 +80,15 @@ export function createRelayPipeline({
     }
     _evt("relay-start", { reqId, model: actual, via, isStream: Boolean(body?.stream), fallback });
 
-    // 3. relay（唯一/最后候选：无 failover 去向 → 闸门放宽到防泄漏级别）
+    // 3. relay（唯一/最后候选：无 failover 去向 → 闸门放宽到防泄漏级别；显式 streamTimeoutMs 优先）
     const orderLen = handlerCtx?.orderLen;
     const curIdx = handlerCtx?.idx;
     const isLastCandidate =
       Number.isInteger(orderLen) && orderLen > 0 &&
       (orderLen === 1 || (Number.isInteger(curIdx) && curIdx >= orderLen - 1));
-    const streamTimeoutMs = isLastCandidate ? LAST_CANDIDATE_TIMEOUT_MS : C.STREAM_TIMEOUT_MS;
+    const streamTimeoutMs = Number.isInteger(ctxStreamTimeoutMs) && ctxStreamTimeoutMs >= 0
+      ? ctxStreamTimeoutMs
+      : (isLastCandidate ? LAST_CANDIDATE_TIMEOUT_MS : C.STREAM_TIMEOUT_MS);
     const out = await _relay(res, upRes, body, {
       fallback,
       streamTimeoutMs,
@@ -115,11 +118,12 @@ export function createRelayPipeline({
 
     // 5a. 首块超时未写字节 → 回退（显式 timedOut 字段，status 只是 HTTP 语义展示）
     if (out.timedOut === true) {
+      const why = out.detail?.upstreamError ? ` (upstream read error: ${out.detail.upstreamError})` : "";
       if (auto) try { await auto.recordError(actual, { status: 502, slow: true, note: `stream timeout ${streamTimeoutMs}ms` }); } catch {}
-      try { _logError(actual, 502, `stream timeout ${streamTimeoutMs}ms`); } catch {}
+      try { _logError(actual, 502, `stream timeout ${streamTimeoutMs}ms${why}`); } catch {}
       _evt("upstream-error", { reqId, model: actual, status: 502, message: "stream timeout", timing: null });
       _evt("fallback", { reqId, from: actual, to: null, reason: "stream timeout" });
-      return { handled: false, upRes: null, lastErr: { model: actual, upstream: null, status: 502, message: `stream timed out after ${streamTimeoutMs}ms` } };
+      return { handled: false, upRes: null, lastErr: { model: actual, upstream: null, status: 502, message: `stream timed out after ${streamTimeoutMs}ms${why}` } };
     }
 
     // 5b. 中断（stall 超时 / max 流时长）

package/src/routes/chat/via-route-handler.js

@@ -1,4 +1,4 @@
-import { createRelayPipeline } from "./relay-pipeline.js";
+import { createRelayPipeline, LAST_CANDIDATE_TIMEOUT_MS } from "./relay-pipeline.js";
 import { relay, SLOW_TOTAL_MS, STREAM_TIMEOUT_MS, STALL_TIMEOUT_MS, SCORE_STALL_MS } from "../stream.js";
 import { buildFallbackInfo } from "../fallback.js";
 import { getViaRoute } from "../../bench/via-routes.js";
@@ -121,7 +121,7 @@ export async function handleViaRoute({
     startedAt,
     stages,
   });
-  await pipeline.execute({
+  const r = await pipeline.execute({
     res,
     upRes,
     body,
@@ -136,6 +136,9 @@ export async function handleViaRoute({
     perf0,
     stages,
     startedAt,
+    // 借道单路径无第二候选可比：按末位耐心档（默认 120s，MSLXDFF_LAST_CANDIDATE_TIMEOUT_MS 可调/0=不限）
+    streamTimeoutMs: LAST_CANDIDATE_TIMEOUT_MS,
   });
+  if (!r.handled) return { handled: false, upRes: null, lastErr: r.lastErr };
   return { handled: true };
 }

package/src/routes/helpers.js

@@ -19,7 +19,8 @@ export function authorized(req, token) {
 
 export function json(res, status, body) {
   res.statusCode = status;
-  res.setHeader("Content-Type", "application/json");
+  // 已发 headers（如 failover 时前一个候选写过 SSE 注释帧）不可再设，否则抛 ERR_HTTP_HEADERS_SENT
+  try { if (!res.headersSent) res.setHeader("Content-Type", "application/json"); } catch { /* ignore */ }
   res.end(JSON.stringify(body));
 }
 

package/src/routes/stream.js

@@ -20,6 +20,29 @@ function cancelBody(body) {
   } catch { /* ignore */ }
 }
 
+// 注释帧（": keepalive" 等）不是模型输出：不算首块、不解除闸门、不触发超时救回，但照常透传
+function hasPayload(text) {
+  for (const line of String(text).split("\n")) {
+    const t = line.trim();
+    if (!t || t.startsWith(":")) continue;
+    return true;
+  }
+  return false;
+}
+
+// 自持 reader 优先：for-await 会锁定 ReadableStream，使 body.cancel() 必 reject（真流上等于空操作），
+// 超时/断下游要真能掐上游必须走 reader.cancel()
+async function* bodyChunks(body, reader) {
+  if (reader) {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      yield value;
+    }
+  }
+  for await (const c of body) yield c;
+}
+
 export const SLOW_TOTAL_MS = (() => {
   const n = Number(process.env.MSLXDFF_SLOW_TOTAL_MS);
   return Number.isInteger(n) && n > 0 ? n : 20_000;
@@ -94,16 +117,26 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
     recoveries: 0,
   };
   let prevChunkAt = t0;
+  // 断下游即掐上游：流式分支装配真实取消，非流式保持 no-op
+  let cancelUpstream = () => {};
   const onClose = () => {
     detail.downstreamClosed = true;
-    if (!finishedNormally && onDownstreamAbort) onDownstreamAbort();
+    if (!finishedNormally) {
+      cancelUpstream();
+      if (onDownstreamAbort) onDownstreamAbort();
+    }
   };
   res.on("close", onClose);
 
   if (isStream) {
-    res.setHeader("Content-Type", "text/event-stream");
-    res.setHeader("Cache-Control", "no-cache");
-    res.setHeader("Connection", "keep-alive");
+    // failover 重入时 headers 可能已发（前一个候选只发过 keepalive 注释帧就被掐）——已发则不可再设
+    if (!res.headersSent) {
+      try {
+        res.setHeader("Content-Type", "text/event-stream");
+        res.setHeader("Cache-Control", "no-cache");
+        res.setHeader("Connection", "keep-alive");
+      } catch { /* ignore */ }
+    }
     if (fallback?.fallback) {
       try {
         res.write(`: mslxdff fallback ${fallback.requested_model} -> ${fallback.actual_model} (${fallback.reason})\n`);
@@ -113,10 +146,21 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
     if (upRes.body) {
       let first = true;
       let wroteAny = false;
+      let wrotePayload = false; // 真实数据帧（注释帧不算）：决定能否安全 failover
       let timedOut = false;
       let stalled = false;
       let tooLong = false;
       let stallTimer = null;
+      // 自持 reader：超时/断下游时 reader.cancel() 才真的掐得断上游
+      // Note: 闸门真取消 + 注释帧不算首块 + wrotePayload 判据 — 见 .agents/notes/implemented/bug-fix/2026-09-17-relay-first-chunk-gate-real-cancel.md
+      const reader = typeof upRes.body.getReader === "function" ? upRes.body.getReader() : null;
+      let cancelled = false;
+      cancelUpstream = () => {
+        if (cancelled) return;
+        cancelled = true;
+        if (reader) { try { reader.cancel().catch(() => {}); } catch { /* ignore */ } }
+        else cancelBody(upRes.body);
+      };
       let pingTimer = keepaliveMs > 0
         ? setInterval(() => {
             if (wroteAny) return;
@@ -129,7 +173,7 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
           ? setTimeout(() => {
               stalled = true;
               detail.exitReason = "stall";
-              cancelBody(upRes.body);
+              cancelUpstream();
             }, STALL_TIMEOUT_MS)
           : null;
       };
@@ -137,18 +181,18 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
         ? setTimeout(() => {
             timedOut = true;
             detail.exitReason = "first-timeout";
-            cancelBody(upRes.body);
+            cancelUpstream();
           }, streamTimeoutMs)
         : null;
       const maxTimer = MAX_STREAM_MS
         ? setTimeout(() => {
             tooLong = true;
             detail.exitReason = "max";
-            cancelBody(upRes.body);
+            cancelUpstream();
           }, MAX_STREAM_MS)
         : null;
       try {
-        for await (const chunk of upRes.body) {
+        for await (const chunk of bodyChunks(upRes.body, reader)) {
           const now = performance.now();
           detail.receivedChunks += 1;
           const len = chunk?.length ?? chunk?.byteLength ?? 0;
@@ -159,8 +203,9 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
           if (gap > detail.maxGapMs) detail.maxGapMs = gap;
           if (gap > SCORE_STALL_MS) detail.stallHits += 1;
           prevChunkAt = now;
+          const txt = chunkText(chunk);
+          const isPayload = hasPayload(txt);
           try {
-            const txt = chunkText(chunk);
             if (txt.includes("[DONE]")) detail.sawDone = true;
             const m = txt.match(/"finish_reason"\s*:\s*"([^"]+)"/);
             if (m) detail.sawFinishReason = m[1];
@@ -196,9 +241,10 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
               } catch {}
             }
           } catch { /* ignore */ }
-          // 首块/空闲超时后上游仍吐出了数据 → 只是慢，不是死：撤销超时判定，照常转发
-          //（cancel 是协作式的，缓冲数据仍会到达；丢掉已到达的数据是纯损失）
-          if (timedOut || stalled) {
+          // 首块/空闲超时后上游仍吐出了真实数据 → 只是慢，不是死：撤销超时判定，照常转发
+          //（cancel 是异步的，竞态窗口内已到达的数据是纯收益；丢掉是纯损失）
+          // 注释帧（keepalive）不算：否则对端只要在发心跳，闸门就永远解除
+          if (isPayload && (timedOut || stalled)) {
             timedOut = false;
             stalled = false;
             detail.recoveries = (detail.recoveries || 0) + 1;
@@ -206,14 +252,14 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
             if (firstTimer) { clearTimeout(firstTimer); firstTimer = null; }
           }
           if (timedOut || stalled || tooLong) break;
-          if (first) {
+          if (isPayload && first) {
             first = false;
             ttf = Math.round(now - t0);
             onFirstChunk?.(ttf);
             if (firstTimer) { clearTimeout(firstTimer); firstTimer = null; }
           }
           let outChunk = chunk;
-          if (first === false && fallback?.fallback && wroteAny === false) {
+          if (first === false && fallback?.fallback && wrotePayload === false) {
             try {
               let txt = "";
               if (Buffer.isBuffer(chunk)) txt = chunk.toString("utf8");
@@ -226,16 +272,17 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
             } catch {}
           }
           wroteAny = true;
+          if (isPayload) wrotePayload = true;
           detail.wroteChunks += 1;
           detail.wroteBytes += Buffer.isBuffer(outChunk) ? outChunk.length : (outChunk?.length ?? len);
-          res.write(outChunk);
+          try { res.write(outChunk); } catch { /* 下游已断开：onClose 已掐上游 */ }
           armStall();
         }
-        if (!detail.exitReason) detail.exitReason = "normal";
+        if (!detail.exitReason) detail.exitReason = detail.downstreamClosed ? "downstream-closed" : "normal";
       } catch (err) {
         detail.upstreamError = String(err?.message || err).slice(0, 300);
         detail.exitReason = "upstream-error";
-        if (!wroteAny) timedOut = true;
+        if (!wrotePayload) timedOut = true;
         else stalled = true;
       } finally {
         if (firstTimer) clearTimeout(firstTimer);
@@ -243,12 +290,13 @@ export async function relay(res, upRes, body, { onFirstChunk, onDownstreamAbort,
         if (stallTimer) clearTimeout(stallTimer);
         if (pingTimer) clearInterval(pingTimer);
       }
-      if (timedOut && !wroteAny) {
+      // 任一闸门到点且未写出真实数据 → 可安全 failover（注释帧对客户端无意义，不算已响应）
+      if ((timedOut || stalled || tooLong) && !wrotePayload) {
         res.removeListener("close", onClose);
         // Note: 超时是显式字段（timedOut），别再用 status 数值当信号 — 见 .agents/notes/implemented/architecture/2026-09-17-relay-timedout-explicit-and-metrics-seam.md
         return { status: 504, timedOut: true, ttfMs: null, totalMs: Math.round(performance.now() - t0), aborted: true, interrupted: false, detail };
       }
-      if ((stalled || tooLong) && wroteAny) {
+      if ((stalled || tooLong) && wrotePayload) {
         interrupted = true;
         detail.exitReason = detail.exitReason || (stalled ? "stall" : "max");
         res.removeListener("close", onClose);

package/src/upstream-engine/index.js

@@ -5,6 +5,7 @@
 import { createUpstreamClient, createOpencodeHeaderBuilder } from "../upstream.js";
 import { isResponsesModel } from "../upstream-responses.js";
 import { isFreeModel } from "../models.js";
+import { ensureFreeLaneShape } from "../free-lane.js";
 import { createSdkChat } from "./sdk/chat.js";
 import { createSdkResponses } from "./sdk/responses.js";
 import { dispatcherFetch } from "./sdk/attempt.js";
@@ -32,9 +33,11 @@ export function createUpstreamEngine(opts = {}) {
   let logged = false;
 
   async function chat(body) {
-    if (sdkDown) return legacy.chat(body);
-    // doGenerate 聚合未实现：非流式（含 responses 非流式）委派 legacy，避免把 JSON 客户端 SSE 化
-    if (body?.stream === false) return legacy.chat(body);
+    // zen 免费层 agent 形状门禁（2026-09-18）：SDK 流式通道不经 legacy.chat，必须在这里补形状。
+    // 非流式先委派 legacy（它在自己内部注入并把 SSE 聚合回 JSON，避免这里先改 stream 导致误判）。
+    const wantsStream = body?.stream !== false;
+    if (sdkDown || !wantsStream) return legacy.chat(body);
+    if (isFreeModel(body?.model)) ensureFreeLaneShape(body);
     const useResponses = isResponsesModel(body?.model);
     try {
       const res = useResponses ? await responses.chat(body) : await sdk.chat(body);

package/src/upstream.js

@@ -7,6 +7,7 @@ import { isFreeModel } from "./models.js";
 import { fmtShanghaiYMDHMS } from "./time.js";
 import { createTransport } from "./transport/index.js";
 import { isResponsesModel, chatToResponsesBody, toChatResponse, reshapeResponsesSse } from "./upstream-responses.js";
+import { ensureFreeLaneShape, aggregateChatSse } from "./free-lane.js";
 import { digestIdTail, genId, opencodeClientIdentity, opencodeUa } from "./opencode-identity.js";
 
 export { opencodeClientIdentity, opencodeUa };
@@ -136,6 +137,27 @@ export function createUpstreamClient({
     const sessionId = opts?.sessionId || sessionFromMessages(body?.messages) || null;
     const url = isResp ? `${baseUrl}/zen/v1/responses` : `${baseUrl}/zen/v1/chat/completions`;
     const reqBody = isResp ? chatToResponsesBody(body) : body;
+    const clientWantsStream = body?.stream !== false;
+    // zen 免费层 agent 形状门禁（2026-09-18）：必须流式 + 含核心五工具名，否则 403 FreeTierError
+    const freeLane = authToken === "public" && isFreeModel(body?.model);
+    if (freeLane) ensureFreeLaneShape(reqBody, { responses: isResp });
+    const laneDebug = freeLane && envInt("MSLXDFF_FREE_LANE_DEBUG", 0) === 1;
+    if (laneDebug) {
+      try { console.error(`[free-lane] send model=${body?.model} url=${url} stream=${reqBody.stream} tools=${(reqBody.tools || []).length} ua=${opencodeUa()} want=${clientWantsStream}`); } catch {}
+    }
+    // 非流式调用者实际拿到的是被强制流式的上游 → 聚合回 chat completion JSON
+    async function agentJson(resp) {
+      if (!(freeLane && !clientWantsStream && resp.ok)) return resp;
+      const ct = resp.headers?.get?.("content-type") || "";
+      if (!ct.includes("text/event-stream")) return resp;
+      try {
+        const out = await aggregateChatSse(resp);
+        out._t = resp._t;
+        return out;
+      } catch {
+        return resp;
+      }
+    }
     const t0 = performance.now();
 
      // 首发请求（transport 已处理 network/429 等重试）
@@ -146,7 +168,7 @@ export function createUpstreamClient({
         method: "POST",
         headers: buildHeaders(reqBody, { sessionId }),
         body: reqBody,
-        stream: body?.stream !== false,
+        stream: reqBody.stream !== false,
         timeoutMs: connectTimeoutMs,
         retry,
       });
@@ -154,6 +176,9 @@ export function createUpstreamClient({
       e._t = e._t || { attempts: [], waitMs: 0, totalMs: Math.round(performance.now() - t0) };
       throw e;
     }
+    if (laneDebug) {
+      try { console.error(`[free-lane] resp model=${body?.model} status=${res.status} ct=${res.headers?.get?.("content-type") || ""}`); } catch {}
+    }
 
     // 匿名兜底：仅非 anonFirst 时，public 429 + free 模型才走 hermes 空头重试
     if (!anonFirst && res.status === 429 && isFreeModel(body?.model) && shouldTryAnonFree()) {
@@ -168,7 +193,7 @@ export function createUpstreamClient({
             method: "POST",
             headers: buildHeaders(reqBody, { anonymous: true, sessionId }),
             body: reqBody,
-            stream: body?.stream !== false,
+            stream: reqBody.stream !== false,
             timeoutMs: connectTimeoutMs,
             retry,
           });
@@ -180,7 +205,7 @@ export function createUpstreamClient({
           let outAnon = anonRes;
           if (isResp && anonRes.ok) {
             const ctAnon = anonRes.headers.get("content-type") || "";
-            const isStreamAnon = body?.stream !== false && ctAnon.includes("text/event-stream");
+            const isStreamAnon = (clientWantsStream || freeLane) && ctAnon.includes("text/event-stream");
             if (isStreamAnon) {
               outAnon = reshapeResponsesSse(anonRes, body.model);
             } else {
@@ -201,7 +226,7 @@ export function createUpstreamClient({
           if (consecutiveHits >= 2) {
             try { appendFile(freeAnonLogFile(), `  -> 连续额外额度 ${consecutiveHits} 次\n`).catch(() => {}); } catch {}
           }
-          return outAnon;
+          return await agentJson(outAnon);
         }
       }
       if (anonRes) {
@@ -215,11 +240,11 @@ export function createUpstreamClient({
     // responses 模型成功态转 chat（复用 upstream-responses）
     if (isResp && res.ok) {
       const ct = res.headers.get("content-type") || "";
-      const isStream = body?.stream !== false && ct.includes("text/event-stream");
+      const isStream = (clientWantsStream || freeLane) && ct.includes("text/event-stream");
       if (isStream) {
         const transformed = reshapeResponsesSse(res, body.model);
         transformed._t = { ...(res._t || {}), totalMs: Math.round(performance.now() - t0) };
-        return transformed;
+        return await agentJson(transformed);
       }
       try {
         const txt = await res.text();
@@ -238,7 +263,7 @@ export function createUpstreamClient({
       }
     }
     res._t = { ...(res._t || {}), totalMs: res._t?.totalMs ?? Math.round(performance.now() - t0) };
-    return res;
+    return await agentJson(res);
   }
 
   async function preheat() {