@craftedxp/sdk-node 0.16.0 → 0.18.0

package/README.md

@@ -284,6 +284,8 @@ for await (const call of client.calls.listAll({ agentId })) {
 ## Changelog
 
 - **Unreleased** _(forward-looking)_ — `isPersonal?: boolean` on `Agent` and `AgentCreateInput` (and so on `AgentUpdateInput`). Assistant-only: when `true`, the learning tools (`remember_fact`, `add_correction`, `add_skill_hint`) are live on every `ct_`-token call rather than only on `mode=learning`. Server-side field — no runtime change in this package.
+- **Unreleased** _(forward-looking)_ — Per-call `agentSpeaksFirst` override on `callTokens.mint` (0.18.0, publish pending; server support 2026-09-02).
+- **0.17.0** — `channel` on `CallTokenMintInput` / `CallTokenMintResult` / `CallRecord` widened to include `'multimodal'` (typed turns + live audio in one WS session). Type-only plumbing in this package — accepted at mint (assistant-only, same gate as `'text'`) and threaded through; the server's handler semantics for it shipped 2026-09-01 (phase 2/3); `chatsFor(token)` (HTTP+SSE) always rejects a `'multimodal'` token. No runtime change in this package.
 - **0.16.0** — `debug?: boolean` on `CallTokenMintInput`. Operator-gated (Firebase-admin or `sk_`-key mints only — silently stripped otherwise); when set, the call streams diagnostic frames (`tool_call` / `tool_result` / `phase_marker` / `prefetch*`) to the client. Request-only field — the mint response does not echo it back (see `docs/openapi.yaml`). No client-side behavior change; the HTTP layer already posts `body: input` verbatim, so this is a type-only addition.
 - **0.15.0** — `client.speech` namespace (`synthesize` / `enqueue` / `get` / `list` / `delete`) for pre-generated agent audio (`POST /v1/speech`), plus `speech.ready` / `speech.failed` webhook event types and the `accepted` error code (`synthesize` → 202 handoff). Requires server ≥ the 2026-08 speech release.
 - **0.14.0** — `client.spaces` namespace (create / get / list / update / delete) for durable multi-party spaces, plus the standalone `buildJoinUrl(spaceOrCode, { baseUrl, style? })` helper for white-label participant links. No server changes — the `/v1/spaces` endpoints already existed.

package/dist/index.d.mts

@@ -293,8 +293,8 @@ interface CallRecord {
     costBreakdown?: CostBreakdown;
     errorMessage?: string;
     metadata?: Record<string, string>;
-    /** Transport channel the call was carried over (`'voice'` = WebRTC/WS audio, `'text'` = text-only). */
-    channel?: 'voice' | 'text';
+    /** Transport channel the call was carried over (`'voice'` = WebRTC/WS audio, `'text'` = text-only, `'multimodal'` = typed turns + live audio in one WS session). */
+    channel?: 'voice' | 'text' | 'multimodal';
 }
 interface CallListFilters {
     agentId?: string;
@@ -397,13 +397,33 @@ interface CallTokenMintInput {
      * default user-initiated connect. See docs/sdks.md "Agent-initiated calls".
      */
     initiatedBy?: 'user' | 'agent';
+    /**
+     * Per-call override of the agent's `agentSpeaksFirst`. `false` opens the
+     * call silently — the caller speaks first (a look-to-wake desk device, a
+     * "tap to talk" surface). `true` forces the agent's greeting turn even on
+     * an agent configured silent (an alarm the device dialled on the user's
+     * behalf, briefed via `context`). Omit to use the agent's own setting.
+     * Assistant agents only; room/transcribe agents are always silent and the
+     * field is accepted but ignored. The `context` briefing shapes the
+     * greeting only when the agent has no pre-rendered `opening`; an agent
+     * with `opening.enabled` plays its static opening line. With `false`, the
+     * platform also suppresses its idle "are you still there?" nudge until
+     * the caller's first turn; a caller who never speaks is simply timed out
+     * in silence.
+     * Server support: 2026-09-02.
+     */
+    agentSpeaksFirst?: boolean;
     /**
      * Session channel selector. `voice` (default) routes to WS/WebRTC audio;
-     * `text` routes to HTTP+SSE chat via the `chats` resource. `text` requires
-     * a `type: 'assistant'` agent; non-assistant agents are rejected at mint
-     * (`wrong_agent_type`), as is `mode: 'learning'` on a non-assistant agent.
+     * `text` routes to HTTP+SSE chat via the `chats` resource (or the same WS
+     * as `voice`, as a typed session). `text` requires a `type: 'assistant'`
+     * agent; non-assistant agents are rejected at mint (`wrong_agent_type`),
+     * as is `mode: 'learning'` on a non-assistant agent. `multimodal` combines
+     * typed turns and live audio in one WS session — accepted at mint as of
+     * this SDK version, and the server's handler semantics for it shipped
+     * 2026-09-01 (phase 2/3); the HTTP+SSE `chats` resource always rejects it.
      */
-    channel?: 'voice' | 'text';
+    channel?: 'voice' | 'text' | 'multimodal';
     /**
      * Session purpose. `standard` (default) is a regular call. `learning`
      * (admin-bypass only) flags a self-learning session — see Phase 19.
@@ -441,9 +461,10 @@ interface CallTokenMintResult {
     /**
      * Session channel echoed back from the mint. Useful for the client SDK
      * to dispatch correctly — text-mode tokens go to `chatsFor(token)`,
-     * voice-mode tokens go to `voice-js`/`voice-rn`.
+     * voice-mode tokens go to `voice-js`/`voice-rn`, multimodal-mode tokens
+     * go to the WS call path (handler semantics shipped 2026-09-01, phase 2/3).
      */
-    channel?: 'voice' | 'text';
+    channel?: 'voice' | 'text' | 'multimodal';
 }
 interface CallTokenSummary {
     tokenId: string;

package/dist/index.d.ts

@@ -293,8 +293,8 @@ interface CallRecord {
     costBreakdown?: CostBreakdown;
     errorMessage?: string;
     metadata?: Record<string, string>;
-    /** Transport channel the call was carried over (`'voice'` = WebRTC/WS audio, `'text'` = text-only). */
-    channel?: 'voice' | 'text';
+    /** Transport channel the call was carried over (`'voice'` = WebRTC/WS audio, `'text'` = text-only, `'multimodal'` = typed turns + live audio in one WS session). */
+    channel?: 'voice' | 'text' | 'multimodal';
 }
 interface CallListFilters {
     agentId?: string;
@@ -397,13 +397,33 @@ interface CallTokenMintInput {
      * default user-initiated connect. See docs/sdks.md "Agent-initiated calls".
      */
     initiatedBy?: 'user' | 'agent';
+    /**
+     * Per-call override of the agent's `agentSpeaksFirst`. `false` opens the
+     * call silently — the caller speaks first (a look-to-wake desk device, a
+     * "tap to talk" surface). `true` forces the agent's greeting turn even on
+     * an agent configured silent (an alarm the device dialled on the user's
+     * behalf, briefed via `context`). Omit to use the agent's own setting.
+     * Assistant agents only; room/transcribe agents are always silent and the
+     * field is accepted but ignored. The `context` briefing shapes the
+     * greeting only when the agent has no pre-rendered `opening`; an agent
+     * with `opening.enabled` plays its static opening line. With `false`, the
+     * platform also suppresses its idle "are you still there?" nudge until
+     * the caller's first turn; a caller who never speaks is simply timed out
+     * in silence.
+     * Server support: 2026-09-02.
+     */
+    agentSpeaksFirst?: boolean;
     /**
      * Session channel selector. `voice` (default) routes to WS/WebRTC audio;
-     * `text` routes to HTTP+SSE chat via the `chats` resource. `text` requires
-     * a `type: 'assistant'` agent; non-assistant agents are rejected at mint
-     * (`wrong_agent_type`), as is `mode: 'learning'` on a non-assistant agent.
+     * `text` routes to HTTP+SSE chat via the `chats` resource (or the same WS
+     * as `voice`, as a typed session). `text` requires a `type: 'assistant'`
+     * agent; non-assistant agents are rejected at mint (`wrong_agent_type`),
+     * as is `mode: 'learning'` on a non-assistant agent. `multimodal` combines
+     * typed turns and live audio in one WS session — accepted at mint as of
+     * this SDK version, and the server's handler semantics for it shipped
+     * 2026-09-01 (phase 2/3); the HTTP+SSE `chats` resource always rejects it.
      */
-    channel?: 'voice' | 'text';
+    channel?: 'voice' | 'text' | 'multimodal';
     /**
      * Session purpose. `standard` (default) is a regular call. `learning`
      * (admin-bypass only) flags a self-learning session — see Phase 19.
@@ -441,9 +461,10 @@ interface CallTokenMintResult {
     /**
      * Session channel echoed back from the mint. Useful for the client SDK
      * to dispatch correctly — text-mode tokens go to `chatsFor(token)`,
-     * voice-mode tokens go to `voice-js`/`voice-rn`.
+     * voice-mode tokens go to `voice-js`/`voice-rn`, multimodal-mode tokens
+     * go to the WS call path (handler semantics shipped 2026-09-01, phase 2/3).
      */
-    channel?: 'voice' | 'text';
+    channel?: 'voice' | 'text' | 'multimodal';
 }
 interface CallTokenSummary {
     tokenId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craftedxp/sdk-node",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Node.js / TypeScript SDK for the voice agent platform. Server-side API client — mint call tokens, manage agents, query calls, upload knowledge-base docs.",
   "author": "Crafted XP",
   "license": "MIT",