mojentic 1.2.4 → 1.5.0

package/dist/realtime/session.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Realtime session — the stateful surface exposed by {@link RealtimeVoiceBroker}.
+ *
+ * Owns the socket lifetime, demultiplexes raw server events into a
+ * vendor-neutral {@link RealtimeEvent} stream, and drives parallel tool
+ * execution per response turn.
+ */
+import { Result } from '../error';
+import { TracerSystem } from '../tracer';
+import { ToolRunner } from '../llm/tools';
+import { RealtimeVoiceConfig } from './config';
+import { RealtimeEvent } from './events';
+import { RealtimeGatewaySession, ServerRealtimeEvent } from './gateway';
+/**
+ * Options accepted by {@link RealtimeSession}.
+ */
+export interface RealtimeSessionOptions {
+    config: RealtimeVoiceConfig;
+    toolRunner?: ToolRunner;
+    tracer?: TracerSystem;
+    correlationId?: string;
+}
+/**
+ * Encode an `Int16Array` or `Uint8Array` of PCM samples as base64.
+ */
+export declare function encodeBase64Pcm16(frame: Int16Array | Uint8Array): string;
+/**
+ * Build a vendor-specific `session.update` payload from a vendor-neutral
+ * config, matching the OpenAI Realtime GA shape:
+ *
+ * - `session.type: "realtime"` is required.
+ * - Vendor-neutral `modalities` maps to GA `output_modalities`.
+ * - Voice + output audio format live under `session.audio.output`.
+ * - Turn detection, transcription, and input audio format live under
+ *   `session.audio.input`.
+ * - `temperature` is no longer accepted on GA — silently dropped.
+ * - `maxResponseOutputTokens` maps to GA `max_output_tokens`.
+ */
+export declare function buildSessionUpdate(config: RealtimeVoiceConfig): {
+    type: 'session.update';
+    session: Record<string, unknown>;
+};
+/**
+ * Stateful realtime session handle.
+ *
+ * Constructed by {@link RealtimeVoiceBroker}; users don't instantiate this
+ * directly.
+ */
+export declare class RealtimeSession {
+    private readonly gatewaySession;
+    private readonly config;
+    private readonly tools;
+    private readonly toolRunner;
+    private readonly tracer?;
+    private readonly correlationId;
+    private readonly normalizedChannel;
+    private readonly rawChannel;
+    private readonly audioChannel;
+    private readonly pumpPromise;
+    private readonly pendingBatches;
+    private currentTurn?;
+    private currentResponseId?;
+    private closed;
+    private currentInstructions?;
+    constructor(gatewaySession: RealtimeGatewaySession, options: RealtimeSessionOptions);
+    /**
+     * Initialise the session by sending the `session.update`. Called once by
+     * the broker before returning the session to the caller.
+     */
+    initialise(): Promise<Result<void, Error>>;
+    /** Vendor-neutral event stream. Terminates when the session closes. */
+    events(): AsyncGenerator<RealtimeEvent>;
+    /** Raw server events for power users / debugging. */
+    rawEvents(): AsyncGenerator<ServerRealtimeEvent>;
+    /** Async generator yielding PCM frames from the assistant. */
+    audioOutput(): AsyncGenerator<Int16Array>;
+    /**
+     * Send a text-mode user message. Use this in text-only sessions and tests.
+     */
+    sendText(text: string): Promise<Result<void, Error>>;
+    /**
+     * Pipe an async iterable of PCM frames into the input audio buffer.
+     *
+     * Frames are encoded as base64 pcm16 and appended to the server VAD buffer.
+     * Returns once the iterable completes or the session closes.
+     */
+    sendAudio(stream: AsyncIterable<Int16Array | Uint8Array>): Promise<Result<void, Error>>;
+    /**
+     * Manually commit the input audio buffer (only meaningful with
+     * `turnDetection: 'none'`) and request a response.
+     */
+    commitAudio(): Promise<Result<void, Error>>;
+    /**
+     * Cancel the in-flight response, abort any in-flight tool execution, and
+     * fire an `interrupted` event with `reason: 'manual'`.
+     */
+    interrupt(): Promise<Result<void, Error>>;
+    /**
+     * Update the instructions used by future assistant turns. The change is
+     * sent immediately via a `session.update`.
+     */
+    updateInstructions(instructions: string): Promise<Result<void, Error>>;
+    /** Close the session, dispose the socket, and end all event streams. */
+    close(): Promise<void>;
+    /** Symbol.asyncDispose support for `await using` syntax. */
+    [Symbol.asyncDispose](): Promise<void>;
+    /** Effective instructions used in the most recent `session.update`. */
+    getInstructions(): string | undefined;
+    private pump;
+    private handleServerEvent;
+    private runToolBatchForTurn;
+    private selectOutputsToSubmit;
+    private cancelCurrentTurn;
+}
+//# sourceMappingURL=session.d.ts.map

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

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