@pouchy_ai/companion-sdk 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -12,7 +12,38 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
-## [0.15.0] - 2026-07-08
+## [0.17.0] - 2026-07-08
+
+### Added
+
+Surface completion — the last three wire types that lacked a typed
+client accessor now have one. All additive; wire protocol unchanged
+(`PROTOCOL_VERSION 1`).
+
+- **`onVoiceInject(fn)`** + `VoiceInjectPayload { text, speak }` — a typed
+  subscription for `companion.voice_inject` (a `voiceRelevant` world-state
+  line the companion should say aloud during a live call). The event was
+  already emitted; this is the public handler + payload type for it.
+- **`client.setModalities(modalities)`** — change a live session's I/O
+  modalities mid-session (e.g. toggle `voice`). Intersected with the
+  token's granted modalities server-side; returns the effective set.
+  Backed by `POST /api/companion/session/{id}/modalities`.
+- **`client.ping()`** — keepalive that bumps the session's last-seen time
+  so a long-idle embed stays "live" within the TTL (cross-app A2A friend
+  messages keep reaching it). Backed by
+  `POST /api/companion/session/{id}/ping`.
+
+### Added
+
+- **Conversation history** — `client.history({ limit })` fetches this session's
+  recent turns (`{ user, assistant, ts }`, oldest→newest) so a reconnecting
+  embed can restore its transcript. Distinct from `recall` (durable memory /
+  facts): this is the raw exchange log. Reads the token's OWN session only
+  (tenant-safe by construction — the turn log is keyed by the token's uid);
+  internal per-turn trace (`meta`) is stripped server-side. `limit` defaults to
+  20, capped at 50. New type `CompanionTurn`. Backed by
+  `GET /api/companion/session/{sessionId}/history`. Wire protocol unchanged
+  (`PROTOCOL_VERSION 1`) — this is a REST method, not a stream event.
 
 ### Added
 

package/README.md

@@ -70,6 +70,7 @@ Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers:
 | `onConfirmRequest(fn)` | `companion.confirm_request` | a sensitive-op approval request. **Platform session tokens** (your end users): show your own confirm card and resolve it with `confirmAction` — this is how confirm-gated custom skills (POST / credentialed) run. First-party user tokens: observe-only — approval stays first-party (where the `stepUp:true` biometric gate lives) |
 | `onAudio(fn)` | `companion.audio` | TTS clip (non-call modality) |
 | `onExpression(fn)` | `companion.expression` | avatar viseme / expression / gesture |
+| `onVoiceInject(fn)` | `companion.voice_inject` | `fn({text, speak})` — a `voiceRelevant` world-state line to say aloud during a live call; route `text` to your voice session when `speak` |
 | `onTyping(fn)` | `companion.typing` | activity indicator — `fn({active})` fires `true` when a turn starts working and `false` when it finishes / pauses, spanning the tool-loop / thinking phase before the first text delta. Drive a "typing…" state |
 | `onUsage(fn)` | `control.usage` | per-token metering echo |
 | `onError(fn)` | `control.error` | agent / stream errors |

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundType, PendingConfirm, RenderInterfacePayload, SocialMessagePayload, TypingPayload, UsagePayload, WorldStateEvent } from './protocol.js';
+import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundType, PendingConfirm, RenderInterfacePayload, SocialMessagePayload, TypingPayload, UsagePayload, VoiceInjectPayload, WorldStateEvent } from './protocol.js';
 /** Ergonomic world-state input: a WorldStateEvent with the CloudEvents plumbing
  *  (specversion / id / source) optional — sendWorldState fills them. */
 export type WorldStateInput<D = unknown> = Omit<WorldStateEvent<D>, 'specversion' | 'id' | 'source'> & Partial<Pick<WorldStateEvent<D>, 'specversion' | 'id' | 'source'>>;
@@ -100,6 +100,14 @@ export interface RecalledMemory {
     namespace: string;
     createdAt?: string;
 }
+/** One exchange from a session's conversation log (see `history`). `user` is the
+ *  end-user's message, `assistant` the companion's reply; either may be `''` for
+ *  a paused / assistant-only row. `ts` is epoch ms. */
+export interface CompanionTurn {
+    user: string;
+    assistant: string;
+    ts: number;
+}
 /** The user's current companion avatar (see getAvatar). */
 export interface CompanionAvatar {
     /** Companion display name (the user's chosen name), or null. */
@@ -273,6 +281,25 @@ export declare class CompanionClient {
     recall(opts?: {
         limit?: number;
     }): Promise<RecalledMemory[]>;
+    /** Fetch this session's recent conversation turns (oldest→newest) so a
+     *  reconnecting embed can restore its transcript. Distinct from `recall`
+     *  (durable memory / facts) — this is the raw exchange log. Returns the
+     *  token's OWN session turns only; requires a live session (call `connect`
+     *  first). `limit` defaults to 20, capped at 50. */
+    history(opts?: {
+        limit?: number;
+    }): Promise<CompanionTurn[]>;
+    /** Change this session's I/O modalities mid-session (e.g. enable/disable
+     *  `voice`). The request is intersected with the token's granted modalities
+     *  server-side — a session can't widen past its key — and the EFFECTIVE set is
+     *  returned. Requires a live session. */
+    setModalities(modalities: string[]): Promise<{
+        modalities: string[];
+    }>;
+    /** Keepalive: bump this session's last-seen time so a long-idle embed stays
+     *  "live" within the session TTL (cross-app A2A friend messages keep reaching
+     *  it). Cheap; call it on a timer for a background tab. Requires a live session. */
+    ping(): Promise<void>;
     /** Remember a fact (into this app's namespace unless `namespace` is given and
      *  the token has the core scope). Intimate-tier writes are rejected server-side. */
     remember(fact: {
@@ -407,6 +434,11 @@ export declare class CompanionClient {
      *  tool-loop / thinking phase before the first text delta. Drive a "typing…"
      *  affordance from it: `client.onTyping(({ active }) => setTyping(active))`. */
     onTyping(handler: (payload: TypingPayload, envelope: CompanionEnvelope) => void): () => void;
+    /** Convenience: subscribe to voice-inject cues (companion.voice_inject) — a
+     *  `voiceRelevant` world-state line the companion should say aloud during a
+     *  live call. Route `payload.text` to your active voice session when
+     *  `payload.speak`. A text-only host can ignore it. */
+    onVoiceInject(handler: (payload: VoiceInjectPayload, envelope: CompanionEnvelope) => void): () => void;
     /** Open the event stream (auto-reconnecting with the resume cursor). Uses the
      *  WebSocket plane when opted in + available, else SSE. */
     start(): void;

package/dist/client.js

@@ -465,6 +465,52 @@ export class CompanionClient {
         }
         return json.memories ?? [];
     }
+    /** Fetch this session's recent conversation turns (oldest→newest) so a
+     *  reconnecting embed can restore its transcript. Distinct from `recall`
+     *  (durable memory / facts) — this is the raw exchange log. Returns the
+     *  token's OWN session turns only; requires a live session (call `connect`
+     *  first). `limit` defaults to 20, capped at 50. */
+    async history(opts) {
+        const id = this.requireSession();
+        const qs = opts?.limit ? `?limit=${encodeURIComponent(opts.limit)}` : '';
+        const res = await this.doFetch(this.url(`/api/companion/session/${encodeURIComponent(id)}/history${qs}`), { headers: { Authorization: `Bearer ${this.opts.token}` } });
+        const json = (await res.json().catch(() => null));
+        if (!res.ok || !json || json.ok === false) {
+            throw new CompanionError(json?.error || `history failed (${res.status})`, res.status);
+        }
+        return json.history ?? [];
+    }
+    /** Change this session's I/O modalities mid-session (e.g. enable/disable
+     *  `voice`). The request is intersected with the token's granted modalities
+     *  server-side — a session can't widen past its key — and the EFFECTIVE set is
+     *  returned. Requires a live session. */
+    async setModalities(modalities) {
+        const id = this.requireSession();
+        const res = await this.doFetch(this.url(`/api/companion/session/${encodeURIComponent(id)}/modalities`), {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.opts.token}`,
+                'Content-Type': 'application/json'
+            },
+            body: JSON.stringify({ modalities })
+        });
+        const json = (await res.json().catch(() => null));
+        if (!res.ok || !json || json.ok === false) {
+            throw new CompanionError(json?.error || `setModalities failed (${res.status})`, res.status);
+        }
+        return { modalities: json.modalities ?? modalities };
+    }
+    /** Keepalive: bump this session's last-seen time so a long-idle embed stays
+     *  "live" within the session TTL (cross-app A2A friend messages keep reaching
+     *  it). Cheap; call it on a timer for a background tab. Requires a live session. */
+    async ping() {
+        const id = this.requireSession();
+        const res = await this.doFetch(this.url(`/api/companion/session/${encodeURIComponent(id)}/ping`), { method: 'POST', headers: { Authorization: `Bearer ${this.opts.token}` } });
+        if (!res.ok) {
+            const json = (await res.json().catch(() => null));
+            throw new CompanionError(json?.error || `ping failed (${res.status})`, res.status);
+        }
+    }
     /** Remember a fact (into this app's namespace unless `namespace` is given and
      *  the token has the core scope). Intimate-tier writes are rejected server-side. */
     async remember(fact) {
@@ -655,6 +701,17 @@ export class CompanionClient {
                 handler(p, env);
         });
     }
+    /** Convenience: subscribe to voice-inject cues (companion.voice_inject) — a
+     *  `voiceRelevant` world-state line the companion should say aloud during a
+     *  live call. Route `payload.text` to your active voice session when
+     *  `payload.speak`. A text-only host can ignore it. */
+    onVoiceInject(handler) {
+        return this.on('companion.voice_inject', (env) => {
+            const p = env.payload;
+            if (p && typeof p === 'object' && typeof p.text === 'string')
+                handler(p, env);
+        });
+    }
     /** Open the event stream (auto-reconnecting with the resume cursor). Uses the
      *  WebSocket plane when opted in + available, else SSE. */
     start() {

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { CompanionClient, type CompanionClientOptions } from './client.js';
 export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js';
-export type { CompanionClientOptions, HelloAck, RecalledMemory, CallCredentials, CompanionToolDecl, WorldStateInput, CompanionAvatar, BrandIconSize } from './client.js';
+export type { CompanionClientOptions, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, WorldStateInput, CompanionAvatar, BrandIconSize } from './client.js';
 export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_VISUAL_TOOLS, AVATAR_VISUAL_TOOL_NAMES } from './call.js';
 export type { CompanionCall, CompanionCallOptions, VoiceToolBridge } from './call.js';
-export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, PendingConfirm, AudioClipPayload, ExpressionPayload, TypingPayload, UsagePayload } from './protocol.js';
+export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, PendingConfirm, AudioClipPayload, ExpressionPayload, TypingPayload, VoiceInjectPayload, UsagePayload } from './protocol.js';
 /** Create a companion client. */
 export declare function createCompanion(opts: CompanionClientOptions): CompanionClient;

package/dist/protocol.d.ts

@@ -120,6 +120,15 @@ export interface SocialMessagePayload {
     /** ISO timestamp of delivery. */
     createdAt: string;
 }
+/** Payload of a `companion.voice_inject` event — a `voiceRelevant` world-state
+ *  line the companion should say aloud DURING a live call (the app pushed the
+ *  moment via `sendWorldState`; the server decided it's worth voicing). `speak`
+ *  is the host's cue to route `text` to the active voice session. A text-only
+ *  host can ignore it — the moment still shaped the next turn's context. */
+export interface VoiceInjectPayload {
+    text: string;
+    speak: boolean;
+}
 /** Payload of a `companion.typing` event — an activity indicator bracketing the
  *  model work of a turn: `active:true` when the companion starts working,
  *  `active:false` when it emits its reply or pauses for an app tool result. It

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Embed the Pouchy companion — chat, voice, tools, memory, live world-state, instant UI, and agent-to-agent messaging — in any app, game, or site.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",