kernl 0.1.4 → 0.2.0

package/dist/thread/thread.d.ts

@@ -2,8 +2,8 @@ import { Kernl } from "../kernl";
 import { Agent } from "../agent";
 import { Context } from "../context";
 import type { Task } from "../task";
-import { LanguageModel, LanguageModelResponse } from "@kernl-sdk/protocol";
-import type { ThreadEvent, ThreadOptions, ThreadExecuteResult } from "../types/thread";
+import { LanguageModel } from "@kernl-sdk/protocol";
+import type { ThreadEvent, ThreadOptions, ThreadExecuteResult, ThreadState, ThreadStreamEvent } from "../types/thread";
 import type { AgentResponseType } from "../types/agent";
 import type { ResolvedAgentResponse } from "../guardrail";
 /**
@@ -17,19 +17,40 @@ export declare class Thread<TContext = unknown, TResponse extends AgentResponseT
     readonly model: LanguageModel;
     readonly parent: Task<TContext> | null;
     readonly mode: "blocking" | "stream";
-    readonly state: ThreadState;
-    readonly input: ThreadEvent[] | string;
+    readonly input: ThreadEvent[];
+    _tick: number;
+    state: ThreadState;
     private history;
-    constructor(kernl: Kernl, agent: Agent<TContext, TResponse>, input: ThreadEvent[] | string, options?: ThreadOptions<TContext>);
+    private abort?;
+    constructor(kernl: Kernl, agent: Agent<TContext, TResponse>, input: ThreadEvent[], options?: ThreadOptions<TContext>);
     /**
-     * Main thread execution loop - runs until terminal state or interruption
+     * Blocking execution loop - runs until terminal state or interruption
      */
     execute(): Promise<ThreadExecuteResult<ResolvedAgentResponse<TResponse>>>;
     /**
-     * A single tick of the thread's execution.
+     * Streaming execution - returns async iterator of events
+     */
+    stream(): AsyncIterable<ThreadStreamEvent>;
+    /**
+     * Cancel the running thread
+     */
+    cancel(): void;
+    /**
+     * Append a new event to the thread history
+     */
+    append(event: ThreadEvent): void;
+    /**
+     * Main execution loop - always yields events, callers can propagate or discard (as in execute())
+     *
+     * NOTE: Streaming structured output deferred for now. Prioritizing correctness + simplicity,
+     * and unclear what use cases there would actually be for streaming a structured output (other than maybe gen UI).
+     */
+    private _execute;
+    /**
+     * A single tick - calls model and yields events as they arrive
      *
-     * 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).
+     * NOTE: Streaming structured outputs deferred until concrete use cases emerge.
+     * For now, we stream text-delta and tool events, final validation happens in _execute().
      */
     private tick;
     /**
@@ -46,21 +67,5 @@ export declare class Thread<TContext = unknown, TResponse extends AgentResponseT
      * 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

@@ -1 +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,qBAAqB,CAAC;AAG7B,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"}
+{"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,EAMd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAEV,WAAW,EACX,aAAa,EACb,mBAAmB,EAEnB,WAAW,EACX,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AASzD;;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;IACrC,QAAQ,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC;IAI9B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,OAAO,CAAsE;IACrF,OAAO,CAAC,KAAK,CAAC,CAAkB;gBAG9B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,SAAS,CAAC,EACjC,KAAK,EAAE,WAAW,EAAE,EACpB,OAAO,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC;IAgBnC;;OAEG;IACG,OAAO,IAAI,OAAO,CACtB,mBAAmB,CAAC,qBAAqB,CAAC,SAAS,CAAC,CAAC,CACtD;IAcD;;OAEG;IACI,MAAM,IAAI,aAAa,CAAC,iBAAiB,CAAC;IAkBjD;;OAEG;IACH,MAAM;IAIN;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAIhC;;;;;OAKG;YACY,QAAQ;IAiDvB;;;;;OAKG;YACY,IAAI;IAwBnB;;OAEG;YACW,cAAc;IA6C5B;;;;OAIG;YACW,YAAY;IA4C1B;;OAEG;YACW,mBAAmB;CA2ClC"}

package/dist/thread/thread.js

@@ -1,8 +1,8 @@
 import assert from "assert";
 import { Context } from "../context";
-import { FAILED, } from "@kernl-sdk/protocol";
+import { FAILED, RUNNING, STOPPED, } from "@kernl-sdk/protocol";
 import { randomID, filter } from "@kernl-sdk/shared/lib";
-import { getFinalResponse, parseFinalResponse } from "./utils";
+import { notDelta, getFinalResponse, getIntentions, parseFinalResponse, } from "./utils";
 /**
  * A thread drives the execution loop for an agent.
  */
@@ -14,10 +14,13 @@ export class Thread {
     model; /* inherited from the agent unless specified */
     parent; /* parent task which spawned this thread */
     mode; /* TODO */
+    input; /* the initial input for the thread */
+    // readonly stats: ThreadMetrics;
     /* state */
+    _tick;
     state;
-    input; /* the initial input for the thread */
     history;
+    abort;
     constructor(kernl, agent, input, options) {
         this.id = `tid_${randomID()}`;
         this.agent = agent;
@@ -25,59 +28,94 @@ export class Thread {
         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,
-                        },
-                    ],
-                },
-            ];
+        this._tick = 0;
+        this.state = STOPPED;
+        this.history = input;
+    }
+    /**
+     * Blocking execution loop - runs until terminal state or interruption
+     */
+    async execute() {
+        for await (const _event of this.stream()) {
+            // just consume the stream (already in history in _execute())
         }
-        else {
-            this.history = input;
+        // extract final response from accumulated history
+        const text = getFinalResponse(this.history);
+        assert(text, "_execute continues until text !== null"); // (TODO): consider preventing infinite loops here
+        const parsed = parseFinalResponse(text, this.agent.responseType);
+        return { response: parsed, state: this.state };
+    }
+    /**
+     * Streaming execution - returns async iterator of events
+     */
+    async *stream() {
+        if (this.state === RUNNING && this.abort) {
+            throw new Error("thread already running");
+        }
+        this.state = RUNNING;
+        this.abort = new AbortController();
+        try {
+            yield* this._execute();
+        }
+        catch (err) {
+            throw err;
+        }
+        finally {
+            this.state = STOPPED;
+            this.abort = undefined;
         }
     }
     /**
-     * Main thread execution loop - runs until terminal state or interruption
+     * Cancel the running thread
      */
-    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
+    cancel() {
+        this.abort?.abort();
+    }
+    /**
+     * Append a new event to the thread history
+     */
+    append(event) {
+        this.history.push(event);
+    }
+    /**
+     * Main execution loop - always yields events, callers can propagate or discard (as in execute())
+     *
+     * NOTE: Streaming structured output deferred for now. Prioritizing correctness + simplicity,
+     * and unclear what use cases there would actually be for streaming a structured output (other than maybe gen UI).
+     */
+    async *_execute() {
+        for (;;) {
+            if (this.abort?.signal.aborted) {
+                return;
+            }
+            const events = [];
+            for await (const e of this.tick()) {
+                // we don't want deltas in the history
+                if (notDelta(e)) {
+                    events.push(e);
+                    this.history.push(e);
+                }
+                yield e;
+            }
+            // if model returns a message with no action intentions -> terminal state
+            const intentions = getIntentions(events);
             if (!intentions) {
                 const text = getFinalResponse(events);
                 if (!text)
-                    continue; // run again, policy-dependent?
-                const parsed = parseFinalResponse(text, this.agent.responseType);
+                    continue; // run again, policy-dependent? (how to ensure no infinite loop here?)
                 // await this.agent.runOutputGuardails(context, state);
                 // this.kernl.emit("thread.terminated", context, output);
-                return { response: parsed, state: this.state };
+                return;
             }
-            // perform the actions intended by the model
+            // perform actions intended by the model
             const { actions, pendingApprovals } = await this.performActions(intentions);
-            this.history.push(...actions);
+            // yield action events
+            for (const a of actions) {
+                this.history.push(a);
+                yield a;
+            }
             if (pendingApprovals.length > 0) {
                 // publish a batch approval request containing all of them
                 //
@@ -89,57 +127,57 @@ export class Thread {
             }
         }
     }
-    // ----------------------
-    // Internal helpers
-    // ----------------------
     /**
-     * A single tick of the thread's execution.
+     * A single tick - calls model and yields events as they arrive
      *
-     * 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).
+     * NOTE: Streaming structured outputs deferred until concrete use cases emerge.
+     * For now, we stream text-delta and tool events, final validation happens in _execute().
      */
-    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, ...?);
+    async *tick() {
+        this._tick++;
+        // (TODO): check limits (if this._tick > this.limits.maxTicks)
+        // (TODO): run input guardrails on first tick (if this._tick === 1)
+        const req = await this.prepareModelRequest(this.history);
+        // try to stream if model supports it
+        if (this.model.stream) {
+            const stream = this.model.stream(req);
+            for await (const event of stream) {
+                yield event; // [text-delta, tool-call, message, reasoning, ...]
+            }
+        }
+        else {
+            // fallback: blocking generate, yield events as batch
+            const res = await this.model.generate(req);
+            for (const event of res.content) {
+                yield event;
+            }
+            // (TODO): track usage (this.stats.usage.add(res.usage))
         }
-        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) {
+        // // 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:
+        //   }
+        // }
         // (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") {
+                e.state === "requires_approval" // (TODO): fix this
+            ) {
                 // Find the original tool call for this pending approval
                 const originalCall = intentions.toolCalls.find((call) => call.callId === e.callId);
                 if (originalCall) {
@@ -231,242 +269,4 @@ export class Thread {
             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

@@ -1,6 +1,21 @@
 import type { ResolvedAgentResponse } from "../guardrail";
+import { ToolCall } from "@kernl-sdk/protocol";
 import type { AgentResponseType } from "../types/agent";
-import type { ThreadEvent } from "../types/thread";
+import type { ThreadEvent, ThreadStreamEvent, ActionSet } from "../types/thread";
+/**
+ * Check if an event represents an intention (action to be performed)
+ */
+export declare function isActionIntention(event: ThreadEvent): event is ToolCall;
+/**
+ * Extract action intentions from a list of events.
+ * Returns ActionSet if there are any tool calls, null otherwise.
+ */
+export declare function getIntentions(events: ThreadEvent[]): ActionSet | null;
+/**
+ * Check if an event is NOT a delta/start/end event (i.e., a complete item).
+ * Returns true for complete items: Message, Reasoning, ToolCall, ToolResult
+ */
+export declare function notDelta(event: ThreadStreamEvent): event is ThreadEvent;
 /**
  * Extract the final text response from a list of events.
  * Returns null if no assistant message with text content is found.

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

@@ -1 +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"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/thread/utils.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAIzD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAI/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,QAAQ,CAEvE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,SAAS,GAAG,IAAI,CAGrE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,KAAK,IAAI,WAAW,CAYvE;AAED;;;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

@@ -1,6 +1,36 @@
 /* lib */
 import { json } from "@kernl-sdk/shared/lib";
 import { ModelBehaviorError } from "../lib/error";
+/**
+ * Check if an event represents an intention (action to be performed)
+ */
+export function isActionIntention(event) {
+    return event.kind === "tool-call";
+}
+/**
+ * Extract action intentions from a list of events.
+ * Returns ActionSet if there are any tool calls, null otherwise.
+ */
+export function getIntentions(events) {
+    const toolCalls = events.filter(isActionIntention);
+    return toolCalls.length > 0 ? { toolCalls } : null;
+}
+/**
+ * Check if an event is NOT a delta/start/end event (i.e., a complete item).
+ * Returns true for complete items: Message, Reasoning, ToolCall, ToolResult
+ */
+export function notDelta(event) {
+    switch (event.kind) {
+        case "message":
+        case "reasoning":
+        case "tool-call":
+        case "tool-result":
+            return true;
+        // all other events are streaming deltas/control events
+        default:
+            return false;
+    }
+}
 /**
  * Extract the final text response from a list of events.
  * Returns null if no assistant message with text content is found.

package/dist/tool/index.d.ts

@@ -1,4 +1,4 @@
 export { BaseTool, FunctionTool, HostedTool, tool } from "./tool";
-export { Toolkit, FunctionToolkit, MCPToolkit } from "./toolkit";
+export { BaseToolkit, Toolkit, FunctionToolkit, MCPToolkit } from "./toolkit";
 export type { Tool, ToolResult, FunctionToolkitConfig, MCPToolkitConfig, ToolkitFilter, ToolkitFilterContext, } from "./types";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tool/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACjE,YAAY,EACV,IAAI,EACJ,UAAU,EACV,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,oBAAoB,GACrB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tool/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9E,YAAY,EACV,IAAI,EACJ,UAAU,EACV,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,oBAAoB,GACrB,MAAM,SAAS,CAAC"}