@theokit/sdk 2.13.0 → 2.14.0

package/dist/internal/llm/hermes-tool-extract.d.ts

@@ -1,3 +1,4 @@
+import type { LlmToolCallPart } from "./types.js";
 export interface HermesExtractResult {
     /** Recovered tool calls (empty when none matched). */
     toolCalls: LlmToolCallPart[];

package/dist/sanitize/coerce.d.cts

@@ -0,0 +1 @@
+export {};

package/dist/sanitize/coerce.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sanitize/index.cjs

@@ -0,0 +1,119 @@
+'use strict';
+
+var module$1 = require('module');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+// src/sanitize/coerce.ts
+var cachedJsonrepair;
+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;
+}
+
+// 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 ?? 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 };
+}
+
+exports.sanitizeToolInput = sanitizeToolInput;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/sanitize/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sanitize/coerce.ts","../../src/sanitize/sanitize-tool-input.ts"],"names":["createRequire"],"mappings":"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","file":"index.cjs","sourcesContent":["import { createRequire } from \"node:module\";\n\nimport type { ZodType } from \"zod\";\n\n// `jsonrepair` is loaded lazily — consumers who never set `repairJson: true` never pay its\n// module-parse cost. Unlike `zod` (an optional peer dep), `jsonrepair` is a direct dependency and\n// is always installed; the lazy load is a startup-cost optimization, not an optional-install story.\n// Cached after the first repair.\nlet cachedJsonrepair: ((text: string) => string) | undefined;\nfunction loadJsonrepair(): (text: string) => string {\n  if (cachedJsonrepair === undefined) {\n    const req = createRequire(import.meta.url);\n    cachedJsonrepair = (req(\"jsonrepair\") as { jsonrepair: (t: string) => string }).jsonrepair;\n  }\n  return cachedJsonrepair;\n}\n\n/** @internal */\nexport function isPlainObject(v: unknown): v is Record<string, unknown> {\n  return v !== null && typeof v === \"object\" && !Array.isArray(v);\n}\n\n/** Number coercion with a round-trip + finite guard: rejects big-ints, leading-zeros, `NaN`,\n *  `Infinity`, and non-canonical forms (`\"1e3\"`), preventing silent ID/precision corruption (EC-2). */\nfunction toFiniteNumber(raw: string): number | undefined {\n  if (raw === \"\") return undefined;\n  const n = Number(raw);\n  return Number.isFinite(n) && String(n) === raw ? n : undefined;\n}\n\n/** Parse a value ONLY when it looks like a JSON object/array (EC-3 guard; leading whitespace\n *  ignored so `trim:false` inputs are still gated correctly). `repair` routes it through\n *  `jsonrepair` first. Returns `undefined` when not JSON-looking or on parse failure.\n *  @internal */\nexport function tryJson(raw: string, repair: boolean): unknown {\n  const t = raw.trimStart();\n  if (!(t.startsWith(\"{\") || t.startsWith(\"[\"))) return undefined;\n  try {\n    return JSON.parse(repair ? loadJsonrepair()(t) : t);\n  } catch {\n    return undefined;\n  }\n}\n\n/** Heuristic scalar/JSON coercion (agentfw `coerceParameter` shape) used when there is no\n *  per-field schema. Returns the coerced value, or the raw string when nothing applies.\n *  @internal */\nexport function heuristicCoerce(raw: string, repairJson: boolean): unknown {\n  if (raw === \"true\") return true;\n  if (raw === \"false\") return false;\n  if (raw === \"null\") return null;\n  const n = toFiniteNumber(raw);\n  if (n !== undefined) return n;\n  const json = tryJson(raw, false) ?? (repairJson ? tryJson(raw, true) : undefined);\n  return json === undefined ? raw : json;\n}\n\n/** Candidates a raw string could coerce to, most-specific first. Used for schema-aware coercion:\n *  the field schema selects the first candidate it accepts (so a string field keeps `\"5\"`).\n *  @internal */\nexport function coerceCandidates(raw: string, repairJson: boolean): unknown[] {\n  const out: unknown[] = [];\n  if (raw === \"true\") out.push(true);\n  else if (raw === \"false\") out.push(false);\n  else if (raw === \"null\") out.push(null);\n  const n = toFiniteNumber(raw);\n  if (n !== undefined) out.push(n);\n  const json = tryJson(raw, false) ?? (repairJson ? tryJson(raw, true) : undefined);\n  if (json !== undefined) out.push(json);\n  out.push(raw); // raw string is always the last-resort candidate\n  return out;\n}\n\n/** True for a Zod schema that exposes a per-key `.shape` (a `z.object`, incl. Zod-v4\n *  `.refine()`/`.default()` which keep `.shape`); non-object schemas (union/record) return\n *  `undefined` so callers fall back to heuristic coercion (EC-4).\n *  @internal */\nexport function objectShape(schema: ZodType | undefined): Record<string, ZodType> | undefined {\n  const shape = (schema as unknown as { shape?: unknown } | undefined)?.shape;\n  return shape !== null && typeof shape === \"object\"\n    ? (shape as Record<string, ZodType>)\n    : undefined;\n}\n","import type { ZodType } from \"zod\";\n\nimport {\n  coerceCandidates,\n  heuristicCoerce,\n  isPlainObject,\n  objectShape,\n  tryJson,\n} from \"./coerce.js\";\nimport type { SanitizeOptions, SanitizeResult } from \"./types.js\";\n\ninterface Ctx {\n  trim: boolean;\n  coerce: boolean;\n  repairJson: boolean;\n  deep: boolean;\n  maxDepth: number;\n  shape: Record<string, ZodType> | undefined;\n  notes: string[];\n}\n\n/** Trim rung — returns the trimmed string, noting the change. */\nfunction applyTrim(key: string, value: string, ctx: Ctx): string {\n  const trimmed = value.trim();\n  if (trimmed !== value) ctx.notes.push(`trimmed \"${key}\"`);\n  return trimmed;\n}\n\n/** Coerce rung — schema-aware when a field schema exists (pick the first accepted candidate),\n *  else heuristic. Returns the coerced value (or the raw string), noting the change. */\nfunction applyCoerce(key: string, raw: string, ctx: Ctx): unknown {\n  const field = ctx.shape?.[key];\n  let coerced: unknown = raw;\n  if (field) {\n    for (const candidate of coerceCandidates(raw, ctx.repairJson)) {\n      if (field.safeParse(candidate).success) {\n        coerced = candidate;\n        break;\n      }\n    }\n  } else {\n    coerced = heuristicCoerce(raw, ctx.repairJson);\n  }\n  if (coerced !== raw) ctx.notes.push(`coerced \"${key}\"`);\n  return coerced;\n}\n\n/** Repair rung — repair-then-parse a JSON-looking string, noting the change. */\nfunction applyRepair(key: string, value: string, ctx: Ctx): unknown {\n  const repaired = tryJson(value, true);\n  if (repaired === undefined) return value;\n  ctx.notes.push(`repaired json \"${key}\"`);\n  return repaired;\n}\n\n/** Sanitize one string value through the enabled rungs (trim → coerce → repair). */\nfunction sanitizeString(key: string, value: string, ctx: Ctx): unknown {\n  let out: unknown = ctx.trim ? applyTrim(key, value, ctx) : value;\n  if (ctx.coerce && typeof out === \"string\") out = applyCoerce(key, out, ctx);\n  // Standalone repair runs ONLY when coerce is off. When coerce is on it already embedded the\n  // repair candidate (via coerceCandidates / heuristicCoerce), and a schema-confirmed raw string\n  // (e.g. a JSON string a `z.string()` field accepted) must not be clobbered back into an object.\n  if (ctx.repairJson && !ctx.coerce && typeof out === \"string\") out = applyRepair(key, out, ctx);\n  return out;\n}\n\nfunction walk(input: Record<string, unknown>, ctx: Ctx, depth: number): Record<string, unknown> {\n  const out: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(input)) {\n    if (typeof value === \"string\") out[key] = sanitizeString(key, value, ctx);\n    else if (ctx.deep && depth < ctx.maxDepth && isPlainObject(value))\n      out[key] = walk(value, ctx, depth + 1);\n    else out[key] = value;\n  }\n  return out;\n}\n\n/**\n * Sanitize the raw arguments a model emitted for a tool call — trim (default), optionally coerce\n * string values toward their expected type, optionally repair malformed JSON. Pure, synchronous,\n * and TOTAL: it never throws (non-object input is returned unchanged) and never changes a value's\n * meaning — only its hygiene/representation. Reused internally by the leaked-dialect recovery so\n * the public primitive and the internal path never diverge.\n *\n * @public\n */\nexport function sanitizeToolInput(\n  input: Record<string, unknown>,\n  options?: SanitizeOptions,\n): SanitizeResult {\n  // EC-1 — total contract: a non-object (null / array / primitive) is returned as-is, never thrown on.\n  if (!isPlainObject(input)) return { value: input, changed: false, notes: [] };\n  const ctx: Ctx = {\n    trim: options?.trim ?? true,\n    coerce: options?.coerce ?? false,\n    repairJson: options?.repairJson ?? false,\n    deep: options?.deep ?? false,\n    maxDepth: options?.maxDepth ?? 8,\n    shape: objectShape(options?.schema),\n    notes: [],\n  };\n  const value = walk(input, ctx, 0);\n  return { value, changed: ctx.notes.length > 0, notes: ctx.notes };\n}\n"]}

package/dist/sanitize/index.d.cts

@@ -0,0 +1,9 @@
+/**
+ * `@theokit/sdk/sanitize` — a professional, isolated tool-input sanitization primitive that
+ * custom tools consume to clean model-emitted arguments (trim / coerce / json-repair). Pure,
+ * synchronous, dependency-light. See `sanitizeToolInput`.
+ *
+ * @packageDocumentation
+ */
+export { sanitizeToolInput } from "./sanitize-tool-input.js";
+export type { SanitizeOptions, SanitizeResult } from "./types.js";

package/dist/sanitize/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@theokit/sdk/sanitize` — a professional, isolated tool-input sanitization primitive that
+ * custom tools consume to clean model-emitted arguments (trim / coerce / json-repair). Pure,
+ * synchronous, dependency-light. See `sanitizeToolInput`.
+ *
+ * @packageDocumentation
+ */
+export { sanitizeToolInput } from "./sanitize-tool-input.js";
+export type { SanitizeOptions, SanitizeResult } from "./types.js";

package/dist/sanitize/index.js

@@ -0,0 +1,116 @@
+import { createRequire } from 'module';
+
+// src/sanitize/coerce.ts
+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(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 ?? 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 };
+}
+
+export { sanitizeToolInput };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/sanitize/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sanitize/coerce.ts","../../src/sanitize/sanitize-tool-input.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { createRequire } from \"node:module\";\n\nimport type { ZodType } from \"zod\";\n\n// `jsonrepair` is loaded lazily — consumers who never set `repairJson: true` never pay its\n// module-parse cost. Unlike `zod` (an optional peer dep), `jsonrepair` is a direct dependency and\n// is always installed; the lazy load is a startup-cost optimization, not an optional-install story.\n// Cached after the first repair.\nlet cachedJsonrepair: ((text: string) => string) | undefined;\nfunction loadJsonrepair(): (text: string) => string {\n  if (cachedJsonrepair === undefined) {\n    const req = createRequire(import.meta.url);\n    cachedJsonrepair = (req(\"jsonrepair\") as { jsonrepair: (t: string) => string }).jsonrepair;\n  }\n  return cachedJsonrepair;\n}\n\n/** @internal */\nexport function isPlainObject(v: unknown): v is Record<string, unknown> {\n  return v !== null && typeof v === \"object\" && !Array.isArray(v);\n}\n\n/** Number coercion with a round-trip + finite guard: rejects big-ints, leading-zeros, `NaN`,\n *  `Infinity`, and non-canonical forms (`\"1e3\"`), preventing silent ID/precision corruption (EC-2). */\nfunction toFiniteNumber(raw: string): number | undefined {\n  if (raw === \"\") return undefined;\n  const n = Number(raw);\n  return Number.isFinite(n) && String(n) === raw ? n : undefined;\n}\n\n/** Parse a value ONLY when it looks like a JSON object/array (EC-3 guard; leading whitespace\n *  ignored so `trim:false` inputs are still gated correctly). `repair` routes it through\n *  `jsonrepair` first. Returns `undefined` when not JSON-looking or on parse failure.\n *  @internal */\nexport function tryJson(raw: string, repair: boolean): unknown {\n  const t = raw.trimStart();\n  if (!(t.startsWith(\"{\") || t.startsWith(\"[\"))) return undefined;\n  try {\n    return JSON.parse(repair ? loadJsonrepair()(t) : t);\n  } catch {\n    return undefined;\n  }\n}\n\n/** Heuristic scalar/JSON coercion (agentfw `coerceParameter` shape) used when there is no\n *  per-field schema. Returns the coerced value, or the raw string when nothing applies.\n *  @internal */\nexport function heuristicCoerce(raw: string, repairJson: boolean): unknown {\n  if (raw === \"true\") return true;\n  if (raw === \"false\") return false;\n  if (raw === \"null\") return null;\n  const n = toFiniteNumber(raw);\n  if (n !== undefined) return n;\n  const json = tryJson(raw, false) ?? (repairJson ? tryJson(raw, true) : undefined);\n  return json === undefined ? raw : json;\n}\n\n/** Candidates a raw string could coerce to, most-specific first. Used for schema-aware coercion:\n *  the field schema selects the first candidate it accepts (so a string field keeps `\"5\"`).\n *  @internal */\nexport function coerceCandidates(raw: string, repairJson: boolean): unknown[] {\n  const out: unknown[] = [];\n  if (raw === \"true\") out.push(true);\n  else if (raw === \"false\") out.push(false);\n  else if (raw === \"null\") out.push(null);\n  const n = toFiniteNumber(raw);\n  if (n !== undefined) out.push(n);\n  const json = tryJson(raw, false) ?? (repairJson ? tryJson(raw, true) : undefined);\n  if (json !== undefined) out.push(json);\n  out.push(raw); // raw string is always the last-resort candidate\n  return out;\n}\n\n/** True for a Zod schema that exposes a per-key `.shape` (a `z.object`, incl. Zod-v4\n *  `.refine()`/`.default()` which keep `.shape`); non-object schemas (union/record) return\n *  `undefined` so callers fall back to heuristic coercion (EC-4).\n *  @internal */\nexport function objectShape(schema: ZodType | undefined): Record<string, ZodType> | undefined {\n  const shape = (schema as unknown as { shape?: unknown } | undefined)?.shape;\n  return shape !== null && typeof shape === \"object\"\n    ? (shape as Record<string, ZodType>)\n    : undefined;\n}\n","import type { ZodType } from \"zod\";\n\nimport {\n  coerceCandidates,\n  heuristicCoerce,\n  isPlainObject,\n  objectShape,\n  tryJson,\n} from \"./coerce.js\";\nimport type { SanitizeOptions, SanitizeResult } from \"./types.js\";\n\ninterface Ctx {\n  trim: boolean;\n  coerce: boolean;\n  repairJson: boolean;\n  deep: boolean;\n  maxDepth: number;\n  shape: Record<string, ZodType> | undefined;\n  notes: string[];\n}\n\n/** Trim rung — returns the trimmed string, noting the change. */\nfunction applyTrim(key: string, value: string, ctx: Ctx): string {\n  const trimmed = value.trim();\n  if (trimmed !== value) ctx.notes.push(`trimmed \"${key}\"`);\n  return trimmed;\n}\n\n/** Coerce rung — schema-aware when a field schema exists (pick the first accepted candidate),\n *  else heuristic. Returns the coerced value (or the raw string), noting the change. */\nfunction applyCoerce(key: string, raw: string, ctx: Ctx): unknown {\n  const field = ctx.shape?.[key];\n  let coerced: unknown = raw;\n  if (field) {\n    for (const candidate of coerceCandidates(raw, ctx.repairJson)) {\n      if (field.safeParse(candidate).success) {\n        coerced = candidate;\n        break;\n      }\n    }\n  } else {\n    coerced = heuristicCoerce(raw, ctx.repairJson);\n  }\n  if (coerced !== raw) ctx.notes.push(`coerced \"${key}\"`);\n  return coerced;\n}\n\n/** Repair rung — repair-then-parse a JSON-looking string, noting the change. */\nfunction applyRepair(key: string, value: string, ctx: Ctx): unknown {\n  const repaired = tryJson(value, true);\n  if (repaired === undefined) return value;\n  ctx.notes.push(`repaired json \"${key}\"`);\n  return repaired;\n}\n\n/** Sanitize one string value through the enabled rungs (trim → coerce → repair). */\nfunction sanitizeString(key: string, value: string, ctx: Ctx): unknown {\n  let out: unknown = ctx.trim ? applyTrim(key, value, ctx) : value;\n  if (ctx.coerce && typeof out === \"string\") out = applyCoerce(key, out, ctx);\n  // Standalone repair runs ONLY when coerce is off. When coerce is on it already embedded the\n  // repair candidate (via coerceCandidates / heuristicCoerce), and a schema-confirmed raw string\n  // (e.g. a JSON string a `z.string()` field accepted) must not be clobbered back into an object.\n  if (ctx.repairJson && !ctx.coerce && typeof out === \"string\") out = applyRepair(key, out, ctx);\n  return out;\n}\n\nfunction walk(input: Record<string, unknown>, ctx: Ctx, depth: number): Record<string, unknown> {\n  const out: Record<string, unknown> = {};\n  for (const [key, value] of Object.entries(input)) {\n    if (typeof value === \"string\") out[key] = sanitizeString(key, value, ctx);\n    else if (ctx.deep && depth < ctx.maxDepth && isPlainObject(value))\n      out[key] = walk(value, ctx, depth + 1);\n    else out[key] = value;\n  }\n  return out;\n}\n\n/**\n * Sanitize the raw arguments a model emitted for a tool call — trim (default), optionally coerce\n * string values toward their expected type, optionally repair malformed JSON. Pure, synchronous,\n * and TOTAL: it never throws (non-object input is returned unchanged) and never changes a value's\n * meaning — only its hygiene/representation. Reused internally by the leaked-dialect recovery so\n * the public primitive and the internal path never diverge.\n *\n * @public\n */\nexport function sanitizeToolInput(\n  input: Record<string, unknown>,\n  options?: SanitizeOptions,\n): SanitizeResult {\n  // EC-1 — total contract: a non-object (null / array / primitive) is returned as-is, never thrown on.\n  if (!isPlainObject(input)) return { value: input, changed: false, notes: [] };\n  const ctx: Ctx = {\n    trim: options?.trim ?? true,\n    coerce: options?.coerce ?? false,\n    repairJson: options?.repairJson ?? false,\n    deep: options?.deep ?? false,\n    maxDepth: options?.maxDepth ?? 8,\n    shape: objectShape(options?.schema),\n    notes: [],\n  };\n  const value = walk(input, ctx, 0);\n  return { value, changed: ctx.notes.length > 0, notes: ctx.notes };\n}\n"]}

package/dist/sanitize/sanitize-tool-input.d.cts

@@ -0,0 +1,11 @@
+import type { SanitizeOptions, SanitizeResult } from "./types.js";
+/**
+ * Sanitize the raw arguments a model emitted for a tool call — trim (default), optionally coerce
+ * string values toward their expected type, optionally repair malformed JSON. Pure, synchronous,
+ * and TOTAL: it never throws (non-object input is returned unchanged) and never changes a value's
+ * meaning — only its hygiene/representation. Reused internally by the leaked-dialect recovery so
+ * the public primitive and the internal path never diverge.
+ *
+ * @public
+ */
+export declare function sanitizeToolInput(input: Record<string, unknown>, options?: SanitizeOptions): SanitizeResult;

package/dist/sanitize/sanitize-tool-input.d.ts

@@ -0,0 +1,11 @@
+import type { SanitizeOptions, SanitizeResult } from "./types.js";
+/**
+ * Sanitize the raw arguments a model emitted for a tool call — trim (default), optionally coerce
+ * string values toward their expected type, optionally repair malformed JSON. Pure, synchronous,
+ * and TOTAL: it never throws (non-object input is returned unchanged) and never changes a value's
+ * meaning — only its hygiene/representation. Reused internally by the leaked-dialect recovery so
+ * the public primitive and the internal path never diverge.
+ *
+ * @public
+ */
+export declare function sanitizeToolInput(input: Record<string, unknown>, options?: SanitizeOptions): SanitizeResult;

package/dist/sanitize/types.d.cts

@@ -0,0 +1,39 @@
+import type { ZodType } from "zod";
+/**
+ * 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
+ */
+export 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;
+}
+/**
+ * Result of {@link sanitizeToolInput}. `value` is the sanitized copy; `changed` is true when any
+ * value was altered; `notes` records a human-readable line per change (for logging/debugging).
+ *
+ * @public
+ */
+export interface SanitizeResult<T = Record<string, unknown>> {
+    value: T;
+    changed: boolean;
+    notes: string[];
+}

package/dist/sanitize/types.d.ts

@@ -0,0 +1,39 @@
+import type { ZodType } from "zod";
+/**
+ * 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
+ */
+export 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;
+}
+/**
+ * Result of {@link sanitizeToolInput}. `value` is the sanitized copy; `changed` is true when any
+ * value was altered; `notes` records a human-readable line per change (for logging/debugging).
+ *
+ * @public
+ */
+export interface SanitizeResult<T = Record<string, unknown>> {
+    value: T;
+    changed: boolean;
+    notes: string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheo/theokit-sdk#readme",
@@ -208,6 +208,16 @@
         "default": "./dist/subscription/index.cjs"
       }
     },
+    "./sanitize": {
+      "import": {
+        "types": "./dist/sanitize/index.d.ts",
+        "default": "./dist/sanitize/index.js"
+      },
+      "require": {
+        "types": "./dist/sanitize/index.d.cts",
+        "default": "./dist/sanitize/index.cjs"
+      }
+    },
     "./internal/persistence": {
       "import": {
         "types": "./dist/internal/persistence/index.d.ts",
@@ -358,7 +368,8 @@
     "Theo"
   ],
   "dependencies": {
-    "croner": "^9.0.0"
+    "croner": "^9.0.0",
+    "jsonrepair": "^3.13.2"
   },
   "devDependencies": {
     "@opentelemetry/api": "^1.9.1",