Member Junction
    Preparing search index...

    Concrete IRealtimeSession backed by a raw Inworld Realtime WebSocket.

    Owns the inbound translation (Inworld wire events → Core events) and the outbound translation (Core calls → wire frames). Created by InworldRealtime.StartSession; never instantiated directly by consumers.

    Provider-behavior notes (the contract deltas a consumer should know):

    • session.update is the universal config channel. Model, instructions, audio/STT/TTS, tools, and turn-taking are all carried by session.update — at connect time AND mid-session. Components are swappable without reconnect, so RegisterTools and SendContextNote are native config writes (never interrupting generation).
    • Semantic VAD owns turn detection / barge-in. A raw "speech started" is NOT an interruption; the provider's true-barge-in signal (it tracks its own output emission) is surfaced only when it cuts off an ACTIVE response, gated on responseActive per the base contract.
    • Output supports inline steering tags (e.g. [laugh]) — passed through verbatim in instructions; the driver does not parse or strip them.
    • Tool results must reach the model. SendToolResult is sent immediately (the provider owns the spoken continuation) and marks a response active eagerly so a queued narration can't slip ahead.
    • RequestSpokenUpdate queues behind an in-flight response per the collision rule; a tool.call clears the busy flag WITHOUT draining the queue (deadlock guard, obligation #2).

    Hierarchy (View Summary)

    Implements

    Index

    Constructors

    Properties

    callsFromBeforeReseed: Set<string>
    closedByConsumer: boolean
    configuredCallDurationSeconds: number
    configuredReconnectBufferSeconds: number
    configuredSessionMaxSeconds: number
    configuredTrustNativeResumption: boolean
    configuredZeroDataRetention: boolean
    conversationMemory: RealtimeConversationMemory
    pendingToolCallNames: Map<string, string>
    reconnectController: RealtimeReconnectController
    turnOpen: boolean

    Accessors

    • get CallDurationSeconds(): number

      Effective single-connection duration in seconds, resolved via ClampSessionSecondsValue so metadata (configuredCallDurationSeconds) narrows the driver's provider ceiling (DefaultCallDurationSeconds) and any state-dependent RuntimeCallDurationSeconds, never widening it.

      Returns number

    • get ConversationMemory(): RealtimeConversationMemory

      Accessor for the session's provider-neutral conversation memory ledger.

      Returns RealtimeConversationMemory

    • get DefaultCallDurationSeconds(): number

      Static driver default connection duration in seconds when metadata does not specify one.

      Returns number

    • get DefaultTrustsNativeResumption(): boolean

      Driver default for whether native resumption handles are trusted when metadata does not override.

      Returns boolean

    • get IsClosedByConsumer(): boolean

      True once the consumer has closed the session.

      Returns boolean

    • get IsReconnecting(): boolean

      True while an in-place reconnect is currently running.

      Returns boolean

    • get ReconnectBufferSeconds(): number

      Buffer in seconds before CallDurationSeconds at which the framework initiates a reconnect.

      Returns number

    • get RequiresPostTurnResumptionHandle(): boolean

      Whether this session's provider emits a fresh resumable handle shortly after each turnComplete (e.g. Gemini / Vertex AI Live), so a planned move (goAway or soft window) during a turn waits for that post-turn handle (bounded by the deadline timer) rather than resuming from a pre-turn handle.

      Returns boolean

    • get ResumptionHandle(): string

      Latest recorded provider resumption handle, or null if none.

      Returns string

    • get RuntimeCallDurationSeconds(): number

      Dynamic state-dependent duration cap in seconds (for example, returning 120 when uncompressed video is active on Gemini Live, and undefined otherwise). Clamped with configuredCallDurationSeconds via ClampSessionSecondsValue so neither a seeded 600s catalog value nor a tighter custom metadata value (e.g., 45s) is shadowed.

      Returns number

    • get SessionMaxSeconds(): number

      Configured credential/session lifetime in seconds, when distinct from CallDurationSeconds.

      Returns number

    • get TrustsNativeResumption(): boolean

      Whether native resumption is trusted on this session (always false under ZeroDataRetention).

      Returns boolean

    Methods

    • Extracts timing and native-resumption overrides from a session configuration bag.

      Parameters

      • config: Record<string, unknown>

      Returns void

    • Arms (or re-arms) the proactive connection-duration timer for the current connection.

      Returns void

    • Cancels all reconnect and duration timers and abandons any in-flight attempt when closed by the consumer. Tool results held for the attempt are dropped: no new connection will carry them.

      Returns void

    • Surfaces an UNEXPECTED socket close as a fatal error (expected closes — the consumer called Close — are silent). The provider hard-closes at token expiry and when it ends the session itself, so this is also how credential / session death reaches the consumer. The close handler fires after the error so consumers driving finalization from either signal converge.

      Parameters

      • Optionalcode: number

        Optional WebSocket close code.

      • Optionalreason: string

        Optional WebSocket close reason.

      • OptionalfromSocket: InworldRealtimeSocket

      Returns void

    • Holds a tool result that arrives while a reconnect is moving the session, and returns true when it did. Sent then, the result would reach the connection being replaced after the attempt's seed was built, so the new connection would have the call and never its result. A driver calls this first in SendToolResult and returns when it is true. Once the move lands the result goes through SendToolResult again, after callsFromBeforeReseed is rebuilt, so a reseeded connection gets it as a late-result note; a failed reconnect or a close drops it with a warning. Outside a reconnect it returns false and changes nothing.

      Parameters

      • callID: string
      • output: string
      • OptionaltaskRevision: number

      Returns boolean

    • Clears the recorded resumption handle so subsequent reconnects fall back to history seeding.

      Returns void

    • Handles a provider-initiated connection-ending advisory (goAway / session.going_away). Reconnects immediately if idle and ready, or waits for the turn/handle boundary up to the scaled deadline.

      Parameters

      • OptionaltimeLeftMs: number

      Returns void

    • Notifies the reconnect controller when pending tool calls drain on SendToolResult. When expectsReply is true (default), a queued soft-window or ConnectionEnding move waits for the model's post-tool turn (or a fresh trusted native handle) rather than reconnecting in the gap between SendToolResult and the first model output frame.

      Parameters

      • OptionalexpectsReply: boolean

      Returns void

    • Marks a turn as ended and triggers a queued soft-window or ConnectionEnding reconnect if ready.

      Parameters

      • OptionalkeepPostToolTurnWait: boolean

      Returns void

    • Marks a turn as open so soft-window reconnects wait for the turn boundary.

      Returns void

    • Optional capability — registers a handler invoked when the underlying provider connection closes WITHOUT the consumer having called IRealtimeSession.Close (provider-side hangup, network drop). Not fired for a consumer-initiated Close() — the caller already knows about that one.

      Optional because not every provider surface exposes a close signal cheaply; callers must feature-detect (if (session.OnClose) { ... }). An unexpected close is typically ALSO surfaced as a Fatal IRealtimeSession.OnError, which is the signal consumers should drive finalization from.

      Parameters

      • handler: () => void

        Invoked when the provider connection closes unexpectedly.

      Returns void

    • Registers a handler for session errors.

      Fatality semantics mirror the client-side BaseRealtimeClient contract:

      • Fatal: true — the session is unusable (transport/socket failure, credential/token expiry, unexpected connection loss). The consumer should finalize the session (e.g. RealtimeSessionRunner calls Stop()) instead of idling forever on a dead socket.
      • Fatal: false — a provider-reported, recoverable error frame; the session stays open and the consumer should log and continue.

      Parameters

      Returns void

    • Registers a handler for provider-detected interruptions (barge-in).

      True barge-in only: the handler fires ONLY when user speech interrupts ACTIVE model output — NOT on every user utterance. A user simply taking their normal turn while the model is idle is not an interruption, and drivers must not report it as one (e.g. a raw "speech started" frame must be gated on whether a model response is actually in flight).

      Turn detection / VAD is owned by the provider. The agent layer uses this hook to cancel the model's current turn and to fire the cancellationToken of any in-flight delegated agent run — a stale delegated result must never be narrated into a conversation that has moved on.

      Parameters

      • handler: () => void

        Invoked when the provider reports a true barge-in interruption.

      Returns void

    • Hook invoked when a reconnect attempt succeeds.

      Parameters

      • _usedNativeResumption: boolean

      Returns void

    • Records a provider resumption handle or conversation ID.

      Parameters

      • handle: string
      • Optionalresumable: boolean

      Returns void

    • Parameters

      • instructions: string

        Instructions for the single spoken update.

      Returns void

      ONE short spoken update via a response-create frame carrying per-response instructions. Collision behavior: queue. A response-create sent mid-response would collide with the in-flight generation (the provider rejects overlapping triggers), so the send is deferred until the active response completes and drained at the next boundary.

    • Parameters

      Returns void

      via the mutable system prompt: Inworld has no purpose-built non-interrupting context channel, but session.update may rewrite instructions mid-session WITHOUT triggering generation. The note is appended under a "Background updates" heading and the full prompt is re-sent — a config write, so it never interrupts and is sent immediately even mid-response. The model sees the notes the next time it speaks.

    • Sends the initial session.update frame carrying the full server-authored session config (model, instructions, audio/STT/TTS, tools, semantic-VAD turn-taking). Always the FIRST client frame — the provider drops audio sent before the session is configured.

      Parameters

      Returns void

    • Parameters

      • callID: string

        The CallID from the originating RealtimeToolCall.

      • output: string

        The tool's result as a JSON-stringified string.

      Returns Promise<void>

      the tool-call loop: sends a tool-result frame correlated by call_id. Sent IMMEDIATELY (never queued behind a response) — the provider asked for it and owns the spoken continuation. The one wait is a reconnect: the result is held and sent on the new socket (holdToolResultDuringReconnect). The busy flag is set eagerly so a queued narration can't slip in before the spoken result (driver obligation #5 — the result must EVENTUALLY be voiced and never be dropped).

    • Resolves once the provider's session-ready confirmation arrives (its acknowledgment that the session config is applied); rejects if the transport dies first. Awaited by InworldRealtime.StartSession so the session is never handed to a consumer before it is actually configured (driver obligation #7).

      Returns Promise<void>

      A promise resolving on session-ready and rejecting on pre-ready transport death.