@pyai/sdk 0.6.0 → 0.6.1

package/AGENT_GUIDE.md

@@ -10,8 +10,8 @@ Markdown and does not require the marketing website renderer.
 
 ## Availability and sources of truth
 
-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;
+The CLI is included in `@pyai/sdk` 0.6.1. Install it with
+`npm install -g @pyai/sdk@0.6.1`. Browser login supports existing PyAI accounts;
 unattended agents should use an authorized environment key. Inspect the
 installed command schema before acting.
 
@@ -35,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.6.0
+npm install -g @pyai/sdk@0.6.1
 pyai --version
 pyai schema --json
 ```
@@ -51,7 +51,7 @@ npm install -g .
 ```
 
 Alternatively install a supplied build with
-`npm install -g /path/to/pyai-sdk-0.6.0.tgz`. The compiled executable supports
+`npm install -g /path/to/pyai-sdk-0.6.1.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.6.0. Install it from
-npm with `npm install -g @pyai/sdk@0.6.0`, then run `pyai login` for browser
+**Version:** the expanded CLI is included in `@pyai/sdk` 0.6.1. Install it from
+npm with `npm install -g @pyai/sdk@0.6.1`, 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.6.0
+npm install -g @pyai/sdk@0.6.1
 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.6.0.tgz
+npm install -g /path/to/pyai-sdk-0.6.1.tgz
 pyai schema --json
 ```
 

package/README.md

@@ -78,9 +78,17 @@ the instant the socket opens and routes server frames to typed callbacks, so you
 **can't** trip the #1 Omni integration bug (a hand-rolled `{"event":"configure"}`
 is acked but silently dropped, giving you a connected session with zero turns):
 
-```ts
+For a Node 20 server, install `npm install ws` and inject its WebSocket constructor
+as shown below. Use ESM imports. Node 22+ can omit the `ws` import and `webSocket`
+option to use its global WebSocket. This SDK transport option does not change the
+MCP server's Node 22+ requirement.
+
+```js
+import WebSocket from "ws";
+
 // Omni is zero-state: the key's org authorizes the session, nothing to create.
 const omni = pyai.omni.connect({
+  webSocket: WebSocket, // Supplies the transport on Node 20.
   rate: 16000, // 24000 browser · 16000 wideband telephony · 8000 G.711/Twilio
   configure: { voice_id: "stock_emma_en_gb", persona: "You are a receptionist." },
   onAudio: (chunk) => speaker.write(chunk), // binary agent audio, play it out
@@ -109,6 +117,25 @@ Caller transcripts continue to require the `0x02` carrier.
 agent audio; `rate: 8000` receives 8 kHz. Read `hello.audio_out` before playback.
 Omni has no commit frame—keep streaming silence during caller pauses.
 
+For a client-executed lookup, declare `side_effect: "read"` in its tool definition:
+
+```js
+const officeHoursTool = {
+  name: "lookup_office_hours",
+  description: "Read the office opening time.",
+  side_effect: "read",
+  parameters: { type: "object", properties: {} },
+};
+// Include officeHoursTool in configure.tools. In onToolCall, return the
+// actual lookup result using session.toolResult(frame.call_id, { result }).
+```
+
+An omitted `side_effect` is treated as an action. Action results need a positive
+completion acknowledgement, for example `{ ok: true, receipt_id: actualReceiptId }`,
+returned inside `toolResult`'s `result`. Send that only after the operation has
+completed; a queued request or transport acknowledgement is insufficient.
+On failure, return `{ error: "Operation failed" }` instead of claiming success.
+
 From the browser, mint an ephemeral token server-side with
 `pyai.omni.createSession({ allowedOrigins })` and pass it as `token` so the page
 never holds a secret key:

package/dist/cli-dx.js

@@ -34,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.6.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.1 and pin that version in repeatable builds."] },
 ].map(recipe => ({ ...recipe, docs_url: "https://pyai.com/agents/speech-calling.md" }));

package/dist/cli-init.js

@@ -127,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.6.0
+npm install -g @pyai/sdk@0.6.1
 pyai --version
 \`\`\`
 
@@ -220,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.6.0
+npm install @pyai/sdk@0.6.1
 cp .env.example .env
 \`\`\`
 

package/dist/cli.js

@@ -405,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  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`);
+            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\nCalling\n  pyai numbers list                         List owned phone numbers\n  pyai numbers search --country US           Find available numbers\n  pyai calls list                           Inspect outbound calls\n  pyai recipes calling --json                Setup and preview examples\n  pyai calls create --data @call.json --idempotency-key REQUEST_KEY --dry-run\n                                             Preview a call without submitting it\n  --dry-run previews a change without sending the request.\n  Number purchases and outbound calls require --confirm and --idempotency-key.\n  Use --confirm only after that purchase or call is authorized.\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;

package/dist/index.d.ts

@@ -594,6 +594,9 @@ export interface OmniToolDef {
     name: string;
     description?: string;
     parameters?: Record<string, unknown>;
+    /** Declare lookups as read-only. Omitted tools are treated as actions and
+     * require a positive completion acknowledgement in their result. */
+    side_effect?: "read" | "action";
 }
 export interface OmniToolCallFrame {
     event: "tool_call";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyai/sdk",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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

@@ -35,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.6.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.1 and pin that version in repeatable builds."] },
 ].map(recipe => ({ ...recipe, docs_url: "https://pyai.com/agents/speech-calling.md" }));

package/src/cli-init.ts

@@ -149,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.6.0
+npm install -g @pyai/sdk@0.6.1
 pyai --version
 \`\`\`
 
@@ -242,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.6.0
+npm install @pyai/sdk@0.6.1
 cp .env.example .env
 \`\`\`
 

package/src/cli.ts

@@ -270,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  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 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\nCalling\n  pyai numbers list                         List owned phone numbers\n  pyai numbers search --country US           Find available numbers\n  pyai calls list                           Inspect outbound calls\n  pyai recipes calling --json                Setup and preview examples\n  pyai calls create --data @call.json --idempotency-key REQUEST_KEY --dry-run\n                                             Preview a call without submitting it\n  --dry-run previews a change without sending the request.\n  Number purchases and outbound calls require --confirm and --idempotency-key.\n  Use --confirm only after that purchase or call is authorized.\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;
   }

package/src/index.ts

@@ -887,6 +887,9 @@ export interface OmniToolDef {
   name: string;
   description?: string;
   parameters?: Record<string, unknown>;
+  /** Declare lookups as read-only. Omitted tools are treated as actions and
+   * require a positive completion acknowledgement in their result. */
+  side_effect?: "read" | "action";
 }
 
 export interface OmniToolCallFrame {