@ebony-vinyl/dsh-our-free-model 2.7.4 → 2.8.0

package/src/upstream.js

@@ -15,34 +15,47 @@
  * Details and the measurements: docs/free-lane-wire.md.
  *
  * Re-verified 2026-10-16 against the **v2** client fingerprint (the shape the
- * official client has sent since 2026-10-14, and the one this module now
- * mirrors). Four facts changed together, and each of them is a 403
- * FreeTierError on its own:
+ * official client has sent since 2026-10-14). The v2 gate compares declared
+ * definitions and headers directly; see the re-verifications in
+ * `src/o2a/` — the port of the reference gateway's shaping — for the current
+ * fact list.
  *
- * | 项 | v1（旧） | v2（现在） |
- * |---|---|---|
- * | User-Agent | `opencode/1.18.31` | `opencode/latest/2.0.26/cli` |
- * | 请求头 | 带 `x-opencode-request` | **不带**（v1 专用头，带了即 403）；另加 `x-session-affinity` / `x-session-id` |
- * | 工具闸门 | `bash`/`glob`/`grep`/`read` 四个名字，各带至少一个 property | **`read` 与 `shell` 两个名字，且 description 与参数 schema 必须与官方客户端逐字一致** |
- * | `tool_choice` | 无工具时补 `none` | **`none` 即 403**，绝不下发 |
-
- * The v2 gate compares the declared definitions themselves, so the old "stub
- * with a placeholder property" trick is refused: the definitions below are
- * verbatim from the v2.0.26 CLI and must not be reworded or reformatted.
- * Source of the shape (live-probed upstream by that project, and the reference
- * this port follows): 9router `open-sse/utils/opencodeFingerprint.js` +
- * `open-sse/executors/opencode.js` at v0.5.104.
+ * **2026-10-31: the shaping layer was replaced with a port of
+ * https://github.com/jasonxu114514/opencode2api v1.4.6** (commit 58f5667), the
+ * reference gateway this lane has tracked since 2026-10-17. The request-shaping
+ * logic no longer lives here: {@link module:src/o2a/version} names the ported
+ * release, and `src/o2a/SYNC.md` maps every Go file to its JS port together
+ * with the deviations this adapter keeps. What changed with the port:
  *
- * Re-verified 2026-10-17 after every request started answering 403: the gate
- * also validates the session id's *encoding*, not only its `ses_…` shape. The
- * twelve hex digits must be the descending `~(ts_ms << 12 | counter)` value with
- * counter 1–63 (low 12 bits `0xfc0–0xfff`); an ascending `ts << 12` value or a
- * sha256 digest is refused with 403 FreeTierError. See
- * {@link SESSION_DESCENDING_RE} and {@link canonicalizeSession}, and the
- * reference implementation at https://github.com/jasonxu114514/opencode2api
- * (`internal/identity/request.go`). A live control on the same egress IP showed
- * that the official 2.0.32 CLI's exact bytes pass while a fresh ascending id
- * 403s, so this is an identity check and not IP rate limiting.
+ * - **Every client tool is renamed to an opaque `clint_<digest>` wire name**
+ *   and the full 13-tool official CLI set is appended from the captured
+ *   `opencode_tools.json` — the free tier refuses bodies that still carry
+ *   another client's tool vocabulary (2026-10-30's two-entry alias table was
+ *   the same discovery in miniature, and is superseded).
+ * - **The official CLI system prompt is injected in full** (base prompt +
+ *   `<env>` + skill listing, per wire), replacing the bare env block; the
+ *   2026-10-28 finding that a bare env block suffices stays true, but the full
+ *   prompt is what the reference sends.
+ * - **Per-request 40-hex `x-opencode-project`** replaces the shared `global`
+ *   bucket: free-tier quota is ledged per project id × egress, so a shared id
+ *   is one shared bucket that arrives pre-burned.
+ * - **Endpoints follow the 2.1 client's provider-family grouping**
+ *   (`/inference/openai/v1/...`, `/inference/anthropic/v1/messages?beta=true`);
+ *   the flat `/inference/v1/...` routes still answer but are the older shape.
+ * - **Chat bodies gain the client's own ceiling** (`max_completion_tokens`
+ *   32000 when the caller named none) and `stream_options.include_usage`.
+ * - **Session minting follows the reference's slow clock** (`src/o2a/identity.js`):
+ *   today's UTC midnight minus a hash-derived offset of at most 30 days, so a
+ *   session's date never leaves the window the upstream accepts — the general
+ *   fix for the 2026-10-28 finding that implausible timestamps answer 429.
+ *   One conversation still maps to one persisted session, and sessions whose
+ *   stored date has drifted out of the accepted window are re-minted.
+ *
+ * The adapter keeps the plugin-specific behaviors the reference has no need
+ * for (each is a listed deviation in SYNC.md): the placeholder note for the
+ * injected officials, `tool_choice: 'none'` stripping (the gate refuses it),
+ * the Responses `auto` default, block identity across prompt injection, and
+ * the idempotence pass for already-shaped bodies.
  *
  * @module src/upstream.js
  */
@@ -51,6 +64,29 @@ import crypto from 'node:crypto'
 import fs from 'node:fs'
 import path from 'node:path'
 import { DATA_DIR_NAME, resolveDshHome } from './store.js'
+// 发布形态唯一导入点：src/o2a.js 由 scripts/build-legacy-payload.mjs 把
+// src/o2a/ 八个模块（官方资产内联）打成单文件；开发/测试直接跑仓库里的产物。
+import {
+  BASE62_ALPHABET,
+  CANONICAL_SESSION_RE,
+  CLIENT_UA,
+  DESCENDING_TIME_RE,
+  O2A_VERSION,
+  ToolRenameMap,
+  canonicalSessionID,
+  ensureChatUsage,
+  ensureV2CompletionLimit,
+  gatewayHeaders as o2aGatewayHeaders,
+  injectOfficialPrompt,
+  isOfficialSessionID,
+  officialTool,
+  phaseAgeMs,
+  randomID,
+  randomProjectID,
+  renameAndCompleteTools,
+  renamableToolName,
+  sessionPhaseMs,
+} from './o2a.js'
 
 /**
  * Overridable so the selftest can point the adapter at a dead port and exercise
@@ -58,97 +94,33 @@ import { DATA_DIR_NAME, resolveDshHome } from './store.js'
  */
 export const UPSTREAM_BASE = process.env.OUR_FREE_MODEL_BASE ?? 'https://opencode.ai'
 
+export { CLIENT_UA }
+
 /**
- * The client User-Agent the v2 gate fingerprints.
- *
- * ⚠️ 形状是 `opencode/<channel>/<version>/<client>`，且 major 必须 ≥ 2；v1 的
- * `opencode/1.18.x` 自 2026-10-14 起被上游按名字拒掉（403 FreeTierError）。
- * ⚠️ 这个值**必须原样单独发出**：v2 的校验是整串匹配，任何前缀/后缀
- * （包括本插件的归属 UA）都会让它不再是「一个 v2 客户端」。归属因此只保留在
- * 其余车道（channel pack / EAC / Kilo），本车道发官方那一串。
+ * Which opencode2api release the shaping layer currently mirrors. Bumped with
+ * `src/o2a/version.js` on every port refresh.
  */
-export const CLIENT_UA = 'opencode/latest/2.0.26/cli'
+export const O2A_PORTED_VERSION = O2A_VERSION
+
 const MAX_SESSION_LENGTH = 256
 const MAX_TOOL_NAME_LEN = 128
-const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+const BASE62 = BASE62_ALPHABET
 
 /**
- * The two tools the v2 free-tier gate requires, with OpenCode's own definitions.
- *
- * ⚠️ **逐字取自 OpenCode v2.0.26 CLI**（与 9router 移植的那份一致）。上游比对
- * description 与 parameters：改写措辞、精简 schema、`properties: {}`、改名都会
- * 换来 403 FreeTierError（v1 时代「桩工具 + 占位 property」的做法已失效）。
- * 不要为了「更好看」动这些字符串。
+ * The names the v2 gate validates verbatim. The full official set now ships
+ * alongside them (see `src/o2a/official-tools.js`); these two are the ones the
+ * gate's tool check is known to read.
  */
-const FINGERPRINT_TOOL_DEFINITIONS = {
-  read: {
-    description: 'Read the contents of a file or directory. Supports text files, images, and PDFs. Images and PDFs are presented directly to the model. Each text line is prefixed by its 1-based line number as <line>: <content>. The prefix is for reference and is not part of the file content. Directory entries are returned one per line. Use offset and limit to read large files or directories in sections. Prefer one larger read over many small slices, and use grep to find specific content in large files.',
-    parameters: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: 'File or directory to read' },
-        offset: { type: 'integer', minimum: 0, description: 'The line or directory entry to start reading from (1-based)' },
-        limit: { type: 'integer', minimum: 0, description: 'The maximum number of lines or directory entries to read (defaults to and capped at 2000)' },
-      },
-      required: ['path'],
-      additionalProperties: false,
-    },
-  },
-  shell: {
-    description: 'Execute a shell command and return its output. Commands run on Linux using bash. Quote file paths containing spaces or special characters. Prefer dedicated tools over shell commands when possible. When output is large, the full result is saved to a file and a truncated preview is returned. Rely on automatic truncation unless filtering the output is more useful. Commands accept an optional timeout, background commands have no timeout by default. Background commands return immediately, and you will be notified when they complete.',
-    parameters: {
-      type: 'object',
-      properties: {
-        command: { type: 'string', description: 'Shell command string to execute' },
-        workdir: { type: 'string', description: 'Working directory to execute the command in. Defaults to the current working directory. When possible, avoid changing directories in the command and set the working directory here instead.' },
-        timeout: { type: 'integer', minimum: 0, description: 'Timeout in milliseconds. Set to 0 to disable the timeout. Defaults to 120000 for foreground commands. Background commands have no timeout by default.' },
-        background: { type: 'boolean', description: 'Run the command in the background and return immediately (useful for dev servers and long-running builds). You do not need to use \'&\' at the end of the command when using this parameter. You will be notified when it completes. DO NOT poll for completion.' },
-      },
-      required: ['command'],
-      additionalProperties: false,
-    },
-  },
-}
-
-/** The names the v2 gate requires to be declared (with the definitions above). */
 export const FINGERPRINT_TOOLS = ['read', 'shell']
 
-/**
- * The note appended when a fingerprint tool had to be injected.
- *
- * ⚠️ v2 的定义是**真工具**（描述与 schema 都来自官方客户端），模型会真的去调它
- * —— 实测把 `read` 用在「/etc 里有什么文件」这种问题上。v1 靠「must not be
- * used」的桩描述压住，v2 只能用提示词压。措辞是实测选出来的：写成「不可用」会让
- * 模型连调用方自己的 `Read`/`Bash` 也一起拒绝；「占位、请用别的工具」才既压住
- * 注入项、又不误伤调用方的工具。
- */
-function placeholderNote(names) {
-  const list = names.map(name => `\`${name}\``).join(' or ')
-  return names.length > 1
-    ? `Do not call the ${list} tools; they are placeholders that do nothing. Use the other tools you have been given instead.`
-    : `Do not call the ${list} tool; it is a placeholder that does nothing. Use the other tools you have been given instead.`
-}
-
 /** Models served by /responses instead of /chat/completions. */
 const RESPONSES_MODELS = new Set(['muse-spark-1.2-contributor-free', 'muse-spark-1.3-contributor-free'])
 /** Models served by the Anthropic-shaped /messages endpoint. */
 const MESSAGES_MODELS = new Set(['union-alpha'])
 
-export const SESSION_RE = /^ses_[0-9a-f]{12}[0-9A-Za-z]{14}$/
+export const SESSION_RE = CANONICAL_SESSION_RE
 
-/**
- * The time half of a canonical session id the upstream free tier actually accepts.
- *
- * ⚠️ 形状对还不够（2026-10-17 实测）：官方客户端用 `Identifier.descending()`
- * 铸造时间戳 —— 48 位的 `~(ts_ms << 12 | counter)`，取反把低 12 位变成
- * `0xFFF - counter`。上游只放行 counter 1–63，即低 12 位落在 `0xfc0–0xfff`
- * （前 9 位任意 hex，第 10 位 `c`–`f`，后两位任意）。任何其它编码 —— 包括
- * `ts_ms << 12` 这种升序写法、以及 sha256 摘要 —— 即使 `ses_` 形状完全正确，
- * 也会被 403 FreeTierError 拒掉。参考实现：
- * https://github.com/jasonxu114514/opencode2api `internal/identity/request.go`
- * （`descendingTimePartPattern`）。
- */
-export const SESSION_DESCENDING_RE = /^[0-9a-f]{9}f[c-f][0-9a-f]$/
+export const SESSION_DESCENDING_RE = DESCENDING_TIME_RE
 
 /** Whether `id` is a session the upstream free tier will accept as-is. */
 export function isCanonicalSession(id) {
@@ -156,37 +128,17 @@ export function isCanonicalSession(id) {
 }
 
 /**
- * Re-encode any session id into the descending layout the gate accepts, keeping
- * one conversation pinned to one upstream session.
- *
- * The digest is the same `ses\0<signal>` sha256 the reference gateway uses, so a
- * given downstream conversation always maps to the same upstream id. Counter 1
- * keeps the low 12 bits at `0xffe`, inside the accepted window.
+ * Re-encode any session signal into the canonical layout the gate accepts,
+ * keeping one signal on one session for the life of the process
+ * (`o2a/identity.canonicalSessionID`): official sessions pass through, and a
+ * synthesized one carries a slow-clock timestamp inside the window the
+ * upstream accepts, salted per process so a restart re-mints.
  */
 export function canonicalizeSession(signal) {
-  const digest = crypto.createHash('sha256').update(`ses\0${signal}`).digest()
-  const current = ((BigInt(digest[0]) << 28n | BigInt(digest[1]) << 20n | BigInt(digest[2]) << 12n |
-    BigInt(digest[3]) << 4n | BigInt(digest[4]) >> 4n) << 12n) | 1n
-  const inverted = ~current & 0xffffffffffffn
-  const timeHex = inverted.toString(16).padStart(12, '0')
-  return `ses_${timeHex}${base62Fixed(digest.subarray(6, 16), 14)}`
-}
-
-/** Render `bytes` as exactly `width` base62 characters (big-endian). */
-function base62Fixed(bytes, width) {
-  let n = 0n
-  for (const byte of bytes) n = (n << 8n) | BigInt(byte)
-  const base = 62n
-  const out = new Array(width)
-  for (let i = width - 1; i >= 0; i -= 1) {
-    out[i] = BASE62[Number(n % base)]
-    n /= base
-  }
-  return out.join('')
+  return canonicalSessionID(signal)
 }
 
-const ANTHROPIC_API_VERSION = '2023-06-01'
-
+/** Render `bytes` as base62, one character per byte (`base62From`). */
 function base62From(bytes) {
   let out = ''
   for (const byte of bytes) out += BASE62[byte % 62]
@@ -199,9 +151,9 @@ let seq = 0
 /**
  * Mint a gateway-shaped canonical session id (time-prefixed, monotonic counter).
  *
- * The encoding is the gate's: `~(ts_ms * 0x1000 + counter)`, whose low 12 bits
- * land at `0xfff - counter`. The counter resets every millisecond, so a burst of
- * mints inside one millisecond stays inside the accepted 1–63 window.
+ * Kept for bookkeeping and tests: the free lane mints through
+ * {@link canonicalizeSession} now. The encoding is the gate's:
+ * `~(ts_ms * 0x1000 + counter)`, whose low 12 bits land at `0xfff - counter`.
  */
 export function mintSessionId(timestamp = Date.now()) {
   if (timestamp !== lastStamp) { lastStamp = timestamp; seq = 0 }
@@ -225,6 +177,16 @@ export function mintRequestId(timestamp = Date.now()) {
   return `msg_${hex}${base62From(crypto.randomBytes(14))}`
 }
 
+/**
+ * The phase age a kept session may carry. The wire's time part is a 36-bit
+ * millisecond phase (~795-day cycle, see o2a/identity.js), and the slow clock
+ * mints phases at most 30 days old; a 60-day ceiling accepts every id this
+ * lane mints (active conversations keep theirs indefinitely) while re-minting
+ * the pre-port ids, whose hash-derived phase landed uniformly across the whole
+ * cycle.
+ */
+const SESSION_PLAUSIBILITY_MS = 60 * 24 * 60 * 60 * 1000
+
 const SESSION_MAP_FILE = 'session-map.json'
 let sessions
 
@@ -258,26 +220,35 @@ function rememberSession(seed, id) {
   } catch { /* non-fatal: the id still works, it just will not survive a restart */ }
 }
 
+/**
+ * Whether a canonical session's embedded time phase is inside the accepted
+ * window. The wire carries a 36-bit millisecond phase (see
+ * `o2a/identity.js`), not an absolute date, so plausibility is "dated within
+ * the last month of the current phase cycle" — exactly what the slow clock
+ * mints and what a hash-derived 1970 landing (the pre-port ids) almost never
+ * satisfies.
+ */
+function plausibleSession(id) {
+  const phase = sessionPhaseMs(id)
+  return phase !== null && phaseAgeMs(phase) < SESSION_PLAUSIBILITY_MS
+}
+
 /**
  * Map one downstream conversation onto one stable upstream session.
  *
- * Mint once using a real creation timestamp and persist the result. Never
- * rotate IDs on retries or model errors. A caller's canonical OC ID is kept.
- *
- * Live A/B controls on 2026-10-28: hash-derived pseudo timestamps returned429
- * even for an unused ID; a real timestamp returned200 and repeated use of that
- * same ID also returned200. Structural regex validation alone is insufficient.
- * Legacy deterministic mappings are migrated once on use; other remembered
- * canonical IDs remain unchanged, including across restarts.
+ * Mint once and persist the result. Never rotate IDs on retries or model
+ * errors. A caller's canonical OC ID is kept. Since the o2a port, a minted id
+ * carries a slow-clock date inside the window the upstream accepts, and a
+ * remembered id whose date has left that window — an id carried over from the
+ * pre-port era, whose hash-derived timestamp landed outside it and answered
+ * 429 (live A/B, 2026-10-28) — is re-minted instead of replayed.
  */
 export function sessionForConversation(sessionId) {
   if (typeof sessionId === 'string' && isCanonicalSession(sessionId)) return sessionId.trim()
   const seed = typeof sessionId === 'string' && sessionId.trim() ? sessionId.trim() : 'global'
   const remembered = loadSessions().get(seed)
-  // A hash-derived pseudo timestamp has the right shape but is not a real
-  // creation time. Migrate exactly that old mapping once; preserve real IDs.
-  if (remembered !== undefined && isCanonicalSession(remembered) && remembered !== canonicalizeSession(seed)) return remembered
-  const minted = mintSessionId()
+  if (remembered !== undefined && isCanonicalSession(remembered) && plausibleSession(remembered)) return remembered
+  const minted = canonicalizeSession(seed)
   rememberSession(seed, minted)
   return minted
 }
@@ -302,49 +273,45 @@ export function isMessagesModel(modelId) {
 }
 
 /**
- * Which upstream path serves this model. The free lane lives under
- * `/inference/v1` (measured 2026-10-14, and the shape the console's model table
- * documents); `/zen/v1` chat completions answer 403 FreeTierError for free ids.
+ * Which upstream path serves this model.
+ *
+ * The 2.1 client groups `/inference` routes by provider family, so the family
+ * segment sits between the origin and the protocol path (a 2.0.32 client
+ * posted the protocol path directly, and that flat route still answers — the
+ * reference gateway sends the family form, so this lane does too). Anthropic
+ * endpoints additionally carry the beta query the client appends.
  */
 export function endpointFor(modelId) {
-  if (isResponsesModel(modelId)) return '/inference/v1/responses'
-  if (isMessagesModel(modelId)) return '/inference/v1/messages'
-  return '/inference/v1/chat/completions'
+  if (isResponsesModel(modelId)) return '/inference/openai/v1/responses'
+  if (isMessagesModel(modelId)) return '/inference/anthropic/v1/messages?beta=true'
+  return '/inference/openai/v1/chat/completions'
 }
 
 /** The wire shape one endpoint speaks; drives request encoding and response parsing. */
 export function wireFor(modelId) {
-  const path = endpointFor(modelId)
-  if (path === '/inference/v1/responses') return 'responses'
-  if (path === '/inference/v1/messages') return 'messages'
+  if (isResponsesModel(modelId)) return 'responses'
+  if (isMessagesModel(modelId)) return 'messages'
   return 'chat'
 }
 
 /**
- * The headers the gateway fingerprints a genuine client by.
- * `Authorization: Bearer public` is the pooled免密 credential — there is no
- * per-user secret on this lane.
+ * The headers the gateway fingerprints a genuine client by — the v2 set
+ * (`o2a/headers.js`), with the pooled免密 credential `Bearer public`.
  *
- * ⚠️ v2 形状（2026-10-14 起），与官方客户端逐项对齐：
- * - `x-opencode-session` 与 `x-opencode-session-id` 必须同时存在（缺一即 403）；
- * - `x-session-affinity` / `x-session-id` 是 v2 新增的同值镜像；
- * - **不带 `x-opencode-request`** —— 那是 v1 专用头，v2 收到就回 403；
- * - `x-opencode-client: cli` 与官方 CLI 一致。
+ * @param {object} options
+ * @param {string} options.session - canonical session (all four session headers)
+ * @param {boolean} [options.stream] - drives the default `accept`
+ * @param {string} [options.accept] - explicit `accept` override
+ * @param {string} [options.project] - caller project signal; **defaults to a
+ *   fresh 40-hex id per request**, the quota-spread the reference mints when
+ *   the client names no project (the old shared `global` bucket arrived
+ *   pre-burned). A literal `global` or 40-hex commit passes through verbatim.
+ * @param {string} [options.childSession] - child session for
+ *   `x-opencode-session-id`; defaults to `session`
+ * @param {boolean} [options.anthropic] - add the Messages-lane beta header
  */
-export function gatewayHeaders({ session, stream, accept }) {
-  const headers = {
-    'content-type': 'application/json',
-    'authorization': 'Bearer public',
-    'user-agent': CLIENT_UA,
-    'x-opencode-client': 'cli',
-    'x-opencode-session': session,
-    'x-opencode-session-id': session,
-    'x-session-affinity': session,
-    'x-session-id': session,
-    'x-opencode-project': 'global',
-    'accept': accept ?? (stream ? 'text/event-stream' : '*/*'),
-  }
-  return headers
+export function gatewayHeaders(options) {
+  return o2aGatewayHeaders(options)
 }
 
 function toolNameOf(tool) {
@@ -355,128 +322,59 @@ function toolNameOf(tool) {
   return ''
 }
 
-/**
- * The gate name when the tool's name is **exactly** one of the two; `''` otherwise.
- *
- * ⚠️ 大小写变体（`Read`/`Shell`）**不算**闸门工具，原样透传：上游接受它们与
- * 注入的 `read`/`shell` 并存（实测），而 v1 那种「按小写归并」会把调用方的
- * `Read` 改名成 `read`，正好撞上 v2 的「定义必须逐字一致」判定。
- */
-function fingerprintKey(name) {
-  const trimmed = String(name ?? '').trim()
-  return FINGERPRINT_TOOLS.includes(trimmed) ? trimmed : ''
-}
-
-/** The Chat-shape `{function:{…}}` wrapper, or null for the flat Responses one. */
-function functionOf(tool) {
-  return tool.function && typeof tool.function === 'object' && !Array.isArray(tool.function) ? tool.function : null
-}
-
-/** Where a tool's description and parameter schema sit for one wire shape. */
-function definitionOf(tool, { claude, flat }) {
-  const wrapper = claude || flat ? tool : functionOf(tool)
-  if (wrapper === null || wrapper === undefined) return null
-  return { description: wrapper.description, schema: claude ? wrapper.input_schema : wrapper.parameters }
+/** The shape name one `style` argument speaks. */
+function shapeOf(style) {
+  return style === true ? 'flat' : style === 'claude' ? 'claude' : 'chat'
 }
 
-/** Does this tool already carry OpenCode's own definition for `name`? */
-function carriesFingerprintDefinition(tool, name, shape) {
-  const own = definitionOf(tool, shape)
+/** Does this entry carry the verbatim official definition for `name`?
+ *
+ * Compared against the **rendered** official tool — the shell description is
+ * platform-aware (`v2ShellDescription`), so on a Windows host a verbatim
+ * official shell says powershell while the raw asset says bash. */
+function carriesOfficialDefinition(entry, name, shape) {
+  const own = definitionOf(entry, shape)
   if (own === null) return false
-  const want = FINGERPRINT_TOOL_DEFINITIONS[name]
-  return own.description === want.description
-    && JSON.stringify(own.schema) === JSON.stringify(want.parameters)
-}
-
-function withToolName(tool, name) {
-  const fn = functionOf(tool)
-  return fn ? { ...tool, function: { ...fn, name } } : { ...tool, name }
+  const rendered = officialTool(shape, name)
+  const wrapper = shape === 'chat' ? rendered.function : rendered
+  if (!wrapper) return false
+  return own.description === wrapper.description
+    && JSON.stringify(own.schema) === JSON.stringify(wrapper.parameters)
 }
 
-/** The gate's own declaration, in the shape the wire expects. */
-function fingerprintTool(name, { claude, flat }) {
-  const { description, parameters } = FINGERPRINT_TOOL_DEFINITIONS[name]
-  if (claude) return { name, description, input_schema: parameters }
-  if (flat) return { type: 'function', name, description, parameters }
-  return { type: 'function', function: { name, description, parameters } }
-}
-
-/** `sent name -> caller's name` for every tool the alias pass renamed. */
-function aliasesByOriginal(map) {
-  return new Map([...map].map(([alias, original]) => [original, alias]))
-}
-
-/**
- * Point an explicit `tool_choice` at the alias of a tool that was renamed.
- *
- * Only an alias is retargeted: a choice naming a tool we left alone must stay
- * byte-identical, and `none` is never emitted (see {@link applyFingerprint}).
- */
-function retargetToolChoice(body, map) {
-  if (!body || typeof body !== 'object' || map.size === 0) return
-  const choice = body.tool_choice
-  if (!choice || typeof choice !== 'object' || Array.isArray(choice)) return
-  const aliases = aliasesByOriginal(map)
-  if (typeof choice.name === 'string') {
-    const alias = aliases.get(choice.name.trim())
-    if (alias !== undefined) body.tool_choice = { ...choice, name: alias }
-    return
-  }
-  const fn = choice.function
-  if (fn && typeof fn === 'object' && !Array.isArray(fn) && typeof fn.name === 'string') {
-    const alias = aliases.get(fn.name.trim())
-    if (alias !== undefined) body.tool_choice = { ...choice, function: { ...fn, name: alias } }
-  }
+/** Where a tool's description and parameter schema sit for one wire shape. */
+function definitionOf(entry, shape) {
+  if (!entry || typeof entry !== 'object') return null
+  const wrapper = shape === 'chat' ? entry.function : entry
+  if (wrapper === null || wrapper === undefined || typeof wrapper !== 'object') return null
+  const schema = shape === 'claude' ? wrapper.input_schema : wrapper.parameters
+  return { description: wrapper.description, schema }
 }
 
 /**
- * Rename prior-turn calls to a renamed tool in the history we are about to send.
+ * The note appended when official tools had to be injected.
  *
- * Without this the model reads its own earlier `read` calls as calls to
- * OpenCode's injected tool of that name, and the two definitions disagree.
+ * ⚠️ v2 的定义是**真工具**（描述与 schema 都来自官方客户端），模型会真的去调它
+ * —— 实测把 `read` 用在「/etc 里有什么文件」这种问题上。本插件的宿主并不实现
+ * 官方工具集，注入项必须用提示词压住。措辞是实测选出来的：写成「不可用」会让
+ * 模型连调用方自己的 `Read`/`Bash` 也一起拒绝；「占位、请用别的工具」才既压住
+ * 注入项、又不误伤调用方的工具。（参考实现不发这条 —— 它的下游是真 CLI ——
+ * 这是本适配层的既列偏差，见 src/o2a/SYNC.md。）
  */
-function aliasHistoryToolCalls(body, map) {
-  if (!body || typeof body !== 'object' || map.size === 0) return
-  const aliases = aliasesByOriginal(map)
-  const rename = name => (typeof name === 'string' && aliases.has(name) ? aliases.get(name) : name)
-
-  if (Array.isArray(body.input)) {
-    body.input = body.input.map(item => item?.type === 'function_call' && aliases.has(item.name)
-      ? { ...item, name: aliases.get(item.name) }
-      : item)
-  }
-  if (Array.isArray(body.messages)) {
-    body.messages = body.messages.map(message => {
-      if (message === null || typeof message !== 'object') return message
-      let next = message
-      if (Array.isArray(message.content)) {
-        const content = message.content.map(block => block?.type === 'tool_use' && aliases.has(block.name)
-          ? { ...block, name: aliases.get(block.name) }
-          : block)
-        next = { ...next, content }
-      }
-      if (Array.isArray(message.tool_calls)) {
-        next = {
-          ...next,
-          tool_calls: message.tool_calls.map(call => aliases.has(call?.function?.name)
-            ? { ...call, function: { ...call.function, name: aliases.get(call.function.name) } }
-            : call),
-        }
-      }
-      return next
-    })
-  }
+function placeholderNote(names) {
+  const list = names.map(name => `\`${name}\``).join(', ')
+  return `The tools ${list} are part of the host CLI's own toolset and are placeholders in this session; they do nothing here. Use the other tools you have been given instead.`
 }
 
 /** Add free-lane context without replacing the caller's system text or blocks. */
-function appendSystemContext(body, { claude, flat }, note) {
-  if (flat) {
+function appendSystemContext(body, shape, note) {
+  if (shape === 'flat') {
     body.instructions = typeof body.instructions === 'string' && body.instructions.trim() !== ''
       ? `${body.instructions}\n\n${note}`
       : note
     return
   }
-  if (claude) {
+  if (shape === 'claude') {
     body.system = Array.isArray(body.system)
       ? [...body.system, { type: 'text', text: note }]
       : typeof body.system === 'string' && body.system !== '' ? `${body.system}\n\n${note}` : note
@@ -495,7 +393,7 @@ function appendSystemContext(body, { claude, flat }, note) {
   body.messages = [{ role: 'system', content: note }, ...messages]
 }
 
-/** Tell the model injected tools are placeholders; never replace caller blocks. */
+/** Tell the model the injected officials are placeholders; never replace caller blocks. */
 function noteInjectedTools(body, shape, names) {
   appendSystemContext(body, shape, placeholderNote(names))
 }
@@ -505,13 +403,17 @@ function noteInjectedTools(body, shape, names) {
  * Reversible live controls (2026-10-28) returned 429 without it and PONG with it.
  * Use truthful process metadata, not a copied OC persona or a user workspace guess.
  * A caller's existing environment block takes precedence and is kept unchanged.
+ *
+ * Kept for its standalone contract (and the escaping guarantee); the shaping
+ * pass now injects the full official prompt — which carries the same env block
+ * — instead of this bare one.
  */
 export function ensureFreeLaneEnvironment(body, style, environment = {}) {
-  const shape = { flat: style === true, claude: style === 'claude' }
+  const shape = shapeOf(style)
   const textOf = value => typeof value === 'string' ? value
     : Array.isArray(value) ? value.map(part => part?.text ?? '').join('\n') : ''
-  const existing = shape.flat ? textOf(body.instructions)
-    : shape.claude ? textOf(body.system)
+  const existing = shape === 'flat' ? textOf(body.instructions)
+    : shape === 'claude' ? textOf(body.system)
       : (Array.isArray(body.messages) ? body.messages : []).filter(message => message?.role === 'system' || message?.role === 'developer').map(message => textOf(message.content)).join('\n')
   if (/<env>[\s\S]*?<\/env>/i.test(existing)) return
   const line = value => String(value).replace(/[\r\n<>]/g, ' ')
@@ -520,109 +422,73 @@ export function ensureFreeLaneEnvironment(body, style, environment = {}) {
   appendSystemContext(body, shape, `Here is some useful information about the environment you are running in:\n<env>\n  Working directory: ${line(cwd)}\n  Platform: ${line(platform)}\n</env>`)
 }
 
-// Reproduced from a real DSH request (2026-10-30): subagent_fork alone, and
-// read_image together with working_directory, received 429. Renaming only the
-// two entries below restored the complete 80-tool request. Keep all capabilities
-// and schemas; map wire names back before the harness dispatches a tool call.
-const FREE_LANE_TOOL_ALIASES = Object.freeze({
-  subagent_fork: 'conversation_delegate',
-  working_directory: 'workspace_directory',
-})
-
 /**
- * Satisfy the v2 free-tier fingerprint gate on `body.tools`.
+ * Satisfy the v2 free-tier fingerprint on `body`, shaped as the reference
+ * gateway shapes it (opencode2api v1.4.6, see the module header):
  *
- * ## v2 规则（每条都对应一次 403，见模块头）
- *
- * 1. `read` 与 `shell` 必须**声明**，且定义与官方客户端逐字一致；
- * 2. 调用方的工具**原样保留**（含 `Read`/`Bash` 这类大小写变体）；
- * 3. 调用方若**正好**用了 `read`/`shell` 这个名字但定义不同，它被改名成
- *    `<name>_client[N]` 并走 {@link aliasHistoryToolCalls}/{@link retargetToolChoice}
- *    同步历史与 `tool_choice`，响应侧再由重命名表还原成调用方的名字；
- * 4. 同名重复声明只留第一个（上游按重复拒）；
+ * 1. **官方系统提示注入**：base prompt + `<env>` + skills，逐线注入（Chat 折到
+ *    首条 system，Responses 折到 `instructions`，Messages 折到 `system`）；
+ *    已带官方标记的请求体原样跳过。
+ * 2. **全部调用方工具改名** 为 `clint_<sha256[:12]>`（外来工具词汇一概不上
+ *    线——`ReportFindings`/`ScheduleWakeup` 同时出现即 429，2026-10-30 实测）；
+ *    Responses 内建与 Messages 服务端工具无客户名，原样保留。
+ * 3. **补齐官方 13 工具集**（捕获自官方 CLI 的逐字定义，chat 形状带
+ *    `strict: false`，Windows 主机 shell 描述换 powershell）；已带逐字官方
+ *    定义的声明视为官方声明，不重命名也不重复补。
+ * 4. **引用同步**：`tool_choice`、历史 tool_calls / tool_use / function_call、
+ *    Responses 的 `input` 调用行全部跟随改名；字符串 choice 原样透传。
  * 5. **绝不下发 `tool_choice: 'none'`** —— v2 见到它就 403；调用方没给
  *    `tool_choice` 时，只有 Responses 线补 `auto`（官方行为）。
- *
- * ⚠️ v1 的「把调用方的 shell 提升成 `bash` 槽位」已删除：v2 比对定义，提升会让
- * 槽位定义与官方不符（403），而调用方自己的 `pwsh`/`Bash` 本来就能被调用。
+ * 6. Chat 请求体补上官方客户端的两个常量字段：流式时
+ *    `stream_options.include_usage: true`；调用方未给上限时
+ *    `max_completion_tokens: 32000`。
  *
  * @param {object} body - request body, mutated in place
  * @param {boolean|'claude'} style - true 为 Responses，false 为 Chat，claude 为 Messages
- * @returns {Map<string, string>} sent name -> caller's name (for the response side)
+ * @returns {ToolRenameMap} sent name -> caller's name（响应侧还原用；带
+ *   {@link ToolRenameMap.resolve} 的折叠还原）
  */
 export function applyFingerprint(body, style) {
-  const flat = style === true
-  const claude = style === 'claude'
-  const shape = { claude, flat }
-  const map = new Map()
-  const tools = Array.isArray(body.tools) ? body.tools : []
-  const taken = new Set(tools.map(toolNameOf).filter(name => name !== ''))
-  // 两个集合分工不同：`seen` 只用于「同名重复留第一个」（含被改名的那个名字），
-  // `present` 记录**真正带官方定义留下来**的门禁名 —— 注入判据必须看后者，
-  // 否则「调用方的 read 被改成 read_client」会被误判成「read 已经声明」，
-  // 官方定义反而不会补上（门禁仍然 403）。
-  const seen = new Set()
-  const present = new Set()
-  const out = []
-  const compatibilityAliases = []
+  const shape = shapeOf(style)
+  if (!body || typeof body !== 'object') return new ToolRenameMap()
+
+  // 1. Official system prompt (the reference injects before shaping tools).
+  injectOfficialPrompt(body, shape)
 
+  // 2.+3. Tool pass: rename client tools, append the official set. Tools that
+  // already carry the verbatim official definition are declared officials —
+  // kept as-is and not duplicated — so repeated shaping stays a no-op.
+  const tools = Array.isArray(body.tools) ? body.tools : []
+  const keep = new Set()
   for (const tool of tools) {
-    const name = toolNameOf(tool)
-    const compatibilityBase = Object.hasOwn(FREE_LANE_TOOL_ALIASES, name) ? FREE_LANE_TOOL_ALIASES[name] : undefined
-    if (compatibilityBase !== undefined) {
-      let alias = compatibilityBase
-      for (let i = 2; taken.has(alias); i += 1) alias = `${compatibilityBase}${i}`
-      taken.add(alias)
-      map.set(alias, name)
-      compatibilityAliases.push({ alias, original: name })
-      out.push(withToolName(tool, alias))
-      continue
+    const name = renamableToolName(shape, tool)
+    if (name !== null && carriesOfficialDefinition(tool, name, shape)) {
+      keep.add(name)
     }
-    const key = fingerprintKey(name)
-    if (key === '') { out.push(tool); continue }
-    // 同名重复声明：上游按重复拒，留第一个。
-    if (seen.has(key)) continue
-    seen.add(key)
-    if (carriesFingerprintDefinition(tool, key, shape)) {
-      out.push(tool)
-      present.add(key)
-      continue
-    }
-    let alias = `${key}_client`
-    for (let i = 2; taken.has(alias); i += 1) alias = `${key}_client${i}`
-    taken.add(alias)
-    map.set(alias, name)
-    out.push(withToolName(tool, alias))
-  }
-
-  const injected = []
-  for (const name of FINGERPRINT_TOOLS) {
-    if (present.has(name)) continue
-    out.push(fingerprintTool(name, shape))
-    injected.push(name)
   }
+  const { renames, injected } = renameAndCompleteTools(body, shape, { keep })
 
-  body.tools = out
-  retargetToolChoice(body, map)
-  aliasHistoryToolCalls(body, map)
-  ensureFreeLaneEnvironment(body, style)
+  // 4b. The injected officials need the placeholder note.
   if (injected.length > 0) noteInjectedTools(body, shape, injected)
-  if (compatibilityAliases.length > 0) {
-    appendSystemContext(body, shape, `Tool name mapping for this request: ${compatibilityAliases.map(({ alias, original }) => `use \`${alias}\` for \`${original}\``).join('; ')}. These tools retain their original behavior and parameters.`)
-  }
-  // ⚠️ v2 见到 `tool_choice: 'none'` 就回 403（v1 允许，旧代码甚至主动补过它）。
-  // 兜底清除：调用方（续写路径等）留下的 `none` 会让整轮失败。
+
+  // 5. Never ship tool_choice none; default the Responses wire to auto.
   if (body.tool_choice === 'none'
     || (body.tool_choice !== null && typeof body.tool_choice === 'object' && body.tool_choice.type === 'none')) {
     delete body.tool_choice
   }
-  if (flat && !body.tool_choice) body.tool_choice = 'auto'
-  return map
+  if (shape === 'flat' && !body.tool_choice) body.tool_choice = 'auto'
+
+  // 6. The chat body's own constants.
+  ensureChatUsage(body, shape)
+  ensureV2CompletionLimit(body, shape)
+  return renames
 }
 
 /** Restore the caller's tool spelling in a streaming delta or a final payload. */
 export function restoreToolName(name, map) {
-  if (!map || map.size === 0) return name
+  if (!map) return name
+  if (typeof map.resolve === 'function') return map.resolve(name)
+  if (map.size === 0) return name
   return map.get(name) ?? name
 }
 
@@ -642,4 +508,15 @@ function truncateSession(value) {
   return trimmed.length > MAX_SESSION_LENGTH ? trimmed.slice(0, MAX_SESSION_LENGTH) : trimmed
 }
 
-export { truncateSession, ANTHROPIC_API_VERSION, MAX_TOOL_NAME_LEN }
+/** The Anthropic API version the Messages lane sends. */
+const ANTHROPIC_API_VERSION = '2023-06-01'
+
+export { truncateSession, randomID, randomProjectId, MAX_TOOL_NAME_LEN, ANTHROPIC_API_VERSION }
+
+/**
+ * A fresh per-request project id, exposed for callers that want to pin the
+ * same id across a retried turn. The lane default is one per request.
+ */
+function randomProjectId() {
+  return randomProjectID()
+}