@cartanova/qgrid-cli 2.5.2 → 2.5.4

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

@@ -1,7 +1,7 @@
 import crypto from "node:crypto";
 
 import { getLogger } from "@logtape/logtape";
-import { type FastifyReply } from "fastify";
+import { type FastifyReply, type FastifyRequest } from "fastify";
 import { api, BadRequestException, BaseFrameClass, Sonamu, stream } from "sonamu";
 import { getCacheManagerRef } from "sonamu/cache";
 
@@ -11,6 +11,7 @@ import {
   getExpiresAt,
   getRefreshToken,
 } from "../../utils/providers/common/credentials";
+import { CallerSchemaValidationError } from "../../utils/providers/common/schema-validation";
 import { MICRO_USD, RequestLogModel } from "../request-log/request-log.model";
 import { type TokenSubsetA } from "../sonamu.generated";
 import { TokenModel, type TokenUpdateFields } from "../token/token.model";
@@ -29,7 +30,7 @@ import {
   finishRunAborted,
   finishRunWithError,
 } from "./qgrid-run-lifecycle";
-import { QgridDispatcher } from "./qgrid.dispatcher";
+import { buildAndValidateStrictOutputSchema, QgridDispatcher } from "./qgrid.dispatcher";
 import {
   type QueryInput,
   type AppendStepInput,
@@ -43,6 +44,7 @@ import {
   type TokenStats,
   type UsageResponse,
 } from "./qgrid.types";
+import { ToolSchemaCompositionError } from "./tool-emulation-schema";
 
 const pendingStreams = new Map<string, QueryInput>();
 
@@ -100,6 +102,66 @@ function rejectLegacyLogMode(args: QueryInput): void {
   );
 }
 
+function rejectInvalidCallerSchemas(args: QueryInput): void {
+  if (args.jsonSchema === undefined && !args.tools?.length) return;
+
+  try {
+    buildAndValidateStrictOutputSchema(args);
+  } catch (error) {
+    if (
+      error instanceof CallerSchemaValidationError ||
+      error instanceof ToolSchemaCompositionError
+    ) {
+      throw new BadRequestException(error.message as LocalizedString);
+    }
+    // 잘못된 keyword 형태(anyOf 를 객체로 보내는 등)는 파이프라인에서 untyped 오류로 나오므로,
+    // 타입 좁히기 대신 Error 전체를 caller-fault 400 으로 매핑한다(계약 테스트로 고정됨).
+    if (error instanceof Error) {
+      throw new BadRequestException(
+        `qgrid: caller schema cannot be normalized: ${error.message}` as LocalizedString,
+      );
+    }
+    throw error;
+  }
+}
+
+function createHttpDisconnectHandle(): {
+  signal: AbortSignal;
+  dispose: () => void;
+} {
+  const abortController = new AbortController();
+  let requestRaw: FastifyRequest["raw"] | undefined;
+  let responseRaw: FastifyReply["raw"] | undefined;
+
+  try {
+    const ctx = Sonamu.getContext();
+    requestRaw = ctx.request?.raw;
+    if (ctx.transport === "http") responseRaw = ctx.reply.raw;
+  } catch {
+    // Direct frame calls (for example unit tests) do not have an HTTP context.
+  }
+
+  const abort = () => abortController.abort();
+  const abortOnIncompleteResponseClose = () => {
+    if (!responseRaw?.writableEnded) abort();
+  };
+
+  requestRaw?.once("aborted", abort);
+  responseRaw?.once("close", abortOnIncompleteResponseClose);
+
+  if (requestRaw?.aborted || (responseRaw?.destroyed && !responseRaw.writableEnded)) {
+    abort();
+  }
+
+  return {
+    signal: abortController.signal,
+    dispose: () => {
+      requestRaw?.removeListener("aborted", abort);
+      responseRaw?.removeListener("close", abortOnIncompleteResponseClose);
+    },
+  };
+}
+
 const logger = getLogger(["qgrid"]);
 const oauthLogger = getLogger(["qgrid", "oauth"]);
 
@@ -111,33 +173,50 @@ class QgridFrameClass extends BaseFrameClass {
   @api({ httpMethod: "POST", clients: ["axios", "tanstack-mutation"] })
   async query(args: QueryInput): Promise<QueryOutput> {
     rejectLegacyLogMode(args);
-    if (args.logger === false) {
-      return QgridDispatcher.query(args, args.timeout);
-    }
-
-    const { requestLogId, stepIndex } = await beforeQuery(args);
-    let result: QueryOutput;
+    rejectInvalidCallerSchemas(args);
+    const disconnect = createHttpDisconnectHandle();
     try {
-      result = await QgridDispatcher.query(args, args.timeout);
-    } catch (e) {
-      await finishRunWithError(requestLogId, (e as Error).message, args);
-      throw e;
-    }
+      if (args.logger === false) {
+        return await QgridDispatcher.query(args, disconnect.signal);
+      }
 
-    try {
-      const lifecycle = await afterQuery(requestLogId, stepIndex, args, result);
-      // tool-call requestLogId와 provider threadCoord는 서로 독립적으로 유지한다.
-      const threadCoord = result.runContext?.threadCoord;
-      const runContext =
-        lifecycle.runContext || threadCoord
-          ? { ...lifecycle.runContext, ...(threadCoord ? { threadCoord } : {}) }
-          : undefined;
-      return { ...result, runContext };
-    } catch (e) {
-      logger.error(`query afterQuery failed: ${(e as Error).message}`);
-      await finishRunWithError(requestLogId, (e as Error).message, args);
-      // provider 응답은 성공했으므로 로깅 장애가 생성 결과를 덮어쓰지 않는다.
-      return result;
+      const { requestLogId, stepIndex } = await beforeQuery(args);
+      let result: QueryOutput;
+      try {
+        result = await QgridDispatcher.query(args, disconnect.signal);
+      } catch (e) {
+        if (disconnect.signal.aborted) {
+          await finishRunAborted(requestLogId, args);
+        } else {
+          await finishRunWithError(requestLogId, (e as Error).message, args);
+        }
+        throw e;
+      }
+
+      try {
+        const lifecycle = await afterQuery(requestLogId, stepIndex, args, result);
+        if (disconnect.signal.aborted) {
+          await finishRunAborted(requestLogId, args);
+        }
+        // tool-call requestLogId와 provider threadCoord는 서로 독립적으로 유지한다.
+        const threadCoord = result.runContext?.threadCoord;
+        const runContext =
+          lifecycle.runContext || threadCoord
+            ? { ...lifecycle.runContext, ...(threadCoord ? { threadCoord } : {}) }
+            : undefined;
+        return { ...result, runContext };
+      } catch (e) {
+        logger.error(`query afterQuery failed: ${(e as Error).message}`);
+        if (disconnect.signal.aborted) {
+          await finishRunAborted(requestLogId, args);
+        } else {
+          await finishRunWithError(requestLogId, (e as Error).message, args);
+        }
+        // provider 응답은 성공했으므로 로깅 장애가 생성 결과를 덮어쓰지 않는다.
+        return result;
+      }
+    } finally {
+      disconnect.dispose();
     }
   }
 
@@ -145,6 +224,7 @@ class QgridFrameClass extends BaseFrameClass {
   async prepareStream(args: QueryInput): Promise<{ streamId: string }> {
     rejectLegacyLogMode(args);
     rejectImageGenerationStream(args);
+    rejectInvalidCallerSchemas(args);
     const streamId = crypto.randomUUID();
     pendingStreams.set(streamId, args);
     const expiry = setTimeout(() => pendingStreams.delete(streamId), 30_000);

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

@@ -69,6 +69,9 @@ export const QgridInputPart = z.discriminatedUnion("type", [
 ]);
 export type QgridInputPart = z.infer<typeof QgridInputPart>;
 
+export const MAX_QUERY_TIMEOUT_MS = 30 * 60_000;
+export const QueryTimeoutMs = z.number().int().positive().max(MAX_QUERY_TIMEOUT_MS);
+
 // ─── Run Lifecycle Context (SDK ↔ Server contract) ───
 
 // codex thread 좌표. thread 재사용으로 conversation_id(=prompt_cache_key)를 고정해
@@ -103,7 +106,7 @@ export const QueryInput = z
     prompt: z.string(),
     input: z.array(QgridInputPart).optional(),
     model: z.string().optional(),
-    timeout: z.number().optional(),
+    timeout: QueryTimeoutMs.optional(),
     jsonSchema: z.string().optional(),
     tools: z.array(QgridTool).optional(),
     effort: z.string().optional(),

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

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "vitest";
+
+import { type QgridTool } from "./qgrid.types";
+import { buildToolCallSchema } from "./tool-emulation-schema";
+
+const userPath = (...path: Array<string | number>) => [
+  "$defs",
+  "__qgrid_user_output",
+  ...path,
+];
+
+describe("buildToolCallSchema", () => {
+  const tools: QgridTool[] = [
+    {
+      name: "getWeather",
+      description: "Get weather for a city",
+      inputSchema: {
+        type: "object",
+        properties: { city: { type: "string" } },
+        required: ["city"],
+        additionalProperties: false,
+      },
+    },
+  ];
+
+  it("documents that emulated tools must be requested through StructuredOutput", () => {
+    const schema = buildToolCallSchema(tools);
+
+    expect(schema).toHaveProperty(
+      "description",
+      expect.stringContaining("Do not invoke listed client tools as native Claude Code tools"),
+    );
+    expect(schema).toHaveProperty(
+      ["properties", "action", "description"],
+      expect.stringContaining("tool_call"),
+    );
+    expect(schema).toHaveProperty(
+      ["properties", "toolCalls", "description"],
+      expect.stringContaining("Do not call these tools as native"),
+    );
+    expect(schema).toHaveProperty(
+      ["properties", "toolCalls", "anyOf", 0, "items", "properties", "toolName", "description"],
+      expect.stringContaining("getWeather"),
+    );
+  });
+
+  it("preserves the legacy string answer shape when no user schema is supplied", () => {
+    const schema = buildToolCallSchema(tools);
+
+    expect(schema).not.toHaveProperty("$defs");
+    expect(schema).toHaveProperty("properties.answer.anyOf", [
+      { type: "string" },
+      { type: "null" },
+    ]);
+  });
+
+  it("namespaces a user schema and references it from answer", () => {
+    const userSchema = {
+      type: "object",
+      properties: { translated: { type: "string" } },
+    };
+    const schema = buildToolCallSchema(tools, userSchema);
+
+    expect(schema).toHaveProperty("properties.answer.anyOf", [
+      { $ref: "#/$defs/__qgrid_user_output" },
+      { type: "null" },
+    ]);
+    expect(schema).toHaveProperty(userPath(), userSchema);
+  });
+
+  it("rebases root and nested local refs into the user-schema namespace", () => {
+    const schema = buildToolCallSchema(tools, {
+      type: "object",
+      properties: {
+        self: { $ref: "#" },
+        item: { $ref: "#/$defs/Item" },
+      },
+      $defs: {
+        Item: {
+          type: "object",
+          properties: { parent: { $ref: "#" } },
+        },
+      },
+    });
+
+    expect(schema).toHaveProperty(
+      userPath("properties", "self", "$ref"),
+      "#/$defs/__qgrid_user_output",
+    );
+    expect(schema).toHaveProperty(
+      userPath("properties", "item", "$ref"),
+      "#/$defs/__qgrid_user_output/$defs/Item",
+    );
+    expect(schema).toHaveProperty(
+      userPath("$defs", "Item", "properties", "parent", "$ref"),
+      "#/$defs/__qgrid_user_output",
+    );
+  });
+
+  it("only traverses schema positions and preserves property names and literal data", () => {
+    const literal = {
+      $id: "literal-id",
+      $ref: "https://example.com/literal.json",
+      $dynamicRef: "#literal",
+    };
+    const schema = buildToolCallSchema(tools, {
+      type: "object",
+      properties: {
+        $id: { type: "string" },
+        $ref: { type: "string" },
+        payload: {
+          type: "object",
+          const: literal,
+          enum: [literal],
+          default: literal,
+          examples: [literal],
+        },
+      },
+      patternProperties: {
+        "^\\$dynamicRef$": { type: "string" },
+      },
+      dependentSchemas: {
+        $dynamicRef: {
+          type: "object",
+          properties: { value: { $ref: "#" } },
+        },
+      },
+    });
+
+    expect(schema).toHaveProperty(userPath("properties", "$id"), { type: "string" });
+    expect(schema).toHaveProperty(userPath("properties", "$ref"), { type: "string" });
+    expect(schema).toHaveProperty(userPath("patternProperties", "^\\$dynamicRef$"), {
+      type: "string",
+    });
+    expect(schema).toHaveProperty(userPath("properties", "payload", "const"), literal);
+    expect(schema).toHaveProperty(userPath("properties", "payload", "enum"), [literal]);
+    expect(schema).toHaveProperty(userPath("properties", "payload", "default"), literal);
+    expect(schema).toHaveProperty(userPath("properties", "payload", "examples"), [literal]);
+    expect(schema).toHaveProperty(
+      userPath("dependentSchemas", "$dynamicRef", "properties", "value", "$ref"),
+      "#/$defs/__qgrid_user_output",
+    );
+  });
+
+  it("rebases draft-07 additionalItems and schema dependencies while preserving property dependencies", () => {
+    const schema = buildToolCallSchema(tools, {
+      type: "array",
+      items: [{ type: "string" }],
+      additionalItems: { $ref: "#/$defs/Extra" },
+      dependencies: {
+        triggerSchema: {
+          type: "object",
+          properties: { extra: { $ref: "#/$defs/Extra" } },
+        },
+        triggerProperties: ["first", "$ref", "$id"],
+      },
+      $defs: {
+        Extra: { type: "string" },
+      },
+    });
+
+    expect(schema).toHaveProperty(
+      userPath("additionalItems", "$ref"),
+      "#/$defs/__qgrid_user_output/$defs/Extra",
+    );
+    expect(schema).toHaveProperty(
+      userPath("dependencies", "triggerSchema", "properties", "extra", "$ref"),
+      "#/$defs/__qgrid_user_output/$defs/Extra",
+    );
+    expect(schema).toHaveProperty(
+      userPath("dependencies", "triggerProperties"),
+      ["first", "$ref", "$id"],
+    );
+  });
+
+  it.each([
+    [{ $ref: "https://example.com/schema.json" }, "$.$ref"],
+    [{ $ref: "#named-anchor" }, "$.$ref"],
+    [{ $id: "urn:example:schema", type: "object" }, "$.$id"],
+    [{ $dynamicRef: "#node" }, "$.$dynamicRef"],
+    [{ $recursiveRef: "#" }, "$.$recursiveRef"],
+    [{ $recursiveAnchor: true }, "$.$recursiveAnchor"],
+  ])("rejects unsupported reference features with their path", (answerSchema, path) => {
+    expect(() => buildToolCallSchema(tools, answerSchema)).toThrowError(
+      expect.objectContaining({ path }),
+    );
+  });
+});

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

@@ -0,0 +1,176 @@
+import { type JsonValue } from "../../codex-protocol/serde_json/JsonValue";
+import { type QgridTool } from "./qgrid.types";
+
+const USER_OUTPUT_DEFINITION = "__qgrid_user_output";
+const USER_OUTPUT_REF = `#/$defs/${USER_OUTPUT_DEFINITION}`;
+
+export class ToolSchemaCompositionError extends Error {
+  constructor(
+    message: string,
+    public path: string,
+  ) {
+    super(`tool schema composition: ${message} (at ${path})`);
+    this.name = "ToolSchemaCompositionError";
+  }
+}
+
+export function buildToolCallSchema(tools: QgridTool[], answerSchema?: JsonValue): JsonValue {
+  const toolDescriptions = tools
+    .map((tool) => {
+      const schema = JSON.stringify(tool.inputSchema);
+      return `- ${tool.name}: ${tool.description ?? ""}\n  inputSchema: ${schema}`;
+    })
+    .join("\n");
+
+  const normalizedAnswerSchema =
+    answerSchema === undefined ? undefined : rebaseUserOutputSchema(answerSchema);
+
+  return {
+    type: "object",
+    description:
+      "Use this schema only through StructuredOutput. Do not invoke listed client tools as native Claude Code tools. To request client-side tool execution, set action to tool_call and include toolCalls. Use action answer only when no further client tool result is needed.",
+    properties: {
+      action: {
+        type: "string",
+        enum: ["answer", "tool_call"],
+        description:
+          "Use tool_call to request client-side tool execution through this structured output. Use answer only for a final answer.",
+      },
+      answer: {
+        anyOf: [
+          normalizedAnswerSchema === undefined ? { type: "string" } : { $ref: USER_OUTPUT_REF },
+          { type: "null" },
+        ],
+      },
+      toolCalls: {
+        description:
+          "Client-side tool calls requested through structured output. Do not call these tools as native Claude Code tools.",
+        anyOf: [
+          {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                toolName: {
+                  type: "string",
+                  enum: tools.map((tool) => tool.name),
+                  description: `Client-side tool name to request through structured output. Do not call this as a native Claude Code tool.\n${toolDescriptions}`,
+                },
+                args: {
+                  type: "string",
+                  description: "Tool arguments as a JSON string for the client-side tool.",
+                },
+              },
+              required: ["toolName", "args"],
+              additionalProperties: false,
+            },
+          },
+          { type: "null" },
+        ],
+      },
+    },
+    required: ["action", "answer", "toolCalls"],
+    additionalProperties: false,
+    ...(normalizedAnswerSchema === undefined
+      ? {}
+      : {
+          $defs: {
+            [USER_OUTPUT_DEFINITION]: normalizedAnswerSchema,
+          },
+        }),
+  };
+}
+
+function rebaseUserOutputSchema(schema: JsonValue): JsonValue {
+  return rewriteSchemaNode(schema, "$");
+}
+
+const SCHEMA_MAP_KEYWORDS = new Set([
+  "$defs",
+  "definitions",
+  "dependentSchemas",
+  "patternProperties",
+  "properties",
+]);
+const SCHEMA_ARRAY_KEYWORDS = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+const SCHEMA_KEYWORDS = new Set([
+  "additionalItems",
+  "additionalProperties",
+  "contains",
+  "contentSchema",
+  "else",
+  "if",
+  "items",
+  "not",
+  "propertyNames",
+  "then",
+  "unevaluatedItems",
+  "unevaluatedProperties",
+]);
+
+function rewriteSchemaNode(value: JsonValue, path: string): JsonValue {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
+
+  const source = value as Record<string, JsonValue>;
+  const result: Record<string, JsonValue> = { ...source };
+
+  for (const unsupportedKeyword of ["$id", "$dynamicRef", "$recursiveRef", "$recursiveAnchor"]) {
+    if (unsupportedKeyword in source) {
+      throw new ToolSchemaCompositionError(
+        `${unsupportedKeyword} is not supported`,
+        `${path}.${unsupportedKeyword}`,
+      );
+    }
+  }
+
+  if ("$ref" in source) {
+    const ref = source.$ref;
+    if (typeof ref !== "string" || (ref !== "#" && !ref.startsWith("#/"))) {
+      throw new ToolSchemaCompositionError(
+        "only root-relative JSON Pointer $ref values are supported",
+        `${path}.$ref`,
+      );
+    }
+    result.$ref = `${USER_OUTPUT_REF}${ref.slice(1)}`;
+  }
+
+  for (const [keyword, child] of Object.entries(source)) {
+    const keywordPath = `${path}.${keyword}`;
+
+    if (SCHEMA_MAP_KEYWORDS.has(keyword) && isJsonObject(child)) {
+      result[keyword] = Object.fromEntries(
+        Object.entries(child).map(([name, schema]) => [
+          name,
+          rewriteSchemaNode(schema, `${keywordPath}.${name}`),
+        ]),
+      ) as JsonValue;
+    } else if (keyword === "dependencies" && isJsonObject(child)) {
+      result[keyword] = Object.fromEntries(
+        Object.entries(child).map(([name, dependency]) => [
+          name,
+          Array.isArray(dependency)
+            ? dependency
+            : rewriteSchemaNode(dependency, `${keywordPath}.${name}`),
+        ]),
+      ) as JsonValue;
+    } else if (SCHEMA_ARRAY_KEYWORDS.has(keyword) && Array.isArray(child)) {
+      result[keyword] = child.map((schema, index) =>
+        rewriteSchemaNode(schema, `${keywordPath}[${index}]`),
+      ) as JsonValue;
+    } else if (SCHEMA_KEYWORDS.has(keyword)) {
+      if (keyword === "items" && Array.isArray(child)) {
+        result[keyword] = child.map((schema, index) =>
+          rewriteSchemaNode(schema, `${keywordPath}[${index}]`),
+        ) as JsonValue;
+      } else {
+        result[keyword] = rewriteSchemaNode(child, keywordPath);
+      }
+    }
+  }
+
+  return result as JsonValue;
+}
+
+function isJsonObject(value: JsonValue): value is Record<string, JsonValue> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}