@pyai/sdk 0.4.0 → 0.6.0

package/src/cli-init.ts

@@ -0,0 +1,433 @@
+import { constants, type Stats } from "node:fs";
+import fs from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, parse, resolve } from "node:path";
+
+export type CliTemplate = "agent" | "typescript" | "python";
+export interface CliTemplateManifest {
+  id: CliTemplate;
+  description: string;
+  files: readonly string[];
+}
+export interface ScaffoldOptions {
+  directory: string;
+  template?: CliTemplate;
+  dryRun?: boolean;
+  cwd?: string;
+}
+export interface ScaffoldResult {
+  directory: string;
+  template: CliTemplate;
+  files: string[];
+  created: boolean;
+  next_steps: string[];
+}
+export class CliInitError extends Error {
+  readonly code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "CliInitError";
+    this.code = code;
+  }
+}
+
+const context = `# Build with PyAI
+
+This file is a project-local API integration guide for engineers and coding agents.
+Read it before generating PyAI calls. Do not place credentials in this file.
+
+## Discover the contract
+
+- Run \`pyai schema --json\` for the installed CLI's offline commands, flags,
+  routes, output conventions, and exit codes.
+- Run \`pyai schema --openapi --json\` to retrieve the deployed API contract.
+- 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
+currently deployed API. Verify live fields before building a new integration.
+Use \`pyai request METHOD /v1/path --data @request.json --json\` for JSON routes
+that do not yet have a dedicated command. Do not invent endpoint aliases.
+
+## Authentication and secrets
+
+For human use: \`pyai auth login\` opens browser approval; add \`--no-browser\`
+for SSH. Match the terminal code, select a project, and approve. Browser login
+requires the matching backend and console deployment. Use an existing key
+through \`PYAI_API_KEY\` when web login is unavailable.
+
+For unattended agents and CI: inject \`PYAI_API_KEY\` from a secret manager.
+\`pyai auth sandbox --profile sandbox\` creates a separate sandbox organization
+and saves its key locally; each invocation creates a new organization.
+Inspect \`pyai auth status --json\` before making product calls. Sandbox scopes,
+limits, and expiry come from the returned metadata; live calls may incur usage.
+
+Keys are opaque strings. Never parse them, print them, commit them, put them in
+URLs, expose them in browser code, or include them in prompts or issue reports.
+Use the bearer Authorization header for server-side REST. CLI profiles are
+plaintext private local files; SDK examples read the environment and do not
+read CLI profiles. An exported PYAI_API_KEY overrides the CLI's saved profile.
+\`auth logout\` removes a local profile; revoke the key in the console separately.
+
+## Canonical operations
+
+| Task | API | CLI |
+| --- | --- | --- |
+| List voices | GET /v1/voices | pyai voices --json |
+| List models | GET /v1/models | pyai models --json |
+| Speak | POST /v1/audio/speech | pyai speak --text-file message.txt --out speech.wav --json |
+| Hear, local audio | POST /v1/audio/transcriptions (multipart file) | pyai transcribe --file recording.wav --json |
+| Transcription jobs | POST/GET /v1/transcription/jobs | pyai transcribe --url HTTPS_URL --wait --json |
+| Managed Agents | /v1/agents | pyai agents list --json |
+| Voice cloning | /v1/voice/clones | pyai clones list --json |
+| Voice design | /v1/voice/design | pyai design --help |
+| Cast | /v1/cast/* | pyai cast --help |
+| Dub | POST /v1/dub; /v1/dub/jobs/{job_id} | pyai dub --help |
+| Hear vocabulary | GET/PUT /v1/hear/vocabulary | pyai vocabulary --help |
+
+Speak uses model \`pyai-speak\`, input text, and a voice from the catalog;
+\`alloy\` is an accepted compatibility voice. The speech example requests WAV
+and buffered delivery. Hear uses multipart file upload and model \`pyai-hear\`.
+Never send local filesystem paths as remote audio URLs. Request examples use
+placeholder HTTPS URLs: replace them with accessible audio you are authorized
+to process before submission. Synchronous Hear's language is an STT hint;
+async jobs' language field is a Recap summarization hint.
+
+## Files, jobs, retries, and errors
+
+- Prefer \`--json\` for automation. Success is stdout, structured errors are
+  stderr, and the process exits nonzero on failure. Browser login may emit a
+  public authorization event to stderr while waiting for approval.
+- Audio is binary. Use \`--out audio.wav --json\` for an output receipt, or
+  \`--out -\` for a binary pipe without \`--json\`. Output files are protected
+  from overwrites unless the user explicitly requests \`--force\`.
+- Preview supported calls with \`--dry-run --json\`; this does not prove that
+  a deployed API accepts a payload or that the key has permission.
+- Use \`--wait --wait-timeout 300\` when creating URL transcription jobs, or
+  \`pyai jobs wait JOB_ID --wait-timeout 300 --json\` to resume bounded polling.
+  A local timeout does not cancel a server-side job. Save the returned job ID.
+- Reuse an \`--idempotency-key\` for retries of the same operation only on
+  routes whose live contract supports it (for example transcription jobs).
+  Do not assume every POST is idempotent or automatically repeat billable
+  calls after an ambiguous network failure. These SDK starters disable
+  automatic retries; deliberately decide whether a failed call is safe to repeat.
+- Read structured error codes, HTTP status, and request IDs. Fix 400 input,
+  401 authentication, 403 scope, and 402 credit errors before retrying. Honor
+  Retry-After on 429 responses and use bounded backoff for safe operations.
+- Keep project boundaries explicit. Use the intended \`--profile NAME\` and
+  verify its organization/project through auth status before changing resources.
+
+## Realtime is an SDK/application workflow
+
+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\`.
+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.
+
+## Suggested workflow
+
+1. Read this file and inspect CLI/schema help.
+2. Authenticate, inspect the intended project, and choose catalog voice IDs.
+3. Preview a request, then run one small product call with authorized input.
+4. Save useful job IDs and request IDs; keep generated audio and secrets out of git.
+5. Add bounded error handling and tests before expanding the integration.
+`;
+
+const speech = `${JSON.stringify({ model: "pyai-speak", input: "Hello from PyAI.", voice: "alloy", response_format: "wav", stream: false }, null, 2)}\n`;
+const job = `${JSON.stringify({ audio_url: "https://example.com/replace-with-your-recording.wav", model: "pyai-hear", output_formats: ["json", "srt"] }, null, 2)}\n`;
+const agent = `${JSON.stringify({ name: "Support assistant", persona_system_prompt: "Help the caller clearly and briefly. Ask one question at a time.", greeting: "Hello, how can I help you?", voice_id: "stock_emma_en_gb", language: "en" }, null, 2)}\n`;
+const env = "# Set locally or inject through your secret manager. Never commit the real key.\nPYAI_API_KEY=\nPYAI_BASE_URL=https://api.pyai.com\nPYAI_VOICE=alloy\n";
+const ignore = ".env\n.env.*\n!.env.example\nnode_modules/\n.venv/\n__pycache__/\n*.pyc\n*.wav\n*.mp3\n*.raw\ntranscript.json\n";
+const install = `## Install the CLI
+
+Install the published CLI with Node.js 22 or newer recommended:
+
+\`\`\`bash
+npm install -g @pyai/sdk@0.6.0
+pyai --version
+\`\`\`
+
+The Python SDK can also provide a command named pyai. Check
+\`pyai --version\` and \`pyai schema --json\` to confirm this executable.
+For development, build with \`npm ci && npm run build\` in the platform's
+sdk/typescript directory and run \`node dist/cli.js\` explicitly.
+
+Use \`pyai login\` for browser sign-in (or \`pyai login --no-browser\`
+over SSH). For automation, inject \`PYAI_API_KEY\` and verify
+\`pyai whoami --json\`.
+`;
+const agentReadme = `# PyAI agent starter
+
+This project contains API context and editable JSON requests. Initialization
+is offline: it creates files only and does not install packages, authenticate,
+create an organization, or make a product call.
+
+${install}
+## Make the first calls
+
+\`\`\`bash
+pyai schema --json
+pyai voices --json
+pyai request POST /v1/audio/speech --data @speech.json --out hello.wav --dry-run --json
+pyai request POST /v1/audio/speech --data @speech.json --out hello.wav --json
+pyai transcribe --file hello.wav --json
+\`\`\`
+
+Edit \`job.json\` to use an accessible HTTPS recording URL, then submit a job
+with \`pyai jobs create --data @job.json --json\`. Wait on its returned ID with
+\`pyai jobs wait JOB_ID --wait-timeout 300 --json\`.
+
+Edit \`agent.json\` for your use case and confirm the voice in the live catalog.
+Preview it with \`pyai agents create --data @agent.json --dry-run --json\`, then
+remove \`--dry-run\` to create a managed Agent profile. This creates a profile;
+use the SDK and Omni protocol docs to build the realtime application.
+
+Point Cursor, Claude Code, Codex, or another coding agent at \`PYAI.md\`.
+Inspect the installed command schema instead of guessing flags or endpoints.
+`;
+const tsMain = `import { open, readFile, unlink } from "node:fs/promises";
+import { basename } from "node:path";
+import { PyAI, PyAIError } from "@pyai/sdk";
+
+async function main() {
+  const [command, input, output = "hello.wav"] = process.argv.slice(2);
+  if ((command !== "speak" && command !== "hear") || !input) {
+    throw new Error('Usage: npm run speak -- "Hello" [hello.wav] OR npm run hear -- recording.wav');
+  }
+  const apiKey = process.env.PYAI_API_KEY;
+  if (!apiKey) throw new Error("Set PYAI_API_KEY in your environment or ignored .env file.");
+  const client = new PyAI({ apiKey, baseURL: process.env.PYAI_BASE_URL || "https://api.pyai.com", maxRetries: 0 });
+  if (command === "speak") {
+    // Reserve a new private output before making a billable request.
+    const file = await open(output, "wx", 0o600);
+    try {
+      const audio = await client.audio.speech({ input, voice: process.env.PYAI_VOICE || "alloy", response_format: "wav", stream: false });
+      await file.writeFile(new Uint8Array(audio));
+    } catch (error) {
+      await file.close();
+      await unlink(output);
+      throw error;
+    }
+    await file.close();
+    process.stdout.write(JSON.stringify({ output }) + "\\n");
+  } else {
+    const bytes = await readFile(input);
+    const result = await client.audio.transcriptions.create({ file: new Blob([bytes]), filename: basename(input), model: "pyai-hear" });
+    process.stdout.write(JSON.stringify(result) + "\\n");
+  }
+}
+
+main().catch((error: unknown) => {
+  // API error messages can reflect request contents; report stable metadata only.
+  const detail = error instanceof PyAIError
+    ? { code: error.code, status: error.status, request_id: error.requestId }
+    : { code: "local_error", message: error instanceof Error && (error.message.startsWith("Usage:") || error.message.startsWith("Set PYAI_API_KEY")) ? error.message : "Check input/output paths and permissions; existing output files are refused." };
+  process.stderr.write(JSON.stringify({ error: detail }) + "\\n");
+  process.exitCode = 1;
+});
+`;
+const tsReadme = `# PyAI TypeScript starter
+
+Requires Node.js 22.6+ and npm. Initialization is offline; dependency installation
+and product calls below are separate explicit steps. Read \`PYAI.md\` first.
+
+## Install the SDK and configure the environment
+
+Install the official SDK:
+
+\`\`\`bash
+npm install @pyai/sdk@0.6.0
+cp .env.example .env
+\`\`\`
+
+Put your key in the ignored \`.env\`, or inject it through a secret manager.
+These scripts read the environment and do not read credentials saved by
+\`pyai login\`.
+An existing environment variable takes precedence over values in \`.env\`.
+
+## Speak, then Hear
+
+\`\`\`bash
+npm run speak -- "Hello from PyAI." hello.wav
+npm run hear -- hello.wav
+\`\`\`
+
+Speak reserves a new private output file and refuses to overwrite existing
+files. Hear uploads a local audio file and prints JSON. Both make real API
+calls and use your key's scopes, limits, and billing. Automatic SDK retries are
+disabled to avoid repeating ambiguous product calls. Extend \`main.ts\` after
+checking the live contract; add bounded timeouts for your application's needs.
+
+${install}`;
+const pythonMain = `import json
+import os
+from pathlib import Path
+import sys
+
+from pyai import PyAI, PyAIError
+
+
+def main():
+    args = sys.argv[1:]
+    if len(args) < 2 or args[0] not in ("speak", "hear"):
+        raise ValueError('Usage: python main.py speak "Hello" [hello.wav] OR python main.py hear recording.wav')
+    api_key = os.environ.get("PYAI_API_KEY")
+    if not api_key:
+        raise ValueError("Set PYAI_API_KEY in your environment.")
+    with PyAI(api_key=api_key, base_url=os.environ.get("PYAI_BASE_URL") or "https://api.pyai.com", max_retries=0, timeout=60) as client:
+        if args[0] == "speak":
+            output = Path(args[2] if len(args) > 2 else "hello.wav")
+            # Exclusive creation reserves the path before a billable request.
+            descriptor = os.open(output, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            try:
+                with os.fdopen(descriptor, "wb") as target:
+                    audio = client.audio.speech(input=args[1], voice=os.environ.get("PYAI_VOICE") or "alloy", response_format="wav")
+                    target.write(audio)
+            except Exception:
+                output.unlink(missing_ok=True)
+                raise
+            print(json.dumps({"output": str(output)}))
+        else:
+            with open(args[1], "rb") as source:
+                result = client.audio.transcriptions.create(file=source, filename=Path(args[1]).name, model="pyai-hear")
+            print(json.dumps(result))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except PyAIError as error:
+        print(json.dumps({"error": {"code": error.code, "status": error.status, "request_id": error.request_id}}), file=sys.stderr)
+        sys.exit(1)
+    except (OSError, ValueError) as error:
+        message = str(error) if isinstance(error, ValueError) and (str(error).startswith("Usage:") or str(error).startswith("Set PYAI_API_KEY")) else "Check input/output paths and permissions; existing output files are refused."
+        print(json.dumps({"error": {"code": "local_error", "message": message}}), file=sys.stderr)
+        sys.exit(1)
+`;
+const pythonReadme = `# PyAI Python starter
+
+Requires Python 3.9+. Initialization is offline. Dependency installation and
+product calls below are separate explicit steps. Read \`PYAI.md\` first.
+
+## Install the SDK and configure the environment
+
+Create a virtual environment with \`python3 -m venv .venv\`, activate it using
+your shell's normal command, and install the matching SDK checkout:
+
+\`\`\`bash
+python -m pip install /absolute/path/to/platform/sdk/python
+\`\`\`
+
+Inject \`PYAI_API_KEY\` through your secret manager or shell environment. The
+\`.env.example\` file documents supported variables; this script deliberately
+does not load .env files or read credentials saved by \`pyai auth login\`.
+Do not paste a real key into shell history or source control.
+
+## Speak, then Hear
+
+\`\`\`bash
+python main.py speak "Hello from PyAI." hello.wav
+python main.py hear hello.wav
+\`\`\`
+
+Speak creates a new private file and refuses existing output paths. Hear
+uploads a local file and prints JSON. Calls use your key's scopes, limits,
+and billing. The SDK timeout is 60 seconds and automatic retries are disabled.
+Check the live contract before expanding the example.
+
+${install}`;
+
+const content: Readonly<Record<CliTemplate, Readonly<Record<string, string>>>> = Object.freeze({
+  agent: Object.freeze({ "README.md": agentReadme, "PYAI.md": context, "speech.json": speech, "job.json": job, "agent.json": agent, ".env.example": env, ".gitignore": ignore }),
+  typescript: Object.freeze({ "README.md": tsReadme, "PYAI.md": context, "main.ts": tsMain, "package.json": JSON.stringify({ name: "pyai-starter", version: "0.0.0", private: true, type: "module", engines: { node: ">=22.6.0" }, scripts: { speak: "node --experimental-strip-types --env-file=.env main.ts speak", hear: "node --experimental-strip-types --env-file=.env main.ts hear" } }, null, 2) + "\n", ".env.example": env, ".gitignore": ignore }),
+  python: Object.freeze({ "README.md": pythonReadme, "PYAI.md": context, "main.py": pythonMain, ".env.example": env, ".gitignore": ignore }),
+});
+
+/** Offline discovery; file contents are static and never include local credentials. */
+export const CLI_TEMPLATES: readonly CliTemplateManifest[] = Object.freeze(([
+  { id: "agent", description: "API context and JSON requests for coding agents" },
+  { id: "typescript", description: "Runnable Node.js Speak and Hear examples using @pyai/sdk" },
+  { id: "python", description: "Runnable Python Speak and Hear examples using pyai-sdk" },
+] as const).map((entry) => Object.freeze({ ...entry, files: Object.freeze(Object.keys(content[entry.id])) })));
+
+function hasCode(error: unknown, code: string): boolean {
+  return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+function sameFile(a: Stats, b: Stats): boolean { return a.dev === b.dev && a.ino === b.ino; }
+async function exists(path: string): Promise<boolean> {
+  try { await fs.lstat(path); return true; }
+  catch (error) { if (hasCode(error, "ENOENT")) return false; throw error; }
+}
+
+/** Create a new project only. Never authenticates, installs packages, or runs a shell. */
+export async function scaffoldProject(options: ScaffoldOptions): Promise<ScaffoldResult> {
+  const template = options.template ?? "agent";
+  if (!Object.hasOwn(content, template)) throw new CliInitError("invalid_template", "Choose agent, typescript, or python with --template.");
+  if (typeof options.directory !== "string" || !options.directory.trim() || /[\p{Cc}]/u.test(options.directory)) {
+    throw new CliInitError("invalid_directory", "Provide a new project directory without control characters.");
+  }
+  const requested = resolve(options.cwd ?? process.cwd(), options.directory);
+  if (requested === parse(requested).root) throw new CliInitError("invalid_directory", "The filesystem root cannot be a project destination.");
+  let directory: string;
+  try {
+    if (await exists(requested)) throw new CliInitError("destination_exists", "The destination already exists. Choose a new directory; existing directories, files, and symbolic links are never overwritten.");
+    // Resolve parent aliases once (including platform aliases such as /tmp),
+    // then use the canonical path consistently for creation and rollback.
+    const parent = await fs.realpath(dirname(requested));
+    if (!(await fs.lstat(parent)).isDirectory()) throw new CliInitError("invalid_directory", "The destination parent must be an existing directory.");
+    directory = join(parent, basename(requested));
+  } catch (error) {
+    if (error instanceof CliInitError) throw error;
+    throw new CliInitError("invalid_directory", "The destination parent must exist and be accessible. Create parent directories first.");
+  }
+  const entries = Object.entries(content[template]);
+  for (const [file] of entries) {
+    if (isAbsolute(file) || basename(file) !== file || file === "." || file === "..") throw new CliInitError("invalid_template", "The template contains an unsafe file path.");
+  }
+  const result: ScaffoldResult = {
+    directory, template, files: entries.map(([file]) => file), created: !options.dryRun,
+    next_steps: ["Open README.md in the created project for setup and examples.", "Give PYAI.md to your coding agent before building against the API.", "Inspect available commands with pyai schema --json."],
+  };
+  if (options.dryRun) return result;
+
+  let ownedDirectory: Stats | undefined;
+  const ownedFiles: Array<{ path: string; stat: Stats }> = [];
+  try {
+    await fs.mkdir(directory, { mode: 0o700 });
+    ownedDirectory = await fs.lstat(directory);
+    if (!ownedDirectory.isDirectory() || ownedDirectory.isSymbolicLink()) throw new Error("Destination changed");
+    for (const [name, text] of entries) {
+      const current = await fs.lstat(directory);
+      if (!current.isDirectory() || current.isSymbolicLink() || !sameFile(current, ownedDirectory)) throw new Error("Destination changed");
+      const path = join(directory, name);
+      const file = await fs.open(path, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | (constants.O_NOFOLLOW ?? 0), 0o600);
+      try {
+        ownedFiles.push({ path, stat: await file.stat() });
+        await file.writeFile(text, "utf8");
+      } finally { await file.close(); }
+    }
+    return result;
+  } catch (error) {
+    // No recursive delete: remove only exact files created by this invocation.
+    // Preserve another process's additions or replacements, even during failure.
+    if (ownedDirectory) {
+      try {
+        const current = await fs.lstat(directory);
+        if (current.isDirectory() && !current.isSymbolicLink() && sameFile(current, ownedDirectory)) {
+          for (const owned of ownedFiles.reverse()) {
+            try { if (sameFile(await fs.lstat(owned.path), owned.stat)) await fs.unlink(owned.path); } catch { /* preserve unknown paths */ }
+          }
+          await fs.rmdir(directory).catch(() => undefined);
+        }
+      } catch { /* no longer our destination */ }
+    }
+    if (hasCode(error, "EEXIST") && !ownedDirectory) throw new CliInitError("destination_exists", "The destination already exists. Choose a new directory.");
+    throw new CliInitError("scaffold_failed", "Unable to create the starter. Check filesystem permissions and free space; any files added by another process were preserved.");
+  }
+}

package/src/cli-routes.ts

@@ -0,0 +1,88 @@
+/** API-backed commands shared by dispatch, help, and offline discovery. */
+export interface CliRoute {
+  command: string;
+  method: string;
+  path: string;
+  description: string;
+  body?: boolean;
+  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." },
+  { command: "agents update", method: "POST", path: "/v1/agents/{id}", id: true, body: true, description: "Update present Agent fields; null clears a field." },
+  { command: "agents delete", method: "DELETE", path: "/v1/agents/{id}", id: true, description: "Delete an Agent profile." },
+
+  { command: "jobs list", method: "GET", path: "/v1/transcription/jobs", description: "List transcription jobs with --limit and --cursor pagination." },
+  { command: "jobs create", method: "POST", path: "/v1/transcription/jobs", body: true, description: "Create a transcription job from JSON with audio_url." },
+  { command: "jobs get", method: "GET", path: "/v1/transcription/jobs/{id}", id: true, description: "Get transcription status and result." },
+  { command: "jobs cancel", method: "DELETE", path: "/v1/transcription/jobs/{id}", id: true, description: "Cancel a pending transcription job; completed results are retained." },
+  { command: "jobs wait", method: "GET", path: "/v1/transcription/jobs/{id}", id: true, wait: { success: ["completed"], failure: ["failed", "cancelled"] }, description: "Wait for a transcription job to finish." },
+
+  { command: "clones list", method: "GET", path: "/v1/voice/clones", description: "List cloned voices belonging to the current organization." },
+  { command: "clones delete", method: "DELETE", path: "/v1/voice/clones/{id}", id: true, description: "Delete a cloned voice." },
+  { command: "design create", method: "POST", path: "/v1/voice/design", body: true, description: "Generate voice candidates from a JSON prompt." },
+  { command: "design get", method: "GET", path: "/v1/voice/design/{id}", id: true, description: "Get voice design status and candidate previews." },
+  { command: "design wait", method: "GET", path: "/v1/voice/design/{id}", id: true, wait: { success: ["completed"], failure: ["failed"] }, description: "Wait for voice design candidates." },
+  { command: "design save", method: "POST", path: "/v1/voice/design/{id}/save", id: true, body: true, description: "Save a candidate using candidate_id and name." },
+
+  // These are the public gateway adapter routes, including its render lifecycle.
+  { command: "cast capabilities", method: "GET", path: "/v1/cast/capabilities", description: "Discover currently supported Cast voices and directions." },
+  { command: "cast direct", method: "POST", path: "/v1/cast/direct", body: true, description: "Assign emotion and intensity to script text." },
+  { command: "cast speech", method: "POST", path: "/v1/cast/speech", body: true, binary: true, description: "Render one directed line to a WAV file." },
+  { command: "cast render", method: "POST", path: "/v1/cast/render_jobs", body: true, description: "Create a render with voice and script or directed lines." },
+  { command: "cast get", method: "GET", path: "/v1/cast/render_jobs/{id}", id: true, description: "Get Cast render status." },
+  { command: "cast wait", method: "GET", path: "/v1/cast/render_jobs/{id}", id: true, wait: { success: ["done"], failure: ["error"] }, description: "Wait for a Cast render to finish." },
+  { command: "cast audio", method: "GET", path: "/v1/cast/render_jobs/{id}/audio", id: true, binary: true, description: "Download completed Cast audio to a WAV file." },
+
+  { command: "dub get", method: "GET", path: "/v1/dub/jobs/{id}", id: true, description: "Get Dub progress and output details." },
+  { command: "dub wait", method: "GET", path: "/v1/dub/jobs/{id}", id: true, wait: { success: ["done"], failure: ["error"] }, description: "Wait for a Dub job to finish." },
+  { command: "dub audio", method: "GET", path: "/v1/dub/jobs/{id}/audio", id: true, binary: true, description: "Download completed dubbed audio." },
+  { command: "dub video", method: "GET", path: "/v1/dub/jobs/{id}/video", id: true, binary: true, description: "Download a completed video-source job's dubbed video." },
+
+  { command: "recap list", method: "GET", path: "/v1/recap/calls", description: "List calls with Recap summaries." },
+  { command: "recap get", method: "GET", path: "/v1/recap/calls/{id}", id: true, description: "Get a call's Recap summary." },
+  { command: "recap config", method: "GET", path: "/v1/recap/config", description: "Read Recap configuration." },
+  { command: "recap configure", method: "PUT", path: "/v1/recap/config", body: true, description: "Update Recap configuration from JSON." },
+
+  { command: "trace list", method: "GET", path: "/v1/trace/interactions", description: "List Trace interactions." },
+  { command: "trace get", method: "GET", path: "/v1/trace/interactions/{id}", id: true, description: "Get a Trace interaction's findings and timeline." },
+  { command: "trace config", method: "GET", path: "/v1/trace/config", description: "Read Trace configuration." },
+  { command: "trace configure", method: "PUT", path: "/v1/trace/config", body: true, description: "Update Trace configuration from JSON." },
+  { command: "trace findings", method: "GET", path: "/v1/trace/findings", description: "List Trace findings." },
+  { command: "trace violations", method: "GET", path: "/v1/trace/violations", description: "List Trace violations." },
+  { command: "trace exposure", method: "GET", path: "/v1/trace/exposure", description: "Get aggregate Trace exposure." },
+
+  { command: "tools list", method: "GET", path: "/v1/tools", description: "List hosted and registered tools." },
+  { command: "tools get", method: "GET", path: "/v1/tools/{id}", id: true, description: "Get a tool definition." },
+  { command: "tools create", method: "POST", path: "/v1/tools", body: true, description: "Register a tool from JSON." },
+  { command: "tools update", method: "POST", path: "/v1/tools/{id}", id: true, body: true, description: "Update a registered tool." },
+  { command: "tools delete", method: "DELETE", path: "/v1/tools/{id}", id: true, description: "Delete a registered tool." },
+
+  { command: "vocabulary get", method: "GET", path: "/v1/hear/vocabulary", description: "Read organization Hear vocabulary and activation profiles." },
+  { command: "vocabulary set", method: "PUT", path: "/v1/hear/vocabulary", body: true, description: "Replace terms and enabled_for profiles from JSON." },
+  { command: "amd calls", method: "GET", path: "/v1/amd/calls", description: "List answering-machine detection decisions." },
+  { command: "amd get", method: "GET", path: "/v1/amd/calls/{id}", id: true, description: "Get one answering-machine detection decision." },
+  { command: "amd config", method: "GET", path: "/v1/amd/config", description: "Read answering-machine detection configuration." },
+  { command: "amd configure", method: "POST", path: "/v1/amd/config", body: true, description: "Configure AMD aggressiveness and webhook from JSON." },
+];

package/src/cli-runtime.ts

@@ -0,0 +1,30 @@
+/** Keep machine-readable errors clean on runtimes with an experimental File. */
+interface WarningRuntime {
+  versions: { node: string };
+  argv: readonly string[];
+  emitWarning: typeof process.emitWarning;
+}
+
+const installed = new WeakSet<WarningRuntime>();
+const FILE_WARNING = "buffer.File is an experimental feature and might change at any time";
+
+export function installRuntimeCompatibility(runtime: WarningRuntime = process): void {
+  const major = Number(runtime.versions.node.split(".", 1)[0]);
+  const delimiter = runtime.argv.indexOf("--", 2);
+  const args = runtime.argv.slice(2, delimiter < 0 ? undefined : delimiter);
+  if (![18, 19].includes(major) || !(args.includes("--json") || args.includes("-j")) || installed.has(runtime)) return;
+  const emitWarning = runtime.emitWarning;
+  runtime.emitWarning = function (this: unknown, warning: string | Error, ...args: unknown[]): void {
+    const message = typeof warning === "string" ? warning : warning instanceof Error ? warning.message : undefined;
+    const options = args[0];
+    const type = warning instanceof Error ? warning.name : typeof options === "string" ? options
+      : options !== null && typeof options === "object" ? (options as { type?: unknown }).type : undefined;
+    if (message === FILE_WARNING && type === "ExperimentalWarning") return;
+    // Forward untouched arguments so Node retains every emitWarning overload,
+    // its validation, warning codes, constructors, and error object identity.
+    Reflect.apply(emitWarning, this, [warning, ...args]);
+  } as typeof process.emitWarning;
+  installed.add(runtime);
+}
+
+installRuntimeCompatibility();