@kernl-sdk/protocol 0.2.8 → 0.3.1

package/src/realtime/model.ts

@@ -0,0 +1,121 @@
+import { SharedProviderMetadata } from "@/provider";
+import { RealtimeClientEvent, RealtimeServerEvent } from "./events";
+import { RealtimeConnectOptions, TransportStatus } from "./types";
+
+/**
+ * A realtime model that can establish bidirectional streaming connections.
+ *
+ * Models are reusable - each call to connect() creates a new connection.
+ * Providers implement this interface.
+ */
+export interface RealtimeModel {
+  /**
+   * The realtime model spec version.
+   */
+  readonly spec: "1.0";
+
+  /**
+   * Provider ID (e.g., "openai", "google", "elevenlabs").
+   */
+  readonly provider: string;
+
+  /**
+   * Model ID (e.g., "gpt-4o-realtime", "gemini-2.0-flash").
+   */
+  readonly modelId: string;
+
+  /**
+   * Establish a connection and return a connection instance.
+   */
+  connect(options?: RealtimeConnectOptions): Promise<RealtimeConnection>;
+}
+
+/**
+ * An active bidirectional connection to a realtime model.
+ *
+ * One connection per session. Providers implement this interface.
+ */
+export interface RealtimeConnection {
+  /**
+   * Current connection status.
+   */
+  readonly status: TransportStatus;
+
+  /**
+   * Whether input audio is muted.
+   * null if muting is not handled by the connection.
+   */
+  readonly muted: boolean | null;
+
+  /**
+   * Session ID once connected.
+   */
+  readonly sessionId: string | null;
+
+  /**
+   * Provider-specific metadata.
+   */
+  readonly providerMetadata?: SharedProviderMetadata;
+
+  /**
+   * Send a client event to the model.
+   */
+  send(event: RealtimeClientEvent): void;
+
+  /**
+   * Close the connection.
+   */
+  close(): void;
+
+  /**
+   * Mute input audio.
+   */
+  mute(): void;
+
+  /**
+   * Unmute input audio.
+   */
+  unmute(): void;
+
+  /**
+   * Interrupt the current response.
+   * Convenience for sending response.cancel event.
+   */
+  interrupt(): void;
+
+  // --- event subscription ---
+
+  on(event: "event", listener: (event: RealtimeServerEvent) => void): this;
+  on(event: "status", listener: (status: TransportStatus) => void): this;
+  on(event: "error", listener: (error: Error) => void): this;
+
+  off(event: "event", listener: (event: RealtimeServerEvent) => void): this;
+  off(event: "status", listener: (status: TransportStatus) => void): this;
+  off(event: "error", listener: (error: Error) => void): this;
+
+  once(event: "event", listener: (event: RealtimeServerEvent) => void): this;
+  once(event: "status", listener: (status: TransportStatus) => void): this;
+  once(event: "error", listener: (error: Error) => void): this;
+}
+
+/**
+ * A transport factory for custom connection mechanisms (e.g., WebRTC).
+ *
+ * Pass to RealtimeSession when you need to handle audio via media tracks
+ * instead of base64 events.
+ */
+export interface RealtimeTransport {
+  /**
+   * Whether this transport handles audio I/O internally (e.g., WebRTC).
+   * If true, cannot use a channel with this transport.
+   */
+  readonly handlesAudio: boolean;
+
+  /**
+   * Create a connection using this transport.
+   */
+  connect(
+    model: RealtimeModel,
+    options?: RealtimeConnectOptions,
+  ): Promise<RealtimeConnection>;
+}

package/src/realtime/types.ts

@@ -0,0 +1,276 @@
+import { SharedProviderOptions } from "@/provider";
+import { LanguageModelTool } from "@/language-model";
+
+export interface RealtimeConnectOptions {
+  /**
+   * Initial session configuration.
+   */
+  sessionConfig?: RealtimeSessionConfig;
+
+  /**
+   * Resume a previous session.
+   */
+  resume?: SessionResumeConfig;
+
+  /**
+   * Abort signal for cancelling connection.
+   */
+  abort?: AbortSignal;
+
+  /**
+   * Provider-specific options.
+   */
+  providerOptions?: SharedProviderOptions;
+}
+
+/**
+ * Configuration for a realtime session.
+ */
+export interface RealtimeSessionConfig {
+  /**
+   * System instructions for the model.
+   */
+  instructions?: string;
+
+  /**
+   * Available tools the model can call.
+   */
+  tools?: LanguageModelTool[];
+
+  /**
+   * Tool choice behavior.
+   */
+  toolChoice?: RealtimeToolChoice;
+
+  /**
+   * Output modalities (text, audio, or both).
+   */
+  modalities?: RealtimeModality[];
+
+  /**
+   * Voice configuration for audio output.
+   */
+  voice?: VoiceConfig;
+
+  /**
+   * Audio format configuration.
+   */
+  audio?: AudioConfig;
+
+  /**
+   * Turn detection / VAD configuration.
+   */
+  turnDetection?: TurnDetectionConfig;
+
+  /**
+   * Provider-specific options.
+   */
+  providerOptions?: SharedProviderOptions;
+}
+
+/**
+ * Output modality for realtime sessions.
+ */
+export type RealtimeModality = "text" | "audio";
+
+/**
+ * Tool choice behavior for realtime sessions.
+ */
+export type RealtimeToolChoice =
+  | { kind: "auto" }
+  | { kind: "none" }
+  | { kind: "required" };
+
+/**
+ * Voice configuration for audio output.
+ */
+export interface VoiceConfig {
+  /**
+   * Voice ID (provider-specific).
+   */
+  voiceId: string;
+
+  /**
+   * Playback speed multiplier.
+   */
+  speed?: number;
+}
+
+/**
+ * Audio format configuration for input and output.
+ */
+export interface AudioConfig {
+  /**
+   * Input audio format.
+   */
+  inputFormat?: AudioFormat;
+
+  /**
+   * Output audio format.
+   */
+  outputFormat?: AudioFormat;
+}
+
+/**
+ * Audio format specification.
+ */
+export interface AudioFormat {
+  /**
+   * MIME type (e.g., "audio/pcm", "audio/wav").
+   */
+  mimeType: string;
+
+  /**
+   * Sample rate in Hz.
+   */
+  sampleRate?: number;
+
+  /**
+   * Bits per sample.
+   */
+  bitDepth?: number;
+
+  /**
+   * Number of channels.
+   */
+  channels?: number;
+}
+
+/**
+ * Turn detection / VAD configuration.
+ */
+export interface TurnDetectionConfig {
+  /**
+   * Detection mode.
+   */
+  mode: "server_vad" | "manual";
+
+  /**
+   * VAD threshold (0-1).
+   */
+  threshold?: number;
+
+  /**
+   * Silence duration to trigger end of speech (ms).
+   */
+  silenceDurationMs?: number;
+
+  /**
+   * Audio to include before speech start (ms).
+   */
+  prefixPaddingMs?: number;
+
+  /**
+   * Auto-create response on speech end.
+   */
+  createResponse?: boolean;
+
+  /**
+   * Allow interruption of ongoing response.
+   */
+  interruptResponse?: boolean;
+}
+
+/**
+ * Configuration for resuming a previous session.
+ */
+export interface SessionResumeConfig {
+  /**
+   * Handle from a previous session.
+   */
+  handle: string;
+}
+
+/**
+ * Configuration for creating a response (for response.create event).
+ */
+export interface RealtimeResponseConfig {
+  /**
+   * Override session instructions for this response.
+   */
+  instructions?: string;
+
+  /**
+   * Override tools for this response.
+   */
+  tools?: LanguageModelTool[];
+
+  /**
+   * Override modalities for this response.
+   */
+  modalities?: RealtimeModality[];
+}
+
+/**
+ * A realtime session as returned from the server.
+ */
+export interface RealtimeSession {
+  /**
+   * Unique session identifier.
+   */
+  id: string;
+
+  /**
+   * Current session configuration.
+   */
+  config: RealtimeSessionConfig;
+}
+
+/**
+ * Error from a realtime session.
+ */
+export interface RealtimeError {
+  /**
+   * Error code.
+   */
+  code: string;
+
+  /**
+   * Human-readable error message.
+   */
+  message: string;
+
+  /**
+   * Additional error details.
+   */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Token usage information for a response.
+ */
+export interface RealtimeUsage {
+  /**
+   * Number of input tokens.
+   */
+  inputTokens?: number;
+
+  /**
+   * Number of output tokens.
+   */
+  outputTokens?: number;
+
+  /**
+   * Total number of tokens.
+   */
+  totalTokens?: number;
+}
+
+/**
+ * Status of a response.
+ */
+export type ResponseStatus =
+  | "completed"
+  | "interrupted"
+  | "cancelled"
+  | "failed";
+
+/**
+ * Status of a realtime transport connection.
+ */
+export type TransportStatus =
+  | "disconnected"
+  | "connecting"
+  | "connected"
+  | "reconnecting"
+  | "closed";

package/.turbo/turbo-check-types.log

@@ -1,4 +0,0 @@
-
-> @kernl-sdk/protocol@0.2.5 check-types /Users/andjones/Documents/projects/kernl/packages/protocol
-> tsc --noEmit
-

package/dist/codec.d.ts

@@ -1,22 +0,0 @@
-/**
- * Bidirectional codec for converting between kernl protocol types and provider-specific types.
- *
- * @example
- * ```typescript
- * const tools: Codec<LanguageModelTool[], ProviderTool[]> = {
- *   encode: (tools: Tool[]) => tools.map(convertToProvider),
- *   decode: () => { throw new Error("codec:unimplemented"); },
- * };
- * ```
- */
-export interface Codec<TKernl, TProvider> {
-    /**
-     * Transform from kernl protocol format to provider format.
-     */
-    encode: (value: TKernl) => TProvider;
-    /**
-     * Transform from provider format to kernl protocol format.
-     */
-    decode: (value: TProvider) => TKernl;
-}
-//# sourceMappingURL=codec.d.ts.map

package/dist/codec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../src/codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,KAAK,CAAC,MAAM,EAAE,SAAS;IACtC;;OAEG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,SAAS,CAAC;IAErC;;OAEG;IACH,MAAM,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,MAAM,CAAC;CACtC"}

package/dist/embedding-model/embedding-model.d.ts

@@ -1,57 +0,0 @@
-/**
- * Embedding Model Protocol
- *
- * Defines the standard interface for embedding model providers in Kernl.
- */
-import { Usage } from "../language-model/index.js";
-/**
- * A request to an embedding model.
- */
-export interface EmbeddingRequest {
-    /**
-     * The input text(s) to embed.
-     * Can be a single string or an array of strings.
-     */
-    input: string | string[];
-    /**
-     * The number of dimensions for the embeddings.
-     * Optional - defaults to the model's default dimensionality.
-     */
-    dimensions?: number;
-    /**
-     * Additional provider-specific options.
-     */
-    providerData?: Record<string, any>;
-}
-/**
- * The response from an embedding model.
- */
-export interface EmbeddingResponse {
-    /**
-     * The generated embeddings.
-     * Each embedding is an array of numbers (the embedding vector).
-     */
-    embeddings: number[][];
-    /**
-     * The usage information for the embedding request.
-     */
-    usage: Usage;
-    /**
-     * Raw response data from the underlying model provider.
-     */
-    providerData?: Record<string, any>;
-}
-/**
- * The base interface for calling an embedding model.
- *
- * All embedding model providers must implement this interface.
- */
-export interface EmbeddingModel {
-    /**
-     * Generate embeddings for the given input.
-     *
-     * @param request - The embedding request.
-     */
-    embed(request: EmbeddingRequest): Promise<EmbeddingResponse>;
-}
-//# sourceMappingURL=embedding-model.d.ts.map

package/dist/embedding-model/embedding-model.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"embedding-model.d.ts","sourceRoot":"","sources":["../../src/embedding-model/embedding-model.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAM1C;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAEzB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,UAAU,EAAE,MAAM,EAAE,EAAE,CAAC;IAEvB;;OAEG;IACH,KAAK,EAAE,KAAK,CAAC;IAEb;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,KAAK,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAC9D"}

package/dist/embedding-model/embedding-model.js

@@ -1,6 +0,0 @@
-/**
- * Embedding Model Protocol
- *
- * Defines the standard interface for embedding model providers in Kernl.
- */
-export {};

package/dist/language-model/content.d.ts

@@ -1,141 +0,0 @@
-import { SharedProviderMetadata } from "../provider/metadata.js";
-import { JSONValue } from "../json.js";
-export type LanguageModelContent = LanguageModelText | LanguageModelReasoning | LanguageModelFile | LanguageModelSource | LanguageModelToolCall | LanguageModelToolResult;
-/**
- * Text that the model has generated.
- */
-export type LanguageModelText = {
-    kind: "text";
-    /**
-     * The text content.
-     */
-    text: string;
-    /**
-     * Optional provider-specific metadata for the text part.
-     */
-    providerMetadata?: SharedProviderMetadata;
-};
-/**
- * Reasoning that the model has generated.
- */
-export type LanguageModelReasoning = {
-    kind: "reasoning";
-    /**
-     * The reasoning content
-     */
-    text: string;
-    /**
-     * Optional provider-specific metadata for the reasoning part.
-     */
-    providerMetadata?: SharedProviderMetadata;
-};
-/**
- * A file that has been generated by the model.
- *
- * May be base64 encoded strings or binary data.
- */
-export type LanguageModelFile = {
-    kind: "file";
-    /**
-     * The IANA media type of the file, e.g. `image/png` or `audio/mp3`.
-     *
-     * @see https://www.iana.org/assignments/media-types/media-types.xhtml
-     */
-    mime: string;
-    /**
-     * Generated file data as base64 encoded strings or binary data.
-     */
-    data: string | Uint8Array;
-    /**
-     * Optional filename for the file
-     */
-    filename?: string;
-};
-/**
- * A source that has been used as input to generate the response.
- */
-export type LanguageModelSource = {
-    kind: "source";
-    /**
-     * The ID of the source.
-     */
-    id: string;
-    /**
-     * The URI of the source.
-     */
-    uri: string;
-    /**
-     * IANA media type of the document (e.g., 'application/pdf').
-     */
-    mime: string;
-    /**
-     * The title of the source.
-     */
-    title?: string;
-    /**
-     * Additional metadata for the source.
-     */
-    metadata?: Record<string, any>;
-    /**
-     * Additional provider metadata for the source.
-     */
-    providerMetadata?: SharedProviderMetadata;
-};
-export type LanguageModelToolCallStatus = "in_progress" | "completed" | "incomplete" | "failed";
-/**
- * Tool calls that the model has generated.
- */
-export type LanguageModelToolCall = {
-    kind: "tool-call";
-    /**
-     * The identifier of the tool call. It must be unique across all tool calls.
-     */
-    callId: string;
-    /**
-     * The id of the tool that should be called.
-     */
-    toolId: string;
-    /**
-     * The status of the tool call.
-     */
-    status: LanguageModelToolCallStatus;
-    /**
-     * The stringified JSON object with the arguments of the tool call.
-     */
-    arguments: string;
-    /**
-     * Additional provider-specific metadata for the tool call.
-     */
-    providerMetadata?: SharedProviderMetadata;
-};
-/**
- * Result of a tool call that has been executed by the provider.
- */
-export type LanguageModelToolResult = {
-    kind: "tool-result";
-    /**
-     * The ID of the tool call that this result is associated with.
-     */
-    callId: string;
-    /**
-     * Name of the tool that generated this result.
-     */
-    toolId: string;
-    /**
-     * The status of the tool call.
-     */
-    status: LanguageModelToolCallStatus;
-    /**
-     * Result of the tool call. This is a JSON-serializable object.
-     */
-    result: NonNullable<JSONValue>;
-    /**
-     * Error message if the tool call failed
-     */
-    error: string | null;
-    /**
-     * Additional provider-specific metadata for the tool result.
-     */
-    providerMetadata?: SharedProviderMetadata;
-};
-//# sourceMappingURL=content.d.ts.map

package/dist/language-model/content.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/language-model/content.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEpC,MAAM,MAAM,oBAAoB,GAC5B,iBAAiB,GACjB,sBAAsB,GACtB,iBAAiB,GACjB,mBAAmB,GACnB,qBAAqB,GACrB,uBAAuB,CAAC;AAE5B;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,WAAW,CAAC;IAElB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,QAAQ,CAAC;IAEf;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE/B;;OAEG;IACH,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C,CAAC;AAEF,MAAM,MAAM,2BAA2B,GACnC,aAAa,GACb,WAAW,GACX,YAAY,GACZ,QAAQ,CAAC;AAEb;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,IAAI,EAAE,WAAW,CAAC;IAElB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,EAAE,2BAA2B,CAAC;IAEpC;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,EAAE,aAAa,CAAC;IAEpB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,MAAM,EAAE,2BAA2B,CAAC;IAEpC;;OAEG;IACH,MAAM,EAAE,WAAW,CAAC,SAAS,CAAC,CAAC;IAE/B;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAErB;;OAEG;IACH,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;CAC3C,CAAC"}