@pyai/sdk 0.15.0 → 0.17.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.
- package/README.md +2 -2
- package/dist/cli-omni-template.d.ts +2 -2
- package/dist/cli-omni-template.js +2 -2
- package/dist/dialer/dialerElement.js +1 -1
- package/dist/dialer/managedDialer.d.ts +3 -1
- package/dist/dialer/managedDialer.js +4 -2
- package/dist/dialer/serverBroker.js +17 -5
- package/dist/index.d.ts +144 -3
- package/dist/index.js +16 -1
- package/package.json +1 -1
- package/src/cli-omni-template.ts +2 -2
- package/src/dialer/dialerElement.ts +1 -1
- package/src/dialer/managedDialer.ts +6 -3
- package/src/dialer/serverBroker.ts +15 -4
- package/src/index.ts +110 -3
package/README.md
CHANGED
|
@@ -106,12 +106,12 @@ the instant the socket opens and routes server frames to typed callbacks, so you
|
|
|
106
106
|
is acked but silently dropped, giving you a connected session with zero turns):
|
|
107
107
|
|
|
108
108
|
<!-- omni-starter:start -->
|
|
109
|
-
Requires SDK 0.
|
|
109
|
+
Requires SDK 0.17.0 for `--template omni`. The runnable starter uses ESM,
|
|
110
110
|
Node 20.19+ with an explicit `ws` transport, or Node 22+. MCP 0.5.1
|
|
111
111
|
requires Node 22+. The SDK's REST client continues to support Node 18+.
|
|
112
112
|
|
|
113
113
|
```sh
|
|
114
|
-
npm install @pyai/sdk@0.
|
|
114
|
+
npm install @pyai/sdk@0.17.0
|
|
115
115
|
npx pyai init voice-demo --template omni
|
|
116
116
|
cd voice-demo
|
|
117
117
|
npm install
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
export declare const omniTemplate: Readonly<{
|
|
2
|
-
"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.
|
|
3
|
-
"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.
|
|
2
|
+
"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.17.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";
|
|
3
|
+
"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.17.0\",\n \"ws\": \"^8.18.3\"\n }\n}\n";
|
|
4
4
|
"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";
|
|
5
5
|
"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";
|
|
6
6
|
"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";
|
|
@@ -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.
|
|
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.
|
|
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.17.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.17.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",
|
|
@@ -109,7 +109,7 @@ export class PyaiDialerElement extends HTMLElement {
|
|
|
109
109
|
complete.hidden = transfer?.mode !== "warm" || transfer.status !== "ready";
|
|
110
110
|
complete.disabled = Boolean(snapshot.transferPending);
|
|
111
111
|
const cancel = this.root.querySelector("[data-action=cancel-transfer]");
|
|
112
|
-
cancel.hidden = transfer
|
|
112
|
+
cancel.hidden = !transfer || !pending;
|
|
113
113
|
cancel.disabled = Boolean(snapshot.transferPending || ["completing", "canceling"].includes(transfer?.status ?? ""));
|
|
114
114
|
this.root.querySelector("[data-action=recover-transfer]").hidden = !snapshot.transferPending;
|
|
115
115
|
}
|
|
@@ -1,10 +1,12 @@
|
|
|
1
|
-
import type { TelephonyBrowserSession, TelephonyBrowserSessionCreate, TelephonyCall } from "../index.ts";
|
|
1
|
+
import type { TelephonyBrowserSession, TelephonyBrowserSessionCreate, TelephonyCall, TelephonyCallControl } from "../index.ts";
|
|
2
2
|
/** Implement on your server using PyAI's telephony client. The browser receives
|
|
3
3
|
* a single-call capability, never an organization key or carrier credential. */
|
|
4
4
|
export interface DialerBroker {
|
|
5
5
|
create(input: TelephonyBrowserSessionCreate, idempotencyKey: string): Promise<TelephonyBrowserSession>;
|
|
6
6
|
get(callId: string): Promise<TelephonyCall>;
|
|
7
7
|
hangup(callId: string): Promise<TelephonyCall>;
|
|
8
|
+
setHold?(callId: string, held: boolean, key: string): Promise<TelephonyCall>;
|
|
9
|
+
sendDtmf?(callId: string, digits: string, key: string): Promise<TelephonyCallControl>;
|
|
8
10
|
transfers?: {
|
|
9
11
|
create(callId: string, input: {
|
|
10
12
|
to: string;
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
const terminal = (call) => ["completed", "failed", "canceled"].includes(call.status);
|
|
2
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" &&
|
|
3
|
+
export const dialerCallHandedOff = (call) => call.transfer_enabled === true && Boolean(call.transfers?.some(transfer => transfer.status === "completed" || transfer.mode === "cold" && transfer.status === "completing"));
|
|
4
4
|
/** One immutable workspace/user scope per instance. Setup and stop retain the
|
|
5
5
|
* original intent through lost acknowledgments, reloads and audio failures. */
|
|
6
6
|
export class ManagedDialer {
|
|
@@ -291,8 +291,10 @@ export class ManagedDialer {
|
|
|
291
291
|
const transfer = this.snapshot.call?.transfers?.find(item => item.id === this.intent.transfer.id);
|
|
292
292
|
if (command === "complete" && transfer?.status !== "ready")
|
|
293
293
|
throw new Error("Wait until the transfer target has joined.");
|
|
294
|
-
if (this.intent.transfer.mode !== "warm")
|
|
294
|
+
if (this.intent.transfer.mode !== "warm" && command === "complete")
|
|
295
295
|
throw new Error("Cold transfers complete automatically.");
|
|
296
|
+
if (command === "cancel" && ["completing", "completed"].includes(transfer?.status ?? ""))
|
|
297
|
+
throw new Error("The handoff has started. Check its status instead of canceling it.");
|
|
296
298
|
if (this.intent.transfer.command && this.intent.transfer.command !== command)
|
|
297
299
|
throw new Error("Recover the saved transfer command first.");
|
|
298
300
|
const next = structuredClone(this.intent);
|
|
@@ -1,6 +1,5 @@
|
|
|
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";
|
|
4
3
|
export function createServerDialerBroker(sdk, authenticatedUserId) {
|
|
5
4
|
if (!authenticatedUserId.trim())
|
|
6
5
|
throw new Error("An authenticated user is required.");
|
|
@@ -20,10 +19,23 @@ export function createServerDialerBroker(sdk, authenticatedUserId) {
|
|
|
20
19
|
},
|
|
21
20
|
get: ownedCall,
|
|
22
21
|
async hangup(id) {
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
22
|
+
await ownedCall(id);
|
|
23
|
+
// The provider rechecks handoff ownership in the stop CAS, after this read.
|
|
24
|
+
return sdk.telephony.calls.hangup(id, { user_id: authenticatedUserId });
|
|
25
|
+
},
|
|
26
|
+
async setHold(id, held, key) {
|
|
27
|
+
await ownedCall(id);
|
|
28
|
+
if (!key || key.length > 255 || /[\r\n]/.test(key))
|
|
29
|
+
throw new Error("A valid hold retry key is required.");
|
|
30
|
+
const scopedKey = "dialer-hold:" + createHash("sha256").update(authenticatedUserId).update("\0").update(id).update("\0").update(key).digest("hex");
|
|
31
|
+
return sdk.telephony.calls.setHold(id, { held, user_id: authenticatedUserId }, { idempotencyKey: scopedKey });
|
|
32
|
+
},
|
|
33
|
+
async sendDtmf(id, digits, key) {
|
|
34
|
+
await ownedCall(id);
|
|
35
|
+
if (!key || key.length > 255 || /[\r\n]/.test(key))
|
|
36
|
+
throw new Error("A valid keypad retry key is required.");
|
|
37
|
+
const scopedKey = "dialer-keypad:" + createHash("sha256").update(authenticatedUserId).update("\0").update(id).update("\0").update(key).digest("hex");
|
|
38
|
+
return sdk.telephony.calls.sendDtmf(id, { digits, user_id: authenticatedUserId }, { idempotencyKey: scopedKey });
|
|
27
39
|
},
|
|
28
40
|
transfers: {
|
|
29
41
|
async create(id, input, key) {
|
package/dist/index.d.ts
CHANGED
|
@@ -857,7 +857,18 @@ export interface TelephonyCall {
|
|
|
857
857
|
agent_id: string | null;
|
|
858
858
|
call_type?: "human";
|
|
859
859
|
transfer_enabled?: boolean;
|
|
860
|
+
held?: boolean;
|
|
861
|
+
hold_pending?: boolean;
|
|
860
862
|
transfers?: TelephonyTransfer[];
|
|
863
|
+
forwarding?: {
|
|
864
|
+
to: string | null;
|
|
865
|
+
status: "waiting" | "claimed" | "unknown" | "acknowledged" | "canceled";
|
|
866
|
+
menu?: {
|
|
867
|
+
kind: "keypad";
|
|
868
|
+
status: "pending" | "selected" | "rejected";
|
|
869
|
+
choice_id: string | null;
|
|
870
|
+
};
|
|
871
|
+
};
|
|
861
872
|
user_id?: string;
|
|
862
873
|
client_reference: string | null;
|
|
863
874
|
stop_requested: boolean;
|
|
@@ -874,6 +885,44 @@ export interface TelephonyTransfer {
|
|
|
874
885
|
status: "holding" | "dialing" | "ready" | "completing" | "canceling" | "completed" | "canceled" | "failed";
|
|
875
886
|
to: string | null;
|
|
876
887
|
}
|
|
888
|
+
export interface TelephonyCallQuality {
|
|
889
|
+
call_id: string;
|
|
890
|
+
status: "available" | "unavailable";
|
|
891
|
+
reason: string | null;
|
|
892
|
+
source: "managed_transport" | null;
|
|
893
|
+
scope: "caller_to_platform" | null;
|
|
894
|
+
observation: "terminal_snapshot" | "partial_snapshot" | null;
|
|
895
|
+
observed_at: string | null;
|
|
896
|
+
live: false;
|
|
897
|
+
metrics: Record<"packets_received" | "packets_lost" | "packets_reordered" | "duplicate_packets" | "packets_sent" | "playout_frames" | "concealed_frames" | "late_frames" | "playout_duplicates" | "jitter_ms" | "packet_loss_percent" | "concealment_percent", number | null> & {
|
|
898
|
+
mos: null;
|
|
899
|
+
rtt_ms: null;
|
|
900
|
+
};
|
|
901
|
+
unavailable_metrics: string[];
|
|
902
|
+
}
|
|
903
|
+
export interface TelephonyCallCapabilities {
|
|
904
|
+
object: "telephony.call_capabilities";
|
|
905
|
+
call_id: string;
|
|
906
|
+
version: 1;
|
|
907
|
+
call_type: "human" | "ai";
|
|
908
|
+
controls: Record<"hangup" | "hold" | "warm_transfer" | "cold_transfer" | "complete_transfer" | "cancel_transfer" | "listen" | "whisper" | "barge", {
|
|
909
|
+
supported: boolean;
|
|
910
|
+
reason: string | null;
|
|
911
|
+
}>;
|
|
912
|
+
client_controls: Array<"mute" | "dtmf">;
|
|
913
|
+
quality: {
|
|
914
|
+
read_supported: true;
|
|
915
|
+
live: false;
|
|
916
|
+
};
|
|
917
|
+
revalidation_required: true;
|
|
918
|
+
}
|
|
919
|
+
export interface TelephonyCallControl {
|
|
920
|
+
object: "telephony.call_control";
|
|
921
|
+
id: string;
|
|
922
|
+
call_id: string;
|
|
923
|
+
action: "send_dtmf";
|
|
924
|
+
status: "acknowledged" | "unknown" | "rejected";
|
|
925
|
+
}
|
|
877
926
|
export interface TelephonyCallCreate {
|
|
878
927
|
from_number_id: string;
|
|
879
928
|
to: string;
|
|
@@ -925,6 +974,15 @@ export interface TelephonyAvailableNumber {
|
|
|
925
974
|
region?: string | null;
|
|
926
975
|
capabilities?: TelephonyCapabilities;
|
|
927
976
|
monthly_cost_cents?: number;
|
|
977
|
+
/** Bind purchase to the exact account/market inventory result. */
|
|
978
|
+
inventory_reference?: string;
|
|
979
|
+
}
|
|
980
|
+
export interface TelephonyNumberInventory extends ListResponse<TelephonyAvailableNumber> {
|
|
981
|
+
provisioning?: {
|
|
982
|
+
mode: "automated" | "assisted";
|
|
983
|
+
capability: string;
|
|
984
|
+
message: string;
|
|
985
|
+
};
|
|
928
986
|
}
|
|
929
987
|
export interface TelephonyNumber {
|
|
930
988
|
object?: "telephony.number";
|
|
@@ -947,7 +1005,7 @@ export interface TelephonyNumberOrder {
|
|
|
947
1005
|
id: string;
|
|
948
1006
|
status: "pending" | "unknown" | "completed" | "failed" | "released";
|
|
949
1007
|
phone_number: string;
|
|
950
|
-
country: "AU";
|
|
1008
|
+
country: "AU" | "US" | "CA";
|
|
951
1009
|
project_id: string;
|
|
952
1010
|
retry_after_seconds: number;
|
|
953
1011
|
message: string;
|
|
@@ -956,12 +1014,72 @@ export interface TelephonyNumberOrder {
|
|
|
956
1014
|
}
|
|
957
1015
|
export interface TelephonyNumberPurchase {
|
|
958
1016
|
phone_number: string;
|
|
1017
|
+
country?: "US" | "CA" | "IN" | "AU";
|
|
1018
|
+
inventory_reference?: string;
|
|
959
1019
|
agent_id?: string | null;
|
|
960
1020
|
provisioning_mode?: "automated" | "adopt_preowned";
|
|
961
1021
|
project_id?: string;
|
|
962
1022
|
compliance_case_id?: string;
|
|
963
1023
|
max_monthly_cost_cents?: number;
|
|
964
1024
|
}
|
|
1025
|
+
export interface TelephonyInboundBinding {
|
|
1026
|
+
object: "telephony.inbound_binding";
|
|
1027
|
+
number_id: string;
|
|
1028
|
+
version: number;
|
|
1029
|
+
enabled: boolean;
|
|
1030
|
+
project_id?: string;
|
|
1031
|
+
agent_id?: string;
|
|
1032
|
+
agent_release_id?: string;
|
|
1033
|
+
agent_profile_sha256?: string;
|
|
1034
|
+
admission_mode?: "client" | "platform";
|
|
1035
|
+
forward?: TelephonyInboundForward | null;
|
|
1036
|
+
carrier_operation?: {
|
|
1037
|
+
id: string;
|
|
1038
|
+
phase: "pending" | "unknown" | "active" | "rollback_pending" | "rolled_back";
|
|
1039
|
+
action: "activate" | "rollback";
|
|
1040
|
+
};
|
|
1041
|
+
}
|
|
1042
|
+
export interface TelephonyInboundMenu {
|
|
1043
|
+
/** Saved single-digit spoken menu before forwarding. */
|
|
1044
|
+
kind: "keypad";
|
|
1045
|
+
prompt: string;
|
|
1046
|
+
choices: Array<{
|
|
1047
|
+
id: string;
|
|
1048
|
+
key: string;
|
|
1049
|
+
to: string;
|
|
1050
|
+
}>;
|
|
1051
|
+
timeout_seconds: number;
|
|
1052
|
+
/** null hangs up; otherwise the ID of one saved choice. */
|
|
1053
|
+
timeout_choice_id: string | null;
|
|
1054
|
+
}
|
|
1055
|
+
export type TelephonyInboundForward = {
|
|
1056
|
+
max_duration_seconds: number;
|
|
1057
|
+
recording: boolean;
|
|
1058
|
+
} & ({
|
|
1059
|
+
to: string;
|
|
1060
|
+
menu?: never;
|
|
1061
|
+
} | {
|
|
1062
|
+
to?: never;
|
|
1063
|
+
menu: TelephonyInboundMenu;
|
|
1064
|
+
});
|
|
1065
|
+
export type TelephonyInboundBindingUpdate = {
|
|
1066
|
+
expected_version: number;
|
|
1067
|
+
activate_carrier_route?: boolean;
|
|
1068
|
+
rollback_carrier_route?: boolean;
|
|
1069
|
+
/** Persist the original operation ID; recover it instead of inventing a new one. */
|
|
1070
|
+
carrier_operation_id?: string;
|
|
1071
|
+
} & ({
|
|
1072
|
+
enabled: false;
|
|
1073
|
+
} | {
|
|
1074
|
+
enabled: true;
|
|
1075
|
+
project_id: string;
|
|
1076
|
+
agent_id: string;
|
|
1077
|
+
agent_release_id: string;
|
|
1078
|
+
agent_profile_sha256: string;
|
|
1079
|
+
admission_mode?: "client" | "platform";
|
|
1080
|
+
agent_knowledge_receipt?: Record<string, unknown>;
|
|
1081
|
+
forward?: TelephonyInboundForward | null;
|
|
1082
|
+
});
|
|
965
1083
|
export type TraceVerdict = "PASS" | "WARN" | "FAIL";
|
|
966
1084
|
export type TraceSeverity = "low" | "medium" | "high" | "critical";
|
|
967
1085
|
export interface TraceInteraction {
|
|
@@ -1507,6 +1625,8 @@ export declare class PyAI {
|
|
|
1507
1625
|
idempotencyKey: string;
|
|
1508
1626
|
}) => Promise<TelephonyCall>;
|
|
1509
1627
|
get: (id: string) => Promise<TelephonyCall>;
|
|
1628
|
+
capabilities: (id: string) => Promise<TelephonyCallCapabilities>;
|
|
1629
|
+
quality: (id: string) => Promise<TelephonyCallQuality>;
|
|
1510
1630
|
list: (input?: {
|
|
1511
1631
|
limit?: number;
|
|
1512
1632
|
cursor?: string;
|
|
@@ -1516,7 +1636,9 @@ export declare class PyAI {
|
|
|
1516
1636
|
next_cursor: string | null;
|
|
1517
1637
|
}>;
|
|
1518
1638
|
/** Durable stop intent; use get() until a terminal status is confirmed. */
|
|
1519
|
-
hangup: (id: string
|
|
1639
|
+
hangup: (id: string, input?: {
|
|
1640
|
+
user_id: string;
|
|
1641
|
+
}) => Promise<TelephonyCall>;
|
|
1520
1642
|
decideAdmission: (id: string, input: {
|
|
1521
1643
|
decision: "accept" | "reject";
|
|
1522
1644
|
client_reference: string;
|
|
@@ -1526,6 +1648,21 @@ export declare class PyAI {
|
|
|
1526
1648
|
range?: string;
|
|
1527
1649
|
}) => Promise<Response>;
|
|
1528
1650
|
deleteRecording: (id: string) => Promise<void>;
|
|
1651
|
+
/** The same durable key recovers an uncertain hold command without repeating it. */
|
|
1652
|
+
setHold: (id: string, input: {
|
|
1653
|
+
user_id: string;
|
|
1654
|
+
held: boolean;
|
|
1655
|
+
}, options: {
|
|
1656
|
+
idempotencyKey: string;
|
|
1657
|
+
}) => Promise<TelephonyCall>;
|
|
1658
|
+
/** Server-side keypad command for an owned switch call. Reuse the same key
|
|
1659
|
+
* after an unknown result; never store keypad digits in a browser journal. */
|
|
1660
|
+
sendDtmf: (id: string, input: {
|
|
1661
|
+
digits: string;
|
|
1662
|
+
user_id: string;
|
|
1663
|
+
}, options: {
|
|
1664
|
+
idempotencyKey: string;
|
|
1665
|
+
}) => Promise<TelephonyCallControl>;
|
|
1529
1666
|
transfers: {
|
|
1530
1667
|
/** Persist the key and target before requesting a consultation. */
|
|
1531
1668
|
create: (id: string, input: {
|
|
@@ -1552,7 +1689,7 @@ export declare class PyAI {
|
|
|
1552
1689
|
areaCode?: string;
|
|
1553
1690
|
contains?: string;
|
|
1554
1691
|
limit?: number;
|
|
1555
|
-
}) => Promise<
|
|
1692
|
+
}) => Promise<TelephonyNumberInventory>;
|
|
1556
1693
|
/** List the org's managed numbers (active only unless `includeReleased`). */
|
|
1557
1694
|
list: (params?: {
|
|
1558
1695
|
includeReleased?: boolean;
|
|
@@ -1563,6 +1700,10 @@ export declare class PyAI {
|
|
|
1563
1700
|
}) => Promise<TelephonyNumber | TelephonyNumberOrder>;
|
|
1564
1701
|
/** Route a number to an agent (`agentId: null` to unassign). */
|
|
1565
1702
|
assign: (id: string, agentId: string | null) => Promise<TelephonyNumber>;
|
|
1703
|
+
getInboundBinding: (id: string) => Promise<TelephonyInboundBinding>;
|
|
1704
|
+
/** Save the profile and stable operation first; after uncertainty read the
|
|
1705
|
+
* binding before explicitly recovering that same operation. */
|
|
1706
|
+
setInboundBinding: (id: string, input: TelephonyInboundBindingUpdate) => Promise<TelephonyInboundBinding>;
|
|
1566
1707
|
/** Release a number back to the carrier (idempotent). */
|
|
1567
1708
|
release: (id: string) => Promise<TelephonyNumber>;
|
|
1568
1709
|
};
|
package/dist/index.js
CHANGED
|
@@ -1183,6 +1183,8 @@ export class PyAI {
|
|
|
1183
1183
|
calls: {
|
|
1184
1184
|
create: (input, options) => this.postJson("/v1/telephony/calls", input, telephonyIdempotencyHeader(options.idempotencyKey)),
|
|
1185
1185
|
get: (id) => this.getJson(`/v1/telephony/calls/${encodeURIComponent(id)}`),
|
|
1186
|
+
capabilities: (id) => this.getJson(`/v1/telephony/calls/${encodeURIComponent(id)}/capabilities`),
|
|
1187
|
+
quality: (id) => this.getJson(`/v1/telephony/calls/${encodeURIComponent(id)}/quality`),
|
|
1186
1188
|
list: (input = {}) => {
|
|
1187
1189
|
const query = new URLSearchParams();
|
|
1188
1190
|
for (const [key, value] of Object.entries(input))
|
|
@@ -1191,10 +1193,19 @@ export class PyAI {
|
|
|
1191
1193
|
return this.getJson(`/v1/telephony/calls${query.size ? `?${query}` : ""}`);
|
|
1192
1194
|
},
|
|
1193
1195
|
/** Durable stop intent; use get() until a terminal status is confirmed. */
|
|
1194
|
-
hangup: (id) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/hangup`, {}),
|
|
1196
|
+
hangup: (id, input) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/hangup`, input ?? {}),
|
|
1195
1197
|
decideAdmission: (id, input) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/admission`, input),
|
|
1196
1198
|
recording: (id, options = {}) => this.request(`/v1/telephony/calls/${encodeURIComponent(id)}/recording`, { headers: this.authHeaders(options.range ? { Range: options.range } : {}) }),
|
|
1197
1199
|
deleteRecording: async (id) => { await this.deleteReq(`/v1/telephony/calls/${encodeURIComponent(id)}/recording`); },
|
|
1200
|
+
/** The same durable key recovers an uncertain hold command without repeating it. */
|
|
1201
|
+
setHold: (id, input, options) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/hold`, input, telephonyIdempotencyHeader(options.idempotencyKey)),
|
|
1202
|
+
/** Server-side keypad command for an owned switch call. Reuse the same key
|
|
1203
|
+
* after an unknown result; never store keypad digits in a browser journal. */
|
|
1204
|
+
sendDtmf: (id, input, options) => {
|
|
1205
|
+
if (!/^[0-9A-D*#]{1,32}$/.test(input.digits))
|
|
1206
|
+
throw new Error("Use 1–32 keypad digits (0–9, *, #, A–D).");
|
|
1207
|
+
return this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/dtmf`, input, telephonyIdempotencyHeader(options.idempotencyKey));
|
|
1208
|
+
},
|
|
1198
1209
|
transfers: {
|
|
1199
1210
|
/** Persist the key and target before requesting a consultation. */
|
|
1200
1211
|
create: (id, input, options) => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/transfers`, input, telephonyIdempotencyHeader(options.idempotencyKey)),
|
|
@@ -1230,6 +1241,10 @@ export class PyAI {
|
|
|
1230
1241
|
buy: (params, options) => this.postJson("/v1/telephony/numbers", params, telephonyIdempotencyHeader(options.idempotencyKey)),
|
|
1231
1242
|
/** Route a number to an agent (`agentId: null` to unassign). */
|
|
1232
1243
|
assign: (id, agentId) => this.postJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/assign`, { agent_id: agentId }),
|
|
1244
|
+
getInboundBinding: (id) => this.getJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/inbound-binding`),
|
|
1245
|
+
/** Save the profile and stable operation first; after uncertainty read the
|
|
1246
|
+
* binding before explicitly recovering that same operation. */
|
|
1247
|
+
setInboundBinding: (id, input) => this.putJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/inbound-binding`, input),
|
|
1233
1248
|
/** Release a number back to the carrier (idempotent). */
|
|
1234
1249
|
release: async (id) => {
|
|
1235
1250
|
const res = await this.deleteReq(`/v1/telephony/numbers/${encodeURIComponent(id)}`);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pyai/sdk",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.17.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",
|
package/src/cli-omni-template.ts
CHANGED
|
@@ -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.
|
|
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.
|
|
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.17.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.17.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",
|
|
@@ -88,7 +88,7 @@ export class PyaiDialerElement extends HTMLElement {
|
|
|
88
88
|
const complete = this.root.querySelector<HTMLButtonElement>("[data-action=complete-transfer]")!;
|
|
89
89
|
complete.hidden = transfer?.mode !== "warm" || transfer.status !== "ready"; complete.disabled = Boolean(snapshot.transferPending);
|
|
90
90
|
const cancel = this.root.querySelector<HTMLButtonElement>("[data-action=cancel-transfer]")!;
|
|
91
|
-
cancel.hidden = transfer
|
|
91
|
+
cancel.hidden = !transfer || !pending; cancel.disabled = Boolean(snapshot.transferPending || ["completing", "canceling"].includes(transfer?.status ?? ""));
|
|
92
92
|
this.root.querySelector<HTMLButtonElement>("[data-action=recover-transfer]")!.hidden = !snapshot.transferPending;
|
|
93
93
|
}
|
|
94
94
|
private async run(action: () => Promise<void>) {
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import type { TelephonyBrowserSession, TelephonyBrowserSessionCreate, TelephonyCall } from "../index.ts";
|
|
1
|
+
import type { TelephonyBrowserSession, TelephonyBrowserSessionCreate, TelephonyCall, TelephonyCallControl } from "../index.ts";
|
|
2
2
|
|
|
3
3
|
/** Implement on your server using PyAI's telephony client. The browser receives
|
|
4
4
|
* a single-call capability, never an organization key or carrier credential. */
|
|
@@ -6,6 +6,8 @@ export interface DialerBroker {
|
|
|
6
6
|
create(input: TelephonyBrowserSessionCreate, idempotencyKey: string): Promise<TelephonyBrowserSession>;
|
|
7
7
|
get(callId: string): Promise<TelephonyCall>;
|
|
8
8
|
hangup(callId: string): Promise<TelephonyCall>;
|
|
9
|
+
setHold?(callId: string, held: boolean, key: string): Promise<TelephonyCall>;
|
|
10
|
+
sendDtmf?(callId: string, digits: string, key: string): Promise<TelephonyCallControl>;
|
|
9
11
|
transfers?: {
|
|
10
12
|
create(callId: string, input: { to: string; mode: "warm" | "cold" }, key: string): Promise<TelephonyCall>;
|
|
11
13
|
complete(callId: string, transferId: string): Promise<TelephonyCall>;
|
|
@@ -44,7 +46,7 @@ export interface DialerSnapshot {
|
|
|
44
46
|
const terminal = (call: TelephonyCall) => ["completed", "failed", "canceled"].includes(call.status);
|
|
45
47
|
/** A durable handoff keeps its original room after the browser goes away. */
|
|
46
48
|
export const dialerCallHandedOff = (call: TelephonyCall) => call.transfer_enabled === true && Boolean(call.transfers?.some(transfer =>
|
|
47
|
-
transfer.status === "completed" || transfer.mode === "cold" &&
|
|
49
|
+
transfer.status === "completed" || transfer.mode === "cold" && transfer.status === "completing"));
|
|
48
50
|
|
|
49
51
|
/** One immutable workspace/user scope per instance. Setup and stop retain the
|
|
50
52
|
* original intent through lost acknowledgments, reloads and audio failures. */
|
|
@@ -257,7 +259,8 @@ export class ManagedDialer {
|
|
|
257
259
|
if (!this.intent?.transfer?.id || !this.broker.transfers) throw new Error("Recover the transfer identity first.");
|
|
258
260
|
const transfer = this.snapshot.call?.transfers?.find(item => item.id === this.intent!.transfer!.id);
|
|
259
261
|
if (command === "complete" && transfer?.status !== "ready") throw new Error("Wait until the transfer target has joined.");
|
|
260
|
-
if (this.intent.transfer.mode !== "warm") throw new Error("Cold transfers complete automatically.");
|
|
262
|
+
if (this.intent.transfer.mode !== "warm" && command === "complete") throw new Error("Cold transfers complete automatically.");
|
|
263
|
+
if (command === "cancel" && ["completing", "completed"].includes(transfer?.status ?? "")) throw new Error("The handoff has started. Check its status instead of canceling it.");
|
|
261
264
|
if (this.intent.transfer.command && this.intent.transfer.command !== command) throw new Error("Recover the saved transfer command first.");
|
|
262
265
|
const next = structuredClone(this.intent); next.transfer!.command = command;
|
|
263
266
|
await this.journal.write(next); this.intent = next;
|
|
@@ -2,7 +2,6 @@
|
|
|
2
2
|
import { createHash } from "node:crypto";
|
|
3
3
|
import type { PyAI, TelephonyBrowserSessionCreate } from "../index.ts";
|
|
4
4
|
import type { DialerBroker } from "./managedDialer.ts";
|
|
5
|
-
import { dialerCallHandedOff } from "./managedDialer.ts";
|
|
6
5
|
|
|
7
6
|
export function createServerDialerBroker(sdk: PyAI, authenticatedUserId: string): DialerBroker {
|
|
8
7
|
if (!authenticatedUserId.trim()) throw new Error("An authenticated user is required.");
|
|
@@ -20,9 +19,21 @@ export function createServerDialerBroker(sdk: PyAI, authenticatedUserId: string)
|
|
|
20
19
|
},
|
|
21
20
|
get: ownedCall,
|
|
22
21
|
async hangup(id: string) {
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
return sdk.telephony.calls.hangup(id);
|
|
22
|
+
await ownedCall(id);
|
|
23
|
+
// The provider rechecks handoff ownership in the stop CAS, after this read.
|
|
24
|
+
return sdk.telephony.calls.hangup(id,{user_id:authenticatedUserId});
|
|
25
|
+
},
|
|
26
|
+
async setHold(id, held, key) {
|
|
27
|
+
await ownedCall(id);
|
|
28
|
+
if (!key || key.length > 255 || /[\r\n]/.test(key)) throw new Error("A valid hold retry key is required.");
|
|
29
|
+
const scopedKey = "dialer-hold:" + createHash("sha256").update(authenticatedUserId).update("\0").update(id).update("\0").update(key).digest("hex");
|
|
30
|
+
return sdk.telephony.calls.setHold(id, { held, user_id: authenticatedUserId }, { idempotencyKey: scopedKey });
|
|
31
|
+
},
|
|
32
|
+
async sendDtmf(id, digits, key) {
|
|
33
|
+
await ownedCall(id);
|
|
34
|
+
if (!key || key.length > 255 || /[\r\n]/.test(key)) throw new Error("A valid keypad retry key is required.");
|
|
35
|
+
const scopedKey = "dialer-keypad:" + createHash("sha256").update(authenticatedUserId).update("\0").update(id).update("\0").update(key).digest("hex");
|
|
36
|
+
return sdk.telephony.calls.sendDtmf(id, { digits, user_id: authenticatedUserId }, { idempotencyKey: scopedKey });
|
|
26
37
|
},
|
|
27
38
|
transfers: {
|
|
28
39
|
async create(id, input, key) {
|
package/src/index.ts
CHANGED
|
@@ -1501,7 +1501,10 @@ export interface TelephonyCall {
|
|
|
1501
1501
|
agent_id: string | null;
|
|
1502
1502
|
call_type?: "human";
|
|
1503
1503
|
transfer_enabled?: boolean;
|
|
1504
|
+
held?: boolean;
|
|
1505
|
+
hold_pending?: boolean;
|
|
1504
1506
|
transfers?: TelephonyTransfer[];
|
|
1507
|
+
forwarding?: { to: string | null; status: "waiting" | "claimed" | "unknown" | "acknowledged" | "canceled"; menu?: { kind: "keypad"; status: "pending" | "selected" | "rejected"; choice_id: string | null } };
|
|
1505
1508
|
user_id?: string;
|
|
1506
1509
|
client_reference: string | null;
|
|
1507
1510
|
stop_requested: boolean;
|
|
@@ -1518,6 +1521,40 @@ export interface TelephonyTransfer {
|
|
|
1518
1521
|
status: "holding" | "dialing" | "ready" | "completing" | "canceling" | "completed" | "canceled" | "failed";
|
|
1519
1522
|
to: string | null;
|
|
1520
1523
|
}
|
|
1524
|
+
export interface TelephonyCallQuality {
|
|
1525
|
+
call_id: string;
|
|
1526
|
+
status: "available" | "unavailable";
|
|
1527
|
+
reason: string | null;
|
|
1528
|
+
source: "managed_transport" | null;
|
|
1529
|
+
scope: "caller_to_platform" | null;
|
|
1530
|
+
observation: "terminal_snapshot" | "partial_snapshot" | null;
|
|
1531
|
+
observed_at: string | null;
|
|
1532
|
+
live: false;
|
|
1533
|
+
metrics: Record<"packets_received" | "packets_lost" | "packets_reordered" | "duplicate_packets" |
|
|
1534
|
+
"packets_sent" | "playout_frames" | "concealed_frames" | "late_frames" | "playout_duplicates" |
|
|
1535
|
+
"jitter_ms" | "packet_loss_percent" | "concealment_percent", number | null> & { mos: null; rtt_ms: null };
|
|
1536
|
+
unavailable_metrics: string[];
|
|
1537
|
+
}
|
|
1538
|
+
export interface TelephonyCallCapabilities {
|
|
1539
|
+
object: "telephony.call_capabilities";
|
|
1540
|
+
call_id: string;
|
|
1541
|
+
version: 1;
|
|
1542
|
+
call_type: "human" | "ai";
|
|
1543
|
+
controls: Record<"hangup" | "hold" | "warm_transfer" | "cold_transfer" | "complete_transfer" |
|
|
1544
|
+
"cancel_transfer" | "listen" | "whisper" | "barge", { supported: boolean; reason: string | null }>;
|
|
1545
|
+
client_controls: Array<"mute" | "dtmf">;
|
|
1546
|
+
quality: { read_supported: true; live: false };
|
|
1547
|
+
revalidation_required: true;
|
|
1548
|
+
}
|
|
1549
|
+
|
|
1550
|
+
export interface TelephonyCallControl {
|
|
1551
|
+
object: "telephony.call_control";
|
|
1552
|
+
id: string;
|
|
1553
|
+
call_id: string;
|
|
1554
|
+
action: "send_dtmf";
|
|
1555
|
+
status: "acknowledged" | "unknown" | "rejected";
|
|
1556
|
+
}
|
|
1557
|
+
|
|
1521
1558
|
export interface TelephonyCallCreate {
|
|
1522
1559
|
from_number_id: string;
|
|
1523
1560
|
to: string;
|
|
@@ -1565,6 +1602,12 @@ export interface TelephonyAvailableNumber {
|
|
|
1565
1602
|
region?: string | null;
|
|
1566
1603
|
capabilities?: TelephonyCapabilities;
|
|
1567
1604
|
monthly_cost_cents?: number;
|
|
1605
|
+
/** Bind purchase to the exact account/market inventory result. */
|
|
1606
|
+
inventory_reference?: string;
|
|
1607
|
+
}
|
|
1608
|
+
|
|
1609
|
+
export interface TelephonyNumberInventory extends ListResponse<TelephonyAvailableNumber> {
|
|
1610
|
+
provisioning?: { mode: "automated" | "assisted"; capability: string; message: string };
|
|
1568
1611
|
}
|
|
1569
1612
|
|
|
1570
1613
|
export interface TelephonyNumber {
|
|
@@ -1589,7 +1632,7 @@ export interface TelephonyNumberOrder {
|
|
|
1589
1632
|
id: string;
|
|
1590
1633
|
status: "pending" | "unknown" | "completed" | "failed" | "released";
|
|
1591
1634
|
phone_number: string;
|
|
1592
|
-
country: "AU";
|
|
1635
|
+
country: "AU" | "US" | "CA";
|
|
1593
1636
|
project_id: string;
|
|
1594
1637
|
retry_after_seconds: number;
|
|
1595
1638
|
message: string;
|
|
@@ -1598,6 +1641,8 @@ export interface TelephonyNumberOrder {
|
|
|
1598
1641
|
}
|
|
1599
1642
|
export interface TelephonyNumberPurchase {
|
|
1600
1643
|
phone_number: string;
|
|
1644
|
+
country?: "US" | "CA" | "IN" | "AU";
|
|
1645
|
+
inventory_reference?: string;
|
|
1601
1646
|
agent_id?: string | null;
|
|
1602
1647
|
provisioning_mode?: "automated" | "adopt_preowned";
|
|
1603
1648
|
project_id?: string;
|
|
@@ -1605,6 +1650,51 @@ export interface TelephonyNumberPurchase {
|
|
|
1605
1650
|
max_monthly_cost_cents?: number;
|
|
1606
1651
|
}
|
|
1607
1652
|
|
|
1653
|
+
export interface TelephonyInboundBinding {
|
|
1654
|
+
object: "telephony.inbound_binding";
|
|
1655
|
+
number_id: string;
|
|
1656
|
+
version: number;
|
|
1657
|
+
enabled: boolean;
|
|
1658
|
+
project_id?: string;
|
|
1659
|
+
agent_id?: string;
|
|
1660
|
+
agent_release_id?: string;
|
|
1661
|
+
agent_profile_sha256?: string;
|
|
1662
|
+
admission_mode?: "client" | "platform";
|
|
1663
|
+
forward?: TelephonyInboundForward | null;
|
|
1664
|
+
carrier_operation?: { id: string; phase: "pending" | "unknown" | "active" | "rollback_pending" | "rolled_back"; action: "activate" | "rollback" };
|
|
1665
|
+
}
|
|
1666
|
+
|
|
1667
|
+
export interface TelephonyInboundMenu {
|
|
1668
|
+
/** Saved single-digit spoken menu before forwarding. */
|
|
1669
|
+
kind: "keypad";
|
|
1670
|
+
prompt: string;
|
|
1671
|
+
choices: Array<{ id: string; key: string; to: string }>;
|
|
1672
|
+
timeout_seconds: number;
|
|
1673
|
+
/** null hangs up; otherwise the ID of one saved choice. */
|
|
1674
|
+
timeout_choice_id: string | null;
|
|
1675
|
+
}
|
|
1676
|
+
export type TelephonyInboundForward = {
|
|
1677
|
+
max_duration_seconds: number;
|
|
1678
|
+
recording: boolean;
|
|
1679
|
+
} & ({ to: string; menu?: never } | { to?: never; menu: TelephonyInboundMenu });
|
|
1680
|
+
|
|
1681
|
+
export type TelephonyInboundBindingUpdate = {
|
|
1682
|
+
expected_version: number;
|
|
1683
|
+
activate_carrier_route?: boolean;
|
|
1684
|
+
rollback_carrier_route?: boolean;
|
|
1685
|
+
/** Persist the original operation ID; recover it instead of inventing a new one. */
|
|
1686
|
+
carrier_operation_id?: string;
|
|
1687
|
+
} & ({ enabled: false } | {
|
|
1688
|
+
enabled: true;
|
|
1689
|
+
project_id: string;
|
|
1690
|
+
agent_id: string;
|
|
1691
|
+
agent_release_id: string;
|
|
1692
|
+
agent_profile_sha256: string;
|
|
1693
|
+
admission_mode?: "client" | "platform";
|
|
1694
|
+
agent_knowledge_receipt?: Record<string, unknown>;
|
|
1695
|
+
forward?: TelephonyInboundForward | null;
|
|
1696
|
+
});
|
|
1697
|
+
|
|
1608
1698
|
/* ------------------------------------------------------------------------- *
|
|
1609
1699
|
* Trace (compliance)
|
|
1610
1700
|
* ------------------------------------------------------------------------- */
|
|
@@ -2396,18 +2486,29 @@ export class PyAI {
|
|
|
2396
2486
|
create: (input: TelephonyCallCreate, options: { idempotencyKey: string }): Promise<TelephonyCall> =>
|
|
2397
2487
|
this.postJson("/v1/telephony/calls", input, telephonyIdempotencyHeader(options.idempotencyKey)),
|
|
2398
2488
|
get: (id: string): Promise<TelephonyCall> => this.getJson(`/v1/telephony/calls/${encodeURIComponent(id)}`),
|
|
2489
|
+
capabilities: (id: string): Promise<TelephonyCallCapabilities> => this.getJson(`/v1/telephony/calls/${encodeURIComponent(id)}/capabilities`),
|
|
2490
|
+
quality: (id: string): Promise<TelephonyCallQuality> => this.getJson(`/v1/telephony/calls/${encodeURIComponent(id)}/quality`),
|
|
2399
2491
|
list: (input: { limit?: number; cursor?: string; direction?: "inbound" | "outbound"; status?: TelephonyCallStatus } = {}): Promise<ListResponse<TelephonyCall> & { next_cursor: string | null }> => {
|
|
2400
2492
|
const query = new URLSearchParams();
|
|
2401
2493
|
for (const [key, value] of Object.entries(input)) if (value !== undefined) query.set(key, String(value));
|
|
2402
2494
|
return this.getJson(`/v1/telephony/calls${query.size ? `?${query}` : ""}`);
|
|
2403
2495
|
},
|
|
2404
2496
|
/** Durable stop intent; use get() until a terminal status is confirmed. */
|
|
2405
|
-
hangup: (id: string): Promise<TelephonyCall> => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/hangup`, {}),
|
|
2497
|
+
hangup: (id: string, input?: {user_id:string}): Promise<TelephonyCall> => this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/hangup`, input ?? {}),
|
|
2406
2498
|
decideAdmission: (id: string, input: { decision: "accept" | "reject"; client_reference: string; max_duration_seconds: number }): Promise<TelephonyCall> =>
|
|
2407
2499
|
this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/admission`, input),
|
|
2408
2500
|
recording: (id: string, options: { range?: string } = {}): Promise<Response> =>
|
|
2409
2501
|
this.request(`/v1/telephony/calls/${encodeURIComponent(id)}/recording`, { headers: this.authHeaders(options.range ? { Range: options.range } : {}) }),
|
|
2410
2502
|
deleteRecording: async (id: string): Promise<void> => { await this.deleteReq(`/v1/telephony/calls/${encodeURIComponent(id)}/recording`); },
|
|
2503
|
+
/** The same durable key recovers an uncertain hold command without repeating it. */
|
|
2504
|
+
setHold: (id: string, input: { user_id: string; held: boolean }, options: { idempotencyKey: string }): Promise<TelephonyCall> =>
|
|
2505
|
+
this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/hold`, input, telephonyIdempotencyHeader(options.idempotencyKey)),
|
|
2506
|
+
/** Server-side keypad command for an owned switch call. Reuse the same key
|
|
2507
|
+
* after an unknown result; never store keypad digits in a browser journal. */
|
|
2508
|
+
sendDtmf: (id: string, input: { digits: string; user_id: string }, options: { idempotencyKey: string }): Promise<TelephonyCallControl> => {
|
|
2509
|
+
if (!/^[0-9A-D*#]{1,32}$/.test(input.digits)) throw new Error("Use 1–32 keypad digits (0–9, *, #, A–D).");
|
|
2510
|
+
return this.postJson(`/v1/telephony/calls/${encodeURIComponent(id)}/dtmf`, input, telephonyIdempotencyHeader(options.idempotencyKey));
|
|
2511
|
+
},
|
|
2411
2512
|
transfers: {
|
|
2412
2513
|
/** Persist the key and target before requesting a consultation. */
|
|
2413
2514
|
create: (id: string, input: { to: string; mode: "warm" | "cold"; user_id: string }, options: { idempotencyKey: string }): Promise<TelephonyCall> =>
|
|
@@ -2427,7 +2528,7 @@ export class PyAI {
|
|
|
2427
2528
|
/** Search managed inventory; country availability and ordering may be gated. */
|
|
2428
2529
|
available: (
|
|
2429
2530
|
params: { country?: "US" | "CA" | "IN" | "AU"; areaCode?: string; contains?: string; limit?: number } = {},
|
|
2430
|
-
): Promise<
|
|
2531
|
+
): Promise<TelephonyNumberInventory> => {
|
|
2431
2532
|
const q = new URLSearchParams();
|
|
2432
2533
|
if (params.country) q.set("country", params.country);
|
|
2433
2534
|
if (params.areaCode) q.set("area_code", params.areaCode);
|
|
@@ -2447,6 +2548,12 @@ export class PyAI {
|
|
|
2447
2548
|
/** Route a number to an agent (`agentId: null` to unassign). */
|
|
2448
2549
|
assign: (id: string, agentId: string | null): Promise<TelephonyNumber> =>
|
|
2449
2550
|
this.postJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/assign`, { agent_id: agentId }),
|
|
2551
|
+
getInboundBinding: (id: string): Promise<TelephonyInboundBinding> =>
|
|
2552
|
+
this.getJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/inbound-binding`),
|
|
2553
|
+
/** Save the profile and stable operation first; after uncertainty read the
|
|
2554
|
+
* binding before explicitly recovering that same operation. */
|
|
2555
|
+
setInboundBinding: (id: string, input: TelephonyInboundBindingUpdate): Promise<TelephonyInboundBinding> =>
|
|
2556
|
+
this.putJson(`/v1/telephony/numbers/${encodeURIComponent(id)}/inbound-binding`, input),
|
|
2450
2557
|
/** Release a number back to the carrier (idempotent). */
|
|
2451
2558
|
release: async (id: string): Promise<TelephonyNumber> => {
|
|
2452
2559
|
const res = await this.deleteReq(`/v1/telephony/numbers/${encodeURIComponent(id)}`);
|