@theokit/sdk 2.13.1 → 2.14.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2.14.0
+
+### Minor Changes
+
+- 6ee4217: Add a public, isolated tool-input **sanitization** primitive on the new `@theokit/sdk/sanitize` subpath, plus a declarative `defineTool({ sanitize })` opt-in. Custom tools can now clean the raw arguments a model emits before they reach the tool schema: `sanitizeToolInput(input, options?)` trims whitespace by default and — opt-in — coerces string values toward their expected type (`"5"`→`5`, `"true"`→`true`, JSON-encoded strings→arrays/objects) and repairs malformed JSON (via `jsonrepair`). Coercion is guarded against silent corruption: numeric coercion round-trips and stays finite, so ID-like strings (`"12345678901234567890"`, `"007"`) and `NaN`/`Infinity` are left as strings; JSON repair only runs on JSON-looking values; a non-object input is returned untouched (the primitive is total — it never throws). When a Zod object schema is passed, coercion is schema-aware (a `z.string()` field keeps `"5"` a string). `defineTool({ sanitize: true })` trims the raw args before validation; `defineTool({ sanitize: { coerce: true } })` additionally coerces toward the tool's own schema — absent, `defineTool` behaviour is unchanged. Internally, the leaked-dialect recovery (`hermes-tool-extract`) now reuses the same primitive, so the public surface and the internal path never diverge. Grounded in a SOTA study of openclaw / agentfw / opencode / cline / vercel-ai-sdk.
+
 ## 2.13.1
 
 ### Patch Changes

package/dist/a2a/index.cjs

@@ -10096,6 +10096,124 @@ var init_ollama_native = __esm({
     ollamaSystemText = collapseSystemText;
   }
 });
+function loadJsonrepair() {
+  if (cachedJsonrepair === void 0) {
+    const req = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.cjs', document.baseURI).href)));
+    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;
+}
+var cachedJsonrepair;
+var init_coerce = __esm({
+  "src/sanitize/coerce.ts"() {
+  }
+});
+
+// src/sanitize/sanitize-tool-input.ts
+function applyTrim(key, value, ctx) {
+  const trimmed = value.trim();
+  if (trimmed !== value) ctx.notes.push(`trimmed "${key}"`);
+  return trimmed;
+}
+function applyCoerce(key, raw, ctx) {
+  const field = ctx.shape?.[key];
+  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 "${key}"`);
+  return coerced;
+}
+function applyRepair(key, value, ctx) {
+  const repaired = tryJson(value, true);
+  if (repaired === void 0) return value;
+  ctx.notes.push(`repaired json "${key}"`);
+  return repaired;
+}
+function sanitizeString(key, value, ctx) {
+  let out = ctx.trim ? applyTrim(key, value, ctx) : value;
+  if (ctx.coerce && typeof out === "string") out = applyCoerce(key, out, ctx);
+  if (ctx.repairJson && !ctx.coerce && typeof out === "string") out = applyRepair(key, out, ctx);
+  return out;
+}
+function walk(input, ctx, depth) {
+  const out = {};
+  for (const [key, value] of Object.entries(input)) {
+    if (typeof value === "string") out[key] = sanitizeString(key, value, ctx);
+    else if (ctx.deep && depth < ctx.maxDepth && isPlainObject(value))
+      out[key] = walk(value, ctx, depth + 1);
+    else out[key] = value;
+  }
+  return out;
+}
+function sanitizeToolInput(input, options) {
+  if (!isPlainObject(input)) return { value: input, changed: false, notes: [] };
+  const ctx = {
+    trim: options?.trim,
+    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 };
+}
+var init_sanitize_tool_input = __esm({
+  "src/sanitize/sanitize-tool-input.ts"() {
+    init_coerce();
+  }
+});
 
 // src/internal/llm/hermes-tool-extract.ts
 function extractHermesToolCalls(content, makeId) {
@@ -10119,13 +10237,14 @@ function parseHermesParams(inner) {
     const key = param[1];
     const value = param[2];
     if (key === void 0 || value === void 0) continue;
-    input[key.trim()] = value.trim();
+    input[key.trim()] = value;
   }
-  return input;
+  return sanitizeToolInput(input, { trim: true }).value;
 }
 var HERMES_BLOCK, HERMES_PARAM;
 var init_hermes_tool_extract = __esm({
   "src/internal/llm/hermes-tool-extract.ts"() {
+    init_sanitize_tool_input();
     HERMES_BLOCK = /<function=\s*([^>\s]+)\s*>([\s\S]*?)<\/tool_call>/g;
     HERMES_PARAM = /<parameter=\s*([^>\s]+)\s*>([\s\S]*?)<\/parameter>/g;
   }