@cartanova/qgrid-cli 2.5.3 → 2.5.5

package/bundle/src/utils/providers/common/schema-validation.test.ts

@@ -0,0 +1,284 @@
+import { Buffer } from "node:buffer";
+
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  ANTHROPIC_SCHEMA_ARGV_MAX_UTF8_BYTES,
+  CALLER_SCHEMA_LIMITS,
+  CallerSchemaValidationError,
+  parseAndValidateCallerSchemas,
+  serializeAndValidateDispatchSchema,
+} from "./schema-validation";
+
+// jsonSchema 단독 경로용 테스트 헬퍼 — 프로덕션 진입점은 parseAndValidateCallerSchemas 하나다.
+const parseCallerOutputSchema = (jsonSchema: string) =>
+  parseAndValidateCallerSchemas({ jsonSchema });
+
+function schemaWithArrayDepth(arrayDepth: number): string {
+  return `{"type":"object","x":${"[".repeat(arrayDepth)}0${"]".repeat(arrayDepth)}}`;
+}
+
+function schemaWithNodeCount(nodeCount: number): string {
+  // root object + "object" string + enum array account for the other three nodes.
+  const enumLength = nodeCount - 3;
+  return `{"type":"object","enum":[${Array.from({ length: enumLength }, () => "0").join(",")}]}`;
+}
+
+function schemaWithUtf8Bytes(byteLength: number): string {
+  const prefix = '{"type":"object","description":"';
+  const suffix = '"}';
+  const paddingLength =
+    byteLength - Buffer.byteLength(prefix, "utf8") - Buffer.byteLength(suffix, "utf8");
+  if (paddingLength < 0) throw new Error("requested schema byte length is too small");
+  return `${prefix}${"x".repeat(paddingLength)}${suffix}`;
+}
+
+describe("caller schema validation", () => {
+  it("accepts schemas exactly at each complexity boundary", () => {
+    expect(() =>
+      parseCallerOutputSchema(
+        schemaWithUtf8Bytes(CALLER_SCHEMA_LIMITS.maxUtf8Bytes),
+      ),
+    ).not.toThrow();
+    expect(() =>
+      parseCallerOutputSchema(
+        schemaWithNodeCount(CALLER_SCHEMA_LIMITS.maxNodes),
+      ),
+    ).not.toThrow();
+    // Root is depth 0 and the primitive inside N nested arrays is depth N + 1.
+    expect(() =>
+      parseCallerOutputSchema(
+        schemaWithArrayDepth(CALLER_SCHEMA_LIMITS.maxDepth - 1),
+      ),
+    ).not.toThrow();
+  });
+
+  it.each([
+    [
+      "UTF-8 bytes",
+      () => schemaWithUtf8Bytes(CALLER_SCHEMA_LIMITS.maxUtf8Bytes + 1),
+      "UTF-8 byte limit",
+    ],
+    [
+      "nodes",
+      () => schemaWithNodeCount(CALLER_SCHEMA_LIMITS.maxNodes + 1),
+      "node limit",
+    ],
+    [
+      "depth",
+      () => schemaWithArrayDepth(CALLER_SCHEMA_LIMITS.maxDepth),
+      "depth limit",
+    ],
+  ])("rejects schemas above the %s budget", (_label, makeSchema, message) => {
+    expect(() => parseCallerOutputSchema(makeSchema())).toThrow(
+      CallerSchemaValidationError,
+    );
+    expect(() => parseCallerOutputSchema(makeSchema())).toThrow(message);
+  });
+
+  it("measures the raw schema in UTF-8 bytes, not JavaScript code units", () => {
+    const prefix = '{"type":"object","description":"';
+    const suffix = '"}';
+    const remainingBytes =
+      CALLER_SCHEMA_LIMITS.maxUtf8Bytes -
+      Buffer.byteLength(prefix, "utf8") -
+      Buffer.byteLength(suffix, "utf8");
+    const schema = `${prefix}${"가".repeat(Math.floor(remainingBytes / 3) + 1)}${suffix}`;
+
+    expect(schema.length).toBeLessThan(CALLER_SCHEMA_LIMITS.maxUtf8Bytes);
+    expect(() => parseCallerOutputSchema(schema)).toThrow(/UTF-8 byte limit/);
+  });
+
+  it("enforces the final Anthropic argv limit without constraining OpenAI to it", () => {
+    const atLimit = JSON.parse(
+      schemaWithUtf8Bytes(ANTHROPIC_SCHEMA_ARGV_MAX_UTF8_BYTES),
+    );
+    const aboveLimit = JSON.parse(
+      schemaWithUtf8Bytes(ANTHROPIC_SCHEMA_ARGV_MAX_UTF8_BYTES + 1),
+    );
+
+    expect(() => serializeAndValidateDispatchSchema(atLimit, "anthropic")).not.toThrow();
+    expect(() => serializeAndValidateDispatchSchema(aboveLimit, "anthropic")).toThrow(
+      "Anthropic dispatch schema exceeds argv UTF-8 byte limit",
+    );
+    expect(() => serializeAndValidateDispatchSchema(aboveLimit, "openai")).not.toThrow();
+  });
+
+  it("enforces the aggregate limit again after schema composition", () => {
+    const overLimit = {
+      type: "object",
+      description: "x".repeat(CALLER_SCHEMA_LIMITS.maxUtf8Bytes),
+    } as const;
+
+    expect(() => serializeAndValidateDispatchSchema(overLimit, "openai")).toThrow(
+      "dispatch schema exceeds UTF-8 byte limit",
+    );
+  });
+
+  it("rejects non-serializable direct dispatch schemas", () => {
+    expect(() => serializeAndValidateDispatchSchema(() => {}, "anthropic")).toThrow(
+      "dispatch schema must be JSON-serializable",
+    );
+  });
+
+  it("applies the same depth guard to tools-only input schemas", () => {
+    const inputSchema = JSON.parse(
+      schemaWithArrayDepth(CALLER_SCHEMA_LIMITS.maxDepth),
+    ) as unknown;
+
+    expect(() =>
+      parseAndValidateCallerSchemas({
+        tools: [{ name: "deepTool", inputSchema }],
+      }),
+    ).toThrow(CallerSchemaValidationError);
+    expect(() =>
+      parseAndValidateCallerSchemas({
+        tools: [{ name: "deepTool", inputSchema }],
+      }),
+    ).toThrow("tools[0].inputSchema exceeds depth limit");
+  });
+
+  it("aggregates node and byte budgets across output and tool schemas", () => {
+    const halfNodeSchema = JSON.parse(
+      schemaWithNodeCount(Math.floor(CALLER_SCHEMA_LIMITS.maxNodes / 2) + 1),
+    ) as unknown;
+    expect(() =>
+      parseAndValidateCallerSchemas({
+        tools: [
+          { name: "first", inputSchema: halfNodeSchema },
+          { name: "second", inputSchema: halfNodeSchema },
+        ],
+      }),
+    ).toThrow("caller schemas exceed aggregate node limit");
+
+    const halfByteSchema = JSON.parse(
+      schemaWithUtf8Bytes(Math.floor(CALLER_SCHEMA_LIMITS.maxUtf8Bytes / 2) + 1),
+    ) as unknown;
+    expect(() =>
+      parseAndValidateCallerSchemas({
+        tools: [
+          { name: "first", inputSchema: halfByteSchema },
+          { name: "second", inputSchema: halfByteSchema },
+        ],
+      }),
+    ).toThrow("caller schemas exceed aggregate UTF-8 byte limit");
+  });
+
+  it("counts a tool name twice before materializing the composed schema", () => {
+    const name = "x".repeat(Math.floor(CALLER_SCHEMA_LIMITS.maxUtf8Bytes / 2));
+    const stringify = vi.spyOn(JSON, "stringify");
+
+    expect(Buffer.byteLength(name, "utf8")).toBeLessThan(CALLER_SCHEMA_LIMITS.maxUtf8Bytes);
+    expect(() =>
+      parseAndValidateCallerSchemas({
+        tools: [{ name, inputSchema: { type: "object" } }],
+      }),
+    ).toThrow("tools[0].name exceeds UTF-8 byte limit");
+    expect(stringify).not.toHaveBeenCalled();
+  });
+
+  it("counts JSON escaping in tool descriptions before schema composition", () => {
+    const description = '"'.repeat(
+      Math.floor(CALLER_SCHEMA_LIMITS.maxUtf8Bytes / 2),
+    );
+    const stringify = vi.spyOn(JSON, "stringify");
+
+    expect(Buffer.byteLength(description, "utf8")).toBeLessThan(
+      CALLER_SCHEMA_LIMITS.maxUtf8Bytes,
+    );
+    expect(() =>
+      parseAndValidateCallerSchemas({
+        tools: [{ name: "escaped", description, inputSchema: { type: "object" } }],
+      }),
+    ).toThrow("tools[0].description exceeds UTF-8 byte limit");
+    expect(stringify).not.toHaveBeenCalled();
+  });
+
+  it("counts nested escaping when an input schema is embedded in the tool description", () => {
+    const escapedValue = '"'.repeat(
+      Math.floor(CALLER_SCHEMA_LIMITS.maxUtf8Bytes / 4),
+    );
+    const inputSchema = { type: "object", description: escapedValue };
+    const serializedInputSchema = JSON.stringify(inputSchema);
+
+    expect(Buffer.byteLength(serializedInputSchema, "utf8")).toBeLessThan(
+      CALLER_SCHEMA_LIMITS.maxUtf8Bytes,
+    );
+    expect(() =>
+      parseAndValidateCallerSchemas({
+        tools: [{ name: "escapedInput", inputSchema }],
+      }),
+    ).toThrow("tools[0].inputSchema exceeds UTF-8 byte limit");
+  });
+
+  it("counts per-tool composition framing even when tool metadata is empty", () => {
+    const tools = Array.from({ length: CALLER_SCHEMA_LIMITS.maxNodes }, () => ({
+      name: "",
+      inputSchema: {},
+    }));
+
+    expect(() => parseAndValidateCallerSchemas({ tools })).toThrow(
+      "caller schemas exceed aggregate UTF-8 byte limit",
+    );
+  });
+
+  it("rejects an oversized tool schema before materializing its full JSON serialization", () => {
+    const stringify = vi.spyOn(JSON, "stringify");
+    let thrown: unknown;
+
+    try {
+      parseAndValidateCallerSchemas({
+        tools: [
+          {
+            name: "oversized",
+            inputSchema: {
+              type: "object",
+              description: "x".repeat(CALLER_SCHEMA_LIMITS.maxUtf8Bytes + 1),
+            },
+          },
+        ],
+      });
+    } catch (error) {
+      thrown = error;
+    }
+
+    expect(thrown).toBeInstanceOf(CallerSchemaValidationError);
+    expect((thrown as Error).message).toContain("UTF-8 byte limit");
+    expect(stringify).not.toHaveBeenCalled();
+  });
+
+  it("stops a wide object at the node limit before reading later property values", () => {
+    const properties: Record<string, unknown> = {};
+    // inputSchema root, its type value, and this properties object consume three nodes.
+    for (let index = 0; index < CALLER_SCHEMA_LIMITS.maxNodes - 3; index += 1) {
+      properties[`field${index}`] = 0;
+    }
+    const readPastLimit = vi.fn(() => {
+      throw new Error("value past node limit was read");
+    });
+    Object.defineProperty(properties, "pastLimit", {
+      enumerable: true,
+      get: readPastLimit,
+    });
+
+    expect(() =>
+      parseAndValidateCallerSchemas({
+        tools: [{ name: "wide", inputSchema: { type: "object", properties } }],
+      }),
+    ).toThrow("tools[0].inputSchema exceeds node limit");
+    expect(readPastLimit).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["malformed JSON", '{"type":"object"', "must contain valid JSON"],
+    ["array JSON root", "[]", 'top-level type must be "object"'],
+    ["primitive JSON root", "true", 'top-level type must be "object"'],
+    ["array output schema", '{"type":"array","items":{"type":"string"}}', 'top-level type must be "object"'],
+    ["missing output type", '{"properties":{}}', 'top-level type must be "object"'],
+  ])("rejects %s with a stable validation error", (_label, schema, message) => {
+    expect(() => parseCallerOutputSchema(schema)).toThrow(
+      CallerSchemaValidationError,
+    );
+    expect(() => parseCallerOutputSchema(schema)).toThrow(message);
+  });
+});

package/bundle/src/utils/providers/common/schema-validation.ts

@@ -0,0 +1,308 @@
+import { Buffer } from "node:buffer";
+
+import { type JsonValue } from "../../../codex-protocol/serde_json/JsonValue";
+
+/**
+ * Caller-provided schemas are serialized, copied, and recursively normalized before dispatch.
+ * Keep these limits comfortably above normal generated schemas while bounding that preprocessing
+ * well below the API's 10 MiB request-body ceiling.
+ */
+export const CALLER_SCHEMA_LIMITS = {
+  maxUtf8Bytes: 512 * 1024,
+  maxNodes: 20_000,
+  maxDepth: 128,
+} as const;
+
+// Linux permits at most 128 KiB (MAX_ARG_STRLEN) for one argv value. qgrid uses a 50% safety
+// margin for every argv-delivered payload — Claude Code --json-schema here and the system-prompt
+// transport (claude-session) both derive from this single constant.
+export const ARGV_SAFE_MAX_UTF8_BYTES = 64 * 1024;
+export const ANTHROPIC_SCHEMA_ARGV_MAX_UTF8_BYTES = ARGV_SAFE_MAX_UTF8_BYTES;
+
+export class CallerSchemaValidationError extends Error {
+  constructor(message: string) {
+    super(`qgrid: ${message}`);
+    this.name = "CallerSchemaValidationError";
+  }
+}
+
+export interface CallerSchemasInput {
+  jsonSchema?: string;
+  tools?: Array<{ name: string; description?: string; inputSchema: unknown }>;
+}
+
+interface ComplexityState {
+  utf8Bytes: number;
+  nodes: number;
+  schemas: number;
+}
+
+export function parseAndValidateCallerSchemas(input: CallerSchemasInput): JsonValue | undefined {
+  const state: ComplexityState = {
+    utf8Bytes: 0,
+    nodes: 0,
+    schemas: 0,
+  };
+  let outputSchema: JsonValue | undefined;
+
+  if (input.jsonSchema !== undefined) {
+    addUtf8Bytes(Buffer.byteLength(input.jsonSchema, "utf8"), "jsonSchema", state);
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(input.jsonSchema);
+    } catch {
+      throw new CallerSchemaValidationError("jsonSchema must contain valid JSON");
+    }
+
+    if (!isRecord(parsed) || parsed.type !== "object") {
+      throw new CallerSchemaValidationError('jsonSchema top-level type must be "object"');
+    }
+
+    addComplexity(parsed, "jsonSchema", state);
+    state.schemas += 1;
+    outputSchema = parsed as JsonValue;
+  }
+
+  for (const [index, tool] of (input.tools ?? []).entries()) {
+    addToolMetadataUtf8Bytes(tool, index, state);
+
+    const path = `tools[${index}].inputSchema`;
+    addComplexity(tool.inputSchema, path, state, true);
+
+    const serialized = stringifyJsonOrThrow(tool.inputSchema, path);
+
+    // buildToolCallSchema embeds this serialization inside another JSON string. Charge the
+    // escaped outer-string representation before that composed description is materialized.
+    addUtf8Bytes(jsonStringContentUtf8ByteUpperBound(serialized), path, state);
+    state.schemas += 1;
+  }
+
+  return outputSchema;
+}
+
+export function serializeAndValidateDispatchSchema(
+  schema: unknown,
+  provider?: string,
+): string | undefined {
+  if (schema === undefined) return undefined;
+
+  const serialized = stringifyJsonOrThrow(schema, "dispatch schema");
+
+  const byteLength = Buffer.byteLength(serialized, "utf8");
+  if (byteLength > CALLER_SCHEMA_LIMITS.maxUtf8Bytes) {
+    throw new CallerSchemaValidationError(
+      `dispatch schema exceeds UTF-8 byte limit of ${CALLER_SCHEMA_LIMITS.maxUtf8Bytes}`,
+    );
+  }
+  if (provider === "anthropic") {
+    assertAnthropicSchemaArgvSize(serialized);
+  }
+
+  return serialized;
+}
+
+export function assertAnthropicSchemaArgvSize(jsonSchema: string): void {
+  if (Buffer.byteLength(jsonSchema, "utf8") > ANTHROPIC_SCHEMA_ARGV_MAX_UTF8_BYTES) {
+    throw new CallerSchemaValidationError(
+      `Anthropic dispatch schema exceeds argv UTF-8 byte limit of ${ANTHROPIC_SCHEMA_ARGV_MAX_UTF8_BYTES}`,
+    );
+  }
+}
+
+function stringifyJsonOrThrow(value: unknown, subject: string): string {
+  let serialized: string | undefined;
+  try {
+    serialized = JSON.stringify(value);
+  } catch {
+    throw new CallerSchemaValidationError(`${subject} must be JSON-serializable`);
+  }
+  if (serialized === undefined) {
+    throw new CallerSchemaValidationError(`${subject} must be JSON-serializable`);
+  }
+  return serialized;
+}
+
+function addUtf8Bytes(byteLength: number, path: string, state: ComplexityState): void {
+  state.utf8Bytes += byteLength;
+  if (state.utf8Bytes > CALLER_SCHEMA_LIMITS.maxUtf8Bytes) {
+    throwLimitError(path, "UTF-8 byte", CALLER_SCHEMA_LIMITS.maxUtf8Bytes, state);
+  }
+}
+
+const TOOL_DESCRIPTION_ENTRY_PREFIX = "- ";
+const TOOL_DESCRIPTION_NAME_SEPARATOR = ": ";
+const TOOL_DESCRIPTION_INPUT_SCHEMA_PREFIX = "\n  inputSchema: ";
+const TOOL_DESCRIPTION_ENTRY_SEPARATOR = "\n";
+
+function addToolMetadataUtf8Bytes(
+  tool: NonNullable<CallerSchemasInput["tools"]>[number],
+  index: number,
+  state: ComplexityState,
+): void {
+  const toolPath = `tools[${index}]`;
+
+  // buildToolCallSchema places every tool name in both the enum and the human-readable tool
+  // description. Count both escaped occurrences, plus the enum's JSON string delimiters.
+  const encodedNameBytes = jsonStringContentUtf8ByteUpperBound(tool.name);
+  addUtf8Bytes(encodedNameBytes * 2 + 2, `${toolPath}.name`, state);
+
+  if (tool.description !== undefined) {
+    addUtf8Bytes(
+      jsonStringContentUtf8ByteUpperBound(tool.description),
+      `${toolPath}.description`,
+      state,
+    );
+  }
+
+  // Per-tool framing also grows with the number of tools even when all caller strings are empty.
+  // Include both the toolDescriptions join separator and the enum comma after the first entry.
+  const framingBytes =
+    jsonStringContentUtf8ByteUpperBound(TOOL_DESCRIPTION_ENTRY_PREFIX) +
+    jsonStringContentUtf8ByteUpperBound(TOOL_DESCRIPTION_NAME_SEPARATOR) +
+    jsonStringContentUtf8ByteUpperBound(TOOL_DESCRIPTION_INPUT_SCHEMA_PREFIX) +
+    (index === 0 ? 0 : jsonStringContentUtf8ByteUpperBound(TOOL_DESCRIPTION_ENTRY_SEPARATOR) + 1);
+  addUtf8Bytes(framingBytes, toolPath, state);
+}
+
+/**
+ * Returns a conservative UTF-8 byte count for a string when it becomes JSON string content,
+ * without allocating the escaped representation. JSON.stringify uses short two-byte escapes for
+ * five control characters; counting every control character as a six-byte `\u00XX` escape keeps
+ * this an upper bound while avoiding a second large temporary string.
+ */
+function jsonStringContentUtf8ByteUpperBound(value: string): number {
+  let bytes = 0;
+
+  for (let index = 0; index < value.length; index += 1) {
+    const codeUnit = value.charCodeAt(index);
+
+    if (codeUnit === 0x22 || codeUnit === 0x5c) {
+      bytes += 2;
+      continue;
+    }
+    if (codeUnit <= 0x1f) {
+      bytes += 6;
+      continue;
+    }
+    if (codeUnit >= 0xd800 && codeUnit <= 0xdbff) {
+      const nextCodeUnit = value.charCodeAt(index + 1);
+      if (nextCodeUnit >= 0xdc00 && nextCodeUnit <= 0xdfff) {
+        bytes += 4;
+        index += 1;
+      } else {
+        // Well-formed JSON.stringify escapes lone surrogates as `\uXXXX`.
+        bytes += 6;
+      }
+      continue;
+    }
+    if (codeUnit >= 0xdc00 && codeUnit <= 0xdfff) {
+      bytes += 6;
+      continue;
+    }
+
+    bytes += codeUnit <= 0x7f ? 1 : codeUnit <= 0x7ff ? 2 : 3;
+  }
+
+  return bytes;
+}
+
+function addComplexity(
+  root: unknown,
+  path: string,
+  state: ComplexityState,
+  precheckUtf8Bytes = false,
+): void {
+  const rawUtf8Bytes = { value: 0 };
+  if (precheckUtf8Bytes && typeof root === "string") {
+    addRawUtf8LowerBound(root, path, state, rawUtf8Bytes);
+  }
+  addNode(path, state);
+  if (root === null || typeof root !== "object") return;
+
+  const stack: Array<{ value: Record<string, unknown> | unknown[]; depth: number }> = [
+    { value: root as Record<string, unknown> | unknown[], depth: 0 },
+  ];
+
+  while (stack.length > 0) {
+    const current = stack.pop()!;
+    if (Array.isArray(current.value)) {
+      for (let index = 0; index < current.value.length; index += 1) {
+        const depth = current.depth + 1;
+        assertDepthWithinLimit(depth, path);
+        addNode(path, state);
+
+        const child = current.value[index];
+        if (precheckUtf8Bytes && typeof child === "string") {
+          addRawUtf8LowerBound(child, path, state, rawUtf8Bytes);
+        }
+        if (child !== null && typeof child === "object") {
+          stack.push({ value: child as Record<string, unknown> | unknown[], depth });
+        }
+      }
+      continue;
+    }
+
+    for (const key in current.value) {
+      if (!Object.hasOwn(current.value, key)) continue;
+      if (precheckUtf8Bytes) {
+        addRawUtf8LowerBound(key, path, state, rawUtf8Bytes);
+      }
+      const depth = current.depth + 1;
+      assertDepthWithinLimit(depth, path);
+      addNode(path, state);
+
+      const child = current.value[key];
+      if (precheckUtf8Bytes && typeof child === "string") {
+        addRawUtf8LowerBound(child, path, state, rawUtf8Bytes);
+      }
+      if (child !== null && typeof child === "object") {
+        stack.push({ value: child as Record<string, unknown> | unknown[], depth });
+      }
+    }
+  }
+}
+
+function addRawUtf8LowerBound(
+  value: string,
+  path: string,
+  state: ComplexityState,
+  rawUtf8Bytes: { value: number },
+): void {
+  rawUtf8Bytes.value += Buffer.byteLength(value, "utf8");
+  if (state.utf8Bytes + rawUtf8Bytes.value > CALLER_SCHEMA_LIMITS.maxUtf8Bytes) {
+    throwLimitError(path, "UTF-8 byte", CALLER_SCHEMA_LIMITS.maxUtf8Bytes, state);
+  }
+}
+
+function assertDepthWithinLimit(depth: number, path: string): void {
+  if (depth > CALLER_SCHEMA_LIMITS.maxDepth) {
+    throw new CallerSchemaValidationError(
+      `${path} exceeds depth limit of ${CALLER_SCHEMA_LIMITS.maxDepth}`,
+    );
+  }
+}
+
+function addNode(path: string, state: ComplexityState): void {
+  state.nodes += 1;
+  if (state.nodes > CALLER_SCHEMA_LIMITS.maxNodes) {
+    throwLimitError(path, "node", CALLER_SCHEMA_LIMITS.maxNodes, state);
+  }
+}
+
+function throwLimitError(
+  path: string,
+  kind: "UTF-8 byte" | "node",
+  limit: number,
+  state: ComplexityState,
+): never {
+  throw new CallerSchemaValidationError(
+    state.schemas === 0
+      ? `${path} exceeds ${kind} limit of ${limit}`
+      : `caller schemas exceed aggregate ${kind} limit of ${limit}`,
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}