@theokit/sdk 2.13.0 → 2.14.0

package/dist/index.d.cts

@@ -863,6 +863,34 @@ interface DefineProviderOptions {
  */
 declare function defineProvider(profile: ProviderProfile, opts?: DefineProviderOptions): Plugin;
 
+/**
+ * Options for {@link sanitizeToolInput}. Trim is the only default-on rung — coercion and JSON
+ * repair change a value's representation, so they are opt-in (the SDK's "values are strings; Zod
+ * coerces" boundary; see `define-tool.ts` doc-comment).
+ *
+ * @public
+ */
+interface SanitizeOptions {
+    /** Trim leading/trailing whitespace from string values. Default `true`. */
+    trim?: boolean;
+    /** Coerce string values to typed values (`"5"`→`5`, `"true"`→`true`, `"null"`→`null`, JSON). Default `false`. */
+    coerce?: boolean;
+    /** Repair-then-parse malformed JSON-looking string values (via `jsonrepair`). Default `false`. */
+    repairJson?: boolean;
+    /**
+     * Optional Zod schema. When it is a `z.object(...)`, coercion is schema-aware: each TOP-LEVEL
+     * field is coerced only toward a candidate its field-schema accepts (so a `z.string()` field
+     * keeps `"5"` as a string). Non-object schemas (union/record) fall back to heuristic coercion.
+     * Note: with `deep: true`, nested fields always use heuristic coercion (the schema is not
+     * descended into).
+     */
+    schema?: ZodType;
+    /** Recurse into nested objects/arrays. Default `false` (shallow). */
+    deep?: boolean;
+    /** Max recursion depth when `deep` is set. Default `8`. */
+    maxDepth?: number;
+}
+
 /**
  * Spec accepted by {@link defineTool}. `inputSchema` is a Zod schema; the
  * `handler` argument type is inferred via `z.infer<T>` — no `as` casts.
@@ -878,6 +906,13 @@ interface DefineToolSpec<T extends ZodType> {
     inputSchema: T;
     /** Handler invoked with the parsed input. Type is inferred via `z.infer<T>`. */
     handler: (input: z.infer<T>) => string | Promise<string>;
+    /**
+     * Sanitize the raw model-emitted args BEFORE schema validation (`@theokit/sdk/sanitize`).
+     * `true` trims whitespace; an object opts into coercion / JSON-repair. Coercion is schema-aware
+     * against this tool's `inputSchema`. Absent ⇒ args reach validation untouched. Sanitize is
+     * hygiene, not a validity bypass — a genuinely invalid arg still raises `ZodError`.
+     */
+    sanitize?: boolean | SanitizeOptions;
 }
 /**
  * Type-safe builder for {@link CustomTool}. Converts a Zod schema to JSON

package/dist/index.d.ts

@@ -863,6 +863,34 @@ interface DefineProviderOptions {
  */
 declare function defineProvider(profile: ProviderProfile, opts?: DefineProviderOptions): Plugin;
 
+/**
+ * Options for {@link sanitizeToolInput}. Trim is the only default-on rung — coercion and JSON
+ * repair change a value's representation, so they are opt-in (the SDK's "values are strings; Zod
+ * coerces" boundary; see `define-tool.ts` doc-comment).
+ *
+ * @public
+ */
+interface SanitizeOptions {
+    /** Trim leading/trailing whitespace from string values. Default `true`. */
+    trim?: boolean;
+    /** Coerce string values to typed values (`"5"`→`5`, `"true"`→`true`, `"null"`→`null`, JSON). Default `false`. */
+    coerce?: boolean;
+    /** Repair-then-parse malformed JSON-looking string values (via `jsonrepair`). Default `false`. */
+    repairJson?: boolean;
+    /**
+     * Optional Zod schema. When it is a `z.object(...)`, coercion is schema-aware: each TOP-LEVEL
+     * field is coerced only toward a candidate its field-schema accepts (so a `z.string()` field
+     * keeps `"5"` as a string). Non-object schemas (union/record) fall back to heuristic coercion.
+     * Note: with `deep: true`, nested fields always use heuristic coercion (the schema is not
+     * descended into).
+     */
+    schema?: ZodType;
+    /** Recurse into nested objects/arrays. Default `false` (shallow). */
+    deep?: boolean;
+    /** Max recursion depth when `deep` is set. Default `8`. */
+    maxDepth?: number;
+}
+
 /**
  * Spec accepted by {@link defineTool}. `inputSchema` is a Zod schema; the
  * `handler` argument type is inferred via `z.infer<T>` — no `as` casts.
@@ -878,6 +906,13 @@ interface DefineToolSpec<T extends ZodType> {
     inputSchema: T;
     /** Handler invoked with the parsed input. Type is inferred via `z.infer<T>`. */
     handler: (input: z.infer<T>) => string | Promise<string>;
+    /**
+     * Sanitize the raw model-emitted args BEFORE schema validation (`@theokit/sdk/sanitize`).
+     * `true` trims whitespace; an object opts into coercion / JSON-repair. Coercion is schema-aware
+     * against this tool's `inputSchema`. Absent ⇒ args reach validation untouched. Sanitize is
+     * hygiene, not a validity bypass — a genuinely invalid arg still raises `ZodError`.
+     */
+    sanitize?: boolean | SanitizeOptions;
 }
 /**
  * Type-safe builder for {@link CustomTool}. Converts a Zod schema to JSON

package/dist/index.js

@@ -13424,6 +13424,115 @@ function toOllamaTools(tools) {
     }
   }));
 }
+var cachedJsonrepair;
+function loadJsonrepair() {
+  if (cachedJsonrepair === void 0) {
+    const req = createRequire(import.meta.url);
+    cachedJsonrepair = req("jsonrepair").jsonrepair;
+  }
+  return cachedJsonrepair;
+}
+function isPlainObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function toFiniteNumber(raw) {
+  if (raw === "") return void 0;
+  const n = Number(raw);
+  return Number.isFinite(n) && String(n) === raw ? n : void 0;
+}
+function tryJson(raw, repair) {
+  const t = raw.trimStart();
+  if (!(t.startsWith("{") || t.startsWith("["))) return void 0;
+  try {
+    return JSON.parse(repair ? loadJsonrepair()(t) : t);
+  } catch {
+    return void 0;
+  }
+}
+function heuristicCoerce(raw, repairJson) {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (raw === "null") return null;
+  const n = toFiniteNumber(raw);
+  if (n !== void 0) return n;
+  const json = tryJson(raw, false) ?? (repairJson ? tryJson(raw, true) : void 0);
+  return json === void 0 ? raw : json;
+}
+function coerceCandidates(raw, repairJson) {
+  const out = [];
+  if (raw === "true") out.push(true);
+  else if (raw === "false") out.push(false);
+  else if (raw === "null") out.push(null);
+  const n = toFiniteNumber(raw);
+  if (n !== void 0) out.push(n);
+  const json = tryJson(raw, false) ?? (repairJson ? tryJson(raw, true) : void 0);
+  if (json !== void 0) out.push(json);
+  out.push(raw);
+  return out;
+}
+function objectShape(schema) {
+  const shape = schema?.shape;
+  return shape !== null && typeof shape === "object" ? shape : void 0;
+}
+
+// src/sanitize/sanitize-tool-input.ts
+function applyTrim(key2, value, ctx) {
+  const trimmed = value.trim();
+  if (trimmed !== value) ctx.notes.push(`trimmed "${key2}"`);
+  return trimmed;
+}
+function applyCoerce(key2, raw, ctx) {
+  const field = ctx.shape?.[key2];
+  let coerced = raw;
+  if (field) {
+    for (const candidate of coerceCandidates(raw, ctx.repairJson)) {
+      if (field.safeParse(candidate).success) {
+        coerced = candidate;
+        break;
+      }
+    }
+  } else {
+    coerced = heuristicCoerce(raw, ctx.repairJson);
+  }
+  if (coerced !== raw) ctx.notes.push(`coerced "${key2}"`);
+  return coerced;
+}
+function applyRepair(key2, value, ctx) {
+  const repaired = tryJson(value, true);
+  if (repaired === void 0) return value;
+  ctx.notes.push(`repaired json "${key2}"`);
+  return repaired;
+}
+function sanitizeString(key2, value, ctx) {
+  let out = ctx.trim ? applyTrim(key2, value, ctx) : value;
+  if (ctx.coerce && typeof out === "string") out = applyCoerce(key2, out, ctx);
+  if (ctx.repairJson && !ctx.coerce && typeof out === "string") out = applyRepair(key2, out, ctx);
+  return out;
+}
+function walk(input, ctx, depth) {
+  const out = {};
+  for (const [key2, value] of Object.entries(input)) {
+    if (typeof value === "string") out[key2] = sanitizeString(key2, value, ctx);
+    else if (ctx.deep && depth < ctx.maxDepth && isPlainObject(value))
+      out[key2] = walk(value, ctx, depth + 1);
+    else out[key2] = value;
+  }
+  return out;
+}
+function sanitizeToolInput(input, options) {
+  if (!isPlainObject(input)) return { value: input, changed: false, notes: [] };
+  const ctx = {
+    trim: options?.trim ?? true,
+    coerce: options?.coerce ?? false,
+    repairJson: options?.repairJson ?? false,
+    deep: options?.deep ?? false,
+    maxDepth: options?.maxDepth ?? 8,
+    shape: objectShape(options?.schema),
+    notes: []
+  };
+  const value = walk(input, ctx, 0);
+  return { value, changed: ctx.notes.length > 0, notes: ctx.notes };
+}
 
 // src/internal/llm/hermes-tool-extract.ts
 var HERMES_BLOCK = /<function=\s*([^>\s]+)\s*>([\s\S]*?)<\/tool_call>/g;
@@ -13451,7 +13560,7 @@ function parseHermesParams(inner) {
     if (key2 === void 0 || value === void 0) continue;
     input[key2.trim()] = value;
   }
-  return input;
+  return sanitizeToolInput(input, { trim: true }).value;
 }
 
 // src/internal/llm/openai.ts
@@ -18172,7 +18281,11 @@ function defineTool(spec) {
     description: spec.description,
     inputSchema,
     handler: async (input) => {
-      const parsed = spec.inputSchema.parse(input);
+      const raw = spec.sanitize ? sanitizeToolInput(input, {
+        ...spec.sanitize === true ? {} : spec.sanitize,
+        schema: spec.inputSchema
+      }).value : input;
+      const parsed = spec.inputSchema.parse(raw);
       return await spec.handler(parsed);
     }
   };