第一部｜最小閉環 · 第 2 章

訊息、Transcript 與 Provider Adapter

理解 tiny-agent 如何藉由 transcript 延續工作，以及 provider wire format 為何不能直接進入核心。

一句話掌握本章核心：tiny-agent 的 Chat Completions 配接器會由 Host 重送選入的 Transcript 以延續對話。其他 API 也可能提供 Server-managed State。無論狀態由誰管理，Provider 回傳的 Wire Format 都不應未經驗證地進入 Canonical Transcript：本專案以 正規化防線（Normalization Seam）只保留允許欄位。

狀態延續的本質：無對話記憶的模型與忠實的紀錄卷軸

對 tiny-agent 目前使用的 Chat Completions 模式，可想像模型每次通話都需要 Host 提供本輪有效 Context：System Instructions、選入的歷史、工具定義與結果。這個比喻不涵蓋所有 Endpoint。例如 OpenAI Responses API 可透過 previous_response_id 串接 Provider 管理的狀態。

在系統架構中，這個「依序重送歷程的紀錄卷軸」就是 Transcript。

四種訊息角色的嚴格語意

Transcript 絕不是隨意的自然語言文字串，而是具有嚴格型別定義與角色約束（Role Invariants）的時序陣列：

合法 Transcript 是硬限制 (Strict Invariants)

主流 LLM Provider 對 Message 序列的合法性有極為嚴格的校驗機制：

{"role":"assistant","content":null,"tool_calls":[
  {"id":"call_1","type":"function","function":{"name":"read","arguments":"{\"path\":\"README.md\"}"}}
]}
{"role":"tool","tool_call_id":"call_1","content":"# tiny-agent project..."}

Provider Adapter 必須正規化（Normalization Seam）

核心踩坑警示：TypeScript 的 Type Assertion（如 response.message as Message）只存在於編譯時期，在 JavaScript Runtime 階段完全不會刪除任何欄位！

若直接將 OpenRouter / OpenAI 回傳的原始物件存入 Canonical Session，諸如 reasoning、refusal、annotations 等供應商專屬欄位會污染持久化格式。tiny-agent 的 Strict Reducer 會以 INVALID_FACT / Session Corruption 拒絕不符合 Exact-key Contract 的資料。另一種架構也可另外保存 Raw Events，但不可把未驗證的 Wire Shape 當成 Canonical Message。

// tiny-agent 實作的等價節錄。validateToolCall 代表原始碼內的 inline 欄位驗證
// 核心契約：先拒絕不合法資料，再以白名單重建 Canonical Object
function normalizeAssistantMessage(value: unknown): Message {
    // 1. Wire value 必須是非陣列物件，且 role 必須正確
    if (!value || typeof value !== "object" || Array.isArray(value)) {
        throw new Error("invalid assistant message");
    }
    const raw = value as Record<string, unknown>;
    if (raw.role !== "assistant") throw new Error("invalid assistant message role");

    // 2. content 僅接受 string | null。不合法時拒絕，不做寬鬆轉型
    if (raw.content !== null && typeof raw.content !== "string") {
        throw new Error("invalid assistant content");
    }
    const normalized: Message = { role: "assistant", content: raw.content };

    // 3. tool_calls 若存在，必須是非空 Array，且逐欄驗證 id/type/name/arguments
    if (raw.tool_calls === undefined || raw.tool_calls === null) return normalized;
    if (!Array.isArray(raw.tool_calls) || !raw.tool_calls.length) {
        throw new Error("invalid assistant tool_calls");
    }
    normalized.tool_calls = raw.tool_calls.map(validateToolCall);
    return normalized; // Provider-only 欄位未被複製
}

Finish Reason 狀態映射

TL;DR：tiny-agent 會交叉驗證 Provider 的 finish_reason 與 Canonical Message。tool_calls / function_call Reason 必須真的含 Calls。length 走截斷分支。而合法、缺省或 stop Reason 若仍帶 Calls，目前實作會依 Calls 正規化為內部 toolUse。

Provider-reported Token Usage 的標準化

在多輪對話中，保存每一次物理 Request 由 Provider 回報的 Token Usage，是成本控制與除錯的重要訊號。它不是 tiny-agent 以本機 Tokenizer 獨立重算的絕對量測。OpenRouter 說明 Token Counts 由實際路由模型的 Native Tokenizer 計算，明細欄位也可能依 Endpoint 而異：

type Usage = {
    input: number;      // 扣除快取後的純淨輸入 Token
    output: number;     // 本次生成的輸出 Token
    cacheRead: number;  // 命中 Provider Prompt Cache 的 Token 數
    cacheWrite: number; // 寫入 Provider Prompt Cache 的 Token 數
};

OpenAI / OpenRouter 風格的 prompt_tokens 可包含 Cache Read / Write Tokens。tiny-agent 依 Provider 回傳的 Optional Details 採用以下內部 Ledger 公式，缺少的明細以 0 處理：

input = prompt_tokens - cacheRead - cacheWrite
cacheHitRate = cacheRead / (input + cacheRead + cacheWrite)

動手驗證 (Hands-on Lab)

請執行既有的離線回歸測試，觀察 Provider 原始髒資料如何被精準清洗：

cd typescript
# 1. 驗證 Provider 專屬欄位被清洗，Session 僅保留 Canonical Message
node --import tsx --test --test-name-pattern="normalizes provider-only" tests/index.test.ts

# 2. 驗證畸形 Assistant Message 會被安全拒絕，不會引發未捕獲例外
node --import tsx --test --test-name-pattern="rejects malformed provider assistant" tests/index.test.ts

嚴格的 Transcript Contract 與正規化防線，使經過目前 Adapter 與 Reducer 接受的資料維持 Canonical 結構。Storage Corruption、未來 Schema 變更與實作 Bug 仍須 Fail-closed 處理。下一章將探討誰把這些 JSON 轉化為檔案讀寫、Shell 執行與背景行程：Tool 的設計哲學與執行守衛。