@theokit/sdk 2.22.0 → 2.24.0

package/dist/define-tool.d.ts

@@ -1,13 +1,21 @@
 import type { z as ZodNamespace, ZodType } from "zod";
 import type { SanitizeOptions } from "./sanitize/types.js";
 import type { CustomTool } from "./types/agent.js";
+import type { ToolResultContentBlock } from "./types/content-blocks.js";
 /**
  * Spec accepted by {@link defineTool}. `inputSchema` is a Zod schema; the
  * `handler` argument type is inferred via `z.infer<T>` — no `as` casts.
  *
  * @public
  */
-export 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 : ZodNamespace.infer<O>;
+export 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. */
@@ -15,7 +23,16 @@ export 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.
@@ -23,7 +40,18 @@ export interface DefineToolSpec<T extends ZodType> {
     handler: (input: ZodNamespace.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
@@ -32,20 +60,5 @@ export 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
- */
-export declare function defineTool<T extends ZodType>(spec: DefineToolSpec<T>): CustomTool;
+export declare function defineTool<T extends ZodType, O extends ZodType = never>(spec: DefineToolSpec<T, O>): CustomTool;
+export {};

package/dist/{errors-CkCaIqVP.d.cts → errors-DIKBXffg.d.cts}

@@ -1,4 +1,4 @@
-import { v as RunOperation } from './run-CrIulPF7.cjs';
+import { v as RunOperation } from './run-Cr0C6cOM.cjs';
 
 /**
  * Public type contract for the Budget enforcement primitive

package/dist/{errors-BuwwkrAk.d.ts → errors-DRS-kqOK.d.ts}

@@ -1,4 +1,4 @@
-import { v as RunOperation } from './run-CrIulPF7.js';
+import { v as RunOperation } from './run-Cr0C6cOM.js';
 
 /**
  * Public type contract for the Budget enforcement primitive

package/dist/errors.d.cts

@@ -1,3 +1,3 @@
-export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, g as BudgetExceededError, C as ConfigurationError, u as CredentialPoolExhaustedError, m as ErrorCode, E as ErrorMetadata, I as IntegrationNotConnectedError, n as InvalidTaskIdError, K as KnownAgentRunErrorCode, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, T as TheokitAgentError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-CkCaIqVP.cjs';
-import './run-CrIulPF7.cjs';
+export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, g as BudgetExceededError, C as ConfigurationError, u as CredentialPoolExhaustedError, m as ErrorCode, E as ErrorMetadata, I as IntegrationNotConnectedError, n as InvalidTaskIdError, K as KnownAgentRunErrorCode, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, T as TheokitAgentError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-DIKBXffg.cjs';
+import './run-Cr0C6cOM.cjs';
 import 'zod';

package/dist/eval.cjs

@@ -13302,6 +13302,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"]);
@@ -13413,6 +13414,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(
@@ -13543,7 +13545,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) {