@amigo-ai/platform-sdk 0.23.0 → 0.25.0

package/dist/resources/observers.js

@@ -0,0 +1,238 @@
+/**
+ * Voice-call observer real-time stream.
+ *
+ * The voice agent ("agent-engine") exposes a per-call WebSocket that emits
+ * the live timeline of a call: transcripts (user + agent), emotion / empathy
+ * frames, latency markers, tool invocations, navigation timing, and lifecycle
+ * events (start / end / participant join / leave).
+ *
+ * This resource is the canonical SDK consumer for that stream. Before it
+ * existed, every developer-console-style app re-implemented the loop by hand
+ * — different idle thresholds, missing close-code handling for the long list
+ * of voice-specific 4xxx codes (4001 unauthorized, 4003 forbidden, 4029 rate
+ * limit, 4100 token expired), and inconsistent reconnect backoff.
+ *
+ * The implementation composes {@link createReconnectingWebSocket} with a
+ * lightweight ``ObserverSSEEvent`` parser. Frames that don't deserialize or
+ * lack a recognized ``type`` discriminator are dropped — the stream remains
+ * forward-compatible with new event types added on the server before the SDK
+ * spec snapshot picks them up.
+ *
+ * @see ConversationsResource.subscribeTextStream for the analogous text-stream
+ *   helper.
+ */
+import { ConfigurationError } from '../core/errors.js';
+import { createReconnectingWebSocket, } from '../core/reconnecting-websocket.js';
+import { WorkspaceScopedResource } from './base.js';
+/** Token grammar accepted in WebSocket subprotocols (RFC 6455). */
+const WEB_SOCKET_PROTOCOL_TOKEN_RE = /^[!#$%&'*+\-.^_`|~A-Za-z0-9]+$/;
+const MAX_AUTH_TOKEN_CHARS = 4096;
+/**
+ * Build browser WebSocket subprotocols for the observer stream.
+ *
+ * Identical wire format to the text-stream subprotocol pair —
+ * ``Sec-WebSocket-Protocol: auth, <token>`` — but exposed as its own
+ * function so consumers do not have to reason about cross-resource sharing
+ * and so the SDK can evolve the auth scheme independently per stream.
+ *
+ * @security The returned tuple contains the raw bearer token. Do not log,
+ *   persist, serialize, or otherwise expose this value.
+ */
+export function observerAuthProtocols(token) {
+    if (!token) {
+        throw new ConfigurationError('observerAuthProtocols requires a non-empty token');
+    }
+    if (token.length > MAX_AUTH_TOKEN_CHARS) {
+        throw new ConfigurationError(`observer token exceeds the ${MAX_AUTH_TOKEN_CHARS}-character WebSocket subprotocol limit`);
+    }
+    if (!WEB_SOCKET_PROTOCOL_TOKEN_RE.test(token)) {
+        throw new ConfigurationError('observer token contains characters browsers reject in WebSocket subprotocols');
+    }
+    return ['auth', token];
+}
+/**
+ * Voice-call observer resource.
+ *
+ * @example
+ * ```ts
+ * const handle = client.observers.subscribe({
+ *   callSid: 'CAxxx',
+ *   token: bearerToken,
+ *   onEvent: (event) => {
+ *     switch (event.type) {
+ *       case 'agent_transcript_delta':
+ *         renderAgentDelta(event.text)
+ *         break
+ *       case 'user_transcript':
+ *         renderUserTurn(event.text)
+ *         break
+ *       case 'session_end':
+ *         showSummary(event)
+ *         break
+ *     }
+ *   },
+ *   onError: (err) => console.error('observer terminal:', err.reason),
+ * })
+ *
+ * // Later, to stop:
+ * handle.close()
+ * await handle.done
+ * ```
+ */
+export class ObserversResource extends WorkspaceScopedResource {
+    agentBaseUrl;
+    constructor(client, workspaceId, agentBaseUrl) {
+        super(client, workspaceId);
+        this.agentBaseUrl = agentBaseUrl;
+    }
+    /**
+     * Subscribe to the live observer stream for a call.
+     *
+     * Returns a {@link ReconnectingWebSocketHandle} that resolves
+     * ``handle.done`` when the stream terminates (consumer-aborted, terminal
+     * close code, or reconnect budget exhausted). Errors are surfaced through
+     * ``onError``; the promise never rejects.
+     */
+    subscribe(options) {
+        const url = buildObserverUrl({
+            baseUrl: this.agentBaseUrl ?? this.platformBaseUrl,
+            workspaceId: this.workspaceId,
+            callSid: options.callSid,
+            observerUrl: options.observerUrl,
+        });
+        const protocols = observerAuthProtocols(options.token);
+        return createReconnectingWebSocket({
+            url,
+            protocols: [...protocols],
+            onMessage: (ev) => {
+                const parsed = parseObserverFrame(ev.data);
+                if (parsed) {
+                    try {
+                        options.onEvent(parsed);
+                    }
+                    catch {
+                        // Consumer threw in onEvent — do not let it kill the loop.
+                    }
+                }
+            },
+            onStateChange: options.onStateChange,
+            onReconnect: options.onReconnect,
+            onError: options.onError,
+            signal: options.signal,
+            idleTimeoutMs: options.idleTimeoutMs ?? 60_000,
+            initialDelayMs: options.initialDelayMs ?? 1_000,
+            maxDelayMs: options.maxDelayMs ?? 30_000,
+            maxReconnects: options.maxReconnects ?? 10,
+            webSocketFactory: options.webSocketFactory,
+        });
+    }
+}
+const CALL_SID_RE = /^CA[a-zA-Z0-9]{32}$/;
+function buildObserverUrl(args) {
+    if (!args.workspaceId) {
+        throw new ConfigurationError('workspaceId is required to build the observer URL');
+    }
+    if (!args.callSid) {
+        throw new ConfigurationError('callSid is required to subscribe to the observer stream');
+    }
+    if (args.observerUrl) {
+        // Override path — the consumer has already constructed the full URL
+        // (e.g. via a custom voice-agent gateway helper). Skip the Twilio CA
+        // SID grammar check; the override owns the URL shape.
+        return parseOverride(args.observerUrl).toString();
+    }
+    // Default path — derive ``/v1/{ws}/observers/{callSid}/ws`` and validate
+    // the CA SID grammar so a typo fails at the function boundary instead of
+    // mid-reconnect-loop with an opaque 4001.
+    if (!CALL_SID_RE.test(args.callSid)) {
+        throw new ConfigurationError(`callSid does not match Twilio CA SID format (CA + 32 hex chars): ${args.callSid}`);
+    }
+    return deriveFromBase(args.baseUrl, args.workspaceId, args.callSid).toString();
+}
+function parseOverride(observerUrl) {
+    let url;
+    try {
+        url = new URL(observerUrl);
+    }
+    catch (cause) {
+        throw new ConfigurationError(`observerUrl must be an absolute URL: ${String(cause)}`);
+    }
+    if (url.protocol !== 'ws:' && url.protocol !== 'wss:') {
+        throw new ConfigurationError('observerUrl overrides must use ws: or wss: URLs');
+    }
+    if (url.search || url.hash) {
+        throw new ConfigurationError('observerUrl overrides must not include query parameters or fragments');
+    }
+    return url;
+}
+function deriveFromBase(baseUrl, workspaceId, callSid) {
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch (cause) {
+        throw new ConfigurationError(`observerUrl cannot be derived from baseUrl: ${String(cause)}`);
+    }
+    // Map http(s) to ws(s) — the agent-engine ALB serves both on the same host.
+    let scheme;
+    if (parsed.protocol === 'https:' || parsed.protocol === 'wss:')
+        scheme = 'wss:';
+    else if (parsed.protocol === 'http:' || parsed.protocol === 'ws:')
+        scheme = 'ws:';
+    else {
+        throw new ConfigurationError(`observerUrl can only be derived from an http, https, ws, or wss baseUrl: ${baseUrl}`);
+    }
+    // The pathname must be '/' — observer paths are owned by this helper,
+    // not the consumer's baseUrl gateway.
+    if (parsed.pathname !== '/' && parsed.pathname !== '') {
+        throw new ConfigurationError('observerUrl can only be derived from an origin-only baseUrl; pass observerUrl explicitly when using path-prefixed gateways');
+    }
+    const out = new URL(`${scheme}//${parsed.host}/v1/${encodeURIComponent(workspaceId)}/observers/${encodeURIComponent(callSid)}/ws`);
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Frame parser
+// ---------------------------------------------------------------------------
+/**
+ * Parse a raw WebSocket frame into a typed {@link ObserverSSEEvent}.
+ *
+ * Drift-tolerant: returns ``null`` on JSON decode errors, non-object
+ * payloads, missing ``type`` discriminator, or unknown discriminator
+ * values. The static type of ``ObserverSSEEvent`` is the contract — the
+ * server may add new event types ahead of an SDK release and the consumer's
+ * exhaustive ``switch`` will simply not match them, leaving the unknown
+ * frame on the floor.
+ */
+function parseObserverFrame(data) {
+    let text;
+    if (typeof data === 'string') {
+        text = data;
+    }
+    else if (data instanceof ArrayBuffer) {
+        text = new TextDecoder().decode(data);
+    }
+    else if (ArrayBuffer.isView(data)) {
+        // ``data`` is some TypedArray; @types/node TextDecoder.decode wants
+        // ``BufferSource``. Pass through as ``Uint8Array`` over the underlying
+        // buffer so every TypedArray variant decodes consistently.
+        const view = data;
+        text = new TextDecoder().decode(new Uint8Array(view.buffer, view.byteOffset, view.byteLength));
+    }
+    else {
+        return null;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof payload !== 'object' || payload === null || Array.isArray(payload))
+        return null;
+    const obj = payload;
+    if (typeof obj['type'] !== 'string')
+        return null;
+    return obj;
+}
+//# sourceMappingURL=observers.js.map

package/dist/resources/observers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observers.js","sourceRoot":"","sources":["../../src/resources/observers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EACL,2BAA2B,GAK5B,MAAM,mCAAmC,CAAA;AAG1C,OAAO,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AAcnD,mEAAmE;AACnE,MAAM,4BAA4B,GAAG,gCAAgC,CAAA;AACrE,MAAM,oBAAoB,GAAG,IAAI,CAAA;AAoEjC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IACjD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,kBAAkB,CAAC,kDAAkD,CAAC,CAAA;IAClF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,GAAG,oBAAoB,EAAE,CAAC;QACxC,MAAM,IAAI,kBAAkB,CAC1B,8BAA8B,oBAAoB,wCAAwC,CAC3F,CAAA;IACH,CAAC;IACD,IAAI,CAAC,4BAA4B,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,kBAAkB,CAC1B,8EAA8E,CAC/E,CAAA;IACH,CAAC;IACD,OAAO,CAAC,MAAM,EAAE,KAAK,CAAU,CAAA;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,iBAAkB,SAAQ,uBAAuB;IAC3C,YAAY,CAAoB;IAEjD,YAAY,MAAqB,EAAE,WAAmB,EAAE,YAAqB;QAC3E,KAAK,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;QAC1B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IAClC,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,CAAC,OAAiC;QACzC,MAAM,GAAG,GAAG,gBAAgB,CAAC;YAC3B,OAAO,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,eAAe;YAClD,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CAAA;QAEF,MAAM,SAAS,GAAG,qBAAqB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAEtD,OAAO,2BAA2B,CAAC;YACjC,GAAG;YACH,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC;YACzB,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE;gBAChB,MAAM,MAAM,GAAG,kBAAkB,CAAC,EAAE,CAAC,IAAI,CAAC,CAAA;gBAC1C,IAAI,MAAM,EAAE,CAAC;oBACX,IAAI,CAAC;wBACH,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;oBACzB,CAAC;oBAAC,MAAM,CAAC;wBACP,2DAA2D;oBAC7D,CAAC;gBACH,CAAC;YACH,CAAC;YACD,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,MAAM;YAC9C,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,KAAK;YAC/C,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,MAAM;YACxC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,EAAE;YAC1C,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;SAC3C,CAAC,CAAA;IACJ,CAAC;CACF;AAaD,MAAM,WAAW,GAAG,qBAAqB,CAAA;AAEzC,SAAS,gBAAgB,CAAC,IAA0B;IAClD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACtB,MAAM,IAAI,kBAAkB,CAAC,mDAAmD,CAAC,CAAA;IACnF,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAClB,MAAM,IAAI,kBAAkB,CAAC,yDAAyD,CAAC,CAAA;IACzF,CAAC;IACD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,oEAAoE;QACpE,qEAAqE;QACrE,sDAAsD;QACtD,OAAO,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE,CAAA;IACnD,CAAC;IACD,yEAAyE;IACzE,yEAAyE;IACzE,0CAA0C;IAC1C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,kBAAkB,CAC1B,oEAAoE,IAAI,CAAC,OAAO,EAAE,CACnF,CAAA;IACH,CAAC;IACD,OAAO,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAA;AAChF,CAAC;AAED,SAAS,aAAa,CAAC,WAAmB;IACxC,IAAI,GAAQ,CAAA;IACZ,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAA;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,kBAAkB,CAC1B,wCAAwC,MAAM,CAAC,KAAK,CAAC,EAAE,CACxD,CAAA;IACH,CAAC;IACD,IAAI,GAAG,CAAC,QAAQ,KAAK,KAAK,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;QACtD,MAAM,IAAI,kBAAkB,CAAC,iDAAiD,CAAC,CAAA;IACjF,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3B,MAAM,IAAI,kBAAkB,CAC1B,sEAAsE,CACvE,CAAA;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,cAAc,CAAC,OAAe,EAAE,WAAmB,EAAE,OAAe;IAC3E,IAAI,MAAW,CAAA;IACf,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,CAAA;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,kBAAkB,CAC1B,+CAA+C,MAAM,CAAC,KAAK,CAAC,EAAE,CAC/D,CAAA;IACH,CAAC;IACD,4EAA4E;IAC5E,IAAI,MAAc,CAAA;IAClB,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM;QAAE,MAAM,GAAG,MAAM,CAAA;SAC1E,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,KAAK;QAAE,MAAM,GAAG,KAAK,CAAA;SAC5E,CAAC;QACJ,MAAM,IAAI,kBAAkB,CAC1B,4EAA4E,OAAO,EAAE,CACtF,CAAA;IACH,CAAC;IACD,sEAAsE;IACtE,sCAAsC;IACtC,IAAI,MAAM,CAAC,QAAQ,KAAK,GAAG,IAAI,MAAM,CAAC,QAAQ,KAAK,EAAE,EAAE,CAAC;QACtD,MAAM,IAAI,kBAAkB,CAC1B,4HAA4H,CAC7H,CAAA;IACH,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,MAAM,KAAK,MAAM,CAAC,IAAI,OAAO,kBAAkB,CAAC,WAAW,CAAC,cAAc,kBAAkB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAClI,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,SAAS,kBAAkB,CAAC,IAAa;IACvC,IAAI,IAAY,CAAA;IAChB,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,IAAI,GAAG,IAAI,CAAA;IACb,CAAC;SAAM,IAAI,IAAI,YAAY,WAAW,EAAE,CAAC;QACvC,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;IACvC,CAAC;SAAM,IAAI,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,oEAAoE;QACpE,uEAAuE;QACvE,2DAA2D;QAC3D,MAAM,IAAI,GAAG,IAAuB,CAAA;QACpC,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAC7B,IAAI,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,CAC9D,CAAA;IACH,CAAC;SAAM,CAAC;QACN,OAAO,IAAI,CAAA;IACb,CAAC;IAED,IAAI,OAAgB,CAAA;IACpB,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAA;IAC1F,MAAM,GAAG,GAAG,OAAkC,CAAA;IAC9C,IAAI,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAChD,OAAO,GAAuB,CAAA;AAChC,CAAC"}

package/dist/resources/workspaces.js

@@ -3,16 +3,12 @@ import { WorkspaceScopedResource, extractData } from './base.js';
  * Manage Amigo Platform workspaces.
  * Workspaces are the top-level tenancy boundary for all resources.
  *
- * Note: list and create operate at account level (/v1/workspaces),
- * while get, update, and archive operate on a specific workspace.
+ * Note: list operates at account level (/v1/workspaces); creation goes
+ * through the authenticated self-service flow. The unauthenticated
+ * ``POST /v1/workspaces`` was removed in platform-api PR #2378 (orphan-
+ * maker). Get/update/archive/provision operate on a specific workspace.
  */
 export class WorkspacesResource extends WorkspaceScopedResource {
-    /** Create a new workspace (unauthenticated — no owner membership created) */
-    async create(body) {
-        return extractData(await this.client.POST('/v1/workspaces', {
-            body,
-        }));
-    }
     /** Create a workspace for the authenticated user and attach owner access */
     async createSelfService(body) {
         return extractData(await this.client.POST('/v1/workspaces/self-service', {

package/dist/resources/workspaces.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspaces.js","sourceRoot":"","sources":["../../src/resources/workspaces.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workspaces.js","sourceRoot":"","sources":["../../src/resources/workspaces.ts"],"names":[],"mappings":"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"}

package/dist/types/core/errors.d.ts

@@ -2,20 +2,74 @@
  * Error hierarchy for the Amigo Platform SDK.
  * All errors extend AmigoError which can be caught with a single catch.
  */
+import type { components } from '../generated/api.js';
 export interface ErrorContext {
     statusCode?: number;
     errorCode?: string;
     requestId?: string;
     detail?: string;
     context?: Record<string, unknown>;
+    /** Parsed error body (typed when recognized) */
+    errorBody?: PlatformErrorBody;
+    /** Raw body string for diagnostic logging — populated even on parse failure */
+    rawBody?: string;
 }
+/**
+ * FastAPI 422 validation-error body.
+ * Surfaces from openapi-typescript so consumers can read field-level errors.
+ */
+export type HttpValidationErrorBody = components['schemas']['HTTPValidationError'];
+/**
+ * Default FastAPI HTTPException shape (`raise HTTPException(status_code, detail=...)`).
+ *
+ * Most platform-api routes that don't define an explicit error model return
+ * this shape. `detail` may be a free-form string or a JSON-serializable object.
+ */
+export interface HttpExceptionBody {
+    detail: string | Record<string, unknown> | unknown[];
+    /** Populated by request-id middleware on bounded routes */
+    request_id?: string;
+    /** Populated by typed error responses (e.g. Surface lifecycle errors) */
+    error_code?: string;
+}
+/**
+ * Fallback shape used when the response body fails to parse or is empty.
+ * `rawBody` is the verbatim text (truncated to 8 KB to avoid log bloat).
+ */
+export interface UnparseableErrorBody {
+    detail: string;
+    raw_body: string;
+}
+/**
+ * Discriminated union of all error body shapes the platform API emits.
+ *
+ * Consumers should use the type guards (`isHttpException`,
+ * `isHttpValidationError`, `isUnparseableErrorBody`) rather than checking
+ * fields directly — both `HttpExceptionBody` and `HttpValidationErrorBody`
+ * have a `detail` field but it is shaped differently.
+ */
+export type PlatformErrorBody = HttpExceptionBody | HttpValidationErrorBody | UnparseableErrorBody;
 /** Base class for all Amigo Platform SDK errors */
-export declare class AmigoError extends Error {
+export declare class AmigoError<TBody extends PlatformErrorBody = PlatformErrorBody> extends Error {
     readonly statusCode?: number;
     readonly errorCode?: string;
     readonly requestId?: string;
     readonly detail?: string;
     readonly context?: Record<string, unknown>;
+    /**
+     * Typed body of the error response, when one was returned and successfully
+     * parsed. Use the `isHttpException` / `isHttpValidationError` /
+     * `isUnparseableErrorBody` type guards to narrow the discriminated union.
+     *
+     * Named `errorBody` (not `body`) to avoid colliding with the legacy
+     * `ParseError.body: string` field.
+     */
+    readonly errorBody?: TBody;
+    /**
+     * Raw response body (truncated to 8 KB). Populated even when parsing fails,
+     * so callers always have something to log when debugging server errors.
+     */
+    readonly rawBody?: string;
     constructor(message: string, ctx?: ErrorContext);
     toJSON(): Record<string, unknown>;
 }
@@ -82,4 +136,42 @@ export declare function isNotFoundError(err: unknown): err is NotFoundError;
 export declare function isRateLimitError(err: unknown): err is RateLimitError;
 export declare function isAuthenticationError(err: unknown): err is AuthenticationError;
 export declare function isRequestTimeoutError(err: unknown): err is RequestTimeoutError;
+export declare function isPermissionError(err: unknown): err is PermissionError;
+export declare function isConflictError(err: unknown): err is ConflictError;
+export declare function isValidationError(err: unknown): err is ValidationError;
+export declare function isServerError(err: unknown): err is ServerError;
+export declare function isNetworkError(err: unknown): err is NetworkError;
+/**
+ * Narrowed AmigoError where `errorBody` is guaranteed non-undefined.
+ * Used as the return-type for body type guards so consumers don't need to
+ * re-assert `errorBody !== undefined` after the guard.
+ */
+export type AmigoErrorWithBody<TBody extends PlatformErrorBody> = AmigoError<TBody> & {
+    readonly errorBody: TBody;
+};
+/**
+ * True when `err.errorBody` is the FastAPI 422 validation-error shape (an
+ * object with `detail: ValidationError[]`). Lets consumers iterate
+ * field-level errors without `as any`:
+ *
+ * ```ts
+ * if (isHttpValidationError(err)) {
+ *   for (const issue of err.errorBody.detail ?? []) {
+ *     console.log(issue.loc, issue.msg)
+ *   }
+ * }
+ * ```
+ */
+export declare function isHttpValidationError(err: unknown): err is AmigoErrorWithBody<HttpValidationErrorBody>;
+/**
+ * True when `err.errorBody` is the default FastAPI HTTPException shape
+ * (`{ detail: string | object | array }`, possibly with `error_code` /
+ * `request_id`). This is the most common error body across platform-api.
+ */
+export declare function isHttpException(err: unknown): err is AmigoErrorWithBody<HttpExceptionBody>;
+/**
+ * True when the response body could not be parsed as JSON (or was empty).
+ * `err.errorBody.raw_body` is the verbatim text (truncated to 8 KB).
+ */
+export declare function isUnparseableErrorBody(err: unknown): err is AmigoErrorWithBody<UnparseableErrorBody>;
 //# sourceMappingURL=errors.d.ts.map

package/dist/types/core/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/core/errors.ts"],"names":[],"mappings":"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"}

package/dist/types/core/reconnecting-websocket.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Reconnecting WebSocket primitive shared by the SDK's WS-based realtime
+ * helpers (text-stream, session-connect, observer).
+ *
+ * The platform exposes three workspace-scoped WebSocket surfaces with similar
+ * lifecycle requirements:
+ *
+ *   * Resume on transient drops with exponential backoff + full jitter
+ *   * Treat 4001 (client error) and 4403 (auth) close codes as terminal
+ *   * Treat 4029 (rate limit / cap) as terminal-but-retryable on a slow timer
+ *   * Watchdog the connection: if no message arrives within an idle window,
+ *     the upstream is dead even if the TCP socket has not closed; force a
+ *     reconnect
+ *   * Surface every typed message through ``onMessage`` and every state
+ *     transition through ``onStateChange``
+ *
+ * Before this primitive existed, every consumer (developer-console
+ * useStreamSession, useCallObserver, agent-engineering scripts) re-implemented
+ * the loop with subtle bugs (different idle thresholds, missing retry budget,
+ * no terminal-code handling). This module is the single canonical
+ * implementation; resource helpers compose it with their own message parsers
+ * and protocol details.
+ *
+ * @see ReconnectingWebSocket
+ * @see EventsResource for the analogous SSE-based helper
+ */
+/** Lifecycle states reported via {@link ReconnectingWebSocketOptions.onStateChange}. */
+export type ReconnectingWebSocketState = 'connecting' | 'open' | 'closing' | 'closed' | 'reconnecting' | 'terminal';
+/** Reasons surfaced to {@link ReconnectingWebSocketOptions.onError} on a terminal close. */
+export type ReconnectingWebSocketErrorReason = 'auth' | 'rate_limited' | 'client_error' | 'server_error' | 'reconnect_budget_exhausted' | 'aborted' | 'idle_watchdog' | 'open_failed' | 'unknown';
+/** Structured terminal error surfaced to consumers. */
+export declare class ReconnectingWebSocketError extends Error {
+    readonly reason: ReconnectingWebSocketErrorReason;
+    readonly closeCode: number | undefined;
+    readonly closeReason: string | undefined;
+    readonly attempts: number;
+    constructor(message: string, reason: ReconnectingWebSocketErrorReason, closeCode: number | undefined, closeReason: string | undefined, attempts: number);
+}
+/**
+ * Constructor for the underlying WebSocket. Defaults to the global
+ * ``WebSocket`` (browsers, Bun, Deno, Node 22+ via global) if available.
+ *
+ * Pass an explicit factory in environments without a global (older Node) or
+ * for tests that swap in a mock.
+ */
+export type WebSocketFactory = (url: string, protocols?: string | string[]) => WebSocket;
+/** Options for {@link ReconnectingWebSocket}. */
+export interface ReconnectingWebSocketOptions {
+    /** Target ws:// or wss:// URL. */
+    url: string;
+    /**
+     * Optional WebSocket subprotocols. The platform's auth scheme passes the
+     * bearer token here (``['auth', token]``) so it never appears in the URL.
+     */
+    protocols?: string | string[];
+    /**
+     * Initial backoff delay (ms). Doubles with full jitter on each successive
+     * failure up to ``maxDelayMs``. Default ``1_000``.
+     */
+    initialDelayMs?: number;
+    /** Cap on the reconnect backoff delay (ms). Default ``30_000``. */
+    maxDelayMs?: number;
+    /**
+     * Maximum number of reconnect attempts before giving up. Default ``10``.
+     * Set to ``Infinity`` to retry forever (rely on AbortSignal for shutdown).
+     */
+    maxReconnects?: number;
+    /**
+     * Idle watchdog (ms). If no message arrives within this window the
+     * connection is considered dead and is force-closed; the reconnect loop
+     * then handles the rebuild. Default ``45_000`` (matches the longest
+     * platform endpoint heartbeat). Set to ``0`` to disable.
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Cancellation signal. Aborting the signal closes the underlying socket
+     * and stops the reconnect loop. The ``done`` promise resolves once the
+     * teardown completes.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional WebSocket factory. Defaults to ``globalThis.WebSocket`` if
+     * available; throws at first connect attempt otherwise.
+     */
+    webSocketFactory?: WebSocketFactory;
+    /**
+     * Invoked when the underlying socket transitions states. Mostly useful
+     * for surfacing reconnects to the UI (e.g., "Reconnecting…" banner).
+     */
+    onStateChange?: (state: ReconnectingWebSocketState) => void;
+    /**
+     * Invoked once per inbound frame. ``MessageEvent.data`` is delivered raw
+     * — consumers parse JSON / binary themselves.
+     */
+    onMessage: (event: MessageEvent) => void;
+    /**
+     * Invoked just before each reconnect attempt with the 1-based attempt
+     * number, the planned delay (ms), and the close code that triggered the
+     * reconnect.
+     */
+    onReconnect?: (info: {
+        attempt: number;
+        delayMs: number;
+        closeCode: number | undefined;
+    }) => void;
+    /**
+     * Invoked exactly once per ``ReconnectingWebSocket`` instance on a
+     * terminal failure (consumer-aborted, reconnect budget exhausted, or a
+     * close code in the terminal set: 4001 / 4003 / 4403 / 4100 / 1008).
+     */
+    onError?: (error: ReconnectingWebSocketError) => void;
+}
+/** Handle returned by {@link createReconnectingWebSocket}. */
+export interface ReconnectingWebSocketHandle {
+    /**
+     * Resolves when the loop has fully stopped (post-abort cleanup complete).
+     * Never rejects; consume errors via ``onError``.
+     */
+    done: Promise<void>;
+    /**
+     * Send a frame on the currently open socket. Throws if no socket is
+     * currently open. Use ``onStateChange`` to gate sends, or buffer in
+     * caller code.
+     */
+    send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void;
+    /**
+     * Close the connection and stop reconnecting. Equivalent to aborting the
+     * caller-supplied signal. Idempotent.
+     */
+    close(code?: number, reason?: string): void;
+    /** Latest known lifecycle state. */
+    readonly state: ReconnectingWebSocketState;
+}
+/**
+ * Build a managed reconnecting WebSocket.
+ *
+ * The returned handle is the only public surface; the underlying
+ * ``WebSocket`` is held privately so consumers cannot bypass the lifecycle
+ * machinery (which would defeat the watchdog and reconnect loop).
+ *
+ * @example
+ * ```ts
+ * const handle = createReconnectingWebSocket({
+ *   url: client.conversations.sessionConnectUrl({ serviceId, entityId }),
+ *   protocols: sessionConnectAuthProtocols(apiKey),
+ *   onMessage: (e) => console.log('frame', e.data),
+ *   onStateChange: (s) => console.log('state', s),
+ *   onError: (err) => console.error('terminal:', err.reason, err.closeCode),
+ * });
+ *
+ * handle.send(JSON.stringify({ type: 'user_text', text: 'hi' }));
+ * await handle.done;  // resolves after handle.close() or terminal error
+ * ```
+ */
+export declare function createReconnectingWebSocket(options: ReconnectingWebSocketOptions): ReconnectingWebSocketHandle;
+//# sourceMappingURL=reconnecting-websocket.d.ts.map

package/dist/types/core/reconnecting-websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconnecting-websocket.d.ts","sourceRoot":"","sources":["../../../src/core/reconnecting-websocket.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,wFAAwF;AACxF,MAAM,MAAM,0BAA0B,GAClC,YAAY,GACZ,MAAM,GACN,SAAS,GACT,QAAQ,GACR,cAAc,GACd,UAAU,CAAA;AAEd,4FAA4F;AAC5F,MAAM,MAAM,gCAAgC,GACxC,MAAM,GACN,cAAc,GACd,cAAc,GACd,cAAc,GACd,4BAA4B,GAC5B,SAAS,GACT,eAAe,GACf,aAAa,GACb,SAAS,CAAA;AAEb,uDAAuD;AACvD,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,MAAM,EAAE,gCAAgC,CAAA;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;gBAGvB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,gCAAgC,EACxC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,QAAQ,EAAE,MAAM;CASnB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,SAAS,CAAA;AAExF,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAA;IAEX;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAE7B;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IAEvB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IAEpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IAEnC;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAA;IAE3D;;;OAGG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IAExC;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,KAAK,IAAI,CAAA;IAEjG;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,CAAA;CACtD;AAED,8DAA8D;AAC9D,MAAM,WAAW,2BAA2B;IAC1C;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAEnB;;;;OAIG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,GAAG,eAAe,GAAG,IAAI,CAAA;IAEnE;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAE3C,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAA;CAC3C;AA8BD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,4BAA4B,GACpC,2BAA2B,CAiF7B"}