kernl 0.9.1 → 0.11.0

package/dist/realtime/session.js

@@ -1,4 +1,4 @@
-import { EventEmitter } from "node:events";
+import { Emitter } from "@kernl-sdk/shared";
 import { message, } from "@kernl-sdk/protocol";
 import { Context } from "../context.js";
 import { MisconfiguredError } from "../lib/error.js";
@@ -8,7 +8,7 @@ import { MisconfiguredError } from "../lib/error.js";
  * Handles the bidirectional communication between an agent and a model,
  * including audio I/O (via channels), tool execution, and event routing.
  */
-export class RealtimeSession extends EventEmitter {
+export class RealtimeSession extends Emitter {
     /**
      * Session ID. Null until connected.
      */
@@ -56,6 +56,7 @@ export class RealtimeSession extends EventEmitter {
         const options = {
             ...this.options.connectOptions,
             sessionConfig,
+            credential: this.options.credential ?? this.options.connectOptions?.credential,
         };
         this.connection = this.options.transport
             ? await this.options.transport.connect(this.model, options)
@@ -63,6 +64,9 @@ export class RealtimeSession extends EventEmitter {
         this.connection.on("event", this.onEvent.bind(this));
         this.connection.on("error", (e) => this.emit("error", e));
         this.connection.on("status", (s) => this.emit("status", s));
+        this.connection.on("interrupted", () => this.channel?.interrupt());
+        // Emit current status (may have been set before listeners attached)
+        this.emit("status", this.connection.status);
         this.init();
     }
     /**
@@ -79,6 +83,53 @@ export class RealtimeSession extends EventEmitter {
             config: await this.buildSessionConfig(),
         });
     }
+    /**
+     * Send audio to the model.
+     */
+    sendAudio(audio) {
+        this.connection?.send({ kind: "audio.input.append", audio });
+    }
+    /**
+     * Commit the audio buffer (signal end of speech).
+     */
+    commit() {
+        this.connection?.send({ kind: "audio.input.commit" });
+    }
+    /**
+     * Send a text message to the model.
+     */
+    sendMessage(text) {
+        this.connection?.send({
+            kind: "item.create",
+            item: message({ role: "user", text }),
+        });
+    }
+    /**
+     * Interrupt the current response.
+     */
+    interrupt() {
+        this.connection?.send({ kind: "response.cancel" });
+        this.channel?.interrupt();
+    }
+    /**
+     * Mute audio input.
+     */
+    mute() {
+        this.connection?.mute();
+    }
+    /**
+     * Unmute audio input.
+     */
+    unmute() {
+        this.connection?.unmute();
+    }
+    /**
+     * Close the session and release resources.
+     */
+    close() {
+        this.channel?.close();
+        this.connection?.close();
+    }
     /**
      * Build session configuration from agent.
      */
@@ -88,6 +139,11 @@ export class RealtimeSession extends EventEmitter {
             instructions: await this.agent.instructions(this.context),
             tools: tools.map((t) => t.serialize()),
             voice: this.agent.voice,
+            turnDetection: { mode: "server_vad" },
+            audio: {
+                inputFormat: { mimeType: "audio/pcm", sampleRate: 24000 },
+                outputFormat: { mimeType: "audio/pcm", sampleRate: 24000 },
+            },
         };
     }
     /**
@@ -101,7 +157,7 @@ export class RealtimeSession extends EventEmitter {
      */
     onEvent(event) {
         switch (event.kind) {
-            // Audio output → 'audio'
+            // audio output → 'audio'
             case "audio.output.delta":
                 this.channel?.sendAudio(event.audio);
                 this.emit("audio", event);
@@ -109,24 +165,24 @@ export class RealtimeSession extends EventEmitter {
             case "audio.output.done":
                 this.emit("audio", event);
                 break;
-            // Speech transcriptions → 'transcript'
+            // speech transcriptions → 'transcript'
             case "transcript.input":
             case "transcript.output":
                 this.emit("transcript", event);
                 break;
-            // Text output → 'text'
+            // text output → 'text'
             case "text.output":
                 this.emit("text", event);
                 break;
-            // Errors → 'error'
+            // ERrors → 'error'
             case "session.error":
                 this.emit("error", event.error);
                 break;
-            // Tool calls - handled internally
+            // tool calls - handled internally
             case "tool.call":
                 this.performActions(event);
                 break;
-            // Session lifecycle - internal state
+            // session lifecycle - internal state
             case "session.created":
                 this.id = event.session.id;
                 break;
@@ -153,51 +209,4 @@ export class RealtimeSession extends EventEmitter {
             error: result.error ?? undefined,
         });
     }
-    /**
-     * Send audio to the model.
-     */
-    sendAudio(audio) {
-        this.connection?.send({ kind: "audio.input.append", audio });
-    }
-    /**
-     * Commit the audio buffer (signal end of speech).
-     */
-    commit() {
-        this.connection?.send({ kind: "audio.input.commit" });
-    }
-    /**
-     * Send a text message to the model.
-     */
-    sendMessage(text) {
-        this.connection?.send({
-            kind: "item.create",
-            item: message({ role: "user", text }),
-        });
-    }
-    /**
-     * Interrupt the current response.
-     */
-    interrupt() {
-        this.connection?.send({ kind: "response.cancel" });
-        this.channel?.interrupt();
-    }
-    /**
-     * Mute audio input.
-     */
-    mute() {
-        this.connection?.mute();
-    }
-    /**
-     * Unmute audio input.
-     */
-    unmute() {
-        this.connection?.unmute();
-    }
-    /**
-     * Close the session and release resources.
-     */
-    close() {
-        this.channel?.close();
-        this.connection?.close();
-    }
 }

package/dist/realtime/transport.d.ts

@@ -0,0 +1,45 @@
+import type { RealtimeModel, RealtimeConnection, RealtimeTransport, RealtimeConnectOptions, WebSocketConstructor } from "@kernl-sdk/protocol";
+/**
+ * Options for creating a WebSocket transport.
+ */
+export interface WebSocketTransportOptions {
+    /**
+     * WebSocket constructor to use.
+     *
+     * Required in Node.js <22 (provide the 'ws' package).
+     * Optional in browsers and Node.js 22+ (uses globalThis.WebSocket).
+     *
+     * @example
+     * ```ts
+     * import WebSocket from 'ws';
+     * new WebSocketTransport({ websocket: WebSocket });
+     * ```
+     */
+    websocket?: WebSocketConstructor;
+}
+/**
+ * WebSocket transport for realtime connections.
+ *
+ * Use this transport when you need to provide a custom WebSocket implementation,
+ * such as the 'ws' package in Node.js <22.
+ *
+ * @example
+ * ```ts
+ * // Node.js <22
+ * import WebSocket from 'ws';
+ * const session = new RealtimeSession(agent, {
+ *   transport: new WebSocketTransport({ websocket: WebSocket }),
+ *   ...
+ * });
+ *
+ * // Browser or Node.js 22+ - no transport needed
+ * const session = new RealtimeSession(agent, { ... });
+ * ```
+ */
+export declare class WebSocketTransport implements RealtimeTransport {
+    readonly handlesAudio = false;
+    private WS;
+    constructor(options?: WebSocketTransportOptions);
+    connect(model: RealtimeModel, options?: RealtimeConnectOptions): Promise<RealtimeConnection>;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/realtime/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../../src/realtime/transport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,oBAAoB,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,kBAAmB,YAAW,iBAAiB;IAC1D,QAAQ,CAAC,YAAY,SAAS;IAC9B,OAAO,CAAC,EAAE,CAAmC;gBAEjC,OAAO,CAAC,EAAE,yBAAyB;IAIzC,OAAO,CACX,KAAK,EAAE,aAAa,EACpB,OAAO,CAAC,EAAE,sBAAsB,GAC/B,OAAO,CAAC,kBAAkB,CAAC;CAM/B"}

package/dist/realtime/transport.js

@@ -0,0 +1,32 @@
+/**
+ * WebSocket transport for realtime connections.
+ *
+ * Use this transport when you need to provide a custom WebSocket implementation,
+ * such as the 'ws' package in Node.js <22.
+ *
+ * @example
+ * ```ts
+ * // Node.js <22
+ * import WebSocket from 'ws';
+ * const session = new RealtimeSession(agent, {
+ *   transport: new WebSocketTransport({ websocket: WebSocket }),
+ *   ...
+ * });
+ *
+ * // Browser or Node.js 22+ - no transport needed
+ * const session = new RealtimeSession(agent, { ... });
+ * ```
+ */
+export class WebSocketTransport {
+    handlesAudio = false;
+    WS;
+    constructor(options) {
+        this.WS = options?.websocket;
+    }
+    async connect(model, options) {
+        return model.connect({
+            ...options,
+            websocket: this.WS ?? options?.websocket,
+        });
+    }
+}

package/dist/realtime/types.d.ts

@@ -1,7 +1,6 @@
-import { RealtimeModel, RealtimeTransport, RealtimeConnectOptions } from "@kernl-sdk/protocol";
+import { RealtimeModel, RealtimeTransport, RealtimeConnectOptions, RealtimeChannel, ClientCredential } from "@kernl-sdk/protocol";
 import { Context, UnknownContext } from "../context.js";
 import type { BaseAgentConfig } from "../agent/base.js";
-import type { RealtimeChannel } from "./channel.js";
 /**
  * Configuration for a realtime agent.
  */
@@ -50,6 +49,13 @@ export interface RealtimeSessionOptions<TContext = UnknownContext> {
      * Context for this session.
      */
     context?: Context<TContext>;
+    /**
+     * Ephemeral credential for client-side connections.
+     *
+     * Obtained from model.authenticate() on the server.
+     * Shorthand for connectOptions.credential.
+     */
+    credential?: ClientCredential;
     /**
      * Options passed to model.connect() or transport.connect().
      */

package/dist/realtime/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/realtime/types.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACvB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,QAAQ,GAAG,cAAc,CAC5D,SAAQ,eAAe,CAAC,QAAQ,CAAC;IACjC;;OAEG;IACH,KAAK,EAAE,aAAa,CAAC;IAErB;;OAEG;IACH,KAAK,CAAC,EAAE,wBAAwB,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB,CAAC,QAAQ,GAAG,cAAc;IAC/D;;OAEG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IAEtB;;;OAGG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;;OAGG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAE9B;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE5B;;OAEG;IACH,cAAc,CAAC,EAAE,sBAAsB,CAAC;CACzC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/realtime/types.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,EACjB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,QAAQ,GAAG,cAAc,CAC5D,SAAQ,eAAe,CAAC,QAAQ,CAAC;IACjC;;OAEG;IACH,KAAK,EAAE,aAAa,CAAC;IAErB;;OAEG;IACH,KAAK,CAAC,EAAE,wBAAwB,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB,CAAC,QAAQ,GAAG,cAAc;IAC/D;;OAEG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IAEtB;;;OAGG;IACH,OAAO,CAAC,EAAE,eAAe,CAAC;IAE1B;;;OAGG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAE9B;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAE5B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAE9B;;OAEG;IACH,cAAc,CAAC,EAAE,sBAAsB,CAAC;CACzC"}

package/dist/thread/__tests__/thread.test.js

@@ -275,7 +275,7 @@ describe("Thread", () => {
                                 toolId: "simple",
                                 state: IN_PROGRESS,
                                 callId: "call_1",
-                                arguments: "first",
+                                arguments: JSON.stringify({ value: "first" }),
                             },
                         ],
                         finishReason: "stop",
@@ -301,7 +301,7 @@ describe("Thread", () => {
                                 toolId: "simple",
                                 state: IN_PROGRESS,
                                 callId: "call_2",
-                                arguments: "second",
+                                arguments: JSON.stringify({ value: "second" }),
                             },
                         ],
                         finishReason: "stop",

package/dist/thread/thread.d.ts

@@ -49,8 +49,8 @@ export declare class Thread<TContext = unknown, TOutput extends AgentOutputType
     readonly tid: string;
     readonly namespace: string;
     readonly agent: Agent<TContext, TOutput>;
-    readonly context: Context<TContext>;
-    readonly model: LanguageModel;
+    context: Context<TContext>;
+    model: LanguageModel;
     readonly parent: Task<TContext> | null;
     readonly createdAt: Date;
     readonly updatedAt: Date;

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

@@ -1 +1 @@
-{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/thread/thread.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAKzD,OAAO,EAML,aAAa,EAGd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAEV,WAAW,EACX,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EAEpB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAWrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,MAAM,CACjB,QAAQ,GAAG,OAAO,EAClB,OAAO,SAAS,eAAe,GAAG,MAAM;IAExC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACzC,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,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAIlD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,OAAO,CAAwE;IAEvF,OAAO,CAAC,KAAK,CAAC,CAAkB;IAChC,OAAO,CAAC,OAAO,CAAC,CAAc;gBAElB,OAAO,EAAE,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC;IAgCrD;;OAEG;IACG,OAAO,IAAI,OAAO,CACtB,mBAAmB,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CACpD;IAoBD;;OAEG;IACI,MAAM,IAAI,aAAa,CAAC,iBAAiB,CAAC;IAuBjD;;;;;OAKG;YACY,QAAQ;IAgEvB;;;;;OAKG;YACY,IAAI;IA8BnB;;;;;OAKG;YACW,UAAU;IAuCxB;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,KAAK,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE;IAiBnD;;OAEG;IACH,MAAM;IAQN;;OAEG;YACW,cAAc;IAyC5B;;;;OAIG;YACW,YAAY;IA4C1B;;OAEG;YACW,mBAAmB;CAsDlC"}
+{"version":3,"file":"thread.d.ts","sourceRoot":"","sources":["../../src/thread/thread.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAKzD,OAAO,EAML,aAAa,EAKd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,KAAK,EAEV,WAAW,EACX,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EAEpB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAWrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBAAa,MAAM,CACjB,QAAQ,GAAG,OAAO,EAClB,OAAO,SAAS,eAAe,GAAG,MAAM;IAExC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACzC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3B,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAIlD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,SAAS,CAAU;IAC3B,OAAO,CAAC,OAAO,CAAwE;IAEvF,OAAO,CAAC,KAAK,CAAC,CAAkB;IAChC,OAAO,CAAC,OAAO,CAAC,CAAc;gBAElB,OAAO,EAAE,aAAa,CAAC,QAAQ,EAAE,OAAO,CAAC;IAgCrD;;OAEG;IACG,OAAO,IAAI,OAAO,CACtB,mBAAmB,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC,CACpD;IAoBD;;OAEG;IACI,MAAM,IAAI,aAAa,CAAC,iBAAiB,CAAC;IAuBjD;;;;;OAKG;YACY,QAAQ;IAgEvB;;;;;OAKG;YACY,IAAI;IAoEnB;;;;;OAKG;YACW,UAAU;IAuCxB;;;;;;OAMG;IACH,MAAM,CAAC,GAAG,KAAK,EAAE,gBAAgB,EAAE,GAAG,WAAW,EAAE;IAiBnD;;OAEG;IACH,MAAM;IAQN;;OAEG;YACW,cAAc;IAyC5B;;;;OAIG;YACW,YAAY;IAkF1B;;OAEG;YACW,mBAAmB;CAsDlC"}

package/dist/thread/thread.js

@@ -143,14 +143,14 @@ export class Thread {
      */
     async *_execute() {
         for (;;) {
-            let err = false;
+            let err = undefined;
             if (this.abort?.signal.aborted) {
                 return;
             }
             const events = [];
             for await (const e of this.tick()) {
                 if (e.kind === "error") {
-                    err = true;
+                    err = e.error;
                     logger.error(e.error); // (TODO): onError callback in options
                 }
                 // we don't want deltas in the history
@@ -160,9 +160,9 @@ export class Thread {
                 }
                 yield e;
             }
-            // if an error event occurred → terminate
+            // if an error event occurred → throw it
             if (err) {
-                return;
+                throw err;
             }
             // if model returns a message with no action intentions → terminal state
             const intentions = getIntentions(events);
@@ -205,23 +205,57 @@ export class Thread {
         // (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);
+        this.agent.emit("model.call.start", {
+            kind: "model.call.start",
+            provider: this.model.provider,
+            modelId: this.model.modelId,
+            settings: req.settings ?? {},
+            threadId: this.tid,
+            agentId: this.agent.id,
+            context: this.context,
+        });
+        let usage;
+        let finishReason = "unknown";
         try {
             if (this.model.stream) {
-                const stream = this.model.stream(req);
-                for await (const event of stream) {
-                    yield event; // [text-delta, tool-call, message, reasoning, ...]
+                for await (const event of this.model.stream(req)) {
+                    if (event.kind === "finish") {
+                        usage = event.usage;
+                        finishReason = event.finishReason;
+                    }
+                    yield event;
                 }
             }
             else {
                 // fallback: blocking generate, yield events as batch
                 const res = await this.model.generate(req);
+                usage = res.usage;
+                finishReason = res.finishReason;
                 for (const event of res.content) {
                     yield event;
                 }
-                // (TODO): this.stats.usage.add(res.usage)
             }
+            this.agent.emit("model.call.end", {
+                kind: "model.call.end",
+                provider: this.model.provider,
+                modelId: this.model.modelId,
+                finishReason,
+                usage,
+                threadId: this.tid,
+                agentId: this.agent.id,
+                context: this.context,
+            });
         }
         catch (error) {
+            this.agent.emit("model.call.end", {
+                kind: "model.call.end",
+                provider: this.model.provider,
+                modelId: this.model.modelId,
+                finishReason: "error",
+                threadId: this.tid,
+                agentId: this.agent.id,
+                context: this.context,
+            });
             yield {
                 kind: "error",
                 error: error instanceof Error ? error : new Error(String(error)),
@@ -343,6 +377,16 @@ export class Thread {
      */
     async executeTools(calls) {
         return await Promise.all(calls.map(async (call) => {
+            const parsedArgs = JSON.parse(call.arguments || "{}");
+            this.agent.emit("tool.call.start", {
+                kind: "tool.call.start",
+                threadId: this.tid,
+                agentId: this.agent.id,
+                context: this.context,
+                toolId: call.toolId,
+                callId: call.callId,
+                args: parsedArgs,
+            });
             try {
                 const tool = this.agent.tool(call.toolId);
                 if (!tool) {
@@ -356,6 +400,19 @@ export class Thread {
                 ctx.agent = this.agent;
                 ctx.approve(call.callId); // mark this call as approved
                 const res = await tool.invoke(ctx, call.arguments, call.callId);
+                this.agent.emit("tool.call.end", {
+                    kind: "tool.call.end",
+                    threadId: this.tid,
+                    agentId: this.agent.id,
+                    context: this.context,
+                    toolId: call.toolId,
+                    callId: call.callId,
+                    state: res.state,
+                    result: typeof res.result === "string"
+                        ? res.result
+                        : JSON.stringify(res.result),
+                    error: res.error,
+                });
                 return {
                     kind: "tool-result",
                     callId: call.callId,
@@ -366,6 +423,16 @@ export class Thread {
                 };
             }
             catch (error) {
+                this.agent.emit("tool.call.end", {
+                    kind: "tool.call.end",
+                    threadId: this.tid,
+                    agentId: this.agent.id,
+                    context: this.context,
+                    toolId: call.toolId,
+                    callId: call.callId,
+                    state: FAILED,
+                    error: error instanceof Error ? error.message : String(error),
+                });
                 return {
                     kind: "tool-result",
                     callId: call.callId,

package/dist/thread/types.d.ts

@@ -124,7 +124,7 @@ export interface ThreadOptions<TContext = unknown, TOutput extends AgentOutputTy
  * Options passed to agent.execute() and agent.stream().
  */
 export interface ThreadExecuteOptions<TContext> {
-    context?: Context<TContext>;
+    context?: TContext;
     model?: LanguageModel;
     task?: Task<TContext>;
     threadId?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/thread/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/thread/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kernl",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "A modern AI agent framework",
   "keywords": [
     "kernl",
@@ -34,8 +34,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.20.2",
     "yaml": "^2.8.2",
-    "@kernl-sdk/protocol": "0.3.1",
-    "@kernl-sdk/retrieval": "0.1.5",
+    "@kernl-sdk/protocol": "0.4.1",
+    "@kernl-sdk/retrieval": "0.1.7",
     "@kernl-sdk/shared": "^0.3.1"
   },
   "peerDependencies": {
@@ -48,7 +48,7 @@
     "typescript": "5.9.2",
     "vitest": "^4.0.8",
     "zod": "^4.1.8",
-    "@kernl-sdk/ai": "0.3.2"
+    "@kernl-sdk/ai": "0.3.4"
   },
   "scripts": {
     "clean": "rm -rf dist",

package/src/agent/base.ts

@@ -4,7 +4,7 @@ import type { Context, UnknownContext } from "@/context";
 import type { Tool, BaseToolkit } from "@/tool";
 import { memory } from "@/tool";
 import { MisconfiguredError } from "@/lib/error";
-import { AgentHooks } from "@/lifecycle";
+import { AgentHooks, type AgentHookEvents } from "@/lifecycle";
 import type { Kernl } from "@/kernl";
 import type {
   AgentMemoryCreate,
@@ -101,6 +101,18 @@ export abstract class BaseAgent<
     }
   }
 
+  /**
+   * Emit a lifecycle event to agent and kernl listeners.
+   */
+  emit<K extends keyof AgentHookEvents<TContext, TOutput>>(
+    event: K,
+    ...args: AgentHookEvents<TContext, TOutput>[K]
+  ): boolean {
+    const result = super.emit(event, ...args);
+    this.kernl?.emit(event, ...(args as any));
+    return result;
+  }
+
   /**
    * Get a specific tool by ID from systools and toolkits.
    */

package/src/agent.ts

@@ -13,7 +13,7 @@ import type {
   RThreadHistoryParams,
   RThreadUpdateParams,
 } from "@/api/resources/threads/types";
-import type { Context, UnknownContext } from "./context";
+import { Context, type UnknownContext } from "./context";
 import {
   InputGuardrail,
   OutputGuardrail,
@@ -102,10 +102,14 @@ export class Agent<
 
     // create new thread if not found in storage or no tid provided
     if (!thread) {
+      const ctx = options?.context
+        ? new Context<TContext>(options?.namespace ?? "kernl", options.context)
+        : undefined;
+
       thread = new Thread({
         agent: this,
         input: items,
-        context: options?.context,
+        context: ctx,
         model: options?.model,
         task: options?.task,
         tid: options?.threadId,
@@ -116,6 +120,9 @@ export class Agent<
     }
 
     // resume existing thread from storage
+    if (options?.context) {
+      thread.context.context = options.context;
+    }
     thread.append(...items);
     return this.kernl.schedule(thread);
   }
@@ -163,10 +170,14 @@ export class Agent<
 
     // create new thread if not found in storage or no tid provided
     if (!thread) {
+      const ctx = options?.context
+        ? new Context<TContext>(options?.namespace ?? "kernl", options.context)
+        : undefined;
+
       thread = new Thread({
         agent: this,
         input: items,
-        context: options?.context,
+        context: ctx,
         model: options?.model,
         task: options?.task,
         tid: options?.threadId,
@@ -178,6 +189,9 @@ export class Agent<
     }
 
     // resume existing thread from storage
+    if (options?.context) {
+      thread.context.context = options.context;
+    }
     thread.append(...items);
     yield* this.kernl.scheduleStream(thread);
   }

package/src/context.ts

@@ -23,6 +23,8 @@ export class Context<TContext = UnknownContext> {
   /**
    * The agent executing this context.
    * Set by the thread during execution.
+   *
+   * NOTE: Primarily used by system tools (e.g., memory) that need agent access.
    */
   agent?: Agent<TContext, any>;
 

package/src/index.ts

@@ -8,11 +8,20 @@ export type {
 export { Agent } from "./agent";
 export { Context } from "./context";
 
+// --- realtime ---
+
+export { RealtimeAgent, RealtimeSession, WebSocketTransport } from "./realtime";
+export type {
+  RealtimeAgentConfig,
+  RealtimeAgentVoiceConfig,
+  RealtimeSessionOptions,
+  WebSocketTransportOptions,
+} from "./realtime";
+
 // --- tools --
 
 export { tool, Toolkit, FunctionToolkit, MCPToolkit } from "./tool";
 export { MCPServerSSE } from "./mcp/sse";
-export { MCPServerStdio } from "./mcp/stdio";
 export { MCPServerStreamableHttp } from "./mcp/http";
 
 // --- threads ---