@cohortapp/agent-sdk 2.3.0

package/lib/security/coerce-args.mjs

@@ -0,0 +1,552 @@
+/**
+ * coerce-args.mjs — best-effort JSON-Schema argument coercion + required-field
+ * validation for tool calls.
+ *
+ * LLMs frequently emit tool arguments with the wrong JSON primitive type: a
+ * number arrives as the string "3", a boolean as "true", an integer as "5".
+ * Rather than reject the call outright, this module walks the tool's JSON
+ * Schema and coerces each value toward the declared type — "3" -> 3,
+ * "true" -> true — fills in declared defaults, and recurses through nested
+ * objects and arrays. Every step is a *no-op when it cannot coerce safely*:
+ * if a value can't be turned into the target type it is left untouched, so a
+ * downstream validator still sees (and can reject) genuinely bad input.
+ *
+ * Ported and adapted from OpenClaw (packages/llm-core/src/validation.ts,
+ * coerceWithJsonSchema and helpers) for the maestro ESM model. The TypeBox-
+ * coupled half of the original — Compile/Value.Convert and the
+ * validateToolArguments wrapper — is intentionally NOT ported (it pulls in the
+ * typebox dependency). The one place the original leaned on TypeBox, picking
+ * the winning branch of an anyOf/oneOf union, is reimplemented here with a
+ * small pure-JS structural validator (validateAgainstSchema) so the port stays
+ * dependency-free.
+ *
+ * Pure functions; no dependencies. Node builtins only (structuredClone is
+ * global in Node 17+).
+ */
+
+/* ------------------------------------------------------------------ *
+ * type helpers
+ * ------------------------------------------------------------------ */
+
+/**
+ * @param {unknown} value
+ * @returns {boolean} true for any non-null object (including arrays).
+ */
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * A plain (non-array) object.
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPlainObject(value) {
+  return isRecord(value) && !Array.isArray(value);
+}
+
+/**
+ * A value that looks like a JSON Schema fragment (any object).
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isJsonSchemaObject(value) {
+  return isRecord(value);
+}
+
+/**
+ * Normalise schema.type (string | string[] | undefined) into a string[].
+ * @param {Record<string, any>} schema
+ * @returns {string[]}
+ */
+function getSchemaTypes(schema) {
+  if (typeof schema.type === "string") {
+    return [schema.type];
+  }
+  if (Array.isArray(schema.type)) {
+    return schema.type.filter((type) => typeof type === "string");
+  }
+  return [];
+}
+
+/**
+ * Does a runtime value already satisfy a single JSON Schema primitive type?
+ * @param {unknown} value
+ * @param {string} type
+ * @returns {boolean}
+ */
+function matchesJsonType(value, type) {
+  switch (type) {
+    case "number":
+      return typeof value === "number";
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    case "boolean":
+      return typeof value === "boolean";
+    case "string":
+      return typeof value === "string";
+    case "null":
+      return value === null;
+    case "array":
+      return Array.isArray(value);
+    case "object":
+      return isPlainObject(value);
+    default:
+      return false;
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * number parsing (strict JSON-style tokens only)
+ * ------------------------------------------------------------------ */
+
+const JSON_NUMBER_TOKEN_RE = /^[+-]?(?:(?:\d+\.?\d*)|(?:\.\d+))(?:e[+-]?\d+)?$/iu;
+
+/**
+ * Parse a string into a finite number, but only if it is a clean numeric
+ * token (no trailing units, hex, Infinity, etc.). Returns undefined otherwise.
+ * @param {string} value
+ * @returns {number|undefined}
+ */
+function parseJsonNumberString(value) {
+  const trimmed = value.trim();
+  if (!trimmed || !JSON_NUMBER_TOKEN_RE.test(trimmed)) {
+    return undefined;
+  }
+  const parsed = Number(trimmed);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/**
+ * Like parseJsonNumberString but only accepts safe integers.
+ * @param {string} value
+ * @returns {number|undefined}
+ */
+function parseJsonIntegerString(value) {
+  const parsed = parseJsonNumberString(value);
+  return parsed !== undefined && Number.isSafeInteger(parsed) ? parsed : undefined;
+}
+
+/* ------------------------------------------------------------------ *
+ * primitive coercion
+ * ------------------------------------------------------------------ */
+
+/**
+ * Coerce a single value toward one JSON Schema primitive type. Returns the
+ * coerced value, or the original value unchanged if it cannot be coerced
+ * safely. (Identity return is used by the caller to detect "no change".)
+ * @param {unknown} value
+ * @param {string} type
+ * @returns {unknown}
+ */
+function coercePrimitiveByType(value, type) {
+  switch (type) {
+    case "number": {
+      if (value === null) {
+        return 0;
+      }
+      if (typeof value === "string" && value.trim() !== "") {
+        const parsed = parseJsonNumberString(value);
+        if (parsed !== undefined) {
+          return parsed;
+        }
+      }
+      if (typeof value === "boolean") {
+        return value ? 1 : 0;
+      }
+      return value;
+    }
+    case "integer": {
+      if (value === null) {
+        return 0;
+      }
+      if (typeof value === "string" && value.trim() !== "") {
+        const parsed = parseJsonIntegerString(value);
+        if (parsed !== undefined) {
+          return parsed;
+        }
+      }
+      if (typeof value === "boolean") {
+        return value ? 1 : 0;
+      }
+      return value;
+    }
+    case "boolean": {
+      if (value === null) {
+        return false;
+      }
+      if (typeof value === "string") {
+        if (value === "true") {
+          return true;
+        }
+        if (value === "false") {
+          return false;
+        }
+      }
+      if (typeof value === "number") {
+        if (value === 1) {
+          return true;
+        }
+        if (value === 0) {
+          return false;
+        }
+      }
+      return value;
+    }
+    case "string": {
+      if (value === null) {
+        return "";
+      }
+      if (typeof value === "number" || typeof value === "boolean") {
+        return String(value);
+      }
+      return value;
+    }
+    case "null": {
+      if (value === "" || value === 0 || value === false) {
+        return null;
+      }
+      return value;
+    }
+    default:
+      return value;
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * structural validation (pure-JS replacement for the TypeBox check that
+ * the original used only to pick the winning anyOf/oneOf branch)
+ * ------------------------------------------------------------------ */
+
+/**
+ * Best-effort structural check that a value satisfies a JSON Schema fragment.
+ * This is deliberately lenient — it only understands the keywords this module
+ * coerces against (type, properties, required, items). Unknown keywords are
+ * ignored. It exists solely to disambiguate union branches; it is NOT a
+ * complete JSON Schema validator.
+ * @param {unknown} value
+ * @param {Record<string, any>} schema
+ * @returns {boolean}
+ */
+function validateAgainstSchema(value, schema) {
+  if (!isJsonSchemaObject(schema)) {
+    return true;
+  }
+
+  if (Array.isArray(schema.allOf)) {
+    if (!schema.allOf.every((sub) => validateAgainstSchema(value, sub))) {
+      return false;
+    }
+  }
+  if (Array.isArray(schema.anyOf)) {
+    if (!schema.anyOf.some((sub) => validateAgainstSchema(value, sub))) {
+      return false;
+    }
+  }
+  if (Array.isArray(schema.oneOf)) {
+    const matches = schema.oneOf.filter((sub) => validateAgainstSchema(value, sub));
+    if (matches.length !== 1) {
+      return false;
+    }
+  }
+
+  const types = getSchemaTypes(schema);
+  if (types.length > 0 && !types.some((t) => matchesJsonType(value, t))) {
+    return false;
+  }
+
+  if (isPlainObject(value)) {
+    if (Array.isArray(schema.required)) {
+      for (const key of schema.required) {
+        if (!(key in value)) {
+          return false;
+        }
+      }
+    }
+    if (schema.properties && isJsonSchemaObject(schema.properties)) {
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        if (key in value && !validateAgainstSchema(value[key], propSchema)) {
+          return false;
+        }
+      }
+    }
+  }
+
+  if (Array.isArray(value) && schema.items !== undefined) {
+    if (Array.isArray(schema.items)) {
+      for (let i = 0; i < value.length; i++) {
+        const itemSchema = schema.items[i];
+        if (itemSchema && !validateAgainstSchema(value[i], itemSchema)) {
+          return false;
+        }
+      }
+    } else if (isJsonSchemaObject(schema.items)) {
+      for (const item of value) {
+        if (!validateAgainstSchema(item, schema.items)) {
+          return false;
+        }
+      }
+    }
+  }
+
+  return true;
+}
+
+/* ------------------------------------------------------------------ *
+ * recursive coercion
+ * ------------------------------------------------------------------ */
+
+/**
+ * Coerce the properties (and additionalProperties) of an object in place.
+ * Also fills in declared `default`s for missing properties.
+ * @param {Record<string, unknown>} value
+ * @param {Record<string, any>} schema
+ * @returns {void}
+ */
+function applySchemaObjectCoercion(value, schema) {
+  const properties = schema.properties;
+  const definedKeys = new Set(properties ? Object.keys(properties) : []);
+
+  if (properties && isJsonSchemaObject(properties)) {
+    for (const [key, propertySchema] of Object.entries(properties)) {
+      if (key in value) {
+        value[key] = coerceWithJsonSchema(value[key], propertySchema);
+      } else if (isJsonSchemaObject(propertySchema) && "default" in propertySchema) {
+        // Fill declared defaults for absent properties, then coerce the
+        // default itself (defaults are usually already well-typed, but this
+        // keeps the behaviour consistent and lets a default flow through
+        // nested object/array coercion too).
+        value[key] = coerceWithJsonSchema(
+          structuredCloneSafe(propertySchema.default),
+          propertySchema,
+        );
+      }
+    }
+  }
+
+  if (schema.additionalProperties && isJsonSchemaObject(schema.additionalProperties)) {
+    for (const [key, propertyValue] of Object.entries(value)) {
+      if (!definedKeys.has(key)) {
+        value[key] = coerceWithJsonSchema(propertyValue, schema.additionalProperties);
+      }
+    }
+  }
+}
+
+/**
+ * Coerce the elements of an array in place against schema.items.
+ * @param {unknown[]} value
+ * @param {Record<string, any>} schema
+ * @returns {void}
+ */
+function applySchemaArrayCoercion(value, schema) {
+  if (Array.isArray(schema.items)) {
+    for (let index = 0; index < value.length; index++) {
+      const itemSchema = schema.items[index];
+      if (itemSchema) {
+        value[index] = coerceWithJsonSchema(value[index], itemSchema);
+      }
+    }
+    return;
+  }
+
+  if (isJsonSchemaObject(schema.items)) {
+    for (let index = 0; index < value.length; index++) {
+      value[index] = coerceWithJsonSchema(value[index], schema.items);
+    }
+  }
+}
+
+/**
+ * Try each branch of an anyOf/oneOf union: coerce a clone against the branch
+ * and keep the first result that structurally validates. Falls back to the
+ * original value if no branch produces a valid result.
+ * @param {unknown} value
+ * @param {Record<string, any>[]} schemas
+ * @returns {unknown}
+ */
+function coerceWithUnionSchema(value, schemas) {
+  for (const schema of schemas) {
+    const candidate = structuredCloneSafe(value);
+    const coerced = coerceWithJsonSchema(candidate, schema);
+    if (validateAgainstSchema(coerced, schema)) {
+      return coerced;
+    }
+  }
+  return value;
+}
+
+/**
+ * structuredClone is global in Node 17+, but guard for primitives (cheaper and
+ * avoids any host without it choking on simple values).
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+function structuredCloneSafe(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (typeof structuredClone === "function") {
+    return structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
+/**
+ * Core recursive coercion. Given a value and a JSON Schema fragment, returns a
+ * value coerced toward the schema's declared type(s), recursing into objects
+ * and arrays and resolving allOf/anyOf/oneOf on a best-effort basis. Mutates
+ * objects/arrays in place (callers that need immutability should clone first —
+ * see coerceArgs).
+ * @param {unknown} value
+ * @param {Record<string, any>} schema
+ * @returns {unknown}
+ */
+function coerceWithJsonSchema(value, schema) {
+  if (!isJsonSchemaObject(schema)) {
+    return value;
+  }
+
+  let nextValue = value;
+
+  if (Array.isArray(schema.allOf)) {
+    for (const nested of schema.allOf) {
+      nextValue = coerceWithJsonSchema(nextValue, nested);
+    }
+  }
+
+  if (Array.isArray(schema.anyOf)) {
+    nextValue = coerceWithUnionSchema(nextValue, schema.anyOf);
+  }
+
+  if (Array.isArray(schema.oneOf)) {
+    nextValue = coerceWithUnionSchema(nextValue, schema.oneOf);
+  }
+
+  const schemaTypes = getSchemaTypes(schema);
+  // For a union of types (e.g. ["string","number"]) only coerce if the value
+  // matches none of them; otherwise leave a value that already fits one member.
+  const matchesUnionMember =
+    schemaTypes.length > 1 &&
+    schemaTypes.some((schemaType) => matchesJsonType(nextValue, schemaType));
+  if (schemaTypes.length > 0 && !matchesUnionMember) {
+    for (const schemaType of schemaTypes) {
+      const candidate = coercePrimitiveByType(nextValue, schemaType);
+      if (candidate !== nextValue) {
+        nextValue = candidate;
+        break;
+      }
+    }
+  }
+
+  if (schemaTypes.includes("object") && isPlainObject(nextValue)) {
+    applySchemaObjectCoercion(nextValue, schema);
+  }
+
+  if (schemaTypes.includes("array") && Array.isArray(nextValue)) {
+    applySchemaArrayCoercion(nextValue, schema);
+  }
+
+  return nextValue;
+}
+
+/* ------------------------------------------------------------------ *
+ * public API
+ * ------------------------------------------------------------------ */
+
+/**
+ * Coerce tool-call arguments toward a JSON Schema, filling declared defaults
+ * and recursing into nested objects/arrays. Best-effort and non-destructive:
+ * the input is deep-cloned first (never mutated), and any value that cannot be
+ * coerced safely is returned unchanged so a strict validator downstream can
+ * still reject it.
+ *
+ * @param {unknown} value  The arguments object (or any value) to coerce.
+ * @param {Record<string, any>} schema  A JSON Schema fragment.
+ * @returns {unknown} A new, coerced value.
+ *
+ * @example
+ *   coerceArgs({ count: "3", on: "true" },
+ *     { type: "object", properties: {
+ *         count: { type: "integer" }, on: { type: "boolean" } } });
+ *   // => { count: 3, on: true }
+ */
+export function coerceArgs(value, schema) {
+  if (!isJsonSchemaObject(schema)) {
+    return value;
+  }
+  const clone = structuredCloneSafe(value);
+  return coerceWithJsonSchema(clone, schema);
+}
+
+/**
+ * Check that an object contains every property listed in `schema.required`.
+ * Recurses one level into `properties` whose sub-schema also declares
+ * `required`, reporting nested misses with dotted paths (e.g. "address.zip").
+ *
+ * Note: a missing top-level value (non-object) is reported as every required
+ * key missing. This is a structural required-presence check only — it does NOT
+ * type-check present values (use coerceArgs + a full validator for that).
+ *
+ * @param {unknown} value  The object to check.
+ * @param {Record<string, any>} schema  A JSON Schema fragment.
+ * @returns {{ ok: boolean, missing: string[] }}
+ *
+ * @example
+ *   validateRequired({ a: 1 }, { required: ["a", "b"] });
+ *   // => { ok: false, missing: ["b"] }
+ */
+export function validateRequired(value, schema) {
+  const missing = [];
+  collectMissingRequired(value, schema, "", missing);
+  return { ok: missing.length === 0, missing };
+}
+
+/**
+ * @param {unknown} value
+ * @param {Record<string, any>} schema
+ * @param {string} prefix  Dotted path prefix for nested reporting.
+ * @param {string[]} out  Accumulator for missing dotted paths.
+ * @returns {void}
+ */
+function collectMissingRequired(value, schema, prefix, out) {
+  if (!isJsonSchemaObject(schema)) {
+    return;
+  }
+
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  const valueIsObject = isPlainObject(value);
+
+  for (const key of required) {
+    if (typeof key !== "string") {
+      continue;
+    }
+    if (!valueIsObject || !(key in value)) {
+      out.push(prefix ? `${prefix}.${key}` : key);
+    }
+  }
+
+  // Recurse one level into declared object properties that are present, so a
+  // nested required miss (e.g. address.zip) is also surfaced.
+  if (valueIsObject && schema.properties && isJsonSchemaObject(schema.properties)) {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      if (!isJsonSchemaObject(propSchema)) {
+        continue;
+      }
+      const present = key in value;
+      const childRequired = Array.isArray(propSchema.required) && propSchema.required.length > 0;
+      // Only descend when the property is present (an absent object property is
+      // already flagged at this level if it was required) and the child itself
+      // declares required keys to check.
+      if (present && childRequired) {
+        collectMissingRequired(
+          value[key],
+          propSchema,
+          prefix ? `${prefix}.${key}` : key,
+          out,
+        );
+      }
+    }
+  }
+}