Class: OracleSession
Defined in: packages/aiui-oracle/src/session.ts:86
Constructors
Constructor
new OracleSession(
options):OracleSession
Defined in: packages/aiui-oracle/src/session.ts:153
Parameters
options
Returns
OracleSession
Properties
transport
readonlytransport:OracleTransport
Defined in: packages/aiui-oracle/src/session.ts:87
Methods
applyAudioConstraints()
applyAudioConstraints(
constraints):Promise<void>
Defined in: packages/aiui-oracle/src/session.ts:494
Apply constraints to the LIVE mic track. Resolves if the browser took them; rejects otherwise — and audioSettings is what says which, since a browser may resolve and still not have changed anything.
Parameters
constraints
MediaTrackConstraints
Returns
Promise<void>
audioSettings()
audioSettings():
Record<string,unknown> |undefined
Defined in: packages/aiui-oracle/src/session.ts:504
The mic track's EFFECTIVE settings right now — the readback half.
Returns
Record<string, unknown> | undefined
behavior()
behavior():
object
Defined in: packages/aiui-oracle/src/session.ts:842
The aiui-side knobs — ours, not the vendor's, and applied immediately rather than sent anywhere (there is nothing on the wire to send).
Returns
object
parkAfterIdleSeconds
parkAfterIdleSeconds:
number
close()
close():
void
Defined in: packages/aiui-oracle/src/session.ts:334
Returns
void
effectiveSession()
effectiveSession():
Record<string,unknown> |undefined
Defined in: packages/aiui-oracle/src/session.ts:485
What the server said it holds, from the last session.updated. Undefined until the first ack — which is itself worth showing.
Returns
Record<string, unknown> | undefined
ledger()
ledger(): readonly
LedgerEntry[]
Defined in: packages/aiui-oracle/src/session.ts:172
Returns
readonly LedgerEntry[]
micStream()
micStream():
MediaStream|undefined
Defined in: packages/aiui-oracle/src/session.ts:347
Returns
MediaStream | undefined
onLedger()
onLedger(
listener): () =>void
Defined in: packages/aiui-oracle/src/session.ts:176
Parameters
listener
(entry) => void
Returns
() => void
onState()
onState(
listener): () =>void
Defined in: packages/aiui-oracle/src/session.ts:181
Parameters
listener
(state) => void
Returns
() => void
park()
park(
reason?):void
Defined in: packages/aiui-oracle/src/session.ts:292
Gate the mic, keep the connection: the free park.
Parameters
reason?
"idle" | "manual"
Returns
void
refreshPrompt()
refreshPrompt():
Promise<void>
Defined in: packages/aiui-oracle/src/session.ts:394
Recompose the prompt from the configured recipe and send it if it moved.
The whole reason a resolver can read PromptContext.turns or the app's own storage: call this when the thing the prompt describes has changed — a navigation, a selection, the user finishing the tour.
IDENTICAL TEXT SENDS NOTHING. Instructions are the largest thing on the session and are re-billed as input tokens on every subsequent turn, so a refresh that changed nothing must cost nothing; it also keeps the config ledger free of acks that say only "still the same". That guard is what makes an each-turn recompose, or a refresh wired to a noisy signal, affordable rather than reckless.
Resolver failures are recorded and swallowed — a refresh is an improvement on a session that is already running, and losing the improvement is better than losing the session. (A failure at START is fatal, deliberately: there is no good prompt to fall back to there.)
Returns
Promise<void>
resume()
resume():
void
Defined in: packages/aiui-oracle/src/session.ts:308
Returns
void
sendImage()
sendImage(
image,caption?,options?):void
Defined in: packages/aiui-oracle/src/session.ts:548
image is a data URL or fully-qualified URL (the vendor's contract).
respond defaults to true — pasting an image into a lab bench is a question. Pass false when the image is CONTEXT the human is about to talk about: the intent panel's oracle does, because a shot taken mid-sentence must not make the model start answering over them (owner, 2026-07-30 — the same rule sendText already carries).
Parameters
image
string
caption?
string
options?
respond?
boolean
Returns
void
sendText()
sendText(
text,options?):void
Defined in: packages/aiui-oracle/src/session.ts:520
Parameters
text
string
options?
respond?
boolean
role?
"user" | "system"
Returns
void
sessionConfig()
sessionConfig():
Record<string,unknown>
Defined in: packages/aiui-oracle/src/session.ts:479
What we INTEND the server to hold, as the vendor's session shape — INCLUDING the frozen fields (model, voice), which a params widget must still be able to display even though no update may carry them. Paired with effectiveSession this is the whole sent-vs-in-force story.
Returns
Record<string, unknown>
setBehavior()
setBehavior(
path,value):void
Defined in: packages/aiui-oracle/src/session.ts:846
Parameters
path
string
value
unknown
Returns
void
setInstructions()
setInstructions(
instructions):void
Defined in: packages/aiui-oracle/src/session.ts:370
State the prompt outright — the imperative escape hatch, unchanged.
This REPLACES the configured recipe, so a session driven this way stops recomposing: an app that has taken manual control of the text keeps it until it hands control back. Use refreshPrompt instead when the resolver should stay in charge.
Parameters
instructions
string
Returns
void
setSessionParam()
setSessionParam(
path,value):void
Defined in: packages/aiui-oracle/src/session.ts:460
Set one session parameter by its VENDOR path — "audio.input .turn_detection.silence_duration_ms", "audio.output.speed" — and re-send. undefined deletes the key (back to the vendor's default); null is a value in its own right (turn_detection: null is manual).
What goes on the wire is the whole updatable session, not the field that changed. turn_detection travels as a complete object with no documented field-level patch, so whether the vendor merges INSIDE it is unverified — and if it replaces, a lone { silence_duration_ms } would silently drop type and threshold back to defaults, undoing tuning while appearing to work. A whole-session send is correct under either semantics, and it means the config entry's drift covers everything rather than the one block someone remembered to include.
Switching turn_detection.type drops the outgoing algorithm's knobs, because they do not exist on the other side: threshold is meaningless to semantic_vad and eagerness to server_vad.
Parameters
path
string
value
unknown
Returns
void
setTools()
setTools(
tools):void
Defined in: packages/aiui-oracle/src/session.ts:355
Replace the tool surface mid-session (wholesale — the vendor semantics). Reconciled against the session.updated ack; drift lands in the ledger.
Parameters
tools
Returns
void
start()
start():
Promise<void>
Defined in: packages/aiui-oracle/src/session.ts:188
Returns
Promise<void>
state()
state():
OracleState
Defined in: packages/aiui-oracle/src/session.ts:168
Returns
stopSpeaking()
stopSpeaking():
void
Defined in: packages/aiui-oracle/src/session.ts:321
Manual barge-in — safe to fire with no reply in flight.
Returns
void