@pouchy_ai/companion-sdk 0.18.1 → 0.19.1

package/CHANGELOG.md

@@ -12,6 +12,31 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.19.1] - 2026-07-10
+
+### Documentation
+
+- README gains a client-method reference table (memory ingest, history,
+  setModalities, ping, pendingConfirms/confirmAction incl. the
+  exec_failed/retryable retry contract, endSession skipped reasons, close(),
+  startCall/connectCall, getAvatar/brandIconUrl) plus a note on
+  HOST_CONTROL_TOOLS and AVATAR_VISUAL_TOOLS (declare-or-silent-no-op).
+  No code change.
+
+## [0.19.0] - 2026-07-10
+
+### Added
+
+- **Typed scope vocabulary exported from the package.** `COMPANION_SCOPES` /
+  `CompanionScope`, `COMPANION_MODALITIES` / `CompanionModality`,
+  `SENSITIVE_SCOPES`, `REPRESENT_SCOPES`, `DEFAULT_SCOPES`,
+  `DEFAULT_MODALITIES`, and the helpers `isSensitiveScope()`,
+  `isRepresentScope()`, `hasScope(granted, required)`. Configure keys, gate
+  features on `hello.ack.grantedScopes`, and explain 403s with compile-checked
+  scope strings instead of prose-copied literals. Mirrors the server vocabulary
+  and is guarded by the same drift test as the wire protocol. Additive — no
+  wire-protocol change.
+
 ## [0.18.1] - 2026-07-08
 
 ### Changed

package/README.md

@@ -92,6 +92,52 @@ Reference renderers ship in [`examples/`](../../examples): `web-instant-ui` (van
 `native-instant-ui` (SwiftUI + Jetpack Compose), and `cli-skills` (terminal +
 local/device skills).
 
+## Client methods (beyond the quickstart)
+
+| 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. |
+| `setModalities([...])` | Switch active I/O mid-session (within the token's grant). |
+| `ping()` | Keepalive for long-idle embeds. |
+| `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. |
+
+Tool calling beyond your own declared tools: `HOST_CONTROL_TOOLS` (universal
+verbs — `invoke_action`, `set_feature`, `set_value`, `navigate`, `highlight`)
+are offered automatically once you declare `tools`/`handles`, and
+`AVATAR_VISUAL_TOOLS` (`play_gesture` / `play_expression`) let avatar-rendering
+embeds receive expression cues — declare them or they no-op silently. Full
+contract: `docs/companion-host-control.md`.
+
+## Scopes (typed)
+
+The full capability-scope vocabulary ships as typed constants — no more
+copying scope strings from prose:
+
+```ts
+import {
+  COMPANION_SCOPES, SENSITIVE_SCOPES, DEFAULT_SCOPES,
+  hasScope, isSensitiveScope, type CompanionScope
+} from '@pouchy_ai/companion-sdk';
+
+const ack = await c.connect();
+if (!hasScope(ack.grantedScopes, 'skills.execute')) {
+  // hide the "run a skill" affordance instead of eating a 403
+}
+```
+
+`COMPANION_SCOPES` lists every scope a key can carry; `SENSITIVE_SCOPES` are
+the ones that are never on by default (money / skills / social / core memory /
+the representative plane); `DEFAULT_SCOPES` is what a fresh key gets. Also
+exported: `COMPANION_MODALITIES`, `REPRESENT_SCOPES`, `DEFAULT_MODALITIES`,
+`isRepresentScope()`. The list mirrors the server vocabulary and is guarded by
+the SDK's drift test.
+
 ## Representative mode (代聊)
 
 Pass a `visitor` and the session flips from **owner-facing** to **representative**:

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client.js
 export type { CompanionClientOptions, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, WorldStateInput, CompanionAvatar, 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';
+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';
 /** Create a companion client. */
 export declare function createCompanion(opts: CompanionClientOptions): CompanionClient;

package/dist/index.js

@@ -11,6 +11,7 @@
 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';
 /** Create a companion client. */
 export function createCompanion(opts) {
     return new CompanionClient(opts);

package/dist/scopes.d.ts

@@ -0,0 +1,24 @@
+/** Every capability scope a Personal Access Token / OAuth grant can carry. */
+export declare const COMPANION_SCOPES: readonly ["chat", "voice", "call", "files", "events.subscribe", "worldstate.write", "ui.render", "memory.read:app", "memory.write:app", "memory.read:core", "memory.write:core", "skills.execute", "wallet.read", "wallet.spend", "social.message", "represent", "expose:knowledge", "expose:facts", "represent:pair", "represent:remember"];
+export type CompanionScope = (typeof COMPANION_SCOPES)[number];
+/** I/O modalities a key can carry alongside its scopes. */
+export declare const COMPANION_MODALITIES: readonly ["text", "voice", "call", "files"];
+export type CompanionModality = (typeof COMPANION_MODALITIES)[number];
+/** Sensitive scopes — never granted by default; the user opts in at key
+ *  creation, and execution still passes a confirm on a Pouchy-controlled
+ *  surface (see `companion.confirm_request`). */
+export declare const SENSITIVE_SCOPES: ReadonlySet<CompanionScope>;
+/** The representative ("on-behalf-of") plane — a distinct axis from the
+ *  execution scopes: one lets the companion ACT for the owner, the other lets
+ *  it REPRESENT the owner to an outside visitor. `represent` is the umbrella;
+ *  the `expose:*` / `represent:*` scopes only mean anything alongside it. */
+export declare const REPRESENT_SCOPES: ReadonlySet<CompanionScope>;
+/** What a freshly-generated key carries unless the user opts into more: a
+ *  chat/play companion confined to its own app memory namespace. */
+export declare const DEFAULT_SCOPES: readonly CompanionScope[];
+export declare const DEFAULT_MODALITIES: readonly CompanionModality[];
+export declare function isSensitiveScope(s: CompanionScope): boolean;
+export declare function isRepresentScope(s: CompanionScope): boolean;
+/** Does a granted scope set (e.g. `hello.ack.grantedScopes`) satisfy a
+ *  required scope? Exact-match for v1 (no hierarchical wildcards). */
+export declare function hasScope(granted: readonly string[], required: CompanionScope): boolean;

package/dist/scopes.js

@@ -0,0 +1,85 @@
+// Companion capability scopes — the SDK's self-contained copy (no $lib
+// imports; same doctrine as protocol.ts). The server's source of truth is
+// src/lib/types/companion-scopes.ts; protocol.drift.test.ts fails if the two
+// diverge — extend both together.
+//
+// Why the SDK exports these: a host app configuring a key, gating a feature
+// on `hello.ack.grantedScopes`, or explaining a `403 missing scope` needs the
+// vocabulary as types and constants, not prose. Typos in scope strings become
+// compile errors instead of runtime 403s.
+/** Every capability scope a Personal Access Token / OAuth grant can carry. */
+export const COMPANION_SCOPES = [
+    'chat', // text turns
+    'voice', // TTS / STT
+    'call', // realtime WebRTC voice session
+    'files', // multimodal file in/out (vision / image)
+    'events.subscribe', // receive the outbound companion event stream
+    'worldstate.write', // push inbound live world-state / context events
+    'ui.render', // let the companion render Instant UI surfaces on the host (display + forms; not sensitive)
+    'memory.read:app', // read this app's own memory namespace
+    'memory.write:app', // write into this app's own memory namespace
+    '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.spend', // spend from the Care Wallet (SENSITIVE)
+    'social.message', // message friends via A2A (SENSITIVE)
+    // ── Representative ("on-behalf-of") plane ─────────────────────────────
+    'represent', // open visitor-facing representative sessions (SENSITIVE)
+    'expose:knowledge', // let the representative draw on the owner's knowledge base (SENSITIVE)
+    'expose:facts', // widen exposed facts past the identity/preference floor (SENSITIVE)
+    'represent:pair', // let a representative pair a visitor (also a Pouchy user) as a friend (SENSITIVE)
+    'represent:remember' // let a representative keep durable per-visitor notes across visits (SENSITIVE)
+];
+/** I/O modalities a key can carry alongside its scopes. */
+export const COMPANION_MODALITIES = ['text', 'voice', 'call', 'files'];
+/** Sensitive scopes — never granted by default; the user opts in at key
+ *  creation, and execution still passes a confirm on a Pouchy-controlled
+ *  surface (see `companion.confirm_request`). */
+export const SENSITIVE_SCOPES = new Set([
+    'memory.read:core',
+    'memory.write:core',
+    'skills.execute',
+    'wallet.spend',
+    'social.message',
+    'represent',
+    'expose:knowledge',
+    'expose:facts',
+    'represent:pair',
+    'represent:remember'
+]);
+/** The representative ("on-behalf-of") plane — a distinct axis from the
+ *  execution scopes: one lets the companion ACT for the owner, the other lets
+ *  it REPRESENT the owner to an outside visitor. `represent` is the umbrella;
+ *  the `expose:*` / `represent:*` scopes only mean anything alongside it. */
+export const REPRESENT_SCOPES = new Set([
+    'represent',
+    'expose:knowledge',
+    'expose:facts',
+    'represent:pair',
+    'represent:remember'
+]);
+/** What a freshly-generated key carries unless the user opts into more: a
+ *  chat/play companion confined to its own app memory namespace. */
+export const DEFAULT_SCOPES = [
+    'chat',
+    'voice',
+    'call',
+    'files',
+    'events.subscribe',
+    'worldstate.write',
+    'memory.read:app',
+    'memory.write:app'
+];
+export const DEFAULT_MODALITIES = ['text', 'voice'];
+export function isSensitiveScope(s) {
+    return SENSITIVE_SCOPES.has(s);
+}
+export function isRepresentScope(s) {
+    return REPRESENT_SCOPES.has(s);
+}
+/** Does a granted scope set (e.g. `hello.ack.grantedScopes`) satisfy a
+ *  required scope? Exact-match for v1 (no hierarchical wildcards). */
+export function hasScope(granted, required) {
+    return granted.includes(required);
+}

package/package.json

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