Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

12.1 KB
Raw Blame
/**
 * A minimal JSON Schema reader for TOOL schemas.
 *
 * Scope is deliberate, and recorded in this session's `decisions.md` (ruling 1):
 * the keywords a Claude Code tool `input_schema` actually uses — `type`,
 * `properties`, `required`, `enum`, `items`, `default` — and nothing else. It is
 * not a general-purpose validator and must not grow into one. The trigger to
 * replace it with a real library (`ajv`) is a tool schema in the wild that it
 * mis-validates; until then a published CLI with a `--compile` binary target
 * (`packages/cli/package.json` `build:binary`) carries no new runtime dependency
 * for this.
 *
 * The one rule that matters more than any other lives in {@link missingRequired}:
 * **presence is key presence, never truthiness.** The hand-written filter this
 * replaces tested `parsedArgs[param] === ""` and so declared a legitimately empty
 * string missing. A live `[email protected]` turn emitted
 * `Edit{…,"new_string":""}` — a deletion, the whole point of the call — and
 * claudish rejected it as "missing required parameters: new_string". The file was
 * left unchanged and the model was told its own correct call was malformed. See
 * `test-fixtures/sse-responses/grok-4.6-openai-edit-empty-new-string.sse`.
 */

/** The slice of JSON Schema this module reads. Anything else is ignored. */
export interface JsonSchemaNode {
  type?: string | string[];
  properties?: Record<string, JsonSchemaNode | undefined>;
  required?: string[];
  enum?: unknown[];
  items?: JsonSchemaNode;
  default?: unknown;
  [key: string]: unknown;
}

/**
 * Which of the schema's `required` keys are genuinely absent from `args`?
 *
 * Present means **the key exists and its value is neither `undefined` nor
 * `null`**. `""`, `0`, `false`, `[]` and `{}` are all present values a model may
 * legitimately mean: an empty replacement string, a zero offset, a disabled flag,
 * an empty list.
 *
 * `null` counts as absent rather than present because JSON's `null` is how a
 * model spells "I have no value for this", and no Claude Code tool declares a
 * nullable required parameter.
 */
export function missingRequired(
  schema: JsonSchemaNode | undefined,
  args: Record<string, unknown> | undefined
): string[] {
  const required = schema?.required;
  if (!Array.isArray(required) || required.length === 0) return [];
  const supplied = args ?? {};
  return required.filter((key) => {
    if (typeof key !== "string") return false;
    if (!Object.hasOwn(supplied, key)) return true;
    const value = supplied[key];
    return value === undefined || value === null;
  });
}

/** Is this key absent by the same rule {@link missingRequired} uses? */
function isAbsent(args: Record<string, unknown>, key: string): boolean {
  if (!Object.hasOwn(args, key)) return true;
  const value = args[key];
  return value === undefined || value === null;
}

/** The declared type(s) of one property, normalized to a list. */
function declaredTypes(node: JsonSchemaNode | undefined): string[] {
  if (!node) return [];
  const t = node.type;
  if (typeof t === "string") return [t];
  if (Array.isArray(t)) return t.filter((x): x is string => typeof x === "string");
  // No `type`, but an `enum` — the members' own kinds are the declaration.
  // That is the ONLY thing `enum` is read for here. A value is never snapped to
  // a near-matching member: picking "all" for a model that wrote "All" is
  // choosing a value the model did not write, which is the fabrication this
  // module exists to have removed.
  if (Array.isArray(node.enum) && node.enum.length > 0) {
    const kinds = new Set<string>();
    for (const member of node.enum) {
      if (member === null || member === undefined) continue;
      if (Array.isArray(member)) kinds.add("array");
      else if (typeof member === "object") kinds.add("object");
      else if (typeof member === "number")
        kinds.add(Number.isInteger(member) ? "integer" : "number");
      else if (typeof member === "boolean") kinds.add("boolean");
      else if (typeof member === "string") kinds.add("string");
    }
    return [...kinds];
  }
  return [];
}

/**
 * A number literal spelled out in full — never `parseInt`, which reads `"3abc"`
 * as `3` and would hand a tool an argument the model did not write.
 */
const FULL_NUMBER = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;

/** Coerce one value to one declared type, or return `undefined` on failure. */
function coerceOne(value: unknown, type: string, node: JsonSchemaNode | undefined): unknown {
  switch (type) {
    case "string":
      return typeof value === "string"
        ? value
        : typeof value === "number" || typeof value === "boolean"
          ? String(value)
          : undefined;
    case "number":
    case "integer": {
      if (typeof value === "number") {
        return type === "integer" && !Number.isInteger(value) ? undefined : value;
      }
      if (typeof value !== "string" || !FULL_NUMBER.test(value.trim())) return undefined;
      const n = Number(value.trim());
      if (!Number.isFinite(n)) return undefined;
      return type === "integer" && !Number.isInteger(n) ? undefined : n;
    }
    case "boolean": {
      if (typeof value === "boolean") return value;
      if (typeof value !== "string") return undefined;
      const s = value.trim().toLowerCase();
      return s === "true" ? true : s === "false" ? false : undefined;
    }
    case "array": {
      const arr = Array.isArray(value) ? value : parseJsonOfKind(value, "array");
      if (!Array.isArray(arr)) return undefined;
      const items = node?.items;
      if (!items) return arr;
      return arr.map((el) => {
        const target = declaredTypes(items);
        for (const t of target) {
          const c = coerceOne(el, t, items);
          if (c !== undefined) return c;
        }
        return el;
      });
    }
    case "object":
      return value && typeof value === "object" && !Array.isArray(value)
        ? value
        : parseJsonOfKind(value, "object");
    default:
      return undefined;
  }
}

/** JSON-parse a string and keep it only if it decoded to the expected kind. */
function parseJsonOfKind(value: unknown, kind: "array" | "object"): unknown {
  if (typeof value !== "string") return undefined;
  try {
    const parsed = JSON.parse(value);
    if (kind === "array") return Array.isArray(parsed) ? parsed : undefined;
    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
  } catch {
    return undefined;
  }
}

/**
 * Give each supplied argument the type its schema declares.
 *
 * Needed because the `<function=NAME><parameter=P>` envelope has no types at
 * all — every value arrives as a string, so a `number` parameter reaches the
 * tool as `"5"` and a `boolean` as `"true"`.
 *
 * **A failed coercion keeps the original value.** It is never dropped and never
 * replaced by a guess: the harness re-validates the call on arrival, so a wrong
 * type is visible to the user while a missing key is not. Undeclared keys are
 * left exactly as they came.
 */
export function coerceToSchema(
  schema: JsonSchemaNode | undefined,
  args: Record<string, unknown>
): { args: Record<string, unknown>; coerced: string[] } {
  const properties = schema?.properties;
  if (!properties) return { args, coerced: [] };

  const out: Record<string, unknown> = { ...args };
  const coerced: string[] = [];
  for (const [key, value] of Object.entries(args)) {
    const node = properties[key];
    if (!node || value === undefined || value === null) continue;
    const types = declaredTypes(node);
    if (types.length === 0) continue;
    if (types.some((t) => matchesType(value, t))) continue;
    for (const t of types) {
      const c = coerceOne(value, t, node);
      if (c !== undefined) {
        out[key] = c;
        coerced.push(key);
        break;
      }
    }
  }
  return { args: coerced.length > 0 ? out : args, coerced };
}

/** Does this value already satisfy the declared type? Then leave it alone. */
function matchesType(value: unknown, type: string): boolean {
  switch (type) {
    case "string":
      return typeof value === "string";
    case "number":
      return typeof value === "number";
    case "integer":
      return typeof value === "number" && Number.isInteger(value);
    case "boolean":
      return typeof value === "boolean";
    case "array":
      return Array.isArray(value);
    case "object":
      return !!value && typeof value === "object" && !Array.isArray(value);
    case "null":
      return value === null;
    default:
      return false;
  }
}

/**
 * Fill absent REQUIRED arguments from the schema's own `default`.
 *
 * The value comes from the client's declaration of its own tool, so this is the
 * schema speaking, not us guessing. This is how `ToolSearch.max_results = 5`
 * survives the deletion of the hardcoded per-tool inference: tool-agnostically,
 * as a `default` read.
 *
 * Scoped to `required` keys ON PURPOSE. An optional parameter with a default
 * needs no help — Claude Code applies its own when it re-validates — and filling
 * every optional default would flip `repaired` to true on calls that were
 * already perfectly valid, which in `openai-sse.ts` supersedes an
 * already-streamed tool block with a second one. The narrow rule keeps
 * `repaired` meaning "this call would otherwise have failed".
 */
export function applySchemaDefaults(
  schema: JsonSchemaNode | undefined,
  args: Record<string, unknown>
): { args: Record<string, unknown>; applied: string[] } {
  const properties = schema?.properties;
  const required = schema?.required;
  if (!properties || !Array.isArray(required)) return { args, applied: [] };

  const out: Record<string, unknown> = { ...args };
  const applied: string[] = [];
  for (const key of required) {
    if (typeof key !== "string" || !isAbsent(out, key)) continue;
    const node = properties[key];
    if (!node || !Object.hasOwn(node, "default") || node.default === undefined) continue;
    out[key] = node.default;
    applied.push(key);
  }
  return { args: applied.length > 0 ? out : args, applied };
}

/**
 * Names a model reaches for when it does not use the one the schema declares.
 *
 * This is a synonym vocabulary, not a hardcoded list in CLAUDE.md's sense: it is not
 * per-user, not per-account, not time-varying, and it names no tool and no
 * agent. Every entry RENAMES A VALUE THE MODEL SUPPLIED; none invents one. The
 * gate in {@link renameToDeclaredKeys} is what makes that safe.
 */
const KEY_SYNONYMS: Record<string, string[]> = {
  command: ["cmd", "shell", "script"],
  file_path: ["path", "file", "filename"],
  content: ["text", "data", "body"],
  pattern: ["query", "search", "regex", "glob"],
  query: ["search", "keyword"],
  prompt: ["query", "task"],
};

/**
 * Move a supplied value onto the key the schema actually declares.
 *
 * Three conditions, all required, and together they are why this is not the
 * fabrication that was deleted:
 *
 *  1. the SOURCE key is one the schema does **not** declare — so nothing the
 *     tool asked for is ever overwritten or taken away;
 *  2. the TARGET key **is** declared and **is** required — so this only ever
 *     rescues a call that would otherwise fail;
 *  3. the target is **absent** — so a value the model did supply always wins.
 *
 * The value itself is untouched. A first matching synonym wins, and the source
 * key is removed so the tool does not receive both spellings.
 */
export function renameToDeclaredKeys(
  schema: JsonSchemaNode | undefined,
  args: Record<string, unknown>
): { args: Record<string, unknown>; renamed: string[] } {
  const properties = schema?.properties;
  const required = schema?.required;
  if (!properties || !Array.isArray(required)) return { args, renamed: [] };

  const out: Record<string, unknown> = { ...args };
  const renamed: string[] = [];
  for (const target of required) {
    if (typeof target !== "string") continue;
    if (!properties[target] || !isAbsent(out, target)) continue;
    for (const source of KEY_SYNONYMS[target] ?? []) {
      if (properties[source]) continue; // the schema declares it: it means something else
      if (isAbsent(out, source)) continue;
      out[target] = out[source];
      delete out[source];
      renamed.push(`${source}→${target}`);
      break;
    }
  }
  return { args: renamed.length > 0 ? out : args, renamed };
}