@pyai/sdk 0.12.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,4 +1,6 @@
1
1
  const terminal = (call) => ["completed", "failed", "canceled"].includes(call.status);
2
+ /** A durable handoff keeps its original room after the browser goes away. */
3
+ export const dialerCallHandedOff = (call) => call.transfer_enabled === true && Boolean(call.transfers?.some(transfer => transfer.status === "completed" || transfer.mode === "cold" && ["dialing", "ready", "completing"].includes(transfer.status)));
2
4
  /** One immutable workspace/user scope per instance. Setup and stop retain the
3
5
  * original intent through lost acknowledgments, reloads and audio failures. */
4
6
  export class ManagedDialer {
@@ -61,7 +63,7 @@ export class ManagedDialer {
61
63
  this.intent = saved ? structuredClone(saved) : null;
62
64
  this.initialized = true;
63
65
  if (saved) {
64
- this.update({ state: "unconfirmed", callId: saved.callId ?? null, error: "Recover the previous call before starting another." });
66
+ this.update({ state: "unconfirmed", callId: saved.callId ?? null, transferPending: Boolean(saved.transfer), error: "Recover the previous call before starting another." });
65
67
  // Reload never consumes a new browser capability automatically.
66
68
  if (saved.callId)
67
69
  await this.readStatus();
@@ -112,7 +114,7 @@ export class ManagedDialer {
112
114
  if (saved.stopping)
113
115
  intent.stopping = true;
114
116
  this.update({ callId: session.call_id, call: session.call });
115
- if (terminal(session.call)) {
117
+ if (terminal(session.call) || dialerCallHandedOff(session.call)) {
116
118
  await this.acceptStatus(session.call);
117
119
  return;
118
120
  }
@@ -125,7 +127,7 @@ export class ManagedDialer {
125
127
  return;
126
128
  }
127
129
  await this.audio.connect(session, state => {
128
- if (this.intent !== intent || intent.stopping || this.snapshot.state === "wrapup")
130
+ if (this.intent?.key !== intent.key || this.intent.stopping || ["wrapup", "handing_off", "transferred"].includes(this.snapshot.state))
129
131
  return;
130
132
  if (state === "disconnected") {
131
133
  this.audio.disconnect();
@@ -160,16 +162,38 @@ export class ManagedDialer {
160
162
  throw new Error("Calling status identity changed.");
161
163
  if (this.snapshot.call && call.version < this.snapshot.call.version)
162
164
  return;
165
+ const transfer = this.intent.transfer;
166
+ if (transfer) {
167
+ const observed = call.transfers?.find(item => transfer.id ? item.id === transfer.id : item.to === transfer.to && item.mode === transfer.mode);
168
+ if (observed && observed.to === transfer.to && observed.mode === transfer.mode) {
169
+ const next = structuredClone(this.intent);
170
+ if (["canceled", "failed"].includes(observed.status)) {
171
+ next.retiredTransferKeys = [...new Set([...(next.retiredTransferKeys ?? []), transfer.key])];
172
+ delete next.transfer;
173
+ }
174
+ else
175
+ next.transfer.id = observed.id;
176
+ await this.journal.write(next);
177
+ this.intent = next;
178
+ this.update({ transferPending: Boolean(transfer.command && !["completed", "canceled", "failed"].includes(observed.status)) });
179
+ }
180
+ }
163
181
  if (terminal(call)) {
164
182
  this.audio.disconnect();
165
183
  this.update({ call, state: "wrapup", muted: false, error: null });
166
184
  }
185
+ else if (dialerCallHandedOff(call)) {
186
+ this.audio.disconnect();
187
+ this.update({ call, state: call.transfers?.some(item => item.status === "completed") ? "transferred" : "handing_off", muted: false, error: null });
188
+ }
167
189
  else
168
190
  this.update({ call });
169
191
  }
170
192
  async stop() {
171
193
  if (!this.intent)
172
194
  return;
195
+ if (this.snapshot.call && dialerCallHandedOff(this.snapshot.call))
196
+ throw new Error("The transferred conversation continues independently. Check its status instead of ending the caller's conversation.");
173
197
  // Mark immediately so a late create acknowledgment cannot connect audio.
174
198
  this.intent.stopping = true;
175
199
  this.audio.disconnect();
@@ -178,6 +202,11 @@ export class ManagedDialer {
178
202
  if (this.operation)
179
203
  await this.operation;
180
204
  return this.exclusive(async () => {
205
+ if (this.snapshot.call && dialerCallHandedOff(this.snapshot.call)) {
206
+ this.intent.stopping = false;
207
+ await this.journal.write(structuredClone(this.intent));
208
+ return;
209
+ }
181
210
  await this.journal.write(structuredClone(this.intent));
182
211
  if (!this.intent.callId)
183
212
  await this.setup();
@@ -187,6 +216,13 @@ export class ManagedDialer {
187
216
  }
188
217
  async stopKnown() {
189
218
  try {
219
+ const current = await this.broker.get(this.intent.callId);
220
+ if (dialerCallHandedOff(current)) {
221
+ this.intent.stopping = false;
222
+ await this.journal.write(structuredClone(this.intent));
223
+ await this.acceptStatus(current);
224
+ return;
225
+ }
190
226
  const call = await this.broker.hangup(this.intent.callId);
191
227
  await this.acceptStatus(call);
192
228
  if (!terminal(call))
@@ -198,13 +234,86 @@ export class ManagedDialer {
198
234
  }
199
235
  async finishWrapup() {
200
236
  return this.exclusive(async () => {
201
- if (!this.intent || this.snapshot.state !== "wrapup" || !this.snapshot.call || !terminal(this.snapshot.call))
202
- throw new Error("Confirmed call completion is required.");
237
+ if (!this.intent || !this.snapshot.call || !(this.snapshot.state === "wrapup" && terminal(this.snapshot.call) ||
238
+ this.snapshot.state === "transferred" && this.snapshot.call.transfers?.some(item => item.status === "completed")))
239
+ throw new Error("Confirmed call completion or successful transfer is required.");
203
240
  await this.journal.clear(this.scope, this.intent.key);
204
241
  this.intent = null;
205
- this.update({ state: "idle", callId: null, call: null, muted: false, error: null });
242
+ this.update({ state: "idle", callId: null, call: null, muted: false, error: null, transferPending: false });
206
243
  });
207
244
  }
245
+ async transfer(to, mode) {
246
+ if (!/^\+[1-9]\d{6,14}$/.test(to) || !["warm", "cold"].includes(mode))
247
+ throw new Error("Choose a transfer destination with its country code and a transfer mode.");
248
+ return this.exclusive(async () => {
249
+ if (!this.intent?.callId || this.snapshot.state !== "active" || !this.snapshot.call?.transfer_enabled || !this.broker.transfers)
250
+ throw new Error("Transfers require a connected call started with transfers enabled.");
251
+ if (this.intent.transfer || this.snapshot.call.transfers?.some(item => !["completed", "canceled", "failed"].includes(item.status)))
252
+ throw new Error("Recover or finish the current transfer before starting another.");
253
+ const next = structuredClone(this.intent);
254
+ next.transfer = { key: this.newKey(), to, mode };
255
+ await this.journal.write(next);
256
+ this.intent = next;
257
+ await this.transferKnown();
258
+ });
259
+ }
260
+ async retryTransfer() {
261
+ return this.exclusive(async () => {
262
+ if (!this.intent?.transfer)
263
+ throw new Error("No transfer to recover.");
264
+ await this.transferKnown();
265
+ });
266
+ }
267
+ async completeTransfer() { return this.transferCommand("complete"); }
268
+ async cancelTransfer() { return this.transferCommand("cancel"); }
269
+ async transferCommand(command) {
270
+ return this.exclusive(async () => {
271
+ if (!this.intent?.transfer?.id || !this.broker.transfers)
272
+ throw new Error("Recover the transfer identity first.");
273
+ const transfer = this.snapshot.call?.transfers?.find(item => item.id === this.intent.transfer.id);
274
+ if (command === "complete" && transfer?.status !== "ready")
275
+ throw new Error("Wait until the transfer target has joined.");
276
+ if (this.intent.transfer.mode !== "warm")
277
+ throw new Error("Cold transfers complete automatically.");
278
+ if (this.intent.transfer.command && this.intent.transfer.command !== command)
279
+ throw new Error("Recover the saved transfer command first.");
280
+ const next = structuredClone(this.intent);
281
+ next.transfer.command = command;
282
+ await this.journal.write(next);
283
+ this.intent = next;
284
+ await this.transferKnown();
285
+ });
286
+ }
287
+ async transferKnown() {
288
+ this.update({ transferPending: true, error: null });
289
+ try {
290
+ const original = this.intent, saved = await this.journal.read(this.scope);
291
+ if (!saved || saved.scope !== this.scope || saved.key !== original.key || saved.callId !== original.callId ||
292
+ saved.transfer?.key !== original.transfer?.key || saved.transfer?.to !== original.transfer?.to || saved.transfer?.mode !== original.transfer?.mode)
293
+ throw new Error("Saved transfer intent changed.");
294
+ this.intent = saved;
295
+ if (saved.stopping) {
296
+ await this.stopKnown();
297
+ return;
298
+ }
299
+ const intent = saved, transfer = saved.transfer, broker = this.broker.transfers;
300
+ const call = transfer.command && transfer.id ? await broker[transfer.command](intent.callId, transfer.id)
301
+ : await broker.create(intent.callId, { to: transfer.to, mode: transfer.mode }, transfer.key);
302
+ if (call.id !== intent.callId)
303
+ throw new Error("Transfer call identity changed.");
304
+ const observed = transfer.id ? call.transfers?.find(item => item.id === transfer.id)
305
+ : call.transfers?.slice().reverse().find(item => item.to === transfer.to && item.mode === transfer.mode);
306
+ if (!observed || observed.to !== transfer.to || observed.mode !== transfer.mode)
307
+ throw new Error("Transfer identity is unavailable.");
308
+ transfer.id = observed.id;
309
+ await this.journal.write(structuredClone(intent));
310
+ await this.acceptStatus(call);
311
+ this.update({ transferPending: false });
312
+ }
313
+ catch {
314
+ this.update({ transferPending: true, error: "Transfer is unconfirmed. Recover this same transfer before trying another." });
315
+ }
316
+ }
208
317
  mute(value) {
209
318
  if (this.snapshot.state !== "active")
210
319
  throw new Error("No active audio call.");
@@ -1,11 +1,12 @@
1
1
  /** Server-only broker. Never import this module into a browser bundle. */
2
2
  import { createHash } from "node:crypto";
3
+ import { dialerCallHandedOff } from "./managedDialer.js";
3
4
  export function createServerDialerBroker(sdk, authenticatedUserId) {
4
5
  if (!authenticatedUserId.trim())
5
6
  throw new Error("An authenticated user is required.");
6
7
  const ownedCall = async (id) => {
7
8
  const call = await sdk.telephony.calls.get(id);
8
- if (call.call_type !== "human" || call.user_id !== authenticatedUserId)
9
+ if (call.id !== id || call.call_type !== "human" || call.user_id !== authenticatedUserId)
9
10
  throw new Error("No such call.");
10
11
  return call;
11
12
  };
@@ -18,6 +19,22 @@ export function createServerDialerBroker(sdk, authenticatedUserId) {
18
19
  return sdk.telephony.browserSessions.create({ ...input, user_id: authenticatedUserId }, { idempotencyKey: scopedKey });
19
20
  },
20
21
  get: ownedCall,
21
- async hangup(id) { await ownedCall(id); return sdk.telephony.calls.hangup(id); },
22
+ async hangup(id) {
23
+ const call = await ownedCall(id);
24
+ if (dialerCallHandedOff(call))
25
+ return call;
26
+ return sdk.telephony.calls.hangup(id);
27
+ },
28
+ transfers: {
29
+ async create(id, input, key) {
30
+ await ownedCall(id);
31
+ if (!key || key.length > 255 || /[\r\n]/.test(key))
32
+ throw new Error("A valid transfer retry key is required.");
33
+ const scopedKey = "dialer-transfer:" + createHash("sha256").update(authenticatedUserId).update("\0").update(id).update("\0").update(key).digest("hex");
34
+ return sdk.telephony.calls.transfers.create(id, { ...input, user_id: authenticatedUserId }, { idempotencyKey: scopedKey });
35
+ },
36
+ async complete(id, transferId) { await ownedCall(id); return sdk.telephony.calls.transfers.complete(id, transferId, authenticatedUserId); },
37
+ async cancel(id, transferId) { await ownedCall(id); return sdk.telephony.calls.transfers.cancel(id, transferId, authenticatedUserId); },
38
+ },
22
39
  };
23
40
  }
package/dist/index.d.ts CHANGED
@@ -201,6 +201,8 @@ export interface AgentConfig {
201
201
  name?: string;
202
202
  /** Saved instructions: 8,000 Unicode characters by default; 32,000 on commitment plans. */
203
203
  persona_system_prompt?: string | null;
204
+ /** Separate setup rules, writable only by explicitly enrolled server credentials. */
205
+ platform_guidance?: string | null;
204
206
  /** False restricts retrieval to explicit agent bindings, including none. Default true. */
205
207
  inherit_org_knowledgebases?: boolean;
206
208
  greeting?: string | null;
@@ -650,6 +652,8 @@ export interface OmniConfigure {
650
652
  voice_id?: string;
651
653
  /** System prompt / role + instructions for the agent. */
652
654
  persona?: string;
655
+ /** Separate bounded platform guidance, applied before customer instructions. */
656
+ role_scaffold?: string;
653
657
  /** Customer-hosted URL the engine calls per turn for grounding. */
654
658
  kb_endpoint?: string;
655
659
  /** Bearer the engine presents to `kb_endpoint`. */
@@ -851,6 +855,8 @@ export interface TelephonyCall {
851
855
  from_number_id: string | null;
852
856
  agent_id: string | null;
853
857
  call_type?: "human";
858
+ transfer_enabled?: boolean;
859
+ transfers?: TelephonyTransfer[];
854
860
  user_id?: string;
855
861
  client_reference: string | null;
856
862
  stop_requested: boolean;
@@ -861,6 +867,12 @@ export interface TelephonyCall {
861
867
  [key: string]: unknown;
862
868
  }
863
869
  export type TelephonyUseCase = "transactional" | "support" | "sales" | "collections" | "survey";
870
+ export interface TelephonyTransfer {
871
+ id: string;
872
+ mode: "warm" | "cold";
873
+ status: "holding" | "dialing" | "ready" | "completing" | "canceling" | "completed" | "canceled" | "failed";
874
+ to: string | null;
875
+ }
864
876
  export interface TelephonyCallCreate {
865
877
  from_number_id: string;
866
878
  to: string;
@@ -883,9 +895,11 @@ export type TelephonyBrowserSessionCreate = {
883
895
  } & ({
884
896
  to: string;
885
897
  destinations?: never;
898
+ transfer_enabled?: boolean;
886
899
  } | {
887
900
  to?: never;
888
901
  destinations: string[];
902
+ transfer_enabled?: false;
889
903
  });
890
904
  export interface TelephonyBrowserSession {
891
905
  object: "telephony.browser_session";
@@ -1498,6 +1512,18 @@ export declare class PyAI {
1498
1512
  range?: string;
1499
1513
  }) => Promise<Response>;
1500
1514
  deleteRecording: (id: string) => Promise<void>;
1515
+ transfers: {
1516
+ /** Persist the key and target before requesting a consultation. */
1517
+ create: (id: string, input: {
1518
+ to: string;
1519
+ mode: "warm" | "cold";
1520
+ user_id: string;
1521
+ }, options: {
1522
+ idempotencyKey: string;
1523
+ }) => Promise<TelephonyCall>;
1524
+ complete: (id: string, transferId: string, userId: string) => Promise<TelephonyCall>;
1525
+ cancel: (id: string, transferId: string, userId: string) => Promise<TelephonyCall>;
1526
+ };
1501
1527
  };
1502
1528
  browserSessions: {
1503
1529
  /** Persist input and key on your server; retries recover the original session. */
package/dist/index.js CHANGED
@@ -1177,6 +1177,12 @@ export class PyAI {
1177
1177
  decideAdmission: (id, input) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/admission`, input),
1178
1178
  recording: (id, options = {}) => this.request(`/v1/telephony/calls/${encodeURIComponent(id)}/recording`, { headers: this.authHeaders(options.range ? { Range: options.range } : {}) }),
1179
1179
  deleteRecording: async (id) => { await this.deleteReq(`/v1/telephony/calls/${encodeURIComponent(id)}/recording`); },
1180
+ transfers: {
1181
+ /** Persist the key and target before requesting a consultation. */
1182
+ create: (id, input, options) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/transfers`, input, telephonyIdempotencyHeader(options.idempotencyKey)),
1183
+ complete: (id, transferId, userId) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/transfers/${encodeURIComponent(transferId)}/complete`, { user_id: userId }),
1184
+ cancel: (id, transferId, userId) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/transfers/${encodeURIComponent(transferId)}/cancel`, { user_id: userId }),
1185
+ },
1180
1186
  },
1181
1187
  browserSessions: {
1182
1188
  /** Persist input and key on your server; retries recover the original session. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pyai/sdk",
3
- "version": "0.12.0",
3
+ "version": "0.13.0",
4
4
  "description": "Official TypeScript/JavaScript SDK for PyAI, speech-to-text (Hear), text-to-speech (Speak), realtime voice agents (Omni), and call compliance (Trace).",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -1,7 +1,7 @@
1
1
  // Generated by scripts/generate-omni-starter.mjs; edit examples/omni-starter instead.
2
2
  export const omniTemplate = Object.freeze({
3
- "README.md": "# Runnable Omni starter\n\nRequires Node 20.19+ and ESM. Node 20 uses the included `ws` transport;\nNode 22 also works. The separate MCP server requires Node 22+.\nThis server-side example uses a synthetic read-only office-hours tool. Read\n`PYAI.md` when generating the project through the CLI.\n\n<!-- omni-install:start -->\n```sh\nnpm install @pyai/sdk@0.12.0\nnpx pyai init voice-demo --template omni\ncd voice-demo\nnpm install\n```\n\nInitialization is offline; installing dependencies and running `main.mjs` are\nseparate steps. For an existing checkout of this example, run `npm install`\nin its directory instead.\n<!-- omni-install:end -->\n\nInject `PYAI_API_KEY` through your secret manager or shell environment. Do not\npaste a real key into source, a prompt, or shell history. `.env.example` documents\nthe variable; this program does not load `.env` or saved CLI profiles.\n\nPrepare a 24 kHz PCM16 mono WAV, at most 20 seconds, saying “Please look up the\noffice opening time.” Then run:\n\n```sh\nnode main.mjs caller.wav\n```\n\nRunning the program explicitly opens one bounded Omni session and uploads its\ncaptured reply to Hear. Both consume your key's allowed usage. Automatic retries\nare disabled. No managed number is bought and no phone call is placed.\n\n`session.mjs` waits for configuration and the greeting to drain, sends exactly\none paced input stream (caller PCM or silence), returns the read tool's result,\nand captures output using the rate from `hello.audio_out`. Never run a separate\nsilence timer alongside caller audio. `timing.mjs` is generated from the existing\nOmni evaluation harness's timing utilities.\n\nThe new private `omni-run-*` folder contains `session.wav`, `reply.wav`, and\n`report.json`. The report separates received audio, an office-hours answer\nrecovered by Hear from captured audio, and physical playback (not tested).\nThe office-hours check accepts formatting such as `opens@9a.m`, `9 a.m.` and\n`nine in the morning` in a complete affirmative opening-time sentence. Wrong\ntimes, negation, conflicting or truncated text remain unverified. This is a\nconservative check for the example fact, not a general answer-quality score.\nA synthesis transcript is advisory; it is not evidence that speech arrived.\nThis starter does not negotiate playback receipts. Capture ends after the\nsimulated queue drains and two seconds of quiet, a bounded capture heuristic.\nListen to the saved file when qualifying actual sound quality or completeness.\n\nTo exercise interruption, supply a second WAV saying “Stop speaking now”:\n\n```sh\nnode main.mjs caller.wav interruption.wav\n```\n\nThe second clip starts while reply audio is queued. `onBargeIn` clears that\nsimulated queue, and capture observes at least five seconds after that clip ends.\nAn interrupted answer can correctly fail the full-answer check;\ninspect the separate interruption evidence. This is not a physical speaker test.\nFor a real playback adapter, cancel both queued and currently playing audio.\nReplace the example lookup with authorized application data before product use.\n\nOn a session error, the program exits with JSON containing a recognized machine\n`code` (for example `media_dead` or `invalid_configure`). Unknown server codes\nbecome `unrecognized_server_error`; transport or decoding errors without a\nrecognized transport code become `transport_or_protocol_error`. Raw error text,\ncall IDs and unknown code values are omitted. No automatic retry is attempted;\ninspect the code and your authorized diagnostics before deciding to retry.\n",
4
- "package.json": "{\n \"name\": \"pyai-omni-starter\",\n \"version\": \"0.0.0\",\n \"private\": true,\n \"type\": \"module\",\n \"engines\": {\n \"node\": \">=20.19.0\"\n },\n \"scripts\": {\n \"start\": \"node main.mjs\"\n },\n \"dependencies\": {\n \"@pyai/sdk\": \"0.12.0\",\n \"ws\": \"^8.18.3\"\n }\n}\n",
3
+ "README.md": "# Runnable Omni starter\n\nRequires Node 20.19+ and ESM. Node 20 uses the included `ws` transport;\nNode 22 also works. The separate MCP server requires Node 22+.\nThis server-side example uses a synthetic read-only office-hours tool. Read\n`PYAI.md` when generating the project through the CLI.\n\n<!-- omni-install:start -->\n```sh\nnpm install @pyai/sdk@0.13.0\nnpx pyai init voice-demo --template omni\ncd voice-demo\nnpm install\n```\n\nInitialization is offline; installing dependencies and running `main.mjs` are\nseparate steps. For an existing checkout of this example, run `npm install`\nin its directory instead.\n<!-- omni-install:end -->\n\nInject `PYAI_API_KEY` through your secret manager or shell environment. Do not\npaste a real key into source, a prompt, or shell history. `.env.example` documents\nthe variable; this program does not load `.env` or saved CLI profiles.\n\nPrepare a 24 kHz PCM16 mono WAV, at most 20 seconds, saying “Please look up the\noffice opening time.” Then run:\n\n```sh\nnode main.mjs caller.wav\n```\n\nRunning the program explicitly opens one bounded Omni session and uploads its\ncaptured reply to Hear. Both consume your key's allowed usage. Automatic retries\nare disabled. No managed number is bought and no phone call is placed.\n\n`session.mjs` waits for configuration and the greeting to drain, sends exactly\none paced input stream (caller PCM or silence), returns the read tool's result,\nand captures output using the rate from `hello.audio_out`. Never run a separate\nsilence timer alongside caller audio. `timing.mjs` is generated from the existing\nOmni evaluation harness's timing utilities.\n\nThe new private `omni-run-*` folder contains `session.wav`, `reply.wav`, and\n`report.json`. The report separates received audio, an office-hours answer\nrecovered by Hear from captured audio, and physical playback (not tested).\nThe office-hours check accepts formatting such as `opens@9a.m`, `9 a.m.` and\n`nine in the morning` in a complete affirmative opening-time sentence. Wrong\ntimes, negation, conflicting or truncated text remain unverified. This is a\nconservative check for the example fact, not a general answer-quality score.\nA synthesis transcript is advisory; it is not evidence that speech arrived.\nThis starter does not negotiate playback receipts. Capture ends after the\nsimulated queue drains and two seconds of quiet, a bounded capture heuristic.\nListen to the saved file when qualifying actual sound quality or completeness.\n\nTo exercise interruption, supply a second WAV saying “Stop speaking now”:\n\n```sh\nnode main.mjs caller.wav interruption.wav\n```\n\nThe second clip starts while reply audio is queued. `onBargeIn` clears that\nsimulated queue, and capture observes at least five seconds after that clip ends.\nAn interrupted answer can correctly fail the full-answer check;\ninspect the separate interruption evidence. This is not a physical speaker test.\nFor a real playback adapter, cancel both queued and currently playing audio.\nReplace the example lookup with authorized application data before product use.\n\nOn a session error, the program exits with JSON containing a recognized machine\n`code` (for example `media_dead` or `invalid_configure`). Unknown server codes\nbecome `unrecognized_server_error`; transport or decoding errors without a\nrecognized transport code become `transport_or_protocol_error`. Raw error text,\ncall IDs and unknown code values are omitted. No automatic retry is attempted;\ninspect the code and your authorized diagnostics before deciding to retry.\n",
4
+ "package.json": "{\n \"name\": \"pyai-omni-starter\",\n \"version\": \"0.0.0\",\n \"private\": true,\n \"type\": \"module\",\n \"engines\": {\n \"node\": \">=20.19.0\"\n },\n \"scripts\": {\n \"start\": \"node main.mjs\"\n },\n \"dependencies\": {\n \"@pyai/sdk\": \"0.13.0\",\n \"ws\": \"^8.18.3\"\n }\n}\n",
5
5
  "timing.mjs": "// Monotonic capture timing. Arrival time is distinct from queued playback:\n// a single packet may contain seconds of audio and must finish before settling.\nexport const FRAME_MS = 20;\nexport const REALTIME_GAP_LIMIT_MS = 100;\n// Interruption tests need an observation window after caller transmission,\n// even when an earlier cue/response already finished. These are test bounds,\n// not an inferred engine reply-end or a naturalness threshold.\nexport const INTERRUPTION_OBSERVATION = Object.freeze({\n minimumAfterCallerStreamMs: 5000, quietMs: 2000, maximumAfterCallerStreamMs: 25000,\n});\n\n/** Approximate audible bounds; this is energy detection, not a speech/VAD claim. */\nexport function audibleBounds(pcm, rate, rmsFloor = 160) {\n const window = Math.max(1, Math.round(rate / 100)); // 10 ms windows\n let first = null;\n let last = null;\n for (let off = 0; off < pcm.length; off += window) {\n const end = Math.min(pcm.length, off + window);\n let energy = 0;\n for (let i = off; i < end; i++) energy += pcm[i] * pcm[i];\n if (Math.sqrt(energy / (end - off)) >= rmsFloor) {\n first ??= off;\n last = end;\n }\n }\n return { first, last };\n}\n\nexport function newAudioCapture(started) {\n return {\n started, firstPacketAt: null, lastPacketAt: null,\n firstAudioAt: null, lastAudioAt: null, playbackEndAt: null,\n samples: 0, pcm: [], turnBeginAt: null, eouMs: null,\n latestTurnBeginAt: null, postTurnBeginFirstPacketAt: null,\n postTurnBeginFirstAudioAt: null, lastAssistantTranscriptAt: null, lastCallerTranscriptAt: null,\n callerTranscriptEvents: [], assistantTranscriptEvents: [],\n turnBegins: [], unheardCancellations: [], unheardSupersededTurns: [], tools: [], toolResults: [], kb: null, events: [],\n };\n}\n\nexport function recordTurnBegin(ctx, at, turn, origin = 0) {\n const prior = ctx.turnBegins.at(-1);\n const cancellation = ctx.unheardCancellations.at(-1);\n if (prior && cancellation && !cancellation.admitted\n && cancellation.turn === prior.turn && cancellation.turnBeginIndex === ctx.turnBegins.length - 1\n && Number.isSafeInteger(turn) && turn > prior.turn && at > cancellation.at\n && ctx.samples === 0 && ctx.assistantTranscriptEvents.length === 0\n && ctx.tools.length === 0 && ctx.toolResults.length === 0) {\n cancellation.admitted = true;\n ctx.unheardSupersededTurns.push({ turn: prior.turn, beginAtMs: prior.atMs,\n cancelledAtMs: cancellation.atMs, cancellationEventIndex: cancellation.eventIndex,\n replacementTurn: turn, outputPacketsBeforeReplacement: 0 });\n }\n ctx.turnBeginAt ??= at;\n ctx.latestTurnBeginAt = at;\n // Earlier PCM can be a listening cue. A new reply is still pending even\n // when that cue has already finished playing; retain all of its PCM.\n ctx.postTurnBeginFirstPacketAt = null;\n ctx.postTurnBeginFirstAudioAt = null;\n ctx.turnBegins.push({ atMs: Math.round(at - origin), turn: turn ?? null });\n}\n\nexport function recordUnheardCancellation(ctx, event, at, origin, eventIndex) {\n const prior = ctx.turnBegins.at(-1);\n if (event.event !== \"flush\" || event.reason !== \"turn_merge\"\n || !Number.isSafeInteger(event.cancelled_turn) || event.cancelled_turn <= 0\n || prior?.turn !== event.cancelled_turn || at < ctx.latestTurnBeginAt\n || ctx.samples !== 0 || ctx.assistantTranscriptEvents.length\n || ctx.tools.length || ctx.toolResults.length\n || ctx.unheardCancellations.some(c => c.turnBeginIndex === ctx.turnBegins.length - 1)) return;\n ctx.unheardCancellations.push({ turn: event.cancelled_turn, at,\n atMs: Math.round(at - origin), eventIndex, turnBeginIndex: ctx.turnBegins.length - 1,\n admitted: false });\n}\n\nexport function recordAudio(ctx, pcm, at, rate) {\n if (!(pcm instanceof Int16Array) || !pcm.length) return null;\n const copy = pcm.slice(); // Some transports reuse callback buffers.\n const playbackAt = Math.max(at, ctx.playbackEndAt ?? at);\n const endAt = playbackAt + (copy.length / rate) * 1000;\n const bounds = audibleBounds(copy, rate);\n ctx.firstPacketAt ??= at;\n ctx.lastPacketAt = at;\n ctx.playbackEndAt = endAt;\n const afterTurnBegin = ctx.latestTurnBeginAt != null && at >= ctx.latestTurnBeginAt;\n if (afterTurnBegin) ctx.postTurnBeginFirstPacketAt ??= at;\n if (bounds.first != null) {\n ctx.firstAudioAt ??= playbackAt + (bounds.first / rate) * 1000;\n ctx.lastAudioAt = playbackAt + (bounds.last / rate) * 1000;\n if (afterTurnBegin) ctx.postTurnBeginFirstAudioAt ??= playbackAt + (bounds.first / rate) * 1000;\n }\n ctx.samples += copy.length;\n ctx.pcm.push(copy);\n return { playbackAt, endAt, pcm: copy };\n}\n\n/** Preserve negative gaps: they are overlaps, never missing measurements. */\nexport function captureTiming(ctx, caller, origin = 0) {\n const relative = (at) => at == null ? null : Math.round(at - origin);\n const gap = (at) => at == null || caller.speechOffsetAt == null\n ? null : Math.round(at - caller.speechOffsetAt);\n return {\n ttfbMs: gap(ctx.firstAudioAt),\n anyAudioTtfbMs: gap(ctx.firstAudioAt),\n postTurnBeginTtfbMs: gap(ctx.postTurnBeginFirstAudioAt),\n turnMs: gap(ctx.lastAudioAt),\n packetTtfbMs: gap(ctx.firstPacketAt),\n callerStartMs: relative(caller.startedAt),\n callerSpeechOnsetMs: relative(caller.speechOnsetAt),\n callerSpeechOffsetMs: relative(caller.speechOffsetAt),\n callerStreamEndMs: relative(caller.streamEndAt),\n agentFirstPacketMs: relative(ctx.firstPacketAt),\n agentLastPacketMs: relative(ctx.lastPacketAt),\n agentSpeechOnsetMs: relative(ctx.firstAudioAt),\n agentSpeechOffsetMs: relative(ctx.lastAudioAt),\n agentPlaybackEndMs: relative(ctx.playbackEndAt),\n latestTurnBeginMs: relative(ctx.latestTurnBeginAt),\n postTurnBeginFirstPacketMs: relative(ctx.postTurnBeginFirstPacketAt),\n postTurnBeginSpeechOnsetMs: relative(ctx.postTurnBeginFirstAudioAt),\n lastAssistantTranscriptMs: relative(ctx.lastAssistantTranscriptAt),\n callerMaxFrameGapMs: Math.round(caller.maxFrameGapMs ?? 0),\n method: \"client-monotonic-queued-playback-energy-bounds\",\n };\n}\n\nexport async function streamPcmRealtime(omni, pcm, rate, clock, onFrame = () => {}) {\n const frameSize = Math.max(1, Math.round((rate * FRAME_MS) / 1000));\n const bounds = audibleBounds(pcm, rate);\n const startedAt = clock.now();\n let speechOnsetAt = null;\n let speechOffsetAt = null;\n let previousFrameEnd = startedAt;\n let maxFrameGapMs = 0;\n for (let off = 0; off < pcm.length; off += frameSize) {\n const frame = pcm.subarray(off, Math.min(off + frameSize, pcm.length));\n const at = clock.now();\n maxFrameGapMs = Math.max(maxFrameGapMs, at - previousFrameEnd);\n const durationMs = (frame.length / rate) * 1000;\n omni.sendAudio(frame);\n onFrame(frame, at);\n if (bounds.first != null && bounds.first >= off && bounds.first < off + frame.length) {\n speechOnsetAt = at + ((bounds.first - off) / rate) * 1000;\n }\n if (bounds.last != null && bounds.last > off && bounds.last <= off + frame.length) {\n speechOffsetAt = at + ((bounds.last - off) / rate) * 1000;\n }\n previousFrameEnd = at + durationMs;\n // Pace from the actual send. Never burst late frames to \"catch up\".\n await clock.sleep(Math.max(0, previousFrameEnd - clock.now()));\n }\n return { startedAt, speechOnsetAt, speechOffsetAt,\n streamEndAt: clock.now(), maxFrameGapMs };\n}\n\nexport async function streamSilenceWhile(omni, rate, shouldContinue, clock, onFrame = () => {}) {\n const silence = new Int16Array(Math.max(1, Math.round((rate * FRAME_MS) / 1000)));\n while (shouldContinue()) {\n const at = clock.now();\n omni.sendAudio(silence);\n onFrame(silence, at);\n await clock.sleep(FRAME_MS);\n }\n}\n\nexport async function waitForAgentSettle(getCtx, clock, opts = {}) {\n const started = clock.now();\n const observation = opts.callerStreamEndAt != null;\n if (observation && (!Number.isFinite(opts.callerStreamEndAt)\n || opts.callerStreamEndAt < 0 || opts.callerStreamEndAt > started)) {\n throw new Error(\"Invalid caller observation boundary\");\n }\n const timeoutMs = observation ? INTERRUPTION_OBSERVATION.maximumAfterCallerStreamMs : opts.timeoutMs ?? 25000;\n const settleMs = observation ? INTERRUPTION_OBSERVATION.quietMs : opts.settleMs ?? 2000;\n const deadlineAt = (observation ? opts.callerStreamEndAt : started) + timeoutMs;\n const minimumAt = observation ? opts.callerStreamEndAt + INTERRUPTION_OBSERVATION.minimumAfterCallerStreamMs : -Infinity;\n while (true) {\n const ctx = getCtx();\n const at = clock.now();\n if (opts.isClosed?.()) return { reason: \"closed\", at };\n if (observation && at >= deadlineAt) return { reason: \"timeout\", at };\n const hasResponseAudio = !opts.requireTurnBegin || (ctx.latestTurnBeginAt != null\n && ctx.postTurnBeginFirstAudioAt != null);\n // Synthesis text is progress, not a completion event. It can arrive after\n // early/final audio, so extend the quiet floor without demanding another\n // packet after every advisory. The protocol still has no reply-end marker.\n const activityEnd = Math.max(ctx.playbackEndAt ?? -Infinity,\n ctx.latestTurnBeginAt ?? -Infinity, ctx.lastAssistantTranscriptAt ?? -Infinity,\n observation ? ctx.lastCallerTranscriptAt ?? -Infinity : -Infinity);\n // Do not demand a new post-caller turn_begin: an earlier turn can be\n // coalesced and speak later. This records a bounded quiet observation;\n // downstream response-timing checks can impose a stricter begin boundary.\n if (ctx.firstPacketAt != null && hasResponseAudio && at >= minimumAt && at >= activityEnd + settleMs) {\n return { reason: \"settled\", at };\n }\n if (opts.allowEmpty && ctx.firstPacketAt == null && at >= minimumAt && at - started >= (opts.emptyWaitMs ?? 800)) {\n return { reason: \"empty\", at };\n }\n if (at - started >= timeoutMs) return { reason: \"timeout\", at };\n await clock.sleep(observation ? Math.min(20, deadlineAt - at) : 20);\n }\n}\n\nexport async function withTimeout(promise, ms, message, clock) {\n let timer;\n try {\n return await Promise.race([\n promise,\n new Promise((_, reject) => {\n timer = clock.setTimeout(() => reject(new Error(message)), ms);\n }),\n ]);\n } finally {\n clock.clearTimeout(timer);\n }\n}\n",
6
6
  "main.mjs": "import PyAI from \"@pyai/sdk\";\nimport WebSocket from \"ws\"; // Explicit transport makes this work on Node 20 too.\nimport { readFile, writeFile, mkdtemp } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { runSession } from \"./session.mjs\";\nimport { readWav, writeWav, assessAnswer } from \"./audio.mjs\";\n\nasync function main() {\n const [callerPath, interruptionPath, extra] = process.argv.slice(2);\n if (!callerPath || extra) throw new Error(\"Usage: node main.mjs caller.wav [interruption.wav]\");\n if (!process.env.PYAI_API_KEY) throw new Error(\"Inject PYAI_API_KEY through your environment first\");\n const caller = readWav(await readFile(callerPath));\n const interruption = interruptionPath ? readWav(await readFile(interruptionPath)) : undefined;\n const pyai = new PyAI({ apiKey: process.env.PYAI_API_KEY, maxRetries: 0,\n fetch: (url, options) => fetch(url, { ...options, signal: AbortSignal.timeout(30000) }),\n });\n const { report, audio, replyAudio } = await runSession({ pyai, webSocket: WebSocket, caller, interruption });\n const directory = await mkdtemp(join(process.cwd(), \"omni-run-\"));\n const save = (name, data) => writeFile(join(directory, name), data, { mode: 0o600, flag: \"wx\" });\n await save(\"session.wav\", writeWav(audio, report.output_rate ?? 24000));\n const reply = writeWav(replyAudio, report.output_rate ?? 24000);\n await save(\"reply.wav\", reply);\n // Hear the captured bytes, rather than trusting synthesis-advisory text.\n let capturedTranscript = \"\";\n if (report.reply_audio_bytes) {\n try {\n const heard = await pyai.audio.transcriptions.create({ file: new File([reply], \"reply.wav\", { type: \"audio/wav\" }), model: \"pyai-hear\" });\n capturedTranscript = heard.text;\n } catch { report.hear_error = \"Captured audio saved; Hear verification failed\"; }\n }\n const result = { ...report, captured_transcript: capturedTranscript, evidence: assessAnswer(report, capturedTranscript) };\n await save(\"report.json\", JSON.stringify(result, null, 2) + \"\\n\");\n console.log(JSON.stringify({ directory, ...result }, null, 2));\n if (result.evidence.captured_answer !== \"verified_by_hear\" || (interruption && result.evidence.interruption !== \"simulated_queue_cleared\")) process.exitCode = 1;\n}\n\nmain().catch(error => {\n const message = String(error.message).replaceAll(process.env.PYAI_API_KEY || \"\\0\", \"[REDACTED]\");\n console.error(JSON.stringify({ error: message, ...(error.omni_code ? { code: error.omni_code } : {}) })); process.exitCode = 1;\n});\n",
7
7
  "session.mjs": "import { newAudioCapture, recordAudio, recordTurnBegin, streamPcmRealtime, INTERRUPTION_OBSERVATION } from \"./timing.mjs\";\n\nexport const realClock = {\n now: () => performance.now(),\n sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),\n};\n\n// Only recognized machine codes may leave the example. Error messages, call\n// IDs and arbitrary code values can contain credentials or customer content.\nconst publicErrorCodes = new Set([\n \"invalid_configure\", \"unsupported_tool_transport\", \"tool_configuration_locked\",\n \"media_dead\", \"unauthorized\", \"insufficient_scope\", \"rate_limit_exceeded\",\n \"concurrency_limit_exceeded\", \"daily_cap_exceeded\", \"credit_exhausted\",\n]);\nconst transportErrorCodes = new Set([\"ECONNRESET\", \"ECONNREFUSED\", \"ETIMEDOUT\", \"ENOTFOUND\", \"EAI_AGAIN\"]);\nexport function omniFailure(error) {\n const code = error instanceof Error\n ? (transportErrorCodes.has(error.code) ? error.code : \"transport_or_protocol_error\")\n : (publicErrorCodes.has(error?.code) ? error.code : \"unrecognized_server_error\");\n return Object.assign(new Error(`Omni failed (${code}); no automatic retry was attempted`), { omni_code: code });\n}\n\n/** One bounded, server-side example. Its playback queue is simulated. */\nexport async function runSession({ pyai, webSocket, caller, interruption, clock = realClock, timeoutMs = 60000 }) {\n const rate = 24000, frameSize = 480, silence = new Int16Array(frameSize);\n if (!(caller instanceof Int16Array) || !caller.length || caller.length > rate * 20) throw new Error(\"Provide 1–20 seconds of caller PCM16 at 24 kHz\");\n if (interruption && (!(interruption instanceof Int16Array) || !interruption.length || interruption.length > rate * 20)) throw new Error(\"Invalid interruption PCM\");\n const started = clock.now(), all = newAudioCapture(started), reply = newAudioCapture(started);\n const report = { input_rate: rate, output_rate: null, playback_sink: \"simulated\", tool_calls: 0, tool_executions: 0, duplicate_tool_calls: 0, flushes_after_interruption: 0, cleared_queue_ms: 0, interruption_requested: !!interruption, caller_started_ms: null, interruption_started_ms: null, advisory_transcripts: [], end_reason: \"timeout\" };\n let session, configuredAt = null, closed = false, failure = null, phase = \"greeting\", offset = 0, queueEnd = started, interruptionSent = false, inputEndAt = started;\n const handled = new Set();\n const fail = message => { failure ??= new Error(message); };\n try {\n session = pyai.omni.connect({\n webSocket, rate,\n configure: {\n voice_id: \"stock_amos_en_us\", language: \"en\", greeting: \"Hello. How can I help?\",\n persona: \"When asked about office hours, call lookup_office_hours. Never guess. After the result, say one short sentence giving its opening_time.\",\n tools: [{ name: \"lookup_office_hours\", description: \"Read the synthetic example office opening time.\", side_effect: \"read\", parameters: { type: \"object\", properties: {}, required: [], additionalProperties: false } }],\n },\n onHello: frame => {\n const match = /^pcm16@(8000|24000)$/.exec(frame.audio_out ?? \"\");\n if (!match) return fail(\"Unsupported Omni output format\");\n report.output_rate = Number(match[1]);\n },\n onConfigured: () => { configuredAt ??= clock.now(); },\n onAudio: chunk => {\n if (!report.output_rate) return fail(\"Audio arrived before its output format\");\n const bytes = chunk instanceof ArrayBuffer ? new Uint8Array(chunk) : new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);\n if (bytes.byteLength % 2) return fail(\"Invalid PCM16 output\");\n const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n const pcm = Int16Array.from({ length: bytes.length / 2 }, (_, i) => view.getInt16(i * 2, true));\n const now = clock.now();\n recordAudio(all, pcm, now, report.output_rate);\n queueEnd = Math.max(now, queueEnd) + pcm.length / report.output_rate * 1000;\n if (report.tool_executions) recordAudio(reply, pcm, now, report.output_rate);\n },\n onEvent: frame => {\n if (frame.event === \"turn_begin\") recordTurnBegin(all, clock.now(), frame.turn);\n },\n onTranscript: frame => {\n // An assistant advisory is progress; never treat it as received speech.\n if (report.advisory_transcripts.length < 100) report.advisory_transcripts.push({ role: frame.role, text: frame.text });\n if (frame.role === \"assistant\") all.lastAssistantTranscriptAt = clock.now();\n },\n onToolCall: frame => {\n report.tool_calls++;\n if (handled.has(frame.call_id)) { report.duplicate_tool_calls++; return; }\n handled.add(frame.call_id);\n if (frame.name !== \"lookup_office_hours\") { session.toolResult(frame.call_id, { error: \"Unknown example tool\" }); return; }\n // Replace this read-only fixture with your authorized data lookup.\n report.tool_executions++;\n session.toolResult(frame.call_id, { result: { opening_time: \"9 a.m.\", source: \"synthetic example office\" } });\n },\n onBargeIn: () => {\n const now = clock.now(), queued = Math.max(0, queueEnd - now);\n if (report.interruption_started_ms != null) { report.flushes_after_interruption++; report.cleared_queue_ms += queued; }\n // A real speaker adapter must cancel scheduled and currently playing audio.\n queueEnd = now; all.playbackEndAt = now; reply.playbackEndAt = now;\n },\n onError: error => { failure ??= omniFailure(error); },\n onClose: () => { closed = true; },\n });\n while (clock.now() - started < timeoutMs) {\n if (failure) throw failure;\n if (closed) { report.end_reason = \"closed\"; break; }\n const now = clock.now();\n if (configuredAt == null || !report.output_rate) {\n if (now - started >= 10000) throw new Error(\"Omni connection/configuration timed out\");\n await clock.sleep(20); continue;\n }\n const quietAt = Math.max(queueEnd, all.lastPacketAt ?? now, all.lastAssistantTranscriptAt ?? 0, inputEndAt);\n if (phase === \"greeting\") {\n if (all.firstPacketAt != null && now - configuredAt >= 2000 && now >= quietAt + 800) {\n phase = \"caller\"; report.caller_started_ms = now - started;\n } else if (now - configuredAt > 15000) throw new Error(\"Greeting did not drain within 15 seconds\");\n }\n if (phase === \"reply\" && interruption && !interruptionSent && reply.samples && queueEnd - now >= 200) {\n phase = \"interruption\"; offset = 0; interruptionSent = true; report.interruption_started_ms = now - started;\n }\n const observationEnd = inputEndAt + (interruptionSent ? INTERRUPTION_OBSERVATION.minimumAfterCallerStreamMs : 0);\n if (phase === \"reply\" && reply.samples && now >= quietAt + 2000 && now >= observationEnd && (!interruption || interruptionSent)) {\n report.end_reason = \"quiet_window\"; break;\n }\n // Exactly one producer: each 20 ms slot contains caller PCM OR silence.\n let pcm = silence;\n if (phase === \"caller\" || phase === \"interruption\") {\n const source = phase === \"caller\" ? caller : interruption;\n pcm = source.subarray(offset, offset + frameSize); offset += pcm.length;\n if (offset >= source.length) {\n inputEndAt = now + pcm.length / rate * 1000;\n report[phase === \"caller\" ? \"caller_completed_ms\" : \"interruption_completed_ms\"] = inputEndAt - started;\n phase = \"reply\"; offset = 0;\n }\n }\n await streamPcmRealtime(session, pcm, rate, clock);\n }\n report.audio_bytes = all.samples * 2;\n report.reply_audio_bytes = reply.samples * 2;\n report.elapsed_ms = Math.round(clock.now() - started);\n return { report, audio: all.pcm, replyAudio: reply.pcm };\n } finally { session?.close(); }\n}\n",
package/src/cli.ts CHANGED
@@ -46,7 +46,7 @@ const commands: Command[] = [
46
46
  { command: "init", description: "Create a new project with API context and request examples offline", args: ["directory"], flags: { template: "string" }, example: "pyai init voice-demo --template typescript" },
47
47
  { command: "smoke", description: "Check models, voices, and speech synthesis", flags: { "tolerate-upstream": "boolean" } },
48
48
  { command: "doctor", description: "Diagnose key, catalogs, and a Speak to Hear round-trip" },
49
- { command: "dialer", description: "Open the private desktop calling and meeting-recording app", flags: { port: "string", "no-browser": "boolean", name: "string", "white-label": "boolean" }, example: "pyai dialer --profile production" },
49
+ { command: "dialer", description: "Open the private desktop calling and meeting-recording app", flags: { port: "string", "no-browser": "boolean", name: "string", "white-label": "boolean", transfers: "boolean" }, example: "pyai dialer --profile production" },
50
50
  ...routes.map((r): Command => ({ command: r.command, description: r.description, args: r.id ? ["id"] : [], flags: {
51
51
  ...(r.body ? bodyFlags : {}), ...(r.binary ? outputFlags : {}), ...(r.wait ? waitFlags : {}),
52
52
  ...(r.query ?? {}), ...(r.confirm ? { confirm: "boolean" as const } : {}),
@@ -342,7 +342,7 @@ async function main(): Promise<void> {
342
342
  const { startDialerApp } = await import("./dialer/appServer.ts");
343
343
  const fingerprint = createHash("sha256").update(config.baseURL).update("\0").update(config.apiKey).digest("hex");
344
344
  const sdk = new PyAI({ apiKey: config.apiKey, baseURL: config.baseURL, fetch: (url, init) => fetch(url, { ...init, redirect: "error", signal: init?.signal ?? AbortSignal.timeout(15000) }) });
345
- const app = await startDialerApp({ sdk, userId: `desktop_${fingerprint.slice(0,40)}`, scope: `desktop:${fingerprint}`, port, name: value(flags, "name"), whiteLabel: flags["white-label"] === true });
345
+ const app = await startDialerApp({ sdk, userId: `desktop_${fingerprint.slice(0,40)}`, scope: `desktop:${fingerprint}`, port, name: value(flags, "name"), whiteLabel: flags["white-label"] === true, allowTransfers: flags.transfers === true });
346
346
  output({ url: app.url, local_only: true }, flags, `PyAI Phone is ready at ${app.url}\nKeep this window open. Press Ctrl+C to stop the app and end its owned calls.`);
347
347
  if (flags["no-browser"] || !(await openBrowser(app.launchUrl))) process.stderr.write(`Private one-use launch link (valid for 60 seconds): ${app.launchUrl}\n`);
348
348
  await new Promise<void>(resolve => {
@@ -1,7 +1,7 @@
1
1
  <!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="theme-color" content="#5b55e7"><title>PyAI Phone</title><link rel="icon" href="/icon.svg"><link rel="manifest" href="/manifest.webmanifest"><link rel="stylesheet" href="/app.css"><script type="module" src="/app.js"></script></head><body>
2
2
  <aside><a class="brand" href="/" aria-label="PyAI Phone"><span class="logo">p</span> <span data-brand>PyAI Phone</span></a><nav aria-label="Workspace"><button class="selected" data-tab="calls">Phone <span>↗</span></button><button data-tab="meetings">Meeting recorder <span>◉</span></button></nav><div class="aside-foot"><span class="online"></span> Private workspace<br><small>Powered by PyAI</small></div></aside>
3
3
  <main><header><div><p class="eyebrow">YOUR CONVERSATIONS, TOGETHER</p><h1 data-heading>Make the next connection.</h1><p class="subtitle" data-subtitle>A clear line. A little less busywork.</p></div><span class="local-badge">On this device</span></header>
4
- <div id="error" role="alert"></div><button id="retry" hidden>Retry connection</button><section data-panel="calls"><div class="calling-grid"><div><label class="source-label" for="source">Calling from</label><select id="source" disabled><option>Loading workspace numbers…</option></select><label class="recording-choice"><input id="record-calls" type="checkbox">Record calls · tell the other person before recording</label><pyai-dialer></pyai-dialer></div>
4
+ <div id="error" role="alert"></div><button id="retry" hidden>Retry connection</button><section data-panel="calls"><div class="calling-grid"><div><label class="source-label" for="source">Calling from</label><select id="source" disabled><option>Loading workspace numbers…</option></select><label class="recording-choice"><input id="record-calls" type="checkbox">Record calls · tell the other person before recording</label><label class="recording-choice" id="transfer-choice" hidden><input id="allow-transfers" type="checkbox">Allow transfers · single-line calls</label><pyai-dialer></pyai-dialer></div>
5
5
  <section class="queue-card"><div class="card-top"><span class="eyebrow">STAY IN YOUR FLOW</span><span class="quiet-icon">≋</span></div><h2>One good conversation<br>after another.</h2><p>Paste your contacts and move through them at your own pace. Each call waits for your wrap-up.</p><label for="contacts">Phone numbers, one per line</label><textarea id="contacts" placeholder="+61 2 5550 0100&#10;+1 415 555 0100" spellcheck="false"></textarea><label for="mode">Calling order</label><select id="mode"><option value="auto">In list order</option><option value="dynamic">Highest priority first · number, priority</option><option value="parallel">Two lines at once · first answer connects</option></select><div class="queue-actions"><button id="queue-start" class="primary" disabled>Start calling</button><button id="queue-pause" disabled>Pause queue</button><button id="queue-resume" disabled>Resume queue</button></div><p id="queue-status" role="status" aria-live="polite">You choose when to start. Your workspace calling rules apply to every call.</p></section></div></section>
6
6
  <section data-panel="meetings" hidden><div class="meeting-grid"><div class="meeting-copy"><span class="eyebrow">LESS DISTRACTION, MORE PRESENCE</span><h2>Stay in the<br>conversation.</h2><p>Choose the audio you want to keep. Record your meeting and microphone together, pause when you need to, and save a private audio file.</p><div class="feature"><b>◉</b><span><strong>Your choice of audio</strong>Choose a supported meeting tab or system source in the browser picker.</span></div><div class="feature"><b>▦</b><span><strong>Saved as you go</strong>Committed audio can be recovered after an interrupted tab.</span></div><div class="feature"><b>↧</b><span><strong>Yours to keep</strong>Download your recording. No automatic uploads or hidden capture.</span></div></div><pyai-meeting-recorder></pyai-meeting-recorder></div></section>
7
7
  <footer>Call history and call recordings are stored in your PyAI workspace. Meeting audio stays in this browser until you save or submit it.</footer></main></body></html>
@@ -1,4 +1,4 @@
1
- import { ManagedDialer } from '/modules/managedDialer.js';
1
+ import { ManagedDialer, dialerCallHandedOff } from '/modules/managedDialer.js';
2
2
  import { IndexedDbDialerJournal } from '/modules/indexedDbJournal.js';
3
3
  import { VoiceSdkAudio } from '/modules/voiceSdkAudio.js';
4
4
  import { DialingQueue } from '/modules/dialingQueue.js';
@@ -26,6 +26,7 @@ function renderQueue(){
26
26
  if(!queue)return;const state=queue.current,active=dialer.current.state!=='idle';
27
27
  $('#queue-start').disabled=active||state.running||!config.numbers.length;
28
28
  $('#queue-pause').disabled=!state.running;$('#queue-resume').disabled=state.running||!state.remaining;
29
+ $('#allow-transfers').disabled=active||state.running||$('#mode').value==='parallel';if($('#mode').value==='parallel')$('#allow-transfers').checked=false;
29
30
  $('#source').disabled=active||state.running;$('#mode').disabled=active||state.running;$('#record-calls').disabled=active||state.running;$('#contacts').disabled=state.running||active;
30
31
  $('#queue-status').textContent=state.activeId?`${state.running?'Queue running':'Queue paused'} · ${state.activeIds.length} in this attempt · ${state.remaining} remaining. Finish this call and choose Done to continue.`:state.remaining?`${state.remaining} contacts waiting. Choose Resume queue when ready.`:'You choose when to start. Your workspace calling rules apply to every call.';
31
32
  }
@@ -38,18 +39,18 @@ async function init(){
38
39
  try{localSession=localStorage.getItem('pyai-local-app-session');}catch{throw Error('Private app storage is unavailable. Enable storage for this local app before calling.');}
39
40
  const code=location.hash.slice(1);history.replaceState(null,'',location.pathname);
40
41
  if(code){const unlocked=await request('/api/unlock',{method:'POST',body:JSON.stringify({code})});localSession=unlocked.session_token;localStorage.setItem('pyai-local-app-session',localSession);}
41
- config=await request('/api/config');document.title=config.name;$('[data-brand]').textContent=config.name;
42
+ config=await request('/api/config');$('#transfer-choice').hidden=!config.transfers_enabled;document.title=config.name;$('[data-brand]').textContent=config.name;
42
43
  if(config.white_label){$('.logo').textContent=(config.name.match(/[A-Za-z]/)?.[0]??'P').toUpperCase();$('.aside-foot small').hidden=true;$('footer').textContent='Calls and call recordings stay in your workspace. Meeting audio stays in this browser until you save or submit it.';}
43
44
  const source=$('#source');source.replaceChildren();
44
45
  for(const number of config.numbers){const option=document.createElement('option');option.value=number.id;option.textContent=number.phone_number;source.append(option);}
45
46
  if(!config.numbers.length){const option=document.createElement('option');option.textContent='No active voice numbers in this workspace';source.append(option);}
46
47
  source.disabled=!config.numbers.length;
47
- const broker={create:(input,key)=>request('/api/sessions',{method:'POST',headers:{'idempotency-key':key},body:JSON.stringify(input)}),get:id=>request(`/api/calls/${encodeURIComponent(id)}`),hangup:id=>request(`/api/calls/${encodeURIComponent(id)}/hangup`,{method:'POST',body:'{}'})};
48
+ const broker={create:(input,key)=>request('/api/sessions',{method:'POST',headers:{'idempotency-key':key},body:JSON.stringify(input)}),get:id=>request(`/api/calls/${encodeURIComponent(id)}`),hangup:id=>request(`/api/calls/${encodeURIComponent(id)}/hangup`,{method:'POST',body:'{}'}),transfers:{create:(id,input,key)=>request(`/api/calls/${encodeURIComponent(id)}/transfers`,{method:'POST',headers:{'idempotency-key':key},body:JSON.stringify(input)}),complete:(id,transferId)=>request(`/api/calls/${encodeURIComponent(id)}/transfers/${encodeURIComponent(transferId)}/complete`,{method:'POST',body:'{}'}),cancel:(id,transferId)=>request(`/api/calls/${encodeURIComponent(id)}/transfers/${encodeURIComponent(transferId)}/cancel`,{method:'POST',body:'{}'})}};
48
49
  const transport=new VoiceSdkAudio(token=>new window.Twilio.Device(token,{logLevel:'silent'}));
49
50
  audio={connect:async(...args)=>{const generation=++audioGeneration;await loadMedia();if(generation!==audioGeneration)throw Error('Calling audio was cancelled.');return transport.connect(...args);},disconnect:()=>{++audioGeneration;transport.disconnect();},mute:value=>transport.mute(value),sendDigits:digits=>transport.sendDigits(digits)};
50
51
  dialer=new ManagedDialer(config.scope,broker,new IndexedDbDialerJournal(),audio);
51
52
  await dialer.restore();
52
- const inputFor=to=>({from_number_id:source.value,to,user_id:config.user_id,client_reference:crypto.randomUUID(),recording:$('#record-calls').checked,max_duration_seconds:3600,use_case:'support'});
53
+ const inputFor=to=>({from_number_id:source.value,to,user_id:config.user_id,client_reference:crypto.randomUUID(),recording:$('#record-calls').checked,max_duration_seconds:3600,use_case:'support',...(config.transfers_enabled&&$('#allow-transfers').checked?{transfer_enabled:true}:{})});
53
54
  queue=new DialingQueue(dialer,async contact=>{const latest=await request('/api/config');return latest.scope===config.scope&&latest.numbers.some(n=>n.id===contact.input.from_number_id);});
54
55
  $('pyai-dialer').bind(dialer,to=>{
55
56
  if(!config.numbers.length)throw Error('Add a voice number in your PyAI workspace before calling.');
@@ -65,10 +66,11 @@ async function init(){
65
66
  return {id:crypto.randomUUID(),input:inputFor(to),priority:Number(priority)};
66
67
  });await queue.start(contacts,$('#mode').value);renderQueue();
67
68
  }));
69
+ $('#mode').addEventListener('change',renderQueue);
68
70
  $('#queue-pause').addEventListener('click',()=>{queue.pause();renderQueue();});$('#queue-resume').addEventListener('click',()=>void act(async()=>{await queue.resume();renderQueue();}));
69
71
  window.addEventListener('pagehide',()=>{
70
72
  closed=true;clearTimeout(poll);queue.pause();audio.disconnect();void recorder.stop();
71
- const id=dialer.current.callId;if(id&&!['idle','wrapup'].includes(dialer.current.state))void fetch(`/api/calls/${encodeURIComponent(id)}/hangup`,{method:'POST',headers:{'content-type':'application/json','x-pyai-local-session':config.nonce,authorization:`Bearer ${localSession}`},body:'{}',keepalive:true}).catch(()=>{});
73
+ const id=dialer.current.callId;if(id&&!['idle','wrapup','transferred','handing_off'].includes(dialer.current.state)&&!dialerCallHandedOff(dialer.current.call??{}))void fetch(`/api/calls/${encodeURIComponent(id)}/hangup`,{method:'POST',headers:{'content-type':'application/json','x-pyai-local-session':config.nonce,authorization:`Bearer ${localSession}`},body:'{}',keepalive:true}).catch(()=>{});
72
74
  });
73
75
  void refresh();
74
76
  }
@@ -8,6 +8,7 @@ import { dirname, join } from "node:path";
8
8
  import { Readable } from "node:stream";
9
9
  import type { PyAI, TelephonyBrowserSessionCreate, TelephonyCall } from "../index.ts";
10
10
  import { createServerDialerBroker } from "./serverBroker.ts";
11
+ import { dialerCallHandedOff } from "./managedDialer.ts";
11
12
 
12
13
  export interface DialerAppOptions {
13
14
  sdk: PyAI;
@@ -16,6 +17,8 @@ export interface DialerAppOptions {
16
17
  scope: string;
17
18
  name?: string;
18
19
  whiteLabel?: boolean;
20
+ /** Operator opt-in; the API independently enforces transfer activation. */
21
+ allowTransfers?: boolean;
19
22
  port?: number;
20
23
  /** Explicit asset injection for packaging/tests, never selected by HTTP. */
21
24
  assets?: { read(path: string): Promise<Uint8Array> };
@@ -60,7 +63,7 @@ export async function startDialerApp(options: DialerAppOptions) {
60
63
  const bootstrap = randomBytes(32).toString("base64url"), rendererToken = randomBytes(32).toString("base64url"), bootstrapExpires = Date.now() + 60000;
61
64
  let bootstrapUsed = false;
62
65
  let origin = "", closing = false; const calls = new Set<string>();
63
- const remember = (call: TelephonyCall) => { if (terminal(call)) calls.delete(call.id); else calls.add(call.id); return call; };
66
+ const remember = (call: TelephonyCall) => { if (terminal(call) || dialerCallHandedOff(call)) calls.delete(call.id); else calls.add(call.id); return call; };
64
67
  const numbers = async () => (await options.sdk.telephony.numbers.list()).data.filter(number => number.status !== "released" && number.capabilities?.voice === true);
65
68
  const own = async (id: string) => remember(await broker.get(id));
66
69
  const server = createServer(async (request, response) => {
@@ -87,16 +90,29 @@ export async function startDialerApp(options: DialerAppOptions) {
87
90
  }
88
91
  if (url.pathname === "/api/config" && method === "GET") {
89
92
  const owned = await numbers();
90
- return json(response, 200, { name: options.name ?? (options.whiteLabel ? "Phone" : "PyAI Phone"), white_label: options.whiteLabel === true, scope: options.scope, user_id: options.userId, nonce,
93
+ return json(response, 200, { name: options.name ?? (options.whiteLabel ? "Phone" : "PyAI Phone"), white_label: options.whiteLabel === true, transfers_enabled: options.allowTransfers === true, scope: options.scope, user_id: options.userId, nonce,
91
94
  numbers: owned.map(number => ({ id: number.id, phone_number: number.phone_number, country: number.country })) });
92
95
  }
93
96
  if (url.pathname === "/api/sessions" && method === "POST") {
94
97
  if (closing) throw new AppError(503, "Dialer is closing. No new calls are admitted.");
95
98
  const input = await body(request), key = request.headers["idempotency-key"];
99
+ if (input.transfer_enabled === true && options.allowTransfers !== true) throw new AppError(400, "Open this dialer with transfers enabled before starting a transferable call.");
96
100
  if (typeof key !== "string" || typeof input.from_number_id !== "string" || !(await numbers()).some(number => number.id === input.from_number_id)) throw new AppError(400, "Choose an owned voice number and a calling retry key.");
97
101
  const session = await broker.create(input as unknown as TelephonyBrowserSessionCreate, key); remember(session.call);
98
102
  return json(response, 200, session);
99
103
  }
104
+ const transferPath = /^\/api\/calls\/([A-Za-z0-9_-]{1,200})\/transfers(?:\/([A-Za-z0-9_-]{1,200})\/(complete|cancel))?$/.exec(url.pathname);
105
+ if (transferPath && method === "POST") {
106
+ if (closing || options.allowTransfers !== true) throw new AppError(503, "Transfers are not enabled in this dialer.");
107
+ const id = transferPath[1]!, transferId = transferPath[2], operation = transferPath[3];
108
+ await own(id); const input = await body(request);
109
+ if (transferId && (operation === "complete" || operation === "cancel"))
110
+ return json(response, 202, remember(await broker.transfers![operation](id, transferId)));
111
+ const key = request.headers["idempotency-key"];
112
+ if (typeof key !== "string" || typeof input.to !== "string" || !/^\+[1-9]\d{6,14}$/.test(input.to) || !["warm", "cold"].includes(String(input.mode)))
113
+ throw new AppError(400, "Choose a transfer destination, mode and retry key.");
114
+ return json(response, 202, remember(await broker.transfers!.create(id, { to: input.to, mode: input.mode as "warm" | "cold" }, key)));
115
+ }
100
116
  const callPath = /^\/api\/calls\/([A-Za-z0-9_-]{1,200})(?:\/(hangup|recording))?$/.exec(url.pathname);
101
117
  if (callPath) {
102
118
  const id = callPath[1]!, operation = callPath[2]; await own(id);