@cartanova/qgrid-cli 2.7.0 → 2.7.2

package/bundle/src/testing/schema-bench.ts

@@ -0,0 +1,352 @@
+/**
+ * schema-delivery 준수율 벤치의 순수 로직 (SON-532).
+ *
+ * 러너(scripts/schema-delivery-bench.ts)는 qgrid HTTP API 로 실제 요청을 발사하고,
+ * 이 모듈은 응답 분류·집계·checkpoint 를 담당한다 — 벤치 결과의 신뢰가 집계 정확성에
+ * 걸려 있으므로 이 부분만 단위 테스트로 고정한다.
+ *
+ * 실패 분류는 서로 배타적인 3계층이다 (Codex 검토 반영 — 중복 판정 금지):
+ *   1. syntax   — JSON.parse 실패
+ *   2. contract — 파싱은 됐으나 계약(필수 키·fixture validate) 불통과. 필드 누락은 여기.
+ *   3. (별도 축) topLevel — 래퍼 키(GEN-359 병리)·펜스 잔존·프로즈. 형태 축이라
+ *      syntax/contract 와 겹칠 수 있고, 게이트 계수는 이 축 기준이다.
+ */
+import Ajv2020, { type ValidateFunction } from "ajv/dist/2020";
+
+export type BenchMode = "generate" | "stream";
+
+export interface BenchClassifyOptions {
+  /**
+   * 응답이 평문 텍스트인 계약 (tools-only 의 최종 answer 등). JSON 문법·형태 축 판정을
+   * 건너뛴다 — 평문 answer 를 JSON.parse 하면 정상 응답이 syntax fail 로 둔갑한다.
+   */
+  plainText?: boolean;
+  /**
+   * fixture 의 전체 JSON Schema. 지정하면 validateAgainstSchema 로 **전체 트리**를
+   * 검증한다 — top-level 키 존재만 보면 `{"scenes":[{},{},{}]}` 같은 속 빈 응답이
+   * 통과한다(SON-495 교훈: 상위 키 판정은 쓰레기를 통과시킨다).
+   */
+  schema?: unknown;
+  /** 최상위에 반드시 있어야 하는 키 (schema 미지정 시의 최소 검증) */
+  requiredTopLevelKeys?: string[];
+  /** 허용되는 최상위 키 전체 — 래퍼 키 판정에 사용 */
+  allowedTopLevelKeys?: string[];
+  /** fixture 별 추가 계약 검증. 실패 사유 문자열을 반환하면 contract fail. */
+  validate?: (parsed: unknown, rawText: string) => string | undefined;
+}
+
+/**
+ * 표준 JSON Schema 검증 (Ajv, Draft 2020-12). 위반 경로 목록을 반환한다.
+ *
+ * 한때 축약 검증기를 썼으나 2차 검토가 기각했다 — 미지원 keyword 를 무시하고 oneOf 를
+ * anyOf 처럼 다뤄 false pass 가 났고, 실제로 e2e 4/4 통과 보고가 Ajv 재검증에서 2/4 로
+ * 뒤집혔다(anyOf 브랜치 내부의 enum 위반을 통째로 건너뜀). 임의 스키마(BENCH_SCHEMA_FILE)
+ * 를 게이트로 쓰려면 표준 검증기가 유일하게 신뢰 가능하다.
+ */
+export function validateAgainstSchema(node: unknown, schema: unknown): string[] {
+  if (schema === null || typeof schema !== "object" || Array.isArray(schema)) return [];
+  const validate = compileSchema(schema as Record<string, unknown>);
+  if (validate(node)) return [];
+  return (validate.errors ?? []).map(
+    (e) =>
+      `${e.instancePath || "$"}: ${e.message ?? e.keyword}${e.keyword === "enum" ? ` (${JSON.stringify((e.params as { allowedValues?: unknown[] }).allowedValues?.slice(0, 8))})` : ""}`,
+  );
+}
+
+const compiledSchemas = new WeakMap<object, ValidateFunction>();
+let ajvInstance: Ajv2020 | undefined;
+
+function compileSchema(schema: Record<string, unknown>): ValidateFunction {
+  const cached = compiledSchemas.get(schema);
+  if (cached) return cached;
+  // strict:false — 소비자 스키마의 비표준 어노테이션(description 변형 등)을 컴파일
+  // 에러로 만들지 않는다. 검증 시맨틱은 표준 그대로다.
+  ajvInstance ??= new Ajv2020({ strict: false, allErrors: true });
+  // $id 가 있는 스키마를 두 번 compile 하면 Ajv 가 중복 등록으로 던진다 — WeakMap 캐시가
+  // 같은 객체의 재컴파일을 막고, 다른 객체로 온 같은 $id 는 인스턴스를 새로 만들어 회피한다.
+  let validate: ValidateFunction;
+  try {
+    validate = ajvInstance.compile(schema);
+  } catch {
+    ajvInstance = new Ajv2020({ strict: false, allErrors: true });
+    validate = ajvInstance.compile(schema);
+  }
+  compiledSchemas.set(schema, validate);
+  return validate;
+}
+
+export interface TopLevelViolations {
+  /** 최상위가 허용 키 목록 밖의 단일 키로 감싸져 있음 — GEN-359 래퍼 키 병리 */
+  wrapperKey: boolean;
+  /** 서버 스트리핑 후에도 ``` 가 양끝에 남아 있음 */
+  fenceResidue: boolean;
+  /** JSON 이 아닌 산문으로 시작 */
+  prose: boolean;
+}
+
+export interface BenchClassification {
+  syntax: "ok" | "fail";
+  /** syntax fail 이면 계약 검증 자체가 불가 — "n/a" */
+  contract: "ok" | "fail" | "n/a";
+  contractDetail?: string;
+  topLevel: TopLevelViolations;
+}
+
+export function classifyBenchText(
+  text: string,
+  options: BenchClassifyOptions = {},
+): BenchClassification {
+  const trimmed = text.trim();
+  const fenceResidue = trimmed.startsWith("```") || trimmed.endsWith("```");
+
+  if (options.plainText) {
+    const reason = options.validate?.(text, text);
+    return {
+      syntax: "ok",
+      contract: reason === undefined ? "ok" : "fail",
+      ...(reason === undefined ? {} : { contractDetail: reason }),
+      topLevel: { wrapperKey: false, fenceResidue, prose: false },
+    };
+  }
+
+  let parsed: unknown;
+  let syntax: "ok" | "fail" = "ok";
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    syntax = "fail";
+  }
+
+  const prose = syntax === "fail" && !fenceResidue && !/^[{[]/.test(trimmed);
+
+  let wrapperKey = false;
+  let contract: BenchClassification["contract"] = "n/a";
+  let contractDetail: string | undefined;
+
+  if (syntax === "ok") {
+    const record =
+      parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>)
+        : undefined;
+
+    if (record && options.allowedTopLevelKeys) {
+      const keys = Object.keys(record);
+      const allowed = new Set(options.allowedTopLevelKeys);
+      wrapperKey =
+        keys.length === 1 &&
+        !allowed.has(keys[0]!) &&
+        typeof record[keys[0]!] === "object" &&
+        record[keys[0]!] !== null;
+    }
+
+    contract = "ok";
+    if (record === undefined) {
+      contract = "fail";
+      contractDetail = "top-level is not an object";
+    } else if (options.schema !== undefined) {
+      const violations = validateAgainstSchema(parsed, options.schema);
+      if (violations.length > 0) {
+        contract = "fail";
+        contractDetail = `${violations.length} schema violations: ${violations.slice(0, 5).join("; ")}`;
+      }
+    } else {
+      const missing = (options.requiredTopLevelKeys ?? []).filter(
+        (key) => !Object.hasOwn(record, key),
+      );
+      if (missing.length > 0) {
+        contract = "fail";
+        contractDetail = `missing required keys: ${missing.join(", ")}`;
+      }
+    }
+    if (contract === "ok" && options.validate) {
+      const reason = options.validate(parsed, text);
+      if (reason !== undefined) {
+        contract = "fail";
+        contractDetail = reason;
+      }
+    }
+  }
+
+  return { syntax, contract, contractDetail, topLevel: { wrapperKey, fenceResidue, prose } };
+}
+
+// ── 레코드·checkpoint ──
+
+export interface BenchRecord {
+  fixture: string;
+  /**
+   * fixture 내용(prompt·schema·tools)의 지문. checkpoint 동일성에 포함된다 —
+   * 이름만으로 식별하면 fixture 를 고친 뒤 재실행할 때 옛 결과가 현재 데이터로
+   * 둔갑한다(pending=0). 지문이 다르면 다른 조합으로 취급돼 재발사된다.
+   */
+  fixtureHash?: string;
+  model: string;
+  mode: BenchMode;
+  iteration: number;
+  /** HTTP/전송 오류 포함 전체 요청이 분모다 — 오류를 분모에서 빼면 오류율 차이가 은폐된다. */
+  transportError?: string;
+  classification?: BenchClassification;
+  /** 스트림에서 델타 연결과 done.text 가 달랐는지 (펜스 transform 불변식의 실전 검증) */
+  deltaDoneMismatch?: boolean;
+  durationMs: number;
+  outputTokens?: number;
+  costUsd?: number;
+}
+
+/** fixture 내용 지문 — djb2 (의존성 없이 충분: 충돌해 봐야 옛 레코드 하나가 스킵될 뿐). */
+export function fingerprintFixture(content: {
+  prompt: string;
+  jsonSchema?: string;
+  tools?: unknown;
+}): string {
+  const text = `${content.prompt}${content.jsonSchema ?? ""}${JSON.stringify(content.tools ?? null)}`;
+  let hash = 5381;
+  for (let i = 0; i < text.length; i += 1) {
+    hash = ((hash << 5) + hash + text.charCodeAt(i)) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+export function checkpointKey(
+  record: Pick<BenchRecord, "fixture" | "fixtureHash" | "model" | "mode" | "iteration">,
+): string {
+  return `${record.model}|${record.fixture}|${record.fixtureHash ?? "-"}|${record.mode}|${record.iteration}`;
+}
+
+/** JSONL checkpoint 파일 파싱. 깨진 줄(중단 시 부분 기록)은 건너뛴다. */
+export function parseCheckpointLines(jsonl: string): Map<string, BenchRecord> {
+  const map = new Map<string, BenchRecord>();
+  for (const line of jsonl.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const record = JSON.parse(line) as BenchRecord;
+      map.set(checkpointKey(record), record);
+    } catch {
+      // 부분 기록된 마지막 줄 — resume 시 해당 조합만 재발사된다
+    }
+  }
+  return map;
+}
+
+// ── 집계 ──
+
+export interface BenchAggregateRow {
+  model: string;
+  fixture: string;
+  mode: BenchMode;
+  total: number;
+  transportErrors: number;
+  syntaxFails: number;
+  contractFails: number;
+  wrapperKey: number;
+  fenceResidue: number;
+  prose: number;
+  deltaDoneMismatches: number;
+  passes: number;
+  /** 분모는 전체 요청(전송 오류 포함) */
+  passRate: number;
+  avgDurationMs: number;
+  totalOutputTokens: number;
+  totalCostUsd: number;
+}
+
+export function aggregateBench(records: BenchRecord[]): BenchAggregateRow[] {
+  const groups = new Map<string, BenchRecord[]>();
+  for (const record of records) {
+    const key = `${record.model}|${record.fixture}|${record.mode}`;
+    const bucket = groups.get(key);
+    if (bucket) bucket.push(record);
+    else groups.set(key, [record]);
+  }
+
+  return [...groups.entries()]
+    .map(([key, bucket]) => {
+      const [model, fixture, mode] = key.split("|") as [string, string, BenchMode];
+      const transportErrors = bucket.filter((r) => r.transportError !== undefined).length;
+      const syntaxFails = bucket.filter((r) => r.classification?.syntax === "fail").length;
+      const contractFails = bucket.filter((r) => r.classification?.contract === "fail").length;
+      // pass = 모든 축이 깨끗한 응답 — 형태 위반(래퍼/펜스/프로즈)과 스트림 델타≠done 도
+      // 실패다. syntax/contract 만 보면 "통과인데 펜스가 남은" 응답이 성공으로 집계된다
+      // (2차 검토 #7).
+      const passes = bucket.filter(
+        (r) =>
+          r.transportError === undefined &&
+          r.classification?.syntax === "ok" &&
+          r.classification.contract === "ok" &&
+          !r.classification.topLevel.wrapperKey &&
+          !r.classification.topLevel.fenceResidue &&
+          !r.classification.topLevel.prose &&
+          r.deltaDoneMismatch !== true,
+      ).length;
+      const count = (pick: (v: TopLevelViolations) => boolean) =>
+        bucket.filter((r) => r.classification !== undefined && pick(r.classification.topLevel))
+          .length;
+
+      return {
+        model,
+        fixture,
+        mode,
+        total: bucket.length,
+        transportErrors,
+        syntaxFails,
+        contractFails,
+        wrapperKey: count((v) => v.wrapperKey),
+        fenceResidue: count((v) => v.fenceResidue),
+        prose: count((v) => v.prose),
+        deltaDoneMismatches: bucket.filter((r) => r.deltaDoneMismatch === true).length,
+        passes,
+        passRate: bucket.length === 0 ? 0 : passes / bucket.length,
+        avgDurationMs:
+          bucket.length === 0
+            ? 0
+            : Math.round(bucket.reduce((sum, r) => sum + r.durationMs, 0) / bucket.length),
+        totalOutputTokens: bucket.reduce((sum, r) => sum + (r.outputTokens ?? 0), 0),
+        totalCostUsd: bucket.reduce((sum, r) => sum + (r.costUsd ?? 0), 0),
+      };
+    })
+    .toSorted((a, b) =>
+      `${a.model}${a.fixture}${a.mode}`.localeCompare(`${b.model}${b.fixture}${b.mode}`),
+    );
+}
+
+export function formatAggregateTable(rows: BenchAggregateRow[]): string {
+  const header = [
+    "model",
+    "fixture",
+    "mode",
+    "N",
+    "pass",
+    "rate",
+    "syntax✗",
+    "contract✗",
+    "wrapper",
+    "fence",
+    "prose",
+    "transport✗",
+    "Δ≠done",
+    "avgMs",
+    "outTok",
+    "cost$",
+  ];
+  const lines = rows.map((r) =>
+    [
+      r.model,
+      r.fixture,
+      r.mode,
+      r.total,
+      r.passes,
+      `${(r.passRate * 100).toFixed(1)}%`,
+      r.syntaxFails,
+      r.contractFails,
+      r.wrapperKey,
+      r.fenceResidue,
+      r.prose,
+      r.transportErrors,
+      r.deltaDoneMismatches,
+      r.avgDurationMs,
+      r.totalOutputTokens,
+      r.totalCostUsd.toFixed(4),
+    ].join("\t"),
+  );
+  return [header.join("\t"), ...lines].join("\n");
+}

package/bundle/src/utils/providers/anthropic/anthropic-dispatcher.ts

@@ -93,6 +93,12 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     return this.tokenPool.size;
   }
 
+  // 지금 실행 중인 Claude Code 프로세스 수 — fresh-spawn 이라 이게 곧 동시 요청 수다.
+  private inFlightCount = 0;
+  get inFlight(): number {
+    return this.inFlightCount;
+  }
+
   // Monit 표시용 — 풀에 있는 토큰 이름 스냅샷 (이름순 정렬)
   get tokenNames(): string[] {
     return [...this.tokenPool.values()].map((token) => token.name).toSorted();
@@ -273,12 +279,21 @@ export class AnthropicDispatcher implements ProviderDispatcher {
   }
 
   // generate/generateStream 공통 실행. onDelta 는 스트림이면 점진 방출, 비스트림이면 no-op.
-  private async run(
+  private async run(...args: Parameters<AnthropicDispatcher["runInner"]>): Promise<GenerateResult> {
+    this.inFlightCount++;
+    try {
+      return await this.runInner(...args);
+    } finally {
+      this.inFlightCount--;
+    }
+  }
+
+  private async runInner(
     req: GenerateRequest,
     onDelta: (t: string) => void,
     opts?: { includePartialMessages?: boolean },
   ): Promise<GenerateResult> {
-    // 이미지 생성은 OpenAI(codex) 경로 전용. Anthropic 라우팅에 이미지 플래그가
+    // 이미지 생성은 OpenAI 경로 전용. Anthropic 라우팅에 이미지 플래그가
     // 도달하면 조용히 텍스트로 폴백하지 않고 명시적으로 거부한다.
     if (req.imageGeneration) {
       throw new Error("image generation is not supported on the Anthropic route");

package/bundle/src/utils/providers/anthropic/claude-session.ts

@@ -18,9 +18,7 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 
-import { type JsonValue } from "../../../codex-protocol/serde_json/JsonValue";
-import { type TokenUsageBreakdown } from "../../../codex-protocol/v2/TokenUsageBreakdown";
-import { type UserInput } from "../../../codex-protocol/v2/UserInput";
+import { type JsonValue, type TokenUsageBreakdown, type UserInput } from "../common/provider-types";
 import {
   ARGV_SAFE_MAX_UTF8_BYTES,
   assertAnthropicSchemaArgvSize,

package/bundle/src/utils/providers/anthropic/fence-strip.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from "vitest";
+
+import { createFenceStripTransform, stripFences } from "./fence-strip";
+
+// 스트림 절단 지점에 무관하게 "방출 연결 + flush == stripFences(전체)" 가 성립해야 한다.
+function runAllSplits(full: string): void {
+  const expected = stripFences(full);
+  for (let i = 0; i <= full.length; i += 1) {
+    for (let j = i; j <= full.length; j += 1) {
+      const t = createFenceStripTransform();
+      const out =
+        t.push(full.slice(0, i)) + t.push(full.slice(i, j)) + t.push(full.slice(j)) + t.flush();
+      expect(out, `split at ${i},${j}`).toBe(expected);
+    }
+  }
+}
+
+describe("stripFences", () => {
+  it("펜스 없음 — 양끝 공백만 제거하고 원문 유지 (1091748 케이스)", () => {
+    expect(stripFences('{"a":1}')).toBe('{"a":1}');
+    expect(stripFences('  {"a":1}\n')).toBe('{"a":1}');
+  });
+
+  it("json 태그 펜스를 벗긴다", () => {
+    expect(stripFences('```json\n{"a":1}\n```')).toBe('{"a":1}');
+  });
+
+  it("언어 태그 없는 펜스를 벗긴다", () => {
+    expect(stripFences('```\n{"a":1}\n```')).toBe('{"a":1}');
+  });
+
+  it("선두 공백/개행 + 펜스 조합", () => {
+    expect(stripFences('\n\n  ```json\n{"a":1}\n```  \n')).toBe('{"a":1}');
+  });
+
+  it("JSON 문자열 값 내부의 백틱은 건드리지 않는다", () => {
+    const inner = '{"code":"```json\\n{}\\n```ok"}';
+    expect(stripFences(inner)).toBe(inner);
+  });
+
+  it("펜스만 있고 본문 없음 → 빈 문자열", () => {
+    expect(stripFences("```json\n```")).toBe("");
+  });
+});
+
+describe("createFenceStripTransform", () => {
+  it("여는 펜스가 delta 경계에 걸쳐 도착해도 본문만 방출한다", () => {
+    const t = createFenceStripTransform();
+    let out = t.push("``");
+    out += t.push("`js");
+    out += t.push('on\n{"a"');
+    out += t.push(":1}\n``");
+    out += t.push("`");
+    out += t.flush();
+    expect(out).toBe('{"a":1}');
+  });
+
+  it("닫는 펜스 직전까지 방출되고 tail 홀드백이 펜스를 삼킨다", () => {
+    const t = createFenceStripTransform();
+    const first = t.push('```json\n{"a":1}');
+    // 본문은 도착 즉시 흘러야 한다 (닫는 펜스 후보가 아니므로)
+    expect(first).toBe('{"a":1}');
+    expect(t.push("\n```") + t.flush()).toBe("");
+  });
+
+  it("홀드백 후보였으나 펜스가 아니면 내용 무손실로 방출한다", () => {
+    const t = createFenceStripTransform();
+    const out = t.push('{"a":"x') + t.push("``") + t.push('y"}') + t.flush();
+    expect(out).toBe('{"a":"x``y"}');
+  });
+
+  it("닫는 펜스 앞의 긴 공백 런도 전부 보류 후 폐기한다", () => {
+    const gap = "\n".repeat(4_000) + " ".repeat(4_000);
+    const t = createFenceStripTransform();
+    const out = t.push('```json\n{"a":1}') + t.push(gap) + t.push("\n```") + t.flush();
+    // 전체 연산과 동일해야 한다: trim 이 trailing 공백을 지우고 펜스가 벗겨진다
+    expect(out).toBe(stripFences('```json\n{"a":1}' + gap + "\n```"));
+  });
+
+  it("미완성 펜스로 끝나는 스트림은 그 백틱을 방출한다 (닫는 펜스 아님)", () => {
+    const t = createFenceStripTransform();
+    const out = t.push('{"a":1}\n``') + t.flush();
+    expect(out).toBe('{"a":1}\n``');
+  });
+
+  it("본문 뒤 공백만으로 끝나면 trailing 공백 제거만 적용된다", () => {
+    const t = createFenceStripTransform();
+    const out = t.push('{"a":1}') + t.push("  \n\n") + t.flush();
+    expect(out).toBe('{"a":1}');
+  });
+
+  it("불변식: 임의 절단 지점에서 방출 연결 == stripFences(전체)", () => {
+    const samples = [
+      '{"a":1}',
+      '```json\n{"a":1}\n```',
+      '```JSON\n{"a":1}\n```',
+      '```\n{"a":1}\n```',
+      '  \n```json  \n\n{"a":[1,2]}\n\n```  ',
+      '{"code":"```"}',
+      "```json\n```",
+      "``",
+      "```jsx\n{}\n```",
+      '{"a":1}\n``` extra',
+      '{"a":1}``````',
+      "   \n  ",
+      "",
+      '```json{"inline":true}```',
+    ];
+    for (const sample of samples) runAllSplits(sample);
+  });
+
+  it("불변식: 유니코드 공백(NBSP·VT·FF·LS·PS·BOM)에서도 성립 (2차 검토 #8)", () => {
+    // trim() 이 지우는 비 ASCII 공백이 tail 에 있으면 홀드백이 함께 보류해야 한다
+    const ws = [" ", "\v", "\f", "
", "
", ""];
+    for (const w of ws) {
+      runAllSplits(`{"a":1}${w}`);
+      runAllSplits(`${w}{"a":1}${w}${w}`);
+      runAllSplits(`\`\`\`json\n{"a":1}\n\`\`\`${w}`);
+      runAllSplits(`{"a":1}${w}\n\`\`\``);
+    }
+  });
+});

package/bundle/src/utils/providers/anthropic/fence-strip.ts

@@ -0,0 +1,105 @@
+/**
+ * 코드펜스 스트리핑 (SON-532).
+ *
+ * anthropic 은 스키마/envelope 계약을 프롬프트로 안내하므로 응답은 평범한 텍스트다.
+ * sonnet 계열이 지시에도 불구하고 ```json 펜스를 붙이는 실측이 있어, 서버가 펜스와
+ * 양끝 공백만 벗겨 소비자(zod)/parseEnvelope/EnvelopeStreamParser 에 순수 JSON 을
+ * 넘긴다. 머리말·후미 프로즈 구제는 하지 않는다 — 관용 복구는 2026-07 medpath 13.5k
+ * 오염 사고로 기각된 원칙이며, 프로즈 응답은 다음 층에서 정직하게 실패한다.
+ *
+ * `stripFences` 는 stream-json-adapter 의 stripCodeFence(비스트림 result 경로)에서
+ * 추출한 동일 시맨틱이다 — 스트림 델타 연결과 비스트림 최종 텍스트가 같은 결과여야
+ * 클라이언트가 어느 쪽을 조립해도 어긋나지 않는다.
+ */
+
+export function stripFences(s: string): string {
+  return s
+    .trim()
+    .replace(/^```(?:json)?\s*\n?/i, "")
+    .replace(/\n?```\s*$/i, "");
+}
+
+interface FenceStripTransform {
+  /** delta 를 넣고 지금 방출해도 안전한 조각을 돌려받는다. */
+  push(delta: string): string;
+  /** 스트림 종료. 보류분 중 펜스·trailing 공백이 아닌 잔여를 돌려준다. */
+  flush(): string;
+}
+
+/**
+ * 델타 스트림용 통과 필터. 불변식: 임의 절단 지점에 대해
+ * `push(...) 들의 연결 + flush() == stripFences(전체 텍스트)`.
+ *
+ * tail 홀드백은 고정 크기가 아니라 계약 기반이다 — "공백·개행·백틱만으로 이루어진
+ * suffix"(닫는 펜스 후보)를 스트림 완료까지 보류하고, 후보를 깨는 내용이 오면 즉시
+ * 방출을 재개한다. 닫는 펜스 앞 공백은 임의 길이일 수 있어 고정 크기로는 "양끝 공백
+ * 제거" 불변식이 성립하지 않는다.
+ */
+export function createFenceStripTransform(): FenceStripTransform {
+  let full = "";
+  // full 에서 본문(leading trim + 여는 펜스 이후)이 시작하는 인덱스. -1 = 아직 미확정.
+  let bodyStart = -1;
+  // 본문 기준으로 이미 방출한 문자 수. 방출분은 최종 결과의 prefix 임이 보장된다 —
+  // 공백은 비공백 내용이 뒤따르기 전까지 항상 보류되므로, 나중에 닫는 펜스의 일부로
+  // 판명될 문자가 미리 방출되는 일이 없다.
+  let emitted = 0;
+
+  return {
+    push(delta: string): string {
+      full += delta;
+      if (bodyStart < 0) {
+        bodyStart = resolveLeadingOffset(full);
+        if (bodyStart < 0) return "";
+      }
+
+      const body = full.slice(bodyStart);
+      const unemitted = body.slice(emitted);
+      const safe = unemitted.length - trailingHoldLength(unemitted);
+      if (safe <= 0) return "";
+
+      const out = unemitted.slice(0, safe);
+      emitted += safe;
+      return out;
+    },
+
+    flush(): string {
+      // 방출분이 최종 결과의 prefix 라는 불변식 위에서, 잔여만 잘라 돌려준다.
+      return stripFences(full).slice(emitted);
+    },
+  };
+}
+
+/**
+ * 여는 펜스 판정. 아직 "```json" 으로 자랄 수 있는 경계(백틱 1~2개, "```j(s(o))",
+ * 펜스 직후 공백만 도착)면 -1 로 보류한다. stripFences 의 leading 정규식과 동일한
+ * 소비 규칙: ```(json)? 뒤에 이어지는 공백 전부가 펜스에 붙어 떨어져 나간다.
+ */
+function resolveLeadingOffset(text: string): number {
+  const trimmedStart = text.trimStart();
+  if (trimmedStart === "") return -1; // 아직 공백뿐 — flush 가 정리한다
+  const ws = text.length - trimmedStart.length;
+
+  if (!trimmedStart.startsWith("`")) return ws;
+  if (/^`{1,2}$/.test(trimmedStart)) return -1; // "```" 로 자랄 수 있음
+
+  const fence = /^```(?:json)?/i.exec(trimmedStart);
+  if (!fence) return ws; // "`x", "``x" — 펜스가 아니라 본문
+  if (/^```(?:j|js|jso)$/i.test(trimmedStart)) return -1; // "json" 태그가 자라는 중
+
+  const afterFence = trimmedStart.slice(fence[0].length);
+  const afterFenceBody = afterFence.trimStart();
+  if (afterFenceBody === "") return -1; // 펜스 뒤 공백만 — 본문 첫 글자 대기
+  return ws + fence[0].length + (afterFence.length - afterFenceBody.length);
+}
+
+/**
+ * 아직 방출하면 안 되는 suffix 길이. 닫는 펜스 후보는 "(개행?)(백틱 1~3)(공백*)" 또는
+ * 순수 trailing 공백 — stripFences 의 trim + /\n?```\s*$/ 가 지울 수 있는 모든 형태를
+ * 덮는다. 공백 클래스는 반드시 `\s`(+BOM) — trim() 은 NBSP·VT·FF·U+2028·U+2029 까지
+ * 지우므로 ASCII 만 보류하면 그 문자들이 먼저 방출돼 "방출 == strip(전체)" 불변식이
+ * 깨진다(2차 검토 #8 실측). 미방출 구간에만 적용하므로 비용은 (보류분+delta)에 비례.
+ */
+function trailingHoldLength(unemitted: string): number {
+  const match = /(?:\n?`{1,3})?[\s]*$/.exec(unemitted);
+  return match ? match[0].length : 0;
+}

package/bundle/src/utils/providers/anthropic/stream-json-adapter.test.ts

@@ -1,7 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { type JsonValue } from "../../../codex-protocol/serde_json/JsonValue";
-import { type UserInput } from "../../../codex-protocol/v2/UserInput";
+import { type JsonValue, type UserInput } from "../common/provider-types";
 import {
   buildStreamJsonInput,
   type ClaudeStreamJsonState,

package/bundle/src/utils/providers/anthropic/stream-json-adapter.ts

@@ -8,12 +8,12 @@
  * The only executable user line is the current input.
  */
 
-import { type JsonValue } from "../../../codex-protocol/serde_json/JsonValue";
-import { type UserInput } from "../../../codex-protocol/v2/UserInput";
 import {
   type ModelFallback,
   type ProviderTokenUsageBreakdown,
 } from "../common/provider-dispatcher";
+import { type JsonValue, type UserInput } from "../common/provider-types";
+import { stripFences } from "./fence-strip";
 
 // ── 입력 어댑터 ────────────────────────────────────────────────────
 
@@ -37,7 +37,7 @@ function textBlock(text: string): Array<{ type: "text"; text: string }> {
   return [{ type: "text", text }];
 }
 
-// codex ResponseItem(coldHistory item) 최소 shape.
+// OpenAI Responses item(coldHistory item) 최소 shape.
 // extractPromptAndHistory(ai-sdk/utils.ts) 가 만드는 형식:
 //   { type:"message", role:"user", content:[{type:"input_text", text}] }
 //   { type:"message", role:"assistant", content:[{type:"output_text", text}] }
@@ -195,13 +195,6 @@ function toUsageBreakdown(u: ClaudeUsage): ProviderTokenUsageBreakdown {
   };
 }
 
-function stripCodeFence(s: string): string {
-  return s
-    .trim()
-    .replace(/^```(?:json)?\s*\n?/i, "")
-    .replace(/\n?```\s*$/i, "");
-}
-
 function structuredOutputToolUseText(j: ResponseItem): string | undefined {
   const message = asObject(j.message);
   const content = message?.content;
@@ -424,7 +417,7 @@ export function handleStreamJsonLine(
     } else if (j.structured_output !== undefined) {
       text = JSON.stringify(j.structured_output);
     } else {
-      text = stripCodeFence(typeof j.result === "string" ? j.result : "");
+      text = stripFences(typeof j.result === "string" ? j.result : "");
     }
 
     const rawUsage = asObject(j.usage) ?? {};