@pouchy_ai/companion-sdk 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -12,6 +12,53 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.22.0] - 2026-07-11
+
+### Added
+
+- **Runtime protocol constants are now exported.** `PROTOCOL_VERSION`,
+  `INBOUND_TYPES`, and `OUTBOUND_TYPES` are re-exported from the package entry —
+  previously only their *types* were reachable. A host can now assert the
+  protocol version or enumerate/validate the event vocabulary at runtime without
+  hard-coding the strings.
+- **`ToolCallPayload` type.** The `companion.tool_call` payload
+  (`{ id, name, args }`) now has a named, exported interface, so a consumer using
+  the generic `on('companion.tool_call', …)` gets a typed payload — parity with
+  `RenderInterfacePayload`, `ConfirmRequestPayload`, and the other payload types.
+  `onToolCall`'s callback is typed against it.
+
+No wire-protocol change (`PROTOCOL_VERSION` stays `1`); this is a purely additive
+type/export surface, hence the minor bump.
+
+## [0.21.0] - 2026-07-11
+
+### Added
+
+- **Token refresh:** `client.setToken(token)` swaps the bearer used by every
+  subsequent request and stream reconnect, and the new `onAuthError` client
+  option refreshes on demand — a 401 (REST **or** event stream) calls it; return
+  a fresh token (e.g. re-minted via `POST /v1/sessions`) and the client retries
+  transparently, return `null` to surface the failure exactly as before.
+  Concurrent 401s share one refresh; the stream loop caps consecutive
+  refresh-and-reject cycles at 3 so a bad hook can't hot-loop. Previously a
+  1-hour session token expiring mid-embed silently stopped reply delivery
+  (`stream_unauthorized`) with no recovery short of rebuilding the client.
+- **Semantic recall:** `recall({ query })` — the server has always supported
+  `?q=` semantic search over the token-visible facts; the client now exposes it.
+  Without `query` the ranking is importance/recency, as before.
+- **Machine-readable error codes:** companion API error responses now carry a
+  stable `code` (`missing_token` / `invalid_token` / `missing_scope` /
+  `invalid_request` / `session_not_found` / `turn_pending` / `no_pending_tools` /
+  `unknown_call` / `payload_too_large` / `forbidden` / `unavailable`), so
+  `CompanionError.code` is finally switchable for HTTP failures — the type
+  always promised it; the server now delivers it. The vocabulary is append-only.
+
+### Fixed
+
+- README method table showed pre-0.18 signatures for `recall` / `remember` /
+  `ingestKnowledge` / `history` (positional args instead of the actual object
+  args). Corrected to match the shipped API.
+
 ## [0.20.0] - 2026-07-11
 
 ### Added

package/README.md

@@ -96,11 +96,12 @@ local/device skills).
 
 | Method | What it does |
 |---|---|
-| `recall(query)` / `remember(text)` | Read / write the token-scoped memory namespace. |
-| `ingestKnowledge(text, opts?)` / `ingestFile(file)` | Push documents into the user's knowledge base ("My materials"); needs `memory.write:core`. |
-| `history(limit?)` | Fetch the session transcript — restore chat on reload. |
+| `recall({ query?, limit? })` / `remember({ content, … })` | Read / write the token-scoped memory namespace. `query` runs SEMANTIC search over the facts server-side (embedding-based, ranked fallback); omit it for the plain importance/recency ranking. |
+| `ingestKnowledge({ text, name, … })` / `ingestFile(file)` | Push documents into the user's knowledge base ("My materials"); needs `memory.write:core`. |
+| `history({ limit? })` | Fetch the session transcript — restore chat on reload. |
 | `setModalities([...])` | Switch active I/O mid-session (within the token's grant). |
 | `ping()` | Keepalive for long-idle embeds. |
+| `setToken(token)` | Swap the bearer for every subsequent request + stream reconnect — session tokens expire (1h default), so call this when your backend re-mints one. Prefer the `onAuthError` constructor option to refresh on demand instead. |
 | `pendingConfirms()` / `confirmAction(id, approve)` | List / resolve pending sensitive-action confirms (platform session tokens). On `{ status: 'exec_failed', retryable: true }` you MAY re-call the same confirmId — idempotent actions only. |
 | `endSession()` | Distill the session into durable memory now; returns `{ skipped?: 'no_session' \| 'no_content' \| 'throttled' }`. |
 | `close()` | One-call teardown: `stop()` + `endSession()` — the text-session mirror of the call handle's `close()`. |
@@ -139,6 +140,12 @@ exported: `COMPANION_MODALITIES`, `REPRESENT_SCOPES`, `DEFAULT_MODALITIES`,
 `isRepresentScope()`. The list mirrors the server vocabulary and is guarded by
 the SDK's drift test.
 
+The wire-protocol runtime constants are exported too — `PROTOCOL_VERSION`,
+`INBOUND_TYPES`, and `OUTBOUND_TYPES` — so you can assert the version or
+enumerate/validate the event vocabulary without hard-coding strings. Every
+outbound payload has a named type; `ToolCallPayload` (`{ id, name, args }`) types
+the `companion.tool_call` event and `onToolCall`'s callback.
+
 ## Representative mode (代聊)
 
 Pass a `visitor` and the session flips from **owner-facing** to **representative**:

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundType, PendingConfirm, RenderInterfacePayload, SocialMessagePayload, TypingPayload, UsagePayload, VoiceInjectPayload, WorldStateEvent } from './protocol.js';
+import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, ExpressionPayload, InterfaceUpdatePayload, OutboundType, PendingConfirm, RenderInterfacePayload, SocialMessagePayload, ToolCallPayload, 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'>>;
@@ -47,6 +47,14 @@ export interface CompanionClientOptions {
     /** Injectable WebSocket constructor (Node without a global WebSocket, or
      *  tests). Defaults to globalThis.WebSocket when present. */
     webSocketImpl?: typeof WebSocket;
+    /** Called when a request or the event stream is rejected with 401 (expired /
+     *  revoked token — session tokens live 1h by default). Return a fresh token
+     *  (e.g. re-minted by your backend via POST /v1/sessions) and the client
+     *  retries transparently; return null to give up, surfacing the failure
+     *  exactly as without this hook. Scope denials (403 `missing_scope`) are
+     *  configuration errors and never trigger it. Alternative: call `setToken()`
+     *  proactively on your own refresh schedule. */
+    onAuthError?: () => string | null | Promise<string | null>;
 }
 export interface HelloAck {
     session: string;
@@ -190,6 +198,19 @@ export declare class CompanionClient {
     constructor(opts: CompanionClientOptions);
     /** The active session id, or null before connect(). */
     get sessionId(): string | null;
+    /** Swap the bearer token used by every subsequent request and stream
+     *  reconnect. Session tokens expire (default 1h) — call this when your
+     *  backend re-mints one, or wire `onAuthError` to do it on demand. */
+    setToken(token: string): void;
+    private refreshing;
+    /** Run opts.onAuthError (deduped), apply the fresh token, and report whether
+     *  the caller should retry. Never throws — a failed refresh means "surface
+     *  the original 401". */
+    private tryRefreshToken;
+    /** doFetch with one transparent retry after a 401-triggered token refresh.
+     *  Everything except the stream loop (which has its own auth handling) goes
+     *  through here. */
+    private fetchAuthed;
     private url;
     private jsonHeaders;
     private requireSession;
@@ -312,11 +333,7 @@ export declare class CompanionClient {
      *  hang the call. */
     private invokeVoiceTool;
     /** Convenience: subscribe to tool-call requests from the companion. */
-    onToolCall(handler: (call: {
-        id: string;
-        name: string;
-        args: string;
-    }, envelope: CompanionEnvelope) => void): () => void;
+    onToolCall(handler: (call: ToolCallPayload, envelope: CompanionEnvelope) => void): () => void;
     /** Convenience: subscribe to errors the companion surfaces — server-side agent
      *  errors and stream failures (e.g. a permanent `stream_unauthorized`) both
      *  arrive as `control.error`. Returns an unsubscribe fn. */
@@ -324,9 +341,14 @@ export declare class CompanionClient {
         code: string;
         message: string;
     }, envelope: CompanionEnvelope) => void): () => void;
-    /** Recall the memory this token is authorized to see (ranked). */
+    /** Recall the memory this token is authorized to see. Without `query` the
+     *  facts come back ranked by importance/recency; with `query` the server
+     *  runs semantic search over them (embedding-based, falls back to ranked
+     *  when embeddings are unavailable) — e.g.
+     *  `recall({ query: 'food preferences', limit: 10 })`. */
     recall(opts?: {
         limit?: number;
+        query?: string;
     }): Promise<RecalledMemory[]>;
     /** Fetch this session's recent conversation turns (oldest→newest) so a
      *  reconnecting embed can restore its transcript. Distinct from `recall`

package/dist/client.js

@@ -8,8 +8,10 @@
 //   await c.sendText('how am I doing?');
 //
 // Pure, dependency-free, isomorphic (browser + Node 18+ fetch). The transport is
-// an internal detail — when the WebSocket plane lands it slots in behind this
-// same API. Protocol types are shared with the server via companion-protocol.
+// an internal detail: the default REST/SSE plane, or an opt-in WebSocket plane
+// (ws-transport.ts) that degrades back to SSE on failure — both sit behind this
+// same API. Protocol types are a self-contained copy of the server's contract,
+// kept in lockstep by protocol.drift.test.ts.
 import { PROTOCOL_VERSION } from './protocol.js';
 import { parseSse } from './sse.js';
 import { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_VISUAL_TOOLS, AVATAR_VISUAL_TOOL_NAMES } from './call.js';
@@ -63,6 +65,45 @@ export class CompanionClient {
     get sessionId() {
         return this._session;
     }
+    /** Swap the bearer token used by every subsequent request and stream
+     *  reconnect. Session tokens expire (default 1h) — call this when your
+     *  backend re-mints one, or wire `onAuthError` to do it on demand. */
+    setToken(token) {
+        if (!token)
+            throw new CompanionError('setToken: token is required', 0, 'missing_option');
+        this.opts.token = token;
+    }
+    // In-flight onAuthError call, shared so concurrent 401s trigger ONE refresh.
+    refreshing = null;
+    /** Run opts.onAuthError (deduped), apply the fresh token, and report whether
+     *  the caller should retry. Never throws — a failed refresh means "surface
+     *  the original 401". */
+    async tryRefreshToken() {
+        const refresh = this.opts.onAuthError;
+        if (!refresh)
+            return false;
+        this.refreshing ??= Promise.resolve()
+            .then(refresh)
+            .catch(() => null)
+            .finally(() => {
+            this.refreshing = null;
+        });
+        const token = await this.refreshing;
+        if (!token)
+            return false;
+        this.opts.token = token;
+        return true;
+    }
+    /** doFetch with one transparent retry after a 401-triggered token refresh.
+     *  Everything except the stream loop (which has its own auth handling) goes
+     *  through here. */
+    async fetchAuthed(url, init) {
+        const res = await this.doFetch(url, init);
+        if (res.status !== 401 || !(await this.tryRefreshToken()))
+            return res;
+        init.headers.Authorization = `Bearer ${this.opts.token}`;
+        return this.doFetch(url, init);
+    }
     url(path) {
         return this.opts.baseUrl.replace(/\/+$/, '') + path;
     }
@@ -75,7 +116,7 @@ export class CompanionClient {
         return this._session;
     }
     async postJson(path, body) {
-        const res = await this.doFetch(this.url(path), {
+        const res = await this.fetchAuthed(this.url(path), {
             method: 'POST',
             headers: this.jsonHeaders(),
             body: JSON.stringify(body)
@@ -151,7 +192,7 @@ export class CompanionClient {
      *  dedups by id). Falls back to buffered semantics if the server ever
      *  responds with plain JSON (e.g. an old deployment). */
     async sendTextStreaming(sessionId, body) {
-        const res = await this.doFetch(this.url(`/api/companion/session/${sessionId}/input`), {
+        const res = await this.fetchAuthed(this.url(`/api/companion/session/${sessionId}/input`), {
             method: 'POST',
             headers: this.jsonHeaders(),
             body: JSON.stringify({ ...body, stream: true })
@@ -347,7 +388,7 @@ export class CompanionClient {
             .slice(-60)
             .map((t) => ({ role: t.role, text: t.text.slice(0, 500) }));
         try {
-            const res = await this.doFetch(this.url(`/api/companion/session/${id}/end`), {
+            const res = await this.fetchAuthed(this.url(`/api/companion/session/${id}/end`), {
                 method: 'POST',
                 headers: this.jsonHeaders(),
                 body: JSON.stringify({ transcript }),
@@ -481,10 +522,20 @@ export class CompanionClient {
             }, env);
         });
     }
-    /** Recall the memory this token is authorized to see (ranked). */
+    /** Recall the memory this token is authorized to see. Without `query` the
+     *  facts come back ranked by importance/recency; with `query` the server
+     *  runs semantic search over them (embedding-based, falls back to ranked
+     *  when embeddings are unavailable) — e.g.
+     *  `recall({ query: 'food preferences', limit: 10 })`. */
     async recall(opts) {
-        const qs = opts?.limit ? `?limit=${encodeURIComponent(opts.limit)}` : '';
-        const res = await this.doFetch(this.url(`/api/companion/memory${qs}`), {
+        const params = new URLSearchParams();
+        if (opts?.limit)
+            params.set('limit', String(opts.limit));
+        if (opts?.query?.trim())
+            params.set('q', opts.query.trim());
+        const query = params.toString();
+        const qs = query ? `?${query}` : '';
+        const res = await this.fetchAuthed(this.url(`/api/companion/memory${qs}`), {
             headers: { Authorization: `Bearer ${this.opts.token}` }
         });
         const json = (await res.json().catch(() => null));
@@ -501,7 +552,7 @@ export class CompanionClient {
     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 res = await this.fetchAuthed(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);
@@ -514,7 +565,7 @@ export class CompanionClient {
      *  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`), {
+        const res = await this.fetchAuthed(this.url(`/api/companion/session/${encodeURIComponent(id)}/modalities`), {
             method: 'POST',
             headers: {
                 Authorization: `Bearer ${this.opts.token}`,
@@ -533,7 +584,7 @@ export class CompanionClient {
      *  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}` } });
+        const res = await this.fetchAuthed(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);
@@ -578,7 +629,7 @@ export class CompanionClient {
      *  and the /models asset is CORS-enabled, so a cross-origin renderer can fetch
      *  the VRM directly. Reflects the user's live choice (built-in or custom). */
     async getAvatar() {
-        const res = await this.doFetch(this.url('/api/companion/avatar'), {
+        const res = await this.fetchAuthed(this.url('/api/companion/avatar'), {
             headers: { Authorization: `Bearer ${this.opts.token}` }
         });
         const json = (await res.json().catch(() => null));
@@ -599,7 +650,7 @@ export class CompanionClient {
      *  which subsumes it). Same data the companion gives when asked "what's my
      *  balance?". */
     async getWallet() {
-        const res = await this.doFetch(this.url('/api/companion/wallet'), {
+        const res = await this.fetchAuthed(this.url('/api/companion/wallet'), {
             headers: { Authorization: `Bearer ${this.opts.token}` }
         });
         const json = (await res.json().catch(() => null));
@@ -715,7 +766,7 @@ export class CompanionClient {
      *  session tokens only, like `confirmAction`. */
     async pendingConfirms() {
         const sessionId = this.requireSession();
-        const res = await this.doFetch(this.url(`/api/companion/session/${encodeURIComponent(sessionId)}/confirm`), { headers: { Authorization: `Bearer ${this.opts.token}` } });
+        const res = await this.fetchAuthed(this.url(`/api/companion/session/${encodeURIComponent(sessionId)}/confirm`), { 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 || `pending confirms failed (${res.status})`, res.status);
@@ -924,11 +975,21 @@ export class CompanionClient {
     async loop() {
         const id = this.requireSession();
         let backoff = 500;
+        let authRefreshes = 0; // consecutive 401→refresh cycles without a healthy connect
         while (this.streaming) {
             this.abort = new AbortController();
             try {
                 const res = await this.doFetch(this.url(`/api/companion/session/${id}/stream?cursor=${this.cursor}`), { headers: { Authorization: `Bearer ${this.opts.token}` }, signal: this.abort.signal });
                 if (res.status === 401 || res.status === 403) {
+                    // 401 = the token itself is bad — usually an EXPIRED session token
+                    // (they live ~1h). With an onAuthError hook this is recoverable:
+                    // refresh and reconnect instead of going permanently silent. The
+                    // counter stops a hot loop when the hook keeps returning a token
+                    // the server keeps rejecting.
+                    if (res.status === 401 && authRefreshes < 3 && (await this.tryRefreshToken())) {
+                        authRefreshes += 1;
+                        continue;
+                    }
                     // Permanent: the token can't subscribe (most often it lacks the
                     // `events.subscribe` scope; also revoked / wrong user). Retrying is
                     // futile and would silently swallow every reply — surface it as a
@@ -955,6 +1016,7 @@ export class CompanionClient {
                     continue;
                 }
                 backoff = 500; // healthy connection resets backoff
+                authRefreshes = 0;
                 await this.consume(res.body);
             }
             catch {

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_
 export type { CompanionCall, CompanionCallOptions, VoiceToolBridge } from './call.js';
 export { COMPANION_SCOPES, COMPANION_MODALITIES, SENSITIVE_SCOPES, REPRESENT_SCOPES, DEFAULT_SCOPES, DEFAULT_MODALITIES, isSensitiveScope, isRepresentScope, hasScope } from './scopes.js';
 export type { CompanionScope, CompanionModality } from './scopes.js';
-export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, PendingConfirm, AudioClipPayload, ExpressionPayload, TypingPayload, VoiceInjectPayload, UsagePayload } from './protocol.js';
+export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, ConfirmRequestPayload, PendingConfirm, ToolCallPayload, AudioClipPayload, ExpressionPayload, TypingPayload, VoiceInjectPayload, UsagePayload } from './protocol.js';
+export { PROTOCOL_VERSION, INBOUND_TYPES, OUTBOUND_TYPES } from './protocol.js';
 /** Create a companion client. */
 export declare function createCompanion(opts: CompanionClientOptions): CompanionClient;

package/dist/index.js

@@ -1,5 +1,6 @@
 // Companion SDK — public entry. Embed the Pouchy companion in a third-party
-// surface (web / app / game / hardware) over the REST/SSE plane.
+// surface (web / app / game / hardware) over the REST/SSE plane (with an
+// optional WebSocket transport that degrades to SSE).
 //
 //   import { createCompanion } from '$lib/companion-sdk';
 //   const c = createCompanion({ baseUrl: 'https://pouchy.ai', token: PAT });
@@ -12,6 +13,9 @@ import { CompanionClient } from './client.js';
 export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js';
 export { openCompanionCall, HOST_CONTROL_TOOLS, HOST_CONTROL_TOOL_NAMES, AVATAR_VISUAL_TOOLS, AVATAR_VISUAL_TOOL_NAMES } from './call.js';
 export { COMPANION_SCOPES, COMPANION_MODALITIES, SENSITIVE_SCOPES, REPRESENT_SCOPES, DEFAULT_SCOPES, DEFAULT_MODALITIES, isSensitiveScope, isRepresentScope, hasScope } from './scopes.js';
+// Runtime protocol constants — so a host can assert PROTOCOL_VERSION or
+// enumerate/validate the event vocabulary without hard-coding the strings.
+export { PROTOCOL_VERSION, INBOUND_TYPES, OUTBOUND_TYPES } from './protocol.js';
 /** Create a companion client. */
 export function createCompanion(opts) {
     return new CompanionClient(opts);

package/dist/protocol.d.ts

@@ -76,6 +76,18 @@ export interface PendingConfirm {
     /** Epoch ms when the companion asked. */
     createdAt: number;
 }
+/** Payload of a `companion.tool_call` event — the companion is asking the host
+ *  to run one of the app-declared tools it was given at `hello`. `args` is the
+ *  raw JSON string the model produced (parse it yourself); reply by posting the
+ *  result back with `client.sendToolResult(id, …)`. */
+export interface ToolCallPayload {
+    /** Correlation id — echo it back on the tool result. */
+    id: string;
+    /** The declared tool name the model chose. */
+    name: string;
+    /** The model's arguments as a raw JSON string. */
+    args: string;
+}
 /** Payload of a `companion.ui_update` event — a live change to an
  *  already-rendered Instant UI panel: write each `{ key, value }` into the
  *  panel's state bag (re-evaluating templates / progress / `when`), without

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.20.0",
+  "version": "0.22.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",