@pouchy_ai/companion-sdk 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -12,6 +12,35 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [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()`. |

package/dist/client.d.ts

@@ -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;
@@ -324,9 +345,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

@@ -63,6 +63,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 +114,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 +190,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 +386,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 +520,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 +550,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 +563,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 +582,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 +627,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 +648,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 +764,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 +973,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 +1014,7 @@ export class CompanionClient {
                     continue;
                 }
                 backoff = 500; // healthy connection resets backoff
+                authRefreshes = 0;
                 await this.consume(res.body);
             }
             catch {

package/package.json

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