@theokit/sdk 2.13.1 → 2.15.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
-import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-9yw4UQwX.cjs';
-export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, E as ErrorCode, m as ErrorMetadata, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-9yw4UQwX.cjs';
-import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as ProviderProfile, m as Plugin, n as ConversationStorageAdapter, o as StoredMessage, B as BudgetTracker, p as MemoryProvider, q as MemoryId, r as PreToolCallDecision, s as SDKProvider } from './cron-CpxLdAXc.cjs';
-export { t as ActiveMemoryPassArgs, u as ActiveMemoryPassResult, v as AgentMemory, w as BudgetCheck, x as BudgetTotal, y as BudgetUsageEvent, z as CloudEnv, D as CloudRepo, E as ContextBudget, F as ContextManagerKind, H as ContextSnapshot, I as ContextSource, J as ContextSourceStatus, K as Cron, N as CronCreateOptions, O as CronGetOptions, Q as CronJob, R as CronJobStatus, T as CronListOptions, U as CronOperationOptions, V as CronRunOptions, W as CronRuntime, X as CronSchedulerStatus, Y as CronStartOptions, Z as GoalEvent, _ as GoalOptions, $ as GoalResult, a0 as HookName, a1 as InvalidateCacheOptions, a2 as MemoryAdapter, a3 as MemoryAdapterCapabilities, a4 as MemoryContext, a5 as MemoryFact, a6 as MemoryProviderHandle, a7 as MemoryProviderInitOptions, a8 as MemoryRevision, a9 as MemoryToolSchema, aa as MemoryTurnMessage, ab as PersonalityPreset, ac as PluginContext, ad as PostAssistantReplyContext, ae as PreToolCallContext, af as PreUserSendContext, ag as PreUserSendResult, ah as ProviderCapability, ai as ProviderRoute, aj as RecordSessionSummaryArgs, ak as ResolvedProviderRoute, al as RunUntilIterator, am as SDKAgentPlugins, an as SDKAgentSkills, ao as SDKArtifact, ap as SDKContextManager, aq as SDKPluginMetadata, ar as SDKProvidersManager, as as SettingSource, at as SystemPromptContext, au as SystemPromptMemoryFact, av as SystemPromptSkillRef, aw as TelemetrySettings, ax as definePlugin } from './cron-CpxLdAXc.cjs';
-import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, S as SDKMessage } from './run-TMdc7gmo.cjs';
-export { A as AgentConversationTurn, c as AssistantMessage, d as ConversationStep, e as ConversationTurn, f as CostBreakdown, g as CostSource, h as CostStatus, I as InteractionUpdate, i as McpAuthConfig, j as McpHttpServerConfig, k as McpOAuthConfig, l as McpStdioServerConfig, m as ModelParameterValue, P as PartialToolCallUpdate, n as RunErrorDetail, o as RunGitInfo, p as RunOperation, q as RunStatus, r as RunToCompletionOptions, s as RunToCompletionResult, t as SDKAssistantMessage, u as SDKImage, v as SDKImageDimension, w as SDKObjectDelta, x as SDKRequestMessage, y as SDKStatusMessage, z as SDKSystemMessage, B as SDKTaskMessage, D as SDKThinkingMessage, E as SDKToolUseMessage, F as SDKUserMessage, G as SDKUserMessageEvent, H as SendOptions, J as ShellCommand, K as ShellConversationTurn, L as ShellOutput, N as ShellOutputDeltaUpdate, O as StepCompletedUpdate, Q as StepStartedUpdate, T as StreamToCompletionResult, U as SummaryCompletedUpdate, V as SummaryStartedUpdate, W as SummaryUpdate, X as TextBlock, Y as TextDeltaUpdate, Z as ThinkingCompletedUpdate, _ as ThinkingDeltaUpdate, $ as ThinkingMessage, a0 as TokenDeltaUpdate, a1 as TokenUsage, a2 as ToolCall, a3 as ToolCallCompletedUpdate, a4 as ToolCallStartedUpdate, a5 as ToolResult, a6 as ToolUseBlock, a7 as TurnEndedUpdate, a8 as UserMessage, a9 as UserMessageAppendedUpdate } from './run-TMdc7gmo.cjs';
+import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-Bart0ptP.cjs';
+export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, E as ErrorCode, m as ErrorMetadata, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-Bart0ptP.cjs';
+import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as ProviderProfile, m as Plugin, n as ConversationStorageAdapter, o as StoredMessage, B as BudgetTracker, p as MemoryProvider, q as MemoryId, r as PreToolCallDecision, s as SDKProvider } from './cron-BxLSz1UH.cjs';
+export { t as ActiveMemoryPassArgs, u as ActiveMemoryPassResult, v as AgentMemory, w as BudgetCheck, x as BudgetTotal, y as BudgetUsageEvent, z as CloudEnv, D as CloudRepo, E as ContextBudget, F as ContextManagerKind, H as ContextSnapshot, I as ContextSource, J as ContextSourceStatus, K as Cron, N as CronCreateOptions, O as CronGetOptions, Q as CronJob, R as CronJobStatus, T as CronListOptions, U as CronOperationOptions, V as CronRunOptions, W as CronRuntime, X as CronSchedulerStatus, Y as CronStartOptions, Z as GoalEvent, _ as GoalOptions, $ as GoalResult, a0 as HookName, a1 as InvalidateCacheOptions, a2 as MemoryAdapter, a3 as MemoryAdapterCapabilities, a4 as MemoryContext, a5 as MemoryFact, a6 as MemoryProviderHandle, a7 as MemoryProviderInitOptions, a8 as MemoryRevision, a9 as MemoryToolSchema, aa as MemoryTurnMessage, ab as PersonalityPreset, ac as PluginContext, ad as PostAssistantReplyContext, ae as PreToolCallContext, af as PreUserSendContext, ag as PreUserSendResult, ah as ProviderCapability, ai as ProviderRoute, aj as RecordSessionSummaryArgs, ak as ResolvedProviderRoute, al as RunUntilIterator, am as SDKAgentPlugins, an as SDKAgentSkills, ao as SDKArtifact, ap as SDKContextManager, aq as SDKPluginMetadata, ar as SDKProvidersManager, as as SettingSource, at as SystemPromptContext, au as SystemPromptMemoryFact, av as SystemPromptSkillRef, aw as TelemetrySettings, ax as definePlugin } from './cron-BxLSz1UH.cjs';
+import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, S as SDKMessage } from './run-DXy_MVwz.cjs';
+export { A as AgentConversationTurn, c as AssistantMessage, d as ConversationStep, e as ConversationTurn, f as CostBreakdown, g as CostSource, h as CostStatus, D as DoomLoopThresholds, I as InteractionUpdate, i as McpAuthConfig, j as McpHttpServerConfig, k as McpOAuthConfig, l as McpStdioServerConfig, m as ModelParameterValue, P as PartialToolCallUpdate, n as RunErrorDetail, o as RunGitInfo, p as RunOperation, q as RunStatus, r as RunToCompletionOptions, s as RunToCompletionResult, t as SDKAssistantMessage, u as SDKImage, v as SDKImageDimension, w as SDKObjectDelta, x as SDKRequestMessage, y as SDKStatusMessage, z as SDKSystemMessage, B as SDKTaskMessage, E as SDKThinkingMessage, F as SDKToolUseMessage, G as SDKUserMessage, H as SDKUserMessageEvent, J as SendOptions, K as ShellCommand, L as ShellConversationTurn, N as ShellOutput, O as ShellOutputDeltaUpdate, Q as StepCompletedUpdate, T as StepStartedUpdate, U as StreamToCompletionResult, V as SummaryCompletedUpdate, W as SummaryStartedUpdate, X as SummaryUpdate, Y as TextBlock, Z as TextDeltaUpdate, _ as ThinkingCompletedUpdate, $ as ThinkingDeltaUpdate, a0 as ThinkingMessage, a1 as TokenDeltaUpdate, a2 as TokenUsage, a3 as ToolCall, a4 as ToolCallCompletedUpdate, a5 as ToolCallStartedUpdate, a6 as ToolResult, a7 as ToolUseBlock, a8 as TurnEndedUpdate, a9 as UserMessage, aa as UserMessageAppendedUpdate } from './run-DXy_MVwz.cjs';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
 
@@ -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

@@ -1,9 +1,9 @@
-import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-DFiY-NHK.js';
-export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, E as ErrorCode, m as ErrorMetadata, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-DFiY-NHK.js';
-import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as ProviderProfile, m as Plugin, n as ConversationStorageAdapter, o as StoredMessage, B as BudgetTracker, p as MemoryProvider, q as MemoryId, r as PreToolCallDecision, s as SDKProvider } from './cron-CL_9nfhQ.js';
-export { t as ActiveMemoryPassArgs, u as ActiveMemoryPassResult, v as AgentMemory, w as BudgetCheck, x as BudgetTotal, y as BudgetUsageEvent, z as CloudEnv, D as CloudRepo, E as ContextBudget, F as ContextManagerKind, H as ContextSnapshot, I as ContextSource, J as ContextSourceStatus, K as Cron, N as CronCreateOptions, O as CronGetOptions, Q as CronJob, R as CronJobStatus, T as CronListOptions, U as CronOperationOptions, V as CronRunOptions, W as CronRuntime, X as CronSchedulerStatus, Y as CronStartOptions, Z as GoalEvent, _ as GoalOptions, $ as GoalResult, a0 as HookName, a1 as InvalidateCacheOptions, a2 as MemoryAdapter, a3 as MemoryAdapterCapabilities, a4 as MemoryContext, a5 as MemoryFact, a6 as MemoryProviderHandle, a7 as MemoryProviderInitOptions, a8 as MemoryRevision, a9 as MemoryToolSchema, aa as MemoryTurnMessage, ab as PersonalityPreset, ac as PluginContext, ad as PostAssistantReplyContext, ae as PreToolCallContext, af as PreUserSendContext, ag as PreUserSendResult, ah as ProviderCapability, ai as ProviderRoute, aj as RecordSessionSummaryArgs, ak as ResolvedProviderRoute, al as RunUntilIterator, am as SDKAgentPlugins, an as SDKAgentSkills, ao as SDKArtifact, ap as SDKContextManager, aq as SDKPluginMetadata, ar as SDKProvidersManager, as as SettingSource, at as SystemPromptContext, au as SystemPromptMemoryFact, av as SystemPromptSkillRef, aw as TelemetrySettings, ax as definePlugin } from './cron-CL_9nfhQ.js';
-import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, S as SDKMessage } from './run-TMdc7gmo.js';
-export { A as AgentConversationTurn, c as AssistantMessage, d as ConversationStep, e as ConversationTurn, f as CostBreakdown, g as CostSource, h as CostStatus, I as InteractionUpdate, i as McpAuthConfig, j as McpHttpServerConfig, k as McpOAuthConfig, l as McpStdioServerConfig, m as ModelParameterValue, P as PartialToolCallUpdate, n as RunErrorDetail, o as RunGitInfo, p as RunOperation, q as RunStatus, r as RunToCompletionOptions, s as RunToCompletionResult, t as SDKAssistantMessage, u as SDKImage, v as SDKImageDimension, w as SDKObjectDelta, x as SDKRequestMessage, y as SDKStatusMessage, z as SDKSystemMessage, B as SDKTaskMessage, D as SDKThinkingMessage, E as SDKToolUseMessage, F as SDKUserMessage, G as SDKUserMessageEvent, H as SendOptions, J as ShellCommand, K as ShellConversationTurn, L as ShellOutput, N as ShellOutputDeltaUpdate, O as StepCompletedUpdate, Q as StepStartedUpdate, T as StreamToCompletionResult, U as SummaryCompletedUpdate, V as SummaryStartedUpdate, W as SummaryUpdate, X as TextBlock, Y as TextDeltaUpdate, Z as ThinkingCompletedUpdate, _ as ThinkingDeltaUpdate, $ as ThinkingMessage, a0 as TokenDeltaUpdate, a1 as TokenUsage, a2 as ToolCall, a3 as ToolCallCompletedUpdate, a4 as ToolCallStartedUpdate, a5 as ToolResult, a6 as ToolUseBlock, a7 as TurnEndedUpdate, a8 as UserMessage, a9 as UserMessageAppendedUpdate } from './run-TMdc7gmo.js';
+import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-DJuuubJK.js';
+export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, E as ErrorCode, m as ErrorMetadata, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-DJuuubJK.js';
+import { A as AgentOptions, L as LocalOptions, P as ProviderRoutingSettings, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as ContextSettings, c as PluginsSettings, d as SkillsSettings, e as SDKAgent, f as ListAgentsOptions, g as ListResult, h as SDKAgentInfo, G as GetAgentOptions, i as ListRunsOptions, j as GetRunOptions, k as AgentOperationOptions, l as ProviderProfile, m as Plugin, n as ConversationStorageAdapter, o as StoredMessage, B as BudgetTracker, p as MemoryProvider, q as MemoryId, r as PreToolCallDecision, s as SDKProvider } from './cron-DcaoP7aW.js';
+export { t as ActiveMemoryPassArgs, u as ActiveMemoryPassResult, v as AgentMemory, w as BudgetCheck, x as BudgetTotal, y as BudgetUsageEvent, z as CloudEnv, D as CloudRepo, E as ContextBudget, F as ContextManagerKind, H as ContextSnapshot, I as ContextSource, J as ContextSourceStatus, K as Cron, N as CronCreateOptions, O as CronGetOptions, Q as CronJob, R as CronJobStatus, T as CronListOptions, U as CronOperationOptions, V as CronRunOptions, W as CronRuntime, X as CronSchedulerStatus, Y as CronStartOptions, Z as GoalEvent, _ as GoalOptions, $ as GoalResult, a0 as HookName, a1 as InvalidateCacheOptions, a2 as MemoryAdapter, a3 as MemoryAdapterCapabilities, a4 as MemoryContext, a5 as MemoryFact, a6 as MemoryProviderHandle, a7 as MemoryProviderInitOptions, a8 as MemoryRevision, a9 as MemoryToolSchema, aa as MemoryTurnMessage, ab as PersonalityPreset, ac as PluginContext, ad as PostAssistantReplyContext, ae as PreToolCallContext, af as PreUserSendContext, ag as PreUserSendResult, ah as ProviderCapability, ai as ProviderRoute, aj as RecordSessionSummaryArgs, ak as ResolvedProviderRoute, al as RunUntilIterator, am as SDKAgentPlugins, an as SDKAgentSkills, ao as SDKArtifact, ap as SDKContextManager, aq as SDKPluginMetadata, ar as SDKProvidersManager, as as SettingSource, at as SystemPromptContext, au as SystemPromptMemoryFact, av as SystemPromptSkillRef, aw as TelemetrySettings, ax as definePlugin } from './cron-DcaoP7aW.js';
+import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, S as SDKMessage } from './run-DXy_MVwz.js';
+export { A as AgentConversationTurn, c as AssistantMessage, d as ConversationStep, e as ConversationTurn, f as CostBreakdown, g as CostSource, h as CostStatus, D as DoomLoopThresholds, I as InteractionUpdate, i as McpAuthConfig, j as McpHttpServerConfig, k as McpOAuthConfig, l as McpStdioServerConfig, m as ModelParameterValue, P as PartialToolCallUpdate, n as RunErrorDetail, o as RunGitInfo, p as RunOperation, q as RunStatus, r as RunToCompletionOptions, s as RunToCompletionResult, t as SDKAssistantMessage, u as SDKImage, v as SDKImageDimension, w as SDKObjectDelta, x as SDKRequestMessage, y as SDKStatusMessage, z as SDKSystemMessage, B as SDKTaskMessage, E as SDKThinkingMessage, F as SDKToolUseMessage, G as SDKUserMessage, H as SDKUserMessageEvent, J as SendOptions, K as ShellCommand, L as ShellConversationTurn, N as ShellOutput, O as ShellOutputDeltaUpdate, Q as StepCompletedUpdate, T as StepStartedUpdate, U as StreamToCompletionResult, V as SummaryCompletedUpdate, W as SummaryStartedUpdate, X as SummaryUpdate, Y as TextBlock, Z as TextDeltaUpdate, _ as ThinkingCompletedUpdate, $ as ThinkingDeltaUpdate, a0 as ThinkingMessage, a1 as TokenDeltaUpdate, a2 as TokenUsage, a3 as ToolCall, a4 as ToolCallCompletedUpdate, a5 as ToolCallStartedUpdate, a6 as ToolResult, a7 as ToolUseBlock, a8 as TurnEndedUpdate, a9 as UserMessage, aa as UserMessageAppendedUpdate } from './run-DXy_MVwz.js';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
 
@@ -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

@@ -2814,6 +2814,7 @@ function isEmptyRound(result) {
   return (result.result ?? "").trim() === "";
 }
 function classifyRound(result, round, maxRounds, emptyStreak) {
+  if (result.stoppedByDoomLoop === true) return "no_progress";
   if (result.stoppedAtIterationLimit !== true) return "done";
   if (isEmptyRound(result) && emptyStreak >= 1) return "no_progress";
   if (round >= maxRounds) return "step_limit";
@@ -6979,6 +6980,7 @@ function applyScriptMetrics(base, script) {
   if (script.usage !== void 0) base.usage = script.usage;
   if (script.cost !== void 0) base.cost = script.cost;
   if (script.stoppedAtIterationLimit === true) base.stoppedAtIterationLimit = true;
+  if (script.stoppedByDoomLoop === true) base.stoppedByDoomLoop = true;
 }
 
 // src/internal/runtime/cloud/cloud-run.ts
@@ -10730,6 +10732,93 @@ function evaluateBudgetGate(tracker) {
   }
 }
 
+// src/internal/agent-loop/doom-loop-tracker.ts
+init_errors();
+function createDoomLoopTracker(option) {
+  if (option === false) return void 0;
+  return new DoomLoopTracker(option);
+}
+var DEFAULT_CONFIG = { softThreshold: 3, hardThreshold: 5 };
+function assertValidThresholds(soft, hard) {
+  for (const [label, value] of [
+    ["softThreshold", soft],
+    ["hardThreshold", hard]
+  ]) {
+    if (!Number.isInteger(value) || value < 1) {
+      throw new ConfigurationError(
+        `doomLoop.${label} must be a positive integer (received ${value}).`,
+        { code: "invalid_doom_loop_threshold" }
+      );
+    }
+  }
+}
+function sortKeys(value) {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(sortKeys);
+  const out = {};
+  for (const key2 of Object.keys(value).sort()) {
+    out[key2] = sortKeys(value[key2]);
+  }
+  return out;
+}
+function signatureOf(call) {
+  const { input } = call;
+  let inputSig;
+  if (input === null || input === void 0) inputSig = "null";
+  else if (typeof input !== "object") inputSig = String(input);
+  else {
+    try {
+      inputSig = JSON.stringify(sortKeys(input)) ?? "null";
+    } catch {
+      inputSig = String(input);
+    }
+  }
+  return `${call.name}\0${inputSig}`;
+}
+var DoomLoopTracker = class {
+  #config;
+  #lastSignature = "";
+  #count = 0;
+  constructor(config) {
+    const softThreshold = config?.softThreshold ?? DEFAULT_CONFIG.softThreshold;
+    const hardThreshold = config?.hardThreshold ?? DEFAULT_CONFIG.hardThreshold;
+    assertValidThresholds(softThreshold, hardThreshold);
+    this.#config = { softThreshold, hardThreshold };
+  }
+  inspect(call) {
+    const signature = signatureOf(call);
+    this.#count = signature === this.#lastSignature ? this.#count + 1 : 1;
+    this.#lastSignature = signature;
+    const count = this.#count;
+    if (count >= this.#config.hardThreshold) {
+      return {
+        kind: "hard",
+        message: `Detected ${count} consecutive identical calls to \`${call.name}\`; stopping to avoid a loop.`
+      };
+    }
+    if (count === this.#config.softThreshold) {
+      return {
+        kind: "soft",
+        message: `Detected ${count} consecutive identical calls to \`${call.name}\`; try a different approach.`
+      };
+    }
+    return { kind: "ok" };
+  }
+  reset() {
+    this.#lastSignature = "";
+    this.#count = 0;
+  }
+};
+function firstDoomLoopVerdict(tracker, calls) {
+  let escalation = { kind: "ok" };
+  for (const call of calls) {
+    const v = tracker.inspect(call);
+    if (v.kind === "hard") return v;
+    if (v.kind === "soft" && escalation.kind === "ok") escalation = v;
+  }
+  return escalation;
+}
+
 // src/internal/budget/usage-accumulator.ts
 var UsageAccumulator = class {
   input = 0;
@@ -10910,6 +10999,7 @@ async function initLoopContext(inputs) {
     tools,
     finalText: "",
     finalStatus: "finished",
+    doomLoop: createDoomLoopTracker(inputs.doomLoop),
     usage: new UsageAccumulator(),
     nudgeAttempts: 0,
     stopFeedbackAttempts: 0,
@@ -11934,6 +12024,7 @@ async function runAgentLoop(inputs) {
       ctx.finalStatus = "error";
     }
     sendSpan?.setAttribute("status", ctx.finalStatus);
+    if (ctx.stoppedByDoomLoop === true) sendSpan?.setAttribute("stoppedByDoomLoop", true);
     if (inputs.telemetry?.includeContent === true && ctx.finalText.length > 0) {
       sendSpan?.addEvent("response", { content: ctx.finalText });
     }
@@ -11960,7 +12051,8 @@ async function runAgentLoop(inputs) {
       ...usage !== void 0 ? { usage } : {},
       ...cost !== void 0 ? { cost } : {},
       ...ctx.error !== void 0 ? { error: ctx.error } : {},
-      ...ctx.stoppedAtIterationLimit === true ? { stoppedAtIterationLimit: true } : {}
+      ...ctx.stoppedAtIterationLimit === true ? { stoppedAtIterationLimit: true } : {},
+      ...ctx.stoppedByDoomLoop === true ? { stoppedByDoomLoop: true } : {}
     };
   } finally {
     if (ctxRef !== void 0 && ctxRef.memoryProviderHandle !== void 0 && inputs.memoryProvider !== void 0) {
@@ -12119,8 +12211,26 @@ async function continueOrTerminate(inputs, ctx, llmOutput) {
     }
   }
   pushToolConversationSteps(ctx, llmOutput.toolCalls, toolResults);
+  if (await inspectDoomLoop(inputs, ctx, llmOutput.toolCalls) === "stop") return "done";
   return handleToolErrorContinuation(inputs, ctx, toolResults);
 }
+async function inspectDoomLoop(inputs, ctx, toolCalls) {
+  if (ctx.doomLoop === void 0) return "continue";
+  const verdict = firstDoomLoopVerdict(ctx.doomLoop, toolCalls);
+  if (verdict.kind === "hard") {
+    ctx.stoppedByDoomLoop = true;
+    await emitAssistantTextStep(
+      inputs,
+      ctx,
+      verdict.message ?? "Stopped: repeated identical tool calls made no progress."
+    );
+    return "stop";
+  }
+  if (verdict.kind === "soft") {
+    ctx.messages.push({ role: "user", content: [{ type: "text", text: verdict.message ?? "" }] });
+  }
+  return "continue";
+}
 
 // src/internal/llm/fallback-client.ts
 init_errors();
@@ -13424,6 +13534,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;
@@ -13449,9 +13668,9 @@ function parseHermesParams(inner) {
     const key2 = param[1];
     const value = param[2];
     if (key2 === void 0 || value === void 0) continue;
-    input[key2.trim()] = value.trim();
+    input[key2.trim()] = value;
   }
-  return input;
+  return sanitizeToolInput(input, { trim: true }).value;
 }
 
 // src/internal/llm/openai.ts
@@ -14572,6 +14791,8 @@ function buildLoopInputs(options, runId, userText) {
     // M1-2: per-send iteration ceiling (validated above). The loop reads
     // inputs.maxIterations (default 8 when unset).
     ...maxIterations !== void 0 ? { maxIterations } : {},
+    // Doom-loop guard config (default on; `false` disables, object tunes thresholds).
+    ...options.sendOptions.doomLoop !== void 0 ? { doomLoop: options.sendOptions.doomLoop } : {},
     // D315-D317 — tool lifecycle hooks (cost tracking + audit + retry/alert)
     ...options.agentOptions.onToolStart !== void 0 ? { onToolStart: options.agentOptions.onToolStart } : {},
     ...options.agentOptions.onToolEnd !== void 0 ? { onToolEnd: options.agentOptions.onToolEnd } : {},
@@ -14704,6 +14925,7 @@ var RealLocalRun = class extends FixtureRunBase {
     if (output.usage !== void 0) this.script.usage = output.usage;
     if (output.cost !== void 0) this.script.cost = output.cost;
     if (output.stoppedAtIterationLimit === true) this.script.stoppedAtIterationLimit = true;
+    if (output.stoppedByDoomLoop === true) this.script.stoppedByDoomLoop = true;
     if (output.error !== void 0 && this.script.errorDetail === void 0) {
       this.script.errorDetail = {
         message: output.error.message,
@@ -18172,7 +18394,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);
     }
   };