@cartanova/qgrid-cli 2.5.3 → 2.5.5

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,177 @@
+/**
+ * tool envelope + 사용자 output 스키마 합성 (요청 방향). 응답 해석은 tool-emulation.ts.
+ *
+ * tools 가 있어도 최종 answer 가 사용자 스키마로 강제되게 하려고 envelope 의 answer 브랜치에
+ * 사용자 스키마를 심는다. 통째로 중첩할 수 없는 이유는 `$ref` 가 문서 절대 경로이기 때문 —
+ * `#` 은 "이 조각의 루트"가 아니라 "최종 문서의 루트"라, 그대로 넣으면 포인터가 envelope 을
+ * 가리켜 조용히 엉뚱한 걸 검증하게 된다. 그래서 예약 이름 아래로 옮기고 로컬 포인터를 재작성한다.
+ *
+ * 배경·실측·예시·거부 목록은 스킬 문서를 볼 것:
+ *   packages/cli/skills/qgrid/references/tool-calling-and-multiturn.md
+ *   → "Composing Tools With A User Output Schema"
+ */
+
+import { type JsonValue } from "../../codex-protocol/serde_json/JsonValue";
+import {
+  SCHEMA_ARRAY_KEYWORDS,
+  SCHEMA_DEPENDENCIES_KEYWORD,
+  SCHEMA_MAP_KEYWORDS,
+  SCHEMA_SINGLE_KEYWORDS,
+  UNSUPPORTED_REFERENCE_KEYWORDS,
+} from "../../utils/providers/common/json-schema-keywords";
+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 MAP_KEYWORDS = new Set<string>(SCHEMA_MAP_KEYWORDS);
+const ARRAY_KEYWORDS = new Set<string>(SCHEMA_ARRAY_KEYWORDS);
+const SINGLE_KEYWORDS = new Set<string>(SCHEMA_SINGLE_KEYWORDS);
+
+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 UNSUPPORTED_REFERENCE_KEYWORDS) {
+    if (Object.hasOwn(source, unsupportedKeyword)) {
+      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 (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 === SCHEMA_DEPENDENCIES_KEYWORD && 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 (ARRAY_KEYWORDS.has(keyword) && Array.isArray(child)) {
+      result[keyword] = child.map((schema, index) =>
+        rewriteSchemaNode(schema, `${keywordPath}[${index}]`),
+      ) as JsonValue;
+    } else if (SINGLE_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);
+}