kernl 0.1.1

package/dist/thread/index.d.ts

@@ -0,0 +1,2 @@
+export { Thread } from "./thread";
+//# sourceMappingURL=index.d.ts.map

package/dist/thread/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/thread/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC"}

package/dist/thread/index.js

@@ -0,0 +1 @@
+export { Thread } from "./thread";

package/dist/thread/thread.d.ts

@@ -0,0 +1,66 @@
+import { Kernl } from "../kernl";
+import { Agent } from "../agent";
+import { Context } from "../context";
+import type { Task } from "../task";
+import { LanguageModel, LanguageModelResponse } from "@kernl/protocol";
+import type { ThreadEvent, ThreadOptions, ThreadExecuteResult } from "../types/thread";
+import type { AgentResponseType } from "../types/agent";
+import type { ResolvedAgentResponse } from "../guardrail";
+/**
+ * A thread drives the execution loop for an agent.
+ */
+export declare class Thread<TContext = unknown, TResponse extends AgentResponseType = "text"> {
+    private kernl;
+    readonly id: string;
+    readonly agent: Agent<TContext, TResponse>;
+    readonly context: Context<TContext>;
+    readonly model: LanguageModel;
+    readonly parent: Task<TContext> | null;
+    readonly mode: "blocking" | "stream";
+    readonly state: ThreadState;
+    readonly input: ThreadEvent[] | string;
+    private history;
+    constructor(kernl: Kernl, agent: Agent<TContext, TResponse>, input: ThreadEvent[] | string, options?: ThreadOptions<TContext>);
+    /**
+     * Main thread execution loop - runs until terminal state or interruption
+     */
+    execute(): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>>;
+    /**
+     * A single tick of the thread's execution.
+     *
+     * Prepares the input for the model, gets the response, and then parses into a TickResult
+     * with the events generated and the model's intentions (actions).
+     */
+    private tick;
+    /**
+     * Perform the actions returned by the model
+     */
+    private performActions;
+    /**
+     * Execute function calls requested by the model
+     *
+     * TODO: refactor into actions system
+     */
+    private executeTools;
+    /**
+     * Applies call-level filters and prepares the model request for the language model
+     */
+    private prepareModelRequest;
+    /**
+     * @internal
+     * Parses the model's response into events (for history) and actions (for execution).
+     */
+    private parseModelResponse;
+}
+/**
+ * ThreadState tracks the execution state of a single thread.
+ *
+ * A thread is created each time a task is scheduled and executes
+ * the main tick() loop until terminal state.
+ */
+export declare class ThreadState {
+    tick: number;
+    modelResponses: LanguageModelResponse[];
+    constructor();
+}
+//# sourceMappingURL=thread.d.ts.map

package/dist/thread/thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/thread/thread.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAEnC,OAAO,EAEL,aAAa,EAEb,qBAAqB,EAGtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,KAAK,EAEV,WAAW,EACX,aAAa,EACb,mBAAmB,EAGpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAIzD;;GAEG;AACH,qBAAa,MAAM,CACjB,QAAQ,GAAG,OAAO,EAClB,SAAS,SAAS,iBAAiB,GAAG,MAAM;IAE5C,OAAO,CAAC,KAAK,CAAQ;IAErB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC;IAGrC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,CAAC;IACvC,OAAO,CAAC,OAAO,CAAsE;gBAGnF,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,EACjC,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,EAC7B,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC;IAgCnC;;OAEG;IACG,OAAO,IAAI,OAAO,CACtB,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CACtD;IAmDD;;;;;OAKG;YACW,IAAI;IAmClB;;OAEG;YACW,cAAc;IAmC5B;;;;OAIG;YACW,YAAY;IA4C1B;;OAEG;YACW,mBAAmB;IA4CjC;;;OAGG;IACH,OAAO,CAAC,kBAAkB;CAqB3B;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IACtB,IAAI,EAAE,MAAM,CAAwE;IACpF,cAAc,EAAE,qBAAqB,EAAE,CAAmE;;CAiB3G"}

package/dist/thread/thread.js

@@ -0,0 +1,472 @@
+import assert from "assert";
+import { Context } from "../context";
+import { FAILED, } from "@kernl/protocol";
+import { randomID, filter } from "@kernl/shared/lib";
+import { getFinalResponse, parseFinalResponse } from "./utils";
+/**
+ * A thread drives the execution loop for an agent.
+ */
+export class Thread {
+    kernl;
+    id;
+    agent;
+    context;
+    model; /* inherited from the agent unless specified */
+    parent; /* parent task which spawned this thread */
+    mode; /* TODO */
+    /* state */
+    state;
+    input; /* the initial input for the thread */
+    history;
+    constructor(kernl, agent, input, options) {
+        this.id = `tid_${randomID()}`;
+        this.agent = agent;
+        this.context = options?.context ?? new Context();
+        this.kernl = kernl;
+        this.parent = options?.task ?? null;
+        this.model = options?.model ?? agent.model;
+        this.state = new ThreadState(); // (TODO): checkpoint ?? new ThreadState()
+        this.mode = "blocking"; // (TODO): add streaming
+        this.input = input;
+        // Convert string input to user message and initialize history
+        if (typeof input === "string") {
+            this.history = [
+                {
+                    kind: "message",
+                    id: `msg_${randomID()}`,
+                    role: "user",
+                    content: [
+                        {
+                            kind: "text",
+                            text: input,
+                        },
+                    ],
+                },
+            ];
+        }
+        else {
+            this.history = input;
+        }
+    }
+    /**
+     * Main thread execution loop - runs until terminal state or interruption
+     */
+    async execute() {
+        while (true) {
+            const { events, intentions } = await this.tick(); // actions: { syscalls, functions, mcpApprovalRequests }
+            this.history.push(...events);
+            // // priority 1: syscalls first - these override all other actions
+            // if (actions.syscalls.length > 0) {
+            //   switch (actions.syscalls.kind) { // is it possible to have more than one?
+            //     case SYS_WAIT:
+            //       return this.state;
+            //     case SYS_EXIT:
+            //       return { state: this.state, output: this.output }
+            //     default:
+            //   }
+            // }
+            // if model returns a message with no actions intentions -> terminal state
+            if (!intentions) {
+                const text = getFinalResponse(events);
+                if (!text)
+                    continue; // run again, policy-dependent?
+                const parsed = parseFinalResponse(text, this.agent.responseType);
+                // await this.agent.runOutputGuardails(context, state);
+                // this.kernl.emit("thread.terminated", context, output);
+                return { response: parsed, state: this.state };
+            }
+            // perform the actions intended by the model
+            const { actions, pendingApprovals } = await this.performActions(intentions);
+            this.history.push(...actions);
+            if (pendingApprovals.length > 0) {
+                // publish a batch approval request containing all of them
+                //
+                // const reqid = randomID();
+                // this.kernl.publish(channel, approvalRequest);
+                //
+                // const filter = { reqid }
+                // await wait_event(Action.ApprovalResponse, filter);
+            }
+        }
+    }
+    // ----------------------
+    // Internal helpers
+    // ----------------------
+    /**
+     * A single tick of the thread's execution.
+     *
+     * Prepares the input for the model, gets the response, and then parses into a TickResult
+     * with the events generated and the model's intentions (actions).
+     */
+    async tick() {
+        this.state.tick++;
+        // // check limits
+        // if (this.state.tick > this.limits.maxTicks) {
+        //   throw new RuntimeError("resource_limit:max_ticks_exceeded");
+        // }
+        // run guardrails on the first tick
+        if (this.state.tick === 1) {
+            // await this.agent.runInputGuardrails(this.context, ...?);
+        }
+        const req = await this.prepareModelRequest(this.history); // (TODO): how to get input for this tick?
+        // if (this.mode === "stream") {
+        // const stream = this.model.stream(input, {
+        //   system: systemPrompt,
+        //   tools: this.agent.tools /* [systools, tools] */,
+        //   settings: this.agent.modelSettings,
+        //   responseSchema: this.agent.responseType,
+        // });
+        // for await (const event of stream) {
+        //   // handle streaming events
+        // }
+        // response = stream.collect(); // something like this
+        // } else {
+        const res = await this.model.generate(req);
+        this.state.modelResponses.push(res);
+        // this.stats.usage.add(response.usage);
+        return this.parseModelResponse(res);
+    }
+    /**
+     * Perform the actions returned by the model
+     */
+    async performActions(intentions) {
+        // (TODO): refactor into a general actions system - probably shouldn't be handled by Thread
+        const toolEvents = await this.executeTools(intentions.toolCalls);
+        // const mcpEvents = await this.executeMCPRequests(actions.mcpRequests);
+        // Separate events and pending approvals
+        const actions = [];
+        const pendingApprovals = [];
+        // (TODO): clean this - approval tracking should be handled differently
+        for (const e of toolEvents) {
+            if (e.kind === "tool-result" &&
+                e.state === "requires_approval") {
+                // Find the original tool call for this pending approval
+                const originalCall = intentions.toolCalls.find((call) => call.callId === e.callId);
+                if (originalCall) {
+                    pendingApprovals.push(originalCall);
+                }
+            }
+            else {
+                actions.push(e);
+            }
+        }
+        return {
+            actions: actions,
+            pendingApprovals,
+        };
+    }
+    /**
+     * Execute function calls requested by the model
+     *
+     * TODO: refactor into actions system
+     */
+    async executeTools(calls) {
+        return await Promise.all(calls.map(async (call) => {
+            try {
+                const tool = this.agent.tool(call.toolId);
+                if (!tool) {
+                    throw new Error(`Tool ${call.toolId} not found`);
+                }
+                // hosted tools are executed server-side by the provider, not locally
+                assert(tool.type === "function", `Tool ${call.id} is a hosted tool and should not be executed locally`);
+                // (TMP) - passing the approval status through the context until actions system
+                // is refined
+                const ctx = new Context(this.context.context);
+                ctx.approve(call.callId); // mark this call as approved
+                const res = await tool.invoke(ctx, call.arguments, call.callId);
+                return {
+                    kind: "tool-result",
+                    callId: call.callId,
+                    toolId: call.toolId,
+                    state: res.state,
+                    result: res.result,
+                    error: res.error,
+                };
+            }
+            catch (error) {
+                // Handles both tool not found AND any execution errors
+                return {
+                    kind: "tool-result",
+                    callId: call.callId,
+                    toolId: call.toolId,
+                    state: FAILED,
+                    result: undefined,
+                    error: error instanceof Error ? error.message : String(error),
+                };
+            }
+        }));
+    }
+    /**
+     * Applies call-level filters and prepares the model request for the language model
+     */
+    async prepareModelRequest(history) {
+        let settings = {
+            ...this.agent.modelSettings,
+        };
+        // // TODO: what do we want to do with this?
+        // settings = maybeResetToolChoice(this.agent, this.state.toolUse, settings);
+        const system = await this.agent.instructions(this.context);
+        const input = system
+            ? [
+                // (TODO): add message(role, text) helper
+                {
+                    kind: "message",
+                    id: randomID(),
+                    role: "system",
+                    content: [{ kind: "text", text: system }],
+                },
+                ...history, // (TODO): filter for LanguageModelItem specifically - there may be other thread events
+            ]
+            : history;
+        // TODO: apply custom input filters - arguably want global + agent-scoped -> apply in a middleware-like chain
+        // const filtered = await applyInputFilters(inputWithSystem, context);
+        const filtered = input;
+        // serialize action repertoire
+        const allTools = await this.agent.tools(this.context);
+        const enabled = await filter(allTools, async (tool) => await tool.isEnabled(this.context, this.agent));
+        const tools = enabled.map((tool) => tool.serialize());
+        return {
+            input: filtered,
+            settings,
+            tools,
+        };
+    }
+    /**
+     * @internal
+     * Parses the model's response into events (for history) and actions (for execution).
+     */
+    parseModelResponse(res) {
+        const events = [];
+        const toolCalls = [];
+        for (const event of res.content) {
+            switch (event.kind) {
+                case "tool-call":
+                    // Add to both actions (for execution) and events (for history)
+                    toolCalls.push(event);
+                // fallthrough
+                default:
+                    events.push(event);
+                    break;
+            }
+        }
+        return {
+            events,
+            intentions: toolCalls.length > 0 ? { toolCalls } : null,
+        };
+    }
+}
+/**
+ * ThreadState tracks the execution state of a single thread.
+ *
+ * A thread is created each time a task is scheduled and executes
+ * the main tick() loop until terminal state.
+ */
+export class ThreadState {
+    tick;
+    modelResponses;
+    constructor() {
+        this.tick = 0;
+        this.modelResponses = [];
+    }
+}
+// /**
+//  * The result of an agent run in streaming mode.
+//  */
+// export class StreamedRunResult<
+//     TContext,
+//     TAgent extends Agent<TContext, AgentResponseType>,
+//   >
+//   extends RunResultBase<TContext, TAgent>
+//   implements AsyncIterable<ThreadStreamEvent>
+// {
+//   /**
+//    * The current agent that is running
+//    */
+//   public get currentAgent(): TAgent | undefined {
+//     return this.lastAgent;
+//   }
+//   /**
+//    * The current turn number
+//    */
+//   public currentTurn: number = 0;
+//   /**
+//    * The maximum number of turns that can be run
+//    */
+//   public maxTurns: number | undefined;
+//   #error: unknown = null;
+//   #signal?: AbortSignal;
+//   #readableController:
+//     | ReadableStreamDefaultController<ThreadStreamEvent>
+//     | undefined;
+//   #readableStream: ReadableStream<ThreadStreamEvent>;
+//   #completedPromise: Promise<void>;
+//   #completedPromiseResolve: (() => void) | undefined;
+//   #completedPromiseReject: ((err: unknown) => void) | undefined;
+//   #cancelled: boolean = false;
+//   #streamLoopPromise: Promise<void> | undefined;
+//   constructor(
+//     result: {
+//       state: ThreadState<TContext, TAgent>;
+//       signal?: AbortSignal;
+//     } = {} as any,
+//   ) {
+//     super(result.state);
+//     this.#signal = result.signal;
+//     this.#readableStream = new ReadableStream<ThreadStreamEvent>({
+//       start: (controller) => {
+//         this.#readableController = controller;
+//       },
+//       cancel: () => {
+//         this.#cancelled = true;
+//       },
+//     });
+//     this.#completedPromise = new Promise((resolve, reject) => {
+//       this.#completedPromiseResolve = resolve;
+//       this.#completedPromiseReject = reject;
+//     });
+//     if (this.#signal) {
+//       const handleAbort = () => {
+//         if (this.#cancelled) {
+//           return;
+//         }
+//         this.#cancelled = true;
+//         const controller = this.#readableController;
+//         this.#readableController = undefined;
+//         if (this.#readableStream.locked) {
+//           if (controller) {
+//             try {
+//               controller.close();
+//             } catch (err) {
+//               logger.debug(`Failed to close readable stream on abort: ${err}`);
+//             }
+//           }
+//         } else {
+//           void this.#readableStream
+//             .cancel(this.#signal?.reason)
+//             .catch((err) => {
+//               logger.debug(`Failed to cancel readable stream on abort: ${err}`);
+//             });
+//         }
+//         this.#completedPromiseResolve?.();
+//       };
+//       if (this.#signal.aborted) {
+//         handleAbort();
+//       } else {
+//         this.#signal.addEventListener("abort", handleAbort, { once: true });
+//       }
+//     }
+//   }
+//   /**
+//    * @internal
+//    * Adds an item to the stream of output items
+//    */
+//   _addItem(item: ThreadStreamEvent) {
+//     if (!this.cancelled) {
+//       this.#readableController?.enqueue(item);
+//     }
+//   }
+//   /**
+//    * @internal
+//    * Indicates that the stream has been completed
+//    */
+//   _done() {
+//     if (!this.cancelled && this.#readableController) {
+//       this.#readableController.close();
+//       this.#readableController = undefined;
+//       this.#completedPromiseResolve?.();
+//     }
+//   }
+//   /**
+//    * @internal
+//    * Handles an error in the stream loop.
+//    */
+//   _raiseError(err: unknown) {
+//     if (!this.cancelled && this.#readableController) {
+//       this.#readableController.error(err);
+//       this.#readableController = undefined;
+//     }
+//     this.#error = err;
+//     this.#completedPromiseReject?.(err);
+//     this.#completedPromise.catch((e) => {
+//       logger.debug(`Resulted in an error: ${e}`);
+//     });
+//   }
+//   /**
+//    * Returns true if the stream has been cancelled.
+//    */
+//   get cancelled(): boolean {
+//     return this.#cancelled;
+//   }
+//   /**
+//    * Returns the underlying readable stream.
+//    * @returns A readable stream of the agent run.
+//    */
+//   toStream(): ReadableStream<ThreadStreamEvent> {
+//     return this.#readableStream as ReadableStream<ThreadStreamEvent>;
+//   }
+//   /**
+//    * Await this promise to ensure that the stream has been completed if you are not consuming the
+//    * stream directly.
+//    */
+//   get completed() {
+//     return this.#completedPromise;
+//   }
+//   /**
+//    * Error thrown during the run, if any.
+//    */
+//   get error() {
+//     return this.#error;
+//   }
+//   /**
+//    * Returns a readable stream of the final text output of the agent run.
+//    *
+//    * @returns A readable stream of the final output of the agent run.
+//    * @remarks Pass `{ compatibleWithNodeStreams: true }` to receive a Node.js compatible stream
+//    * instance.
+//    */
+//   toTextStream(): ReadableStream<string>;
+//   toTextStream(options?: { compatibleWithNodeStreams: true }): Readable;
+//   toTextStream(options?: {
+//     compatibleWithNodeStreams?: false;
+//   }): ReadableStream<string>;
+//   toTextStream(
+//     options: { compatibleWithNodeStreams?: boolean } = {},
+//   ): Readable | ReadableStream<string> {
+//     const stream = this.#readableStream.pipeThrough(
+//       new TransformStream<ThreadStreamEvent, string>({
+//         transform(event, controller) {
+//           if (
+//             event.kind === "raw_model_stream_event" && // (TODO): what to do here?
+//             event.data.kind === "text-delta"
+//           ) {
+//             const item = TextDeltaEvent.parse(event); // ??
+//             controller.enqueue(item.text); // (TODO): is it just the text that we want to return here?
+//           }
+//         },
+//       }),
+//     );
+//     if (options.compatibleWithNodeStreams) {
+//       return Readable.fromWeb(stream);
+//     }
+//     return stream as ReadableStream<string>;
+//   }
+//   [Symbol.asyncIterator](): AsyncIterator<ThreadStreamEvent> {
+//     return this.#readableStream[Symbol.asyncIterator]();
+//   }
+//   /**
+//    * @internal
+//    * Sets the stream loop promise that completes when the internal stream loop finishes.
+//    * This is used to defer trace end until all agent work is complete.
+//    */
+//   _setStreamLoopPromise(promise: Promise<void>) {
+//     this.#streamLoopPromise = promise;
+//   }
+//   /**
+//    * @internal
+//    * Returns a promise that resolves when the stream loop completes.
+//    * This is used by the tracing system to wait for all agent work before ending the trace.
+//    */
+//   _getStreamLoopPromise(): Promise<void> | undefined {
+//     return this.#streamLoopPromise;
+//   }
+// }

package/dist/thread/utils.d.ts

@@ -0,0 +1,19 @@
+import type { ResolvedAgentResponse } from "../guardrail";
+import type { AgentResponseType } from "../types/agent";
+import type { ThreadEvent } from "../types/thread";
+/**
+ * Extract the final text response from a list of events.
+ * Returns null if no assistant message with text content is found.
+ */
+export declare function getFinalResponse(events: ThreadEvent[]): string | null;
+/**
+ * (TODO): This should run through the language model's native structured output (if avail)
+ *
+ * Parse the final response according to the response type schema.
+ * - If responseType is "text", returns the text as-is
+ * - If responseType is a ZodType, parses and validates the text as JSON
+ *
+ * @throws {ModelBehaviorError} if structured output validation fails
+ */
+export declare function parseFinalResponse<TResponse extends AgentResponseType>(text: string, responseType: TResponse): ResolvedAgentResponse<TResponse>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/thread/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/thread/utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAOzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,GAAG,IAAI,CAcrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,SAAS,iBAAiB,EACpE,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,SAAS,GACtB,qBAAqB,CAAC,SAAS,CAAC,CAsBlC"}

package/dist/thread/utils.js

@@ -0,0 +1,50 @@
+/* lib */
+import { json } from "@kernl/shared/lib";
+import { ModelBehaviorError } from "../lib/error";
+/**
+ * Extract the final text response from a list of events.
+ * Returns null if no assistant message with text content is found.
+ */
+export function getFinalResponse(events) {
+    // Scan backwards for the last assistant message
+    for (let i = events.length - 1; i >= 0; i--) {
+        const event = events[i];
+        if (event.kind === "message" && event.role === "assistant") {
+            // Extract text from content parts
+            for (const part of event.content) {
+                if (part.kind === "text") {
+                    return part.text;
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * (TODO): This should run through the language model's native structured output (if avail)
+ *
+ * Parse the final response according to the response type schema.
+ * - If responseType is "text", returns the text as-is
+ * - If responseType is a ZodType, parses and validates the text as JSON
+ *
+ * @throws {ModelBehaviorError} if structured output validation fails
+ */
+export function parseFinalResponse(text, responseType) {
+    if (responseType === "text") {
+        return text; // text output - return as-is
+    }
+    // structured output - decode JSON and validate with schema
+    if (responseType && typeof responseType === "object") {
+        // (TODO): prob better way of checking this here
+        const schema = responseType;
+        try {
+            const validated = json(schema).decode(text); // (TODO): it would be nice if we could use `decodeSafe` here
+            return validated;
+        }
+        catch (error) {
+            throw new ModelBehaviorError(`Failed to parse structured output: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    // Fallback - should not reach here
+    return text;
+}

package/dist/tool/__tests__/fixtures.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+import { Context } from "../../context";
+import { HostedTool } from "../tool";
+/**
+ * Create a minimal mock context for testing
+ */
+export declare const mockContext: <T = any>(data?: T) => Context<T>;
+/**
+ * Simple string tool with no parameters
+ */
+export declare const simpleStringTool: import("..").FunctionTool<unknown, undefined, string>;
+/**
+ * Tool with Zod schema validation
+ */
+export declare const zodTool: import("..").FunctionTool<unknown, z.ZodObject<{
+    name: z.ZodString;
+    age: z.ZodNumber;
+}, z.core.$strip>, string>;
+/**
+ * Tool that always throws an error
+ */
+export declare const errorTool: import("..").FunctionTool<unknown, undefined, never>;
+/**
+ * Tool with custom error handler
+ */
+export declare const customErrorTool: import("..").FunctionTool<unknown, undefined, never>;
+/**
+ * Tool requiring approval (boolean)
+ */
+export declare const approvalRequiredTool: import("..").FunctionTool<unknown, undefined, string>;
+/**
+ * Tool with conditional approval (function)
+ */
+export declare const conditionalApprovalTool: import("..").FunctionTool<unknown, z.ZodObject<{
+    dangerous: z.ZodBoolean;
+}, z.core.$strip>, string>;
+/**
+ * Mock hosted tool (e.g., web_search)
+ */
+export declare const mockHostedTool: HostedTool;
+/**
+ * Another mock hosted tool
+ */
+export declare const anotherHostedTool: HostedTool;
+//# sourceMappingURL=fixtures.d.ts.map

package/dist/tool/__tests__/fixtures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixtures.d.ts","sourceRoot":"","sources":["../../../src/tool/__tests__/fixtures.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAQ,UAAU,EAAE,MAAM,SAAS,CAAC;AAE3C;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,GAAG,GAAG,EAAE,OAAO,CAAC,KAAG,OAAO,CAAC,CAAC,CAExD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,uDAK3B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,OAAO;;;0BAQlB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,SAAS,sDAOpB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe,sDAU1B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,oBAAoB,uDAM/B,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,uBAAuB;;0BAUlC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc,YAOzB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,YAG5B,CAAC"}