@cartanova/qgrid-cli 2.5.3 → 2.5.5

package/bundle/src/application/qgrid/qgrid-run-lifecycle.test.ts

@@ -233,6 +233,109 @@ describe("qgrid run lifecycle TTFT", () => {
     );
   });
 
+  it("persists an immediate structured final answer as JSON text", async () => {
+    await afterQuery(
+      10,
+      0,
+      {
+        prompt: "answer",
+        tools: [{ name: "lookup", inputSchema: { type: "object" } }],
+        jsonSchema: JSON.stringify({
+          type: "object",
+          properties: { result: { type: "string" } },
+        }),
+      },
+      queryOutput({
+        text: '{"result":"ok"}',
+        content: [{ type: "text", text: '{"result":"ok"}' }],
+      }),
+    );
+
+    expect(appendStepMock).toHaveBeenCalledWith(
+      10,
+      expect.objectContaining({
+        step_index: 0,
+        type: "generate",
+        finish_reason: "stop",
+      }),
+    );
+    expect(finishRunMock).toHaveBeenCalledWith(
+      10,
+      expect.objectContaining({
+        status: "succeeded",
+        response: '{"result":"ok"}',
+      }),
+    );
+  });
+
+  it("persists a tool turn and a structured final answer on the continued run", async () => {
+    const schema = JSON.stringify({
+      type: "object",
+      properties: { result: { type: "string" } },
+    });
+    const first = await afterQuery(
+      10,
+      0,
+      { prompt: "lookup", tools: [{ name: "lookup", inputSchema: {} }], jsonSchema: schema },
+      queryOutput({
+        text: "",
+        content: [
+          {
+            type: "tool-call",
+            toolCallId: "call-1",
+            toolName: "lookup",
+            input: '{"key":"value"}',
+          },
+        ],
+        finishReason: "tool-calls",
+      }),
+    );
+
+    expect(first).toEqual({ runContext: { requestLogId: 10 } });
+    expect(finishRunMock).not.toHaveBeenCalled();
+    expect(appendStepMock).toHaveBeenCalledWith(
+      10,
+      expect.objectContaining({
+        step_index: 0,
+        type: "tool_call",
+        tool_call_id: "call-1",
+      }),
+    );
+
+    await afterQuery(
+      10,
+      2,
+      {
+        prompt: "continue",
+        tools: [{ name: "lookup", inputSchema: {} }],
+        jsonSchema: schema,
+        runContext: { requestLogId: 10 },
+        toolResults: [{ toolCallId: "call-1", output: '{"value":"found"}' }],
+      },
+      queryOutput({
+        text: '{"result":"found"}',
+        content: [{ type: "text", text: '{"result":"found"}' }],
+        finishReason: "stop",
+      }),
+    );
+
+    expect(appendStepMock).toHaveBeenCalledWith(
+      10,
+      expect.objectContaining({
+        step_index: 2,
+        type: "generate",
+        finish_reason: "stop",
+      }),
+    );
+    expect(finishRunMock).toHaveBeenCalledWith(
+      10,
+      expect.objectContaining({
+        status: "succeeded",
+        response: '{"result":"found"}',
+      }),
+    );
+  });
+
   it("finishes runs with image data-url img tags in response", async () => {
     await afterQuery(
       10,

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

@@ -25,7 +25,32 @@ function providerResult(overrides: Partial<GenerateResult> = {}): GenerateResult
   };
 }
 
+function deeplyNestedOutputSchema(depth: number): string {
+  const nestedArray = `${'{"type":"array","items":'.repeat(depth)}{"type":"string"}${"}".repeat(depth)}`;
+  return `{"type":"object","properties":{"value":${nestedArray}}}`;
+}
+
 describe("QgridDispatcherClass", () => {
+  const toolsAndSchema = {
+    tools: [
+      {
+        name: "lookup",
+        description: "Look up a value",
+        inputSchema: {
+          type: "object",
+          properties: { key: { type: "string" } },
+          required: ["key"],
+        },
+      },
+    ],
+    jsonSchema: JSON.stringify({
+      type: "object",
+      properties: {
+        result: { type: "string" },
+      },
+    }),
+  };
+
   it("AnthropicDispatcher 미초기화 시 query 는 폴백 없이 실패한다", async () => {
     const dispatcher = new QgridDispatcherClass();
 
@@ -282,6 +307,68 @@ describe("QgridDispatcherClass", () => {
     expect(contentsArray?.items?.additionalProperties).toBe(false);
   });
 
+  it("tools + schema composition preserves prototype-sensitive keys through serialization", () => {
+    const propertyNames = ["__proto__", "constructor", "prototype"];
+    const properties = JSON.parse(
+      '{"__proto__":{"type":"string"},"constructor":{"type":"integer"},"prototype":{"type":"boolean"}}',
+    ) as Record<string, unknown>;
+    const schema = buildStrictOutputSchema({
+      tools: toolsAndSchema.tools,
+      jsonSchema: JSON.stringify({
+        type: "object",
+        properties,
+        required: propertyNames,
+      }),
+    }) as {
+      $defs?: {
+        __qgrid_user_output?: {
+          properties?: Record<string, unknown>;
+          required?: string[];
+        };
+      };
+    };
+    const strictUserSchema = schema.$defs?.__qgrid_user_output;
+    const strictProperties = strictUserSchema?.properties;
+
+    expect(strictUserSchema?.required).toEqual(propertyNames);
+    for (const propertyName of propertyNames) {
+      expect(Object.prototype.hasOwnProperty.call(strictProperties, propertyName)).toBe(true);
+    }
+
+    const serialized = JSON.stringify(schema);
+    expect(serialized).toContain('"__proto__":{"type":"string"}');
+    expect(serialized).toContain('"constructor":{"type":"integer"}');
+    expect(serialized).toContain('"prototype":{"type":"boolean"}');
+  });
+
+  it.each([
+    ["schema-only", undefined, deeplyNestedOutputSchema(5_000), "jsonSchema"],
+    ["tools + schema", toolsAndSchema.tools, deeplyNestedOutputSchema(5_000), "jsonSchema"],
+    [
+      "tools-only",
+      [
+        {
+          name: "deepTool",
+          inputSchema: JSON.parse(deeplyNestedOutputSchema(5_000)) as unknown,
+        },
+      ],
+      undefined,
+      "tools[0].inputSchema",
+    ],
+  ])(
+    "%s 경로에서 재귀 변환 전에 과도하게 깊은 caller schema를 거부한다",
+    (_label, tools, jsonSchema, errorPath) => {
+      expect(() => buildStrictOutputSchema({ jsonSchema, tools })).toThrow(
+        `qgrid: ${errorPath} exceeds depth limit`,
+      );
+      try {
+        buildStrictOutputSchema({ jsonSchema, tools });
+      } catch (error) {
+        expect(error).not.toBeInstanceOf(RangeError);
+      }
+    },
+  );
+
   // SON-495: anthropic route 도 strict(required 유지)를 쓴다 — required 를 살려야 모델이 필드를
   // 빠짐없이 채운다(실측 확정). optionalize 는 제거됨.
   it("Anthropic route 에 strict(required 유지) outputSchema 를 전달한다", async () => {
@@ -361,6 +448,256 @@ describe("QgridDispatcherClass", () => {
     expect(outputSchema.additionalProperties).toBe(false);
   });
 
+  it("tools + jsonSchema 를 합성하고 user $defs까지 strictify 한다", () => {
+    const schema = buildStrictOutputSchema({
+      tools: toolsAndSchema.tools,
+      jsonSchema: JSON.stringify({
+        type: "object",
+        properties: { item: { $ref: "#/$defs/Item" } },
+        $defs: {
+          Item: {
+            type: "object",
+            properties: {
+              value: { type: "string" },
+              optionalNote: { type: "string" },
+            },
+            required: ["value"],
+          },
+        },
+      }),
+    }) as {
+      properties?: { answer?: { anyOf?: Array<{ $ref?: string }> } };
+      $defs?: {
+        __qgrid_user_output?: {
+          required?: string[];
+          additionalProperties?: boolean;
+          properties?: { item?: { anyOf?: Array<{ $ref?: string }> } };
+          $defs?: {
+            Item?: {
+              required?: string[];
+              additionalProperties?: boolean;
+              properties?: { optionalNote?: { anyOf?: unknown[] } };
+            };
+          };
+        };
+      };
+    };
+    const userSchema = schema.$defs?.__qgrid_user_output;
+
+    expect(schema.properties?.answer?.anyOf?.[0]?.$ref).toBe(
+      "#/$defs/__qgrid_user_output",
+    );
+    expect(userSchema).toMatchObject({
+      required: ["item"],
+      additionalProperties: false,
+      properties: {
+        item: {
+          anyOf: [
+            { $ref: "#/$defs/__qgrid_user_output/$defs/Item" },
+            { type: "null" },
+          ],
+        },
+      },
+    });
+    expect(userSchema?.$defs?.Item).toMatchObject({
+      required: ["value", "optionalNote"],
+      additionalProperties: false,
+    });
+    expect(userSchema?.$defs?.Item?.properties?.optionalNote?.anyOf).toEqual([
+      { type: "string" },
+      { type: "null" },
+    ]);
+  });
+
+  it("tools + jsonSchema 합성 경로에서 prefixItems tuple 구성원도 strictify 한다", () => {
+    const schema = buildStrictOutputSchema({
+      tools: toolsAndSchema.tools,
+      jsonSchema: JSON.stringify({
+        type: "object",
+        properties: {
+          tuple: {
+            type: "array",
+            prefixItems: [
+              {
+                type: "object",
+                properties: { label: { type: "string" } },
+                required: ["label"],
+              },
+              { type: "integer" },
+            ],
+            minItems: 2,
+            maxItems: 2,
+          },
+        },
+        required: ["tuple"],
+      }),
+    }) as {
+      $defs?: {
+        __qgrid_user_output?: {
+          properties?: {
+            tuple?: {
+              prefixItems?: Array<{
+                required?: string[];
+                additionalProperties?: boolean;
+              }>;
+            };
+          };
+        };
+      };
+    };
+
+    expect(
+      schema.$defs?.__qgrid_user_output?.properties?.tuple?.prefixItems?.[0],
+    ).toMatchObject({
+      required: ["label"],
+      additionalProperties: false,
+    });
+  });
+
+  it("OpenAI tools + draft-07 tuple schema를 위치 제약을 보존해 정규화한다", () => {
+    const schema = buildStrictOutputSchema(
+      {
+        tools: toolsAndSchema.tools,
+        jsonSchema: JSON.stringify({
+          $schema: "http://json-schema.org/draft-07/schema#",
+          type: "object",
+          properties: {
+            tuple: {
+              type: "array",
+              items: [
+                {
+                  type: "object",
+                  properties: { label: { type: "string" } },
+                },
+                { type: "integer" },
+              ],
+            },
+          },
+          required: ["tuple"],
+        }),
+      },
+      "openai",
+    ) as {
+      $defs?: {
+        __qgrid_user_output?: {
+          properties?: {
+            tuple?: {
+              items?: unknown;
+              prefixItems?: unknown[];
+              minItems?: number;
+              maxItems?: number;
+            };
+          };
+        };
+      };
+    };
+    const tuple = schema.$defs?.__qgrid_user_output?.properties?.tuple;
+
+    expect(tuple).toMatchObject({
+      minItems: 2,
+      maxItems: 2,
+    });
+    expect(Array.isArray(tuple?.items)).toBe(false);
+    expect(tuple?.prefixItems).toHaveLength(2);
+  });
+
+  it("Anthropic tools + positional tuple schema는 의미를 약화하지 않고 거부한다", () => {
+    expect(() =>
+      buildStrictOutputSchema(
+        {
+          tools: toolsAndSchema.tools,
+          jsonSchema: JSON.stringify({
+            type: "object",
+            properties: {
+              tuple: {
+                type: "array",
+                items: [{ type: "string" }, { type: "integer" }],
+              },
+            },
+            required: ["tuple"],
+          }),
+        },
+        "anthropic",
+      ),
+    ).toThrow(/positional tuple schemas are not supported on Anthropic/);
+  });
+
+  it.each([
+    ["openai", "query"],
+    ["openai", "queryStream"],
+    ["anthropic", "query"],
+    ["anthropic", "queryStream"],
+  ] as const)(
+    "%s %s 모두 tools + jsonSchema composed outputSchema를 provider에 전달한다",
+    async (provider, method) => {
+      const dispatcher = new QgridDispatcherClass();
+      const model =
+        provider === "openai" ? "openai/gpt-5.5" : "anthropic/claude-sonnet-4-6";
+      let request: GenerateRequest | undefined;
+      let mappedText: string | undefined;
+
+      if (method === "query") {
+        const generate = vi.fn(async (req: GenerateRequest) => {
+          request = req;
+          return providerResult({
+            text: '{"action":"answer","answer":{"result":"ok"},"toolCalls":null}',
+          });
+        });
+        if (provider === "openai") dispatcher.openaiDispatcher = { generate } as never;
+        else dispatcher.anthropicDispatcher = { generate } as never;
+
+        const output = await dispatcher.query({ prompt: "hi", model, ...toolsAndSchema });
+        mappedText = output.text;
+      } else {
+        const generateStream = vi.fn(
+          async (req: GenerateRequest, cb: GenerateStreamCallbacks) => {
+            request = req;
+            cb.onComplete(
+              providerResult({
+                text: '{"action":"answer","answer":{"result":"ok"},"toolCalls":null}',
+              }),
+            );
+          },
+        );
+        if (provider === "openai") {
+          dispatcher.openaiDispatcher = { generateStream } as never;
+        } else {
+          dispatcher.anthropicDispatcher = { generateStream } as never;
+        }
+
+        await dispatcher.queryStream(
+          { prompt: "hi", model, ...toolsAndSchema },
+          {
+            onDelta: vi.fn(),
+            onComplete: (output) => {
+              mappedText = output.text;
+            },
+            onError: vi.fn(),
+          },
+        );
+      }
+
+      expect(request?.outputSchema).toMatchObject({
+        properties: {
+          answer: {
+            anyOf: [
+              { $ref: "#/$defs/__qgrid_user_output" },
+              { type: "null" },
+            ],
+          },
+        },
+        $defs: {
+          __qgrid_user_output: {
+            type: "object",
+            required: ["result"],
+            additionalProperties: false,
+          },
+        },
+      });
+      expect(mappedText).toBe('{"result":"ok"}');
+    },
+  );
+
   it("provider 가 산출한 costUsd 를 가격표 fallback 보다 우선한다", async () => {
     const dispatcher = new QgridDispatcherClass();
     const generate = vi.fn(

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

@@ -14,6 +14,10 @@ import {
   type GenerateResult,
   type StreamCallbacks,
 } from "../../utils/providers/common/provider-dispatcher";
+import {
+  parseAndValidateCallerSchemas,
+  serializeAndValidateDispatchSchema,
+} from "../../utils/providers/common/schema-validation";
 import { strictify } from "../../utils/providers/common/strictifier";
 import { type OpenAIDispatcher } from "../../utils/providers/openai/openai-dispatcher";
 import { type TokenSubsetA } from "../sonamu.generated";
@@ -21,7 +25,8 @@ import { decideConvRouting, issueConvContext } from "./conv-routing";
 import { type QueryInput, type QueryOutput, type TokenStats } from "./qgrid.types";
 import { maskToken, ProcessError, QuotaError } from "./qgrid.types";
 import { type TokenSubscriber } from "./token-subscriber";
-import { applyToolCallEmulation, buildToolCallSchema } from "./tool-emulation";
+import { applyToolCallEmulation } from "./tool-emulation";
+import { buildToolCallSchema } from "./tool-emulation-schema";
 
 export class QgridDispatcherClass {
   tokens = new Map<number, TokenSubsetA>();
@@ -61,12 +66,10 @@ export class QgridDispatcherClass {
   }
 
   async query(input: QueryInput, abortSignal?: AbortSignal): Promise<QueryOutput> {
-    if (input.tools?.length && input.jsonSchema) {
-      throw new ProcessError("tools and jsonSchema cannot be used together");
-    }
-
     const route = parseProviderRoute(input.model);
-    const outputSchema = buildStrictOutputSchema(input);
+    const outputSchema = buildAndValidateStrictOutputSchema(input, route.provider);
+    // tools+jsonSchema 합성 시 structured envelope 디코더를 쓴다. 4개 방출 지점이 공유하는 단일 판정.
+    const answerMode = input.jsonSchema ? ("structured" as const) : ("legacy" as const);
 
     // provider prefix routing: 'openai/gpt-5.4' → OpenAIDispatcher
     if (route.provider === "openai") {
@@ -96,7 +99,11 @@ export class QgridDispatcherClass {
         ? undefined
         : issueConvContext(result.threadCoord, decision);
 
-      return applyToolCallEmulation(toEmulationResult(result), input.tools, coord, result.images);
+      return applyToolCallEmulation(toEmulationResult(result), input.tools, {
+        threadCoord: coord,
+        images: result.images,
+        answerMode,
+      });
     } else if (route.provider === "anthropic") {
       if (!this.anthropicDispatcher) throw new QuotaError("Anthropic dispatcher not initialized");
 
@@ -115,11 +122,10 @@ export class QgridDispatcherClass {
         imageGenerationOptions: input.imageGenerationOptions,
       });
 
-      return applyToolCallEmulation(
-        toEmulationResult(result),
-        input.tools,
-        issueConvContext(result.threadCoord, decision),
-      );
+      return applyToolCallEmulation(toEmulationResult(result), input.tools, {
+        threadCoord: issueConvContext(result.threadCoord, decision),
+        answerMode,
+      });
     }
 
     throw directLlmApiFallbackNotImplemented(input);
@@ -131,7 +137,9 @@ export class QgridDispatcherClass {
     abortSignal?: AbortSignal,
   ): Promise<void> {
     const route = parseProviderRoute(input.model);
-    const outputSchema = buildStrictOutputSchema(input);
+    const outputSchema = buildAndValidateStrictOutputSchema(input, route.provider);
+    // tools+jsonSchema 합성 시 structured envelope 디코더를 쓴다. 4개 방출 지점이 공유하는 단일 판정.
+    const answerMode = input.jsonSchema ? ("structured" as const) : ("legacy" as const);
 
     if (route.provider === "openai") {
       if (!this.openaiDispatcher) throw new QuotaError("OpenAI dispatcher not initialized");
@@ -161,11 +169,10 @@ export class QgridDispatcherClass {
           onTurnId: cb.onTurnId,
           onComplete: (turnResult) => {
             cb.onComplete(
-              applyToolCallEmulation(
-                toEmulationResult(turnResult),
-                input.tools,
-                issueConvContext(turnResult.threadCoord, decision),
-              ),
+              applyToolCallEmulation(toEmulationResult(turnResult), input.tools, {
+                threadCoord: issueConvContext(turnResult.threadCoord, decision),
+                answerMode,
+              }),
             );
           },
           onError: cb.onError,
@@ -195,7 +202,10 @@ export class QgridDispatcherClass {
           onComplete: (turnResult) => {
             const issuedCoord = issueConvContext(turnResult.threadCoord, decision);
             cb.onComplete(
-              applyToolCallEmulation(toEmulationResult(turnResult), input.tools, issuedCoord),
+              applyToolCallEmulation(toEmulationResult(turnResult), input.tools, {
+                threadCoord: issuedCoord,
+                answerMode,
+              }),
             );
           },
           onError: cb.onError,
@@ -230,25 +240,35 @@ function directLlmApiFallbackNotImplemented(input: QueryInput): ProcessError {
 // SON-495 교훈: 한때 Anthropic route 만 required 를 제거(optionalize)해 partial/rejected attempt 가
 // 섞여도 통과하게 했으나, 실측 결과 그게 오히려 "모델이 비는 필드를 키째 생략"하도록 유도했다
 // (required 살린 schema 는 누락 0, loose 는 누락 다발). strict 로 두면 모델이 빠짐없이 채우고,
-// 드물게 어겨도 retry=1 + 비정상 종료는 정직한 에러(stream-json-adapter)로 받아준다.
+// 드물게 어겨 provider retry 예산을 소진한 비정상 종료도 정직한 에러로 받아준다.
 export function buildStrictOutputSchema(
   input: Pick<QueryInput, "tools" | "jsonSchema">,
+  provider?: string,
 ): JsonValue | undefined {
   const outputSchema = buildRawOutputSchema(input);
 
   return outputSchema
-    ? (strictify(outputSchema as Parameters<typeof strictify>[0]) as JsonValue)
+    ? (strictify(outputSchema as Parameters<typeof strictify>[0], { provider }) as JsonValue)
     : undefined;
 }
 
+export function buildAndValidateStrictOutputSchema(
+  input: Pick<QueryInput, "model" | "tools" | "jsonSchema">,
+  provider = parseProviderRoute(input.model).provider,
+): JsonValue | undefined {
+  const outputSchema = buildStrictOutputSchema(input, provider);
+  serializeAndValidateDispatchSchema(outputSchema, provider);
+  return outputSchema;
+}
+
 function buildRawOutputSchema(
   input: Pick<QueryInput, "tools" | "jsonSchema">,
 ): JsonValue | undefined {
+  const callerOutputSchema = parseAndValidateCallerSchemas(input);
+
   return input.tools?.length
-    ? buildToolCallSchema(input.tools)
-    : input.jsonSchema
-      ? (JSON.parse(input.jsonSchema) as JsonValue)
-      : undefined;
+    ? buildToolCallSchema(input.tools, callerOutputSchema)
+    : callerOutputSchema;
 }
 
 // GenerateResult(provider dispatcher 응답)를 applyToolCallEmulation 입력 shape 로 매핑한다.