@cartanova/qgrid-cli 2.7.0 → 2.7.2

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);
+  });
+});

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

@@ -0,0 +1,293 @@
+/**
+ * output schema / tool envelope 계약의 프롬프트 렌더링 (SON-532).
+ *
+ * anthropic 경로는 CC 에 --json-schema 를 전달하지 않는다 — 강제 없는 사후 채점(AJV)이
+ * 소비자 의도와 충돌해 내부 재시도 루프를 만들었기 때문. 대신 여기서 계약을 텍스트로
+ * 렌더해 system prompt 말미에 주입하고, 판정은 소비자 zod(스키마) / parseEnvelope
+ * (envelope, tool-emulation.ts)가 맡는다.
+ *
+ * 원칙:
+ * - user 스키마는 수신 원형 그대로 안내한다 — strictify(전 필드 required 강제,
+ *   additionalProperties:false)를 거치지 않아 소비자의 nullish/optional 의도가 보존된다.
+ * - envelope 은 buildToolCallSchema(tool-emulation-schema.ts)처럼 user 스키마를 $defs 로
+ *   합성하지 않는다. 텍스트 안내라 `$ref` 문서 루트 충돌이 없어 rebase 가 불필요하고,
+ *   그 덕에 rebase 가 거절하던 형태(named anchor $ref 등)도 그대로 통과한다.
+ * - 렌더된 계약은 parseEnvelope 의 zod 계약({"result": ...} 한 겹, 상호배타 변형)과
+ *   정확히 일치해야 한다 — 교차 테스트(schema-prompt.test.ts)가 드리프트를 막는다.
+ */
+import { type QgridTool, type QueryInput } from "./qgrid.types";
+
+/**
+ * system prompt 말미에 계약을 덧붙인다. anthropic 은 cold-only(매 턴 CC 재스폰 + system
+ * 재전송)라 멀티턴에도 계약이 매 턴 일관되게 주입된다. system 이 argv 64KB 를 넘으면
+ * claude-session 의 --system-prompt-file 분기가 흡수한다.
+ */
+export function composeSystemWithSchemaContract(
+  system: string | undefined,
+  input: Pick<QueryInput, "tools" | "jsonSchema">,
+): string | undefined {
+  const contract = renderSchemaContractPrompt(input);
+  if (contract === undefined) return system;
+  return system ? `${system}\n\n${contract}` : contract;
+}
+
+/** 요청에 스키마/tools 가 없으면 undefined — 계약 주입 없이 평범한 텍스트 요청이다. */
+export function renderSchemaContractPrompt(
+  input: Pick<QueryInput, "tools" | "jsonSchema">,
+): string | undefined {
+  if (input.tools?.length) {
+    return renderToolEnvelopePrompt(input.tools, input.jsonSchema);
+  }
+  if (input.jsonSchema !== undefined) {
+    return renderOutputSchemaPrompt(input.jsonSchema);
+  }
+  return undefined;
+}
+
+// 1091748 실측(스키마 원문 + "펜스·설명 없이 JSON 만" 지시)에서 검증된 형식을 따른다.
+export function renderOutputSchemaPrompt(jsonSchema: string): string {
+  return [
+    "## Output Format",
+    "",
+    "Your entire reply must be a single JSON object that conforms to the JSON Schema below.",
+    "Output raw JSON only — no code fences, no prose before or after the JSON.",
+    "Start your reply with { and end it with }.",
+    "",
+    "<output-json-schema>",
+    jsonSchema,
+    "</output-json-schema>",
+  ].join("\n");
+}
+
+/**
+ * envelope 예시 JSON. 렌더 문구와 parseEnvelope 계약의 드리프트를 교차 테스트로 잡기
+ * 위해 분리 export 한다 — 예시가 실제 파서를 통과하지 못하면 안내문이 틀린 것이다.
+ *
+ * 예시는 스스로 계약을 지켜야 한다: args 는 첫 tool 의 inputSchema 를 실제로 만족하는
+ * 인스턴스여야 한다. 생성기가 다루지 못하는 keyword(pattern/$ref/allOf 등)가 스키마에
+ * 있으면 **fail-closed** — 위반 가능성이 있는 예시를 싣는 대신 예시 자체를 생략하고
+ * 렌더러가 프로즈 서술로 대체한다 (`toolCallExample: undefined`).
+ */
+export function buildEnvelopeExamples(tools: QgridTool[]): {
+  toolCallExample?: string;
+  textAnswerExample: string;
+} {
+  const firstTool = tools[0];
+  const args = firstTool ? exampleValueForSchema(firstTool.inputSchema) : { ok: true, value: {} };
+  return {
+    ...(args.ok
+      ? {
+          toolCallExample: JSON.stringify({
+            result: {
+              action: "tool_call",
+              answer: null,
+              toolCalls: [
+                { toolName: firstTool?.name ?? "toolName", args: JSON.stringify(args.value) },
+              ],
+            },
+          }),
+        }
+      : {}),
+    textAnswerExample: JSON.stringify({
+      result: { action: "answer", answer: "your final answer", toolCalls: null },
+    }),
+  };
+}
+
+type ExampleResult = { ok: true; value: unknown } | { ok: false };
+
+/** 생성기가 값 선택에 반영하는 keyword. 어노테이션(description 등)은 값과 무관해 무시한다. */
+const EXAMPLE_ANNOTATION_KEYWORDS = new Set([
+  "description",
+  "title",
+  "default",
+  "examples",
+  "$comment",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+]);
+const EXAMPLE_HANDLED_KEYWORDS = new Set([
+  "type",
+  "enum",
+  "const",
+  "properties",
+  "required",
+  "additionalProperties",
+  "items",
+  "minItems",
+  "maxItems",
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "anyOf",
+  "oneOf",
+]);
+
+/**
+ * inputSchema 를 만족하는 예시 인스턴스 생성. 지원 keyword 집합 밖의 제약
+ * (pattern/format/$ref/allOf/not/if/multipleOf/uniqueItems/...)을 만나면 값을
+ * 지어내지 않고 { ok: false } 를 돌려준다 — 계약 위반 예시는 모델이 베낀다.
+ */
+function exampleValueForSchema(schema: unknown): ExampleResult {
+  if (schema === true || schema === undefined) return { ok: true, value: {} };
+  if (schema === null || typeof schema !== "object" || Array.isArray(schema)) return { ok: false };
+  const node = schema as Record<string, unknown>;
+
+  for (const keyword of Object.keys(node)) {
+    if (!EXAMPLE_HANDLED_KEYWORDS.has(keyword) && !EXAMPLE_ANNOTATION_KEYWORDS.has(keyword)) {
+      return { ok: false };
+    }
+  }
+
+  if (Array.isArray(node.enum) && node.enum.length > 0) return { ok: true, value: node.enum[0] };
+  if ("const" in node) return { ok: true, value: node.const };
+
+  for (const kw of ["anyOf", "oneOf"] as const) {
+    if (Array.isArray(node[kw])) {
+      // oneOf 는 "정확히 하나"라 첫 브랜치 값이 다른 브랜치에도 매칭될 수 있다 —
+      // 검증기 없이 확신할 수 없으므로 브랜치가 하나일 때만 생성한다.
+      const list = node[kw] as unknown[];
+      if (kw === "oneOf" && list.length > 1) return { ok: false };
+      for (const branch of list) {
+        const result = exampleValueForSchema(branch);
+        if (result.ok) return result;
+      }
+      return { ok: false };
+    }
+  }
+
+  const type = Array.isArray(node.type) ? node.type[0] : node.type;
+  switch (type) {
+    case "string": {
+      const min = typeof node.minLength === "number" ? node.minLength : 0;
+      if (min > 64) return { ok: false };
+      const base = "example";
+      const value = base.length >= min ? base : base.padEnd(min, "x");
+      if (typeof node.maxLength === "number" && value.length > node.maxLength) {
+        if (node.maxLength < min) return { ok: false };
+        return { ok: true, value: value.slice(0, node.maxLength) };
+      }
+      return { ok: true, value };
+    }
+    case "number":
+    case "integer": {
+      let value = 0;
+      if (typeof node.minimum === "number") value = node.minimum;
+      else if (typeof node.exclusiveMinimum === "number") value = node.exclusiveMinimum + 1;
+      if (typeof node.maximum === "number" && value > node.maximum) return { ok: false };
+      if (typeof node.exclusiveMaximum === "number" && value >= node.exclusiveMaximum) {
+        return { ok: false };
+      }
+      return { ok: true, value };
+    }
+    case "boolean":
+      return { ok: true, value: false };
+    case "null":
+      return { ok: true, value: null };
+    case "array": {
+      const min = typeof node.minItems === "number" ? node.minItems : 0;
+      if (min > 8) return { ok: false };
+      if (typeof node.maxItems === "number" && node.maxItems < min) return { ok: false };
+      if (min === 0) return { ok: true, value: [] };
+      const item = exampleValueForSchema(node.items);
+      if (!item.ok) return { ok: false };
+      // 같은 값 반복이라 uniqueItems 와 충돌하지만, uniqueItems 는 지원 집합 밖이라
+      // 위의 keyword 검사에서 이미 fail-closed 된다.
+      return { ok: true, value: Array.from({ length: min }, () => item.value) };
+    }
+    case undefined:
+    case "object": {
+      const properties =
+        node.properties && typeof node.properties === "object" && !Array.isArray(node.properties)
+          ? (node.properties as Record<string, unknown>)
+          : {};
+      const required = Array.isArray(node.required)
+        ? node.required.filter((k): k is string => typeof k === "string")
+        : [];
+      const entries: Array<[string, unknown]> = [];
+      for (const key of required) {
+        const child = exampleValueForSchema(properties[key]);
+        if (!child.ok) return { ok: false };
+        entries.push([key, child.value]);
+      }
+      return { ok: true, value: Object.fromEntries(entries) };
+    }
+    default:
+      return { ok: false };
+  }
+}
+
+// envelope 계약 문구는 buildToolCallSchema 의 description 들과 같은 표현을 쓴다
+// ("Do not invoke ... as native Claude Code tools" 등) — 모델이 structured/프롬프트
+// 어느 안내를 받아도 같은 규칙을 읽게 한다.
+export function renderToolEnvelopePrompt(tools: QgridTool[], jsonSchema?: string): string {
+  const { toolCallExample, textAnswerExample } = buildEnvelopeExamples(tools);
+
+  const toolList = tools
+    .map((tool) => {
+      const description = tool.description ? ` — ${tool.description}` : "";
+      return `- ${tool.name}${description}\n  inputSchema: ${JSON.stringify(tool.inputSchema)}`;
+    })
+    .join("\n");
+
+  // 예시가 raw-JSON-only 규칙을 스스로 어기면 안 된다: json answer 는 스키마 종속이라
+  // 유효한 리터럴 예시를 만들 수 없으므로 예시 없이 프로즈로만 서술한다 (자리표시자가
+  // 섞인 비 JSON 예시를 모델이 그대로 베끼는 것 방지).
+  const answerVariant =
+    jsonSchema === undefined
+      ? [
+          "2. Final answer — use only when no further client tool result is needed:",
+          textAnswerExample,
+          '- "toolCalls" must be null.',
+          '- "answer" must be a plain string with your final answer (not null).',
+        ]
+      : [
+          "2. Final answer — use only when no further client tool result is needed:",
+          '- Set "action" to "answer" and "toolCalls" to null.',
+          '- "answer" must be a JSON value (not null, and not a string of JSON) that conforms to the JSON Schema below.',
+          "",
+          "<answer-json-schema>",
+          jsonSchema,
+          "</answer-json-schema>",
+        ];
+
+  // 예시 생성기가 다루지 못하는 inputSchema(fail-closed)면 구조 서술로 대체한다 —
+  // 스키마를 위반할 수 있는 예시를 싣는 것보다 예시가 없는 편이 안전하다.
+  const toolCallVariant = [
+    toolCallExample !== undefined
+      ? "1. Request client-side tool execution, for example:"
+      : "1. Request client-side tool execution:",
+    ...(toolCallExample !== undefined
+      ? [toolCallExample]
+      : [
+          '- Set "action" to "tool_call" and "answer" to null.',
+          '- "toolCalls" is an array of objects, each {"toolName": ..., "args": ...}.',
+        ]),
+    '- "toolCalls" must contain at least one entry.',
+    '- "toolName" must be one of the client tool names listed below.',
+    '- "args" must be the tool arguments encoded as a JSON string (not an object), conforming to that tool\'s inputSchema.',
+    '- "answer" must be null.',
+  ];
+
+  return [
+    "## Client Tool Protocol",
+    "",
+    "The client-side tools listed below are executed by the client, which returns each result",
+    "in a follow-up turn. Do not invoke them as native Claude Code tools.",
+    "",
+    'Your entire reply must be a single JSON object of the form {"result": ...} —',
+    "raw JSON only, no code fences, no prose before or after the JSON.",
+    'The "result" value is exactly one of the two variants:',
+    "",
+    ...toolCallVariant,
+    "",
+    ...answerVariant,
+    "",
+    "Available client tools:",
+    toolList,
+  ].join("\n");
+}

package/bundle/src/application/qgrid/token-subscriber.ts

@@ -161,7 +161,7 @@ export class TokenSubscriber {
       this.dispatcher.removeCache(payload.id);
       await this.dispatcher.openaiDispatcher
         ?.onTokenRemoved(payload.id)
-        .catch((e) => logger.warn(`openai worker remove failed: ${(e as Error).message}`));
+        .catch((e) => logger.warn(`openai token remove failed: ${(e as Error).message}`));
       // anthropic 토큰 이벤트는 동기(void) — provider 를 모르므로 무해하게 항상 제거 시도.
       this.dispatcher.anthropicDispatcher?.onTokenRemoved(payload.id);
       logger.info(`NOTIFY ${payload.op} id=${payload.id} → removed from cache`);
@@ -172,7 +172,7 @@ export class TokenSubscriber {
       this.dispatcher.removeCache(payload.id);
       await this.dispatcher.openaiDispatcher
         ?.onTokenRemoved(payload.id)
-        .catch((e) => logger.warn(`openai worker remove failed: ${(e as Error).message}`));
+        .catch((e) => logger.warn(`openai token remove failed: ${(e as Error).message}`));
       this.dispatcher.anthropicDispatcher?.onTokenRemoved(payload.id);
       logger.info(`NOTIFY ${payload.op} id=${payload.id} → missing, removed from cache`);
       return;
@@ -192,7 +192,7 @@ export class TokenSubscriber {
             row.quota_threshold,
             row.weight,
           )
-          .catch((e) => logger.warn(`openai worker spawn failed: ${(e as Error).message}`));
+          .catch((e) => logger.warn(`openai token add failed: ${(e as Error).message}`));
       } else if (row.active) {
         if (openaiDispatcher) {
           await openaiDispatcher
@@ -204,7 +204,7 @@ export class TokenSubscriber {
               row.weight,
             )
             .then(() => openaiDispatcher.onTokenActivated(payload.id))
-            .catch((e) => logger.warn(`openai worker update failed: ${(e as Error).message}`));
+            .catch((e) => logger.warn(`openai token update failed: ${(e as Error).message}`));
         }
       } else {
         openaiDispatcher?.onTokenDeactivated(payload.id);

package/bundle/src/application/qgrid/tool-emulation-schema.ts

@@ -11,7 +11,6 @@
  *   → "Composing Tools With A User Output Schema"
  */
 
-import { type JsonValue } from "../../codex-protocol/serde_json/JsonValue";
 import {
   SCHEMA_ARRAY_KEYWORDS,
   SCHEMA_DEPENDENCIES_KEYWORD,
@@ -19,6 +18,7 @@ import {
   SCHEMA_SINGLE_KEYWORDS,
   UNSUPPORTED_REFERENCE_KEYWORDS,
 } from "../../utils/providers/common/json-schema-keywords";
+import { type JsonValue } from "../../utils/providers/common/provider-types";
 import { type QgridTool } from "./qgrid.types";
 
 const USER_OUTPUT_DEFINITION = "__qgrid_user_output";

package/bundle/src/application/qgrid/tool-emulation.test.ts

@@ -11,6 +11,7 @@ const baseResult = {
   usage: {
     input_tokens: 1,
     output_tokens: 1,
+    reasoning_tokens: 0,
     cache_creation_input_tokens: 0,
     cache_read_input_tokens: 0,
   },
@@ -161,6 +162,42 @@ describe("applyToolCallEmulation envelope validation", () => {
     expect(() => applyEnvelope(result, "text")).toThrowError(ToolCallEmulationError);
   });
 
+  // 렌더 문구와 parseEnvelope 계약의 드리프트 방지(SON-532): schema-prompt 안내문에 실린
+  // 예시가 실제 공개 진입점을 통과해야 한다. 예시가 실패하면 안내문이 틀린 것이다.
+  // (schema-prompt.test.ts 가 아닌 여기 두는 이유: 이 파일은 이미 실모듈을 로드한다 —
+  // isolate:false 공유 레지스트리에서 mock 파일 오염을 피한다.)
+  it("schema-prompt 예시 ↔ envelope 교차 계약: tool_call 예시가 해석된다", async () => {
+    const { buildEnvelopeExamples } = await import("./schema-prompt");
+    const { toolCallExample, textAnswerExample } = buildEnvelopeExamples(tools);
+    expect(toolCallExample).toBeDefined(); // lookup inputSchema 는 생성 가능 집합 안이다
+
+    for (const answerKind of ["text", "json"] as const) {
+      const out = applyToolCallEmulation({ ...baseResult, text: toolCallExample! }, tools, {
+        answerKind,
+      });
+      expect(out.finishReason).toBe("tool-calls");
+      expect(out.content[0]).toMatchObject({ type: "tool-call", toolName: "lookup" });
+    }
+
+    const answered = applyToolCallEmulation({ ...baseResult, text: textAnswerExample }, tools, {
+      answerKind: "text",
+    });
+    expect(answered.finishReason).toBe("stop");
+    expect(answered.text).toBe("your final answer");
+  });
+
+  // SON-532: anthropic 은 envelope 을 프롬프트로만 안내하므로 프로즈 응답이 "예상 가능한
+  // 모델 실패"가 됐다. 그래도 구제하지 않는다 — 정직한 실패가 소비자 재시도를 안내한다.
+  it("rejects a prose response with a message that guides the caller", () => {
+    expect(() =>
+      applyToolCallEmulation(
+        { ...baseResult, text: "Sure! I looked it up and the answer is 42." },
+        tools,
+        { answerKind: "json" },
+      ),
+    ).toThrow(/response is not JSON.*retry is the caller's decision/);
+  });
+
   it("rejects an envelope missing the result wrapper", () => {
     expect(() =>
       applyToolCallEmulation(

package/bundle/src/application/qgrid/tool-emulation.ts

@@ -119,11 +119,18 @@ function parseEnvelope(text: string, tools: QgridTool[], answerKind: AnswerKind)
   try {
     value = JSON.parse(text);
   } catch (error) {
-    // 관용 폴백 없음: envelope 는 양 provider 의 structured output 으로 강제되는 내부
-    // 계약이라 여기 도달한 비 JSON 은 버그다. 과거의 텍스트 구제는 퇴화 봉투를 답변으로
-    // 흘려보내 조용한 오염을 만들었다(2026-07 medpath, 13.5k 건).
-    logger.warn(`tool envelope parse failed: ${(error as Error).message}`);
-    throw new ToolCallEmulationError(`invalid tool envelope: ${(error as Error).message}`);
+    // 관용 폴백 없음. openai 는 envelope 이 structured output 으로 강제되므로 여기 도달한
+    // 비 JSON 은 버그다. anthropic 은 계약을 프롬프트로만 안내하므로(SON-532) 비 JSON 이
+    // "예상 가능한 모델 실패"지만, 그래도 구제하지 않는다 — 과거의 텍스트 구제는 퇴화
+    // 봉투를 답변으로 흘려보내 조용한 오염을 만들었다(2026-07 medpath, 13.5k 건).
+    // 정직한 실패가 보여야 소비자가 재시도하거나 근본 원인을 고친다.
+    // 진단에는 위반 원문의 머리가 필요하다(SON-495 전례) — parse 에러 위치만으로는
+    // "프로즈로 답했는지 / 펜스가 남았는지 / JSON 이 잘렸는지"를 구분할 수 없다.
+    const head = JSON.stringify(text.slice(0, 200));
+    logger.warn(`tool envelope parse failed: ${(error as Error).message}; head=${head}`);
+    throw new ToolCallEmulationError(
+      `invalid tool envelope (response is not JSON — the model ignored the envelope contract; retry is the caller's decision): ${(error as Error).message}; response head: ${head}`,
+    );
   }
 
   assertStructuredEnvelopeComplexity(value);
@@ -133,8 +140,13 @@ function parseEnvelope(text: string, tools: QgridTool[], answerKind: AnswerKind)
     const issue = validation.error.issues[0];
     const path = issue && issue.path.length > 0 ? ` at ${issue.path.join(".")}` : "";
     const detail = issue?.message ?? "unknown validation issue";
-    logger.warn(`tool envelope validation failed${path}: ${detail}`);
-    throw new ToolCallEmulationError(`invalid tool envelope${path}: ${detail}`);
+    // valid JSON 이지만 계약 위반인 경우에도 원문 머리를 남긴다 — zod 경로만으로는
+    // "키 생략인지 / 래퍼로 감쌌는지 / 타입이 틀렸는지"의 실물을 볼 수 없다.
+    const head = JSON.stringify(text.slice(0, 200));
+    logger.warn(`tool envelope validation failed${path}: ${detail}; head=${head}`);
+    throw new ToolCallEmulationError(
+      `invalid tool envelope${path}: ${detail}; response head: ${head}`,
+    );
   }
 
   // Zod clones JSON objects and drops own "__proto__" keys. The parsed JSON is safe to return

package/bundle/src/application/queries.generated.ts

@@ -94,6 +94,9 @@ export namespace RequestLogService {
       [subset, rawParams],
       ["RequestLog", "getRequestLogs"],
     );
+
+  export const responseTypeTs = (id: number): SSRQuery =>
+    createSSRQuery("RequestLogModel", "responseTypeTs", [id], ["RequestLog", "responseTypeTs"]);
 }
 
 export namespace QgridService {
@@ -122,4 +125,7 @@ export namespace MonitService {
 
   export const monitInfo = (): SSRQuery =>
     createSSRQuery("MonitFrame", "monitInfo", [], ["Monit", "monitInfo"]);
+
+  export const monitStats = (): SSRQuery =>
+    createSSRQuery("MonitFrame", "monitStats", [], ["Monit", "monitStats"]);
 }