@argosvix/sdk 0.4.22-alpha.0 → 0.5.0

package/dist/redaction.js

@@ -1,87 +1,95 @@
 /**
  * Plaintext PII redaction for the captureContent opt-in path.
  *
- * Argosvix v1.x = Pro+ 平文保存機能の SDK 側 opt-in 時に prompt / completion
- * 本文をそのまま送信する前に、 メールアドレス / クレジットカード番号 /
- * 電話番号 / マイナンバー / IP アドレスを自動マスキングするためのヘルパー。
+ * Helper that automatically masks email addresses / credit card numbers /
+ * phone numbers / Japanese My Number / IP addresses before prompt and
+ * completion bodies are sent verbatim under the Pro+ plaintext storage
+ * feature's SDK-side opt-in.
  *
- * 設計方針:
- *   - false positive 寛容、false negative 厳禁(= 過剰マスクは OK、 PII の
- *     見落としは NG)。 ユーザーが明示的に disablePiiRedaction:true で無効化
- *     しない限り、この関数が必ず通る
- *   - 関数は純関数で副作用なし。 同じ入力に対して常に同じ出力
- *   - 入力が空文字または null / undefined のときは入力をそのまま返す
- *   - 入力が文字列でない場合(オブジェクト等)は String() で文字列化してから
- *     置換、 ただし元の型は保たず string を返す
+ * Design policy:
+ *   - False-positive tolerant, false negatives strictly avoided (over-masking
+ *     is OK; missing PII is not). This function always runs unless the user
+ *     explicitly disables it with disablePiiRedaction:true.
+ *   - Pure function with no side effects. Same input always yields same output.
+ *   - An empty string or null / undefined input is returned as-is.
+ *   - Non-string input (objects etc.) is stringified with String() before
+ *     replacement; the original type is not preserved — a string is returned.
  *
- * 既知の限界:
- *   - 国際電話番号は形式が多様で全カバーは不可能。 conservative パターンで
- *     +81-XX-XXXX-XXXX / 090-XXXX-XXXX 等の主要日本パターンと、 北米 (123)
- *     456-7890 形式を中心にカバー
- *   - クレジットカード番号は Luhn check はしない(false positive 寛容)。
- *     13-19 桁の連続数字列(スペースとハイフン区切り含む)を一律置換
- *   - マイナンバーは 12 桁数字。 クレジットカードと衝突する場合は 12 桁数字
- *     が先に CC パターンにマッチする可能性あり = 結果は両方とも置換される
- *     ので個人情報混入リスクとしては問題なし(マスキング種別が不正確に
- *     なるだけ)
+ * Known limitations:
+ *   - International phone number formats are too diverse to cover fully.
+ *     Conservative patterns focus on the major Japanese forms
+ *     (+81-XX-XXXX-XXXX / 090-XXXX-XXXX etc.) and the North American
+ *     (123) 456-7890 form.
+ *   - Credit card numbers are not Luhn-checked (false-positive tolerant).
+ *     Any run of 13-19 digits (including space and hyphen separators) is
+ *     replaced uniformly.
+ *   - My Number is 12 digits. Where it collides with the credit card pattern,
+ *     the 12-digit run may match the CC pattern first — either way both get
+ *     replaced, so there is no PII-leak risk (only the masking category may
+ *     be inaccurate).
  */
 /**
- * 2026-06-02 Round D = pattern 毎の type tag を 追加 (= migration 0042
- * redaction_metadata に counts JSON を 集計するため、 各 regex がどの
- * カテゴリかを 明示する)。 metadata = { email: N, creditCard: N, ... }。
+ * Each pattern carries a type tag so we can aggregate a counts JSON into the
+ * backend's redaction_metadata column — each regex declares which category it
+ * belongs to. metadata = { email: N, creditCard: N, ... }.
  */
 const PATTERNS = [
-    // Email = RFC 5322 ベース。 audit round2 fix = 旧 ASCII 限定パターンは IDN ドメイン
-    // (例え.jp) や非ASCII local-part (山田@) を見落とした。 false-positive 寛容方針に従い
-    // local/domain/TLD を 非空白・非@ 文字に広げて 国際化アドレスも捕捉する。
+    // Email, RFC 5322 based. An earlier ASCII-only pattern missed IDN domains
+    // (e.g. Japanese-script domains under .jp) and non-ASCII local parts.
+    // Following the false-positive-tolerant policy, local/domain/TLD are widened
+    // to any non-whitespace, non-@ characters so internationalized addresses are
+    // also captured.
     {
         regex: /[^\s@]+@[^\s@]+\.[^\s@]{2,}/g,
         replacement: "[REDACTED_EMAIL]",
         type: "email",
     },
-    // Credit card (= 改行・空白を跨ぐ番号もカバー)。
-    // Codex Round 1 MEDIUM 修正 = 「\d sep \d sep ...」 構造で carry すると
-    // 最後の sep が次の \d を要求してしまい、 4111-1111-\n1111-1111 のような
-    // 改行を跨いだケースで match が切れる。 先頭 \d + 後続 (sep* \d) {12,18}
-    // で「区切りは複数連続可」 にして、 改行や複数空白も巻き込む。
+    // Credit card (also covers numbers spanning newlines and whitespace).
+    // A "\d sep \d sep ..." structure would make the trailing separator demand a
+    // following digit, breaking the match for newline-spanning cases like
+    // 4111-1111-\n1111-1111 (found in review). Using a leading \d followed by
+    // (sep* \d){12,18} allows multiple consecutive separators, so newlines and
+    // repeated spaces are swallowed too.
     {
-        // audit round2 M31 fix = 区切り文字に '.' を追加。 旧 pattern は space/tab/newline/hyphen
-        // のみ許可していたため、 ドット区切りの番号 (4111.1111.1111.1111) が CC に match せず、
-        // 後段の phone pattern に先食いされて末尾 4 桁が平文残存していた。 CC は phone より前に
-        // 走るので、 ドットを CC 区切りに含めれば全桁 redact される (false-positive 寛容方針)。
+        // '.' added to the separator set (found in review): the old pattern only
+        // allowed space/tab/newline/hyphen, so dot-separated numbers
+        // (4111.1111.1111.1111) did not match as CC, got partially consumed by the
+        // later phone pattern, and left the last 4 digits in plaintext. Since CC
+        // runs before phone, including dots as CC separators redacts all digits
+        // (false-positive-tolerant policy).
         regex: /\b\d(?:[ \t\r\n.-]*\d){12,18}\b/g,
         replacement: "[REDACTED_CC]",
         type: "creditCard",
     },
-    // マイナンバー = 12 桁数字、 単語境界で区切る
-    // (上の CC パターンが先に走るので 12-13 桁の重複は CC で処理される)
+    // Japanese My Number = 12 digits, delimited by word boundaries
+    // (the CC pattern above runs first, so 12-13 digit overlaps are handled as CC)
     {
         regex: /\b\d{12}\b/g,
         replacement: "[REDACTED_MYNUMBER]",
         type: "myNumber",
     },
-    // 電話番号 = 主要国の代表パターン:
-    //   - 日本 携帯: 090-XXXX-XXXX / 080-XXXX-XXXX / 070-XXXX-XXXX
-    //   - 日本 固定: 03-XXXX-XXXX / 06-XXXX-XXXX 等
-    //   - 国際: +81 90 XXXX XXXX / +1 (123) 456-7890
-    //   - 全角ハイフンや中黒は対象外(英数前提)
+    // Phone numbers = representative patterns for major countries:
+    //   - Japan mobile: 090-XXXX-XXXX / 080-XXXX-XXXX / 070-XXXX-XXXX
+    //   - Japan landline: 03-XXXX-XXXX / 06-XXXX-XXXX etc.
+    //   - International: +81 90 XXXX XXXX / +1 (123) 456-7890
+    //   - Fullwidth hyphens and middle dots are out of scope (ASCII assumed)
     {
         regex: /\+?\d{1,3}[-.\s]?\(?\d{2,4}\)?[-.\s]?\d{2,4}[-.\s]?\d{3,4}/g,
         replacement: "[REDACTED_PHONE]",
         type: "phone",
     },
-    // IPv4 = 4 オクテット、 0-255 の範囲は厳密 check せず conservative
+    // IPv4 = 4 octets; the 0-255 range is not strictly checked — kept conservative
     {
         regex: /\b(?:\d{1,3}\.){3}\d{1,3}\b/g,
         replacement: "[REDACTED_IPV4]",
         type: "ipv4",
     },
-    // IPv6 (フル形 + 短縮形)。 Codex Round 1 MEDIUM 修正で `::1` などの
-    // 短縮表記を含めて拾えるよう、 各 hex group を 0-4 桁(= 空 group が
-    // 「::」 と一致)で carry し、 lookbehind / lookahead で 単語境界を担保。
-    // `(?:[0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{1,4}` で `::1` / `fe80::1234` /
-    // 通常 8 group の全パターンを束ねる(false positive 寛容、 false negative
-    // 厳禁の方針)。
+    // IPv6 (full + shortened forms). To also catch shortened notations like
+    // `::1` (found in review), each hex group allows 0-4 digits (an empty group
+    // matches "::"), with lookbehind / lookahead providing the word boundaries.
+    // `(?:[0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{1,4}` bundles `::1` / `fe80::1234`
+    // and the ordinary 8-group form (false-positive tolerant, false negatives
+    // strictly avoided).
     {
         regex: /(?<![\w:.])(?:[0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{1,4}(?![\w:.])/g,
         replacement: "[REDACTED_IPV6]",
@@ -95,11 +103,12 @@ const PATTERNS = [
  * @returns The text with PII patterns replaced by [REDACTED_*] markers.
  */
 /**
- * audit round2 fix = 全角数字 (０-９ = U+FF10..FF19) を半角に正規化する。
- * 日本語 IME で入力された全角のクレジットカード番号・マイナンバー・電話番号・IP は
- * \d (= ASCII [0-9]) ベースの PII パターンを素通りしていた (= false negative)。
- * マッチ前に正規化することで全角 PII も確実に捕捉する (= 非PII の全角数字が半角化する
- * 副作用は false-positive 寛容方針で許容)。
+ * Normalize fullwidth digits (U+FF10..FF19) to ASCII. Fullwidth credit card
+ * numbers, My Number, phone numbers, and IPs typed via a Japanese IME slipped
+ * straight past the \d (ASCII [0-9]) based PII patterns — a false negative.
+ * Normalizing before matching reliably captures fullwidth PII too (the side
+ * effect that non-PII fullwidth digits become halfwidth is accepted under the
+ * false-positive-tolerant policy).
  */
 function normalizeFullwidthDigits(s) {
     return s.replace(/[０-９]/g, (c) => String.fromCharCode(c.charCodeAt(0) - 0xfee0));
@@ -120,12 +129,12 @@ export function redactPii(input) {
     return result;
 }
 /**
- * 2026-06-02 Round D = 同 redaction 処理を 行いつつ、 各 type で 何回 置換
- * が 発生したかを 同時 集計する。 backend redaction_metadata JSON 用 +
- * SDK 側で 「PII 含まれていたか」 判定 (= piiRedacted boolean) 用。
+ * Perform the same redaction while simultaneously counting how many
+ * replacements occurred per type. Feeds the backend redaction_metadata JSON
+ * and the SDK-side "did this contain PII" decision (the piiRedacted boolean).
  *
- * matchAll 経由で count を 取り、 続けて replace で carry。 regex は g flag
- * なので 2 回 走らせても 副作用なし。
+ * Counts are taken via match, then the replacement is applied. The regexes use
+ * the g flag, so running them twice has no side effects.
  */
 export function redactPiiWithCounts(input) {
     if (input == null)
@@ -146,8 +155,8 @@ export function redactPiiWithCounts(input) {
     return { text: result, counts };
 }
 /**
- * 2026-06-02 Round D = 複数の redaction 結果 (= prompt / completion / 各 tool
- * call) の counts を 加算合成する helper。
+ * Helper that sums the counts from multiple redaction results (prompt /
+ * completion / each tool call).
  */
 export function mergeRedactionCounts(base, addition) {
     const out = { ...base };
@@ -157,8 +166,8 @@ export function mergeRedactionCounts(base, addition) {
     return out;
 }
 /**
- * 2026-06-02 Round D = counts object に 1 件以上の redaction があるか。
- * piiRedacted boolean field の判定軸。
+ * Whether the counts object contains at least one redaction.
+ * The basis for the piiRedacted boolean field.
  */
 export function hasAnyRedaction(counts) {
     for (const v of Object.values(counts)) {

package/dist/redaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -7,19 +7,23 @@ export interface ArgosvixConfig {
     /** Tags attached to every record (e.g. service / env / userId). */
     tags?: Record<string, string>;
     /**
-     * provider の opaque なエンドユーザー識別子 (OpenAI: safety_identifier、
-     * Anthropic: metadata.user_id) を自動で `userId` タグに carry するか。 既定 true。
-     * 既にこれらを provider へ渡しているアプリは設定ゼロで dashboard の per-user 集計
-     * (/users) が効く。 PII が入りやすい OpenAI 旧 `user` は対象外 (= 必要なら明示
-     * `tags.userId` で carry)。 明示の `tags.userId` があればそちらを優先 (= 上書き
-     * しない)。 自動取得を無効化したい場合のみ false を指定する。
+     * Whether to automatically map the provider's opaque end-user identifier
+     * (OpenAI: safety_identifier, Anthropic: metadata.user_id) into the `userId`
+     * tag. Defaults to true. Apps already passing these to the provider get the
+     * dashboard's per-user aggregation (/users) with zero configuration. The
+     * legacy OpenAI `user` field is excluded because it tends to contain PII
+     * (pass an explicit `tags.userId` if needed). An explicit `tags.userId`
+     * takes precedence (it is never overwritten). Set false only to disable the
+     * automatic capture.
      */
     captureUserId?: boolean;
     /**
-     * 自動トレースコンテキスト伝播 (#1 R1)。 既定 on。 `withTrace(fn)` の内側で wrap した
-     * LLM 呼び出しは明示 traceId なしで同じ trace に自動グルーピングされる。 false にすると
-     * ambient コンテキストを無視し、 従来どおり明示 config.traceId のみで trace を組む。
-     * AsyncLocalStorage が無いランタイム(= nodejs_als 無効の Workers 等)では自動的に無効。
+     * Automatic trace-context propagation. On by default. LLM calls wrapped
+     * inside `withTrace(fn)` are automatically grouped into the same trace
+     * without an explicit traceId. Setting false ignores the ambient context and
+     * builds traces only from an explicit config.traceId, as before.
+     * Automatically disabled on runtimes without AsyncLocalStorage (e.g. Workers
+     * without the nodejs_als flag).
      */
     autoContext?: boolean;
     /** Disable record submission entirely (e.g. for local dev). Defaults to false. */
@@ -48,117 +52,127 @@ export interface ArgosvixConfig {
      */
     provider?: Provider;
     /**
-     * Trace ID = OTel subset の trace 軸 (= 同一 user request / job 内の
-     * 関連 LLM call 群)。 wrap() に渡すと この client の全 call record に
-     * 自動付与される (= 1 wrap = 1 trace の運用)。 multi-call chain で
-     * trace を共有する場合は同じ traceId で wrap、 別 chain なら 別 wrap
-     * or 上書き option 経由。 形式は user 自由 (= OTel hex / UUID / ULID /
-     * 任意 string)、 最大 128 文字。
+     * Trace ID = the trace axis of the OTel subset (the group of related LLM
+     * calls within one user request / job). When passed to wrap(), it is
+     * automatically attached to every call record from this client (one wrap =
+     * one trace). To share a trace across a multi-call chain, wrap with the same
+     * traceId; for a different chain, use a separate wrap or the override
+     * option. The format is up to the user (OTel hex / UUID / ULID / arbitrary
+     * string), max 128 chars.
      */
     traceId?: string;
     /**
-     * Span ID = この call (= wrap した client から発する LLM call 群) の
-     * span 識別子。 通常 wrap 単位で固定するより call 毎に動的に carry
-     * する path の方が clean (= 別 phase で per-call option carry 予定)。
-     * MVP では wrap option 経由で 1 wrap = 1 span (= sub call 自動継承)
-     * を 許容するが、 founder dogfood では traceId のみで充分なケース多。
+     * Span ID = the span identifier for the LLM calls issued by the wrapped
+     * client. Deriving it dynamically per call is usually cleaner than fixing it
+     * per wrap (a per-call option is planned for a later phase). The MVP allows
+     * one wrap = one span via the wrap option (sub-calls inherit automatically),
+     * though in practice a traceId alone is often sufficient.
      */
     spanId?: string;
     /**
-     * Parent span ID = この call の上流 / 直前 call の span_id。 wrap 単位
-     * で固定する path = ある工程の sub LLM call が 全て同 parent を持つ
-     * シンプル case を想定。
+     * Parent span ID = the span_id of this call's upstream / preceding call.
+     * Fixing it per wrap targets the simple case where all sub LLM calls of a
+     * given step share the same parent.
      */
     parentSpanId?: string;
     /**
-     * Session ID = user の任意 group 軸 (= 連続会話 / 同 daily session /
-     * 同 job)。 trace (= OTel 軸の 1 request 内 call group) より上位の
-     * 概念で、 1 session は 複数 trace を 含み得る。 wrap() に渡すと
-     * 全 call record に 自動付与され、 backend /v1/query/session/:id 経由で
-     * dashboard の conversation thread view に carry。 形式は user 自由
-     * (= UUID / ULID / 任意 string)、 最大 128 文字 [A-Za-z0-9_-]。
+     * Session ID = an arbitrary user-defined grouping axis (a continuous
+     * conversation / the same daily session / the same job). A higher-level
+     * concept than a trace (the OTel-style call group within one request); one
+     * session may contain multiple traces. When passed to wrap(), it is
+     * automatically attached to every call record and flows through the backend
+     * /v1/query/session/:id into the dashboard's conversation thread view. The
+     * format is up to the user (UUID / ULID / arbitrary string), max 128 chars
+     * [A-Za-z0-9_-].
      *
-     * 2026-06-02 v0.4.0 で追加 (= v1.5 session tracking の SDK 側 carry)。
+     * Added 2026-06-02 in v0.4.0 (SDK side of session tracking).
      */
     sessionId?: string;
     /**
-     * Enable plaintext content capture (= Pro+ 平文保存機能の SDK 側 opt-in)。
-     * Default false。 true にすると、各 wrapper が prompt / completion 本文
-     * と tool call の引数・結果を抽出して record に乗せ、backend に送信する。
-     * backend 側で account.plaintext_storage_optin = 1 のときに限り暗号化保管
-     * される(env PLAINTEXT_STORAGE_ENABLED で全体 gate も併用)。
+     * Enable plaintext content capture (the SDK-side opt-in for the Pro+
+     * plaintext storage feature). Default false. When true, each wrapper
+     * extracts the prompt / completion bodies and tool call arguments/results,
+     * attaches them to the record, and sends them to the backend. They are
+     * stored encrypted only when account.plaintext_storage_optin = 1 on the
+     * backend (a global gate via the PLAINTEXT_STORAGE_ENABLED env is also applied).
      *
-     * このフラグを true にする前に、ダッシュボードの設定画面で平文保存機能を
-     * 有効化し、同意ダイアログでの明示同意を得ている必要がある。詳細は
-     * https://argosvix.com/ja/docs/plaintext を参照。
+     * Before setting this flag to true, you must enable the plaintext storage
+     * feature in the dashboard settings and give explicit consent in the consent
+     * dialog. See https://argosvix.com/ja/docs/plaintext for details.
      */
     captureContent?: boolean;
     /**
      * Disable the built-in PII redaction filter that masks email / credit card /
-     * phone / マイナンバー / IP address before send. Default false (= redaction
-     * is ON)。 true にすると無加工で送信される — 個人情報混入のリスクは
-     * ユーザーが負う(利用規約 第4条の2 第7項)。
+     * phone / Japanese My Number / IP address before send. Default false
+     * (redaction is ON). When true, content is sent unmodified — the user bears
+     * the risk of personal data exposure (Terms of Service, Article 4-2,
+     * Paragraph 7).
      *
-     * captureContent が false のときは平文自体送らないので、本フラグは無効。
+     * When captureContent is false, no plaintext is sent at all, so this flag
+     * has no effect.
      */
     disablePiiRedaction?: boolean;
     /**
-     * Project ID = v1.5 Pro polish で 追加 (= 2026-06-04)。 複数 product を 1
-     * アカウントで 切り替えて 観測する path で 使う。 Pro = up to 5 projects、
-     * Team = unlimited。 wrap() に渡すと、 backend ingest 経路で
-     * `X-Project-Id` header として 自動付与される (= 該当 project に record
-     * が紐付く)。 未指定 = account の default project に紐付く。
+     * Project ID. Used when observing multiple products under one account,
+     * switching between them. Pro = up to 5 projects, Team = unlimited. When
+     * passed to wrap(), it is automatically attached to the backend ingest path
+     * as the `X-Project-Id` header (records get associated with that project).
+     * When unset, records attach to the account's default project.
      *
-     * 該当 account に紐付かない / archived 済 project_id は backend で 404、
-     * 形式不正 (= /^[A-Za-z0-9_-]{1,128}$/ 外) は 400 が返る (= fail-closed)。
+     * A project_id not belonging to the account or already archived returns 404
+     * from the backend; a malformed one (outside /^[A-Za-z0-9_-]{1,128}$/)
+     * returns 400 (fail-closed).
      *
-     * 詳細 = https://argosvix.com/ja/docs/projects、 もしくは
-     * dashboard の Settings → Projects で project 一覧 + ID を取得。
+     * Details: https://argosvix.com/ja/docs/projects, or get the project list
+     * and IDs from the dashboard under Settings → Projects.
      */
     projectId?: string;
     /**
-     * Runtime 予算ゲートの opt-in (= ランタイム制御プレーン Phase 1)。
-     * true にすると、wrap 済み client の LLM 呼び出し前に backend
-     * `/v1/gate/budget` の月次予算設定 + 当月消費額をローカル評価し、
-     * 上限超過なら ArgosvixBudgetExceededError を投げて呼び出しを止める。
-     * 設定 + 消費額は TTL キャッシュ (default 60s)、呼び出し毎の往復はしない。
-     * gate 未設定の account では no-op。 Default false。
+     * Opt-in for the runtime budget gate (part of the runtime control plane).
+     * When true, before each LLM call on a wrapped client, the SDK locally
+     * evaluates the monthly budget settings plus current-month spend from the
+     * backend `/v1/gate/budget`, and if the limit is exceeded it throws
+     * ArgosvixBudgetExceededError to stop the call. Settings and spend use a TTL
+     * cache (default 60s) — no round trip per call. A no-op on accounts without
+     * a configured gate. Default false.
      *
-     * 既知の limitation: SDK が wrap していない method (= Anthropic
-     * `messages.stream()` 等、観測対象外の経路) は enforce も対象外。 wrap 済み
-     * method の一覧は README を参照。 上限を確実に強制したい場合は wrap 対象
-     * method のみを使うこと。
+     * Known limitation: methods the SDK does not wrap (e.g. Anthropic
+     * `messages.stream()`, paths outside observation) are also outside
+     * enforcement. See the README for the list of wrapped methods. To enforce
+     * limits reliably, use only wrapped methods.
      */
     budgetGate?: boolean;
     /**
-     * Runtime ポリシーゲートの opt-in (= ランタイム制御プレーン Phase 2)。
-     * true にすると、LLM 呼び出し前に backend のポリシー設定 (モデル allowlist /
-     * PII block / secret block) を SDK 内でローカル評価し、違反なら
-     * ArgosvixPolicyViolationError を投げて呼び出しを止める。評価はプロキシ
-     * 経由でなく顧客プロセス内で実行される。policy 未設定の account では no-op。
-     * budgetGate と独立に opt-in でき、設定の取得は同一 fetch (= /v1/gate/config)
-     * を共有する。 Default false。
+     * Opt-in for the runtime policy gate (part of the runtime control plane).
+     * When true, before each LLM call the SDK locally evaluates the backend's
+     * policy settings (model allowlist / PII block / secret block) and on a
+     * violation throws ArgosvixPolicyViolationError to stop the call. Evaluation
+     * runs inside the customer's process, not through a proxy. A no-op on
+     * accounts without a policy. Can be opted into independently of budgetGate;
+     * both share the same settings fetch (/v1/gate/config). Default false.
      */
     policyGate?: boolean;
     /**
-     * budgetGate / policyGate が true で、backend から gate 設定を一度も取得できていない
-     * 段階の挙動。 default false (= fail-open、通す)。 true にすると取得成功
-     * まで全呼び出しを ArgosvixBudgetGateUnavailableError で止める (= 厳格
-     * 運用 opt-in)。 取得後は backend 側 gate の enforceMode に従う。
+     * Behavior while budgetGate / policyGate is true but the gate settings have
+     * never been fetched from the backend. Default false (fail-open, calls pass).
+     * When true, all calls are stopped with ArgosvixBudgetGateUnavailableError
+     * until the fetch succeeds (a strict-operation opt-in). After the fetch, the
+     * backend-side gate's enforceMode applies.
      */
     budgetGateFailClosed?: boolean;
     /**
-     * policyGate の cold start 厳格運用 opt-in (= R72b HIGH 1)。 backend の
-     * enforceMode (fail_closed) は snapshot を一度取得した後にしか SDK から判定
-     * できないため、 取得前の障害は default で fail-open になる。 true にすると
-     * 取得成功まで全呼び出しを ArgosvixBudgetGateUnavailableError で止める。
-     * budgetGateFailClosed と同じ意味論で policy gate のみ使う構成向け。
+     * Strict cold-start opt-in for policyGate. The backend's enforceMode
+     * (fail_closed) can only be determined by the SDK after a snapshot has been
+     * fetched once, so failures before the first fetch default to fail-open.
+     * When true, all calls are stopped with ArgosvixBudgetGateUnavailableError
+     * until the fetch succeeds. Same semantics as budgetGateFailClosed, for
+     * setups using only the policy gate.
      */
     policyGateFailClosed?: boolean;
     /**
-     * 予算ゲート設定の取得先 override (= self-host / test 用)。 未指定なら
-     * `endpoint` と同 origin の /v1/gate/budget、 それも無ければ
-     * https://ingest.argosvix.com/v1/gate/budget。
+     * Override for where budget gate settings are fetched from (for self-hosting
+     * / tests). When unset, /v1/gate/budget on the same origin as `endpoint`;
+     * failing that, https://ingest.argosvix.com/v1/gate/budget.
      */
     gateEndpoint?: string;
 }
@@ -170,21 +184,21 @@ export interface LlmCallRecord {
     promptTokens: number;
     completionTokens: number;
     totalTokens: number;
-    /** プロンプトキャッシュ読取トークン(promptTokens の内数、割引課金)。なければ 0。 */
+    /** Prompt-cache read tokens (a subset of promptTokens, billed at a discount). 0 if none. */
     cachedReadTokens?: number;
-    /** プロンプトキャッシュ書込トークン(Anthropic のみ、プレミアム課金)。なければ 0。 */
+    /** Prompt-cache write tokens (Anthropic only, billed at a premium). 0 if none. */
     cachedWriteTokens?: number;
     /** USD value with 6 decimal places (sufficient for GPT-4o input $5 / 1M tokens granularity). */
     costUsd: number;
-    /** キャッシュ読取で削減できた USD(キャッシュ無し input との差額)。なければ 0。 */
+    /** USD saved by cache reads (the difference versus uncached input). 0 if none. */
     cacheSavingsUsd?: number;
     /** End-to-end call latency in milliseconds. */
     latencyMs: number;
-    /** 初回トークンまでの時間 ms(streaming のみ。非 streaming は未設定)。監査 Tier 2。 */
+    /** Time to first token in ms (streaming only; unset for non-streaming). */
     ttftMs?: number;
-    /** 推論トークン(思考モデル。OpenAI completion_tokens_details.reasoning_tokens 等)。なければ未設定。 */
+    /** Reasoning tokens (thinking models; e.g. OpenAI completion_tokens_details.reasoning_tokens). Unset if none. */
     reasoningTokens?: number;
-    /** 音声トークン(入力 + 出力の合算)。なければ未設定。 */
+    /** Audio tokens (input + output combined). Unset if none. */
     audioTokens?: number;
     /** ISO 8601 UTC timestamp. */
     timestamp: string;
@@ -209,33 +223,34 @@ export interface LlmCallRecord {
         temperature?: number;
         maxTokens?: number;
     };
-    /** OTel subset trace 軸 = backend で集約 / waterfall view に carry。 */
+    /** OTel-subset trace axis — aggregated on the backend and shown in the waterfall view. */
     traceId?: string;
     spanId?: string;
     parentSpanId?: string;
     /**
-     * Session 軸 = trace より上位の user 任意 group (= 連続会話 / 同 daily
-     * session / 同 job)。 backend /v1/query/session/:id で 同 session_id の
-     * call 群を 取得、 dashboard の conversation thread view で 時系列描画。
+     * Session axis = an arbitrary user-defined group above traces (a continuous
+     * conversation / the same daily session / the same job). The backend
+     * /v1/query/session/:id fetches the calls sharing a session_id, rendered
+     * chronologically in the dashboard's conversation thread view.
      */
     sessionId?: string;
     /**
-     * Plaintext prompt body (= ArgosvixConfig.captureContent が true のときのみ
-     * 設定される)。 ユーザーが LLM API に送信したテキスト本文。 PII redaction
-     * が有効なら、メールアドレスやカード番号などが [REDACTED_*] に置換済み。
+     * Plaintext prompt body (only set when ArgosvixConfig.captureContent is
+     * true). The text body the user sent to the LLM API. If PII redaction is
+     * enabled, email addresses, card numbers, etc. have been replaced with
+     * [REDACTED_*].
      */
     promptBody?: string;
     /**
-     * Plaintext completion body (= ArgosvixConfig.captureContent が true の
-     * ときのみ設定される)。 LLM API からの応答テキスト本文。 PII redaction
-     * 適用済み。
+     * Plaintext completion body (only set when ArgosvixConfig.captureContent is
+     * true). The response text body from the LLM API. PII redaction applied.
      */
     completionBody?: string;
     /**
-     * Tool call (= function calling) の関数名と引数と結果。
-     * captureContent が true のときのみ設定される。 SDK が response の
-     * tool_calls / function_call フィールドから抽出する。 引数と結果は PII
-     * redaction 適用後の文字列(JSON 文字列の場合もある)。
+     * Tool call (function calling) names, arguments, and results.
+     * Only set when captureContent is true. The SDK extracts these from the
+     * response's tool_calls / function_call fields. Arguments and results are
+     * strings after PII redaction (possibly JSON strings).
      */
     toolCalls?: Array<{
         name: string;
@@ -243,27 +258,29 @@ export interface LlmCallRecord {
         result?: string;
     }>;
     /**
-     * 2026-06-02 Round D v0.4.1 = PII redaction が 1 件以上適用された flag。
-     * SDK 側 一次 redaction (= redactPiiWithCounts) で email / creditCard /
-     * myNumber / phone / ipv4 / ipv6 の いずれかが 検出 + 置換されたら true。
-     * backend 0042 schema の llm_calls.pii_redacted column に carry。
-     * disablePiiRedaction = true (= 無加工 carry) の場合は当然 false / unset。
+     * Flag set when at least one PII redaction was applied. True when the
+     * SDK-side primary redaction (redactPiiWithCounts) detected and replaced any
+     * of email / creditCard / myNumber / phone / ipv4 / ipv6. Stored in the
+     * backend's llm_calls.pii_redacted column. Naturally false / unset when
+     * disablePiiRedaction = true (content passed through unmodified).
      */
     piiRedacted?: boolean;
     /**
-     * 2026-06-02 Round D v0.4.1 = redaction の カテゴリ別件数 + redactor 識別子
-     * JSON narrative。 backend 0042 schema の llm_calls.redaction_metadata
-     * column に そのまま 保管、 dashboard / MCP server で 「どの type を いくつ
-     * 検出したか」 監査表示に carry。
+     * Per-category redaction counts plus the redactor identifier, as JSON.
+     * Stored as-is in the backend's llm_calls.redaction_metadata column and
+     * surfaced by the dashboard / MCP server for the audit display of which
+     * types were detected and how many times.
      *
-     * 例: { email: 2, phone: 1, creditCard: 0, redactor: "argosvix-sdk" }
+     * Example: { email: 2, phone: 1, creditCard: 0, redactor: "argosvix-sdk" }
      */
     redactionMetadata?: Record<string, unknown>;
 }
 /**
- * #1 R4 = 型付き/ネストの観測ノード(非 LLM ステップ)。 generation(= LlmCallRecord)以外の
- * span / event / retrieval / tool / agent / chain を `withSpan` で emit し、 backend の
- * observations テーブルに保存する。 ⚠ metadata は非機密の構造化属性のみ(件数 / サイズ等)。
+ * Typed / nested observation nodes (non-LLM steps). Beyond generations
+ * (LlmCallRecord), span / event / retrieval / tool / agent / chain nodes are
+ * emitted via `withSpan` and stored in the backend's observations table.
+ * Warning: metadata must contain only non-sensitive structured attributes
+ * (counts / sizes etc.).
  */
 export type ObservationType = "span" | "event" | "retrieval" | "tool" | "agent" | "chain";
 export interface ObservationRecord {