vanspod 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,75 @@
-# Temporary Holding Version
+# VansPod
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+VansPod 是 Windows 學生使用的本機課堂入口。提供含 Node runtime 的單檔 `VansPod.exe`，以及給已有 Node.js 24 以上環境的 npm 套件；兩者共用同一個背景服務和學生設定。
+
+## 學生操作
+
+雙擊 exe 或執行 `vanspod start`，會啟動背景服務並開啟瀏覽器。再開一次會回到既有畫面；關閉瀏覽器或啟動用終端機不會停止課堂代理。Windows 右下角的 VansPod logo 可重新開啟畫面，右鍵「結束 VansPod」可恢復客戶端個人設定後退出。電腦重新啟動後須手動開啟，不設定開機自動啟動。
+
+公開 npm 發佈完成後，學生可使用下列安裝方式；本機打包不代表套件已上架：
+
+```powershell
+npm install -g vanspod
+vanspod start
+```
+
+| 指令 | 用途 |
+| --- | --- |
+| `vanspod` / `vanspod start` | 啟動並開啟瀏覽器，或開啟既有畫面 |
+| `vanspod status` | 顯示是否執行中、執行版本、PID 與本機網址 |
+| `vanspod stop` | 恢復客戶端設定後結束，保留課堂連線與模式記憶 |
+| `vanspod uninstall` | 列出刪除內容，確認後完整移除 |
+| `vanspod --version` / `vanspod --help` | 顯示安裝版本／說明，不啟動服務 |
+
+安裝環境或課程專案時不能結束或移除。模型回答中須確認中斷；命令列無法互動確認時保持執行。設定恢復失敗會保留服務與備份，顯示失敗的客戶端並允許重試。
+
+完整移除請用頁面的「移除 VansPod」或 `vanspod uninstall`。這會先恢復客戶端設定，再清理 VansPod 憑證、偏好、日誌、暫存與已登記的 exe／npm 安裝；保留學生作品、課程專案、Node、Git、VS Code 和客戶端個人設定。結果以 Windows 訊息顯示，刪除失敗會保留移除工具和失敗項目供重試；未登記的其他 exe 副本須自行刪除。直接刪 exe 或 `npm uninstall -g vanspod` 無法保證完整清理。
+
+更新前先結束 VansPod。exe 下載指定版本替換，npm 使用 `npm install -g vanspod@<老師指定版本>`；兩者使用相同版本號，上課途中不自動更新。開啟入口與執行版本不同時會提示，先結束才能換版。
+
+## 開發與本機打包
+
+```powershell
+npm install
+npm run typecheck
+npm test
+npm start
+npm run dist
+npm pack --pack-destination dist
+```
+
+exe 產物為 `dist/VansPod.exe`，本機套件為 `dist/vanspod-0.1.2.tgz`；可在 Windows 用 `npm install -g <套件路徑>` 安裝測試。圖片、favicon、系統匣與移除腳本均包含在發佈產物中。更新 logo 後執行 `powershell.exe -NoProfile -File scripts/build-icon.ps1` 重建多尺寸 Windows icon。
+
+exe 發佈管道為本專案 GitHub Releases，npm 為公開 registry；正式上架需先確認套件名稱及發佈帳號權限。更新時不要執行完整移除，否則會清除課堂資料。
+
+## GitHub Actions 發佈 exe
+
+一般 push 不發佈；推送 `v*` tag 會在 Windows runner 安裝 Node.js 24、檢查型別、執行測試、打包並驗證 exe／npm 生命週期，全部通過後才建立 GitHub Release。學生從 Release 下載 `VansPod.exe`，同頁提供 `SHA256SUMS.txt`。此流程不會發佈 npm 套件。
+
+發版前同步 `package.json`、`package-lock.json` 與 `src/version.ts` 的版本；tag 必須等於 `v` 加版本號，否則流程失敗。以 `0.1.2` 為例：
+
+```powershell
+git push origin master
+git tag -a v0.1.2 -m "VansPod 0.1.2"
+git push origin v0.1.2
+```
+
+新版本使用新的版本號與 tag。相同 tag 的 Actions 重跑會更新該 Release 的產物。
+
+本機課堂 app。規格是 [classroom-one-click-install#8](https://github.com/mz038197/classroom-one-click-install/issues/8)。
+
+不放進凡思課堂安裝擴充，也不從 opencodex fork。領域詞以該 repo 的 CONTEXT.md 為準。視窗決定見該 repo 的 ADR 0017。
+
+設計與操作邊界見 [ADR-0008](docs/adr/0008-student-distribution-and-lifecycle.md)。
+
+## Classroom 上游 API
+
+模型區提供各客戶端的上游 API 選項：Codex 可選 Responses／Chat，Claude Code 可選 Responses／Chat／Messages，兩者均預設 Responses。選擇保存在使用者目錄的 `.vanspod/settings.json`，與課堂憑證分開；重啟、切換模型、清除或重新兌換課堂不會移除偏好。此選項只影響 Classroom 模式的下一個請求。
+
+共用 Adapter 介面下的三個實作負責請求、上游呼叫與回應轉換；所有程式都在 VansPod 內，不需要 opencodex 專案。支援多輪文字、圖片輸入、函式工具往返與串流／非串流；Chat 路徑沿用 Codex 自訂工具的文字包裝及 `apply_patch` 修復。
+
+跨協定不能對等保留的資料會明確報錯，例如 Claude 的 thinking／簽章、工具結果的 `is_error`、快取控制或服務端工具，以及 Codex 的加密 reasoning 或工具 namespace。Chat 自訂工具將完整的 Lark／regex grammar 定義保留在 input schema 的描述中，作為模型指令；Chat 不提供 Responses 原生 grammar 的受限解碼保證。原協定直通可保留其原有資料；轉換失敗不會自動換 adapter 重送。使用者取消或客戶端斷線會中止本機上游請求，串流缺少完成事件會回報失敗。
+
+協定轉換參考官方 [Chat API](https://developers.openai.com/api/reference/resources/chat)、[Responses API](https://developers.openai.com/api/reference/resources/responses) 與 [Claude 串流事件](https://platform.claude.com/docs/en/build-with-claude/streaming)。
+
+驗證指令：`npm run typecheck`、`npm test`、`npm run test:windows-exe`。Windows 驗證使用隔離的合成 USERPROFILE／APPDATA 與模擬 Router，涵蓋三個 Client Route、47821～47823／自訂 base port、port collision、獨立模式與 adapter、client-native catalog、失敗恢復，以及五條 JSON／SSE adapter 路徑；測試前後亦確認真實使用者設定未變。通過不表示實際 Router 或模型已完成端到端驗證。

package/bin/register.cjs

@@ -0,0 +1,11 @@
+// Register a packaged install without starting the classroom service. A source
+// checkout has not been compiled during npm install and needs no registration.
+const fs = require('node:fs');
+const path = require('node:path');
+const entry = path.join(__dirname, '../dist/installations.js');
+if (fs.existsSync(entry)) {
+  require(entry).registerInstallation().catch(error => {
+    process.stderr.write(`VansPod 安裝紀錄無法保存：${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/bin/vanspod.cjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/entry.js');

package/dist/adapterSettings.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultAdapters = defaultAdapters;
+exports.isAdapterChoice = isAdapterChoice;
+exports.createAdapterSettingsStorage = createAdapterSettingsStorage;
+const clientRoutes_1 = require("./clientRoutes");
+function defaultAdapters() { return { codex: "responses", claude: "responses" }; }
+function isAdapterChoice(client, id) {
+    return id === "chat" || id === "responses" || (client === "claude" && id === "messages");
+}
+function settings(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("無法讀取 adapter 設定。");
+    const row = value;
+    if (typeof row.codex !== "string" || !isAdapterChoice("codex", row.codex) || row.codex === "messages" || typeof row.claude !== "string" || !isAdapterChoice("claude", row.claude))
+        throw new Error("adapter 設定格式無效。");
+    return { codex: row.codex, claude: row.claude };
+}
+// Non-secret app preferences are separate from Classroom Connection and survive its removal.
+function createAdapterSettingsStorage(filename) {
+    const routes = (0, clientRoutes_1.createClientRouteSettingsStorage)(filename);
+    return {
+        async load() {
+            const saved = await routes.load();
+            return settings({ codex: saved.codex.adapter, claude: saved.claudeCode.adapter });
+        },
+        async save(next) {
+            const value = settings(next);
+            const saved = await routes.load();
+            await routes.save({
+                ...saved,
+                codex: { ...saved.codex, adapter: value.codex },
+                claudeCode: { ...saved.claudeCode, adapter: value.claude },
+            });
+        },
+    };
+}

package/dist/adapters/chat-output.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatToolCalls = void 0;
+exports.validateChatContent = validateChatContent;
+exports.chatFinishReason = chatFinishReason;
+const types_1 = require("./types");
+function validateChatContent(message, allowPlaintextReasoning = false) {
+    if (allowPlaintextReasoning) {
+        for (const key of ["reasoning", "reasoning_content"])
+            if (message[key] != null && typeof message[key] !== "string")
+                throw new types_1.AdapterError("Chat reasoning 必須是文字。", 502);
+        if (message.reasoning && message.reasoning_content && message.reasoning !== message.reasoning_content)
+            throw new types_1.AdapterError("Chat 回傳互相衝突的 reasoning 欄位。", 502);
+    }
+    if ((!allowPlaintextReasoning && (message.reasoning_content || message.reasoning)) || message.refusal || message.audio || (Array.isArray(message.annotations) ? message.annotations.length : message.annotations))
+        throw new types_1.AdapterError("所選客戶端無法保留此 Chat 輸出。", 502);
+    if (message.function_call !== undefined)
+        throw new types_1.AdapterError("無法保留舊版 Chat function_call 輸出。", 502);
+    if (message.content !== undefined && message.content !== null && typeof message.content !== "string")
+        throw new types_1.AdapterError("Chat 輸出 content 必須是文字。", 502);
+}
+function chatFinishReason(value) {
+    if (value === "stop" || value === "tool_calls" || value === "length")
+        return value;
+    throw new types_1.AdapterError("Chat 串流中斷或結束原因無法轉換。", 502);
+}
+// A Chat tool name can span packets. The downstream start event is immutable, so
+// collect each complete call before publishing it; text still streams immediately.
+class ChatToolCalls {
+    calls = new Map();
+    add(value) {
+        for (const raw of (0, types_1.list)(value, "tool_calls")) {
+            const call = (0, types_1.object)(raw, "tool call"), fn = (0, types_1.object)(call.function ?? {}, "tool function");
+            const index = call.index ?? 0;
+            if (typeof index !== "number" || !Number.isInteger(index) || index < 0)
+                throw new types_1.AdapterError("Chat tool index 無效。", 502);
+            const tool = this.calls.get(index) ?? { id: "", name: "", args: "" };
+            this.calls.set(index, tool);
+            if (typeof call.id === "string") {
+                if (tool.id && tool.id !== call.id)
+                    throw new types_1.AdapterError("工具 ID 在串流中改變。", 502);
+                tool.id = call.id;
+            }
+            if (typeof fn.name === "string")
+                tool.name += fn.name;
+            if (typeof fn.arguments === "string")
+                tool.args += fn.arguments;
+        }
+    }
+    completed(toolKinds = new Map()) {
+        return [...this.calls.entries()].map(([index, call]) => {
+            if (!call.id || !call.name)
+                throw new types_1.AdapterError("上游工具呼叫缺少 ID 或名稱。", 502);
+            if (toolKinds.get(call.name) !== "custom") {
+                let input;
+                try {
+                    input = JSON.parse(call.args || "{}");
+                }
+                catch {
+                    throw new types_1.AdapterError("上游工具參數不是有效 JSON。", 502);
+                }
+                if (!input || typeof input !== "object" || Array.isArray(input))
+                    throw new types_1.AdapterError("上游工具參數必須是 JSON 物件。", 502);
+            }
+            return { index, id: call.id, type: "function", function: { name: call.name, arguments: call.args || "{}" } };
+        });
+    }
+}
+exports.ChatToolCalls = ChatToolCalls;

package/dist/adapters/chat-stream.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.chatToResponsesStream = chatToResponsesStream;
+const responsesChat_1 = require("../responsesChat");
+const stream_1 = require("./stream");
+const types_1 = require("./types");
+const chat_output_1 = require("./chat-output");
+async function* chatToResponsesStream(response, model, toolKinds, toolIdentity, hideReasoningSummary = false) {
+    const output = new responsesChat_1.ResponsesSse(model, toolKinds, toolIdentity, hideReasoningSummary);
+    yield output.created();
+    let finish;
+    const tools = new chat_output_1.ChatToolCalls();
+    for await (const frame of (0, stream_1.frames)(response)) {
+        if (frame.data === "[DONE]")
+            continue;
+        const body = frame.data;
+        if (body.error)
+            throw new types_1.AdapterError("Chat 上游串流回報失敗。", 502);
+        for (const value of (0, types_1.list)(body.choices ?? [], "choices")) {
+            const choice = (0, types_1.object)(value, "choice"), delta = (0, types_1.object)(choice.delta ?? {}, "delta");
+            (0, chat_output_1.validateChatContent)(delta, true);
+            if (delta.tool_calls !== undefined)
+                tools.add(delta.tool_calls);
+            if (choice.finish_reason != null)
+                finish = choice.finish_reason;
+        }
+        const textOnly = { ...body, choices: (0, types_1.list)(body.choices ?? [], "choices").map(value => {
+                const choice = (0, types_1.object)(value, "choice"), delta = { ...(0, types_1.object)(choice.delta ?? {}, "delta") };
+                delete delta.tool_calls;
+                return { ...choice, delta };
+            }) };
+        yield output.pushChatChunk(`data: ${JSON.stringify(textOnly)}\n`);
+    }
+    finish = (0, chat_output_1.chatFinishReason)(finish);
+    const calls = tools.completed(toolKinds);
+    if (finish === "tool_calls" && !calls.length)
+        throw new types_1.AdapterError("上游工具呼叫缺少識別資訊。", 502);
+    if (calls.length)
+        yield output.pushChatChunk(`data: ${JSON.stringify({ choices: [{ delta: { tool_calls: calls } }] })}\n`);
+    const terminal = output.finish();
+    if (terminal.includes("event: response.failed"))
+        throw new types_1.AdapterError("上游工具參數無法轉換。", 502);
+    yield terminal;
+}

package/dist/adapters/chat.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatAdapter = void 0;
+const responsesChat_1 = require("../responsesChat");
+const types_1 = require("./types");
+const claude_request_1 = require("./claude-request");
+const claude_reasoning_1 = require("./claude-reasoning");
+const claude_response_1 = require("./claude-response");
+const messages_stream_1 = require("./messages-stream");
+const stream_1 = require("./stream");
+const chat_stream_1 = require("./chat-stream");
+const transport_1 = require("./transport");
+const chat_output_1 = require("./chat-output");
+const chat_tools_1 = require("../codexWire/chat-tools");
+class ChatAdapter {
+    id = "chat";
+    async send(request) {
+        const codexTools = request.client === "codex" ? (0, chat_tools_1.codexChatTools)(request.body) : undefined;
+        const toolIdentity = (name) => {
+            const item = codexTools.restore({ type: "custom_tool_call", name });
+            return { name: String(item.name), ...(typeof item.namespace === "string" ? { namespace: item.namespace } : {}) };
+        };
+        const hideReasoningSummary = request.client === "codex" && typeof request.body.reasoning === "object" && request.body.reasoning !== null && (0, types_1.object)(request.body.reasoning, "reasoning").summary === "none";
+        const raw = JSON.stringify({ ...request.body, stream: request.body.stream === true });
+        const bodyToSend = request.client === "codex" ? (0, types_1.object)(JSON.parse((0, responsesChat_1.responsesToChatBody)(raw, request.model)), "Chat request") : (0, claude_request_1.claudeToChat)(request.body, request.model);
+        const { response, abort } = await (request.client === "codex" ? transport_1.upstreamRequest : claude_reasoning_1.upstreamRequestWithReplay)(request, "/v1/chat/completions", bodyToSend);
+        if (!response.ok)
+            return response;
+        if (request.body.stream) {
+            if (request.client === "claude")
+                return (0, stream_1.streamResponse)((0, messages_stream_1.chatToMessagesStream)(response, request.model, (0, claude_reasoning_1.thinkingMode)(request.body)), abort);
+            return (0, stream_1.streamResponse)((0, chat_tools_1.restoreChatToolStream)((0, chat_stream_1.chatToResponsesStream)(response, request.model, (0, responsesChat_1.toolKindsFromResponses)(raw), toolIdentity, hideReasoningSummary), codexTools.restore), abort);
+        }
+        return (0, transport_1.jsonResponse)(response, body => {
+            if (request.client === "claude")
+                return (0, claude_response_1.chatToClaude)(body, request.model, (0, claude_reasoning_1.thinkingMode)(request.body));
+            const choice = (0, types_1.object)((0, types_1.list)(body.choices, "choices")[0], "choice");
+            const message = (0, types_1.object)(choice.message, "message");
+            (0, chat_output_1.validateChatContent)(message, true);
+            (0, chat_output_1.chatFinishReason)(choice.finish_reason);
+            if (message.tool_calls !== undefined) {
+                const tools = new chat_output_1.ChatToolCalls();
+                tools.add((0, types_1.list)(message.tool_calls, "tool_calls").map((call, index) => ({ ...(0, types_1.object)(call, "tool call"), index })));
+                message.tool_calls = tools.completed((0, responsesChat_1.toolKindsFromResponses)(raw));
+            }
+            if (choice.finish_reason === "tool_calls" && (!Array.isArray(message.tool_calls) || !message.tool_calls.length))
+                throw new types_1.AdapterError("上游工具呼叫缺少識別資訊。", 502);
+            const sse = new responsesChat_1.ResponsesSse(request.model, (0, responsesChat_1.toolKindsFromResponses)(raw), toolIdentity, hideReasoningSummary);
+            sse.pushChatChunk(`data: ${JSON.stringify({ choices: [{ delta: message, finish_reason: choice.finish_reason }], usage: body.usage })}\n\n`);
+            const frames = sse.finish();
+            const event = frames.match(/event: response.(?:completed|incomplete)\ndata: ([^\n]+)/);
+            if (!event)
+                throw new types_1.AdapterError("Chat 回應無法轉換成 Responses。", 502);
+            const result = JSON.parse(event[1]).response;
+            if (body.usage) {
+                const usage = (0, types_1.object)(body.usage, "usage");
+                result.usage = { input_tokens: usage.prompt_tokens, output_tokens: usage.completion_tokens, total_tokens: usage.total_tokens };
+            }
+            return (0, chat_tools_1.restoreChatToolResponse)(result, codexTools.restore);
+        });
+    }
+}
+exports.ChatAdapter = ChatAdapter;

package/dist/adapters/claude-reasoning.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.thinkingMode = thinkingMode;
+exports.responsesReasoning = responsesReasoning;
+exports.thinkingBlock = thinkingBlock;
+exports.replayedReasoning = replayedReasoning;
+exports.withoutReplayedThinking = withoutReplayedThinking;
+exports.upstreamRequestWithReplay = upstreamRequestWithReplay;
+const types_1 = require("./types");
+const transport_1 = require("./transport");
+// Reasoning continuity for Claude Code on the Chat and Responses upstreams. Claude Code
+// returns a thinking block unchanged on the next turn, so upstream reasoning is handed to it
+// as a thinking block whose signature carries what the upstream needs to see again.
+const PREFIX = "vpr1.";
+function thinkingMode(body) {
+    const thinking = body.thinking && typeof body.thinking === "object" ? body.thinking : {};
+    if (thinking.type !== "enabled" && thinking.type !== "adaptive")
+        return "off";
+    return thinking.display === "omitted" ? "hidden" : "shown";
+}
+function texts(value) {
+    return Array.isArray(value) ? value.flatMap(part => part && typeof part === "object" && typeof part.text === "string" && part.text ? [part.text] : []) : [];
+}
+/** A Responses reasoning output item, reduced to the fields the upstream takes back as input. */
+function responsesReasoning(item) {
+    const text = [...texts(item.summary), ...texts(item.content)].join("\n\n");
+    if (!text && typeof item.encrypted_content !== "string")
+        return undefined;
+    const kept = { type: "reasoning", summary: Array.isArray(item.summary) ? item.summary : [] };
+    for (const key of ["id", "content", "encrypted_content"])
+        if (item[key] != null)
+            kept[key] = item[key];
+    return { item: kept, text };
+}
+function thinkingBlock(reasoning, mode, model) {
+    // An item already holds its text, so the text is only stored when there is no item.
+    const carried = reasoning.item ? { model, item: reasoning.item } : { model, text: reasoning.text };
+    return { type: "thinking", thinking: mode === "shown" ? reasoning.text : "", signature: PREFIX + Buffer.from(JSON.stringify(carried), "utf8").toString("base64url") };
+}
+/** Reads back a thinking block made by `thinkingBlock`. Any other signature cannot be replayed here. */
+function replayedReasoning(block) {
+    const signature = block.signature;
+    if (block.type === "thinking" && typeof signature === "string" && signature.startsWith(PREFIX)) {
+        try {
+            const carried = (0, types_1.object)(JSON.parse(Buffer.from(signature.slice(PREFIX.length), "base64url").toString("utf8")), "reasoning");
+            // The signature comes back from the client, so only a reasoning item's own fields reach the upstream.
+            const item = carried.item === undefined ? undefined : (0, types_1.object)(carried.item, "reasoning item");
+            if (item && item.type !== "reasoning")
+                throw new Error("not a reasoning item");
+            const kept = item && responsesReasoning(item);
+            return { text: typeof carried.text === "string" ? carried.text : kept?.text ?? "", ...(kept ? { item: kept.item } : {}), ...(typeof carried.model === "string" ? { model: carried.model } : {}) };
+        }
+        catch {
+            throw new types_1.AdapterError("Claude thinking 的回放資料已損毀。");
+        }
+    }
+    // Replaying it needs its Anthropic signature; dropping it would silently change the transcript.
+    throw new types_1.AdapterError(`所選上游協定無法轉換 Claude 內容 ${String(block.type)}。`);
+}
+/** A Messages request without the thinking blocks made here, whose signatures an Anthropic upstream would reject. */
+function withoutReplayedThinking(body) {
+    if (!Array.isArray(body.messages))
+        return body;
+    const replayed = (block) => !!block && typeof block === "object" && block.type === "thinking" && String(block.signature).startsWith(PREFIX);
+    const messages = body.messages.flatMap(message => {
+        if (!message || !Array.isArray(message.content) || !message.content.some(replayed))
+            return [message];
+        const content = message.content.filter(block => !replayed(block));
+        return content.length ? [{ ...message, content }] : [];
+    });
+    return { ...body, messages };
+}
+/** The upstream request without anything reasoning replay put in it, or undefined when there is nothing to take out. */
+function withoutReasoning(body) {
+    const plain = { ...body };
+    let changed = false;
+    if (Array.isArray(plain.input)) {
+        const input = (0, types_1.list)(plain.input, "input").filter(item => (0, types_1.object)(item, "input item").type !== "reasoning");
+        if (input.length !== plain.input.length) {
+            plain.input = input;
+            changed = true;
+        }
+    }
+    if (Array.isArray(plain.messages) && plain.messages.some(message => (0, types_1.object)(message, "message").reasoning_content !== undefined)) {
+        plain.messages = plain.messages.map(message => { const { reasoning_content: _, ...rest } = (0, types_1.object)(message, "message"); return rest; });
+        changed = true;
+    }
+    if (plain.include !== undefined) {
+        delete plain.include;
+        changed = true;
+    }
+    if (plain.reasoning && typeof plain.reasoning === "object" && plain.reasoning.summary !== undefined) {
+        const { summary: _, ...rest } = plain.reasoning;
+        if (Object.keys(rest).length)
+            plain.reasoning = rest;
+        else
+            delete plain.reasoning;
+        changed = true;
+    }
+    return changed ? plain : undefined;
+}
+/**
+ * Sends a Claude Code request, and once more without replayed reasoning when the upstream rejects it.
+ * Replayed reasoning stays in the history, so one the upstream refuses would fail every later turn.
+ */
+async function upstreamRequestWithReplay(request, path, body) {
+    const first = await (0, transport_1.upstreamRequest)(request, path, body);
+    const plain = first.response.status === 400 || first.response.status === 422 ? withoutReasoning(body) : undefined;
+    if (!plain)
+        return first;
+    const retried = await (0, transport_1.upstreamRequest)(request, path, plain);
+    if (!retried.response.ok) {
+        retried.abort();
+        return first;
+    }
+    first.abort();
+    return retried;
+}

package/dist/adapters/claude-request.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.claudeToResponses = claudeToResponses;
+exports.claudeToChat = claudeToChat;
+const node_crypto_1 = require("node:crypto");
+const types_1 = require("./types");
+const claude_reasoning_1 = require("./claude-reasoning");
+// Only recognized fields and content types are read. Unknown ones are not forwarded
+// and do not block the request, so a new Claude Code field cannot break every turn.
+function imageUrl(block) {
+    const source = (0, types_1.object)(block.source, "image.source");
+    if (source.type === "url")
+        return (0, types_1.string)(source.url, "image URL");
+    if (source.type === "base64")
+        return `data:${(0, types_1.string)(source.media_type, "media_type")};base64,${(0, types_1.string)(source.data, "image data")}`;
+    throw new types_1.AdapterError("無法轉換此圖片 source。");
+}
+function contentBlocks(content) {
+    if (typeof content === "string")
+        return [{ type: "text", text: content }];
+    return (0, types_1.list)(content, "Claude content").map(value => (0, types_1.object)(value, "Claude content block"));
+}
+const TOOL_ERROR = "[tool error]";
+function result(block, wire) {
+    // The error marker has no equivalent on these upstream protocols; carry it as text, never hide it.
+    const failed = block.is_error === true;
+    if (block.content === undefined)
+        return failed ? TOOL_ERROR : "";
+    if (typeof block.content === "string")
+        return failed ? `${TOOL_ERROR} ${block.content}` : block.content;
+    const parts = contentBlocks(block.content).flatMap(value => part(value, wire, "user"));
+    return failed ? [{ type: wire === "chat" ? "text" : "input_text", text: TOOL_ERROR }, ...parts] : parts;
+}
+function part(block, wire, role) {
+    if (block.type === "text")
+        return [{ type: wire === "chat" ? "text" : role === "assistant" ? "output_text" : "input_text", text: (0, types_1.string)(block.text, "text") }];
+    if (block.type === "image" && role === "user") {
+        const url = imageUrl(block);
+        return [wire === "chat" ? { type: "image_url", image_url: { url } } : { type: "input_image", image_url: url }];
+    }
+    if (block.type === "thinking" || block.type === "redacted_thinking")
+        (0, claude_reasoning_1.replayedReasoning)(block);
+    return [];
+}
+function options(body, wire) {
+    const output = { stream: body.stream === true };
+    for (const key of ["temperature", "top_p"])
+        if (body[key] !== undefined)
+            output[key] = body[key];
+    if (body.max_tokens !== undefined)
+        output[wire === "chat" ? "max_tokens" : "max_output_tokens"] = body.max_tokens;
+    if (wire === "chat" && body.stop_sequences !== undefined)
+        output.stop = body.stop_sequences;
+    if (body.metadata !== undefined) {
+        // Claude Code's user_id is a JSON blob; OpenAI-style upstreams reject user longer than 64 characters.
+        const user = (0, types_1.object)(body.metadata, "metadata").user_id;
+        output.user = typeof user === "string" && user.length > 64 ? (0, node_crypto_1.createHash)("sha256").update(user).digest("hex") : user;
+    }
+    // thinking and context_management have no upstream equivalent. Reasoning depth travels as
+    // effort; the budget is never forwarded raw and only picks the tier when no effort is given.
+    const thinking = body.thinking === undefined ? {} : (0, types_1.object)(body.thinking, "thinking");
+    const effort = body.output_config !== undefined ? (0, types_1.object)(body.output_config, "output_config").effort
+        : thinking.type === "enabled" && typeof thinking.budget_tokens === "number" ? thinking.budget_tokens <= 4096 ? "low" : thinking.budget_tokens <= 16384 ? "medium" : "high" : undefined;
+    if (effort !== undefined) {
+        if (wire === "chat")
+            output.reasoning_effort = effort;
+        else
+            output.reasoning = { effort };
+    }
+    const mode = (0, claude_reasoning_1.thinkingMode)(body);
+    if (wire === "responses" && mode !== "off") {
+        // Encrypted reasoning is what a stateless upstream needs back on the next turn.
+        output.include = ["reasoning.encrypted_content"];
+        if (mode === "shown")
+            output.reasoning = { ...(0, types_1.object)(output.reasoning ?? {}, "reasoning"), summary: "auto" };
+    }
+    if (body.tools !== undefined)
+        output.tools = (0, types_1.list)(body.tools, "tools").map(value => {
+            const tool = (0, types_1.object)(value, "Claude tool");
+            const fn = { name: (0, types_1.string)(tool.name, "tool name"), ...(tool.description !== undefined ? { description: tool.description } : {}),
+                // Responses reads an omitted strict as strict mode, which turns optional parameters into required ones.
+                ...(tool.strict !== undefined ? { strict: tool.strict } : wire === "responses" ? { strict: false } : {}), parameters: (0, types_1.object)(tool.input_schema, "input_schema") };
+            return wire === "chat" ? { type: "function", function: fn } : { type: "function", ...fn };
+        });
+    if (body.tool_choice !== undefined) {
+        const choice = (0, types_1.object)(body.tool_choice, "tool_choice");
+        if (choice.disable_parallel_tool_use !== undefined)
+            output.parallel_tool_calls = !choice.disable_parallel_tool_use;
+        if (choice.type === "tool")
+            output.tool_choice = wire === "chat" ? { type: "function", function: { name: (0, types_1.string)(choice.name, "tool name") } } : { type: "function", name: (0, types_1.string)(choice.name, "tool name") };
+        else if (choice.type === "any")
+            output.tool_choice = "required";
+        else if (choice.type === "auto" || choice.type === "none")
+            output.tool_choice = choice.type;
+        else
+            throw new types_1.AdapterError("無法轉換 Claude tool_choice。");
+    }
+    return output;
+}
+// Claude Code sends mid-conversation system messages. They keep their place in the timeline;
+// Responses takes them as developer because some backends refuse system items in input.
+const ROLES = ["user", "assistant", "system"];
+// Claude Code opens the system prompt with a per-request billing line that is not a model instruction.
+function system(value) {
+    return contentBlocks(value).flatMap(block => block.type === "text" ? [(0, types_1.string)(block.text, "text")] : []).join("\n").replace(/^x-anthropic-billing-header:[^\n]*\n*/, "");
+}
+function claudeToResponses(body, model) {
+    if (body.stop_sequences !== undefined)
+        throw new types_1.AdapterError("Responses 無法表達 Claude stop_sequences。");
+    const input = [];
+    for (const value of (0, types_1.list)(body.messages, "messages")) {
+        const message = (0, types_1.object)(value, "Claude message");
+        const role = (0, types_1.string)(message.role, "role");
+        if (!ROLES.includes(role))
+            throw new types_1.AdapterError("Claude message role 無法轉換。");
+        // A reasoning item is only valid in front of the output it led to, so it waits for that output.
+        let parts = [], reasoning = [];
+        const flush = () => { if (parts.length)
+            input.push({ role: role === "system" ? "developer" : role, content: parts }); parts = []; };
+        const reasoned = () => { input.push(...reasoning); reasoning = []; };
+        for (const block of contentBlocks(message.content)) {
+            if (block.type === "thinking" && role === "assistant") {
+                // Chat reasoning has no Responses item to hand back, so only the item form is replayed.
+                // Encrypted reasoning belongs to the model that made it; another model is not sent it.
+                const replayed = (0, claude_reasoning_1.replayedReasoning)(block);
+                if (replayed.item && (replayed.model === undefined || replayed.model === model)) {
+                    flush();
+                    reasoning.push(replayed.item);
+                }
+            }
+            else if (block.type === "tool_use" && role === "assistant") {
+                flush();
+                reasoned();
+                input.push({ type: "function_call", call_id: (0, types_1.string)(block.id, "tool id"), name: (0, types_1.string)(block.name, "tool name"), arguments: JSON.stringify((0, types_1.object)(block.input, "tool input")) });
+            }
+            else if (block.type === "tool_result" && role === "user") {
+                flush();
+                input.push({ type: "function_call_output", call_id: (0, types_1.string)(block.tool_use_id, "tool_use_id"), output: result(block, "responses") });
+            }
+            else {
+                const converted = part(block, "responses", role);
+                if (converted.length)
+                    reasoned();
+                parts.push(...converted);
+            }
+        }
+        flush();
+    }
+    const instructions = body.system === undefined ? "" : system(body.system);
+    return { model, input, store: false, ...options(body, "responses"), ...(instructions ? { instructions } : {}) };
+}
+function claudeToChat(body, model) {
+    const messages = [];
+    const instructions = body.system === undefined ? "" : system(body.system);
+    if (instructions)
+        messages.push({ role: "system", content: instructions });
+    for (const value of (0, types_1.list)(body.messages, "messages")) {
+        const message = (0, types_1.object)(value, "Claude message");
+        const role = (0, types_1.string)(message.role, "role");
+        if (!ROLES.includes(role))
+            throw new types_1.AdapterError("Claude message role 無法轉換。");
+        let parts = [], calls = [], reasoning = [];
+        const flush = () => {
+            if (parts.length || calls.length)
+                messages.push({ role, content: parts.length ? parts.every(p => p.type === "text") ? parts.map(p => p.text).join("") : parts : null,
+                    ...(reasoning.length ? { reasoning_content: reasoning.join("\n\n") } : {}), ...(calls.length ? { tool_calls: calls } : {}) });
+            parts = [];
+            calls = [];
+            reasoning = [];
+        };
+        for (const block of contentBlocks(message.content)) {
+            if (block.type === "thinking" && role === "assistant") {
+                const { text } = (0, claude_reasoning_1.replayedReasoning)(block);
+                if (text)
+                    reasoning.push(text);
+            }
+            else if (block.type === "tool_use" && role === "assistant") {
+                calls.push({ id: (0, types_1.string)(block.id, "tool id"), type: "function", function: { name: (0, types_1.string)(block.name, "tool name"), arguments: JSON.stringify((0, types_1.object)(block.input, "tool input")) } });
+            }
+            else if (block.type === "tool_result" && role === "user") {
+                flush();
+                messages.push({ role: "tool", tool_call_id: (0, types_1.string)(block.tool_use_id, "tool_use_id"), content: result(block, "chat") });
+            }
+            else
+                parts.push(...part(block, "chat", role));
+        }
+        flush();
+    }
+    return { model, messages, ...options(body, "chat") };
+}