@theokit/sdk 2.23.0 → 2.24.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
-import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-CkCaIqVP.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, m as ErrorCode, 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-CkCaIqVP.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, p as SessionMeta, q as SessionMetaPatch, B as BudgetTracker, r as MemoryProvider, s as MemoryId, t as PreToolCallDecision, u as SDKProvider } from './cron-Bpt_1khA.cjs';
-export { v as ActiveMemoryPassArgs, w as ActiveMemoryPassResult, x as AgentMemory, y as BudgetCheck, z as BudgetTotal, D as BudgetUsageEvent, E as CloudEnv, F as CloudRepo, H as ContextBudget, I as ContextManagerKind, J as ContextSnapshot, K as ContextSource, N as ContextSourceStatus, O as CreateSkillSpec, Q as Cron, R as CronCreateOptions, T as CronGetOptions, U as CronJob, V as CronJobStatus, W as CronListOptions, X as CronOperationOptions, Y as CronRunOptions, Z as CronRuntime, _ as CronSchedulerStatus, $ as CronStartOptions, a0 as GoalEvent, a1 as GoalOptions, a2 as GoalResult, a3 as HookName, a4 as InlineSkill, a5 as InvalidateCacheOptions, a6 as MemoryAdapter, a7 as MemoryAdapterCapabilities, a8 as MemoryContext, a9 as MemoryFact, aa as MemoryProviderHandle, ab as MemoryProviderInitOptions, ac as MemoryRevision, ad as MemoryToolSchema, ae as MemoryTurnMessage, af as PersonalityPreset, ag as PluginContext, ah as PostAssistantReplyContext, ai as PreToolCallContext, aj as PreUserSendContext, ak as PreUserSendResult, al as ProviderCapability, am as ProviderRoute, an as RecordSessionSummaryArgs, ao as ResolvedProviderRoute, ap as RunUntilIterator, aq as SDKAgentPlugins, ar as SDKAgentSkills, as as SDKArtifact, at as SDKContextManager, au as SDKPluginMetadata, av as SDKProvidersManager, aw as SettingSource, ax as SystemPromptContext, ay as SystemPromptMemoryFact, az as SystemPromptSkillRef, aA as TelemetrySettings, aB as createSkill, aC as definePlugin } from './cron-Bpt_1khA.cjs';
-import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, S as SDKMessage, c as MessageOrigin, T as ToolResultContentBlock } from './run-CrIulPF7.cjs';
-export { A as AgentConversationTurn, d as AssistantMessage, e as ConversationStep, f as ConversationTurn, g as CostBreakdown, h as CostSource, i as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, j as GenerateRunResult, I as ImageBlock, k as InteractionUpdate, l as McpAuthConfig, m as McpHttpServerConfig, n as McpOAuthConfig, o as McpStdioServerConfig, p as ModelParameterValue, P as PartialToolCallUpdate, q as RunCompactBoundaryEvent, r as RunErrorDetail, s as RunEvent, t as RunEventSink, u as RunGitInfo, v as RunOperation, w as RunPermissionDeniedEvent, x as RunRateLimitEvent, y as RunStatus, z as RunTaskCompletedEvent, B as RunTaskStartedEvent, E as RunTaskUpdatedEvent, F as RunToCompletionOptions, H as RunToCompletionResult, J as RunToolProgressEvent, K as SDKAssistantMessage, L as SDKImage, N as SDKImageDimension, O as SDKObjectDelta, Q as SDKRequestMessage, U as SDKStatusMessage, V as SDKSystemMessage, W as SDKTaskMessage, X as SDKThinkingMessage, Y as SDKToolUseMessage, Z as SDKUserMessage, _ as SDKUserMessageEvent, $ as SendOptions, a0 as ShellCommand, a1 as ShellConversationTurn, a2 as ShellOutput, a3 as ShellOutputDeltaUpdate, a4 as StepCompletedUpdate, a5 as StepStartedUpdate, a6 as StreamToCompletionResult, a7 as SummaryCompletedUpdate, a8 as SummaryStartedUpdate, a9 as SummaryUpdate, aa as TextBlock, ab as TextDeltaUpdate, ac as ThinkingCompletedUpdate, ad as ThinkingDeltaUpdate, ae as ThinkingMessage, af as TokenDeltaUpdate, ag as TokenUsage, ah as ToolCall, ai as ToolCallCompletedUpdate, aj as ToolCallStartedUpdate, ak as ToolContextMessage, al as ToolResult, am as ToolResultGuardOptions, an as ToolUseBlock, ao as TurnEndedUpdate, ap as UserMessage, aq as UserMessageAppendedUpdate, ar as emitRunEvent } from './run-CrIulPF7.cjs';
+import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-DIKBXffg.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, m as ErrorCode, 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-DIKBXffg.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, p as SessionMeta, q as SessionMetaPatch, B as BudgetTracker, r as MemoryProvider, s as MemoryId, t as PreToolCallDecision, u as SDKProvider } from './cron-Bd2oRD7A.cjs';
+export { v as ActiveMemoryPassArgs, w as ActiveMemoryPassResult, x as AgentMemory, y as BudgetCheck, z as BudgetTotal, D as BudgetUsageEvent, E as CloudEnv, F as CloudRepo, H as ContextBudget, I as ContextManagerKind, J as ContextSnapshot, K as ContextSource, N as ContextSourceStatus, O as CreateSkillSpec, Q as Cron, R as CronCreateOptions, T as CronGetOptions, U as CronJob, V as CronJobStatus, W as CronListOptions, X as CronOperationOptions, Y as CronRunOptions, Z as CronRuntime, _ as CronSchedulerStatus, $ as CronStartOptions, a0 as GoalEvent, a1 as GoalOptions, a2 as GoalResult, a3 as HookName, a4 as InlineSkill, a5 as InvalidateCacheOptions, a6 as MemoryAdapter, a7 as MemoryAdapterCapabilities, a8 as MemoryContext, a9 as MemoryFact, aa as MemoryProviderHandle, ab as MemoryProviderInitOptions, ac as MemoryRevision, ad as MemoryToolSchema, ae as MemoryTurnMessage, af as PersonalityPreset, ag as PluginContext, ah as PostAssistantReplyContext, ai as PreToolCallContext, aj as PreUserSendContext, ak as PreUserSendResult, al as ProviderCapability, am as ProviderRoute, an as RecordSessionSummaryArgs, ao as ResolvedProviderRoute, ap as RunUntilIterator, aq as SDKAgentPlugins, ar as SDKAgentSkills, as as SDKArtifact, at as SDKContextManager, au as SDKPluginMetadata, av as SDKProvidersManager, aw as SettingSource, ax as SystemPromptContext, ay as SystemPromptMemoryFact, az as SystemPromptSkillRef, aA as TelemetrySettings, aB as createSkill, aC as definePlugin } from './cron-Bd2oRD7A.cjs';
+import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, T as ToolResultContentBlock, S as SDKMessage, c as MessageOrigin } from './run-Cr0C6cOM.cjs';
+export { A as AgentConversationTurn, d as AssistantMessage, e as ConversationStep, f as ConversationTurn, g as CostBreakdown, h as CostSource, i as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, j as GenerateRunResult, I as ImageBlock, k as InteractionUpdate, l as McpAuthConfig, m as McpHttpServerConfig, n as McpOAuthConfig, o as McpStdioServerConfig, p as ModelParameterValue, P as PartialToolCallUpdate, q as RunCompactBoundaryEvent, r as RunErrorDetail, s as RunEvent, t as RunEventSink, u as RunGitInfo, v as RunOperation, w as RunPermissionDeniedEvent, x as RunRateLimitEvent, y as RunStatus, z as RunTaskCompletedEvent, B as RunTaskStartedEvent, E as RunTaskUpdatedEvent, F as RunToCompletionOptions, H as RunToCompletionResult, J as RunToolProgressEvent, K as SDKAssistantMessage, L as SDKImage, N as SDKImageDimension, O as SDKObjectDelta, Q as SDKRequestMessage, U as SDKStatusMessage, V as SDKSystemMessage, W as SDKTaskMessage, X as SDKThinkingMessage, Y as SDKToolUseMessage, Z as SDKUserMessage, _ as SDKUserMessageEvent, $ as SendOptions, a0 as ShellCommand, a1 as ShellConversationTurn, a2 as ShellOutput, a3 as ShellOutputDeltaUpdate, a4 as StepCompletedUpdate, a5 as StepStartedUpdate, a6 as StreamToCompletionResult, a7 as SummaryCompletedUpdate, a8 as SummaryStartedUpdate, a9 as SummaryUpdate, aa as TextBlock, ab as TextDeltaUpdate, ac as ThinkingCompletedUpdate, ad as ThinkingDeltaUpdate, ae as ThinkingMessage, af as TokenDeltaUpdate, ag as TokenUsage, ah as ToolCall, ai as ToolCallCompletedUpdate, aj as ToolCallStartedUpdate, ak as ToolContextMessage, al as ToolResult, am as ToolResultGuardOptions, an as ToolUseBlock, ao as TurnEndedUpdate, ap as UserMessage, aq as UserMessageAppendedUpdate, ar as emitRunEvent } from './run-Cr0C6cOM.cjs';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
 
@@ -918,7 +918,14 @@ interface SanitizeOptions {
  *
  * @public
  */
-interface DefineToolSpec<T extends ZodType> {
+/**
+ * SE16 — the handler's return type. With no `outputSchema` the tool returns a
+ * plain `string` (pre-SE16 shape). With an `outputSchema` the handler returns the
+ * STRUCTURED output inferred from it (validated + serialized to the tool result).
+ * The `[O]` tuple wrap prevents distribution so `never` maps cleanly to `string`.
+ */
+type ToolHandlerReturn<O extends ZodType> = [O] extends [never] ? string : z.infer<O>;
+interface DefineToolSpec<T extends ZodType, O extends ZodType = never> {
     /** Tool name surfaced to the LLM. Same constraints as {@link CustomTool.name}. */
     name: string;
     /** Description surfaced to the LLM. */
@@ -926,7 +933,16 @@ interface DefineToolSpec<T extends ZodType> {
     /** Zod schema describing the input. Must be `z.object(...)` at the root for the LLM tool contract. */
     inputSchema: T;
     /**
-     * Handler invoked with the parsed input. Type is inferred via `z.infer<T>`.
+     * SE16 — optional Zod schema describing the OUTPUT. When set, the handler
+     * returns the structured value inferred from it; the value is validated against
+     * this schema and serialized to the tool result (a string stays as-is, an object
+     * is JSON-stringified). A validation failure raises `ZodError`, converted to a
+     * `tool_result(isError)`. Absent ⇒ the handler returns a plain string (unchanged).
+     */
+    outputSchema?: O;
+    /**
+     * Handler invoked with the parsed input. Type is inferred via `z.infer<T>`; the
+     * return type is `z.infer<O>` when `outputSchema` is set, else `string`.
      * #65 — an optional 2nd `ToolContext` argument carries the run's `AbortSignal`,
      * so a cooperative handler can stop early when the run is cancelled. Existing
      * single-argument handlers are unaffected.
@@ -934,7 +950,18 @@ interface DefineToolSpec<T extends ZodType> {
     handler: (input: z.infer<T>, ctx?: {
         signal?: AbortSignal;
         context?: unknown;
-    }) => string | Promise<string>;
+    }) => ToolHandlerReturn<O> | Promise<ToolHandlerReturn<O>>;
+    /**
+     * SE17 — map the handler's (validated) output to the compact / multimodal
+     * representation the MODEL sees in the tool_result. The handler keeps returning
+     * the FULL result (validated by `outputSchema`); `toModelOutput` shapes only what
+     * reaches the model, so app-facing detail is not forced into model context.
+     * Returns a string OR SE7 `ToolResultContentBlock[]` (text + image). Absent ⇒
+     * the tool_result is the serialized handler output (SE16 / pre-SE17 behavior).
+     * Note: observability (`onToolEnd`) sees the model-facing result this returns,
+     * not the raw handler output — the full result lives in the handler's own scope.
+     */
+    toModelOutput?: (output: ToolHandlerReturn<O>) => string | ToolResultContentBlock[];
     /**
      * 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
@@ -943,23 +970,7 @@ interface DefineToolSpec<T extends ZodType> {
      */
     sanitize?: boolean | SanitizeOptions;
 }
-/**
- * Type-safe builder for {@link CustomTool}. Converts a Zod schema to JSON
- * Schema (for the LLM-facing `inputSchema` field), wraps the handler with a
- * runtime `schema.parse` step, and preserves type inference.
- *
- * Behaviour (ADR D24):
- * - JSON Schema conversion uses Zod 4's native `z.toJSONSchema` with
- *   `unrepresentable: "any"` so transforms/refinements round-trip.
- * - Runtime parse failures throw `ZodError`; the SDK's tool-dispatch converts
- *   them to `tool_result(isError)` with the Zod message.
- * - Handler signature is `(input: z.infer<T>)`, not `Record<string, unknown>`.
- * - `zod` loads lazily via `createRequire` — consumers who don't call
- *   `defineTool` don't need `zod` installed.
- *
- * @public
- */
-declare function defineTool<T extends ZodType>(spec: DefineToolSpec<T>): CustomTool;
+declare function defineTool<T extends ZodType, O extends ZodType = never>(spec: DefineToolSpec<T, O>): CustomTool;
 
 /**
  * `EventBus` — typed EventEmitter wrapper.

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-BuwwkrAk.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, m as ErrorCode, 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-BuwwkrAk.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, p as SessionMeta, q as SessionMetaPatch, B as BudgetTracker, r as MemoryProvider, s as MemoryId, t as PreToolCallDecision, u as SDKProvider } from './cron-7CruUd_0.js';
-export { v as ActiveMemoryPassArgs, w as ActiveMemoryPassResult, x as AgentMemory, y as BudgetCheck, z as BudgetTotal, D as BudgetUsageEvent, E as CloudEnv, F as CloudRepo, H as ContextBudget, I as ContextManagerKind, J as ContextSnapshot, K as ContextSource, N as ContextSourceStatus, O as CreateSkillSpec, Q as Cron, R as CronCreateOptions, T as CronGetOptions, U as CronJob, V as CronJobStatus, W as CronListOptions, X as CronOperationOptions, Y as CronRunOptions, Z as CronRuntime, _ as CronSchedulerStatus, $ as CronStartOptions, a0 as GoalEvent, a1 as GoalOptions, a2 as GoalResult, a3 as HookName, a4 as InlineSkill, a5 as InvalidateCacheOptions, a6 as MemoryAdapter, a7 as MemoryAdapterCapabilities, a8 as MemoryContext, a9 as MemoryFact, aa as MemoryProviderHandle, ab as MemoryProviderInitOptions, ac as MemoryRevision, ad as MemoryToolSchema, ae as MemoryTurnMessage, af as PersonalityPreset, ag as PluginContext, ah as PostAssistantReplyContext, ai as PreToolCallContext, aj as PreUserSendContext, ak as PreUserSendResult, al as ProviderCapability, am as ProviderRoute, an as RecordSessionSummaryArgs, ao as ResolvedProviderRoute, ap as RunUntilIterator, aq as SDKAgentPlugins, ar as SDKAgentSkills, as as SDKArtifact, at as SDKContextManager, au as SDKPluginMetadata, av as SDKProvidersManager, aw as SettingSource, ax as SystemPromptContext, ay as SystemPromptMemoryFact, az as SystemPromptSkillRef, aA as TelemetrySettings, aB as createSkill, aC as definePlugin } from './cron-7CruUd_0.js';
-import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, S as SDKMessage, c as MessageOrigin, T as ToolResultContentBlock } from './run-CrIulPF7.js';
-export { A as AgentConversationTurn, d as AssistantMessage, e as ConversationStep, f as ConversationTurn, g as CostBreakdown, h as CostSource, i as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, j as GenerateRunResult, I as ImageBlock, k as InteractionUpdate, l as McpAuthConfig, m as McpHttpServerConfig, n as McpOAuthConfig, o as McpStdioServerConfig, p as ModelParameterValue, P as PartialToolCallUpdate, q as RunCompactBoundaryEvent, r as RunErrorDetail, s as RunEvent, t as RunEventSink, u as RunGitInfo, v as RunOperation, w as RunPermissionDeniedEvent, x as RunRateLimitEvent, y as RunStatus, z as RunTaskCompletedEvent, B as RunTaskStartedEvent, E as RunTaskUpdatedEvent, F as RunToCompletionOptions, H as RunToCompletionResult, J as RunToolProgressEvent, K as SDKAssistantMessage, L as SDKImage, N as SDKImageDimension, O as SDKObjectDelta, Q as SDKRequestMessage, U as SDKStatusMessage, V as SDKSystemMessage, W as SDKTaskMessage, X as SDKThinkingMessage, Y as SDKToolUseMessage, Z as SDKUserMessage, _ as SDKUserMessageEvent, $ as SendOptions, a0 as ShellCommand, a1 as ShellConversationTurn, a2 as ShellOutput, a3 as ShellOutputDeltaUpdate, a4 as StepCompletedUpdate, a5 as StepStartedUpdate, a6 as StreamToCompletionResult, a7 as SummaryCompletedUpdate, a8 as SummaryStartedUpdate, a9 as SummaryUpdate, aa as TextBlock, ab as TextDeltaUpdate, ac as ThinkingCompletedUpdate, ad as ThinkingDeltaUpdate, ae as ThinkingMessage, af as TokenDeltaUpdate, ag as TokenUsage, ah as ToolCall, ai as ToolCallCompletedUpdate, aj as ToolCallStartedUpdate, ak as ToolContextMessage, al as ToolResult, am as ToolResultGuardOptions, an as ToolUseBlock, ao as TurnEndedUpdate, ap as UserMessage, aq as UserMessageAppendedUpdate, ar as emitRunEvent } from './run-CrIulPF7.js';
+import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-DRS-kqOK.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, m as ErrorCode, 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-DRS-kqOK.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, p as SessionMeta, q as SessionMetaPatch, B as BudgetTracker, r as MemoryProvider, s as MemoryId, t as PreToolCallDecision, u as SDKProvider } from './cron-vjod0qVQ.js';
+export { v as ActiveMemoryPassArgs, w as ActiveMemoryPassResult, x as AgentMemory, y as BudgetCheck, z as BudgetTotal, D as BudgetUsageEvent, E as CloudEnv, F as CloudRepo, H as ContextBudget, I as ContextManagerKind, J as ContextSnapshot, K as ContextSource, N as ContextSourceStatus, O as CreateSkillSpec, Q as Cron, R as CronCreateOptions, T as CronGetOptions, U as CronJob, V as CronJobStatus, W as CronListOptions, X as CronOperationOptions, Y as CronRunOptions, Z as CronRuntime, _ as CronSchedulerStatus, $ as CronStartOptions, a0 as GoalEvent, a1 as GoalOptions, a2 as GoalResult, a3 as HookName, a4 as InlineSkill, a5 as InvalidateCacheOptions, a6 as MemoryAdapter, a7 as MemoryAdapterCapabilities, a8 as MemoryContext, a9 as MemoryFact, aa as MemoryProviderHandle, ab as MemoryProviderInitOptions, ac as MemoryRevision, ad as MemoryToolSchema, ae as MemoryTurnMessage, af as PersonalityPreset, ag as PluginContext, ah as PostAssistantReplyContext, ai as PreToolCallContext, aj as PreUserSendContext, ak as PreUserSendResult, al as ProviderCapability, am as ProviderRoute, an as RecordSessionSummaryArgs, ao as ResolvedProviderRoute, ap as RunUntilIterator, aq as SDKAgentPlugins, ar as SDKAgentSkills, as as SDKArtifact, at as SDKContextManager, au as SDKPluginMetadata, av as SDKProvidersManager, aw as SettingSource, ax as SystemPromptContext, ay as SystemPromptMemoryFact, az as SystemPromptSkillRef, aA as TelemetrySettings, aB as createSkill, aC as definePlugin } from './cron-vjod0qVQ.js';
+import { R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, b as Run, T as ToolResultContentBlock, S as SDKMessage, c as MessageOrigin } from './run-Cr0C6cOM.js';
+export { A as AgentConversationTurn, d as AssistantMessage, e as ConversationStep, f as ConversationTurn, g as CostBreakdown, h as CostSource, i as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, j as GenerateRunResult, I as ImageBlock, k as InteractionUpdate, l as McpAuthConfig, m as McpHttpServerConfig, n as McpOAuthConfig, o as McpStdioServerConfig, p as ModelParameterValue, P as PartialToolCallUpdate, q as RunCompactBoundaryEvent, r as RunErrorDetail, s as RunEvent, t as RunEventSink, u as RunGitInfo, v as RunOperation, w as RunPermissionDeniedEvent, x as RunRateLimitEvent, y as RunStatus, z as RunTaskCompletedEvent, B as RunTaskStartedEvent, E as RunTaskUpdatedEvent, F as RunToCompletionOptions, H as RunToCompletionResult, J as RunToolProgressEvent, K as SDKAssistantMessage, L as SDKImage, N as SDKImageDimension, O as SDKObjectDelta, Q as SDKRequestMessage, U as SDKStatusMessage, V as SDKSystemMessage, W as SDKTaskMessage, X as SDKThinkingMessage, Y as SDKToolUseMessage, Z as SDKUserMessage, _ as SDKUserMessageEvent, $ as SendOptions, a0 as ShellCommand, a1 as ShellConversationTurn, a2 as ShellOutput, a3 as ShellOutputDeltaUpdate, a4 as StepCompletedUpdate, a5 as StepStartedUpdate, a6 as StreamToCompletionResult, a7 as SummaryCompletedUpdate, a8 as SummaryStartedUpdate, a9 as SummaryUpdate, aa as TextBlock, ab as TextDeltaUpdate, ac as ThinkingCompletedUpdate, ad as ThinkingDeltaUpdate, ae as ThinkingMessage, af as TokenDeltaUpdate, ag as TokenUsage, ah as ToolCall, ai as ToolCallCompletedUpdate, aj as ToolCallStartedUpdate, ak as ToolContextMessage, al as ToolResult, am as ToolResultGuardOptions, an as ToolUseBlock, ao as TurnEndedUpdate, ap as UserMessage, aq as UserMessageAppendedUpdate, ar as emitRunEvent } from './run-Cr0C6cOM.js';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
 
@@ -918,7 +918,14 @@ interface SanitizeOptions {
  *
  * @public
  */
-interface DefineToolSpec<T extends ZodType> {
+/**
+ * SE16 — the handler's return type. With no `outputSchema` the tool returns a
+ * plain `string` (pre-SE16 shape). With an `outputSchema` the handler returns the
+ * STRUCTURED output inferred from it (validated + serialized to the tool result).
+ * The `[O]` tuple wrap prevents distribution so `never` maps cleanly to `string`.
+ */
+type ToolHandlerReturn<O extends ZodType> = [O] extends [never] ? string : z.infer<O>;
+interface DefineToolSpec<T extends ZodType, O extends ZodType = never> {
     /** Tool name surfaced to the LLM. Same constraints as {@link CustomTool.name}. */
     name: string;
     /** Description surfaced to the LLM. */
@@ -926,7 +933,16 @@ interface DefineToolSpec<T extends ZodType> {
     /** Zod schema describing the input. Must be `z.object(...)` at the root for the LLM tool contract. */
     inputSchema: T;
     /**
-     * Handler invoked with the parsed input. Type is inferred via `z.infer<T>`.
+     * SE16 — optional Zod schema describing the OUTPUT. When set, the handler
+     * returns the structured value inferred from it; the value is validated against
+     * this schema and serialized to the tool result (a string stays as-is, an object
+     * is JSON-stringified). A validation failure raises `ZodError`, converted to a
+     * `tool_result(isError)`. Absent ⇒ the handler returns a plain string (unchanged).
+     */
+    outputSchema?: O;
+    /**
+     * Handler invoked with the parsed input. Type is inferred via `z.infer<T>`; the
+     * return type is `z.infer<O>` when `outputSchema` is set, else `string`.
      * #65 — an optional 2nd `ToolContext` argument carries the run's `AbortSignal`,
      * so a cooperative handler can stop early when the run is cancelled. Existing
      * single-argument handlers are unaffected.
@@ -934,7 +950,18 @@ interface DefineToolSpec<T extends ZodType> {
     handler: (input: z.infer<T>, ctx?: {
         signal?: AbortSignal;
         context?: unknown;
-    }) => string | Promise<string>;
+    }) => ToolHandlerReturn<O> | Promise<ToolHandlerReturn<O>>;
+    /**
+     * SE17 — map the handler's (validated) output to the compact / multimodal
+     * representation the MODEL sees in the tool_result. The handler keeps returning
+     * the FULL result (validated by `outputSchema`); `toModelOutput` shapes only what
+     * reaches the model, so app-facing detail is not forced into model context.
+     * Returns a string OR SE7 `ToolResultContentBlock[]` (text + image). Absent ⇒
+     * the tool_result is the serialized handler output (SE16 / pre-SE17 behavior).
+     * Note: observability (`onToolEnd`) sees the model-facing result this returns,
+     * not the raw handler output — the full result lives in the handler's own scope.
+     */
+    toModelOutput?: (output: ToolHandlerReturn<O>) => string | ToolResultContentBlock[];
     /**
      * 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
@@ -943,23 +970,7 @@ interface DefineToolSpec<T extends ZodType> {
      */
     sanitize?: boolean | SanitizeOptions;
 }
-/**
- * Type-safe builder for {@link CustomTool}. Converts a Zod schema to JSON
- * Schema (for the LLM-facing `inputSchema` field), wraps the handler with a
- * runtime `schema.parse` step, and preserves type inference.
- *
- * Behaviour (ADR D24):
- * - JSON Schema conversion uses Zod 4's native `z.toJSONSchema` with
- *   `unrepresentable: "any"` so transforms/refinements round-trip.
- * - Runtime parse failures throw `ZodError`; the SDK's tool-dispatch converts
- *   them to `tool_result(isError)` with the Zod message.
- * - Handler signature is `(input: z.infer<T>)`, not `Record<string, unknown>`.
- * - `zod` loads lazily via `createRequire` — consumers who don't call
- *   `defineTool` don't need `zod` installed.
- *
- * @public
- */
-declare function defineTool<T extends ZodType>(spec: DefineToolSpec<T>): CustomTool;
+declare function defineTool<T extends ZodType, O extends ZodType = never>(spec: DefineToolSpec<T, O>): CustomTool;
 
 /**
  * `EventBus` — typed EventEmitter wrapper.

package/dist/index.js

@@ -15785,6 +15785,7 @@ function levenshtein(a, b) {
 }
 
 // src/internal/runtime/local-agent/real-local-run.ts
+init_async_local_storage();
 function createRealLocalRun(options) {
   const { userText, id, startTime } = prepareRunContext(options.message);
   const supported = /* @__PURE__ */ new Set(["stream", "wait", "cancel", "conversation"]);
@@ -15896,6 +15897,7 @@ function buildLoopInputs(options, runId, userText) {
     ...options.onStep !== void 0 ? { onStep: options.onStep } : {},
     ...options.onDelta !== void 0 ? { onDelta: options.onDelta } : {},
     ...options.sendOptions.toolChoice !== void 0 ? { toolChoice: options.sendOptions.toolChoice } : {},
+    ...options.sendOptions.activeTools !== void 0 ? { activeTools: options.sendOptions.activeTools } : {},
     ...options.priorMessages !== void 0 ? { priorMessages: options.priorMessages } : {},
     ...options.memoryTools !== void 0 && options.memoryTools.length > 0 ? { memoryTools: options.memoryTools } : {},
     ...buildCustomToolsInput(
@@ -16026,7 +16028,7 @@ var RealLocalRun = class extends FixtureRunBase {
   }
   async executeAgentLoop(inputs) {
     try {
-      const output = await runAgentLoop(inputs);
+      const output = inputs.activeTools !== void 0 ? await withToolWhitelist(new Set(inputs.activeTools), () => runAgentLoop(inputs)) : await runAgentLoop(inputs);
       this.applyAgentLoopOutput(output);
       this.transitionTo(output.finalStatus);
     } catch (cause) {
@@ -19512,6 +19514,11 @@ function defineProvider(profile, opts) {
 
 // src/define-tool.ts
 init_to_json_schema();
+function shapeToolResult(spec, out) {
+  const validated = spec.outputSchema === void 0 ? out : spec.outputSchema.parse(out);
+  if (spec.toModelOutput !== void 0) return spec.toModelOutput(validated);
+  return typeof validated === "string" ? validated : JSON.stringify(validated);
+}
 function defineTool(spec) {
   const inputSchema = toJsonSchema(spec.inputSchema, {
     unrepresentable: "any"
@@ -19526,7 +19533,8 @@ function defineTool(spec) {
         schema: spec.inputSchema
       }).value : input;
       const parsed = spec.inputSchema.parse(raw);
-      return await spec.handler(parsed, ctx);
+      const out = await spec.handler(parsed, ctx);
+      return shapeToolResult(spec, out);
     }
   };
 }