@nuancelabs/js-sdk 0.15.0 → 0.34.0

package/index.d.ts

@@ -7,89 +7,10 @@ export declare class ActiveSessionError extends Error {
     constructor();
 }
 
-/**
- * The turn's first audio. `atMs` is when it plays, which can be after the
- * event arrives.
- */
-export declare interface AgentSpeechStartedEvent extends SessionEventBase {
-    type: "agent.speech.started";
-    /** The turn, as {@link AgentTurnStartedEvent.turnId} names it. */
-    turnId: string;
-}
-
-/**
- * The agent's words, in whole words, as they are committed to the
- * conversation. They arrive ahead of their audio: `atMs` is when the first
- * of them plays. When the agent's turn is interrupted, words whose `atMs` is
- * later than the {@link AgentTurnEndedEvent}'s were never heard.
- */
-export declare interface AgentTextEvent extends SessionEventBase {
-    type: "agent.text";
-    /**
-     * The turn the words belong to, as {@link AgentTurnStartedEvent.turnId}
-     * names it; null for words outside any turn.
-     */
-    turnId: string | null;
-    /** The words, with the spacing to join them to the turn's other words. */
-    text: string;
-}
-
-/**
- * The agent's turn is over. `atMs` is when the turn's audio ends: for an
- * interrupted turn, where the agent was cut off.
- */
-export declare interface AgentTurnEndedEvent extends SessionEventBase {
-    type: "agent.turn.ended";
-    /** The turn, as {@link AgentTurnStartedEvent.turnId} names it. */
-    turnId: string;
-    /**
-     * `"completed"`: the agent said all of it. `"interrupted"`: the user cut
-     * in. `"stopped"`: a command stopped the agent. `"abandoned"`: the turn
-     * gave up, as when nothing of it was heard for a while or it had nothing
-     * to say; `spoken` is then the runtime's estimate of what played. A newer
-     * runtime may send other values.
-     */
-    reason: "completed" | "interrupted" | "stopped" | "abandoned" | (string & {});
-    /**
-     * Every word the turn committed, as its {@link AgentTextEvent}s carried
-     * them. After an interruption it includes words that were cut before they
-     * played; their `agent.text` events have an `atMs` later than this
-     * event's.
-     */
-    spoken: string;
-}
-
-/**
- * The agent took the floor, before its first audio. Its words follow as
- * {@link AgentTextEvent}s and the turn closes with an
- * {@link AgentTurnEndedEvent}, both with the same `turnId`. `atMs` is where
- * on the timeline the agent took it.
- */
-export declare interface AgentTurnStartedEvent extends SessionEventBase {
-    type: "agent.turn.started";
-    /** The turn's id, unique within the session. */
-    turnId: string;
-    /**
-     * What opened the turn. `"user_done"`: the agent judged the user had
-     * finished. `"silence"`: the user went quiet long enough. `"check_in"`:
-     * both were quiet and the agent spoke first, as in its opening greeting.
-     * `"command"`: a command asked for the turn. `"tool"`: a tool's result
-     * reached the agent while both were quiet. A newer runtime may send other
-     * values.
-     */
-    openedBy: "user_done" | "silence" | "check_in" | "command" | "tool" | (string & {});
-    /**
-     * `"reply"`: the agent wrote the turn's words itself. `"say"`: the agent
-     * says a line it was given, word for word. A newer runtime may send other
-     * values.
-     */
-    source: "reply" | "say" | (string & {});
-}
-
 /**
  * An error answer from the Nuance API that the SDK has no more specific error
- * for, such as a `401` for an expired or used session token, a `429` when this
- * month's conversation time is used, or a `503` once the SDK has stopped
+ * for, such as a `401` for an expired or used session token, a `429` when today's
+ * credits are spent, or a `503` once the SDK has stopped
  * retrying a busy service. See the Errors guide for each status and `code`.
  *
  * Act on `status` and `code`, never on `message`: the message is the server's
@@ -113,6 +34,11 @@ export declare class ApiError extends Error {
     readonly code: string | null;
     /** How long to wait before trying again, when the server said. */
     readonly retryAfterSeconds: number | null;
+    /**
+     * When the allowance the refusal is about renews (UTC, ISO 8601), when the
+     * server said, such as today's credits for a `429`.
+     */
+    readonly renewsAt: string | null;
     /** The parsed JSON body of the answer, or `null` when it had none. */
     readonly body: unknown;
     constructor(status: number, detail: string, body?: unknown);
@@ -161,15 +87,6 @@ export declare interface AvatarParticipant {
 /** The direction a camera faces relative to the user. */
 export declare type CameraFacing = "user" | "environment";
 
-/**
- * The runtime's answer to a command: `"applied"`, or `"rejected"` with the
- * runtime's reason in `error`.
- */
-export declare interface CommandResult {
-    status: "applied" | "rejected";
-    error: string | null;
-}
-
 
 /**
  * A live avatar conversation controlled by the SDK.
@@ -182,7 +99,9 @@ export declare interface Conversation {
      * Starts the conversation.
      *
      * This creates or joins the underlying session and requests local camera and
-     * microphone access when required.
+     * microphone access when required. A session the server ends while it
+     * joins is left at once: `connect()` then resolves after `session-ended`,
+     * with the state `"disconnected"`.
      */
     connect(): Promise<void>;
     /**
@@ -212,18 +131,11 @@ export declare interface Conversation {
      */
     readonly avatar: AvatarParticipant;
     /**
-     * Switches the avatar's background to one the runtime serves, by id
-     * (`"original"` is the avatar's own backdrop). The runtime composites the
-     * video, so nothing changes on the client's side of it.
-     *
-     * Resolves with the runtime's answer: a runtime without a background
-     * library, or one that does not serve the id, rejects it.
-     *
-     * @throws If the id is not a background id, the conversation is not
-     * connected, the runtime takes no session commands, or it does not answer
-     * in time.
+     * The interface the session runs on, whose events
+     * {@link Conversation.onInterfaceEvent} and
+     * {@link Conversation.sendInterfaceEvent} carry: `"nuance_live"`.
      */
-    setBackground(background: string): Promise<CommandResult>;
+    readonly interface: string;
     /**
      * Subscribes to conversation lifecycle and media events.
      *
@@ -231,55 +143,36 @@ export declare interface Conversation {
      */
     onChange(handler: (event: ConversationEvent) => void): () => void;
     /**
-     * Subscribes to one type of the session's events: what the user and the
-     * agent say, their turns, and who has the floor.
-     *
-     * Each event arrives once, in the session's order (its `seq`). Events the
-     * connection missed while it was down are asked of the runtime again and
-     * delivered in their place. Subscribe before `connect()` to see the
-     * session's first events.
-     *
-     * @example
-     * ```ts
-     * const stop = conversation.on("agent.text", (event) => {
-     *   transcript.textContent += event.text;
-     * });
-     * ```
-     *
-     * @returns A function that removes the handler.
-     */
-    on<K extends keyof SessionEventMap>(type: K, handler: (event: SessionEventMap[K]) => void): () => void;
-    /**
-     * Subscribes to the agent's calls of the conversation's tools, named when
-     * your server mints the session token. Run the tool in your page and answer each call with
-     * {@link Conversation.sendToolResult}. The agent keeps talking while a call
-     * is open, and uses the result when it arrives.
+     * Subscribes to the session's Nuance Live events: each JSON object the
+     * runtime sends on the interface's topic, parsed, in the order it was sent.
+     * What the user and the agent say, her turns, her tool calls through a
+     * delegation and the session's end all arrive here. An event too large for one packet arrives as `message.part`
+     * packets; the handler gets the event they carry, in its place, and never
+     * the parts. Subscribe before `connect()` to see the session's first
+     * events; a handler stays subscribed when the conversation connects again.
+     * Events sent while the connection was down are not delivered again.
      *
      * @example
      * ```ts
-     * conversation.onToolCall(async (call) => {
-     *   if (call.name === "show_confetti") {
-     *     launchConfetti();
-     *     await conversation.sendToolResult(call.callId, "Confetti is falling.");
+     * conversation.onInterfaceEvent((event) => {
+     *   if (event.type === "session.output_transcript.delta") {
+     *     transcript.textContent += String(event.delta);
      *   }
      * });
      * ```
      *
      * @returns A function that removes the handler.
      */
-    onToolCall(handler: (call: ToolCall) => void): () => void;
+    onInterfaceEvent(handler: (event: Record<string, unknown>) => void): () => void;
     /**
-     * Answers a tool call: what it produced, or with `isError` what went wrong.
-     * The agent keeps the first 2,000 characters of an output, so return what
-     * it needs, not everything you have.
+     * Sends one Nuance Live event, such as `response.create` or
+     * `conversation.item.create`, as JSON on the interface's topic: one reliable packet, or, for an event over 64,000 bytes as JSON
+     * (UTF-8), one text stream. A `response.create` sent after a streamed event
+     * waits for the runtime to read it.
      *
-     * @param callId - The call's {@link ToolCall.callId}.
-     * @returns Whether the runtime took the result: `status` is `"rejected"`,
-     * with the reason in `error`, for an unknown or closed call.
-     * @throws If the conversation is not connected, or the runtime does not
-     * answer in time.
+     * @throws If the conversation is not connected.
      */
-    sendToolResult(callId: string, output: ToolOutput, options?: ToolResultOptions): Promise<CommandResult>;
+    sendInterfaceEvent(event: Record<string, unknown>): Promise<void>;
 }
 
 
@@ -301,6 +194,15 @@ export declare type ConversationEvent =
     type: "session-created";
     id: string;
 }
+/**
+* A runtime is held for an API conversation and is getting ready for it,
+* which can take up to about half a minute; the conversation then connects.
+* Fires once, while `connecting`. An API conversation never queues, so this
+* is all it is told before it connects.
+*/
+| {
+    type: "avatar-preparing";
+}
 /** The avatar participant joined the conversation. */
 | {
     type: "avatar-connected";
@@ -392,15 +294,40 @@ export declare type ConversationEvent =
 * A runtime that stops at its limit does not necessarily leave the transport,
 * so a caller cannot infer this from the connection alone. `reason` is
 * `"time-limit"` when the session was capped and ran out its clock,
-* `"policy-violation"` when the runtime ended it for content, `"refused"`
+* `"policy-violation"` when a safety check ended it for a policy
+* violation, `"age-check"` when it ended because the camera showed only
+* people who look under 18 (each with `message`, the same words for every
+* end of its kind, for you to show the person), `"refused"`
 * when the runtime would not start it, with its reason in `message` when it
-* gave one. Call {@link Conversation.disconnect} then: after the runtime's
-* own end the call stays connected, with the camera and microphone on.
+* gave one, or when the server refused to create it.
+*
+* On any end the server makes (its goodbye, the time limit, a policy end,
+* an age check), the SDK then leaves the call and stops the camera and
+* microphone: the state becomes `"disconnected"`, and `user` and `avatar`
+* throw from then on. An end that arrives while the conversation joins
+* stops the join and releases any camera or microphone it opened, so
+* `connect()` can resolve with the state already `"disconnected"`. With
+* {@link CreateNuanceConversationOptions.stayConnectedOnEnd} it stays in
+* the call until you call {@link Conversation.disconnect}.
+*
+* `endReason` is the runtime's own word for the end ({@link EndReason}),
+* and says who ended the session where `reason` cannot: an agent that hung
+* up reads `"end_call"`, a runtime that failed the session `"error"`. It is
+* absent only when the end reached the SDK without one. `reason` keeps the
+* values it has always had, so code reading it needs no change.
 */
 | {
     type: "session-ended";
     reason: SessionEndReason;
+    endReason?: EndReason;
     message?: string;
+    /**
+     * Why the server refused to create the conversation, when it did: the
+     * error `connect()` rejects with, such as an `ApiError` with the
+     * answer's `status`, `code` and `renewsAt`. It comes before the state
+     * becomes `"disconnected"`.
+     */
+    error?: Error;
 } | {
     type: "queue-changed";
     position: number;
@@ -440,6 +367,8 @@ export declare type ConversationStateValue = `${ConversationState}`;
  * The returned conversation is idle until {@link Conversation.connect} is
  * called. The SDK creates the backend conversation session, waits until it is
  * ready, and connects using the connection details returned by the Nuance API.
+ * An option it does not know is ignored, with a warning in the console that
+ * names it.
  *
  * @example
  * ```ts
@@ -524,61 +453,39 @@ export declare interface CreateNuanceConversationOptions {
     /** Local capture preferences, resolved once for each connection attempt. */
     mediaDevices?: MediaDevicePreferences | (() => MediaDevicePreferences);
     /**
-     * When the avatar starts speaking.
+     * When `avatar-presented` fires. She speaks first once your page sends
+     * `response.create`, so send it on `avatar-presented`.
      *
      * - `"first-frame"`: as soon as her first frame reaches the page.
      *   `avatar-presented` follows `avatar-ready` at once. Her video may be
      *   soft for its first few seconds while the connection ramps up.
      * - `"full-quality"`: once her video has reached its full size and held
-     *   it, or after at most about 12 seconds. She is in view but silent in
-     *   between, so a page using this should cover her until
-     *   `avatar-presented`.
+     *   it, or after at most about 12 seconds. She is in view in between, so a
+     *   page using this should cover her until `avatar-presented`.
      *
      * @defaultValue `"first-frame"`
      */
     startOn?: StartOn;
-}
-
-
-/**
- * Who has the floor changed. `atMs` is when the change plays.
- */
-export declare interface FloorEvent extends SessionEventBase {
-    type: "floor";
     /**
-     * `"speaking"`: the agent has the floor. `"listening"`: the user has it
-     * and the agent listens. `"waiting"`: nobody has it; the agent waits for
-     * the user. A newer runtime may send other values.
+     * Stays in the call after the conversation ends on the server's side (its
+     * goodbye, the time limit, a policy end, an age check), with the camera
+     * and microphone on, until you call `disconnect()`. Left out, the SDK
+     * leaves the call and stops the camera and microphone right after it
+     * reports `session-ended`. `useNuanceConversation` leaves on every end
+     * whatever this says.
+     *
+     * @defaultValue `false`
      */
-    state: "waiting" | "listening" | "speaking" | (string & {});
+    stayConnectedOnEnd?: boolean;
 }
 
+
 /**
- * A tool the agent may call, which your page runs: show something on the
- * screen, read what the user has open, look something up in your app. The
- * agent decides when to call it from its `description`, and fills its
- * arguments to match its `parameters`. A conversation has up to 16 tools.
+ * A {@link KnownEndReason}, or any other string the runtime sends. A reason
+ * the SDK does not know is passed through as it arrived rather than dropped
+ * or flattened, so a value a newer runtime adds still reaches the app.
  */
-export declare interface FunctionTool {
-    /** Always `"function"`, the default. */
-    type?: "function";
-    /**
-     * The tool's name: letters, digits, `_` and `-`, up to 64 characters,
-     * unique in the conversation. `ask_user`, `get_current_time`, `web_search`
-     * and the agent's other own tools' names are taken.
-     */
-    name: string;
-    /**
-     * What the tool does and when to use it, written for the agent, up to
-     * 2,000 characters. Say when to call it, not only what it does.
-     */
-    description: string;
-    /**
-     * The arguments, as a JSON Schema whose `type` is `"object"`, up to 16,000
-     * characters as compact JSON. `{ type: "object", properties: {} }` takes none.
-     */
-    parameters: Record<string, unknown>;
-}
+export declare type EndReason = KnownEndReason | (string & {});
 
 /**
  * Raised by {@link Conversation.connect} when the server refuses a guest's new
@@ -592,6 +499,29 @@ export declare class GuestLimitError extends Error {
     constructor(reason: string, message: string);
 }
 
+/**
+ * Why a session ended, in the runtime's own words.
+ *
+ * The end reason is decided in one place: the `reason` the runtime puts on
+ * `session.closed`, which {@link endReasonOf} reads. A v1 session has an older
+ * vocabulary of its own, which {@link v1EndReason} maps onto the same words,
+ * so a room session and a socket session answer alike for the same end.
+ */
+/**
+ * The reasons the runtime names. A session ends for exactly one of these.
+ *
+ * - `close_requested`: a client closed the session — `session.close` (this
+ *   page's, or another client's, such as your server's attach connection),
+ *   v1's session end, or its input stream ending.
+ * - `content`: a safety check ended it for a policy violation.
+ * - `age_check`: the age check ended it: the camera showed only people who
+ *   look under 18.
+ * - `expired`: it ran out its time cap or its idle limit.
+ * - `end_call`: the agent hung up.
+ * - `error`: the runtime failed the session, a worker drain included.
+ * - `connection_lost`: the client's transport went away without closing.
+ */
+export declare type KnownEndReason = "close_requested" | "content" | "age_check" | "expired" | "end_call" | "error" | "connection_lost";
 
 /**
  * Raised by {@link Conversation.connect} when the server refuses a new session
@@ -651,6 +581,107 @@ export declare type MediaErrorReason = "permission-denied" | "device-not-found"
  */
 export declare type NetworkQuality = "good" | "poor" | "lost";
 
+/**
+ * Who does the work the avatar hands off: `client`, your page, which reports
+ * back with appends naming the delegation; `responses`, a backend that calls
+ * your tools, which your page runs; or `none`, when nothing on your side would
+ * answer a hand-off: she hands nothing off and answers with her own tools.
+ */
+export declare type NuanceLiveDelegation = {
+    type: "client";
+    acknowledgement_delay_ms?: number;
+} | {
+    type: "none";
+} | {
+    type: "responses";
+    /** Accepted and recorded, 0 to 800; changes nothing. */
+    acknowledgement_delay_ms?: number;
+    responses: NuanceLiveResponses;
+};
+
+/** The backend's settings in a `responses` delegation. */
+export declare type NuanceLiveResponses = {
+    /** Required: any non-empty name up to 256 characters. It is recorded; the backend runs Nuance's own model. */
+    model: string;
+    /** The backend's instructions, up to 65,536 characters, which only the backend sees. */
+    instructions?: string;
+    /** Your function tools; a session runs at most 16. */
+    tools?: NuanceLiveTool[];
+    /** `auto` (the default), `none`, `required`, or one tool by name. */
+    tool_choice?: "auto" | "none" | "required" | {
+        type: "function";
+        name: string;
+    };
+    /** `true` (the default) lets a step make several calls; `false`, one per step. */
+    parallel_tool_calls?: boolean;
+    /** The most a step writes, from 16. Reasoning tokens count toward it. */
+    max_output_tokens?: number;
+    /** How much the backend thinks before each step; `low` is the default. */
+    reasoning?: {
+        effort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
+        /** Accepted and echoed; changes nothing. */
+        summary?: "concise" | "detailed" | "auto";
+    };
+    /** Accepted and echoed; changes nothing. */
+    service_tier?: "auto" | "default" | "flex" | "priority" | "fast_tier_temp_pilot" | "ultrafast";
+    /** Accepted and echoed; changes nothing. */
+    text?: {
+        verbosity?: "low" | "medium" | "high";
+    };
+};
+
+/** Nuance Live's settings in a session token (`interface_setup`). */
+export declare type NuanceLiveSetup = {
+    /** Who does the work she hands off: your page (the default), a backend, or nobody. */
+    delegation?: NuanceLiveDelegation;
+    /**
+     * The avatar's own tools, each on (`true`) or off (`false`). Left out, a tool
+     * keeps its default: `stay_quiet` and `switch_identity` on, `end_call` and
+     * `call_time` off. A tool runs only where the deployment offers it.
+     */
+    runtime_tools?: {
+        stay_quiet?: boolean;
+        end_call?: boolean;
+        call_time?: boolean;
+        switch_identity?: boolean;
+    };
+    /** `{ input: { camera: false } }` keeps her from using the user's camera. */
+    video?: {
+        input?: {
+            camera?: boolean;
+        };
+    };
+};
+
+/**
+ * One of your tools in a `responses` delegation: the backend calls it, and
+ * your page runs it and sends back the result.
+ */
+export declare type NuanceLiveTool = {
+    type: "function";
+    /** Letters, digits, `_` and `-`, up to 64 characters, unique in the list. */
+    name: string;
+    /** When to use it, up to 2,000 characters. */
+    description?: string;
+    /**
+     * A JSON Schema whose `type` is `"object"`, up to 16,000 characters as
+     * compact JSON. Left out, the tool takes no arguments.
+     */
+    parameters?: Record<string, unknown>;
+    strict?: boolean;
+    /**
+     * `confirm`: she reads the call back and sends it only after the user's
+     * clear yes. `safety_resource`: a tool that gives a crisis or safety
+     * resource, whose numbers she must say in full.
+     */
+    policy?: {
+        confirm?: boolean;
+        safety_resource?: boolean;
+    };
+    /** MCP's tool hints; see {@link ToolAnnotations}. */
+    annotations?: ToolAnnotations;
+};
+
 /**
  * Who the avatar is in a conversation created with
  * {@link CreateNuanceConversationOptions.personality}.
@@ -662,62 +693,23 @@ export declare interface PersonalityChoice extends SessionPersonality {
  * Raised by {@link Conversation.connect} when the server refuses a new session
  * because the runtime recently ended too many of this account's sessions for
  * content-policy violations. `retryAfterSeconds` is the server's estimate of
- * when a new session may be started, when it sent one.
+ * when a new session may be started, when it sent one. `message` says so in
+ * words to show the person, with the wait when it is known.
  */
 export declare class PolicyCurfewError extends Error {
     readonly retryAfterSeconds: number | null;
     constructor(retryAfterSeconds: number | null);
 }
 
-
 /**
  * Why a session is over. `"time-limit"`: the capped session ran out its clock.
  * `"policy-violation"`: the runtime ended it for content that breaks the usage
- * policy. `"refused"`: the runtime would not start it, for the reason in the
- * event's `message`. `"ended"`: any other server-side end.
- */
-export declare type SessionEndReason = "time-limit" | "ended" | "policy-violation" | "refused" | "connection-lost";
-
-/** Any one of the session's events. */
-export declare type SessionEvent = SessionEventMap[keyof SessionEventMap];
-
-/**
- * What every session event carries: its place in the session's order and on
- * the session's timeline.
+ * policy. `"age-check"`: the runtime ended it because the camera showed only
+ * people who look under 18. `"refused"`: it never started: the runtime would not start it, for
+ * the reason in the event's `message`, or the server refused to create it,
+ * for the reason in its `error`. `"ended"`: any other server-side end.
  */
-export declare interface SessionEventBase {
-    /**
-     * The event's number in the session's sequence: from 1, one more for each
-     * event the runtime sends, of every kind, so the events one handler sees
-     * skip numbers. The SDK delivers events in this order, each once. 0 for an
-     * event the runtime did not number.
-     */
-    seq: number;
-    /**
-     * Where the event falls on the session's timeline, in milliseconds. The
-     * timeline counts the user's audio from the start of the session. A user
-     * event is stamped on the user's audio, as where the user said it; an
-     * agent event where the agent's audio for it plays, which can be ahead of
-     * when the event arrives. Every event of a session is on this one timeline, so
-     * their `atMs` compare. Null when the runtime gives no time.
-     */
-    atMs: number | null;
-}
-
-/**
- * The session's events by their `type`, for {@link Conversation.on}.
- */
-export declare interface SessionEventMap {
-    "user.transcript": UserTranscriptEvent;
-    "user.speech.started": UserSpeechStartedEvent;
-    "user.speech.ended": UserSpeechEndedEvent;
-    "user.turn.ended": UserTurnEndedEvent;
-    "agent.turn.started": AgentTurnStartedEvent;
-    "agent.speech.started": AgentSpeechStartedEvent;
-    "agent.text": AgentTextEvent;
-    "agent.turn.ended": AgentTurnEndedEvent;
-    floor: FloorEvent;
-}
+export declare type SessionEndReason = "time-limit" | "ended" | "policy-violation" | "age-check" | "refused" | "connection-lost";
 
 
 
@@ -730,11 +722,12 @@ export declare interface SessionPersonality {
      */
     system_prompt?: string;
     /**
-     * The face the avatar is drawn as, by the id Nuance gave your organization.
-     * Leave it out for the default face. A face your organization has not been
-     * given is refused when the token is minted.
+     * The persona the avatar is drawn as, by the id Nuance gave your
+     * organization: who it looks like. Leave it out for the default. An id you
+     * can't use, including `"emma"`, the Nuance app's own character, is refused
+     * when the token is minted.
      */
-    face_id?: string;
+    persona_id?: string;
 }
 
 /**
@@ -745,23 +738,6 @@ export declare interface SessionPersonality {
 export declare interface SessionTokenRequest {
     /** Who the avatar is in the conversation. Leave it out for the default personality. */
     personality?: SessionPersonality;
-    /**
-     * Tools the agent may call, which your page runs and answers with
-     * `onToolCall` and `sendToolResult`;
-     * up to 16. Fixed for the conversation: the page can't change them.
-     *
-     * @example
-     * ```ts
-     * tools: [
-     *   {
-     *     name: "show_confetti",
-     *     description: "Plays confetti on the user's screen. Use it to celebrate with them.",
-     *     parameters: { type: "object", properties: {} },
-     *   },
-     * ]
-     * ```
-     */
-    tools?: FunctionTool[];
     /**
      * Your own id for the person this conversation is for, such as a hash of
      * your user id. After repeated policy violations, new conversations pause
@@ -769,6 +745,19 @@ export declare interface SessionTokenRequest {
      * `_ . : -`, up to 128 characters: never an email address or a name.
      */
     end_user_id?: string;
+    /**
+     * The interface the conversation runs: Nuance Live, the default, whose
+     * events your page sends and receives with `conversation.sendInterfaceEvent`
+     * and `conversation.onInterfaceEvent`. Leave it out.
+     */
+    interface?: "nuance_live";
+    /**
+     * Nuance Live's settings for the session, fixed by the token: who does the
+     * work she hands off, the avatar's own tools, and whether she sees the
+     * user's camera. Any key it doesn't list is refused with `422`
+     * `interface_setup`.
+     */
+    interface_setup?: NuanceLiveSetup;
 }
 
 /** What `POST /session-tokens` returns. */
@@ -785,52 +774,25 @@ export declare interface SessionTokenResponse {
 export declare type StartOn = "first-frame" | "full-quality";
 
 /**
- * The agent's call of one of the conversation's tools: run it, then answer
- * with {@link Conversation.sendToolResult} and its `callId`.
- */
-export declare interface ToolCall {
-    /** Identifies the call; answer with it. */
-    callId: string;
-    /** The tool, by its `name`. */
-    name: string;
-    /** The agent's own short name for this use of the tool, such as `"confetti"`. */
-    label: string;
-    /** The call's arguments, held to the tool's `parameters` schema. */
-    arguments: Record<string, unknown>;
-}
-
-/**
- * An image a tool produced, for the agent to look at: a screenshot, say, or
- * a page of a document. Up to 8,000,000 base64 characters (about 6 MB); the
- * runtime fits it to 1920 px on its long side.
- */
-export declare interface ToolImage {
-    mediaType: "image/jpeg" | "image/png";
-    /** The encoded image, base64. */
-    data: string;
-}
-
-/**
- * What a tool call produced: text, or JSON the agent reads as it is. Up to
- * 24,000 characters (its JSON, for an object); the agent keeps the first 2,000.
- */
-export declare type ToolOutput = string | Record<string, unknown> | unknown[];
-
-/**
- * How {@link Conversation.sendToolResult} reports a result.
- */
-export declare interface ToolResultOptions {
-    /** Images the tool produced, up to 4; the agent looks at them, in order,
-     *  where the result enters the conversation. */
-    images?: ToolImage[];
-    /** The output says what went wrong rather than what the tool produced. */
-    isError?: boolean;
-    /** Whether this is the call's last part; a part with `final: false` adds to
-     *  what the agent knows and keeps the call open.
-     *
-     * @defaultValue `true` */
-    final?: boolean;
-}
+ * MCP's tool hints, up to 2,000 characters as compact JSON. A tool whose
+ * `readOnlyHint` and `idempotentHint` are both `false` or left out is called
+ * at most once per user request with the same arguments, across all the
+ * session's tasks: annotate tools that send, book, pay or post this way. A
+ * tool with no `annotations` runs every call. MCP's other hints are accepted
+ * and not read.
+ */
+export declare type ToolAnnotations = {
+    /** The tool only reads: calling it again changes nothing. */
+    readOnlyHint?: boolean;
+    /** Calling it again with the same arguments has no further effect. */
+    idempotentHint?: boolean;
+    /** MCP's hint; accepted and not read. */
+    destructiveHint?: boolean;
+    /** MCP's hint; accepted and not read. */
+    openWorldHint?: boolean;
+    /** MCP's display title; accepted and not read. */
+    title?: string;
+};
 
 /**
  * The local user participant in a conversation.
@@ -868,59 +830,6 @@ export declare interface UserParticipant {
     readonly isSpeaking: boolean;
 }
 
-/**
- * The user's voice went off, as the same detection reads it. `atMs` is where
- * on the timeline it went off.
- */
-export declare interface UserSpeechEndedEvent extends SessionEventBase {
-    type: "user.speech.ended";
-}
-
-/**
- * The user's voice came on, as the runtime's voice-activity detection reads
- * the microphone. `atMs` is where on the timeline it came on.
- */
-export declare interface UserSpeechStartedEvent extends SessionEventBase {
-    type: "user.speech.started";
-}
-
-/**
- * The user's words, live: one recognized segment at a time, as the runtime
- * hears them. A later {@link UserTurnEndedEvent} may read the same speech
- * differently; its `text` is the record of what the agent answered.
- */
-export declare interface UserTranscriptEvent extends SessionEventBase {
-    type: "user.transcript";
-    /** The segment's words. */
-    text: string;
-    /**
-     * `"asr"`: recognized from the user's microphone. `"text"`: a line given
-     * as the user's turn in text rather than spoken. `"forced"`: a transcript
-     * supplied for the user's audio in place of recognition. A newer runtime
-     * may send other values.
-     */
-    source: "asr" | "forced" | "text" | (string & {});
-}
-
-/**
- * The agent is taking the turn to answer the user; sent each time it does.
- * `atMs` is the point in the user's audio where the agent took the turn: the
- * same moment as the turn's {@link AgentTurnStartedEvent}, stamped on the
- * user's side of the timeline, so it is earlier than that event's `atMs` by
- * the delay before the agent's audio plays.
- */
-export declare interface UserTurnEndedEvent extends SessionEventBase {
-    type: "user.turn.ended";
-    /**
-     * The user's words since the agent last spoke, as the agent read them: a
-     * second, more careful hearing's words in place of the live
-     * {@link UserTranscriptEvent}s' where the runtime has one. When an agent
-     * turn ends before it said a word, the next `user.turn.ended` covers the
-     * same words again.
-     */
-    text: string;
-}
-
 /**
  * Capture constraints for the user's published camera track.
  *