@cartanova/qgrid-cli 2.7.0 → 2.7.1

package/bundle/src/application/qgrid/qgrid.dispatcher.ts

@@ -12,6 +12,7 @@ import { InternalServerErrorException, ServiceUnavailableException } from "sonam
 import { type JsonValue } from "../../codex-protocol/serde_json/JsonValue";
 import { SD } from "../../i18n/sd.generated";
 import { type AnthropicDispatcher } from "../../utils/providers/anthropic/anthropic-dispatcher";
+import { createFenceStripTransform } from "../../utils/providers/anthropic/fence-strip";
 import { getAccessToken } from "../../utils/providers/common/credentials";
 import { calculateCostUsd } from "../../utils/providers/common/model-cost";
 import {
@@ -34,6 +35,7 @@ import {
   type QueryOutput,
   type TokenStats,
 } from "./qgrid.types";
+import { composeSystemWithSchemaContract } from "./schema-prompt";
 import { type TokenSubscriber } from "./token-subscriber";
 import { applyToolCallEmulation } from "./tool-emulation";
 import { buildToolCallSchema } from "./tool-emulation-schema";
@@ -149,8 +151,10 @@ export class QgridDispatcherClass {
       const result = await this.anthropicDispatcher.generate({
         // AnthropicDispatcher 내부에서 알아서 provider prefix 를 canonical model 로 정규화함
         model: input.model,
-        systemPrompt: input.system,
-        outputSchema,
+        // 스키마/envelope 계약은 --json-schema 대신 system 말미의 텍스트로 안내한다(SON-532).
+        // outputSchema 는 전달하지 않는다 — anthropic 에서 항상 undefined(U1)이며,
+        // CC 로 가는 --json-schema 채널 자체가 닫혀 있음을 여기서 명시한다.
+        systemPrompt: composeSystemWithSchemaContract(input.system, input),
         effort: input.effort,
         timeoutMs: input.timeout,
         abortSignal,
@@ -220,12 +224,24 @@ export class QgridDispatcherClass {
     } else if (route.provider === "anthropic") {
       if (!this.anthropicDispatcher) throw this.notReadyError("anthropic");
 
+      // 계약(스키마/envelope)이 주입된 요청의 델타에서 코드펜스를 벗긴다(SON-532).
+      // 비스트림 최종 텍스트는 stream-json-adapter 의 stripFences 가 같은 시맨틱으로
+      // 처리하므로 델타 연결과 done.text 가 어긋나지 않는다. 일반 텍스트 요청은 무변경.
+      const hasSchemaContract = input.jsonSchema !== undefined || Boolean(input.tools?.length);
+      const fenceStrip = hasSchemaContract ? createFenceStripTransform() : undefined;
+      const emitDelta = fenceStrip
+        ? (text: string) => {
+            const safe = fenceStrip.push(text);
+            if (safe) cb.onDelta(safe);
+          }
+        : cb.onDelta;
+
       const decision = decideConvRouting(input);
       await this.anthropicDispatcher.generateStream(
         {
           model: input.model,
-          systemPrompt: input.system,
-          outputSchema,
+          // 스키마/envelope 계약은 --json-schema 대신 system 말미의 텍스트로 안내한다(SON-532)
+          systemPrompt: composeSystemWithSchemaContract(input.system, input),
           effort: input.effort,
           coldInput: decision.coldInput,
           coldHistory: decision.coldHistory,
@@ -235,9 +251,14 @@ export class QgridDispatcherClass {
           imageGenerationOptions: input.imageGenerationOptions,
         },
         {
-          onDelta: cb.onDelta,
+          onDelta: emitDelta,
           onThreadId: cb.onThreadId,
           onComplete: (turnResult) => {
+            // 홀드백 잔여(닫는 펜스가 아니었던 tail)를 done 전에 마저 방출한다 —
+            // 델타를 조립하는 클라이언트(EnvelopeStreamParser 등)의 무손실 보장.
+            const rest = fenceStrip?.flush();
+            if (rest) cb.onDelta(rest);
+
             const issuedCoord = issueConvContext(turnResult.threadCoord, decision);
             cb.onComplete(
               applyToolCallEmulation(toEmulationResult(turnResult), input.tools, {
@@ -294,6 +315,16 @@ export function buildAndValidateStrictOutputSchema(
   input: Pick<QueryInput, "model" | "tools" | "jsonSchema">,
   provider = parseProviderRoute(input.model).provider,
 ): JsonValue | undefined {
+  // anthropic(SON-532): CC 에 --json-schema 를 전달하지 않는다 — 강제 없는 사후 채점이
+  // 소비자 의도(nullish 생략 등)와 충돌해 CC 내부 재시도 루프를 발화시켰다(왕복 2~4회,
+  // 4.7~9.1배 출력 청구 실측). 스키마/envelope 계약은 프롬프트 텍스트로 안내하고 판정은
+  // 소비자(zod)/parseEnvelope 가 맡는다. 따라서 strict 변환·argv 64KiB 제한 없이 수신
+  // 원형의 구문·복잡도(전역 512KiB 한도)만 검증해 caller-fault 를 조기에 돌려준다.
+  if (provider === "anthropic") {
+    parseAndValidateCallerSchemas(input);
+    return undefined;
+  }
+
   const outputSchema = buildStrictOutputSchema(input, provider);
   serializeAndValidateDispatchSchema(outputSchema, provider);
   return outputSchema;

package/bundle/src/application/qgrid/qgrid.frame.test.ts

@@ -22,23 +22,29 @@ const {
   finishRunWithErrorMock,
   finishRunAbortedMock,
   getRateLimitsByTokenIdMock,
-} = vi.hoisted(() => ({
-  findOneMock: vi.fn(),
-  findManyMock: vi.fn(),
-  saveMock: vi.fn(),
-  updateFieldsMock: vi.fn(),
-  requestLogSaveMock: vi.fn(),
-  requestLogCreateRunMock: vi.fn(),
-  appendStepMock: vi.fn(),
-  dispatcherQueryMock: vi.fn(),
-  dispatcherQueryStreamMock: vi.fn(),
-  beforeQueryMock: vi.fn(),
-  afterQueryMock: vi.fn(),
-  assertNativeRunAdmissionMock: vi.fn(),
-  finishRunWithErrorMock: vi.fn(),
-  finishRunAbortedMock: vi.fn(),
-  getRateLimitsByTokenIdMock: vi.fn(),
-}));
+} = vi.hoisted(() => {
+  // isolate:false 공유 레지스트리 방어: 같은 fork 에서 앞선 파일이 request-log/token/
+  // run-lifecycle 실모듈을 캐시해 두면 아래 vi.mock 들이 조용히 무시된다(실 DB 호출로
+  // 폭발). import 보다 먼저 레지스트리를 비워 이 파일은 항상 mock 그래프로 시작한다.
+  vi.resetModules();
+  return {
+    findOneMock: vi.fn(),
+    findManyMock: vi.fn(),
+    saveMock: vi.fn(),
+    updateFieldsMock: vi.fn(),
+    requestLogSaveMock: vi.fn(),
+    requestLogCreateRunMock: vi.fn(),
+    appendStepMock: vi.fn(),
+    dispatcherQueryMock: vi.fn(),
+    dispatcherQueryStreamMock: vi.fn(),
+    beforeQueryMock: vi.fn(),
+    afterQueryMock: vi.fn(),
+    assertNativeRunAdmissionMock: vi.fn(),
+    finishRunWithErrorMock: vi.fn(),
+    finishRunAbortedMock: vi.fn(),
+    getRateLimitsByTokenIdMock: vi.fn(),
+  };
+});
 
 vi.mock("../request-log/request-log.model", () => ({
   MICRO_USD: 1_000_000,
@@ -467,56 +473,62 @@ describe("QgridFrame.query request logging", () => {
     expect(dispatcherQueryMock).not.toHaveBeenCalled();
   });
 
-  it("returns 400 for an Anthropic positional tuple before logging or dispatch", async () => {
-    await expect(
-      QgridFrame.query({
-        prompt: "hi",
-        model: "anthropic/claude-opus-4-8",
-        jsonSchema: JSON.stringify({
-          type: "object",
-          properties: {
-            tuple: {
-              type: "array",
-              items: [{ type: "string" }, { type: "integer" }],
-            },
+  // SON-532: anthropic 은 strictify 를 거치지 않으므로 strict 변환이 다루지 못하던 형태
+  // (positional tuple 등)도 거절 사유가 아니다 — 원형 그대로 프롬프트에 안내된다.
+  it.each([
+    [
+      "positional tuple",
+      {
+        type: "object",
+        properties: {
+          tuple: { type: "array", items: [{ type: "string" }, { type: "integer" }] },
+        },
+        required: ["tuple"],
+      },
+    ],
+    [
+      "tuple nested under not",
+      { type: "object", not: { type: "array", items: [{ type: "string" }] } },
+    ],
+    [
+      "prefixItems tuple with missing type",
+      {
+        type: "object",
+        properties: { tuple: { prefixItems: [{ type: "string" }, { type: "integer" }] } },
+        required: ["tuple"],
+      },
+    ],
+    [
+      "prefixItems tuple with nullable union type",
+      {
+        type: "object",
+        properties: {
+          tuple: {
+            type: ["array", "null"],
+            prefixItems: [{ type: "string" }, { type: "integer" }],
           },
-          required: ["tuple"],
-        }),
-      }),
-    ).rejects.toMatchObject({
-      statusCode: 400,
-      message: expect.stringContaining(
-        "positional tuple schemas are not supported on Anthropic",
-      ),
-    });
-
-    expect(beforeQueryMock).not.toHaveBeenCalled();
-    expect(dispatcherQueryMock).not.toHaveBeenCalled();
-  });
+        },
+        required: ["tuple"],
+      },
+    ],
+  ] as const)(
+    "accepts an Anthropic schema with %s and proceeds to dispatch (SON-532)",
+    async (_label, schema) => {
+      beforeQueryMock.mockResolvedValueOnce({ requestLogId: 41, stepIndex: 0 });
+      dispatcherQueryMock.mockResolvedValueOnce(queryOutput());
+      afterQueryMock.mockResolvedValueOnce({});
 
-  it("returns 400 for an Anthropic tuple nested under not before logging or dispatch", async () => {
-    await expect(
-      QgridFrame.query({
-        prompt: "hi",
-        model: "anthropic/claude-opus-4-8",
-        jsonSchema: JSON.stringify({
-          type: "object",
-          not: {
-            type: "array",
-            items: [{ type: "string" }],
-          },
+      await expect(
+        QgridFrame.query({
+          prompt: "hi",
+          model: "anthropic/claude-opus-4-8",
+          jsonSchema: JSON.stringify(schema),
         }),
-      }),
-    ).rejects.toMatchObject({
-      statusCode: 400,
-      message: expect.stringContaining(
-        "positional tuple schemas are not supported on Anthropic",
-      ),
-    });
+      ).resolves.toMatchObject({ text: "hello" });
 
-    expect(beforeQueryMock).not.toHaveBeenCalled();
-    expect(dispatcherQueryMock).not.toHaveBeenCalled();
-  });
+      expect(dispatcherQueryMock).toHaveBeenCalledOnce();
+    },
+  );
 
   it("returns 400 for an OpenAI tuple under not instead of changing negative semantics", async () => {
     await expect(
@@ -654,40 +666,13 @@ describe("QgridFrame.query request logging", () => {
     },
   );
 
-  it.each([
-    ["missing", undefined],
-    ["nullable union", ["array", "null"]],
-  ] as const)(
-    "returns 400 for an Anthropic positional tuple with %s type before logging or dispatch",
-    async (_label, type) => {
-      await expect(
-        QgridFrame.query({
-          prompt: "hi",
-          model: "anthropic/claude-opus-4-8",
-          jsonSchema: JSON.stringify({
-            type: "object",
-            properties: {
-              tuple: {
-                ...(type === undefined ? {} : { type }),
-                prefixItems: [{ type: "string" }, { type: "integer" }],
-              },
-            },
-            required: ["tuple"],
-          }),
-        }),
-      ).rejects.toMatchObject({
-        statusCode: 400,
-        message: expect.stringContaining(
-          "positional tuple schemas are not supported on Anthropic",
-        ),
-      });
-
-      expect(beforeQueryMock).not.toHaveBeenCalled();
-      expect(dispatcherQueryMock).not.toHaveBeenCalled();
-    },
-  );
+  // SON-532: argv 64KiB 제한은 --json-schema 전용이었다. 프롬프트 전달은 system 크기
+  // 분기(--system-prompt-file)가 흡수하므로 전역 복잡도 한도만 남는다.
+  it("accepts an Anthropic schema that exceeds the old argv size limit (SON-532)", async () => {
+    beforeQueryMock.mockResolvedValueOnce({ requestLogId: 41, stepIndex: 0 });
+    dispatcherQueryMock.mockResolvedValueOnce(queryOutput());
+    afterQueryMock.mockResolvedValueOnce({});
 
-  it("returns 400 when the final Anthropic schema exceeds the safe argv size", async () => {
     await expect(
       QgridFrame.query({
         prompt: "hi",
@@ -704,13 +689,9 @@ describe("QgridFrame.query request logging", () => {
           properties: { answer: { type: "string" } },
         }),
       }),
-    ).rejects.toMatchObject({
-      statusCode: 400,
-      message: expect.stringContaining("Anthropic dispatch schema exceeds argv"),
-    });
+    ).resolves.toMatchObject({ text: "hello" });
 
-    expect(beforeQueryMock).not.toHaveBeenCalled();
-    expect(dispatcherQueryMock).not.toHaveBeenCalled();
+    expect(dispatcherQueryMock).toHaveBeenCalledOnce();
   });
 
   it("accepts logger: false in the wire schema", () => {
@@ -757,30 +738,22 @@ describe("QgridFrame.prepareStream", () => {
     });
   });
 
-  it("returns 400 for an Anthropic tuple under patternProperties before allocating a stream id", async () => {
-    await expect(
-      QgridFrame.prepareStream({
-        prompt: "hi",
-        model: "anthropic/claude-opus-4-8",
-        jsonSchema: JSON.stringify({
-          type: "object",
-          patternProperties: {
-            "^tuple$": {
-              type: "array",
-              prefixItems: [{ type: "string" }],
-            },
+  it("accepts an Anthropic tuple under patternProperties and allocates a stream id (SON-532)", async () => {
+    const { streamId } = await QgridFrame.prepareStream({
+      prompt: "hi",
+      model: "anthropic/claude-opus-4-8",
+      jsonSchema: JSON.stringify({
+        type: "object",
+        patternProperties: {
+          "^tuple$": {
+            type: "array",
+            prefixItems: [{ type: "string" }],
           },
-        }),
+        },
       }),
-    ).rejects.toMatchObject({
-      statusCode: 400,
-      message: expect.stringContaining(
-        "positional tuple schemas are not supported on Anthropic",
-      ),
     });
 
-    expect(requestLogSaveMock).not.toHaveBeenCalled();
-    expect(dispatcherQueryMock).not.toHaveBeenCalled();
+    expect(streamId).toEqual(expect.any(String));
   });
 
   it("returns 400 for a deeply nested tool schema before allocating a stream id", async () => {
@@ -796,42 +769,36 @@ describe("QgridFrame.prepareStream", () => {
     });
   });
 
-  it("returns 400 for an unsupported composed-schema reference before allocating a stream id", async () => {
-    await expect(
-      QgridFrame.prepareStream({
-        prompt: "hi",
-        model: "anthropic/claude-sonnet-4-6",
-        tools: [{ name: "lookup", inputSchema: { type: "object" } }],
-        jsonSchema: JSON.stringify({
-          type: "object",
-          properties: { answer: { $ref: "#named-anchor" } },
-        }),
+  // strict 합성 시절엔 $defs rebase 때문에 named anchor $ref 를 거절해야 했다.
+  // 프롬프트 전달은 원문을 그대로 안내하므로 재작성이 없고 거절 사유도 사라진다(SON-532).
+  it("accepts a named-anchor $ref on Anthropic and allocates a stream id (SON-532)", async () => {
+    const { streamId } = await QgridFrame.prepareStream({
+      prompt: "hi",
+      model: "anthropic/claude-sonnet-4-6",
+      tools: [{ name: "lookup", inputSchema: { type: "object" } }],
+      jsonSchema: JSON.stringify({
+        type: "object",
+        properties: { answer: { $ref: "#named-anchor" } },
       }),
-    ).rejects.toMatchObject({
-      statusCode: 400,
-      message: expect.stringContaining(
-        "only root-relative JSON Pointer $ref values are supported",
-      ),
     });
+
+    expect(streamId).toEqual(expect.any(String));
   });
 
-  it("returns 400 for an oversized Anthropic argv schema before allocating a stream id", async () => {
-    await expect(
-      QgridFrame.prepareStream({
-        prompt: "hi",
-        model: "anthropic/claude-sonnet-4-6",
-        tools: [
-          {
-            name: "lookup",
-            description: "x".repeat(64 * 1024),
-            inputSchema: { type: "object" },
-          },
-        ],
-      }),
-    ).rejects.toMatchObject({
-      statusCode: 400,
-      message: expect.stringContaining("Anthropic dispatch schema exceeds argv"),
+  it("accepts an Anthropic schema beyond the old argv limit and allocates a stream id (SON-532)", async () => {
+    const { streamId } = await QgridFrame.prepareStream({
+      prompt: "hi",
+      model: "anthropic/claude-sonnet-4-6",
+      tools: [
+        {
+          name: "lookup",
+          description: "x".repeat(64 * 1024),
+          inputSchema: { type: "object" },
+        },
+      ],
     });
+
+    expect(streamId).toEqual(expect.any(String));
   });
 });
 

package/bundle/src/application/qgrid/qgrid.frame.ts

@@ -138,6 +138,8 @@ function rejectImageGenerationStream(args: QueryInput): void {
   );
 }
 
+// anthropic 은 --json-schema 를 쓰지 않으므로(SON-532) strict 변환·argv 제한 없이 원형의
+// 구문·복잡도만 검증된다 — provider 분기는 buildAndValidateStrictOutputSchema 가 소유한다.
 function rejectInvalidCallerSchemas(args: QueryInput): void {
   if (args.jsonSchema === undefined && !args.tools?.length) return;
 

package/bundle/src/application/qgrid/schema-prompt.test.ts

@@ -0,0 +1,166 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  buildEnvelopeExamples,
+  renderOutputSchemaPrompt,
+  renderSchemaContractPrompt,
+  renderToolEnvelopePrompt,
+} from "./schema-prompt";
+
+const TOOLS = [
+  {
+    name: "lookup",
+    description: "Look up a value",
+    inputSchema: {
+      type: "object",
+      properties: { key: { type: "string" } },
+      required: ["key"],
+    },
+  },
+  { name: "save", inputSchema: { type: "object" } },
+];
+
+// 소비자가 nullish 로 선언한 필드가 있는 원형 — strictify 를 거치면 required 로 굳는 형태.
+const USER_SCHEMA = JSON.stringify({
+  type: "object",
+  properties: {
+    title: { type: "string" },
+    mood: { type: ["string", "null"], description: "생략 가능" },
+  },
+  required: ["title"],
+});
+
+describe("renderOutputSchemaPrompt", () => {
+  it("스키마 원문을 재작성 없이 포함하고 raw JSON 지시를 담는다", () => {
+    const rendered = renderOutputSchemaPrompt(USER_SCHEMA);
+
+    expect(rendered).toContain(USER_SCHEMA);
+    expect(rendered).toContain("no code fences");
+    // strictify 흔적이 없어야 한다 — 원형에 없던 additionalProperties 강제가 생기면 안 된다.
+    expect(rendered).not.toContain("additionalProperties");
+  });
+
+  it("$ref 를 포함한 스키마도 원문 그대로 둔다", () => {
+    const schema = JSON.stringify({
+      type: "object",
+      properties: { answer: { $ref: "#named-anchor" } },
+    });
+
+    expect(renderOutputSchemaPrompt(schema)).toContain('"$ref":"#named-anchor"');
+  });
+});
+
+describe("renderToolEnvelopePrompt", () => {
+  it("envelope 계약({\"result\": ...} 래퍼·상호배타·native tool 금지)을 안내한다", () => {
+    const rendered = renderToolEnvelopePrompt(TOOLS);
+
+    expect(rendered).toContain('{"result": ...}');
+    expect(rendered).toContain("Do not invoke them as native Claude Code tools");
+    expect(rendered).toContain('"answer" must be null');
+    expect(rendered).toContain('"toolCalls" must be null');
+    expect(rendered).toContain("at least one entry");
+    // tool 목록과 inputSchema 원문
+    expect(rendered).toContain("- lookup — Look up a value");
+    expect(rendered).toContain('"required":["key"]');
+    expect(rendered).toContain("- save");
+  });
+
+  it("tools+스키마면 answer 자리에 user 스키마를 원형 그대로 안내한다", () => {
+    const rendered = renderToolEnvelopePrompt(TOOLS, USER_SCHEMA);
+
+    expect(rendered).toContain("<answer-json-schema>");
+    expect(rendered).toContain(USER_SCHEMA);
+    expect(rendered).toContain("conforms to the JSON Schema below");
+    // raw-JSON-only 규칙을 예시가 스스로 어기면 안 된다 — 자리표시자 섞인 비 JSON 예시 금지
+    expect(rendered).not.toContain("<JSON conforming");
+  });
+
+  it("생성기가 다루지 못하는 inputSchema 는 예시를 생략하고 구조 서술로 대체한다 (fail-closed)", () => {
+    const patternTool = [
+      {
+        name: "search",
+        inputSchema: {
+          type: "object",
+          properties: { query: { type: "string", pattern: "^[a-z]+$" } },
+          required: ["query"],
+        },
+      },
+    ];
+
+    // pattern 은 지원 집합 밖 — 위반 가능성이 있는 예시를 싣지 않는다
+    expect(buildEnvelopeExamples(patternTool).toolCallExample).toBeUndefined();
+    const rendered = renderToolEnvelopePrompt(patternTool);
+    expect(rendered).toContain('"toolCalls" is an array of objects');
+    expect(rendered).not.toContain('"args": "{'); // 리터럴 예시 부재
+  });
+
+  it("minLength·numeric bound·enum 을 반영한 예시가 실제 스키마를 만족한다 (ajv 교차검증)", async () => {
+    const { default: Ajv2020 } = await import("ajv/dist/2020");
+    const inputSchema = {
+      type: "object",
+      properties: {
+        key: { type: "string", minLength: 10 },
+        limit: { type: "integer", minimum: 5, maximum: 20 },
+        kind: { type: "string", enum: ["book", "film"] },
+        tags: { type: "array", items: { type: "string" }, minItems: 2 },
+      },
+      required: ["key", "limit", "kind", "tags"],
+    };
+    const { toolCallExample } = buildEnvelopeExamples([{ name: "lookup", inputSchema }]);
+    expect(toolCallExample).toBeDefined();
+
+    const envelope = JSON.parse(toolCallExample!) as {
+      result: { toolCalls: Array<{ args: string }> };
+    };
+    const args = JSON.parse(envelope.result.toolCalls[0]!.args) as unknown;
+    const validate = new Ajv2020({ strict: false }).compile(inputSchema);
+    expect(validate(args), JSON.stringify(validate.errors)).toBe(true);
+  });
+
+  it("tool_call 예시의 args 가 그 tool 의 required 필드를 채운 유효 JSON 이다", () => {
+    const { toolCallExample } = buildEnvelopeExamples(TOOLS);
+    expect(toolCallExample).toBeDefined();
+    const envelope = JSON.parse(toolCallExample!) as {
+      result: { toolCalls: Array<{ toolName: string; args: string }> };
+    };
+    const call = envelope.result.toolCalls[0]!;
+
+    expect(call.toolName).toBe("lookup");
+    const args = JSON.parse(call.args) as Record<string, unknown>;
+    // lookup inputSchema: required ["key"] (string)
+    expect(typeof args.key).toBe("string");
+  });
+
+  it("tools 만이면 answer 는 평문 string 안내다", () => {
+    const rendered = renderToolEnvelopePrompt(TOOLS);
+
+    expect(rendered).toContain("plain string");
+    expect(rendered).not.toContain("<answer-json-schema>");
+  });
+});
+
+describe("renderSchemaContractPrompt", () => {
+  it("tools 가 있으면 envelope, 스키마만 있으면 output format, 둘 다 없으면 undefined", () => {
+    expect(renderSchemaContractPrompt({ tools: TOOLS, jsonSchema: USER_SCHEMA })).toContain(
+      "Client Tool Protocol",
+    );
+    expect(renderSchemaContractPrompt({ jsonSchema: USER_SCHEMA })).toContain("Output Format");
+    expect(renderSchemaContractPrompt({})).toBeUndefined();
+    expect(renderSchemaContractPrompt({ tools: [] })).toBeUndefined();
+  });
+});
+
+// 예시 JSON 이 실제 parseEnvelope 를 통과하는 교차 계약 테스트는 tool-emulation.test.ts 에
+// 있다("schema-prompt 예시 ↔ envelope 교차 계약") — 이 파일은 렌더러만 import 해 가볍게
+// 유지한다(isolate:false 공유 레지스트리에서 실모듈 로드가 mock 파일을 오염시키는 것 방지).
+describe("envelope 예시 문자열", () => {
+  it("렌더 문서에 실리는 예시 문자열이 실제로 그 문서 안에 있다", () => {
+    const { toolCallExample, textAnswerExample } = buildEnvelopeExamples(TOOLS);
+
+    expect(renderToolEnvelopePrompt(TOOLS)).toContain(toolCallExample!);
+    expect(renderToolEnvelopePrompt(TOOLS)).toContain(textAnswerExample);
+    // json answer 변형은 유효한 리터럴 예시를 만들 수 없으므로 예시 없이 프로즈로만 —
+    // text answer 예시(string)가 json 모드 문서에 섞이면 모델이 string 을 베낀다.
+    expect(renderToolEnvelopePrompt(TOOLS, USER_SCHEMA)).not.toContain(textAnswerExample);
+  });
+});