kernl 0.9.1 → 0.11.0

package/src/realtime/session.ts

@@ -1,11 +1,12 @@
-import { EventEmitter } from "node:events";
-
+import { Emitter } from "@kernl-sdk/shared";
 import {
   RealtimeModel,
   RealtimeConnection,
   RealtimeServerEvent,
   RealtimeSessionConfig,
+  RealtimeChannel,
   ToolCallEvent,
+  TransportStatus,
   message,
 } from "@kernl-sdk/protocol";
 
@@ -13,16 +14,28 @@ import { Context, UnknownContext } from "@/context";
 import { MisconfiguredError } from "@/lib/error";
 
 import { RealtimeAgent } from "./agent";
-import type { RealtimeChannel } from "./channel";
 import type { RealtimeSessionOptions } from "./types";
 
+/**
+ * Events emitted by a realtime session.
+ */
+export type RealtimeSessionEvents = {
+  audio: [event: RealtimeServerEvent];
+  transcript: [event: RealtimeServerEvent];
+  text: [event: RealtimeServerEvent];
+  error: [error: Error];
+  status: [status: TransportStatus];
+};
+
 /**
  * A realtime session manages the connection to a realtime model.
  *
  * Handles the bidirectional communication between an agent and a model,
  * including audio I/O (via channels), tool execution, and event routing.
  */
-export class RealtimeSession<TContext = UnknownContext> extends EventEmitter {
+export class RealtimeSession<
+  TContext = UnknownContext,
+> extends Emitter<RealtimeSessionEvents> {
   /**
    * Session ID. Null until connected.
    */
@@ -85,6 +98,8 @@ export class RealtimeSession<TContext = UnknownContext> extends EventEmitter {
     const options = {
       ...this.options.connectOptions,
       sessionConfig,
+      credential:
+        this.options.credential ?? this.options.connectOptions?.credential,
     };
 
     this.connection = this.options.transport
@@ -94,6 +109,10 @@ export class RealtimeSession<TContext = UnknownContext> 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();
   }
@@ -114,6 +133,60 @@ export class RealtimeSession<TContext = UnknownContext> extends EventEmitter {
     });
   }
 
+  /**
+   * Send audio to the model.
+   */
+  sendAudio(audio: string): void {
+    this.connection?.send({ kind: "audio.input.append", audio });
+  }
+
+  /**
+   * Commit the audio buffer (signal end of speech).
+   */
+  commit(): void {
+    this.connection?.send({ kind: "audio.input.commit" });
+  }
+
+  /**
+   * Send a text message to the model.
+   */
+  sendMessage(text: string): void {
+    this.connection?.send({
+      kind: "item.create",
+      item: message({ role: "user", text }),
+    });
+  }
+
+  /**
+   * Interrupt the current response.
+   */
+  interrupt(): void {
+    this.connection?.send({ kind: "response.cancel" });
+    this.channel?.interrupt();
+  }
+
+  /**
+   * Mute audio input.
+   */
+  mute(): void {
+    this.connection?.mute();
+  }
+
+  /**
+   * Unmute audio input.
+   */
+  unmute(): void {
+    this.connection?.unmute();
+  }
+
+  /**
+   * Close the session and release resources.
+   */
+  close(): void {
+    this.channel?.close();
+    this.connection?.close();
+  }
+
   /**
    * Build session configuration from agent.
    */
@@ -124,6 +197,11 @@ export class RealtimeSession<TContext = UnknownContext> 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 },
+      },
     };
   }
 
@@ -138,7 +216,7 @@ export class RealtimeSession<TContext = UnknownContext> extends EventEmitter {
    */
   private onEvent(event: RealtimeServerEvent): void {
     switch (event.kind) {
-      // Audio output → 'audio'
+      // audio output → 'audio'
       case "audio.output.delta":
         this.channel?.sendAudio(event.audio);
         this.emit("audio", event);
@@ -147,28 +225,28 @@ export class RealtimeSession<TContext = UnknownContext> extends EventEmitter {
         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;
@@ -202,58 +280,4 @@ export class RealtimeSession<TContext = UnknownContext> extends EventEmitter {
       error: result.error ?? undefined,
     });
   }
-
-  /**
-   * Send audio to the model.
-   */
-  sendAudio(audio: string): void {
-    this.connection?.send({ kind: "audio.input.append", audio });
-  }
-
-  /**
-   * Commit the audio buffer (signal end of speech).
-   */
-  commit(): void {
-    this.connection?.send({ kind: "audio.input.commit" });
-  }
-
-  /**
-   * Send a text message to the model.
-   */
-  sendMessage(text: string): void {
-    this.connection?.send({
-      kind: "item.create",
-      item: message({ role: "user", text }),
-    });
-  }
-
-  /**
-   * Interrupt the current response.
-   */
-  interrupt(): void {
-    this.connection?.send({ kind: "response.cancel" });
-    this.channel?.interrupt();
-  }
-
-  /**
-   * Mute audio input.
-   */
-  mute(): void {
-    this.connection?.mute();
-  }
-
-  /**
-   * Unmute audio input.
-   */
-  unmute(): void {
-    this.connection?.unmute();
-  }
-
-  /**
-   * Close the session and release resources.
-   */
-  close(): void {
-    this.channel?.close();
-    this.connection?.close();
-  }
 }

package/src/realtime/transport.ts

@@ -0,0 +1,64 @@
+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 class WebSocketTransport implements RealtimeTransport {
+  readonly handlesAudio = false;
+  private WS: WebSocketConstructor | undefined;
+
+  constructor(options?: WebSocketTransportOptions) {
+    this.WS = options?.websocket;
+  }
+
+  async connect(
+    model: RealtimeModel,
+    options?: RealtimeConnectOptions,
+  ): Promise<RealtimeConnection> {
+    return model.connect({
+      ...options,
+      websocket: this.WS ?? options?.websocket,
+    });
+  }
+}

package/src/realtime/types.ts

@@ -2,13 +2,13 @@ import {
   RealtimeModel,
   RealtimeTransport,
   RealtimeConnectOptions,
+  RealtimeChannel,
+  ClientCredential,
 } from "@kernl-sdk/protocol";
 
 import { Context, UnknownContext } from "@/context";
 import type { BaseAgentConfig } from "@/agent/base";
 
-import type { RealtimeChannel } from "./channel";
-
 /**
  * Configuration for a realtime agent.
  */
@@ -66,6 +66,14 @@ export interface RealtimeSessionOptions<TContext = UnknownContext> {
    */
   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/src/thread/__tests__/thread.test.ts

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

package/src/thread/thread.ts

@@ -19,6 +19,8 @@ import {
   LanguageModel,
   LanguageModelItem,
   LanguageModelRequest,
+  type LanguageModelUsage,
+  type LanguageModelFinishReason,
 } from "@kernl-sdk/protocol";
 import { randomID, filter } from "@kernl-sdk/shared/lib";
 
@@ -90,8 +92,8 @@ export class Thread<
   readonly tid: string;
   readonly namespace: string;
   readonly agent: Agent<TContext, TOutput>;
-  readonly context: Context<TContext>;
-  readonly model: LanguageModel; /* inherited from the agent unless specified */
+  context: Context<TContext>;
+  model: LanguageModel; /* inherited from the agent unless specified */
   readonly parent: Task<TContext> | null; /* parent task which spawned this thread */
   readonly createdAt: Date;
   readonly updatedAt: Date;
@@ -200,7 +202,7 @@ export class Thread<
    */
   private async *_execute(): AsyncGenerator<ThreadStreamEvent, void> {
     for (;;) {
-      let err = false;
+      let err: Error | undefined = undefined;
 
       if (this.abort?.signal.aborted) {
         return;
@@ -209,7 +211,7 @@ export class Thread<
       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
@@ -220,9 +222,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
@@ -276,21 +278,59 @@ export class Thread<
 
     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: LanguageModelUsage | undefined;
+    let finishReason: LanguageModelFinishReason = "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)),
@@ -430,6 +470,18 @@ export class Thread<
   private async executeTools(calls: ToolCall[]): Promise<ThreadEventInner[]> {
     return await Promise.all(
       calls.map(async (call: ToolCall) => {
+        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) {
@@ -449,6 +501,21 @@ export class Thread<
           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" as const,
             callId: call.callId,
@@ -458,6 +525,17 @@ export class Thread<
             error: res.error,
           };
         } 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" as const,
             callId: call.callId,

package/src/thread/types.ts

@@ -179,7 +179,7 @@ export interface ThreadOptions<
  * 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/realtime/channel.d.ts

@@ -1,30 +0,0 @@
-import { EventEmitter } from "node:events";
-/**
- * Base interface for audio I/O channels.
- *
- * Channels bridge between audio sources (browser mic, Twilio, Discord)
- * and the realtime session. They handle audio capture/playback and emit
- * events that the session listens to.
- *
- * Events emitted:
- * - 'audio' (audio: string) - Raw audio chunk (base64)
- * - 'commit' () - User finished speaking (VAD or manual)
- * - 'interrupt' () - User started speaking mid-response
- */
-export interface RealtimeChannel extends EventEmitter {
-    /**
-     * Send audio to be played/transmitted by the channel.
-     * Called by session when audio is received from the model.
-     */
-    sendAudio(audio: string): void;
-    /**
-     * Interrupt current audio playback.
-     * Called by session when response is cancelled.
-     */
-    interrupt(): void;
-    /**
-     * Clean up resources and close the channel.
-     */
-    close(): void;
-}
-//# sourceMappingURL=channel.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/realtime/channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;;OAGG;IACH,SAAS,IAAI,IAAI,CAAC;IAElB;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/realtime/channel.js

@@ -1 +0,0 @@
-export {};

package/src/realtime/channel.ts

@@ -1,32 +0,0 @@
-import { EventEmitter } from "node:events";
-
-/**
- * Base interface for audio I/O channels.
- *
- * Channels bridge between audio sources (browser mic, Twilio, Discord)
- * and the realtime session. They handle audio capture/playback and emit
- * events that the session listens to.
- *
- * Events emitted:
- * - 'audio' (audio: string) - Raw audio chunk (base64)
- * - 'commit' () - User finished speaking (VAD or manual)
- * - 'interrupt' () - User started speaking mid-response
- */
-export interface RealtimeChannel extends EventEmitter {
-  /**
-   * Send audio to be played/transmitted by the channel.
-   * Called by session when audio is received from the model.
-   */
-  sendAudio(audio: string): void;
-
-  /**
-   * Interrupt current audio playback.
-   * Called by session when response is cancelled.
-   */
-  interrupt(): void;
-
-  /**
-   * Clean up resources and close the channel.
-   */
-  close(): void;
-}