@pyai/sdk 0.5.0 → 0.6.0

package/AGENT_GUIDE.md

@@ -1,13 +1,17 @@
 # PyAI CLI integration guide for coding agents
 
+Speech and calling decision tree: https://pyai.com/agents/speech-calling.md
+Omni frame contract: https://api.pyai.com/omni-frames.json
+
+
 Use this guide when building an application against PyAI, automating a file
 workflow, or adding PyAI to an existing repository. It is readable as plain
 Markdown and does not require the marketing website renderer.
 
 ## Availability and sources of truth
 
-The CLI is included in `@pyai/sdk` 0.5.0. Install it with
-`npm install -g @pyai/sdk@0.5.0`. Browser login supports existing PyAI accounts;
+The CLI is included in `@pyai/sdk` 0.6.0. Install it with
+`npm install -g @pyai/sdk@0.6.0`. Browser login supports existing PyAI accounts;
 unattended agents should use an authorized environment key. Inspect the
 installed command schema before acting.
 
@@ -31,7 +35,7 @@ do not invent an endpoint or present the feature as deployed.
 Install the published CLI with Node.js 22 or newer recommended:
 
 ```bash
-npm install -g @pyai/sdk@0.5.0
+npm install -g @pyai/sdk@0.6.0
 pyai --version
 pyai schema --json
 ```
@@ -47,7 +51,7 @@ npm install -g .
 ```
 
 Alternatively install a supplied build with
-`npm install -g /path/to/pyai-sdk-0.5.0.tgz`. The compiled executable supports
+`npm install -g /path/to/pyai-sdk-0.6.0.tgz`. The compiled executable supports
 Node.js 18 or newer. Use `node dist/cli.js` explicitly when another package's
 `pyai` shadows this executable.
 

package/CLI.md

@@ -6,8 +6,8 @@ scripts and in coding agents with shell access, including Cursor, Claude Code,
 and Codex. `--json` provides structured results; `--help` and `schema` describe
 the installed command surface.
 
-**Version:** the expanded CLI is included in `@pyai/sdk` 0.5.0. Install it from
-npm with `npm install -g @pyai/sdk@0.5.0`, then run `pyai login` for browser
+**Version:** the expanded CLI is included in `@pyai/sdk` 0.6.0. Install it from
+npm with `npm install -g @pyai/sdk@0.6.0`, then run `pyai login` for browser
 sign-in or provide `PYAI_API_KEY` for unattended automation.
 
 ## Contents
@@ -31,7 +31,7 @@ sign-in or provide `PYAI_API_KEY` for unattended automation.
 Install the published package (Node.js 22 or newer recommended):
 
 ```bash
-npm install -g @pyai/sdk@0.5.0
+npm install -g @pyai/sdk@0.6.0
 pyai --version
 pyai login
 pyai speak "Hello from PyAI." -o hello.wav
@@ -56,7 +56,7 @@ also be packaged and installed on another machine:
 # In sdk/typescript after building
 npm pack --ignore-scripts
 # On the destination machine, using the actual tarball path
-npm install -g /path/to/pyai-sdk-0.5.0.tgz
+npm install -g /path/to/pyai-sdk-0.6.0.tgz
 pyai schema --json
 ```
 
@@ -607,3 +607,28 @@ exit/error code, request ID, and a redacted reproduction. Never include the key.
 Realtime microphone sessions, live Hear streams, Omni conversations, and live
 AMD streams require a realtime client. Use the SDK and canonical protocol docs
 for those workflows; the CLI covers files, REST operations, and job lifecycles.
+
+## Speech and calling
+
+Read the [speech and calling decision tree](https://pyai.com/agents/speech-calling.md),
+or run `pyai recipes calling --json` / `pyai recipes omni --json`.
+
+- `numbers search`, `numbers list`, `numbers buy`, `numbers bind ID`: discover,
+  purchase and route managed numbers. `numbers bind` takes `--data` with
+  `agent_id`; null unassigns.
+- `calls create`, `calls list`, `calls get ID`, `calls wait ID`: real outbound
+  calling. Creation requires a request body from the live contract.
+- `omni calls`, `omni get ID`, `omni summary ID`, `omni transcript ID`,
+  `omni recording ID --out call.wav`: read session artifacts, including inbound
+  calls. Use `--session-label` on `omni calls` to find an Agent's sessions.
+
+Purchases and outbound calls require `--confirm` and `--idempotency-key`. Use
+`--dry-run` for inspection before authorized execution. `needs_human` (exit 2)
+means confirmation is missing and no submission was made. Outbound test calls
+are real calls; sandbox keys do not grant dialing or purchase permissions.
+The API enforces deployment availability, scopes, billing and policy gates.
+
+`calls wait` accepts `--wait-timeout` and `--poll-interval`; preserve the original
+ID after a deadline. `dispatch_unknown` stops waiting with a failure result for
+inspection, never redial. Follow `calls get`'s `artifacts.omni_call_id` to session
+artifacts. A completed call does not guarantee a recording or summary.

package/CLI.schema.json

@@ -232,6 +232,131 @@
       "command": "doctor",
       "description": "Diagnose key, catalogs, and a Speak to Hear round-trip"
     },
+    {
+      "command": "omni calls",
+      "description": "List Omni sessions including inbound calls. Scope omni:read.",
+      "args": [],
+      "flags": {
+        "session-label": "string",
+        "limit": "string",
+        "cursor": "string"
+      }
+    },
+    {
+      "command": "omni get",
+      "description": "Read an Omni call's transcript, summary and recording availability.",
+      "args": [
+        "id"
+      ],
+      "flags": {}
+    },
+    {
+      "command": "omni summary",
+      "description": "Read the structured summary of an Omni session when generated.",
+      "args": [
+        "id"
+      ],
+      "flags": {}
+    },
+    {
+      "command": "omni transcript",
+      "description": "Read the complete Omni session transcript.",
+      "args": [
+        "id"
+      ],
+      "flags": {}
+    },
+    {
+      "command": "omni recording",
+      "description": "Download the recording with --out; recording must have been enabled for this call.",
+      "args": [
+        "id"
+      ],
+      "flags": {
+        "out": "string",
+        "force": "boolean"
+      }
+    },
+    {
+      "command": "numbers search",
+      "description": "Search managed numbers; inspect provisioning availability before buying. Scope telephony:manage.",
+      "args": [],
+      "flags": {
+        "country": "string",
+        "area-code": "string",
+        "contains": "string",
+        "limit": "string"
+      }
+    },
+    {
+      "command": "numbers list",
+      "description": "List the organization's managed numbers and current Agent bindings.",
+      "args": [],
+      "flags": {
+        "include-released": "boolean",
+        "limit": "string",
+        "cursor": "string"
+      }
+    },
+    {
+      "command": "numbers buy",
+      "description": "Purchase a number from JSON. Requires --confirm and --idempotency-key; may incur recurring charges.",
+      "args": [],
+      "flags": {
+        "data": "string",
+        "idempotency-key": "string",
+        "confirm": "boolean"
+      }
+    },
+    {
+      "command": "numbers bind",
+      "description": "Bind an existing number using JSON {agent_id}; null unassigns. Read numbers list first.",
+      "args": [
+        "id"
+      ],
+      "flags": {
+        "data": "string",
+        "idempotency-key": "string"
+      }
+    },
+    {
+      "command": "calls list",
+      "description": "List outbound call requests and their normalized status.",
+      "args": [],
+      "flags": {
+        "limit": "string",
+        "cursor": "string"
+      }
+    },
+    {
+      "command": "calls create",
+      "description": "Dial a real destination from JSON. Requires --confirm and --idempotency-key; this is not a simulated test call.",
+      "args": [],
+      "flags": {
+        "data": "string",
+        "idempotency-key": "string",
+        "confirm": "boolean"
+      }
+    },
+    {
+      "command": "calls get",
+      "description": "Get an outbound call by its returned ID; retain artifact identifiers separately.",
+      "args": [
+        "id"
+      ],
+      "flags": {}
+    },
+    {
+      "command": "calls wait",
+      "description": "Wait with a deadline. dispatch_unknown stops polling for manual inspection; never redial automatically.",
+      "args": [
+        "id"
+      ],
+      "flags": {
+        "wait-timeout": "string",
+        "poll-interval": "string"
+      }
+    },
     {
       "command": "agents list",
       "description": "List managed Agent profiles.",
@@ -660,6 +785,123 @@
     }
   ],
   "routes": [
+    {
+      "command": "omni calls",
+      "method": "GET",
+      "path": "/v1/omni/calls",
+      "query": {
+        "session-label": "string",
+        "limit": "string",
+        "cursor": "string"
+      },
+      "description": "List Omni sessions including inbound calls. Scope omni:read."
+    },
+    {
+      "command": "omni get",
+      "method": "GET",
+      "path": "/v1/omni/calls/{id}",
+      "id": true,
+      "description": "Read an Omni call's transcript, summary and recording availability."
+    },
+    {
+      "command": "omni summary",
+      "method": "GET",
+      "path": "/v1/omni/calls/{id}/summary",
+      "id": true,
+      "description": "Read the structured summary of an Omni session when generated."
+    },
+    {
+      "command": "omni transcript",
+      "method": "GET",
+      "path": "/v1/omni/calls/{id}/transcript",
+      "id": true,
+      "description": "Read the complete Omni session transcript."
+    },
+    {
+      "command": "omni recording",
+      "method": "GET",
+      "path": "/v1/omni/calls/{id}/recording",
+      "id": true,
+      "binary": true,
+      "description": "Download the recording with --out; recording must have been enabled for this call."
+    },
+    {
+      "command": "numbers search",
+      "method": "GET",
+      "path": "/v1/telephony/available",
+      "query": {
+        "country": "string",
+        "area-code": "string",
+        "contains": "string",
+        "limit": "string"
+      },
+      "description": "Search managed numbers; inspect provisioning availability before buying. Scope telephony:manage."
+    },
+    {
+      "command": "numbers list",
+      "method": "GET",
+      "path": "/v1/telephony/numbers",
+      "query": {
+        "include-released": "boolean"
+      },
+      "description": "List the organization's managed numbers and current Agent bindings."
+    },
+    {
+      "command": "numbers buy",
+      "method": "POST",
+      "path": "/v1/telephony/numbers",
+      "body": true,
+      "confirm": true,
+      "idempotencyRequired": true,
+      "description": "Purchase a number from JSON. Requires --confirm and --idempotency-key; may incur recurring charges."
+    },
+    {
+      "command": "numbers bind",
+      "method": "POST",
+      "path": "/v1/telephony/numbers/{id}/assign",
+      "id": true,
+      "body": true,
+      "description": "Bind an existing number using JSON {agent_id}; null unassigns. Read numbers list first."
+    },
+    {
+      "command": "calls list",
+      "method": "GET",
+      "path": "/v1/telephony/calls",
+      "description": "List outbound call requests and their normalized status."
+    },
+    {
+      "command": "calls create",
+      "method": "POST",
+      "path": "/v1/telephony/calls",
+      "body": true,
+      "confirm": true,
+      "idempotencyRequired": true,
+      "description": "Dial a real destination from JSON. Requires --confirm and --idempotency-key; this is not a simulated test call."
+    },
+    {
+      "command": "calls get",
+      "method": "GET",
+      "path": "/v1/telephony/calls/{id}",
+      "id": true,
+      "description": "Get an outbound call by its returned ID; retain artifact identifiers separately."
+    },
+    {
+      "command": "calls wait",
+      "method": "GET",
+      "path": "/v1/telephony/calls/{id}",
+      "id": true,
+      "wait": {
+        "success": [
+          "completed"
+        ],
+        "failure": [
+          "failed",
+          "canceled",
+          "dispatch_unknown"
+        ]
+      },
+      "description": "Wait with a deadline. dispatch_unknown stops polling for manual inspection; never redial automatically."
+    },
     {
       "command": "agents list",
       "method": "GET",

package/README.md

@@ -99,6 +99,12 @@ Live `0x02` transcript bodies are plain UTF-8 caller-text deltas, not JSON.
 Coalesce successive deltas for the current caller turn. Bounded direct JSON
 bodies remain accepted for older bridges.
 
+Since version 0.5.1, the engine's four-field assistant synthesis advisory on
+`0x03` also reaches `onTranscript` with `role: "assistant"`, `final: true`,
+and `mode: "replace"`.
+This is text submitted for synthesis; it does not prove that playback completed.
+Caller transcripts continue to require the `0x02` carrier.
+
 `rate` configures caller input. A `rate: 16000` session still receives 24 kHz
 agent audio; `rate: 8000` receives 8 kHz. Read `hello.audio_out` before playback.
 Omni has no commit frame—keep streaming silence during caller pauses.

package/dist/cli-dx.d.ts

@@ -7,5 +7,6 @@ export interface Recipe {
     description: string;
     commands: string[];
     notes: string[];
+    docs_url: string;
 }
 export declare const recipes: Recipe[];

package/dist/cli-dx.js

@@ -8,6 +8,12 @@ export const shortFlags = Object.assign(Object.create(null), {
     "-t": "--text", "-p": "--profile", "-j": "--json",
 });
 export const recipes = [
+    { name: "calling", title: "Set up a managed phone Agent", description: "Inspect numbers, bind a profile, and retrieve call artifacts through the public API.",
+        commands: ["pyai whoami --json", "pyai numbers list --json", "pyai numbers search --country US --limit 5 --json", "pyai agents list --json", "pyai numbers bind NUMBER_ID --data @binding.json --dry-run --json", "pyai calls create --data @call.json --idempotency-key CALL_REQUEST_KEY --dry-run --json", "pyai calls get RETURNED_CALL_ID --json", "pyai omni get OMNI_CALL_ID --json"],
+        notes: ["Replace all placeholder IDs with returned values. binding.json is {agent_id: RETURNED_AGENT_ID}; call.json requires from_number_id, to, agent_id and use_case from live OpenAPI.", "Remove --dry-run for authorized changes. numbers buy and calls create require --confirm and --idempotency-key. Calls reach real destinations; sandbox keys do not grant telephony permissions.", "Requires telephony:manage; session artifacts require omni:read. Preserve artifacts.omni_call_id. Read the decision tree for purchase, polling, recording, and inbound-call steps.", "Use calls wait ID --wait-timeout 120 --poll-interval 3 --json for bounded waiting. dispatch_unknown requires inspection, never automatic redial."] },
+    { name: "omni", title: "Build a realtime conversation with the SDK", description: "Use the official SDK for binary framing, subprotocol auth, and typed events.",
+        commands: ["pyai schema --openapi --json", "pyai init voice-demo --template typescript", "pyai voices --json"],
+        notes: ["The starter supplies Hear/Speak examples. Add realtime through pyai.omni.connect({ rate, configure }); see the linked decision tree's SDK pattern.", "Wait for configured before non-silent input. Stream paced digital silence during pauses. Read hello.audio_out and clear queued playback on barge_in/flush.", "Browser code uses an ephemeral token minted by omni.createSession on your server. Never put live keys in browser code or URLs.", "Machine framing contract: https://api.pyai.com/omni-frames.json. For an existing Twilio number use @pyai/twilio and the official twilio-omni-voice-agent example."] },
     { name: "auth", title: "Sign in and check access", description: "Save a named profile and inspect the current credential.",
         commands: ["pyai login --profile work", "pyai whoami --profile work --json", "pyai use work"],
         notes: ["Browser login requires the CLI login API and console deployment. Use --no-browser on remote terminals.", "For unattended runs, supply PYAI_API_KEY through the environment. Environment values override saved profiles."] },
@@ -28,5 +34,5 @@ export const recipes = [
         notes: ["Local schema and recipes work without credentials. Live OpenAPI needs a network connection but no API key.", "The CLI manages Agent profiles; use the SDK or WebSocket API for a live Omni audio session."] },
     { name: "ci", title: "Use PyAI in a build", description: "Check access and produce an audio artifact with machine-readable output.",
         commands: ["pyai whoami --json", 'pyai speak "Your build is ready" -o build.wav --json', "pyai doctor --json"],
-        notes: ["Set PYAI_API_KEY through the CI secret store; do not put it in source or shell arguments.", "doctor synthesizes and transcribes a sample, which consumes usage. Use whoami for an authentication-only check.", "Install the CLI with npm install -g @pyai/sdk@0.5.0 and pin that version in repeatable builds."] },
-];
+        notes: ["Set PYAI_API_KEY through the CI secret store; do not put it in source or shell arguments.", "doctor synthesizes and transcribes a sample, which consumes usage. Use whoami for an authentication-only check.", "Install the CLI with npm install -g @pyai/sdk@0.6.0 and pin that version in repeatable builds."] },
+].map(recipe => ({ ...recipe, docs_url: "https://pyai.com/agents/speech-calling.md" }));

package/dist/cli-http.js

@@ -234,12 +234,15 @@ export class CliHttp {
         const duration = timeout(options.timeoutMs ?? this.timeoutMs);
         const deadline = Date.now() + duration;
         const abort = new AbortController();
-        const timer = setTimeout(() => abort.abort(new CliError("timeout", `Request timed out after ${duration} ms.`, 4)), duration);
+        const timedOut = () => new CliError("timeout", `Request timed out after ${duration} ms.`, 4);
+        const timer = setTimeout(() => abort.abort(timedOut()), duration);
         const cleanup = () => clearTimeout(timer);
         const retries = method === "GET" || method === "HEAD" ? this.maxRetries : 0;
         let streaming = false;
         try {
             for (let attempt = 0;; attempt++) {
+                if (Date.now() >= deadline)
+                    throw timedOut();
                 let delay = retryDelay(null, attempt);
                 try {
                     const response = await fetch(url, { method, headers, body, signal: abort.signal, redirect: "manual" });
@@ -275,7 +278,13 @@ export class CliHttp {
                     if (abort.signal.aborted || failure.code !== "network_error" || failure.exitCode !== 4 || attempt >= retries)
                         throw failure;
                 }
-                await pause(Math.min(delay, Math.max(0, deadline - Date.now())), abort.signal);
+                const remaining = Math.max(0, deadline - Date.now());
+                const retryExceedsDeadline = delay >= remaining;
+                await pause(Math.min(delay, remaining), abort.signal);
+                // A clipped wait is terminal even if its timer runs before abort.
+                // Otherwise the next request can ignore Retry-After at the deadline.
+                if (retryExceedsDeadline)
+                    throw timedOut();
             }
         }
         finally {

package/dist/cli-init.js

@@ -22,6 +22,8 @@ Read it before generating PyAI calls. Do not place credentials in this file.
 - Canonical live OpenAPI: https://api.pyai.com/openapi.json
 - API docs: https://docs.pyai.com
 - Agent index: https://api.pyai.com/llms.txt
+- Speech and calling recipes: https://pyai.com/agents/speech-calling.md
+- Omni frame contract: https://api.pyai.com/omni-frames.json
 - API origin: https://api.pyai.com; REST routes below include /v1.
 
 CLI schema describes the installed executable; live OpenAPI describes the
@@ -102,7 +104,8 @@ async jobs' language field is a Recap summarization hint.
 The CLI handles REST and job workflows; it does not run a realtime microphone
 or WebSocket session. Use the SDK and protocol docs for Hear streaming or Omni.
 Omni connects to \`wss://api.pyai.com/v1/omni?format=pcm16&rate=24000\`.
-Configure the agent after connection; a managed Agent is optional. Never place
+Use \`pyai.omni.connect({ rate, configure })\`; a managed Agent is optional.
+Wait for configured before non-silent audio and clear playback on barge-in/flush. Never place
 long-lived API keys in a public frontend. Use the documented ephemeral session
 flow for browser apps. Do not add unsupported grounding/Cue fields.
 
@@ -124,7 +127,7 @@ const install = `## Install the CLI
 Install the published CLI with Node.js 22 or newer recommended:
 
 \`\`\`bash
-npm install -g @pyai/sdk@0.5.0
+npm install -g @pyai/sdk@0.6.0
 pyai --version
 \`\`\`
 
@@ -217,7 +220,7 @@ and product calls below are separate explicit steps. Read \`PYAI.md\` first.
 Install the official SDK:
 
 \`\`\`bash
-npm install @pyai/sdk@0.5.0
+npm install @pyai/sdk@0.6.0
 cp .env.example .env
 \`\`\`
 

package/dist/cli-routes.d.ts

@@ -11,5 +11,8 @@ export interface CliRoute {
         success: string[];
         failure: string[];
     };
+    query?: Record<string, "string" | "boolean">;
+    confirm?: boolean;
+    idempotencyRequired?: boolean;
 }
 export declare const routes: CliRoute[];

package/dist/cli-routes.js

@@ -1,4 +1,17 @@
 export const routes = [
+    { command: "omni calls", method: "GET", path: "/v1/omni/calls", query: { "session-label": "string", limit: "string", cursor: "string" }, description: "List Omni sessions including inbound calls. Scope omni:read." },
+    { command: "omni get", method: "GET", path: "/v1/omni/calls/{id}", id: true, description: "Read an Omni call's transcript, summary and recording availability." },
+    { command: "omni summary", method: "GET", path: "/v1/omni/calls/{id}/summary", id: true, description: "Read the structured summary of an Omni session when generated." },
+    { command: "omni transcript", method: "GET", path: "/v1/omni/calls/{id}/transcript", id: true, description: "Read the complete Omni session transcript." },
+    { command: "omni recording", method: "GET", path: "/v1/omni/calls/{id}/recording", id: true, binary: true, description: "Download the recording with --out; recording must have been enabled for this call." },
+    { command: "numbers search", method: "GET", path: "/v1/telephony/available", query: { country: "string", "area-code": "string", contains: "string", limit: "string" }, description: "Search managed numbers; inspect provisioning availability before buying. Scope telephony:manage." },
+    { command: "numbers list", method: "GET", path: "/v1/telephony/numbers", query: { "include-released": "boolean" }, description: "List the organization's managed numbers and current Agent bindings." },
+    { command: "numbers buy", method: "POST", path: "/v1/telephony/numbers", body: true, confirm: true, idempotencyRequired: true, description: "Purchase a number from JSON. Requires --confirm and --idempotency-key; may incur recurring charges." },
+    { command: "numbers bind", method: "POST", path: "/v1/telephony/numbers/{id}/assign", id: true, body: true, description: "Bind an existing number using JSON {agent_id}; null unassigns. Read numbers list first." },
+    { command: "calls list", method: "GET", path: "/v1/telephony/calls", description: "List outbound call requests and their normalized status." },
+    { command: "calls create", method: "POST", path: "/v1/telephony/calls", body: true, confirm: true, idempotencyRequired: true, description: "Dial a real destination from JSON. Requires --confirm and --idempotency-key; this is not a simulated test call." },
+    { command: "calls get", method: "GET", path: "/v1/telephony/calls/{id}", id: true, description: "Get an outbound call by its returned ID; retain artifact identifiers separately." },
+    { command: "calls wait", method: "GET", path: "/v1/telephony/calls/{id}", id: true, wait: { success: ["completed"], failure: ["failed", "canceled", "dispatch_unknown"] }, description: "Wait with a deadline. dispatch_unknown stops polling for manual inspection; never redial automatically." },
     { command: "agents list", method: "GET", path: "/v1/agents", description: "List managed Agent profiles." },
     { command: "agents get", method: "GET", path: "/v1/agents/{id}", id: true, description: "Get an Agent profile." },
     { command: "agents create", method: "POST", path: "/v1/agents", body: true, description: "Create an Agent profile from JSON; name is required." },

package/dist/cli.js

@@ -44,6 +44,7 @@ const commands = [
     { command: "doctor", description: "Diagnose key, catalogs, and a Speak to Hear round-trip" },
     ...routes.map((r) => ({ command: r.command, description: r.description, args: r.id ? ["id"] : [], flags: {
             ...(r.body ? bodyFlags : {}), ...(r.binary ? outputFlags : {}), ...(r.wait ? waitFlags : {}),
+            ...(r.query ?? {}), ...(r.confirm ? { confirm: "boolean" } : {}),
             ...(r.command.endsWith(" list") || r.command === "amd calls" ? { limit: "string", cursor: "string" } : {}),
         } })),
 ];
@@ -404,7 +405,7 @@ async function main() {
         if (flags.json)
             output({ name: "pyai", globals, aliases, short_flags: shortFlags, commands: visible }, flags, undefined, false);
         else if (!spec && !group)
-            process.stdout.write(`PyAI CLI — speech, agents, and automation\n\nStart here\n  pyai login                                 Sign in through your browser\n  pyai speak "Hello from PyAI" -o hello.wav    Turn text into audio\n  pyai hear call.wav --text-only              Print a transcript\n  pyai dub call.wav --from en --to hi -o hi.wav\n                                             Submit, wait, and save dubbed audio\n  pyai init voice-demo --template typescript  Create a starter project offline\n\nDiscover\n  pyai recipes [name]        Copyable workflows\n  pyai help <command>        Command options and examples\n  pyai help all              Every command\n  pyai schema [command] -j   Machine-readable command definitions\n\nGroups\n  auth  profiles  models  voices  agents  jobs  clones  design\n  cast  dub  recap  trace  tools  vocabulary  amd\n\nShortcuts: login, logout, whoami, use, say (speak), hear (transcribe)\nOptions: -o FILE  -f FILE  -t TEXT  -p PROFILE  -j (JSON)\nGlobal: --base-url URL --api-key KEY --timeout SECONDS --retries N --dry-run\nCredentials: pyai login or PYAI_API_KEY. Run pyai doctor for a usage-consuming diagnostic.\n`);
+            process.stdout.write(`PyAI CLI — speech, agents, and automation\n\nStart here\n  pyai login                                 Sign in through your browser\n  pyai speak "Hello from PyAI" -o hello.wav    Turn text into audio\n  pyai hear call.wav --text-only              Print a transcript\n  pyai dub call.wav --from en --to hi -o hi.wav\n                                             Submit, wait, and save dubbed audio\n  pyai init voice-demo --template typescript  Create a starter project offline\n\nDiscover\n  pyai recipes [name]        Copyable workflows\n  pyai help <command>        Command options and examples\n  pyai help all              Every command\n  pyai schema [command] -j   Machine-readable command definitions\n\nGroups\n  auth  profiles  models  voices  agents  jobs  clones  design\n  cast  dub  recap  trace  tools  vocabulary  amd  numbers  calls  omni\n\nShortcuts: login, logout, whoami, use, say (speak), hear (transcribe)\nOptions: -o FILE  -f FILE  -t TEXT  -p PROFILE  -j (JSON)\nGlobal: --base-url URL --api-key KEY --timeout SECONDS --retries N --dry-run\nCredentials: pyai login or PYAI_API_KEY. Run pyai doctor for a usage-consuming diagnostic.\n`);
         else
             process.stdout.write(`PyAI CLI — speech, agents, and automation\n\n${visible.map(c => `  pyai ${c.command}${(c.args ?? []).map(a => c.optionalArgs ? ` [${a}${c.variadic ? "..." : ""}]` : ` <${a}>`).join("")}\n    ${c.description}${c.flags ? `\n    Options: ${Object.keys(c.flags).map(k => `--${k}${c.flags[k] === "boolean" ? "" : " VALUE"}`).join(" ")}` : ""}${c.example ? `\n    ${c.example}` : ""}`).join("\n")}\n\nGlobal: --profile NAME --json --timeout SECONDS --retries N --dry-run\n        --base-url URL --api-key KEY --help --version\nShort flags: -o FILE  -f FILE  -t TEXT  -p PROFILE  -j (JSON)\nAuth: pyai login or PYAI_API_KEY. Discover: pyai schema --json\n`);
         return;
@@ -666,13 +667,21 @@ async function main() {
         return;
     }
     const route = routes.find(r => r.command === cmd);
+    if (route.confirm && !flags.confirm && !flags["dry-run"]) {
+        throw new CliError("needs_human", "Review the request and supply --confirm only after purchase or dialing is authorized.", 2, { docs_url: "https://pyai.com/agents/speech-calling.md", console_url: "https://console.pyai.com/telephony" });
+    }
+    if (route.idempotencyRequired) {
+        const key = required(flags, "idempotency-key");
+        if (!key.trim() || key.length > 255 || /[\r\n]/.test(key))
+            usage("--idempotency-key must be a non-empty header-safe string of at most 255 characters");
+    }
     let path = route.path.replace("{id}", route.id ? safeId(args[0]) : "");
     if (value(flags, "limit") !== undefined) {
         const limit = number(flags, "limit", 20, 1, 100);
         if (!Number.isInteger(limit))
             usage("--limit must be an integer");
     }
-    path = withQuery(path, { limit: value(flags, "limit"), cursor: value(flags, "cursor") });
+    path = withQuery(path, { limit: value(flags, "limit"), cursor: value(flags, "cursor"), ...Object.fromEntries(Object.keys(route.query ?? {}).filter(k => flags[k] !== undefined).map(k => [k.replaceAll("-", "_"), String(flags[k])])) });
     const data = route.body ? await jsonInput(flags, true) : undefined;
     const out = route.binary ? required(flags, "out") : undefined;
     if (out)

package/dist/index.d.ts

@@ -134,8 +134,19 @@ export interface SpeechParams {
      */
     temperature?: number;
 }
-export interface CreateJobParams {
+export type CreateJobParams = CreateJobOptions & ({
     audio_url: string;
+    gpt_live?: never;
+} | {
+    gpt_live: {
+        session_id: string;
+    };
+    audio_url?: never;
+});
+export interface CreateJobOptions {
+    /** Requires Trace entitlement; incompatible with channel/diarize. */
+    trace?: boolean;
+    rule_pack?: Record<string, unknown>;
     model?: string;
     diarize?: boolean;
     channel?: boolean;
@@ -535,6 +546,8 @@ export declare const OmniEvent: {
     readonly Hello: "hello";
     /** Ack for your `configure` frame (echoes the resolved `voice_id`). */
     readonly Configured: "configured";
+    /** Served voice capabilities changed, for example after synthesis fallback. */
+    readonly VoiceCapabilities: "voice_capabilities";
     /** Session is live; includes the resolved agent + audio caps. */
     readonly SessionStarted: "session_started";
     /** Turn boundary (user/assistant speaking). */
@@ -1085,16 +1098,21 @@ export interface AmdCall extends AmdCallSummary {
 }
 /**
  * A mid-call AMD decision event pushed on the stream (and to the per-call
- * TwiML `webhook`). Carries the coarse routing class; the machine subtype
- * (`voicemail`/`ivr`/`screening`/`music`) is on the stored call record
- * (`AmdCall`) and the `amd.call.completed` webhook instead.
+ * TwiML `webhook`). Carries the routing class and an optional machine subtype.
+ * Stored `AmdCall` records fold the subtype into `answered_by`.
  */
 export interface AmdDecisionEvent {
     event?: "amd";
     call_id?: string;
     answered_by?: AmdWireAnsweredBy;
     answered_by_twilio?: string | null;
+    subtype?: string;
+    /** A human or automated answering party was identified. */
+    party_detected?: boolean;
+    /** Classification events return false; detection does not establish recording readiness. */
+    voicemail_ready?: boolean;
     confidence?: number | null;
+    /** Processed inbound audio through the decision, not time since carrier answer. */
     decision_ms?: number | null;
     reason?: string | null;
     [k: string]: unknown;

package/dist/index.js

@@ -286,6 +286,8 @@ export const OmniEvent = {
     Hello: "hello",
     /** Ack for your `configure` frame (echoes the resolved `voice_id`). */
     Configured: "configured",
+    /** Served voice capabilities changed, for example after synthesis fallback. */
+    VoiceCapabilities: "voice_capabilities",
     /** Session is live; includes the resolved agent + audio caps. */
     SessionStarted: "session_started",
     /** Turn boundary (user/assistant speaking). */
@@ -495,6 +497,17 @@ export class OmniConnection {
                 try {
                     const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(1)));
                     if (parsed?.event === OmniEvent.Transcript) {
+                        // The deployed engine also sends this bounded synthesis-input
+                        // advisory. It is not caller ASR or proof that speech was played.
+                        const keys = Object.keys(parsed);
+                        const text = omniTranscriptText(parsed.text);
+                        if (parsed.role === "assistant" && parsed.final === true && text?.trim()
+                            && keys.length === 4
+                            && keys.every((key) => ["event", "role", "text", "final"].includes(key))) {
+                            this.opts.onEvent?.(parsed);
+                            this.opts.onTranscript?.({ event: "transcript", role: "assistant", text, final: true, mode: "replace" });
+                            return;
+                        }
                         this.opts.onError?.(new Error("Omni transcript events must use a binary 0x02 frame"));
                         return;
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyai/sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Official TypeScript/JavaScript SDK for PyAI, speech-to-text (Hear), text-to-speech (Speak), realtime voice agents (Omni), and call compliance (Trace).",
   "type": "module",
   "main": "dist/index.js",

package/src/cli-dx.ts

@@ -7,8 +7,14 @@ export const shortFlags: Record<string, string> = Object.assign(Object.create(nu
   "-h": "--help", "-v": "--version", "-o": "--out", "-f": "--file",
   "-t": "--text", "-p": "--profile", "-j": "--json",
 });
-export interface Recipe { name: string; title: string; description: string; commands: string[]; notes: string[] }
+export interface Recipe { name: string; title: string; description: string; commands: string[]; notes: string[]; docs_url: string }
 export const recipes: Recipe[] = [
+  { name: "calling", title: "Set up a managed phone Agent", description: "Inspect numbers, bind a profile, and retrieve call artifacts through the public API.",
+    commands: ["pyai whoami --json", "pyai numbers list --json", "pyai numbers search --country US --limit 5 --json", "pyai agents list --json", "pyai numbers bind NUMBER_ID --data @binding.json --dry-run --json", "pyai calls create --data @call.json --idempotency-key CALL_REQUEST_KEY --dry-run --json", "pyai calls get RETURNED_CALL_ID --json", "pyai omni get OMNI_CALL_ID --json"],
+    notes: ["Replace all placeholder IDs with returned values. binding.json is {agent_id: RETURNED_AGENT_ID}; call.json requires from_number_id, to, agent_id and use_case from live OpenAPI.", "Remove --dry-run for authorized changes. numbers buy and calls create require --confirm and --idempotency-key. Calls reach real destinations; sandbox keys do not grant telephony permissions.", "Requires telephony:manage; session artifacts require omni:read. Preserve artifacts.omni_call_id. Read the decision tree for purchase, polling, recording, and inbound-call steps.", "Use calls wait ID --wait-timeout 120 --poll-interval 3 --json for bounded waiting. dispatch_unknown requires inspection, never automatic redial."] },
+  { name: "omni", title: "Build a realtime conversation with the SDK", description: "Use the official SDK for binary framing, subprotocol auth, and typed events.",
+    commands: ["pyai schema --openapi --json", "pyai init voice-demo --template typescript", "pyai voices --json"],
+    notes: ["The starter supplies Hear/Speak examples. Add realtime through pyai.omni.connect({ rate, configure }); see the linked decision tree's SDK pattern.", "Wait for configured before non-silent input. Stream paced digital silence during pauses. Read hello.audio_out and clear queued playback on barge_in/flush.", "Browser code uses an ephemeral token minted by omni.createSession on your server. Never put live keys in browser code or URLs.", "Machine framing contract: https://api.pyai.com/omni-frames.json. For an existing Twilio number use @pyai/twilio and the official twilio-omni-voice-agent example."] },
   { name: "auth", title: "Sign in and check access", description: "Save a named profile and inspect the current credential.",
     commands: ["pyai login --profile work", "pyai whoami --profile work --json", "pyai use work"],
     notes: ["Browser login requires the CLI login API and console deployment. Use --no-browser on remote terminals.", "For unattended runs, supply PYAI_API_KEY through the environment. Environment values override saved profiles."] },
@@ -29,5 +35,5 @@ export const recipes: Recipe[] = [
     notes: ["Local schema and recipes work without credentials. Live OpenAPI needs a network connection but no API key.", "The CLI manages Agent profiles; use the SDK or WebSocket API for a live Omni audio session."] },
   { name: "ci", title: "Use PyAI in a build", description: "Check access and produce an audio artifact with machine-readable output.",
     commands: ["pyai whoami --json", 'pyai speak "Your build is ready" -o build.wav --json', "pyai doctor --json"],
-    notes: ["Set PYAI_API_KEY through the CI secret store; do not put it in source or shell arguments.", "doctor synthesizes and transcribes a sample, which consumes usage. Use whoami for an authentication-only check.", "Install the CLI with npm install -g @pyai/sdk@0.5.0 and pin that version in repeatable builds."] },
-];
+    notes: ["Set PYAI_API_KEY through the CI secret store; do not put it in source or shell arguments.", "doctor synthesizes and transcribes a sample, which consumes usage. Use whoami for an authentication-only check.", "Install the CLI with npm install -g @pyai/sdk@0.6.0 and pin that version in repeatable builds."] },
+].map(recipe => ({ ...recipe, docs_url: "https://pyai.com/agents/speech-calling.md" }));

package/src/cli-http.ts

@@ -232,12 +232,14 @@ export class CliHttp {
     const duration = timeout(options.timeoutMs ?? this.timeoutMs);
     const deadline = Date.now() + duration;
     const abort = new AbortController();
-    const timer = setTimeout(() => abort.abort(new CliError("timeout", `Request timed out after ${duration} ms.`, 4)), duration);
+    const timedOut = () => new CliError("timeout", `Request timed out after ${duration} ms.`, 4);
+    const timer = setTimeout(() => abort.abort(timedOut()), duration);
     const cleanup = () => clearTimeout(timer);
     const retries = method === "GET" || method === "HEAD" ? this.maxRetries : 0;
     let streaming = false;
     try {
       for (let attempt = 0; ; attempt++) {
+        if (Date.now() >= deadline) throw timedOut();
         let delay = retryDelay(null, attempt);
         try {
           const response = await fetch(url, { method, headers, body, signal: abort.signal, redirect: "manual" });
@@ -264,7 +266,12 @@ export class CliHttp {
           const failure = this.transportError(error, abort.signal);
           if (abort.signal.aborted || failure.code !== "network_error" || failure.exitCode !== 4 || attempt >= retries) throw failure;
         }
-        await pause(Math.min(delay, Math.max(0, deadline - Date.now())), abort.signal);
+        const remaining = Math.max(0, deadline - Date.now());
+        const retryExceedsDeadline = delay >= remaining;
+        await pause(Math.min(delay, remaining), abort.signal);
+        // A clipped wait is terminal even if its timer runs before abort.
+        // Otherwise the next request can ignore Retry-After at the deadline.
+        if (retryExceedsDeadline) throw timedOut();
       }
     } finally {
       if (!streaming) cleanup();

package/src/cli-init.ts

@@ -43,6 +43,8 @@ Read it before generating PyAI calls. Do not place credentials in this file.
 - Canonical live OpenAPI: https://api.pyai.com/openapi.json
 - API docs: https://docs.pyai.com
 - Agent index: https://api.pyai.com/llms.txt
+- Speech and calling recipes: https://pyai.com/agents/speech-calling.md
+- Omni frame contract: https://api.pyai.com/omni-frames.json
 - API origin: https://api.pyai.com; REST routes below include /v1.
 
 CLI schema describes the installed executable; live OpenAPI describes the
@@ -123,7 +125,8 @@ async jobs' language field is a Recap summarization hint.
 The CLI handles REST and job workflows; it does not run a realtime microphone
 or WebSocket session. Use the SDK and protocol docs for Hear streaming or Omni.
 Omni connects to \`wss://api.pyai.com/v1/omni?format=pcm16&rate=24000\`.
-Configure the agent after connection; a managed Agent is optional. Never place
+Use \`pyai.omni.connect({ rate, configure })\`; a managed Agent is optional.
+Wait for configured before non-silent audio and clear playback on barge-in/flush. Never place
 long-lived API keys in a public frontend. Use the documented ephemeral session
 flow for browser apps. Do not add unsupported grounding/Cue fields.
 
@@ -146,7 +149,7 @@ const install = `## Install the CLI
 Install the published CLI with Node.js 22 or newer recommended:
 
 \`\`\`bash
-npm install -g @pyai/sdk@0.5.0
+npm install -g @pyai/sdk@0.6.0
 pyai --version
 \`\`\`
 
@@ -239,7 +242,7 @@ and product calls below are separate explicit steps. Read \`PYAI.md\` first.
 Install the official SDK:
 
 \`\`\`bash
-npm install @pyai/sdk@0.5.0
+npm install @pyai/sdk@0.6.0
 cp .env.example .env
 \`\`\`
 

package/src/cli-routes.ts

@@ -8,9 +8,25 @@ export interface CliRoute {
   id?: boolean;
   binary?: boolean;
   wait?: { success: string[]; failure: string[] };
+  query?: Record<string, "string" | "boolean">;
+  confirm?: boolean;
+  idempotencyRequired?: boolean;
 }
 
 export const routes: CliRoute[] = [
+  { command: "omni calls", method: "GET", path: "/v1/omni/calls", query: { "session-label": "string", limit: "string", cursor: "string" }, description: "List Omni sessions including inbound calls. Scope omni:read." },
+  { command: "omni get", method: "GET", path: "/v1/omni/calls/{id}", id: true, description: "Read an Omni call's transcript, summary and recording availability." },
+  { command: "omni summary", method: "GET", path: "/v1/omni/calls/{id}/summary", id: true, description: "Read the structured summary of an Omni session when generated." },
+  { command: "omni transcript", method: "GET", path: "/v1/omni/calls/{id}/transcript", id: true, description: "Read the complete Omni session transcript." },
+  { command: "omni recording", method: "GET", path: "/v1/omni/calls/{id}/recording", id: true, binary: true, description: "Download the recording with --out; recording must have been enabled for this call." },
+  { command: "numbers search", method: "GET", path: "/v1/telephony/available", query: { country: "string", "area-code": "string", contains: "string", limit: "string" }, description: "Search managed numbers; inspect provisioning availability before buying. Scope telephony:manage." },
+  { command: "numbers list", method: "GET", path: "/v1/telephony/numbers", query: { "include-released": "boolean" }, description: "List the organization's managed numbers and current Agent bindings." },
+  { command: "numbers buy", method: "POST", path: "/v1/telephony/numbers", body: true, confirm: true, idempotencyRequired: true, description: "Purchase a number from JSON. Requires --confirm and --idempotency-key; may incur recurring charges." },
+  { command: "numbers bind", method: "POST", path: "/v1/telephony/numbers/{id}/assign", id: true, body: true, description: "Bind an existing number using JSON {agent_id}; null unassigns. Read numbers list first." },
+  { command: "calls list", method: "GET", path: "/v1/telephony/calls", description: "List outbound call requests and their normalized status." },
+  { command: "calls create", method: "POST", path: "/v1/telephony/calls", body: true, confirm: true, idempotencyRequired: true, description: "Dial a real destination from JSON. Requires --confirm and --idempotency-key; this is not a simulated test call." },
+  { command: "calls get", method: "GET", path: "/v1/telephony/calls/{id}", id: true, description: "Get an outbound call by its returned ID; retain artifact identifiers separately." },
+  { command: "calls wait", method: "GET", path: "/v1/telephony/calls/{id}", id: true, wait: { success: ["completed"], failure: ["failed", "canceled", "dispatch_unknown"] }, description: "Wait with a deadline. dispatch_unknown stops polling for manual inspection; never redial automatically." },
   { command: "agents list", method: "GET", path: "/v1/agents", description: "List managed Agent profiles." },
   { command: "agents get", method: "GET", path: "/v1/agents/{id}", id: true, description: "Get an Agent profile." },
   { command: "agents create", method: "POST", path: "/v1/agents", body: true, description: "Create an Agent profile from JSON; name is required." },

package/src/cli.ts

@@ -48,6 +48,7 @@ const commands: Command[] = [
   { command: "doctor", description: "Diagnose key, catalogs, and a Speak to Hear round-trip" },
   ...routes.map((r): Command => ({ command: r.command, description: r.description, args: r.id ? ["id"] : [], flags: {
     ...(r.body ? bodyFlags : {}), ...(r.binary ? outputFlags : {}), ...(r.wait ? waitFlags : {}),
+    ...(r.query ?? {}), ...(r.confirm ? { confirm: "boolean" as const } : {}),
     ...(r.command.endsWith(" list") || r.command === "amd calls" ? { limit: "string" as const, cursor: "string" as const } : {}),
   } })),
 ];
@@ -269,7 +270,7 @@ async function main(): Promise<void> {
     const grouped = group ? commands.filter(c => c.command.startsWith(`${group} `)) : commands;
     const visible = spec ? [spec, ...commands.filter(c => c.command.startsWith(`${spec.command} `))] : grouped.length ? grouped : commands;
     if (flags.json) output({ name: "pyai", globals, aliases, short_flags: shortFlags, commands: visible }, flags, undefined, false);
-    else if (!spec && !group) process.stdout.write(`PyAI CLI — speech, agents, and automation\n\nStart here\n  pyai login                                 Sign in through your browser\n  pyai speak "Hello from PyAI" -o hello.wav    Turn text into audio\n  pyai hear call.wav --text-only              Print a transcript\n  pyai dub call.wav --from en --to hi -o hi.wav\n                                             Submit, wait, and save dubbed audio\n  pyai init voice-demo --template typescript  Create a starter project offline\n\nDiscover\n  pyai recipes [name]        Copyable workflows\n  pyai help <command>        Command options and examples\n  pyai help all              Every command\n  pyai schema [command] -j   Machine-readable command definitions\n\nGroups\n  auth  profiles  models  voices  agents  jobs  clones  design\n  cast  dub  recap  trace  tools  vocabulary  amd\n\nShortcuts: login, logout, whoami, use, say (speak), hear (transcribe)\nOptions: -o FILE  -f FILE  -t TEXT  -p PROFILE  -j (JSON)\nGlobal: --base-url URL --api-key KEY --timeout SECONDS --retries N --dry-run\nCredentials: pyai login or PYAI_API_KEY. Run pyai doctor for a usage-consuming diagnostic.\n`);
+    else if (!spec && !group) process.stdout.write(`PyAI CLI — speech, agents, and automation\n\nStart here\n  pyai login                                 Sign in through your browser\n  pyai speak "Hello from PyAI" -o hello.wav    Turn text into audio\n  pyai hear call.wav --text-only              Print a transcript\n  pyai dub call.wav --from en --to hi -o hi.wav\n                                             Submit, wait, and save dubbed audio\n  pyai init voice-demo --template typescript  Create a starter project offline\n\nDiscover\n  pyai recipes [name]        Copyable workflows\n  pyai help <command>        Command options and examples\n  pyai help all              Every command\n  pyai schema [command] -j   Machine-readable command definitions\n\nGroups\n  auth  profiles  models  voices  agents  jobs  clones  design\n  cast  dub  recap  trace  tools  vocabulary  amd  numbers  calls  omni\n\nShortcuts: login, logout, whoami, use, say (speak), hear (transcribe)\nOptions: -o FILE  -f FILE  -t TEXT  -p PROFILE  -j (JSON)\nGlobal: --base-url URL --api-key KEY --timeout SECONDS --retries N --dry-run\nCredentials: pyai login or PYAI_API_KEY. Run pyai doctor for a usage-consuming diagnostic.\n`);
     else process.stdout.write(`PyAI CLI — speech, agents, and automation\n\n${visible.map(c => `  pyai ${c.command}${(c.args ?? []).map(a => c.optionalArgs ? ` [${a}${c.variadic ? "..." : ""}]` : ` <${a}>`).join("")}\n    ${c.description}${c.flags ? `\n    Options: ${Object.keys(c.flags).map(k => `--${k}${c.flags![k] === "boolean" ? "" : " VALUE"}`).join(" ")}` : ""}${c.example ? `\n    ${c.example}` : ""}`).join("\n")}\n\nGlobal: --profile NAME --json --timeout SECONDS --retries N --dry-run\n        --base-url URL --api-key KEY --help --version\nShort flags: -o FILE  -f FILE  -t TEXT  -p PROFILE  -j (JSON)\nAuth: pyai login or PYAI_API_KEY. Discover: pyai schema --json\n`);
     return;
   }
@@ -436,9 +437,16 @@ async function main(): Promise<void> {
     output(await http.json("GET", path, { auth: cmd !== "schema" }), flags, undefined, cmd !== "schema"); return;
   }
   const route = routes.find(r => r.command === cmd)!;
+  if (route.confirm && !flags.confirm && !flags["dry-run"]) {
+    throw new CliError("needs_human", "Review the request and supply --confirm only after purchase or dialing is authorized.", 2, { docs_url: "https://pyai.com/agents/speech-calling.md", console_url: "https://console.pyai.com/telephony" });
+  }
+  if (route.idempotencyRequired) {
+    const key = required(flags, "idempotency-key");
+    if (!key.trim() || key.length > 255 || /[\r\n]/.test(key)) usage("--idempotency-key must be a non-empty header-safe string of at most 255 characters");
+  }
   let path = route.path.replace("{id}", route.id ? safeId(args[0]!) : "");
   if (value(flags, "limit") !== undefined) { const limit = number(flags, "limit", 20, 1, 100); if (!Number.isInteger(limit)) usage("--limit must be an integer"); }
-  path = withQuery(path, { limit: value(flags, "limit"), cursor: value(flags, "cursor") });
+  path = withQuery(path, { limit: value(flags, "limit"), cursor: value(flags, "cursor"), ...Object.fromEntries(Object.keys(route.query ?? {}).filter(k => flags[k] !== undefined).map(k => [k.replaceAll("-", "_"), String(flags[k])])) });
   const data = route.body ? await jsonInput(flags, true) : undefined;
   const out = route.binary ? required(flags, "out") : undefined;
   if (out) await checkOutput(out, flags);

package/src/index.ts

@@ -165,8 +165,15 @@ function assertActiveSpeechParams(params: SpeechParams): void {
   }
 }
 
-export interface CreateJobParams {
-  audio_url: string;
+export type CreateJobParams = CreateJobOptions & (
+  | { audio_url: string; gpt_live?: never }
+  | { gpt_live: { session_id: string }; audio_url?: never }
+);
+
+export interface CreateJobOptions {
+  /** Requires Trace entitlement; incompatible with channel/diarize. */
+  trace?: boolean;
+  rule_pack?: Record<string, unknown>;
   model?: string;
   diarize?: boolean;
   channel?: boolean;
@@ -731,6 +738,8 @@ export const OmniEvent = {
   Hello: "hello",
   /** Ack for your `configure` frame (echoes the resolved `voice_id`). */
   Configured: "configured",
+  /** Served voice capabilities changed, for example after synthesis fallback. */
+  VoiceCapabilities: "voice_capabilities",
   /** Session is live; includes the resolved agent + audio caps. */
   SessionStarted: "session_started",
   /** Turn boundary (user/assistant speaking). */
@@ -1066,6 +1075,17 @@ export class OmniConnection {
         try {
           const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(1))) as OmniServerFrame;
           if (parsed?.event === OmniEvent.Transcript) {
+            // The deployed engine also sends this bounded synthesis-input
+            // advisory. It is not caller ASR or proof that speech was played.
+            const keys = Object.keys(parsed);
+            const text = omniTranscriptText(parsed.text);
+            if (parsed.role === "assistant" && parsed.final === true && text?.trim()
+              && keys.length === 4
+              && keys.every((key) => ["event", "role", "text", "final"].includes(key))) {
+              this.opts.onEvent?.(parsed);
+              this.opts.onTranscript?.({ event: "transcript", role: "assistant", text, final: true, mode: "replace" });
+              return;
+            }
             this.opts.onError?.(new Error("Omni transcript events must use a binary 0x02 frame"));
             return;
           }
@@ -1593,16 +1613,21 @@ export interface AmdCall extends AmdCallSummary {
 
 /**
  * A mid-call AMD decision event pushed on the stream (and to the per-call
- * TwiML `webhook`). Carries the coarse routing class; the machine subtype
- * (`voicemail`/`ivr`/`screening`/`music`) is on the stored call record
- * (`AmdCall`) and the `amd.call.completed` webhook instead.
+ * TwiML `webhook`). Carries the routing class and an optional machine subtype.
+ * Stored `AmdCall` records fold the subtype into `answered_by`.
  */
 export interface AmdDecisionEvent {
   event?: "amd";
   call_id?: string;
   answered_by?: AmdWireAnsweredBy;
   answered_by_twilio?: string | null;
+  subtype?: string;
+  /** A human or automated answering party was identified. */
+  party_detected?: boolean;
+  /** Classification events return false; detection does not establish recording readiness. */
+  voicemail_ready?: boolean;
   confidence?: number | null;
+  /** Processed inbound audio through the decision, not time since carrier answer. */
   decision_ms?: number | null;
   reason?: string | null;
   [k: string]: unknown;