fix(review): PR #23 round-2 — true-only doc sync, strip tests, strip typing

Stage 1 (docs/comments, zero behavior change): sync all-false -> strip-false/true-only semantics across docs/configuration.md, CHANGELOG, 5 route call-site comments; soften jail git-init comment per round-2 (plain dirs pass); add out-of-matrix OPENCODE_CLIENT backend-identity docs + AGENTS.md notes (no six-way matrix change by design).

Stage 2 (tests): DISABLE_TOOLS:true response-stripping cases for chat + responses; interactions stream + non-stream strip cases; fail-closed pin for the wider transform gate anchor.

Stage 3 (type hygiene): stripFunctionCalls unknown -> string, drop redundant casts; session-ids upstream-pin + explicit fixture constants.

Author: samson910022

AGENTS.md

@@ -72,7 +72,8 @@ config.json.example / .env.example   # examples only, never real secrets
 | Auth multi-key (A) | `OPENCODE_API_KEYS` canonical, `API_KEYS` legacy alias (merge; empty never blocks) | `API_KEYS` | `(none, merges with API_KEY)` |
 | Fallback proxies | `OPENCODE_UPSTREAM_PROXIES` / `OPENCODE_UPSTREAM_PROXY_STRATEGY` / `OPENCODE_UPSTREAM_PROXY_COOLDOWN_MS` / `OPENCODE_UPSTREAM_PROXY_NO_PROXY` | `UPSTREAM_*` short forms | `(none)` / `failover-rr` / `300000` / `localhost,127.0.0.1,::1` |
 
-- `DISABLE_TOOLS` resolution: `OPENCODE_DISABLE_TOOLS > DISABLE_TOOLS > file > true` via `resolveDisableTools` (`src/config/proxy-config.ts:47-57`); covered by `tests/env-alias.test.js`. Never `??`-chain booleans by hand; call the helper.
+- `DISABLE_TOOLS` resolution: `OPENCODE_DISABLE_TOOLS > DISABLE_TOOLS > file > true` via `resolveDisableTools` (`src/config/proxy-config.ts:47-57`); covered by `tests/env-alias.test.js`. Never `??`-chain booleans by hand; call the helper. Note: `true` still resolves `true` — the free-tier strip (`selectPromptToolOverrides`, `src/proxy.ts:75-91`) is a post-resolution prompt-body filter for `isFreeTierSuspectModel` only (guard text + output markup stripping stay active).
+- Out-of-matrix backend identity (do NOT add to the six-way matrix): `OPENCODE_CLIENT` is read directly in `src/backend/manager.ts:41-44` (allowlist `cli/desktop/acp/app`, default `cli`, foreign values overwritten), never enters `ProxyConfig`/`buildProxyConfig`; documented in `docs/configuration.md` backend-identity subsection + `CHANGELOG.md`. Same for the `OPENCODE_API_KEY="public"` strip and best-effort jail `git init`.
 - `RETRY`: raw `env ?? file ?? 3`, normalized by `resolveMaxRetries` (`src/retry/policy.ts:51-58`, clamp 0–5, total attempts `1+n`, `2s×2ⁿ⁻¹` + 25% jitter, `retry-after` clamped to 30s).
 - **Known dual-entry drifts (do NOT silently "fix" defaults — they change behavior; unify explicitly with tests):** `REQUEST_TIMEOUT_MS` prod `180000` (`index.ts:179`, Dockerfile/compose/docs) vs library `300000` (`src/config/proxy-config.ts:4`); `MANAGE_BACKEND` prod `false` (`index.ts:49`) vs library `true` (`src/config/proxy-config.ts:159`); `OMIT_SYSTEM_PROMPT` prod unconditional `false` (`index.ts:184-187`) vs library auto-`true` under `plugin-inject` (`src/config/proxy-config.ts:208-211`); bool parsing strictness differs (`index.ts:12-22` loose vs `src/config/proxy-config.ts:24-37` strict vs `DEBUG`/`ISOLATED` exact-match). Any new env must update all six: `.env.example`, `config.json.example`, `Dockerfile`, `docker-compose.yml`, `index.ts`, `docs/configuration.md` + this table.
 

CHANGELOG.md

@@ -31,7 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- **Anonymous first-party backend posture + Zen free-tier gate handling**: spawned backend pins `OPENCODE_CLIENT` to a known first-party value (`cli` default; `desktop`/`acp`/`app` pass through), strips the `OPENCODE_API_KEY="public"` footgun (anonymous uses empty), and git-inits the jail workspace best-effort (5s timeout, warn-and-continue) so session dirs resolve to a git work tree. All-false prompt `tools` maps are omitted only for likely-free `opencode` models (`-free` suffix, `big-pickle`, `union-alpha`) to dodge the `FreeTierError` 403; paid/other providers keep the exact hard-disable map. The gate (`...used from within OpenCode` / `FreeTierError`) now surfaces as 403 `permission_denied` fail-fast (no retry, no proxy fallback) with false-positive guards for plain quota text. Jail stdout no longer prints absolute paths; interactions route gains text-level tool-markup stripping parity with chat/responses/messages. New `tests/backend-identity.test.js` / `tests/first-party-gate.test.js` / `tests/prompt-tool-overrides.test.js` / `tests/session-ids.test.js`. No new proxy knob (no config matrix change).
+- **Anonymous first-party backend posture + Zen free-tier gate handling**: spawned backend pins `OPENCODE_CLIENT` to a known first-party value (`cli` default; `desktop`/`acp`/`app` pass through), strips the `OPENCODE_API_KEY="public"` footgun (anonymous uses empty), and git-inits the jail workspace best-effort (5s timeout, warn-and-continue) as defense-in-depth for session-dir sensitivity. Prompt `tools` maps have `false` entries stripped (true-only sent; all-false omitted) only for likely-free `opencode` models (`-free` suffix, `big-pickle`, `union-alpha`) to dodge the `FreeTierError` 403 (any `false` gates); stripped tools fall back to agent defaults server-side while paid/other providers keep the exact hard-disable map. The gate (`...used from within OpenCode` / `FreeTierError`) now surfaces as 403 `permission_denied` fail-fast (no retry, no proxy fallback) with false-positive guards for plain quota text. Jail stdout no longer prints absolute paths; interactions route gains text-level tool-markup stripping parity with chat/responses/messages. New `tests/backend-identity.test.js` / `tests/first-party-gate.test.js` / `tests/prompt-tool-overrides.test.js` / `tests/session-ids.test.js`. No new proxy knob (no config matrix change).
 - **Translator parity fixes (N×N matrix review)**: chat array `content` parts no longer silently dropped (extract `text`/`content`); `responses` `incomplete` with `content_filter` reason round-trips instead of collapsing to `length` (non-stream + stream); `is_error` now round-trips via the `ERROR: ` text prefix on chat/messages/responses tool legs (strict `true`/`"true"` check; success text literally starting with `ERROR: ` round-trips as `is_error` by design); named `custom` tool declarations are kept so `custom_tool_call` invocations always have a matching declaration; ID generation centralized on `makeId(prefix)` (`toolu_` fallback separator canonicalized, prefix-only checks unaffected). N×N 翻译矩阵对齐修复。New `tests/translator-phase-fixes.test.js` (13 cases).
 - **后端错误透出**：`/v1/responses` 在后端 session 失败时曾 `throw` 纯对象，经 `transformUpstreamError` 被洗成 `500 Internal server error / code Object`、真实讯息丢失。新增 `normalizeBackendError`（纯对象→Error，保留 `data.message`/`name`/状态码推断），两处 `throw polled.error` 改用它；`transformUpstreamError` 纵深加固（默认分支改读 `data.message`/`name`，code 默认 `upstream_error` 不再用 `constructor.name`）。现 Credits 类错误正确回 `402 insufficient_quota` 并携带原文。新增 `tests/backend-error-surface.test.js`（4 例复现 LiteLLM 案例，含 messages）。
 - **同族错误路径查漏**：responses 串流 idleTimeout 补 poll 失败检查（不再静默回空 `completed`）；messages 非串流改用 transformed `status/type/code`（不再硬编码 `502/api_error`）；messages 串流检查 `collected.error` 与 poll 失败（失败即抛正規化错误走 SSE error 事件，不再静默 200）；`isTransientUpstreamError` 纳入 `name/code/type` 参与签名匹配（无 message 纯对象不再必判 false）。

docs/configuration.md

@@ -32,7 +32,7 @@
 
 | 变量 | 默认值 | 说明 |
 |:-----|:-------|:-----|
-| `OPENCODE_DISABLE_TOOLS` / `DISABLE_TOOLS` | `true` | 禁用 OpenCode 工具调用（兼容别名；`OPENCODE_DISABLE_TOOLS` 优先，二者无效值都会让位给下一顺位：canonical env > legacy env > `config.json` > 默认）。例外：① 疑似免费 Zen 模型（`opencode` provider 且 `-free` 后缀、`big-pickle`、`union-alpha`）省略全 `false` 的 prompt `tools` 映射以避开上游 `FreeTierError` 403，此时仅靠 system prompt 禁用语 + 无 tool 定义 + 输出侧 markup 剥离承载禁用姿态；② `/v1/responses` 的 `web_search` 与 Interactions 的 `google_search` 会以 `hosted-search-grant` 单独放行 `websearch`（输出仅 `web_search_call` + 引文，不经过外部桥接） |
+| `OPENCODE_DISABLE_TOOLS` / `DISABLE_TOOLS` | `true` | 禁用 OpenCode 工具调用（兼容别名；`OPENCODE_DISABLE_TOOLS` 优先，二者无效值都会让位给下一顺位：canonical env > legacy env > `config.json` > 默认）。例外：① 疑似免费 Zen 模型（`opencode` provider 且 `-free` 后缀、`big-pickle`、`union-alpha`）剔除 prompt `tools` 映射中的 `false` 项（仅保留 `true` 项；全 `false` 则省略整个映射）以避开上游 `FreeTierError` 403（任意 `false` 均触发，`{}`/省略/`true`-only 通过），被剔除的工具回落服务端 agent 默认，此时仅靠 system prompt 禁用语 + 输出侧 markup 剥离承载禁用姿态；② `/v1/responses` 的 `web_search` 与 Interactions 的 `google_search` 会以 `hosted-search-grant` 单独放行 `websearch`（输出仅 `web_search_call` + 引文，不经过外部桥接） |
 | `OPENCODE_EXTERNAL_TOOLS_MODE` | `proxy-bridge` | 外部工具桥接模式；当前仅支持 `proxy-bridge` |
 | `OPENCODE_EXTERNAL_TOOLS_CONFLICT_POLICY` | `namespace` | 外部工具冲突隔离策略；当前仅支持 `namespace` |
 | `OPENCODE_INTERNAL_WEB_FETCH_ENABLED` | `false` | 兼容旧开关；未显式配置 allowlist 时，启用后默认放行 `web_fetch` |
@@ -78,6 +78,12 @@
 | `OPENCODE_PATH` | `opencode` | OpenCode 可执行文件路径 |
 | `OPENCODE_ZEN_API_KEY` | - | Zen API Key 透传 |
 
+### 后端 identity（非 proxy knob，不进六向矩阵）
+
+- `OPENCODE_CLIENT`：被拉起后端向 Zen 声明的第一方身份。allowlist 为 `cli`/`desktop`/`acp`/`app`，默认 `cli`；未设置/空白/未知值一律回落 `cli`（allowlist clamp，非 bool fallthrough）。
+- 从网关宿主环境继承的外来值会被覆写（如 `opencode2api` 会被重写为 `cli`），已知值透传。无 file key、无别名，不进 `ProxyConfig`/`buildProxyConfig`，故 `.env.example`/`config.json.example`/`Dockerfile`/`docker-compose.yml`/`index.ts` 均不声明。
+- 附带：`OPENCODE_API_KEY="public"` 字面值会从后端环境删除（匿名应传空而非该字面）；jail 工作目录会 best-effort `git init`（5s 超时，失败 warn 继续）。
+
 ---
 
 ## 📄 config.json 示例

src/backend/manager.ts

@@ -46,11 +46,11 @@ export function resolveBackendClient(): string {
 
 /**
  * Stage-6: `git init` the jail workspace so session directories resolve to a
- * git-backed project root. Zen's free-tier gate answers non-git project roots
- * with FreeTierError 403 even when everything else mimics first-party
- * (verified live: identical backend+prompt returns 200 the moment the session
- * directory sits inside a git work tree — even an empty repo with no commit
- * or remote). Best-effort: warns and continues when git is unavailable.
+ * git-backed project root. Kept as defense-in-depth for backend versions
+ * whose free-tier gate is sensitive to non-git project roots (live round-2
+ * verification showed plain dirs also pass on the current backend, so this
+ * is compatibility insurance, not a requirement). Best-effort: warns and
+ * continues when git is unavailable.
  */
 export function ensureJailGitRepo(workspace: string): boolean {
   try {

src/proxy.ts

@@ -371,7 +371,8 @@ export function createApp(config: ProxyConfig): CreateAppResult {
     return effortMap[value.toLowerCase()] ?? (fallback as string | null);
   };
 
-  const stripFunctionCalls = (text: unknown, trim: boolean = true): unknown => {
+  const stripFunctionCalls = (text: unknown, trim: boolean = true): string => {
+    if (typeof text !== 'string') return String(text ?? '');
     if (!DISABLE_TOOLS || !text) return text;
     return stripFunctionCallMarkup(String(text), trim);
   };
@@ -818,7 +819,7 @@ export function createApp(config: ProxyConfig): CreateAppResult {
             ],
           },
         };
-        // Stage-5: drop all-disabled maps for free-tier suspects (Zen gate).
+        // Stage-5: strip false entries for free-tier suspects (any false gates; true-only sent, all-false omitted).
         const forcedToolOverrides = selectPromptToolOverrides(toolOverrides, providerID, modelID);
         if (forcedToolOverrides) {
           forcedPromptParams.body['tools'] = forcedToolOverrides;

src/routes/chat.ts

@@ -401,7 +401,7 @@ export function registerChatRoutes(app: Application, ctx: AppContext): void {
               REQUEST_TIMEOUT_MS,
               'load tool overrides',
             )) as Record<string, boolean> | null;
-            // Stage-5: drop all-disabled maps for free-tier suspects (Zen gate).
+            // Stage-5: strip false entries for free-tier suspects (any false gates; true-only sent, all-false omitted).
             const promptToolOverrides = selectPromptToolOverrides(toolOverrides, pID, mID);
             if (promptToolOverrides) {
               promptParams.body['tools'] = promptToolOverrides;
@@ -868,8 +868,8 @@ export function registerChatRoutes(app: Application, ctx: AppContext): void {
                 }
               }
               const { validCalls: validatedToolCalls } = finalizeValidatedToolCalls(parsedToolCalls, externalToolRegistry);
-              const safeContent = stripFunctionCallMarkup(stripFunctionCalls(content) as string) as string;
-              const safeReasoning = stripFunctionCallMarkup(stripFunctionCalls(reasoning) as string) as string;
+              const safeContent = stripFunctionCallMarkup(stripFunctionCalls(content));
+              const safeReasoning = stripFunctionCallMarkup(stripFunctionCalls(reasoning));
 
               const promptTokens = Math.ceil((fullPromptText || '').length / 4);
               const completionTokensCalc = Math.ceil((content || '').length / 4);

src/routes/interactions.ts

@@ -275,7 +275,7 @@ export function registerInteractionsRoutes(app: Application, ctx: AppContext): v
           parts,
         },
       };
-      // Stage-5: drop all-disabled maps for free-tier suspects (Zen gate).
+      // Stage-5: strip false entries for free-tier suspects (any false gates; true-only sent, all-false omitted).
       const promptToolOverrides = selectPromptToolOverrides(toolOverrides, pID, mID);
       if (promptToolOverrides) {
         promptParams.body['tools'] = promptToolOverrides;
@@ -358,10 +358,10 @@ export function registerInteractionsRoutes(app: Application, ctx: AppContext): v
           return;
         }
         // Parity with chat/responses/messages: strip tool-call markup when
-        // DISABLE_TOOLS so a free-tier omission (no all-false tools map,
+        // DISABLE_TOOLS so a free-tier strip (no false entries in the tools map,
         // see selectPromptToolOverrides) cannot leak call syntax to clients.
         // stripFunctionCalls is a no-op unless DISABLE_TOOLS=true.
-        const text = String(stripFunctionCalls(polled.content || '') ?? '');
+        const text = stripFunctionCalls(polled.content || '');
           // Chunked deltas keep clients alive on long answers.
           for (let i = 0; i < text.length; i += 500) {
             emit({ type: 'step.delta', interaction_id: interactionId, delta: text.slice(i, i + 500) });
@@ -393,7 +393,7 @@ export function registerInteractionsRoutes(app: Application, ctx: AppContext): v
 
       const polled = await promptAndPoll();
       // Same parity strip as the stream path above.
-      const text = String(stripFunctionCalls(polled.content || '') ?? '');
+      const text = stripFunctionCalls(polled.content || '');
       const evidence = hostedSearch.requested ? extractSearchEvidence(polled.toolParts ?? []) : { queries: [] as string[], sources: [] as { url: string; title: string }[] };
       const searchCalls = buildWebSearchCallItems(evidence);
       const annotations = buildCitationAnnotations(text, evidence.sources);

src/routes/messages.ts

@@ -311,7 +311,7 @@ export function registerMessagesRoutes(app: Application, ctx: AppContext): void
             REQUEST_TIMEOUT_MS,
             'load tool overrides',
           )) as Record<string, boolean> | null;
-          // Stage-5: drop all-disabled maps for free-tier suspects (Zen gate).
+          // Stage-5: strip false entries for free-tier suspects (any false gates; true-only sent, all-false omitted).
           const promptToolOverrides = selectPromptToolOverrides(toolOverrides, pID, mID);
           if (promptToolOverrides) promptParams.body['tools'] = promptToolOverrides;
 
@@ -338,8 +338,8 @@ export function registerMessagesRoutes(app: Application, ctx: AppContext): void
             reasoning: unknown,
             validatedToolCalls: unknown,
           ): Record<string, unknown> => {
-            const safeContent = stripFunctionCallMarkup(stripFunctionCalls(content) as string) as string;
-            const safeReasoning = stripFunctionCallMarkup(stripFunctionCalls(reasoning) as string) as string;
+            const safeContent = stripFunctionCallMarkup(stripFunctionCalls(content));
+            const safeReasoning = stripFunctionCallMarkup(stripFunctionCalls(reasoning));
             const publicCalls = toPublicToolCalls(validatedToolCalls);
             const anthropicTools = publicCalls.map((tc) => {
               const tcr = tc as unknown as Record<string, unknown>;

src/routes/responses.ts

@@ -461,7 +461,7 @@ export function registerResponsesRoutes(app: Application, ctx: AppContext): void
           ...(top_p !== undefined ? { top_p } : {}),
         },
       };
-      // Stage-5: drop all-disabled maps for free-tier suspects (Zen gate).
+      // Stage-5: strip false entries for free-tier suspects (any false gates; true-only sent, all-false omitted).
       const promptToolOverrides = selectPromptToolOverrides(toolOverrides, pID, mID);
       if (promptToolOverrides) {
         promptParams.body['tools'] = promptToolOverrides;
@@ -861,8 +861,8 @@ export function registerResponsesRoutes(app: Application, ctx: AppContext): void
           }
         }
         const { validCalls: validatedStreamedToolCalls } = finalizeValidatedToolCalls(parsedToolCalls, externalToolRegistry);
-        const safeContent = stripFunctionCallMarkup(stripFunctionCalls(content) as string) as string;
-        const safeReasoning = stripFunctionCallMarkup(stripFunctionCalls(reasoning) as string) as string;
+        const safeContent = stripFunctionCallMarkup(stripFunctionCalls(content));
+        const safeReasoning = stripFunctionCallMarkup(stripFunctionCalls(reasoning));
         if (streamedToolCalls.length === 0) {
           validatedStreamedToolCalls.forEach((toolCall) => {
             const record = toolCall as unknown as Record<string, unknown>;
@@ -1063,8 +1063,8 @@ export function registerResponsesRoutes(app: Application, ctx: AppContext): void
         }
       }
       const { validCalls: validatedToolCalls } = finalizeValidatedToolCalls(parsedToolCalls, externalToolRegistry);
-      const safeContent = stripFunctionCallMarkup(stripFunctionCalls(content) as string) as string;
-      const safeReasoning = stripFunctionCallMarkup(stripFunctionCalls(reasoning) as string) as string;
+      const safeContent = stripFunctionCallMarkup(stripFunctionCalls(content));
+      const safeReasoning = stripFunctionCallMarkup(stripFunctionCalls(reasoning));
 
       // P4: server-side grounding evidence → web_search_call items + citations.
       const searchEvidence = hostedSearch.requested

src/session/ids.ts

@@ -1,6 +1,6 @@
 // Session/message ID format guardrails (Stage-2 mimic work).
 //
-// Upstream facts (opencode@5a8335857b):
+// Upstream facts as of opencode@5a8335857b (re-verify on backend bump):
 // - `x-opencode-session` is minted inside the backend:
 //   `packages/schema/src/session-id.ts` = `"ses_" + descending()`,
 //   where descending = 12 lowercase hex + 14 base62
@@ -15,7 +15,8 @@
 // - The SDK path (`session.create()` with no params) offers no per-request
 //   header passthrough: the gateway CANNOT and MUST NOT forge these IDs.
 //   They are validated here only as a debug drift signal (e.g. backend
-//   version change), never to block a request.
+//   version change), never to block a request. The regexes below are
+//   intentionally strict: a backend format change only emits a debug log.
 const SESSION_SUFFIX = '[0-9a-f]{12}[0-9A-Za-z]{14}';
 
 export const SESSION_ID_RE = new RegExp(`^ses_${SESSION_SUFFIX}$`);