@kernl-sdk/protocol 0.2.8 → 0.3.0

package/dist/realtime/types.d.ts

@@ -0,0 +1,229 @@
+import { SharedProviderOptions } from "../provider/index.js";
+import { LanguageModelTool } from "../language-model/index.js";
+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";
+//# sourceMappingURL=types.d.ts.map

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernl-sdk/protocol",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Protocol specification for kernl",
   "keywords": [
     "kernl",

package/src/index.ts

@@ -7,5 +7,6 @@
 export * from "./constants";
 export * from "./language-model";
 export * from "./embedding-model";
+export * from "./realtime";
 export * from "./provider";
 export * from "./json";

package/src/realtime/events.ts

@@ -0,0 +1,397 @@
+import { SharedProviderMetadata } from "@/provider";
+import { LanguageModelItem } from "@/language-model";
+import {
+  RealtimeSession,
+  RealtimeSessionConfig,
+  RealtimeResponseConfig,
+  RealtimeError,
+  RealtimeUsage,
+  ResponseStatus,
+} from "./types";
+
+/**
+ * Base interface for all realtime events.
+ */
+export interface RealtimeEventBase {
+  /**
+   * Unique identifier for this event.
+   */
+  id?: string;
+
+  /**
+   * Provider-specific metadata.
+   */
+  providerMetadata?: SharedProviderMetadata;
+}
+
+/**
+ * Union of all client → server events.
+ */
+export type RealtimeClientEvent =
+  | SessionUpdateEvent
+  | ItemCreateEvent
+  | ItemDeleteEvent
+  | ItemTruncateEvent
+  | AudioInputAppendEvent
+  | AudioInputCommitEvent
+  | AudioInputClearEvent
+  | ActivityStartEvent
+  | ActivityEndEvent
+  | ResponseCreateEvent
+  | ResponseCancelEvent
+  | ToolResultEvent;
+
+/**
+ * Union of all server → client events.
+ */
+export type RealtimeServerEvent =
+  | SessionCreatedEvent
+  | SessionUpdatedEvent
+  | SessionErrorEvent
+  | ItemCreatedEvent
+  | ItemDeletedEvent
+  | ItemTruncatedEvent
+  | AudioInputCommittedEvent
+  | AudioInputClearedEvent
+  | SpeechStartedEvent
+  | SpeechStoppedEvent
+  | AudioOutputDeltaEvent
+  | AudioOutputDoneEvent
+  | TextOutputDeltaEvent
+  | TextOutputEvent
+  | TranscriptInputDeltaEvent
+  | TranscriptInputEvent
+  | TranscriptOutputDeltaEvent
+  | TranscriptOutputEvent
+  | ResponseCreatedEvent
+  | ResponseInterruptedEvent
+  | ResponseDoneEvent
+  | ToolStartEvent
+  | ToolDeltaEvent
+  | ToolCallEvent
+  | ToolCancelledEvent;
+
+/**
+ * Client event to update session configuration.
+ */
+export interface SessionUpdateEvent extends RealtimeEventBase {
+  readonly kind: "session.update";
+  config: RealtimeSessionConfig;
+}
+
+/**
+ * Client event to add an item to the conversation.
+ */
+export interface ItemCreateEvent extends RealtimeEventBase {
+  readonly kind: "item.create";
+  item: LanguageModelItem;
+  previousItemId?: string;
+}
+
+/**
+ * Client event to delete an item from the conversation.
+ */
+export interface ItemDeleteEvent extends RealtimeEventBase {
+  readonly kind: "item.delete";
+  itemId: string;
+}
+
+/**
+ * Client event to truncate assistant audio at a specific timestamp.
+ */
+export interface ItemTruncateEvent extends RealtimeEventBase {
+  readonly kind: "item.truncate";
+  itemId: string;
+  audioEndMs: number;
+}
+
+/**
+ * Client event to append audio to the input buffer.
+ */
+export interface AudioInputAppendEvent extends RealtimeEventBase {
+  readonly kind: "audio.input.append";
+  /**
+   * Base64-encoded audio data.
+   */
+  audio: string;
+}
+
+/**
+ * Client event to commit the audio input buffer as a user message.
+ */
+export interface AudioInputCommitEvent extends RealtimeEventBase {
+  readonly kind: "audio.input.commit";
+}
+
+/**
+ * Client event to clear the audio input buffer.
+ */
+export interface AudioInputClearEvent extends RealtimeEventBase {
+  readonly kind: "audio.input.clear";
+}
+
+/**
+ * Client event to signal start of user activity (manual VAD).
+ */
+export interface ActivityStartEvent extends RealtimeEventBase {
+  readonly kind: "activity.start";
+}
+
+/**
+ * Client event to signal end of user activity (manual VAD).
+ */
+export interface ActivityEndEvent extends RealtimeEventBase {
+  readonly kind: "activity.end";
+}
+
+/**
+ * Client event to trigger a model response.
+ */
+export interface ResponseCreateEvent extends RealtimeEventBase {
+  readonly kind: "response.create";
+  config?: RealtimeResponseConfig;
+}
+
+/**
+ * Client event to cancel an in-progress response.
+ */
+export interface ResponseCancelEvent extends RealtimeEventBase {
+  readonly kind: "response.cancel";
+  responseId?: string;
+}
+
+/**
+ * Server event indicating the session has been created.
+ */
+export interface SessionCreatedEvent extends RealtimeEventBase {
+  readonly kind: "session.created";
+  session: RealtimeSession;
+}
+
+/**
+ * Server event indicating the session configuration has been updated.
+ */
+export interface SessionUpdatedEvent extends RealtimeEventBase {
+  readonly kind: "session.updated";
+  session: RealtimeSession;
+}
+
+/**
+ * Server event indicating a session error.
+ */
+export interface SessionErrorEvent extends RealtimeEventBase {
+  readonly kind: "session.error";
+  error: RealtimeError;
+}
+
+/**
+ * Server event indicating an item has been added to the conversation.
+ */
+export interface ItemCreatedEvent extends RealtimeEventBase {
+  readonly kind: "item.created";
+  item: LanguageModelItem;
+  previousItemId?: string;
+}
+
+/**
+ * Server event indicating an item has been deleted.
+ */
+export interface ItemDeletedEvent extends RealtimeEventBase {
+  readonly kind: "item.deleted";
+  itemId: string;
+}
+
+/**
+ * Server event indicating an item has been truncated.
+ */
+export interface ItemTruncatedEvent extends RealtimeEventBase {
+  readonly kind: "item.truncated";
+  itemId: string;
+  audioEndMs: number;
+}
+
+/**
+ * Server event confirming the audio input buffer has been committed.
+ */
+export interface AudioInputCommittedEvent extends RealtimeEventBase {
+  readonly kind: "audio.input.committed";
+  itemId: string;
+}
+
+/**
+ * Server event confirming the audio input buffer has been cleared.
+ */
+export interface AudioInputClearedEvent extends RealtimeEventBase {
+  readonly kind: "audio.input.cleared";
+}
+
+/**
+ * Server event indicating speech has been detected (VAD).
+ */
+export interface SpeechStartedEvent extends RealtimeEventBase {
+  readonly kind: "speech.started";
+  audioStartMs: number;
+  itemId: string;
+}
+
+/**
+ * Server event indicating speech has stopped (VAD).
+ */
+export interface SpeechStoppedEvent extends RealtimeEventBase {
+  readonly kind: "speech.stopped";
+  audioEndMs: number;
+  itemId: string;
+}
+
+/**
+ * Server event containing an audio output chunk.
+ */
+export interface AudioOutputDeltaEvent extends RealtimeEventBase {
+  readonly kind: "audio.output.delta";
+  responseId: string;
+  itemId: string;
+  /**
+   * Base64-encoded audio chunk.
+   */
+  audio: string;
+}
+
+/**
+ * Server event indicating audio output is complete.
+ */
+export interface AudioOutputDoneEvent extends RealtimeEventBase {
+  readonly kind: "audio.output.done";
+  responseId: string;
+  itemId: string;
+}
+
+/**
+ * Server event containing a text output chunk.
+ */
+export interface TextOutputDeltaEvent extends RealtimeEventBase {
+  readonly kind: "text.output.delta";
+  responseId: string;
+  itemId: string;
+  delta: string;
+}
+
+/**
+ * Server event containing the complete text output.
+ */
+export interface TextOutputEvent extends RealtimeEventBase {
+  readonly kind: "text.output";
+  responseId: string;
+  itemId: string;
+  text: string;
+}
+
+/**
+ * Server event containing an input transcription chunk.
+ */
+export interface TranscriptInputDeltaEvent extends RealtimeEventBase {
+  readonly kind: "transcript.input.delta";
+  itemId: string;
+  delta: string;
+}
+
+/**
+ * Server event containing the complete input transcription.
+ */
+export interface TranscriptInputEvent extends RealtimeEventBase {
+  readonly kind: "transcript.input";
+  itemId: string;
+  text: string;
+}
+
+/**
+ * Server event containing an output transcription chunk.
+ */
+export interface TranscriptOutputDeltaEvent extends RealtimeEventBase {
+  readonly kind: "transcript.output.delta";
+  responseId: string;
+  itemId: string;
+  delta: string;
+}
+
+/**
+ * Server event containing the complete output transcription.
+ */
+export interface TranscriptOutputEvent extends RealtimeEventBase {
+  readonly kind: "transcript.output";
+  responseId: string;
+  itemId: string;
+  text: string;
+}
+
+/**
+ * Server event indicating a response has been created.
+ */
+export interface ResponseCreatedEvent extends RealtimeEventBase {
+  readonly kind: "response.created";
+  responseId: string;
+}
+
+/**
+ * Server event indicating a response has been interrupted.
+ */
+export interface ResponseInterruptedEvent extends RealtimeEventBase {
+  readonly kind: "response.interrupted";
+  responseId: string;
+}
+
+/**
+ * Server event indicating a response is complete.
+ */
+export interface ResponseDoneEvent extends RealtimeEventBase {
+  readonly kind: "response.done";
+  responseId: string;
+  status: ResponseStatus;
+  usage?: RealtimeUsage;
+}
+
+/**
+ * Server event indicating a tool call has started.
+ */
+export interface ToolStartEvent extends RealtimeEventBase {
+  readonly kind: "tool.start";
+  responseId: string;
+  callId: string;
+  toolId: string;
+}
+
+/**
+ * Server event containing a tool call arguments chunk.
+ */
+export interface ToolDeltaEvent extends RealtimeEventBase {
+  readonly kind: "tool.delta";
+  callId: string;
+  delta: string;
+}
+
+/**
+ * Server event indicating the model wants to call a tool.
+ */
+export interface ToolCallEvent extends RealtimeEventBase {
+  readonly kind: "tool.call";
+  callId: string;
+  toolId: string;
+  arguments: string;
+}
+
+/**
+ * Server event indicating a tool call has been cancelled.
+ */
+export interface ToolCancelledEvent extends RealtimeEventBase {
+  readonly kind: "tool.cancelled";
+  callId: string;
+}
+
+/**
+ * Client event to submit a tool result.
+ */
+export interface ToolResultEvent extends RealtimeEventBase {
+  readonly kind: "tool.result";
+  callId: string;
+  result?: string;
+  error?: string;
+}

package/src/realtime/index.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./events";
+export * from "./model";