@argosvix/sdk 0.4.22-alpha.0 → 0.5.0

package/dist/client.js

@@ -32,8 +32,8 @@ export function wrap(client, config = {}) {
         return client;
     }
     const recorder = new Recorder(config);
-    // #1 R4 = withSpan が emit する observation の送信先として登録(= この recorder の
-    // ingest 経路で observations[] を送る)。
+    // Register this recorder as the sink for observations emitted by withSpan
+    // (observations[] are sent through this recorder's ingest path).
     _registerObservationSink(recorder);
     switch (provider) {
         case "openai": {
@@ -61,11 +61,11 @@ export function wrap(client, config = {}) {
             break;
         }
     }
-    // 平文 capture の対応範囲(2026-07 streaming 対応): 全 4 provider の
-    // 非ストリーミング success path に加え、既存 stream wrapper がある streaming 経路
-    // (OpenAI Chat / Anthropic / Mistral / Gemini legacy + 新 SDK)でも promptBody /
-    // completionBody を抽出する。OpenAI Responses の streaming は stream wrapper 自体が
-    // 未実装(下記 "not yet observed" warn)のため平文も未対応。
+    // Plaintext capture coverage (streaming support added 2026-07): in addition to
+    // the non-streaming success path of all 4 providers, promptBody / completionBody
+    // are also extracted on the streaming paths that have an existing stream wrapper
+    // (OpenAI Chat / Anthropic / Mistral / Gemini legacy + new SDK). OpenAI Responses
+    // streaming has no stream wrapper yet, so plaintext capture is unsupported there too.
     wrappedClients.set(client, recorder);
     return client;
 }
@@ -73,9 +73,10 @@ export function getRecorder(client) {
     return wrappedClients.get(client) ?? null;
 }
 /**
- * 内部用 = wrap() を経由しない統合 (= Vercel AI SDK middleware 等) が、 自前の
- * Recorder を flushClient() / getRecorder() の WeakMap に載せるための登録口。
- * これで `flushClient(middleware)` が wrap 済みクライアントと同じ経路で動く。
+ * Internal: registration hook for integrations that do not go through wrap()
+ * (e.g. the Vercel AI SDK middleware) to put their own Recorder into the WeakMap
+ * used by flushClient() / getRecorder(). This lets `flushClient(middleware)`
+ * work through the same path as wrapped clients.
  */
 export function _registerRecorderFor(obj, recorder) {
     wrappedClients.set(obj, recorder);
@@ -115,21 +116,22 @@ function detectProvider(client, override) {
 }
 function buildTraceMeta(config) {
     const meta = {};
-    // #1 R1 自動コンテキスト伝播: traceId は 明示 config > ambient(withTrace 内)の順。
-    // autoContext:false で ambient を無視し従来の静的挙動に戻す。
+    // Automatic context propagation: traceId resolution order is explicit config
+    // first, then ambient (inside withTrace). autoContext:false ignores the
+    // ambient context and restores the previous static behavior.
     const ambient = config.autoContext === false ? undefined : getAmbientTraceContext();
     const traceId = config.traceId ?? ambient?.traceId;
     if (traceId) {
         meta.traceId = traceId;
-        // trace に属する呼び出しは自前の span を持つ(= trace のノードになる)。 明示 spanId 優先。
+        // A call that belongs to a trace gets its own span (it becomes a node of the trace). An explicit spanId takes priority.
         meta.spanId = config.spanId ?? generateId();
-        // parent は 明示 config > ambient span(withSpan 等で設定、 R1 では trace 直下=undefined)。
+        // Parent resolution: explicit config first, then the ambient span (set by withSpan etc.; undefined when directly under the trace).
         const parentSpanId = config.parentSpanId ?? ambient?.spanId;
         if (parentSpanId)
             meta.parentSpanId = parentSpanId;
     }
     else {
-        // trace コンテキストが無い standalone 呼び出し = 従来挙動(明示指定のみ carry)。
+        // Standalone call without a trace context: previous behavior (only explicitly provided values are forwarded).
         if (config.spanId)
             meta.spanId = config.spanId;
         if (config.parentSpanId)
@@ -140,15 +142,17 @@ function buildTraceMeta(config) {
     return meta;
 }
 /**
- * エンドユーザー識別子の自動取得 (= 2026-06-17 user 提案、 Codex review 反映)。
- * provider ごとに「opaque 前提で設計された専用項目」のみ読み取り、 userId タグ
- * として集計に carry する:
- *   - OpenAI:    safety_identifier (= OpenAI 推奨の安定識別子、 hash 推奨)
- *   - Anthropic: metadata.user_id (= 仕様上 PII 禁止・opaque 必須・256 文字以内)
- * 旧 OpenAI `user` は PII (email / 生 ID) が入りやすく自動転送は同意外の漏洩に
- * なりうるため、 自動取得の対象から外す (= 必要なら明示 tags.userId で carry)。
- * provider を明示で分岐し、 Gemini / Mistral は常に no-op (= 別 provider の項目名
- * を誤って拾わない)。 値は backend 上限に合わせ 256 文字に丸める。
+ * Automatic end-user identifier capture (added 2026-06-17, refined in review).
+ * For each provider, only fields designed to hold opaque identifiers are read,
+ * and the value is forwarded to aggregation as the userId tag:
+ *   - OpenAI:    safety_identifier (OpenAI's recommended stable identifier; hashing recommended)
+ *   - Anthropic: metadata.user_id (per spec: no PII, must be opaque, max 256 chars)
+ * The legacy OpenAI `user` field is excluded from automatic capture: it often
+ * carries PII (emails / raw IDs), so auto-forwarding it could leak data beyond
+ * what was consented to (pass an explicit tags.userId if needed).
+ * Providers are matched explicitly; Gemini / Mistral are always a no-op (so we
+ * never mistakenly pick up another provider's field names). Values are trimmed
+ * to 256 characters to match the backend limit.
  */
 function pickEndUserId(provider, requestArgs) {
     if (!requestArgs || typeof requestArgs !== "object")
@@ -172,14 +176,15 @@ function pickEndUserId(provider, requestArgs) {
     return typeof cand === "string" ? cand.slice(0, 256) : undefined;
 }
 /**
- * record に乗せる tags を組み立てる。 config.tags を基底に、 captureUserId が
- * 明示 false でない限り provider 専用項目から userId を補完する。 明示の
- * config.tags.userId が既にあればそれを優先する (= 自動取得で上書きしない)。
+ * Build the tags placed on a record. Starting from config.tags, the userId is
+ * filled in from the provider-specific field unless captureUserId is explicitly
+ * false. An existing explicit config.tags.userId takes priority (automatic
+ * capture never overwrites it).
  *
- * Codex HIGH 2 反映: 各 wrapper の入口で 1 回だけ呼び、 確定した tags を
- * success / error / stream の全 record で共有する (= await 後に requestArgs を
- * 読み直さない。 呼び出し元が request object を再利用・変更しても別ユーザーの
- * userId で記録されない)。
+ * Call this exactly once at each wrapper's entry point and share the resolved
+ * tags across all success / error / stream records: requestArgs must not be
+ * re-read after an await, so a caller that reuses or mutates the request object
+ * cannot cause the call to be recorded under another user's userId.
  */
 function buildTags(config, provider, requestArgs) {
     const tags = { ...(config.tags ?? {}) };
@@ -188,8 +193,9 @@ function buildTags(config, provider, requestArgs) {
         if (native !== undefined)
             tags.userId = native;
     }
-    // withPrompt() の内側なら prompt タグ({name}@v{version})を自動付与。
-    // 明示 tags.prompt が優先(上書きしない)。版別の品質/コスト比較の基盤(2026-07-02 #4)。
+    // Inside withPrompt(), the prompt tag ({name}@v{version}) is attached
+    // automatically. An explicit tags.prompt takes priority (never overwritten).
+    // This is the basis for per-version quality/cost comparison (2026-07-02).
     if (tags.prompt === undefined) {
         const ambientPrompt = getAmbientPromptTag();
         if (ambientPrompt !== undefined)
@@ -198,22 +204,23 @@ function buildTags(config, provider, requestArgs) {
     return tags;
 }
 /**
- * Pro+ 平文保存機能の SDK 側 opt-in 抽出 helper。
+ * SDK-side opt-in extraction helpers for the Pro+ plaintext storage feature.
  *
- * captureContent が true のときに wrapper が呼んで、 provider 毎の
- * request / response 形状から prompt / completion / tool calls を 文字列
- * (および JSON 文字列)として抽出する。 PII redaction は Recorder 側で
- * 一括して適用されるので、 ここでは生の文字列を返すのみ。
+ * Called by the wrappers when captureContent is true; extracts prompt /
+ * completion / tool calls as strings (and JSON strings) from each provider's
+ * request / response shapes. PII redaction is applied centrally in the
+ * Recorder, so these helpers only return the raw strings.
  *
- * 対応 provider(2026-07-02 パリティ解消で全 4 provider の非ストリーミングに拡大):
- *   - openai (Chat Completions + Responses) = prompt + completion + tool calls
- *   - anthropic (Messages) = prompt + completion
- *   - mistral (chat.complete) = prompt + completion
- *   - gemini (legacy generateContent + 新 SDK models.generateContent) = prompt + completion
- *   - streaming 経路(2026-07 対応)= 既存 stream wrapper の finalize で promptBody
- *     (入口 snapshot)+ completionBody(テキスト delta 蓄積、256KB 上限)を付与。
- *     ツール呼び出し引数の streaming 組み立ては対象外。OpenAI Responses streaming は
- *     stream wrapper 未実装のため未対応。
+ * Supported providers (extended 2026-07-02 to cover non-streaming for all 4):
+ *   - openai (Chat Completions + Responses): prompt + completion + tool calls
+ *   - anthropic (Messages): prompt + completion
+ *   - mistral (chat.complete): prompt + completion
+ *   - gemini (legacy generateContent + new SDK models.generateContent): prompt + completion
+ *   - streaming paths (added 2026-07): the existing stream wrappers' finalize
+ *     step attaches promptBody (snapshotted at entry) + completionBody
+ *     (accumulated text deltas, 256KB cap). Streaming assembly of tool-call
+ *     arguments is out of scope. OpenAI Responses streaming is unsupported
+ *     because it has no stream wrapper.
  */
 function extractOpenAIChatPromptBody(requestArgs) {
     if (!Array.isArray(requestArgs.messages) || requestArgs.messages.length === 0) {
@@ -236,7 +243,7 @@ function extractOpenAIChatCompletionBody(response) {
     const content = first?.message?.content;
     if (typeof content === "string")
         return content;
-    // content が array (multi-modal の場合) の場合は JSON 文字列で carry
+    // When content is an array (multi-modal), forward it as a JSON string
     if (Array.isArray(content)) {
         try {
             return JSON.stringify(content);
@@ -273,14 +280,16 @@ function extractOpenAIChatToolCalls(response) {
     return result.length > 0 ? result : undefined;
 }
 /**
- * v0.3.0-alpha.2 段階9 拡張 = OpenAI Responses API の captureContent 抽出。
+ * captureContent extraction for the OpenAI Responses API (added in v0.3.0-alpha.2).
  *
- *   - request.input は string (= 単純 prompt) or array (= multi-modal / structured)
- *     のどちらか。 string ならそのまま、 array なら JSON 文字列化して carry。
- *   - response.output_text (= aggregated text、 SDK 0.4.x で導入) を 第一候補、
- *     なければ response.output (= 配列) を walk して output_text type の text を join。
- *   - tool calls は response.output 内の type === "function_call" item から
- *     name + arguments を抽出。
+ *   - request.input is either a string (a simple prompt) or an array
+ *     (multi-modal / structured). Strings are forwarded as-is; arrays are
+ *     JSON-stringified.
+ *   - response.output_text (aggregated text, introduced in SDK 0.4.x) is the
+ *     first choice; otherwise walk the response.output array and join the text
+ *     of output_text-type items.
+ *   - Tool calls are extracted (name + arguments) from items with
+ *     type === "function_call" inside response.output.
  */
 function extractOpenAIResponsesPromptBody(requestArgs) {
     if (requestArgs.input === undefined || requestArgs.input === null)
@@ -385,7 +394,7 @@ function extractAnthropicCompletionBody(response) {
         }
         if (texts.length > 0)
             return texts.join("\n");
-        // text block がなければ全 content を JSON 文字列として carry
+        // If there is no text block, forward the whole content as a JSON string
         try {
             return JSON.stringify(content);
         }
@@ -396,12 +405,12 @@ function extractAnthropicCompletionBody(response) {
     return undefined;
 }
 /**
- * 2026-07-02 パリティ解消 = Mistral / Gemini の非ストリーミング success path にも
- * captureContent 抽出を追加(OpenAI / Anthropic と同水準)。PII redaction は
- * 従来どおり Recorder 側で一括適用される。
+ * Parity fix (2026-07-02): captureContent extraction was added to the
+ * non-streaming success paths of Mistral / Gemini as well (same level as
+ * OpenAI / Anthropic). PII redaction is still applied centrally in the Recorder.
  */
 function extractMistralPromptBody(requestArgs) {
-    // Mistral chat.complete は OpenAI Chat 互換の messages 配列。
+    // Mistral chat.complete takes an OpenAI-Chat-compatible messages array.
     if (!Array.isArray(requestArgs.messages) || requestArgs.messages.length === 0) {
         return undefined;
     }
@@ -417,15 +426,16 @@ function extractMistralCompletionBody(response) {
         ?.message?.content;
     if (typeof content === "string")
         return content;
-    // ContentChunk[](multi-modal)は JSON 文字列で carry
+    // ContentChunk[] (multi-modal) is forwarded as a JSON string
     if (Array.isArray(content))
         return safeStringify(content);
     return undefined;
 }
 /**
- * Gemini の prompt 抽出。legacy `@google/generative-ai` の generateContent は
- * string または { contents } を受け、新 `@google/genai` は { model, contents }。
- * どちらも contents(または生の string)を文字列化して carry する。
+ * Gemini prompt extraction. The legacy `@google/generative-ai` generateContent
+ * accepts a string or { contents }; the new `@google/genai` takes
+ * { model, contents }. In both cases the contents (or the raw string) are
+ * stringified and forwarded.
  */
 function extractGeminiPromptBody(requestArgs) {
     if (typeof requestArgs === "string")
@@ -440,10 +450,10 @@ function extractGeminiPromptBody(requestArgs) {
     return safeStringify(contents);
 }
 /**
- * Gemini の completion 抽出。legacy は result.response、新 SDK は result 自体が
- * { candidates: [{ content: { parts: [{ text }] } }] } を持つので、caller が
- * candidates を持つ側のオブジェクトを渡す。text part を join、無ければ parts を
- * JSON 文字列で carry。
+ * Gemini completion extraction. On legacy it is result.response; on the new SDK
+ * the result itself holds { candidates: [{ content: { parts: [{ text }] } }] },
+ * so the caller passes whichever object carries candidates. Text parts are
+ * joined; if there are none, the parts are forwarded as a JSON string.
  */
 function extractGeminiCompletionBody(response) {
     if (!response || typeof response !== "object")
@@ -474,22 +484,25 @@ function safeStringify(value) {
     }
 }
 // ============================================================
-// streaming 平文キャプチャ(2026-07 設計、 docs/handoff/streaming-capture-design-2026-07.md)
+// Streaming plaintext capture (designed 2026-07)
 //
-// promptBody は既存の extract*PromptBody を stream 入口で snapshot し、
-// completionBody は既存 stream wrapper(usage 集計で全チャンク観測済み)に
-// テキスト delta の蓄積を足すだけで得る(= 新しい傍受点は作らない)。
-// redaction は従来どおり Recorder の flush 時に一括適用される。
+// promptBody is snapshotted at stream entry via the existing extract*PromptBody
+// helpers; completionBody is obtained by simply adding text-delta accumulation
+// to the existing stream wrappers (which already observe every chunk for usage
+// aggregation) — no new interception points are introduced.
+// Redaction is still applied centrally at Recorder flush time.
 // ============================================================
 /**
- * 蓄積バッファの上限(= 262,144 bytes = 256KB)。ingest 側の本文上限と整合。
- * 暴走ストリームで wrapper がホストアプリのメモリを食う事故を構造的に防ぐ。
+ * Accumulation buffer cap (262,144 bytes = 256KB), aligned with the ingest-side
+ * body limit. Structurally prevents a runaway stream from letting the wrapper
+ * eat the host application's memory.
  */
 const STREAM_CAPTURE_MAX_BYTES = 262_144;
 const STREAM_TRUNCATED_MARKER = "…[truncated]";
 /**
- * UTF-16 code unit 走査で UTF-8 バイト長を数える(TextEncoder の毎 delta 割り当てを
- * 避ける)。surrogate pair は 4 bytes で 1 code point として数える。
+ * Count the UTF-8 byte length by scanning UTF-16 code units (avoids a
+ * TextEncoder allocation per delta). A surrogate pair counts as one code point
+ * of 4 bytes.
  */
 function utf8ByteLength(text) {
     let bytes = 0;
@@ -500,7 +513,7 @@ function utf8ByteLength(text) {
         else if (code < 0x800)
             bytes += 2;
         else if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
-            // surrogate pair = 4 bytes(後続の low surrogate を 1 つ消費)
+            // Surrogate pair: 4 bytes (consumes the following low surrogate)
             bytes += 4;
             i++;
         }
@@ -510,8 +523,8 @@ function utf8ByteLength(text) {
     return bytes;
 }
 /**
- * streaming テキスト delta の蓄積バッファ。256KB 上限で超過分は捨てて、
- * result() が末尾に truncated マーカーを付けた本文を返す。
+ * Accumulation buffer for streaming text deltas. Anything beyond the 256KB cap
+ * is dropped, and result() returns the body with a truncated marker appended.
  */
 class StreamTextAccumulator {
     parts = [];
@@ -526,7 +539,7 @@ class StreamTextAccumulator {
             this.bytes += size;
             return;
         }
-        // 上限をまたぐ delta は入る分だけ code point 境界で継ぎ足し、以降は捨てる。
+        // A delta that crosses the cap is appended up to a code point boundary as far as it fits; the rest is dropped.
         let remaining = STREAM_CAPTURE_MAX_BYTES - this.bytes;
         let head = "";
         for (const ch of text) {
@@ -543,8 +556,9 @@ class StreamTextAccumulator {
         this.truncated = true;
     }
     /**
-     * 蓄積本文を返す(空なら undefined = record に載せない)。
-     * interrupted = 例外 / 途中打ち切りで「そこまでの本文」を返すとき、marker を強制付与。
+     * Return the accumulated body (undefined if empty, i.e. not placed on the record).
+     * interrupted: when returning the body captured so far after an exception or
+     * early termination, the truncated marker is always appended.
      */
     result(interrupted = false) {
         if (this.parts.length === 0)
@@ -554,8 +568,9 @@ class StreamTextAccumulator {
     }
 }
 /**
- * stream 入口での capture 状態生成。captureContent でないときは undefined を返して
- * 抽出コストも蓄積コストもゼロに保つ(promptBody 抽出は thunk で遅延)。
+ * Create the capture state at stream entry. When captureContent is not enabled,
+ * returns undefined so both extraction and accumulation cost stay at zero
+ * (promptBody extraction is deferred behind a thunk).
  */
 function buildStreamCapture(config, extractPromptBody) {
     if (config.captureContent !== true)
@@ -567,8 +582,9 @@ function buildStreamCapture(config, extractPromptBody) {
     return capture;
 }
 /**
- * stream finalize / error record に promptBody / completionBody を付与する。
- * redaction はここではなく Recorder の flush 時に一括適用される(非 stream と同方針)。
+ * Attach promptBody / completionBody to a stream finalize / error record.
+ * Redaction happens not here but centrally at Recorder flush time (same policy
+ * as the non-streaming path).
  */
 function applyStreamCapture(record, capture, interrupted) {
     if (!capture)
@@ -579,16 +595,17 @@ function applyStreamCapture(record, capture, interrupted) {
     if (completionBody !== undefined)
         record.completionBody = completionBody;
 }
-/** OpenAI Chat stream チャンクのテキスト delta(choices[0].delta.content、string のみ)。 */
+/** Text delta of an OpenAI Chat stream chunk (choices[0].delta.content, strings only). */
 function extractOpenAIStreamDeltaText(chunk) {
     const delta = chunk.choices?.[0]?.delta;
     const content = delta?.content;
     return typeof content === "string" && content.length > 0 ? content : undefined;
 }
 /**
- * Gemini stream チャンクのテキスト delta。新 SDK は chunk.text(string property)、
- * legacy は chunk.text()(関数、safety block 等で throw しうる)。どちらも無ければ
- * candidates[0].content.parts[].text を継ぎ足す(JSON fallback はしない = delta のみ)。
+ * Text delta of a Gemini stream chunk. The new SDK exposes chunk.text (a string
+ * property); legacy exposes chunk.text() (a function that may throw, e.g. on a
+ * safety block). If neither yields text, concatenate
+ * candidates[0].content.parts[].text (no JSON fallback — deltas only).
  */
 function extractGeminiStreamChunkText(chunk) {
     if (!chunk || typeof chunk !== "object")
@@ -603,7 +620,7 @@ function extractGeminiStreamChunkText(chunk) {
                 return v;
         }
         catch {
-            // legacy chunk.text() は candidate なし等で throw する。 蓄積は諦めて続行。
+            // Legacy chunk.text() throws when there is no candidate etc. Give up on accumulating and continue.
         }
     }
     const candidates = chunk.candidates;
@@ -648,8 +665,9 @@ function isOpenAIChatLike(client) {
     return typeof c?.chat?.completions?.create === "function";
 }
 /**
- * 監査 Tier 2 = OpenAI usage から推論 / 音声トークンを取り出す(無ければ undefined)。
- * audio は入力(prompt)+ 出力(completion)の合算。 0 のときは記録しない(列を NULL に保つ)。
+ * Extract reasoning / audio tokens from OpenAI usage (undefined when absent).
+ * Audio is the sum of input (prompt) and output (completion) tokens. Zero
+ * values are not recorded (keeps the column NULL).
  */
 function extractRichTokens(usage) {
     const out = {};
@@ -664,8 +682,9 @@ function extractRichTokens(usage) {
     return out;
 }
 /**
- * 監査 Tier 2 = streaming チャンクが「初回トークン」(本文 / ツール / 音声 / refusal)を
- * 載せているか。 先頭の role のみ delta では立てない(TTFT を正しく測る)。
+ * Whether a streaming chunk carries the "first token" (content / tool / audio /
+ * refusal). Not triggered by the leading role-only delta (so TTFT is measured
+ * correctly).
  */
 function chunkHasStreamedOutput(chunk) {
     const choices = chunk.choices;
@@ -681,14 +700,15 @@ function chunkHasStreamedOutput(chunk) {
     return delta.tool_calls != null || delta.function_call != null || delta.audio != null;
 }
 /**
- * audit round2 M27 = 高レベル streaming helper (Anthropic messages.stream() /
- * OpenAI chat.completions.stream()) は wrap 対象外で budget/policy gate を素通りする。
- * これらは同期戻り (event-emitter) で async gate を内部で安全に挟むのが難しいため、 ゲートを
- * 使う設定のときだけ wrap 時に一度警告し、 .create({ stream: true }) (= gate される経路) への
- * 切替を促す。 .create stream:true と Responses streaming は既に gate 済。
+ * The high-level streaming helpers (Anthropic messages.stream() /
+ * OpenAI chat.completions.stream()) are not wrapped and bypass the budget/policy
+ * gate. They return synchronously (event-emitter style), which makes it hard to
+ * safely insert an async gate internally, so when a gate is configured we warn
+ * once at wrap time and suggest switching to .create({ stream: true }) (the
+ * gated path). .create stream:true and Responses streaming are already gated.
  */
 let warnedGateStreamHelper = false;
-/** Test-only: reset the M27 stream-helper warn-once flag. Do not call from production. */
+/** Test-only: reset the stream-helper warn-once flag. Do not call from production. */
 export function __resetStreamHelperWarning() {
     warnedGateStreamHelper = false;
 }
@@ -700,7 +720,7 @@ function warnIfGatedStreamHelper(config, hasStreamHelper, label) {
     warnedGateStreamHelper = true;
     // eslint-disable-next-line no-console
     console.warn(`[argosvix] ${label} bypasses the budget/policy gate (not wrapped). ` +
-        `Use .create({ stream: true }) for gated streaming. (audit M27)`);
+        `Use .create({ stream: true }) for gated streaming.`);
 }
 function hasTee(v) {
     return (v !== null &&
@@ -713,21 +733,23 @@ function isThenable(v) {
         typeof v.then === "function");
 }
 /**
- * 完全互換 wrap の deferred 返り値(2026-07 full-compat)。
+ * Deferred return value of the full-compat wrap (2026-07).
  *
- * gate 待ち / stream の tee 変換がある経路では元の APIPromise をそのまま返せない。
- * その場合でも then/catch/finally に加えて .withResponse() を委譲で温存する
- * (data は mapData 経由 = stream なら tee のユーザー枝に差し替え)。
- * .asResponse()(生 Response の直接読み)だけは観測(parse)と構造的に両立しない
- * ため非対応のまま(docs 開示済み)。
+ * Paths involving a gate wait or a stream tee transform cannot return the
+ * original APIPromise as-is. Even then, .withResponse() is preserved via
+ * delegation in addition to then/catch/finally (data goes through mapData —
+ * for streams it is swapped for the user branch of the tee). Only
+ * .asResponse() (direct reads of the raw Response) remains unsupported, since
+ * it is structurally incompatible with observation (parsing); this is
+ * disclosed in the docs.
  */
 function makeCompatAPIPromise(result, sourceBox, mapData) {
-    // 本物の Promise を返す(instanceof Promise / util.types.isPromise 互換。Codex LOW)。
+    // Return a real Promise (compatible with instanceof Promise / util.types.isPromise).
     const out = result.then((v) => v);
-    // 犠牲 catch: record 用に常時 attach される settled チェーンの rejection が、
-    // ユーザーが withResponse() だけ使う/全く await しない場合に Node の
-    // unhandledRejection にならないようにする(Codex HIGH)。ユーザーの await には
-    // 同じ rejection がそのまま届く。
+    // Sacrificial catch: prevents the rejection of the always-attached settled
+    // chain (used for recording) from becoming a Node unhandledRejection when
+    // the user only uses withResponse() or never awaits at all. The user's own
+    // await still receives the same rejection.
     void out.catch(() => { });
     out.withResponse = () => sourceBox.then((box) => {
         const api = box.api;
@@ -748,28 +770,32 @@ function makeCompatAPIPromise(result, sourceBox, mapData) {
     return out;
 }
 /**
- * deferred compat オブジェクトの asResponse() 用エラー。生 Response の body を
- * ユーザーが直接読む API は記録のための parse と構造的に両立しない(body の
- * 二重消費)ため、compat 側では静かに壊れるのでなく明確に失敗させる。
- * ⚠ identity fast path で返す元の APIPromise の asResponse には触らない:
- * 実 openai-node の withResponse() が内部で asResponse() を呼ぶため、上書きすると
- * withResponse まで壊れる(実パッケージスモークで検出)。そちらは docs 開示で対応。
+ * Error for asResponse() on the deferred compat object. An API that lets the
+ * user read the raw Response body directly is structurally incompatible with
+ * the parse needed for recording (the body would be consumed twice), so on the
+ * compat side we fail loudly instead of breaking silently.
+ * Warning: do not touch asResponse on the original APIPromise returned by the
+ * identity fast path — the real openai-node withResponse() calls asResponse()
+ * internally, so overriding it would break withResponse too (caught in a smoke
+ * test against the real package). That case is handled by docs disclosure.
  */
 const UNSUPPORTED_AS_RESPONSE = "[argosvix] asResponse() is not supported on wrapped clients (the raw body " +
     "would be consumed twice). Use withResponse(), or call this endpoint on an " +
     "unwrapped client.";
 /**
- * 記録用ジェネレータ(wrapOpenAIStream 等)を裏で完走させる。tee の観測枝の消費専用。
- * 記録・エラー記録はジェネレータ内部で完結しているので、ここでは黙って回すだけ。
+ * Run a recording generator (wrapOpenAIStream etc.) to completion in the
+ * background. Used solely to consume the observation branch of a tee.
+ * Recording and error recording are fully handled inside the generator, so
+ * this just spins it silently.
  */
 async function drainRecordingStream(gen) {
     try {
         for await (const _chunk of gen) {
-            /* 観測枝の消費のみ(yield 値は捨てる) */
+            /* Consume the observation branch only (yielded values are discarded) */
         }
     }
     catch {
-        /* エラー記録はジェネレータ側で済んでいる */
+        /* Error recording is already done inside the generator */
     }
 }
 function wrapOpenAIChat(client, recorder, config) {
@@ -782,12 +808,13 @@ function wrapOpenAIChat(client, recorder, config) {
         const callTags = buildTags(config, "openai", requestArgs);
         const id = generateId();
         const isStream = requestArgs.stream === true;
-        // 監査 2026-06-28 HIGH = OpenAI は stream 時に stream_options.include_usage を
-        // 付けないと usage を一切返さず、 streaming 呼び出しが 0 token / $0 で記録され
-        // コストが黙って過少計上(+ budget gate が streaming で素通り)になる。 stream の
-        // とき include_usage を補う(client が明示設定済みならそれを尊重)。
-        // ⚠ 我々が注入した場合、 OpenAI が末尾に足す usage-only チャンク(choices=[])は
-        // host に yield しない(choices[0] 前提の素朴な消費側を壊さないため。Codex 指摘)。
+        // Without stream_options.include_usage, OpenAI returns no usage at all for
+        // streams, so streaming calls would be recorded as 0 tokens / $0 — silently
+        // under-counting cost (and letting streaming pass the budget gate). Inject
+        // include_usage for streams (respecting an explicit client setting).
+        // Warning: when we injected it, the trailing usage-only chunk OpenAI appends
+        // (choices=[]) is not yielded to the host, so naive consumers that assume
+        // choices[0] don't break. (2026-06-28)
         const usageInjected = isStream && requestArgs.stream_options?.include_usage === undefined;
         if (usageInjected) {
             args = [...args];
@@ -804,7 +831,7 @@ function wrapOpenAIChat(client, recorder, config) {
                 const model = r.model || requestArgs.model || "unknown";
                 const promptTokens = r.usage?.prompt_tokens ?? 0;
                 const completionTokens = r.usage?.completion_tokens ?? 0;
-                // OpenAI: prompt_tokens は cached を含む合計。cached は内数。
+                // OpenAI: prompt_tokens is the total including cached tokens; cached is a subset.
                 const cachedReadTokens = r.usage?.prompt_tokens_details?.cached_tokens ?? 0;
                 const cost = calculateCostWithCache("openai", model, promptTokens, completionTokens, cachedReadTokens, 0);
                 const record = {
@@ -838,7 +865,7 @@ function wrapOpenAIChat(client, recorder, config) {
                 recorder.record(record);
             }
             catch {
-                /* 記録は best-effort = host の呼び出しを壊さない */
+                /* Recording is best-effort — never break the host's call */
             }
         };
         const recordFailure = (err) => {
@@ -862,12 +889,12 @@ function wrapOpenAIChat(client, recorder, config) {
                 });
             }
             catch {
-                /* 記録は best-effort */
+                /* Recording is best-effort */
             }
         };
-        // ---- 非 stream + gate 無効 = identity fast path ----
-        // 元の APIPromise をそのまま返す(= .withResponse() / .asResponse() が本物のまま)。
-        // 記録は observer .then で行う(同一 promise の複数 then は安全)。
+        // ---- Non-stream + gate disabled: identity fast path ----
+        // Return the original APIPromise as-is (.withResponse() / .asResponse() stay real).
+        // Recording is done via an observer .then (multiple thens on the same promise are safe).
         if (!isStream && !recorder.budgetGate.isActive) {
             let ret;
             try {
@@ -884,9 +911,10 @@ function wrapOpenAIChat(client, recorder, config) {
             recordSuccess(ret);
             return ret;
         }
-        // ---- deferred 経路(gate 有効 or stream)----
-        // async 関数の return は thenable を自動 flatten して APIPromise が消えるため、
-        // { api } の箱で包んで識別を保持する(withResponse 委譲用)。
+        // ---- Deferred path (gate enabled or stream) ----
+        // An async function's return auto-flattens thenables, which would erase the
+        // APIPromise, so wrap it in an { api } box to preserve its identity (for
+        // withResponse delegation).
         const sourceBox = (async () => {
             await recorder.budgetGate.check({ model: requestArgs.model, payload: requestArgs });
             return { api: originalCreate(...args) };
@@ -906,32 +934,35 @@ function wrapOpenAIChat(client, recorder, config) {
         // ---- stream ----
         const capture = buildStreamCapture(config, () => extractOpenAIChatPromptBody(requestArgs));
         const wrapForRecord = (raw) => wrapOpenAIStream(raw, recorder, requestArgs, start, id, callTags, traceMeta, usageInjected, capture);
-        // tee 変換は経路(await / withResponse().data)をまたいで 1 回だけ。
+        // The tee transform runs exactly once across paths (await / withResponse().data).
         let transformDone = false;
         let transformedValue;
         const transformOnce = (raw) => {
             if (transformDone)
                 return transformedValue;
-            // usage 注入時は tee しない: 注入した usage-only チャンク(choices=[])が
-            // ユーザー枝に素通りして素朴な消費側を壊すため(2026-06-28 監査の非回帰)。
+            // Do not tee when usage was injected: the injected usage-only chunk
+            // (choices=[]) would pass straight through to the user branch and break
+            // naive consumers (regression guard, 2026-06-28).
             if (!usageInjected && hasTee(raw)) {
                 try {
                     const [obs, user] = raw.tee();
-                    // フラグ確定は tee 成功後(同期 throw するカスタム stream で毒らない。Codex)。
+                    // Commit the flag only after tee succeeds (so a custom stream that throws synchronously cannot poison it).
                     transformDone = true;
                     transformedValue = user;
-                    // 観測枝を既存の記録ジェネレータで drain(記録ロジックを複製しない)。
-                    // ユーザー枝は本物の Stream のまま = .tee() / .toReadableStream() /
-                    // .controller が全て生きる。ユーザーが途中 break しても観測枝は完走する
-                    // ので usage は完全に記録される。
-                    // ⚠ メモリ特性: 観測枝の先行 drain 中、未消費のユーザー枝には tee の内部
-                    // キューに全チャンクが滞留する(上限 = レスポンス全体)。確実な記録との
-                    // トレードオフとして許容(docs に開示)。
+                    // Drain the observation branch with the existing recording generator
+                    // (no duplication of recording logic). The user branch stays a real
+                    // Stream, so .tee() / .toReadableStream() / .controller all keep
+                    // working. Even if the user breaks early, the observation branch runs
+                    // to completion, so usage is fully recorded.
+                    // Memory note: while the observation branch drains ahead, all chunks
+                    // for the unconsumed user branch pile up in tee's internal queue
+                    // (bounded by the whole response). Accepted as a trade-off for
+                    // reliable recording (disclosed in the docs).
                     void drainRecordingStream(wrapForRecord(obs));
                     return user;
                 }
                 catch {
-                    /* tee 失敗 → 従来経路へ */
+                    /* tee failed — fall back to the legacy path */
                 }
             }
             transformDone = true;
@@ -948,16 +979,19 @@ function wrapOpenAIChat(client, recorder, config) {
     };
 }
 async function* wrapOpenAIStream(stream, recorder, requestArgs, start, id, 
-// Codex r2 HIGH: stream record の userId は generator 消費開始時ではなく
-// wrapper 入口で確定した callTags を使う (= await 後の requestArgs 再読みを排除)。
+// The stream record's userId must come from the callTags resolved at the
+// wrapper entry, not at generator consumption start (eliminates re-reading
+// requestArgs after an await).
 callTags, 
-// Codex #1 R1: trace 軸も入口で snapshot した meta を使う (= stream を withTrace の外で
-// 消費しても ambient 消失 / 別 trace への取り違えを防ぐ)。
+// The trace fields also use the meta snapshotted at entry, so consuming the
+// stream outside withTrace can neither lose the ambient context nor attribute
+// the call to the wrong trace.
 traceMeta, 
-// 我々が include_usage を注入したか。 true のとき末尾 usage-only チャンクは host に
-// yield せず観測だけする(consumer の stream 形状を変えない)。
+// Whether we injected include_usage. When true, the trailing usage-only chunk
+// is observed but not yielded to the host (keeps the consumer's stream shape
+// unchanged).
 usageInjected = false, 
-// streaming 平文キャプチャ(captureContent=true のときのみ渡る)。
+// Streaming plaintext capture (passed only when captureContent=true).
 capture) {
     let finalModel = requestArgs.model || "unknown";
     let promptTokens = 0;
@@ -965,14 +999,16 @@ capture) {
     let cachedReadTokens = 0;
     let reportedTotal;
     let lastUsage;
-    // 監査 Tier 2 = TTFT。 最初に本文 delta を載せたチャンク到達時刻 - 開始時刻。
+    // TTFT: arrival time of the first chunk carrying a content delta, minus start time.
     let ttftMs;
-    // 正常完走したか(早期 break / abandon では false のまま → 本文に truncated marker)。
+    // Whether the stream ran to completion (stays false on early break / abandon → the body gets the truncated marker).
     let completed = false;
-    // 監査 2026-06-28 = 消費側が早期 break / abandon すると generator が yield で
-    // .return() され、 ループ後の記録が skip されて課金済み呼び出しが record されない
-    // (budget gate の spend も漏れる)。 finally + recorded フラグで「正常完走 / error /
-    // 途中打ち切り」のいずれでも観測済みトークンで 1 回だけ記録する(Python SDK と同等)。
+    // If the consumer breaks early or abandons the stream, the generator gets
+    // .return()ed at the yield and the post-loop recording is skipped, so a
+    // billed call would never be recorded (and the budget gate's spend would
+    // leak too). With finally + the recorded flag, the call is recorded exactly
+    // once with the observed tokens on normal completion, error, and early
+    // termination alike (matches the Python SDK). (2026-06-28)
     let recorded = false;
     const recordOnce = () => {
         if (recorded)
@@ -1003,8 +1039,9 @@ capture) {
     try {
         for await (const chunk of stream) {
             if (ttftMs === undefined && chunkHasStreamedOutput(chunk)) {
-                // 最初に「本文 / ツール / 音声」を載せたチャンク = 初回トークン。 role だけの
-                // 先頭チャンクでは立てない(= TTFT を過小評価しない、 Codex SHOULD_FIX)。
+                // The first chunk carrying content / tool / audio counts as the first
+                // token. Not triggered by the leading role-only chunk (avoids
+                // underestimating TTFT).
                 ttftMs = Date.now() - start;
             }
             capture?.acc.push(extractOpenAIStreamDeltaText(chunk));
@@ -1021,23 +1058,25 @@ capture) {
                     cachedReadTokens = chunk.usage.prompt_tokens_details.cached_tokens;
                 }
             }
-            // 我々が注入した include_usage の末尾 usage-only チャンク(choices 空)は観測のみで
-            // host に渡さない(注入していない=client が自分で付けた場合はそのまま yield)。
+            // The trailing usage-only chunk (empty choices) produced by the
+            // include_usage we injected is observed only and not passed to the host
+            // (if we did not inject it — the client set it themselves — it is
+            // yielded as-is).
             if (usageInjected && chunk.usage != null && (chunk.choices?.length ?? 0) === 0) {
                 continue;
             }
             yield chunk;
         }
-        // controller.abort() を openai-node Stream は握って正常終了扱いにするため、
-        // ここに到達する。clean success ではなく途中打ち切り(truncated)として記録する
-        // (Codex MEDIUM: 過少 usage の成功記録を防ぐ)。
+        // The openai-node Stream swallows controller.abort() and treats it as a
+        // normal end, so execution reaches here. Record it as truncated rather than
+        // a clean success (prevents recording under-counted usage as a success).
         const aborted = stream.controller
             ?.signal?.aborted === true;
         completed = !aborted;
         recordOnce();
     }
     catch (err) {
-        recorded = true; // error record で確定(finally の recordOnce を抑止)
+        recorded = true; // finalized by the error record (suppresses recordOnce in finally)
         const errorDetails = extractErrorDetails(err);
         const errorRecord = {
             id,
@@ -1055,13 +1094,13 @@ capture) {
             ...(errorDetails ? { errorDetails } : {}),
             requestMeta: buildOpenAIRequestMeta(requestArgs),
         };
-        // 例外で切れた場合は「そこまでの本文 + truncated マーカー」を record に載せる。
+        // When cut off by an exception, put the body captured so far + the truncated marker on the record.
         applyStreamCapture(errorRecord, capture, true);
         recorder.record(errorRecord);
         throw err;
     }
     finally {
-        // 早期 break / abandon の経路。 正常完走・error 済みなら no-op。
+        // Early break / abandon path. No-op if the stream already completed normally or errored.
         recordOnce();
     }
 }
@@ -1111,7 +1150,7 @@ function wrapOpenAIResponses(client, recorder, config) {
                 });
             }
             catch {
-                /* 記録は best-effort */
+                /* Recording is best-effort */
             }
         };
         const recordSuccess = (response0) => {
@@ -1153,10 +1192,10 @@ function wrapOpenAIResponses(client, recorder, config) {
                 recorder.record(record);
             }
             catch {
-                /* 記録は best-effort */
+                /* Recording is best-effort */
             }
         };
-        // ---- 非 stream + gate 無効 = identity fast path(chat と同型)----
+        // ---- Non-stream + gate disabled: identity fast path (same shape as chat) ----
         if (!isStream && !recorder.budgetGate.isActive) {
             let ret;
             try {
@@ -1173,7 +1212,7 @@ function wrapOpenAIResponses(client, recorder, config) {
             recordSuccess(ret);
             return ret;
         }
-        // ---- deferred 経路(gate 有効 or stream)----
+        // ---- Deferred path (gate enabled or stream) ----
         const sourceBox = (async () => {
             await recorder.budgetGate.check({ model: requestArgs.model, payload: requestArgs });
             return { api: originalCreate(...args) };
@@ -1207,7 +1246,7 @@ function wrapOpenAIResponses(client, recorder, config) {
                     return user;
                 }
                 catch {
-                    /* tee 失敗 → 従来経路へ */
+                    /* tee failed — fall back to the legacy path */
                 }
             }
             transformDone = true;
@@ -1224,10 +1263,12 @@ function wrapOpenAIResponses(client, recorder, config) {
     };
 }
 /**
- * Responses API stream の記録ジェネレータ(2026-07 に inline から抽出)。
- * response.output_text.delta / refusal.delta を蓄積し、response.completed の usage で
- * 確定。error / response.failed / response.incomplete イベントも処理(Codex 済)。
- * 完全互換経路では tee の観測枝をこれで drain し、ユーザー枝は本物の Stream を返す。
+ * Recording generator for Responses API streams (extracted from inline code in
+ * 2026-07). Accumulates response.output_text.delta / refusal.delta and
+ * finalizes with the usage from response.completed. Also handles error /
+ * response.failed / response.incomplete events. On the full-compat path this
+ * drains the tee's observation branch while the user branch stays the real
+ * Stream that is returned.
  */
 async function* wrapOpenAIResponsesStream(stream, recorder, requestArgs, start, id, callTags, traceMeta, capture) {
     {
@@ -1237,7 +1278,7 @@ async function* wrapOpenAIResponsesStream(stream, recorder, requestArgs, start,
                 let usage;
                 let completed = false;
                 let recorded = false;
-                // Codex: stream イベントとして来る terminal failure / 完了未観測を扱う。
+                // Handle terminal failures arriving as stream events, and the case where completion was never observed.
                 let sawCompleted = false;
                 let incomplete = false;
                 let streamError;
@@ -1245,7 +1286,7 @@ async function* wrapOpenAIResponsesStream(stream, recorder, requestArgs, start,
                     if (recorded)
                         return;
                     recorded = true;
-                    // stream イベントの error/failed を error record にして success を抑止(Codex HIGH)。
+                    // Turn error/failed stream events into an error record and suppress the success record.
                     if (streamError !== undefined) {
                         const errRecord = {
                             id,
@@ -1293,7 +1334,7 @@ async function* wrapOpenAIResponsesStream(stream, recorder, requestArgs, start,
                 try {
                     for await (const event of stream) {
                         const ev = event;
-                        // 本文 delta = output_text と refusal の両方(Codex MEDIUM: refusal が抜けていた)。
+                        // Content deltas include both output_text and refusal (refusal was missing originally).
                         if ((ev.type === "response.output_text.delta" ||
                             ev.type === "response.refusal.delta") &&
                             typeof ev.delta === "string") {
@@ -1309,7 +1350,7 @@ async function* wrapOpenAIResponsesStream(stream, recorder, requestArgs, start,
                             incomplete = ev.type === "response.incomplete";
                         }
                         else if (ev.type === "error" || ev.type === "response.failed") {
-                            // stream イベントとして来る terminal error を記録(Codex HIGH)。
+                            // Record terminal errors that arrive as stream events.
                             const respErr = ev.response?.error?.message;
                             streamError =
                                 typeof respErr === "string"
@@ -1392,8 +1433,8 @@ function wrapAnthropic(client, recorder, config) {
             const r = response;
             const latencyMs = Date.now() - start;
             const model = r.model || requestArgs.model || "unknown";
-            // Anthropic: input_tokens は「非キャッシュ input」。cache 読取/書込は別計上なので
-            // promptTokens(= input 合計)に足し戻す。
+            // Anthropic: input_tokens counts only non-cached input. Cache reads/writes
+            // are reported separately, so add them back into promptTokens (total input).
             const cachedReadTokens = r.usage?.cache_read_input_tokens ?? 0;
             const cachedWriteTokens = r.usage?.cache_creation_input_tokens ?? 0;
             const promptTokens = (r.usage?.input_tokens ?? 0) + cachedReadTokens + cachedWriteTokens;
@@ -1450,17 +1491,17 @@ function wrapAnthropic(client, recorder, config) {
     };
 }
 async function* wrapAnthropicStream(stream, recorder, requestArgs, start, id, callTags, traceMeta, 
-// streaming 平文キャプチャ(captureContent=true のときのみ渡る)。
+// Streaming plaintext capture (passed only when captureContent=true).
 capture) {
     let model = requestArgs.model || "unknown";
-    // Anthropic: input_tokens は「非キャッシュ input」。 cache 読取/書込は別計上。
+    // Anthropic: input_tokens counts only non-cached input. Cache reads/writes are reported separately.
     let inputTokens = 0;
     let cachedReadTokens = 0;
     let cachedWriteTokens = 0;
     let completionTokens = 0;
-    // 正常完走したか(早期 break / abandon では false のまま → 本文に truncated marker)。
+    // Whether the stream ran to completion (stays false on early break / abandon → the body gets the truncated marker).
     let completed = false;
-    // 監査 2026-06-28 = 早期 break でも観測済みトークンで 1 回だけ記録(OpenAI と同様)。
+    // Record exactly once with the observed tokens even on early break (same as OpenAI; 2026-06-28).
     let recorded = false;
     const recordOnce = () => {
         if (recorded)
@@ -1494,7 +1535,7 @@ capture) {
                 event.type === "content_block_delta" &&
                 event.delta?.type === "text_delta" &&
                 typeof event.delta.text === "string") {
-                // テキスト delta のみ蓄積(ツール引数の input_json_delta 等は対象外)。
+                // Accumulate text deltas only (tool-argument input_json_delta etc. are out of scope).
                 capture.acc.push(event.delta.text);
             }
             if (event.type === "message_start" && event.message) {
@@ -1537,7 +1578,7 @@ capture) {
             ...(errorDetails ? { errorDetails } : {}),
             requestMeta: buildAnthropicRequestMeta(requestArgs),
         };
-        // 例外で切れた場合は「そこまでの本文 + truncated マーカー」を record に載せる。
+        // When cut off by an exception, put the body captured so far + the truncated marker on the record.
         applyStreamCapture(errorRecord, capture, true);
         recorder.record(errorRecord);
         throw err;
@@ -1634,7 +1675,7 @@ function wrapMistral(client, recorder, config) {
                 return wrapMistralStream(stream, recorder, requestArgs, start, id, callTags, buildTraceMeta(config), buildStreamCapture(config, () => extractMistralPromptBody(requestArgs)));
             }
             catch (err) {
-                // H-2: stream initialization error (= auth/validation/connection)
+                // Stream initialization error (auth/validation/connection)
                 const errorDetails = extractErrorDetails(err);
                 recorder.record({
                     id,
@@ -1658,15 +1699,15 @@ function wrapMistral(client, recorder, config) {
     }
 }
 async function* wrapMistralStream(stream, recorder, requestArgs, start, id, callTags, traceMeta, 
-// streaming 平文キャプチャ(captureContent=true のときのみ渡る)。
+// Streaming plaintext capture (passed only when captureContent=true).
 capture) {
     let model = requestArgs.model || "unknown";
     let promptTokens = 0;
     let completionTokens = 0;
     let reportedTotal;
-    // 正常完走したか(早期 break / abandon では false のまま → 本文に truncated marker)。
+    // Whether the stream ran to completion (stays false on early break / abandon → the body gets the truncated marker).
     let completed = false;
-    // 監査 2026-06-28 = 早期 break でも観測済みトークンで 1 回だけ記録(OpenAI と同様)。
+    // Record exactly once with the observed tokens even on early break (same as OpenAI; 2026-06-28).
     let recorded = false;
     const recordOnce = () => {
         if (recorded)
@@ -1693,7 +1734,7 @@ capture) {
         for await (const chunk of stream) {
             const inner = chunk.data ?? chunk;
             if (capture) {
-                // Mistral は OpenAI Chat 互換の delta 形状(choices[0].delta.content、string のみ)。
+                // Mistral uses the OpenAI-Chat-compatible delta shape (choices[0].delta.content, strings only).
                 const delta = inner.choices?.[0]?.delta;
                 if (typeof delta?.content === "string")
                     capture.acc.push(delta.content);
@@ -1731,7 +1772,7 @@ capture) {
             ...(errorDetails ? { errorDetails } : {}),
             requestMeta: buildMistralRequestMeta(requestArgs),
         };
-        // 例外で切れた場合は「そこまでの本文 + truncated マーカー」を record に載せる。
+        // When cut off by an exception, put the body captured so far + the truncated marker on the record.
         applyStreamCapture(errorRecord, capture, true);
         recorder.record(errorRecord);
         throw err;
@@ -1843,20 +1884,24 @@ function wrapGeminiLegacyModel(model, modelName, recorder, config) {
                 const result = (await originalStream(...args));
                 if (!result.stream)
                     return result;
-                // 消費側が早期 break / abandon すると generator が .return() され、ループ後の
-                // 記録が skip されて課金済み呼び出しが record されない(他 3 provider と同じく
-                // recordOnce()+finally で「完走 / error / 途中打ち切り」いずれでも 1 回だけ記録)。
+                // If the consumer breaks early or abandons the stream, the generator
+                // gets .return()ed and the post-loop recording is skipped, so a billed
+                // call would never be recorded (as with the other 3 providers,
+                // recordOnce() + finally record exactly once on completion, error, or
+                // early termination).
                 const originalStreamRef = result.stream;
-                // #1 R1: trace 軸は stream 生成時(= 入口、 ambient 有効)に snapshot する。
+                // The trace fields are snapshotted at stream creation (the entry point, where the ambient context is still active).
                 const traceMeta = buildTraceMeta(config);
-                // streaming 平文キャプチャ = promptBody 入口 snapshot + delta 蓄積。
+                // Streaming plaintext capture: promptBody snapshotted at entry + delta accumulation.
                 const capture = buildStreamCapture(config, () => extractGeminiPromptBody(requestArgs));
                 const wrappedStream = (async function* () {
                     let completed = false;
                     let recorded = false;
-                    // legacy Gemini は usage を完走後の result.response からしか読めないため、
-                    // 早期 break では 0 トークン(+ truncated マーカー)で記録する。完走時だけ
-                    // result.response を await する(早期 break で await するとハング/追加消費)。
+                    // Legacy Gemini only exposes usage via result.response after the
+                    // stream completes, so on early break we record 0 tokens (+ the
+                    // truncated marker). result.response is awaited only on full
+                    // completion (awaiting it after an early break can hang or consume
+                    // extra).
                     let promptTokens = 0;
                     let completionTokens = 0;
                     let cachedReadTokens = 0;
@@ -1918,13 +1963,13 @@ function wrapGeminiLegacyModel(model, modelName, recorder, config) {
                             ...(errorDetails ? { errorDetails } : {}),
                             requestMeta: buildGeminiRequestMeta(requestArgs),
                         };
-                        // 例外で切れた場合は「そこまでの本文 + truncated マーカー」を record に載せる。
+                        // When cut off by an exception, put the body captured so far + the truncated marker on the record.
                         applyStreamCapture(errorRecord, capture, true);
                         recorder.record(errorRecord);
                         throw err;
                     }
                     finally {
-                        // 早期 break / abandon の経路。 正常完走・error 済みなら no-op。
+                        // Early break / abandon path. No-op if the stream already completed normally or errored.
                         recordOnce();
                     }
                 })();
@@ -2033,10 +2078,10 @@ function wrapGeminiNew(client, recorder, config) {
             try {
                 await recorder.budgetGate.check({ model: modelName, payload: requestArgs });
                 const stream = (await originalStream(...args));
-                // C-2 + H-3 fix: AsyncGenerator wrap with finally-record + error tied to consumption
-                // #1 R1: trace 軸は stream 生成時(= 入口、 ambient 有効)に snapshot する。
+                // Fix: AsyncGenerator wrap with finally-record + error handling tied to consumption
+                // The trace fields are snapshotted at stream creation (the entry point, where the ambient context is still active).
                 const traceMeta = buildTraceMeta(config);
-                // streaming 平文キャプチャ = promptBody 入口 snapshot + delta 蓄積。
+                // Streaming plaintext capture: promptBody snapshotted at entry + delta accumulation.
                 const capture = buildStreamCapture(config, () => extractGeminiPromptBody(requestArgs));
                 return (async function* () {
                     let lastUsage;
@@ -2100,13 +2145,13 @@ function wrapGeminiNew(client, recorder, config) {
                             ...(errorDetails ? { errorDetails } : {}),
                             requestMeta: buildGeminiNewRequestMeta(requestArgs),
                         };
-                        // 例外で切れた場合は「そこまでの本文 + truncated マーカー」を record に載せる。
+                        // When cut off by an exception, put the body captured so far + the truncated marker on the record.
                         applyStreamCapture(errorRecord, capture, true);
                         recorder.record(errorRecord);
                         throw err;
                     }
                     finally {
-                        // 早期 break / abandon の経路。 正常完走・error 済みなら no-op。
+                        // Early break / abandon path. No-op if the stream already completed normally or errored.
                         recordOnce();
                     }
                 })();
@@ -2161,11 +2206,15 @@ function buildGeminiNewRequestMeta(requestArgs) {
 /**
  * Time-ordered record ID generator.
  *
- * audit round2 M26 fix = 旧実装は `Date.now()` prefix + `Math.random().toString(36).slice(2,10)`
- * suffix で、 (1) 非暗号乱数 (2) 値次第で suffix が 8 文字未満になり実効エントロピーが
- * 41bit を大きく下回る、 という二重の弱さがあった。 backend は
- * `INSERT ... ON CONFLICT(account_id, id) DO NOTHING` で衝突を無音 skip するため、
- * 衝突した本物の call が課金・quota・観測から消える。 暗号乱数 (crypto.getRandomValues /
- * randomUUID) で 128bit 級の衝突耐性に引き上げる。 先頭に時刻 prefix を残して時系列順も保つ。
+ * Fix: the previous implementation used a `Date.now()` prefix + a
+ * `Math.random().toString(36).slice(2,10)` suffix, which had two weaknesses:
+ * (1) non-cryptographic randomness, and (2) depending on the value the suffix
+ * could be shorter than 8 characters, dropping the effective entropy well
+ * below 41 bits. The backend silently skips collisions via
+ * `INSERT ... ON CONFLICT(account_id, id) DO NOTHING`, so a real call that
+ * collides would vanish from billing, quota, and observation. Cryptographic
+ * randomness (crypto.getRandomValues / randomUUID) raises collision resistance
+ * to the 128-bit class. The leading time prefix is kept so ordering stays
+ * chronological.
  */
 //# sourceMappingURL=client.js.map