@oberik/sdk 0.59.0 → 0.61.0

package/dist/esm/index.d.ts

@@ -160,6 +160,9 @@ export interface TokenRequest {
     allowed_models?: string[];
     /** Reasoning-effort ceiling. */
     max_effort?: "minimal" | "low" | "medium" | "high";
+    /** Ceiling on how many tool calls one turn may make. Narrows the project's own
+     *  (Dashboard → LLM & limits) — never widens it. */
+    max_tool_iterations?: number;
     /** Ceiling on how much conversation history is replayed for this token, in tokens.
      *  Narrows the project's own context budget (Dashboard → Context management) — it
      *  can never widen it. Use it to give a cheap tier a shorter memory. */
@@ -1057,6 +1060,15 @@ export interface ChatRequest {
      *  the `webhook_tools` capability. Turn it off for a turn that should not touch your
      *  systems. */
     enable_webhook_tools?: boolean;
+    /** Let the agent use its own conversation controls on a voice call — put the caller on
+     *  hold while something slow runs, then come back. Needs the `voice` capability.
+     *
+     *  Nothing to do with whether a call can be OPENED: that is `voice.open()`, and it needs
+     *  the same capability. This is the per-turn switch, so a text turn in the same project
+     *  can decline the tools. They stay bound either way and refuse with a sentence saying
+     *  there is no call — a model that can see a tool it cannot use reasons better than one
+     *  whose toolset silently changed shape. */
+    enable_voice_control?: boolean;
     enable_plugins?: boolean;
     /** Which plugins this turn may use, by name. Omit for everything the token can see.
      *  Narrowing only — a name that is not visible is absent rather than an error, so a
@@ -2201,6 +2213,875 @@ export interface DownloadOptions {
     onProgress?: (received: number, total: number | null) => void;
     signal?: AbortSignal;
 }
+/**
+ * Where a call is. Explicit state rather than something inferred from whether audio is
+ * flowing — render it and your UI is honest about what is happening.
+ *
+ * `status` on the `state` event is the same thing in words a support agent can read; use
+ * that rather than mapping these yourself, so a state added later renders correctly instead
+ * of falling through to whichever branch omits it.
+ */
+export type VoiceState = "listening" | "delegating" | "bridging" | "external_speech" | "canceling" | "holding" | "resuming" | "transferred" | "ended";
+/** How much of the caller is perceived during a hold.
+ *
+ *  `interrupt_only` is the default and almost always right. `off` exists for the rare case
+ *  where being interrupted would break something — a caller who says "never mind" into hold
+ *  music and is not heard has been ignored by a system that thinks it is helping. */
+export type VoiceListen = "full" | "interrupt_only" | "dtmf_only" | "off";
+/** How faithfully the speech layer must realise the model's words.
+ *
+ *  `strict` for figures, dates, addresses and confirmation codes: "about eighteen hundred"
+ *  is not an acceptable rendering of £1,847.23. `natural` (the default) may adapt punctuation
+ *  and disfluencies but never meaning. `free` lets the agent paraphrase, which is right for
+ *  small talk and wrong for anything a customer will act on. */
+export type VoiceFidelity = "strict" | "natural" | "free";
+export interface VoiceWaitingOptions {
+    /** `"auto"` picks from measured latency: bridge under 2s, an announced wait to 10s, hold
+     *  beyond that. Anything else pins the behaviour, which is occasionally what you want for
+     *  a flow you have measured yourself. */
+    strategy?: "auto" | "bridge" | "wait" | "hold";
+    /** Named hold media from your project's assets. Omitted gets a default that is
+     *  unmistakably "you are on hold and the line is alive" — silence on a hold is
+     *  indistinguishable from a dropped call. */
+    hold_music?: string | null;
+    /** Whether the caller may interrupt the agent mid-sentence. Leave it on. */
+    barge_in?: boolean;
+    /** Perception during a hold. */
+    listen_on_hold?: VoiceListen;
+    /** Keep the speech model quiet for the whole wait, not only the beat after it acknowledges.
+     *
+     *  A conversational model with the floor and nothing to say does not wait, it talks — and what
+     *  it says is invented, because it has no idea what is being looked up. With this on it
+     *  acknowledges you once in its own words and then stays silent until you speak, the answer
+     *  arrives, or the wait has gone on long enough that the runtime remarks on it (irregularly,
+     *  and never with the same line twice running). Off by default: a frontend held quiet cannot
+     *  backchannel, and on a fast lookup the silence can feel more abrupt than a murmur. */
+    quiet_while_waiting?: boolean;
+    /** Give the utterance *after* a barge-in longer to finish.
+     *
+     *  A caller who cuts in is mid-thought, and mid-thought is where they pause — so at the
+     *  ordinary end-of-turn threshold the breath ends the turn, the half-sentence is transcribed,
+     *  and the agent answers a question nobody finished asking. On, the detector waits about a
+     *  second longer, and only on the turn that was interrupted. Off by default: it is latency on
+     *  every interrupted turn to fix a problem on some of them. */
+    patient_bargein?: boolean;
+    /** Keep the answer in flight when you interrupt, instead of abandoning it.
+     *
+     *  A barge-in fires 160ms into your speech — before anything can know whether you are asking
+     *  something else or just saying "mm-hmm" — so abandoning the turn there loses the answer to a
+     *  backchannel. On, the agent stops *speaking* at once and keeps *thinking*; a real new request
+     *  still supersedes it. Off by default: interrupt to change the subject and you may hear the
+     *  tail of the previous answer arrive behind the new one. */
+    keep_answer_through_bargein?: boolean;
+    /** Keep the agent's own voice out of your transcript when your microphone hears it.
+     *
+     *  With an echo path the transcriber attributes the agent's speech to you and the agent then
+     *  answers itself — reproduced at 0.5 echo gain, "Thank you for calling Wessex Power" and
+     *  "There's an active outage in your area" both came back as things the caller had said. Off by
+     *  default: set too strictly the protection costs turns, and not being heard is worse than
+     *  being misheard. */
+    guard_asr_echo?: boolean;
+    /** Apply the echo guard to the transcriber's buffer at the onset only, as the detector does.
+     *  On is the corrected behaviour; off restores the per-frame exclusion that dropped a caller
+     *  who talked over the answer at around the agent's own volume. */
+    onset_echo_only?: boolean;
+    /** How much louder than the agent's own output the caller must be to take the floor. Omit for
+     *  the detector's default. Lower admits quieter barge-ins and more of the agent's own echo. */
+    echo_ratio?: number;
+    /** Learn how loud the agent's own voice comes back and lower the barge-in floor to suit the
+     *  room. Can only lower it, never raise it, so the worst case is `echo_ratio`'s behaviour. */
+    adaptive_echo?: boolean;
+    /** Hold the speech model silent through every gap, not just while it waits.
+     *
+     *  Measured cause of the corruption, the invented facts and the repetition, which are one
+     *  bug: 55 words handed over, 175 spoken. The runtime's text is exact; the other 120 are
+     *  the model filling gaps it has nothing to say in, and they come out as word salad. This
+     *  closes the last of them — at the cost of its own acknowledgement, so it is off by
+     *  default. */
+    quiet_unless_answering?: boolean;
+}
+export interface VoiceSessionRequest {
+    /** Which voice, from the ones the frontend has. Omit for the project's default. */
+    voice?: string | null;
+    /** Which role to condition it into — `support`, `sales`. Where the frontend supports it. */
+    role?: string | null;
+    /** Extra instructions for the SPEAKING half. Your project's system prompt still governs
+     *  the answering half; this is for how it talks, not what it knows. */
+    system?: string | null;
+    /** Which model answers. Bounded by the token's model allow-list, like everywhere else. */
+    model?: string | null;
+    /** Which checkpoint on the deployment's speech host, where it serves more than one — a base
+     *  model and a fine-tune of it, say. `voice.frontend()` lists what there is. Not "which
+     *  host": there is one per deployment. Asking for one the host does not serve is a 400
+     *  rather than a silent fallback, so an A/B cannot end up comparing a model with itself. */
+    voice_model?: string | null;
+    /** Which speech frontend runs this call, overriding the project's setting. Per call for the
+     *  same reason the model is: comparing two arrangements means hearing them one after the
+     *  other, and a project-level setting alone makes that a round trip through the settings
+     *  page between every pair. Refused if the deployment does not serve it. */
+    frontend?: string | null;
+    /** Narrow the tools this call may use, by name. Intersected with what the token already
+     *  allows — a call can decline a tool and can never buy one. Omit for everything the token
+     *  allows; `[]` means none, which is a different call.
+     *
+     *  Worth using. A support line has no business running sandboxed compute, and every tool
+     *  the model can see is a tool it can spend a caller's silence on. */
+    allowed_tools?: string[] | null;
+    fidelity?: VoiceFidelity;
+    waiting?: VoiceWaitingOptions;
+    /** Continue an existing conversation, so the caller picks up where they left off. */
+    session_id?: string | null;
+    /** Hard ceiling on this call in seconds. Narrowed by the token's own `max_voice_seconds`
+     *  and by the deployment's — never widened. */
+    max_seconds?: number | null;
+}
+export interface VoiceSessionOut {
+    id: string;
+    /** The chat session this call's turns land in, so a transcript is readable afterwards. */
+    session_id: string;
+    /** WebSocket URL for audio and events. Relative to the API host. */
+    stream_url: string;
+    frontend: string;
+    voice: string | null;
+    role: string | null;
+    /** The checkpoint serving this call, where the host names them. */
+    voice_model: string;
+    /** Sample rate the frontend generates and expects, in Hz. Send whatever you have; it is
+     *  resampled. Play back at this rate. */
+    rate: number;
+    /** Frame period in milliseconds. Informational — the server owns the clock. */
+    frame_ms: number;
+    /** True when the caller is on a channel narrower than the model generates — a phone line.
+     *  It will not sound like the browser demo, and that is the telephone network rather than
+     *  a setting. Surfaced per call so support can stop guessing. */
+    narrowband: boolean;
+    /** Whether this token may hand the call to a person. */
+    can_transfer: boolean;
+}
+/** A live call, as the server reports it. Everything a UI needs in one object. */
+export interface VoiceSnapshot {
+    state: VoiceState;
+    /** The state in words, for a screen. Computed server-side from what is actually true, so
+     *  a new state renders correctly without a client release. */
+    status: string;
+    generation: number | null;
+    epoch: number;
+    listening: VoiceListen;
+    output: "voice" | "hold" | "announcement" | "party" | "silence";
+    queued_ms: number;
+    hold: {
+        id: string;
+        reason: string;
+        elapsed_ms: number;
+        listen: VoiceListen;
+    } | null;
+    transfer: {
+        id: string;
+        target: string;
+    } | null;
+    turns: number;
+    narrowband: boolean;
+}
+/**
+ * One frame from a call.
+ *
+ * The register is deliberately flat and every event carries `at_ms` — milliseconds since the
+ * call opened, measured server-side. Relative rather than absolute because every number that
+ * matters here is a difference, and a wall clock makes two traces from two machines
+ * incomparable.
+ */
+export type VoiceEvent = {
+    event: "session.open";
+    data: {
+        session_id: string;
+        frontend: string;
+        voice: string | null;
+        transport: string;
+        model: string | null;
+        at_ms: number;
+    };
+} | {
+    event: "session.close";
+    data: {
+        session_id: string;
+        reason: string;
+        duration_ms: number;
+        at_ms: number;
+    };
+}
+/** The call moved. `cause` says why, which is what makes a trace readable six states later. */
+ | {
+    event: "state";
+    data: {
+        from: VoiceState;
+        to: VoiceState;
+        cause: string;
+        at_ms: number;
+    };
+} | {
+    event: "caller.speech_start";
+    data: {
+        at_ms: number;
+    };
+} | {
+    event: "caller.speech_end";
+    data: {
+        at_ms: number;
+    };
+} | {
+    event: "caller.transcript";
+    data: {
+        text: string;
+        final: boolean;
+        at_ms: number;
+    };
+} | {
+    event: "agent.transcript";
+    data: {
+        text: string;
+        at_ms: number;
+    };
+}
+/** A request went to the reasoner. `instruction` is what it was asked, which is not
+ *  necessarily what the caller said. */
+ | {
+    event: "delegate.start";
+    data: {
+        generation_id: number;
+        instruction: string;
+        source: string;
+        at_ms: number;
+        turn_id: number;
+        revision: number;
+    };
+}
+/** A request was abandoned. Nothing from it will be spoken — not "queued and skipped": a
+ *  superseded answer cannot reach the caller. */
+ | {
+    event: "delegate.cancel";
+    data: {
+        generation_id: number;
+        reason: string;
+        at_ms: number;
+    };
+} | {
+    event: "delegate.failed";
+    data: {
+        generation_id: number;
+        detail: string;
+        at_ms: number;
+    };
+} | {
+    event: "delegate.end";
+    data: {
+        generation_id: number;
+        chars_spoken: number;
+        at_ms: number;
+    };
+}
+/** The model's first user-visible character. Thinking and tool-call regions do not count —
+ *  those are never spoken, so counting them would make a slow model look fast. */
+ | {
+    event: "reasoner.first_token";
+    data: {
+        generation_id: number;
+        ttft_ms: number;
+        at_ms: number;
+    };
+} | {
+    event: "reasoner.delta";
+    data: {
+        generation_id: number;
+        text: string;
+        at_ms: number;
+    };
+} | {
+    event: "reasoner.tool_start";
+    data: {
+        generation_id: number;
+        name: string;
+        id: string;
+        at_ms: number;
+    };
+} | {
+    event: "reasoner.tool_end";
+    data: {
+        generation_id: number;
+        name: string;
+        id: string;
+        ms: number;
+        at_ms: number;
+    };
+}
+/** The filler it chose while the model starts. */
+ | {
+    event: "voice.bridge";
+    data: {
+        generation_id: number;
+        text: string;
+        budget_ms: number;
+        at_ms: number;
+    };
+}
+/** From here the caller is hearing the model's words in the frontend's voice. */
+ | {
+    event: "voice.takeover";
+    data: {
+        generation_id: number;
+        buffered_chars: number;
+        at_ms: number;
+    };
+}
+/** The caller interrupted and the agent stopped speaking but kept working. Only with
+ *  `keep_answer_through_bargein`; followed by `delegate.end`, it is an answer that survived an
+ *  interruption instead of being lost to a backchannel. */
+ | {
+    event: "delegate.held";
+    data: {
+        generation_id: number;
+        reason: string;
+        at_ms: number;
+    };
+}
+/** How many frames carried a word the model chose rather than one the runtime supplied. A count
+ *  over the host's own `forced` flag — no transcription, no constants. */
+ | {
+    event: "voice.gated";
+    data: {
+        kind: string;
+        text: string;
+        at_ms: number;
+    };
+} | {
+    event: "voice.ungated";
+    data: {
+        kind: string;
+        at_ms: number;
+    };
+} | {
+    event: "turn.held";
+    data: {
+        reason: string;
+        act: string;
+        wait_ms: number;
+        marked: boolean;
+        at_ms: number;
+    };
+} | {
+    event: "caller.echoed";
+    data: {
+        text: string;
+        kept: string;
+        at_ms: number;
+    };
+} | {
+    event: "voice.echo";
+    data: {
+        gain: number;
+        peak: number;
+        floor: number;
+        samples: number;
+        at_ms: number;
+    };
+} | {
+    event: "voice.own_words";
+    data: {
+        frames: number;
+        forced: number;
+        own: number;
+        sample: string;
+        at_ms: number;
+    };
+}
+/** What the agent produced against what the caller actually heard, at the end of a call. The
+ *  one instrument that can see speech corruption. `worst_uninterrupted` is the number that
+ *  means something — an interrupted turn legitimately scores badly. */
+ | {
+    event: "voice.fidelity";
+    data: {
+        turns: number;
+        unscorable: number;
+        worst: number;
+        worst_uninterrupted: number;
+        spans_intact: boolean;
+        wrote?: string;
+        heard?: string;
+        at_ms: number;
+    };
+}
+/** The runtime remarked on a wait that has gone on. Only with `quiet_while_waiting`: the
+ *  frontend is held silent for the whole lookup, and this stops the silence reading as a
+ *  dropped call. Irregular by design, and never the same line twice running. */
+ | {
+    event: "voice.patience";
+    data: {
+        generation_id: number;
+        text: string;
+        waited_ms: number;
+        at_ms: number;
+    };
+}
+/** A grounded answer the frontend never said, spoken as written instead. `free` fidelity bets
+ *  that a frontend handed a fact will compose a sentence about it; this is that bet losing. */
+ | {
+    event: "voice.grounding_backstop";
+    data: {
+        generation_id: number;
+        chars: number;
+        waited_ms: number;
+        at_ms: number;
+    };
+}
+/** The answer was given to the frontend as grounding rather than as words to say. Only on a
+ *  reference-conditioned arrangement: what the caller hears next is the frontend's own
+ *  sentence about this fact, not this text read out. */
+ | {
+    event: "voice.conditioned";
+    data: {
+        generation_id: number;
+        chars: number;
+        at_ms: number;
+    };
+}
+/** An answer thrown away because its generation was no longer current. On a
+ *  reference-conditioned frontend this is the only protection there is — conditioning cannot
+ *  be cut off mid-word the way injected text can. */
+ | {
+    event: "voice.dropped";
+    data: {
+        generation_id: number;
+        chars: number;
+        why: string;
+        at_ms: number;
+    };
+} | {
+    event: "voice.release";
+    data: {
+        generation_id: number;
+        at_ms: number;
+    };
+}
+/** The caller barged in. `dropped_chars` is what they did not hear. */
+ | {
+    event: "voice.interrupted";
+    data: {
+        generation_id: number;
+        spoken_chars: number;
+        dropped_chars: number;
+        at_ms: number;
+    };
+}
+/** The paced queue ran dry mid-answer — the model is slower than speech. Audible as a
+ *  pause inside a sentence, and the number that says whether the bridge was long enough. */
+ | {
+    event: "voice.starved";
+    data: {
+        generation_id: number;
+        ms: number;
+        at_ms: number;
+    };
+} | {
+    event: "wait.chosen";
+    data: {
+        generation_id: number;
+        mode: "bridge" | "wait" | "hold" | "transfer";
+        predicted_ms: number | null;
+        basis: string;
+        at_ms: number;
+    };
+} | {
+    event: "hold.requested";
+    data: {
+        hold_id: string;
+        reason: string;
+        mode: string;
+        listen: VoiceListen;
+        max_ms: number;
+        at_ms: number;
+    };
+} | {
+    event: "hold.entered";
+    data: {
+        hold_id: string;
+        media: string;
+        at_ms: number;
+    };
+} | {
+    event: "hold.interrupted";
+    data: {
+        hold_id: string;
+        heard: string;
+        at_ms: number;
+    };
+} | {
+    event: "hold.progress";
+    data: {
+        hold_id: string;
+        text: string;
+        elapsed_ms: number;
+        at_ms: number;
+    };
+} | {
+    event: "hold.completed";
+    data: {
+        hold_id: string;
+        outcome: "done" | "failed" | "interrupted" | "timeout" | "abandoned";
+        elapsed_ms: number;
+        at_ms: number;
+    };
+} | {
+    event: "resume.started";
+    data: {
+        hold_id: string;
+        transition: string;
+        speech_hint: string;
+        at_ms: number;
+    };
+} | {
+    event: "resume.done";
+    data: {
+        hold_id: string;
+        silence_ms: number;
+        at_ms: number;
+    };
+} | {
+    event: "transfer.requested";
+    data: {
+        transfer_id: string;
+        target: string;
+        context: string;
+        at_ms: number;
+    };
+} | {
+    event: "transfer.consulting";
+    data: {
+        transfer_id: string;
+        target: string;
+        at_ms: number;
+    };
+} | {
+    event: "transfer.completed";
+    data: {
+        transfer_id: string;
+        target: string;
+        elapsed_ms: number;
+        at_ms: number;
+    };
+}
+/** Nobody took the call. The caller is back with the agent, not on a dead line. */
+ | {
+    event: "transfer.failed";
+    data: {
+        transfer_id: string;
+        target: string;
+        detail: string;
+        at_ms: number;
+    };
+} | {
+    event: "media.source";
+    data: {
+        source: string;
+        fade_ms: number;
+        at_ms: number;
+    };
+}
+/** Audio has actually played out to the caller. The only honest "they heard it" — anything
+ *  else is a guess about a buffer that is not yours. */
+/** A mark was placed where a protected figure finished being spoken, or an answer did.
+ *  Call `markPlayed(mark)` once your player has passed it — that confirmation is the only
+ *  thing that turns "the balance was sent" into "the balance was heard". */
+ | {
+    event: "media.mark_placed";
+    data: {
+        mark: string;
+        source: string;
+        what: string;
+        at_ms: number;
+    };
+}
+/** Your confirmation came back and the server recorded it. */
+ | {
+    event: "media.mark";
+    data: {
+        mark: string;
+        source: string;
+        at_ms: number;
+    };
+} | {
+    event: "context.injected";
+    data: {
+        keys: string[];
+        at_ms: number;
+    };
+} | {
+    event: "error";
+    data: {
+        detail: string;
+        where: string;
+        at_ms: number;
+    };
+}
+/** What the caller said, kept as context rather than acted on — this frontend decides for
+ *  itself when a turn needs the agent. Reported because "the transcript changed nothing" and
+ *  "no transcript arrived" are different facts. */
+ | {
+    event: "caller.context";
+    data: {
+        text: string;
+        at_ms: number;
+    };
+}
+/** A transcript arrived and this project has them switched off, so it was discarded. */
+ | {
+    event: "caller.transcript_ignored";
+    data: {
+        text: string;
+        at_ms: number;
+    };
+}
+/** What the speech model itself said the caller wanted, and whether that needs the agent. The
+ *  delegation text coming from the model that *heard* the call rather than a transcript of it. */
+ | {
+    event: "monologue.turn";
+    data: {
+        text: string;
+        delegating: boolean;
+        at_ms: number;
+    };
+}
+/** The caller finished a turn and the speech model said nothing at all within the window. No
+ *  instruction, so no delegation — reported rather than silent. */
+ | {
+    event: "monologue.empty";
+    data: {
+        waited_ms: number;
+        at_ms: number;
+    };
+}
+/** A second delegation for a turn already answered, refused. Two paths can start one; seeing
+ *  this is normal with a transcriber, never seeing it means one of them is dead. */
+ | {
+    event: "delegate.duplicate";
+    data: {
+        source: string;
+        instruction: string;
+        at_ms: number;
+    };
+}
+/** The selected model thinking. **Never spoken** — carried so a client can show it. */
+ | {
+    event: "reasoner.reasoning";
+    data: {
+        generation_id: number;
+        text: string;
+        at_ms: number;
+    };
+}
+/** A caller turn needed nothing looked up, the speech model did not answer it either, and the
+ *  runtime spoke rather than leave the caller listening to silence. */
+ | {
+    event: "voice.backstop";
+    data: {
+        waited_ms: number;
+        delegating?: boolean;
+        at_ms: number;
+    };
+}
+/** The frontend was given the gap while the agent thought, said nothing audible, and the
+ *  runtime covered it. An uncovered gap is a caller who believes the line has dropped. */
+ | {
+    event: "voice.bridge_backstop";
+    data: {
+        generation_id: number;
+        waited_ms: number;
+        at_ms: number;
+    };
+}
+/** A mark reached the caller's ear. The client's half of the fidelity guarantee: everything
+ *  the server knows is about what it *sent*. */
+ | {
+    event: "media.mark_placed";
+    data: {
+        mark: string;
+        source: string;
+        what: string;
+        at_ms: number;
+    };
+}
+/** The application's own line was queued into the frontend's monologue, displacing whatever
+ *  of the previous answer had not been spoken yet. */
+ | {
+    event: "speech.injected";
+    data: {
+        chars: number;
+        displaced_chars: number;
+        at_ms: number;
+    };
+};
+export type VoiceEventName = VoiceEvent["event"];
+export interface VoiceHandlers {
+    /** Audio for the caller: 16-bit signed little-endian PCM at `VoiceSessionOut.rate`. */
+    onAudio?: (pcm: ArrayBuffer) => void;
+    /** Every event. Use this for a trace panel; use `on()` for one kind. */
+    onEvent?: (ev: VoiceEvent) => void;
+    /** The call moved. The one handler a UI genuinely needs. */
+    onState?: (snapshot: {
+        from: VoiceState;
+        to: VoiceState;
+        cause: string;
+    }) => void;
+    onError?: (detail: string) => void;
+    /** The socket closed, for any reason. */
+    onClose?: (reason: string) => void;
+}
+/**
+ * A live call.
+ *
+ * Audio in with `send`, audio out through `onAudio`, and everything else as events. The
+ * call ends when you `close()` it, when the caller hangs up, or when its ceiling is reached.
+ *
+ * `hold`/`resume`/`transfer` are here as well as being tools the agent can call, because the
+ * decision is sometimes your application's rather than the model's — an app that already
+ * knows the CRM lookup it just triggered takes half a minute should not have to hope the
+ * agent works that out.
+ */
+export interface VoiceCall {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly rate: number;
+    readonly info: VoiceSessionOut;
+    /** Send caller audio. 16-bit signed little-endian PCM, any rate — it is resampled.
+     *
+     *  Any view is accepted, not just `Uint8Array`: a browser's Web Audio path produces an
+     *  `Int16Array` and requiring a byte view would make every caller write the same three lines
+     *  of reinterpretation. */
+    send(pcm: ArrayBuffer | ArrayBufferView): void;
+    /** Subscribe to one kind of event. Returns an unsubscribe function. */
+    on<K extends VoiceEventName>(name: K, fn: (data: Extract<VoiceEvent, {
+        event: K;
+    }>["data"]) => void): () => void;
+    /** The call as the server sees it, now. */
+    snapshot(): Promise<VoiceSnapshot>;
+    /** Put the caller on hold from your side. */
+    hold(opts?: {
+        reason?: string;
+        listen?: VoiceListen;
+        max_seconds?: number;
+    }): Promise<void>;
+    /** Take them off hold, optionally with a line to come back on. */
+    resume(opts?: {
+        lead?: string;
+    }): Promise<void>;
+    /**
+     * Run something slow behind a hold, and come back when it finishes.
+     *
+     * The primitive you actually want when the slow thing is **yours** — a CRM lookup, a booking
+     * system, a payment confirmation your own backend does. `hold()` and `resume()` are the two
+     * halves; this owns the race between them, which is where the bugs are:
+     *
+     * ```ts
+     * const account = await call.holdUntil(
+     *   () => crm.expensiveLookup(customerId),
+     *   { reason: "looking up the account", maxSeconds: 90 },
+     * );
+     * if (account.outcome === "done") {
+     *   // The caller is already back and has heard "thanks for waiting". Say the answer.
+     * }
+     * ```
+     *
+     * Four things can happen and all four are returned rather than thrown: the work finishes,
+     * the work fails, the ceiling is reached, or **the caller talks their way out of it**. That
+     * last one is why this exists — a caller who says "actually never mind" into thirty seconds
+     * of hold music and is not heard has been hung up on by a system that thinks it is helping,
+     * and getting it right by hand means racing four conditions and cancelling in the right
+     * order.
+     *
+     * A ceiling is enforced whether you pass one or not. A hold with no ceiling is a caller on
+     * hold until they give up, which is the most common way an automated line loses a customer.
+     */
+    holdUntil<T>(work: () => Promise<T>, opts?: {
+        reason?: string;
+        listen?: VoiceListen;
+        maxSeconds?: number;
+        lead?: string;
+    }): Promise<{
+        outcome: "done" | "failed" | "timeout" | "interrupted";
+        result?: T;
+        error?: unknown;
+    }>;
+    /** Hand the call to a person. Needs `voice:transfer`. */
+    transfer(to: string, context: string): Promise<void>;
+    /** Tell the frontend something it should KNOW and not necessarily say — an account tier
+     *  that shapes tone, a customer id it must never read out. Distinct from speech on
+     *  purpose: conflating the two is what makes an agent recite a reference number. */
+    inject(facts: Record<string, unknown>): Promise<void>;
+    /** Say a line YOU wrote, in the agent's voice. The other half of `inject()`: that one is
+     *  "know this", this one is "say this".
+     *
+     *  For what only your application knows in the moment — a card that was just declined, an
+     *  appointment that has moved, a line compliance requires on every call. **Not for
+     *  answers**: an answer is a turn, and it gets a model, a bridge while it is being composed,
+     *  and a latency you can measure. Text pushed through here gets none of that.
+     *
+     *  It goes through the same machinery the agent's own speech does, so a caller can talk over
+     *  it — which is the point. A line the caller cannot interrupt is a line they keep hearing
+     *  while they are trying to object to it.
+     *
+     *  `interrupt` (default true) **takes the floor**: an answer being spoken is abandoned, and
+     *  `displaced_chars` says how much of it. That is right for what this is for — a declined
+     *  card outranks the sentence it lands in the middle of. Pass `false` for a disclosure that
+     *  should wait; it is refused rather than chopping an answer in half.
+     *
+     *  Returns what happened rather than resolving regardless. On hold or mid-transfer the
+     *  honest answer is no, and `reason` says which. */
+    say(text: string, opts?: {
+        interrupt?: boolean;
+    }): Promise<{
+        spoken: boolean;
+        chars?: number;
+        displaced_chars?: number;
+        reason?: string;
+    }>;
+    /** The caller started talking. Send this the moment your own voice detection fires —
+     *  within a couple of hundred milliseconds — and stop your local playback in the same
+     *  breath.
+     *
+     *  Waiting for a transcript is waiting for a whole utterance, by which time the agent has
+     *  talked over them. This is the client's half of barge-in; the server drops what it had
+     *  queued and abandons the answer in flight. */
+    speechStart(): void;
+    /** The caller stopped talking. */
+    speechEnd(): void;
+    /** What the caller said, if your client does its own transcription. Omit it and the
+     *  server's frontend supplies one — this is for a deployment that already has an ASR it
+     *  trusts, or for driving a call from text. */
+    transcript(text: string, final?: boolean): void;
+    /** A keypad press. On a hold, this is the classic "press 1 to come back". */
+    dtmf(digit: string): void;
+    /** The caller is gone. Distinct from `close()`: this says the *person* left, which is what
+     *  ends the conversation; `close()` only drops your connection to it. */
+    hangUp(): void;
+    /** Audio the server sent has finished playing out to the caller.
+     *
+     *  Pass the `mark` from a `media.mark_placed` event once your player has played past that
+     *  point. Until you do, `verbatim` figures in the call's fidelity report read `heard: null` —
+     *  unknown, which is the honest answer, because everything else the server knows is about
+     *  what it *sent*.
+     *
+     *  Only meaningful if you can actually tell — a browser scheduling PCM cannot, and guessing
+     *  is worse than not reporting: a mark confirmed early tells the server a sentence was
+     *  heard when it was still queued, which is the one fact a barge-in decision must not get
+     *  wrong. */
+    markPlayed(mark: string): void;
+    /** Latencies and counts for this call. The counts matter as much as the timings: an
+     *  average over turns that produced audio improves when the system gets worse. */
+    bench(): Promise<{
+        timings: Record<string, unknown>;
+        counts: Record<string, number>;
+    }>;
+    close(): void;
+    readonly closed: boolean;
+}
 /**
  * Make the arguments match the declared types, as far as that is safe.
  *
@@ -2403,7 +3284,14 @@ export declare class AgentFramework {
      * Mint a narrower token from the current credential — for a backend holding a
      * project key that hands short-lived, per-end-user tokens to its frontend. Every
      * field is intersected/clamped with what the caller already holds, so this can only
-     * ever narrow: a restricted token cannot mint a broader one.
+     * ever narrow: a restricted token cannot mint a broader one. A bound the caller holds
+     * applies whether or not you name the field, because an absent claim reads as
+     * *unrestricted*.
+     *
+     * `expires_in` is the one exception, deliberately: it is clamped against the PROJECT's
+     * maximum rather than the caller's remaining lifetime, so a short-lived token can mint
+     * a longer-lived one. It is the same grant for longer, never a wider one — but size a
+     * token's lifetime by what it may do, not by whatever minted it.
      */
     auth: {
         token: (body?: TokenRequest) => Promise<TokenResponse>;
@@ -2731,6 +3619,82 @@ export declare class AgentFramework {
             }) => Promise<SessionOut>;
         };
     };
+    /**
+     * Live voice calls.
+     *
+     * `open()` creates the call and connects the audio socket; everything after that is
+     * `send()` for microphone audio, `onAudio` for what to play, and events for what is
+     * happening. The token is the same end-user JWT everything else uses, and the turns
+     * behind the call are ordinary turns — same capability gate, same tool allow-list, same
+     * per-customer cost attribution.
+     *
+     * Needs a `WebSocket` global: present in browsers and in Node 22+. On older Node, pass
+     * one in as `webSocket` — the SDK deliberately has no dependencies, so it will not bring
+     * an implementation of its own.
+     */
+    voice: {
+        open: (body?: VoiceSessionRequest, handlers?: VoiceHandlers, opts?: {
+            webSocket?: unknown;
+        }) => Promise<VoiceCall>;
+        /** Reconnect to a call that is already open — a page reload, a second screen watching.
+         *
+         *  Audio goes to whoever is connected; events go to everyone. So a supervisor can watch
+         *  a call without taking it over, which is what a call-centre floor actually needs. */
+        attach: (id: string, handlers?: VoiceHandlers, opts?: {
+            webSocket?: unknown;
+        }) => Promise<VoiceCall>;
+        /** Every call this token can see. */
+        list: () => Promise<VoiceSnapshot[]>;
+        /** What the frontend can do — the voices and roles a project may ask for. Read it rather
+         *  than hard-coding a list: asking for a voice the host does not have fails the call at
+         *  `open()`, which is a worse place to find out than a dropdown. */
+        frontend: () => Promise<{
+            name: string;
+            rate: number;
+            frame_ms: number;
+            voices: string[];
+            roles: string[];
+            /** The checkpoints this host serves. Empty means it serves one and does not name it —
+             *  and then `voice_model` on `open()` is refused rather than quietly ignored. */
+            models: string[];
+            default_model: string;
+            /** What language each voice speaks, and the one used when the project names none. The
+             *  frontend is the authority here: a voice is trained in a language, so this is what
+             *  decides which phrasebook a call gets. */
+            voice_languages: Record<string, string>;
+            default_language: string;
+            /** Whether the host will speak words it did not generate (a grounded answer read out as
+             *  written), and whether an answer can be handed to it as context instead. A frontend
+             *  with neither can only be bridged to, which changes what a slow lookup sounds like. */
+            supports_injection: boolean;
+            supports_context: boolean;
+            max_concurrent: number;
+            in_use: number;
+            /** The other speech arrangements this deployment can reach, if any. More than one means
+             *  a call may name which runs it — see `frontend` on `open()`. One or none means the
+             *  deployment has a single host and the choice does not exist. */
+            frontends: string[];
+            /** Whether an answer reaches the model as grounding rather than as words to say. Told
+             *  apart from `supports_injection` because a host can take a reference and still refuse
+             *  to be told what to say, and the two produce different failures. */
+            conditions_on_reference: boolean;
+            /** Whether the selected model decides for itself when a turn needs the agent, and says so
+             *  with a directive in its own monologue. A checkpoint with a native retrieval trigger, or
+             *  one carrying a trained adapter, does; without either the runtime's router decides
+             *  instead. Worth reading rather than inferring from behaviour: the two arrangements fail
+             *  in different ways, and knowing which you are looking at is most of the diagnosis. */
+            emits_directives: boolean;
+            /** Which of the host's models decide for themselves, by name. Per model, because it is a
+             *  property of the weights: a host serving a checkpoint and an adapter trained on top of it
+             *  answers differently for each, and `emits_directives` alone described the process. */
+            decides_by_model: Record<string, boolean>;
+            /** Whether the host transcribes the caller. Context for the request, never a trigger —
+             *  a transcript that also triggers races the model's own monologue and loses, because the
+             *  monologue is ready the moment the frontend stops talking. */
+            provides_transcripts: boolean;
+        }>;
+    };
+    private connectVoice;
     /** Agent Plugins — the skills this token can reach for, and the ones it may add.
      *
      *  Two sources, one list: what the project published plus anything this end-user