@pyai/sdk 0.2.1 → 0.2.2

package/dist/index.js

@@ -1,10 +1,9 @@
 /**
- * @pyai/sdk — official TypeScript/JavaScript client for the PyAI API.
+ * @pyai/sdk, official TypeScript/JavaScript client for the PyAI API.
  *
  * Thin, dependency-free wrapper over the public OpenAI-compatible surface at
  * https://api.pyai.com (contract: https://api.pyai.com/openapi.json). Runs in
- * the browser and Node 22+ (uses global fetch + WebSocket). Keys are opaque —
- * never parsed.
+ * the browser and Node 22+ (uses global fetch + WebSocket). Keys are opaque, * never parsed.
  */
 /** Stable, machine-readable error. Branch on `code`, not `message`. */
 export class PyAIError extends Error {
@@ -30,7 +29,7 @@ export const SPEECH_FORMATS = ["wav", "mp3", "opus", "aac", "flac", "pcm", "g711
 /** Sample rates (Hz) the server accepts for `audio.speech` (`g711_*` is always 8 kHz). */
 export const SPEECH_SAMPLE_RATES = [8000, 16000, 24000, 48000];
 /* ------------------------------------------------------------------------- *
- * Stable enums — mirror the server so callers branch on named constants, not
+ * Stable enums, mirror the server so callers branch on named constants, not
  * magic strings, and a contract change surfaces in one place. These are plain
  * `as const` objects (not TS `enum`s) so the source still runs directly under
  * Node's type-stripping and stays tree-shakeable.
@@ -63,7 +62,7 @@ export const WSCloseCode = {
 };
 /**
  * Stable, machine-readable error `code`s (the documented contract). Branch on
- * these. The set is treated as open — `PyAIError.code` stays `string` — so a
+ * these. The set is treated as open, `PyAIError.code` stays `string`, so a
  * new server code never breaks the build, but the known ones are named here.
  */
 export const ErrorCode = {
@@ -151,7 +150,7 @@ export class HearStream {
                 this.opts.onError?.(frame);
                 break;
             default:
-                // Unknown/forward-compatible frame — ignore.
+                // Unknown/forward-compatible frame, ignore.
                 break;
         }
     }
@@ -177,8 +176,73 @@ export class HearStream {
         return this.ws.readyState;
     }
 }
+/**
+ * A live AMD (answering-machine-detection) stream. The wire is Twilio's Media
+ * Streams protocol, so if you're already on Twilio the usual path is one line of
+ * TwiML pointing `<Stream url="wss://api.pyai.com/v1/amd/stream">` at PyAI, no
+ * SDK needed. This helper is for server-side clients that fork the media
+ * themselves: send Twilio `start`/`media`/`stop` frames with {@link AmdStream.send}
+ * (or raw μ-law audio with {@link AmdStream.sendAudio}) and receive the `amd`
+ * decision via `onDecision`. Construct via `pyai.amd.stream()`.
+ */
+export class AmdStream {
+    ws;
+    opts;
+    closed = false;
+    constructor(url, subprotocol, opts) {
+        this.opts = opts;
+        const WS = opts.webSocket ?? globalThis.WebSocket;
+        if (!WS) {
+            throw new Error("No global WebSocket available; pass options.webSocket (e.g. the `ws` package) to amd.stream()");
+        }
+        this.ws = new WS(url, [subprotocol]);
+        this.ws.onopen = () => opts.onOpen?.();
+        this.ws.onmessage = (ev) => this.handleMessage(ev.data);
+        this.ws.onerror = (ev) => opts.onError?.(ev instanceof Error ? ev : new Error("WebSocket error"));
+        this.ws.onclose = (ev) => {
+            this.closed = true;
+            opts.onClose?.(ev.code, ev.reason);
+        };
+    }
+    handleMessage(data) {
+        if (typeof data !== "string")
+            return; // AMD decisions are JSON text frames
+        let frame;
+        try {
+            frame = JSON.parse(data);
+        }
+        catch {
+            this.opts.onError?.(new Error(`Unparseable AMD frame: ${data.slice(0, 120)}`));
+            return;
+        }
+        if (frame.event === "amd")
+            this.opts.onDecision?.(frame);
+        this.opts.onMessage?.(frame);
+    }
+    /** Send a Twilio Media Streams control/media frame (JSON) or a raw string. */
+    send(frame) {
+        this.ws.send(typeof frame === "string" ? frame : JSON.stringify(frame));
+    }
+    /** Send a raw audio chunk (G.711 μ-law 8 kHz for the Twilio-native path). */
+    sendAudio(chunk) {
+        this.ws.send(chunk);
+    }
+    /** Close the socket. */
+    close(code = WSCloseCode.Normal, reason = "") {
+        if (!this.closed)
+            this.ws.close(code, reason);
+    }
+    /** The underlying socket (escape hatch for advanced use). */
+    get socket() {
+        return this.ws;
+    }
+    /** Current WebSocket readyState. */
+    get readyState() {
+        return this.ws.readyState;
+    }
+}
 /* ------------------------------------------------------------------------- *
- * Omni realtime (agentic voice) — typed client over the /v1/omni WebSocket
+ * Omni realtime (agentic voice), typed client over the /v1/omni WebSocket
  * ------------------------------------------------------------------------- */
 /**
  * Event names on Omni **server → client** frames. ⚠️ Note the asymmetry:
@@ -201,11 +265,43 @@ export const OmniEvent = {
     BargeIn: "barge_in",
     /** Alias for barge-in on some engine builds. */
     Flush: "flush",
+    /** Engine requests a client-loop tool invocation. */
+    ToolCall: "tool_call",
     /** Session is closing; see close code. */
     SessionEnd: "session_end",
     /** Server fault frame. */
     Error: "error",
 };
+/** Extract a byte view from a binary WS frame (Buffer / ArrayBuffer / typed
+ * array). Returns null for a Blob or unknown (can't be read synchronously). */
+function omniToBytes(data) {
+    if (data instanceof Uint8Array)
+        return data; // also covers Node Buffer
+    if (data instanceof ArrayBuffer)
+        return new Uint8Array(data);
+    if (ArrayBuffer.isView(data)) {
+        const v = data;
+        return new Uint8Array(v.buffer, v.byteOffset, v.byteLength);
+    }
+    return null;
+}
+/** A 0x01-prefixed audio frame, the engine's client→server framing for caller
+ * PCM16 LE (see OMNI_PROTOCOL_V2.md §2). */
+function omniAudioFrame(pcm) {
+    const out = new Uint8Array(pcm.length + 1);
+    out[0] = 0x01;
+    out.set(pcm, 1);
+    return out;
+}
+/** A 0x03-prefixed control frame, the engine's client→server framing for
+ * `configure`/`dtmf`/`tool_result` (see OMNI_PROTOCOL_V2.md §2/§3). */
+function omniControlFrame(obj) {
+    const json = new TextEncoder().encode(JSON.stringify(obj));
+    const out = new Uint8Array(json.length + 1);
+    out[0] = 0x03;
+    out.set(json, 1);
+    return out;
+}
 /**
  * A live Omni agentic-voice session over `/v1/omni`. Hides the wire protocol's
  * frame-key asymmetry: it sends control frames keyed on `type` (`configure`,
@@ -226,6 +322,8 @@ export class OmniConnection {
     ws;
     opts;
     closed = false;
+    /** Serializes async Blob reads in {@link sendAudio} so frames stay ordered. */
+    blobTail = Promise.resolve();
     constructor(url, subprotocol, opts) {
         this.opts = opts;
         const WS = opts.webSocket ?? globalThis.WebSocket;
@@ -252,21 +350,52 @@ export class OmniConnection {
         };
     }
     handleMessage(data) {
-        // Binary = agent audio (play it out). JSON text = an `event`-keyed frame.
+        // Server → client binary frames are TYPE-TAGGED by their first byte:
+        // 0x01 = agent audio (PCM16) · 0x02 = transcript JSON · 0x03 = control JSON.
+        // (Treating every binary frame as audio, the old behavior, plays the
+        // 0x03/0x02 frames as a glitch and drops every event/transcript.)
         if (typeof data !== "string") {
-            this.opts.onAudio?.(data);
+            const bytes = omniToBytes(data);
+            if (!bytes) {
+                this.opts.onAudio?.(data); // Blob/unknown, best-effort
+                return;
+            }
+            const tag = bytes[0];
+            if (tag === 0x01) {
+                this.opts.onAudio?.(bytes.slice(1)); // copy → aligned PCM16
+                return;
+            }
+            if (tag === 0x02 || tag === 0x03) {
+                try {
+                    const parsed = JSON.parse(new TextDecoder().decode(bytes.subarray(1)));
+                    // The 0x02 tag is authoritative for transcript even if the JSON omits `event`.
+                    this.dispatchFrame(tag === 0x02 ? { ...parsed, event: "transcript" } : parsed);
+                }
+                catch {
+                    this.opts.onError?.(new Error("Unparseable Omni binary frame"));
+                }
+                return;
+            }
+            this.opts.onAudio?.(data); // untagged, forward-compat as audio
             return;
         }
-        let frame;
+        // Text frame (e.g. a server-side broker relay).
         try {
-            frame = JSON.parse(data);
+            this.dispatchFrame(JSON.parse(data));
         }
         catch {
             this.opts.onError?.(new Error(`Unparseable Omni frame: ${data.slice(0, 120)}`));
-            return;
         }
-        this.opts.onEvent?.(frame);
-        switch (frame.event) {
+    }
+    dispatchFrame(frame) {
+        const raw = frame;
+        const eventName = typeof raw.event === "string"
+            ? raw.event
+            : typeof raw.type === "string"
+                ? raw.type
+                : "";
+        this.opts.onEvent?.({ ...frame, event: eventName });
+        switch (eventName) {
             case OmniEvent.Hello:
                 this.opts.onHello?.(frame);
                 break;
@@ -286,6 +415,9 @@ export class OmniConnection {
             case OmniEvent.Flush:
                 this.opts.onBargeIn?.(frame);
                 break;
+            case OmniEvent.ToolCall:
+                this.opts.onToolCall?.(frame);
+                break;
             case OmniEvent.SessionEnd:
                 this.opts.onSessionEnd?.(frame);
                 break;
@@ -293,25 +425,45 @@ export class OmniConnection {
                 this.opts.onError?.(frame);
                 break;
             default:
-                // Unknown/forward-compatible frame — already delivered via onEvent.
+                // Unknown/forward-compatible frame, already delivered via onEvent.
                 break;
         }
     }
     /**
      * Send (or update) the agent config. Always emitted as
-     * `{"type":"configure", ...}` — the correct key. (A hand-rolled
+     * `{"type":"configure", ...}`, the correct key. (A hand-rolled
      * `{"event":"configure"}` is acked but silently dropped by the engine.)
      */
     configure(cfg) {
-        this.ws.send(JSON.stringify({ type: "configure", ...cfg }));
+        this.ws.send(omniControlFrame({ type: "configure", ...cfg }));
     }
-    /** Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate). */
+    /**
+     * Stream a chunk of caller audio (PCM16 LE mono at the negotiated rate) as a
+     * `0x01`-prefixed frame. The engine demuxes on the first byte and has no
+     * default branch, so an untagged chunk is dropped with no error.
+     */
     sendAudio(chunk) {
-        this.ws.send(chunk);
+        const bytes = omniToBytes(chunk);
+        if (bytes) {
+            this.ws.send(omniAudioFrame(bytes));
+            return;
+        }
+        // A Blob can only be read asynchronously; queue behind the previous read so
+        // frames still reach the engine in call order.
+        this.blobTail = this.blobTail
+            .then(async () => {
+            const buf = await chunk.arrayBuffer();
+            this.ws.send(omniAudioFrame(new Uint8Array(buf)));
+        })
+            .catch((err) => this.opts.onError?.(err instanceof Error ? err : new Error(String(err))));
     }
     /** Send DTMF digits as a `{"type":"dtmf"}` control frame. */
     sendDtmf(digits) {
-        this.ws.send(JSON.stringify({ type: "dtmf", digits }));
+        this.ws.send(omniControlFrame({ type: "dtmf", digits }));
+    }
+    /** Reply to a client-loop {@link OmniEvent.ToolCall}. */
+    toolResult(callId, payload) {
+        this.ws.send(omniControlFrame({ type: "tool_result", call_id: callId, ...payload }));
     }
     /**
      * Send an arbitrary control frame for forward-compat control types the SDK
@@ -319,7 +471,7 @@ export class OmniConnection {
      * never `event`.
      */
     send(frame) {
-        this.ws.send(JSON.stringify(frame));
+        this.ws.send(omniControlFrame(frame));
     }
     /** Close the session. */
     close(code = WSCloseCode.Normal, reason = "") {
@@ -447,7 +599,7 @@ export class PyAI {
             const res = await this.request("/v1/audio/speech", {
                 method: "POST",
                 headers: this.authHeaders({ "Content-Type": "application/json" }),
-                body: JSON.stringify({ model: "pyai-voice", ...params }),
+                body: JSON.stringify({ model: "pyai-voice", ...params, stream: true }),
             });
             if (!res.body)
                 throw new PyAIError(res.status, "Response had no body to stream");
@@ -510,7 +662,7 @@ export class PyAI {
     // --- key introspection --------------------------------------------------
     /**
      * Introspect the calling key: scopes, environment, and limits. Useful for a
-     * preflight/doctor check. (New route; older deployments may 404 — handle it.)
+     * preflight/doctor check. (New route; older deployments may 404, handle it.)
      */
     me = () => this.getJson("/v1/me");
     // --- voice clones -------------------------------------------------------
@@ -612,7 +764,7 @@ export class PyAI {
             },
         },
         findings: {
-            /** List Tier-2 (async semantic) findings — advisory, non-blocking. Scope `trace:read`. */
+            /** List Tier-2 (async semantic) findings, advisory, non-blocking. Scope `trace:read`. */
             list: (params = {}) => {
                 const q = new URLSearchParams();
                 if (params.checkId)
@@ -680,11 +832,45 @@ export class PyAI {
             trigger: (callId, input) => this.postJson(`/v1/recap/calls/${encodeURIComponent(callId)}`, input),
         },
     };
+    // --- amd (answering-machine detection) ---------------------------------
+    amd = {
+        config: {
+            /** The org's AMD operating point + webhook. Scope `amd:configure`. */
+            get: () => this.getJson("/v1/amd/config"),
+            /** Set the account-default `aggressiveness` (0-1) and webhook. Scope `amd:configure`. */
+            set: (input) => this.postJson("/v1/amd/config", {
+                ...(input.aggressiveness !== undefined ? { aggressiveness: input.aggressiveness } : {}),
+                ...(input.webhookUrl !== undefined ? { webhook_url: input.webhookUrl } : {}),
+            }),
+        },
+        calls: {
+            /** Recent AMD decisions, newest first. Scope `amd:read`. */
+            list: (params = {}) => {
+                const q = new URLSearchParams();
+                if (params.limit !== undefined)
+                    q.set("limit", String(params.limit));
+                if (params.cursor)
+                    q.set("cursor", params.cursor);
+                if (params.sessionLabel)
+                    q.set("session_label", params.sessionLabel);
+                const qs = q.toString();
+                return this.getJson(`/v1/amd/calls${qs ? `?${qs}` : ""}`);
+            },
+            /** The full decision (answered_by, reason, …) for one call. Scope `amd:read`. */
+            get: (callId) => this.getJson(`/v1/amd/calls/${encodeURIComponent(callId)}`),
+        },
+        /**
+         * Open a live AMD stream over `/v1/amd/stream` (Twilio Media Streams
+         * protocol). Server-side helper for forking media yourself; the common
+         * Twilio path is one line of TwiML, no SDK. Scope `amd:detect`.
+         */
+        stream: (opts = {}) => new AmdStream(this.amdStreamURL(opts), this.realtimeSubprotocol(), opts),
+    };
     // --- omni (agentic voice) ----------------------------------------------
     omni = {
         /**
          * Mint an ephemeral, origin-locked Omni session token a browser can use to
-         * open ONE realtime session **directly** — the public/private split for
+         * open ONE realtime session **directly**, the public/private split for
          * realtime. **Call this from your server** with a secret key holding
          * `omni:session`; never ship the secret key to a page. Hand the returned
          * `token` to the browser, which connects with
@@ -700,8 +886,8 @@ export class PyAI {
         /**
          * Open a live Omni agentic-voice session over `/v1/omni`. Returns an
          * {@link OmniConnection} that handles the wire protocol's frame-key
-         * asymmetry for you — it sends `type`-keyed control frames (`configure`,
-         * `dtmf`) and parses `event`-keyed server frames — so you can't trip the #1
+         * asymmetry for you, it sends `type`-keyed control frames (`configure`,
+         * `dtmf`) and parses `event`-keyed server frames, so you can't trip the #1
          * Omni integration bug. Omni is zero-state: nothing to create first; the
          * agent's behavior travels in the `configure` frame. Pass `token` (from
          * `createSession`) to connect from a browser without the secret key.
@@ -724,7 +910,7 @@ export class PyAI {
         const q = new URLSearchParams(opts.query ?? {});
         if ((opts.product ?? "omni") === "omni") {
             // Omni's native realtime surface is /v1/omni. The session is authorized by
-            // the key's org (zero-state) — sessionLabel is an optional opaque tag.
+            // the key's org (zero-state), sessionLabel is an optional opaque tag.
             // format/rate are load-bearing on the connect URL, so default to
             // browser-grade PCM16/24kHz.
             if (opts.sessionLabel)
@@ -766,6 +952,17 @@ export class PyAI {
         const qs = q.toString();
         return `${wsBase}/v1/audio/transcriptions/stream${qs ? `?${qs}` : ""}`;
     }
+    /** Build the AMD detection WebSocket URL (`/v1/amd/stream`). */
+    amdStreamURL(opts = {}) {
+        const wsBase = this.baseURL.replace(/^http/, "ws");
+        const q = new URLSearchParams(opts.query ?? {});
+        if (opts.aggressiveness !== undefined)
+            q.set("aggressiveness", String(opts.aggressiveness));
+        if (opts.sessionLabel)
+            q.set("session_label", opts.sessionLabel);
+        const qs = q.toString();
+        return `${wsBase}/v1/amd/stream${qs ? `?${qs}` : ""}`;
+    }
     /**
      * Open a realtime WebSocket. Uses the global WebSocket (browser, Node 22+).
      * The key travels as a subprotocol so it works from the browser without

package/package.json

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

package/src/cli.ts

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
 /**
- * pyai — CLI for the PyAI API: proves your key, the endpoint, and audio in one
+ * pyai, CLI for the PyAI API: proves your key, the endpoint, and audio in one
  * command (`smoke`) or runs a deeper diagnosis with remediation hints (`doctor`).
  *
  * Commands:
  *   pyai doctor                         diagnose key/scopes + endpoint + Speak→Hear round-trip
- *   pyai smoke                          run models+voices+speak and report PASS/FAIL
+ *   pyai smoke [--tolerate-upstream]    run models+voices+speak and report PASS/FAIL
+ *                                       (--tolerate-upstream: transient 5xx/429 → WARN, not FAIL)
  *   pyai models                         list models
  *   pyai voices [--gender g --region r] list voices
  *   pyai speak --text T [--voice V] [--out f.wav]
  *   pyai transcribe --url U [--diarize] [--poll]
  *
  * Auth: PYAI_API_KEY env (or --api-key). Base URL: PYAI_BASE_URL (or --base-url).
- * Zero deps — uses the bundled SDK.
+ * Zero deps, uses the bundled SDK.
  */
 
 import { writeFile } from "node:fs/promises";
@@ -64,11 +65,12 @@ function fail(msg: string): never {
   process.exit(1);
 }
 
-const USAGE = `pyai — PyAI API CLI
+const USAGE = `pyai, PyAI API CLI
 
 Usage:
   pyai doctor                             diagnose key/scopes + endpoint + Speak→Hear round-trip
-  pyai smoke                              run a key/endpoint/audio smoke test
+  pyai smoke [--tolerate-upstream]        run a key/endpoint/audio smoke test
+                                          (--tolerate-upstream: transient 5xx/429 warn, don't fail)
   pyai models                             list models
   pyai voices [--gender g] [--region r]   list voices
   pyai speak --text T [--voice V] [--out f.wav]
@@ -116,16 +118,53 @@ async function cmdTranscribe(flags: Flags): Promise<void> {
   out(`job ${job.job_id} still running after polling; check later.`);
 }
 
+// Transient upstream conditions: a momentary engine/capacity blip or network
+// hiccup, NOT a key/scope/contract problem. 5xx = engine unhealthy (e.g. Speak
+// "503 service_unavailable"), 429 = rate/capacity, a non-PyAIError = network.
+// These self-heal; the others (401/403/404/400) are real and must fail loudly.
+const TRANSIENT_STATUSES = new Set([429, 500, 502, 503, 504]);
+function isTransient(err: unknown): boolean {
+  if (err instanceof PyAIError) return TRANSIENT_STATUSES.has(err.status);
+  return true; // network / timeout / unknown, worth a retry, never a hard fail on its own
+}
+
+/** Retry `fn` on transient upstream errors with exponential backoff. Real
+ * (non-transient) errors throw immediately, we never paper over a bad key. */
+async function withRetry<T>(fn: () => Promise<T>, attempts = 4, baseMs = 800): Promise<T> {
+  let lastErr: unknown;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastErr = err;
+      if (!isTransient(err) || i === attempts - 1) throw err;
+      await new Promise((r) => setTimeout(r, baseMs * 2 ** i));
+    }
+  }
+  throw lastErr;
+}
+
 /** The headline: prove key + endpoint + audio in one command. */
 async function cmdSmoke(flags: Flags): Promise<void> {
   const pyai = client(flags);
-  const checks: Array<{ name: string; ok: boolean; detail: string }> = [];
+  // CI/ops opt-in: a transient upstream blip (engine warming, a brief 503,
+  // rate-limit) should not red the build, it isn't the commit's fault. With this
+  // on, such failures are reported as WARN (exit 0); real key/scope/contract
+  // failures still FAIL (exit 1). Off by default so a developer running `pyai
+  // smoke` gets the strict, honest answer.
+  const tolerateUpstream = flags["tolerate-upstream"] === true || process.env.PYAI_SMOKE_TOLERATE_UPSTREAM === "1";
+  // Retry tuning is env-overridable (tests drive it fast; default rides brief blips).
+  const retryAttempts = Number(process.env.PYAI_SMOKE_RETRY_ATTEMPTS ?? 4);
+  const retryBaseMs = Number(process.env.PYAI_SMOKE_RETRY_BASE_MS ?? 800);
+  type Status = "PASS" | "WARN" | "FAIL";
+  const checks: Array<{ name: string; status: Status; detail: string }> = [];
   const run = async (name: string, fn: () => Promise<string>) => {
     try {
-      checks.push({ name, ok: true, detail: await fn() });
+      checks.push({ name, status: "PASS", detail: await withRetry(fn, retryAttempts, retryBaseMs) });
     } catch (err) {
-      const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}` : (err as Error).message;
-      checks.push({ name, ok: false, detail });
+      const detail = err instanceof PyAIError ? `${err.status} ${err.code ?? ""} ${err.message}`.trim() : (err as Error).message;
+      const status: Status = isTransient(err) && tolerateUpstream ? "WARN" : "FAIL";
+      checks.push({ name, status, detail });
     }
   };
 
@@ -142,10 +181,19 @@ async function cmdSmoke(flags: Flags): Promise<void> {
     return `${Buffer.from(audio).byteLength} bytes of audio`;
   });
 
-  for (const c of checks) out(`${c.ok ? "PASS" : "FAIL"}  ${c.name}  — ${c.detail}`);
-  const allOk = checks.every((c) => c.ok);
-  out(allOk ? "\nAll checks passed. Your key, the endpoint, and audio synthesis work." : "\nSome checks failed (see above).");
-  if (!allOk) process.exit(1);
+  for (const c of checks) out(`${c.status}  ${c.name}, ${c.detail}`);
+  const failed = checks.filter((c) => c.status === "FAIL");
+  const warned = checks.filter((c) => c.status === "WARN");
+  // GitHub Actions annotation: a tolerated blip is still surfaced in the run UI.
+  for (const c of warned) out(`::warning title=PyAI smoke transient::${c.name}: ${c.detail}`);
+  if (failed.length === 0 && warned.length === 0) {
+    out("\nAll checks passed. Your key, the endpoint, and audio synthesis work.");
+  } else if (failed.length === 0) {
+    out(`\n${warned.length} transient upstream issue(s) tolerated (self-healing engine blip), not failing the build.`);
+  } else {
+    out("\nSome checks failed (see above).");
+    process.exit(1);
+  }
 }
 
 /** Turn an error into an actionable, code-first remediation hint. */
@@ -153,35 +201,35 @@ function remediation(err: unknown): string {
   if (!(err instanceof PyAIError)) return (err as Error)?.message ?? String(err);
   switch (err.code) {
     case "unauthorized":
-      return "Invalid or missing key — check PYAI_API_KEY (a pyai_test_ or pyai_live_ key).";
+      return "Invalid or missing key, check PYAI_API_KEY (a pyai_test_ or pyai_live_ key).";
     case "forbidden":
-      return "Key is missing a required scope — add it to the key in the console.";
+      return "Key is missing a required scope, add it to the key in the console.";
     case "origin_not_allowed":
-      return "Publishable token origin not allow-listed — fix the allowed origins.";
+      return "Publishable token origin not allow-listed, fix the allowed origins.";
     case "credit_exhausted":
-      return "Out of prepaid credit — add credit, or use a pyai_test_ sandbox key.";
+      return "Out of prepaid credit, add credit, or use a pyai_test_ sandbox key.";
     case "key_budget_exceeded":
-      return "Per-key monthly budget hit — raise the budget in the console.";
+      return "Per-key monthly budget hit, raise the budget in the console.";
     case "insufficient_quota":
-      return "Plan quota exhausted — upgrade your plan.";
+      return "Plan quota exhausted, upgrade your plan.";
     case "rate_limit_exceeded":
-      return "Rate limited — back off and retry (honor Retry-After).";
+      return "Rate limited, back off and retry (honor Retry-After).";
     case "concurrency_limit_exceeded":
-      return "Too many concurrent sessions — retry shortly.";
+      return "Too many concurrent sessions, retry shortly.";
     case "daily_cap_exceeded":
-      return "Daily cap reached — wait until it resets.";
+      return "Daily cap reached, wait until it resets.";
     default:
       break;
   }
   switch (err.status) {
     case 401:
-      return "Invalid or missing key — check PYAI_API_KEY.";
+      return "Invalid or missing key, check PYAI_API_KEY.";
     case 403:
-      return "Forbidden — the key likely lacks the required scope.";
+      return "Forbidden, the key likely lacks the required scope.";
     case 404:
-      return "Not found — check PYAI_BASE_URL and the route.";
+      return "Not found, check PYAI_BASE_URL and the route.";
     case 429:
-      return "Rate/concurrency limited — back off and retry.";
+      return "Rate/concurrency limited, back off and retry.";
     default:
       return err.message;
   }
@@ -210,7 +258,7 @@ async function cmdDoctor(flags: Flags): Promise<void> {
   const checks: DoctorCheck[] = [];
 
   // (a) Key validity + scopes via GET /v1/me. The route is new, so a 404 means
-  // "not deployed here yet" — skip it rather than failing the whole doctor.
+  // "not deployed here yet", skip it rather than failing the whole doctor.
   try {
     const me = await pyai.me();
     const scopes = Array.isArray(me.scopes) ? me.scopes : [];
@@ -245,14 +293,14 @@ async function cmdDoctor(flags: Flags): Promise<void> {
   });
 
   for (const c of checks) {
-    out(`${c.status.padEnd(4)}  ${c.name}  — ${c.detail}`);
+    out(`${c.status.padEnd(4)}  ${c.name}, ${c.detail}`);
     if (c.hint) out(`        ↳ ${c.hint}`);
   }
   const failed = checks.filter((c) => c.status === "FAIL");
   if (failed.length === 0) {
     out("\nDiagnosis: healthy. Key, endpoint, and a Speak→Hear round-trip all work.");
   } else {
-    out(`\nDiagnosis: ${failed.length} check(s) failed — see the remediation hints above.`);
+    out(`\nDiagnosis: ${failed.length} check(s) failed, see the remediation hints above.`);
     process.exit(1);
   }
 }