@pouchy_ai/companion-sdk 0.19.1 → 0.21.0

package/CHANGELOG.md

@@ -12,6 +12,46 @@ 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
+
+- `client.getWallet(): Promise<CompanionWallet>` and the `GET /api/companion/wallet`
+  endpoint — read the companion instance's OWN wallet (nonzero stablecoin
+  balances + total USD). Read-only and receive-only; requires the `wallet.read`
+  scope (or `wallet.spend`, which subsumes it). Shares its read path with the
+  conversational `get_wallet_balance` tool so the endpoint and the in-chat answer
+  can never diverge. New exported types `CompanionWallet` / `WalletBalance`.
+
 ## [0.19.1] - 2026-07-10
 
 ### Documentation

package/README.md

@@ -72,11 +72,11 @@ Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers:
 | `onInterfaceUpdate(fn)` | `companion.ui_update` | live `{key,value}` update to an already-rendered panel (no rebuild) |
 | `onSocialMessage(fn)` | `companion.social_message` | inbound A2A friend message, delivered cross-app. Needs `social.message` |
 | `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 |
+| `onAudio(fn)` | `companion.audio` | TTS clip (non-call modality). _(reserved — not emitted yet)_ |
+| `onExpression(fn)` | `companion.expression` | avatar viseme / expression / gesture. _(reserved — not emitted yet)_ |
 | `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 |
+| `onUsage(fn)` | `control.usage` | per-token metering echo. _(reserved — not emitted yet)_ |
 | `onError(fn)` | `control.error` | agent / stream errors |
 
 ### Instant UI
@@ -96,16 +96,18 @@ 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()`. |
 | `startCall(opts)` / `connectCall(opts)` | Voice plane: raw credentials / fully-wired call handle (`call.close()` ends + folds the transcript into memory). |
 | `getAvatar()` / `brandIconUrl(size?)` | The user's avatar (VRM/portrait) and the Pouchy brand icon for your UI. |
+| `getWallet()` | Read the instance's own wallet — `{ balances: [{ currency, amount }], totalUsd, currency }`. Read-only + receive-only; needs the `wallet.read` scope. |
 
 Tool calling beyond your own declared tools: `HOST_CONTROL_TOOLS` (universal
 verbs — `invoke_action`, `set_feature`, `set_value`, `navigate`, `highlight`)

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;
@@ -123,6 +131,23 @@ export interface CompanionAvatar {
      *  built-ins today (reserved for custom previews / server-rendered thumbs). */
     imageUrl: string | null;
 }
+/** One nonzero stablecoin balance line. */
+export interface WalletBalance {
+    /** Stablecoin code (USDT / USDC / DAI / USD1). */
+    currency: string;
+    /** Decimal amount as a string (not atomic units), e.g. "5.83". */
+    amount: string;
+}
+/** Read-only snapshot of the companion instance's OWN wallet (receive-only —
+ *  there is no way to move funds via the SDK). Requires the `wallet.read` scope. */
+export interface CompanionWallet {
+    /** Nonzero per-currency balances (empty when the wallet is empty). */
+    balances: WalletBalance[];
+    /** Total across the balances; the allowed stablecoins are USD-pegged 1:1. */
+    totalUsd: number;
+    /** Denomination of `totalUsd` (always "USD" today). */
+    currency: string;
+}
 /** Available sizes for the Pouchy brand icon (px). */
 export type BrandIconSize = 256 | 512 | 1024;
 /** Canonical URL of the official Pouchy brand icon at `size` px, derived from a
@@ -173,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;
@@ -307,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`
@@ -392,6 +435,12 @@ export declare 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). */
     getAvatar(): Promise<CompanionAvatar>;
+    /** Read the companion instance's OWN wallet — nonzero stablecoin balances +
+     *  total USD. Read-only and receive-only (spends go through the confirm-gated
+     *  pay tools, never here). Requires the `wallet.read` scope (or `wallet.spend`,
+     *  which subsumes it). Same data the companion gives when asked "what's my
+     *  balance?". */
+    getWallet(): Promise<CompanionWallet>;
     /** Canonical URL of the official Pouchy brand icon (square PNG, transparent
      *  background) at the given size. Static + public — needs no token — so it's
      *  safe to drop straight into an `<img src>` for "powered by Pouchy" badges,

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));
@@ -593,6 +642,25 @@ export class CompanionClient {
             imageUrl: json.imageUrl ?? null
         };
     }
+    /** Read the companion instance's OWN wallet — nonzero stablecoin balances +
+     *  total USD. Read-only and receive-only (spends go through the confirm-gated
+     *  pay tools, never here). Requires the `wallet.read` scope (or `wallet.spend`,
+     *  which subsumes it). Same data the companion gives when asked "what's my
+     *  balance?". */
+    async getWallet() {
+        const res = await this.fetchAuthed(this.url('/api/companion/wallet'), {
+            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 || `wallet fetch failed (${res.status})`, res.status);
+        }
+        return {
+            balances: json.balances ?? [],
+            totalUsd: json.totalUsd ?? 0,
+            currency: json.currency ?? 'USD'
+        };
+    }
     /** Canonical URL of the official Pouchy brand icon (square PNG, transparent
      *  background) at the given size. Static + public — needs no token — so it's
      *  safe to drop straight into an `<img src>` for "powered by Pouchy" badges,
@@ -696,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);
@@ -905,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
@@ -936,6 +1014,7 @@ export class CompanionClient {
                     continue;
                 }
                 backoff = 500; // healthy connection resets backoff
+                authRefreshes = 0;
                 await this.consume(res.body);
             }
             catch {

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { CompanionClient, type CompanionClientOptions } from './client.js';
 export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js';
-export type { CompanionClientOptions, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, WorldStateInput, CompanionAvatar, BrandIconSize, EndSessionResult } from './client.js';
+export type { CompanionClientOptions, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, WorldStateInput, CompanionAvatar, CompanionWallet, WalletBalance, BrandIconSize, EndSessionResult } 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 { COMPANION_SCOPES, COMPANION_MODALITIES, SENSITIVE_SCOPES, REPRESENT_SCOPES, DEFAULT_SCOPES, DEFAULT_MODALITIES, isSensitiveScope, isRepresentScope, hasScope } from './scopes.js';

package/dist/protocol.d.ts

@@ -2,7 +2,13 @@ export declare const PROTOCOL_VERSION: 1;
 /** App → Pouchy (control/data plane). */
 export declare const INBOUND_TYPES: readonly ["hello", "input.text", "context.event", "context.snapshot", "tool.result", "control.start_call", "control.end_call", "control.set_modalities", "control.ping"];
 export type InboundType = (typeof INBOUND_TYPES)[number];
-/** Pouchy → app (control/data plane). */
+/** Pouchy → app (control/data plane).
+ *  NOTE: three types are RESERVED — part of the vocabulary + typed handlers, but
+ *  the server does NOT emit them yet, so `onAudio` / `onExpression` / `onUsage`
+ *  are safe to register but won't fire until a producer ships. Don't build a UX
+ *  that depends on them today. (companion.audio → non-call reply TTS;
+ *  companion.expression → avatar viseme/expression cues; control.usage →
+ *  per-turn usage-metering echo.) */
 export declare const OUTBOUND_TYPES: readonly ["hello.ack", "companion.message", "companion.audio", "companion.tool_call", "companion.ui_action", "companion.ui_update", "companion.expression", "companion.voice_inject", "companion.confirm_request", "companion.social_message", "companion.typing", "control.call_ready", "control.error", "control.usage"];
 export type OutboundType = (typeof OUTBOUND_TYPES)[number];
 export type MessageType = InboundType | OutboundType;

package/dist/protocol.js

@@ -17,20 +17,26 @@ export const INBOUND_TYPES = [
     'control.set_modalities',
     'control.ping'
 ];
-/** Pouchy → app (control/data plane). */
+/** Pouchy → app (control/data plane).
+ *  NOTE: three types are RESERVED — part of the vocabulary + typed handlers, but
+ *  the server does NOT emit them yet, so `onAudio` / `onExpression` / `onUsage`
+ *  are safe to register but won't fire until a producer ships. Don't build a UX
+ *  that depends on them today. (companion.audio → non-call reply TTS;
+ *  companion.expression → avatar viseme/expression cues; control.usage →
+ *  per-turn usage-metering echo.) */
 export const OUTBOUND_TYPES = [
     'hello.ack',
     'companion.message',
-    'companion.audio',
+    'companion.audio', // reserved — not emitted yet
     'companion.tool_call',
     'companion.ui_action',
     'companion.ui_update',
-    'companion.expression',
+    'companion.expression', // reserved — not emitted yet
     'companion.voice_inject',
     'companion.confirm_request',
     'companion.social_message',
     'companion.typing',
     'control.call_ready',
     'control.error',
-    'control.usage'
+    'control.usage' // reserved — not emitted yet
 ];

package/dist/scopes.js

@@ -21,7 +21,7 @@ export const COMPANION_SCOPES = [
     'memory.read:core', // read the shared global brain (SENSITIVE)
     'memory.write:core', // write into the shared global brain (SENSITIVE)
     'skills.execute', // run the user's installed skills (SENSITIVE)
-    'wallet.read', // READ-ONLY wallet: balance + own deposit address (receive-only; not sensitive)
+    'wallet.read', // READ-ONLY wallet: balance + own deposit address (receive-only; not sensitive). Surfaced via the companion's wallet tools (ask it) — no standalone REST endpoint.
     'wallet.spend', // spend from the Care Wallet (SENSITIVE)
     'social.message', // message friends via A2A (SENSITIVE)
     // ── Representative ("on-behalf-of") plane ─────────────────────────────

package/package.json

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