RealtimeInstance
Defined in: packages/realtime/src/lib/realtime-session/realtime-session.types.ts:51
The minimal bridge RealtimeSession needs from a Maelstrom instance.
Orchestrator maps onto this via a small wrapper (submitIntent ->
processIntent, waitForIdle and waitForIdleResult ->
commandProcessor.waitForIdle) — this interface exists so the realtime
package depends on a narrow seam rather than the whole Orchestrator
surface. getStructuralSnapshot backs the
get_ui_state pull (what’s on screen); getCapabilitySnapshot backs the
get_capabilities pull (what CAN be shown).
submitIntent resolves with a SubmitIntentResult carrying the
engine’s conversational userMessage, so the session can speak the engine’s
own reply instead of a structural summary once the change settles. It still
rejects with RequestInFlightError while a prior intent is applying — that
contract drives the barge-in queue and is unchanged.
Properties
Section titled “Properties”applicationWork?
Section titled “applicationWork?”
readonlyoptionalapplicationWork?:VoiceApplicationWorkSource
Defined in: packages/realtime/src/lib/realtime-session/realtime-session.types.ts:53
Optional application-wide current work observations, including non-voice input.
Methods
Section titled “Methods”addAssistantMessageAcknowledged()
Section titled “addAssistantMessageAcknowledged()”addAssistantMessageAcknowledged(
args):Promise<AssistantMessageOutcome>
Defined in: packages/realtime/src/lib/realtime-session/realtime-session.types.ts:84
Persist an assistant message with the engine’s existing MessageId dedup.
'inserted' is positive evidence this runtime owns first insertion;
'deduped' means an earlier attempt already landed.
Parameters
Section titled “Parameters”MessageId
message
Section titled “message”string
Returns
Section titled “Returns”Promise<AssistantMessageOutcome>
getCapabilitySnapshot()
Section titled “getCapabilitySnapshot()”getCapabilitySnapshot():
CapabilitySnapshot
Defined in: packages/realtime/src/lib/realtime-session/realtime-session.types.ts:77
Returns
Section titled “Returns”CapabilitySnapshot
getStructuralSnapshot()
Section titled “getStructuralSnapshot()”getStructuralSnapshot():
UIStructuralSnapshot
Defined in: packages/realtime/src/lib/realtime-session/realtime-session.types.ts:76
Returns
Section titled “Returns”UIStructuralSnapshot
observeEngineConnection()
Section titled “observeEngineConnection()”observeEngineConnection(
cb):Unsubscribe
Defined in: packages/realtime/src/lib/realtime-session/realtime-session.types.ts:94
Observe engine connection readiness. Subscribe first, then the current
status is delivered synchronously (subscribe-then-snapshot), so an
already-connected engine resolves immediately and a not-connected engine
delivers false now and true on the next transition.
Parameters
Section titled “Parameters”(connected) => void
Returns
Section titled “Returns”Unsubscribe
onSettled()
Section titled “onSettled()”onSettled(
cb):Unsubscribe
Defined in: packages/realtime/src/lib/realtime-session/realtime-session.types.ts:78
Parameters
Section titled “Parameters”() => void
Returns
Section titled “Returns”Unsubscribe
submitIntent()
Section titled “submitIntent()”submitIntent(
intent):Promise<SubmitIntentResult>
Defined in: packages/realtime/src/lib/realtime-session/realtime-session.types.ts:54
Parameters
Section titled “Parameters”intent
Section titled “intent”string
Returns
Section titled “Returns”Promise<SubmitIntentResult>
waitForIdle()
Section titled “waitForIdle()”waitForIdle():
Promise<void>
Defined in: packages/realtime/src/lib/realtime-session/realtime-session.types.ts:55
Returns
Section titled “Returns”Promise<void>
waitForIdleResult()?
Section titled “waitForIdleResult()?”
optionalwaitForIdleResult():Promise<Result<void,Error>>
Defined in: packages/realtime/src/lib/realtime-session/realtime-session.types.ts:75
Result-bearing settle wait, preferred over RealtimeInstance.waitForIdle wherever the session needs to know whether the settled work succeeded.
It is optional so that an instance written against the void-only
RealtimeInstance.waitForIdle still satisfies this interface; a
session that finds it absent falls back to that wait and can only treat
every settle as successful. An Orchestrator-backed instance supplies it
directly, because commandProcessor.waitForIdle() already resolves with
this Result.
A !ok result means the settled work failed — a refused set_layout
(duplicate tiling leaf, malformed weight token) being the ordinary case.
Such a refusal neither throws nor rejects and leaves the previous screen
in place, so this is the only signal that the intent changed nothing, and
RealtimeSession answers the update_ui tool call as a failure rather
than describing a snapshot the intent never produced. A rejection leaves
the application outcome unconfirmed and must not trigger automatic replay.
Returns
Section titled “Returns”Promise<Result<void, Error>>