@pouchy_ai/companion-sdk 0.29.1 → 0.32.0

package/src/errors.ts

@@ -0,0 +1,77 @@
+// CompanionError — the one error type every SDK helper rejects with (README
+// contract: consumers `switch` on `.code` instead of string-matching prose).
+// Lives in its own module so call.ts can use it without a runtime cycle
+// through client.ts (client.ts re-exports it, keeping the public import path
+// `@pouchy_ai/companion-sdk` → `CompanionError` unchanged).
+
+// Type-only import: protocol.ts imports nothing at runtime, so this cannot
+// re-create the client.ts cycle this module exists to avoid.
+import type { CompanionErrorCode, ControlErrorCode } from './protocol';
+
+/** Codes the SDK itself synthesizes (status 0 — never sent by the server).
+ *  Runtime array so the drift test can assert every `new CompanionError(...)`
+ *  call site uses a declared code; APPEND-ONLY like the server vocabulary. */
+export const SDK_SYNTHESIZED_ERROR_CODES = [
+	'reply_timeout', // awaitReply/replyTimeoutMs elapsed before the reply
+	'needs_event_stream', // turn paused on tools but start() was never called
+	'not_connected', // a call/stream helper was used before connect
+	'missing_option', // a required option was omitted (e.g. sessionId)
+	'not_representative', // pairVisitor on a non-representative token
+	'call_unsupported', // startCall on a server/provider without voice
+	'call_connect_failed', // WebRTC/provider handshake failed
+	'call_dependency_missing', // optional voice dependency not installed
+	'aborted' // a caller-supplied AbortSignal cancelled the request (0.29.0)
+] as const;
+export type SdkSynthesizedErrorCode = (typeof SDK_SYNTHESIZED_ERROR_CODES)[number];
+
+/** `control.error` STREAM codes the SDK itself synthesizes (never sent by the
+ *  server) — the stream-plane sibling of SDK_SYNTHESIZED_ERROR_CODES above.
+ *  Runtime array so the drift test can assert every locally-emitted
+ *  `control.error` envelope uses a declared code; APPEND-ONLY. */
+export const SDK_STREAM_ERROR_CODES = [
+	'stream_unauthorized' // the event stream got a permanent 401/403 and reconnect gave up
+] as const;
+export type SdkStreamErrorCode = (typeof SDK_STREAM_ERROR_CODES)[number];
+
+/** `control.error` `code` values a consumer can switch on (0.30.0): the server
+ *  vocabulary (CONTROL_ERROR_CODES, drift-tested against the server list) plus
+ *  the SDK-synthesized stream codes — DERIVED from the runtime lists rather
+ *  than hand-retyped, same doctrine as CompanionErrorCodeValue below. The
+ *  `(string & {})` arm keeps the type open for codes newer than this SDK build
+ *  while preserving autocomplete. */
+export type ControlErrorCodeValue =
+	| ControlErrorCode
+	| SdkStreamErrorCode
+	// eslint-disable-next-line @typescript-eslint/ban-types
+	| (string & {});
+
+/** Thrown by every helper on an HTTP or client-side failure. `status` is the
+ *  HTTP status (0 for client-synthesized failures — timeouts, unsupported
+ *  environments, missing optional deps); `code` is machine-switchable when
+ *  the server (or the SDK itself) names a cause. On a `rate_limited` (429)
+ *  failure, `retryAfter` carries the server's Retry-After in SECONDS so a
+ *  consumer can back off precisely instead of guessing. */
+/** `CompanionError.code` values: the server vocabulary (COMPANION_ERROR_CODES,
+ *  drift-tested against api-error.ts) plus the SDK-synthesized ones — DERIVED
+ *  from those runtime lists rather than hand-retyped, so a new code can never
+ *  silently miss this union again (the old copy had drifted 5 codes behind).
+ *  The `(string & {})` arm keeps the type open for codes newer than this SDK
+ *  build while preserving autocomplete. */
+export type CompanionErrorCodeValue =
+	| CompanionErrorCode
+	| SdkSynthesizedErrorCode
+	// eslint-disable-next-line @typescript-eslint/ban-types
+	| (string & {});
+
+export class CompanionError extends Error {
+	status: number;
+	code?: CompanionErrorCodeValue;
+	retryAfter?: number;
+	constructor(message: string, status: number, code?: string, retryAfter?: number) {
+		super(message);
+		this.name = 'CompanionError';
+		this.status = status;
+		if (code) this.code = code;
+		if (typeof retryAfter === 'number' && Number.isFinite(retryAfter)) this.retryAfter = retryAfter;
+	}
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+// Companion SDK — public entry. Embed the Pouchy companion in a third-party
+// 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 });
+//   await c.connect();
+//   c.onMessage((text) => console.log(text));
+//   c.start();
+//   c.sendWorldState({ type: 'game.scene', data: 'tavern', retained: true });
+//   await c.sendText('what should I do?');
+
+import { CompanionClient, type CompanionClientOptions } from './client';
+
+export { CompanionClient, CompanionError, pouchyBrandIconUrl } from './client';
+export type { CompanionDebugEvent } from './client';
+export type { CompanionErrorCodeValue, ControlErrorCodeValue } from './errors';
+export type {
+	CompanionClientOptions,
+	CompanionStreamState,
+	HelloAck,
+	RecalledMemory,
+	CompanionTurn,
+	CallCredentials,
+	CompanionToolDecl,
+	ToolCallEvent,
+	WorldStateInput,
+	CompanionAvatar,
+	CompanionWallet,
+	WalletBalance,
+	BrandIconSize,
+	EndSessionResult,
+	SendTextReply
+} from './client';
+export {
+	openCompanionCall,
+	HOST_CONTROL_TOOLS,
+	HOST_CONTROL_TOOL_NAMES,
+	AVATAR_VISUAL_TOOLS,
+	AVATAR_VISUAL_TOOL_NAMES
+} from './call';
+export type { CompanionCall, CompanionCallOptions, VoiceToolBridge } from './call';
+export {
+	COMPANION_SCOPES,
+	COMPANION_MODALITIES,
+	SENSITIVE_SCOPES,
+	REPRESENT_SCOPES,
+	DEFAULT_SCOPES,
+	DEFAULT_MODALITIES,
+	isSensitiveScope,
+	isRepresentScope,
+	hasScope
+} from './scopes';
+export type { CompanionScope, CompanionModality } from './scopes';
+export type {
+	CompanionEnvelope,
+	OutboundType,
+	InboundType,
+	WorldStateEvent,
+	RenderInterfacePayload,
+	InterfaceUpdatePayload,
+	SocialMessagePayload,
+	ConfirmRequestPayload,
+	PendingConfirm,
+	ToolCallPayload,
+	AudioClipPayload,
+	ExpressionPayload,
+	TypingPayload,
+	VoiceInjectPayload,
+	UsagePayload,
+	MessagePayload,
+	ControlErrorPayload,
+	HelloAckPayload,
+	CallReadyPayload,
+	OutboundPayloadMap
+} from './protocol';
+// Runtime protocol constants — so a host can assert PROTOCOL_VERSION or
+// enumerate/validate the event vocabulary without hard-coding the strings.
+// CONTROL_ERROR_CODES (0.30.0) is the stream-plane control.error vocabulary —
+// a separate, smaller list than the HTTP COMPANION_ERROR_CODES.
+export {
+	PROTOCOL_VERSION,
+	INBOUND_TYPES,
+	OUTBOUND_TYPES,
+	COMPANION_ERROR_CODES,
+	CONTROL_ERROR_CODES
+} from './protocol';
+export type { CompanionErrorCode, ControlErrorCode } from './protocol';
+
+// The framework-agnostic view controller behind the /react, /svelte and /vue
+// subpath adapters — exported from the root too, so a host on any OTHER
+// framework (or none) can reuse the same tested snapshot bookkeeping.
+export { createCompanionView } from './adapter-core';
+export type {
+	CompanionView,
+	CompanionViewOptions,
+	CompanionViewSnapshot,
+	CompanionTranscriptEntry
+} from './adapter-core';
+
+/** Create a companion client. */
+export function createCompanion(opts: CompanionClientOptions): CompanionClient {
+	return new CompanionClient(opts);
+}

package/src/protocol.ts

@@ -0,0 +1,316 @@
+// The wire contract, as the SDK sees it — a self-contained copy so the package
+// has ZERO repo-internal ($lib) imports and publishes / builds with plain tsc.
+//
+// This mirrors the server's source of truth (src/lib/types/companion-protocol.ts);
+// a drift test (protocol.drift.test.ts) keeps PROTOCOL_VERSION + the type unions
+// in sync. Adding an outbound type is non-breaking (receivers ignore unknowns).
+
+export const PROTOCOL_VERSION = 1 as const;
+
+/** App → Pouchy (control/data plane). */
+export const INBOUND_TYPES = [
+	'hello',
+	'input.text',
+	'context.event',
+	'context.snapshot',
+	'tool.result',
+	'control.start_call',
+	'control.end_call',
+	'control.set_modalities',
+	'control.ping'
+] as const;
+export type InboundType = (typeof INBOUND_TYPES)[number];
+
+/** 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', // reserved — not emitted yet
+	'companion.tool_call',
+	'companion.ui_action',
+	'companion.ui_update',
+	'companion.expression', // reserved — not emitted yet
+	'companion.voice_inject',
+	'companion.confirm_request',
+	'companion.social_message',
+	'companion.typing',
+	'control.call_ready',
+	'control.error',
+	'control.usage' // reserved — not emitted yet
+] as const;
+export type OutboundType = (typeof OUTBOUND_TYPES)[number];
+
+export type MessageType = InboundType | OutboundType;
+
+/** `control.error` STREAM-plane code vocabulary (0.30.0) — a separate, smaller
+ *  vocabulary from COMPANION_ERROR_CODES below (those tag HTTP `{ok:false}`
+ *  response bodies; these tag `control.error` envelopes on the event stream,
+ *  surfaced by `onError`). Self-contained mirror of the server list
+ *  (drift-tested); APPEND-ONLY. The SDK itself synthesizes one more,
+ *  `stream_unauthorized` (errors.ts) — the public union `ControlErrorCodeValue`
+ *  covers both plus a forward-compat string arm. */
+export const CONTROL_ERROR_CODES = [
+	'agent_error', // a server-side turn failed after the input was accepted — no reply was produced; safe to re-send
+	'call_mint_failed' // start_call couldn't mint the voice-provider credential — retry later or fall back to text
+] as const;
+export type ControlErrorCode = (typeof CONTROL_ERROR_CODES)[number];
+
+/** HTTP error `code` vocabulary — what `CompanionError.code` can hold. A
+ *  self-contained mirror of the server's api-error.ts list (drift-tested);
+ *  APPEND-ONLY: renaming or removing a code is a breaking SDK change.
+ *  Consumers can switch on these instead of string-matching error prose. */
+export const COMPANION_ERROR_CODES = [
+	'missing_token', // 401 — no Authorization: Bearer header
+	'invalid_token', // 401 — token unknown, revoked, or expired
+	'missing_scope', // 403 — token lacks a required grant
+	'invalid_request', // 400 — malformed JSON / missing or invalid fields
+	'session_not_found', // 404 — sessionId expired or never started
+	'turn_pending', // 409 — a turn is paused awaiting tool results
+	'no_pending_tools', // 409 — tool result posted but nothing is pending
+	'unknown_call', // 404 — tool result for a callId the turn didn't issue
+	'payload_too_large', // 413 — body/image over the documented cap
+	'rate_limited', // 429 — turn burst / demo daily budget spent; Retry-After + retryAfterSec say when
+	'forbidden', // 403 — authorization denial other than a missing scope
+	'unavailable', // 503 — backing store/provider not configured or down
+	'confirm_not_found', // 404 — confirmId unknown or not on this session
+	'confirm_resolved', // 409 — confirm already approved/denied/expired (single-use)
+	'step_up_required', // 401 — approval needs a passkey assertion (fetch confirm/stepup)
+	'step_up_failed' // 401 — the passkey assertion didn't verify; retry the step-up
+] as const;
+export type CompanionErrorCode = (typeof COMPANION_ERROR_CODES)[number];
+
+/** The single envelope every control/data-plane message shares. */
+export interface CompanionEnvelope<T = unknown> {
+	v: typeof PROTOCOL_VERSION;
+	id: string;
+	session?: string;
+	ts: number;
+	type: MessageType;
+	payload: T;
+}
+
+/** Payload of a `companion.ui_action` event — an Instant UI surface for the host
+ *  to render. `interface` is the platform-neutral genui schema: a tree of UI
+ *  `nodes` (Text/Slider/Button/Chart/…), an optional `state` bag input atoms
+ *  read+write, and optional `computed` derived values. The SAME shape is drawn by
+ *  a web embed, a native iOS/Android renderer, or a CLI/TUI — only the renderer
+ *  differs per platform, never the contract. Kept structurally loose here (the
+ *  SDK package carries no $lib import); the authoritative schema lives in
+ *  src/lib/genui/schema.ts and the renderer-contract doc. When the panel sets
+ *  `reportChanges`, the user's edits stream back as a normal text turn. */
+export interface RenderInterfacePayload {
+	interface: {
+		title?: string;
+		nodes: Array<{ type: string; [k: string]: unknown }>;
+		state?: Record<string, string | number | boolean>;
+		computed?: Record<string, unknown>;
+		reportChanges?: boolean;
+	};
+}
+
+/** Payload of a `companion.confirm_request` event — the companion is asking the
+ *  user to approve a sensitive op (a payment, a skill run, a friend message).
+ *  Who may approve depends on the token: a PLATFORM SESSION TOKEN (an end-user
+ *  instance minted via /v1/sessions) resolves it directly with
+ *  `client.confirmAction` — the embedding app's end user is that account's
+ *  human. A first-party user's token can only OBSERVE: approval of a real
+ *  Pouchy user's ops is authed as that user (their app / a hosted confirm
+ *  page), so a third-party DOM can never confirm a spend, and the first-party
+ *  host can gate approval behind a biometric (Face ID / passkey) — see
+ *  docs/companion-wallet-noncustodial.md. */
+export interface ConfirmRequestPayload {
+	/** Opaque id the first-party surface passes to the confirm endpoint. */
+	confirmId: string;
+	/** The scope of the op needing approval (e.g. `wallet.spend`). */
+	scope: string;
+	/** A human, user-facing summary of what approving will do. */
+	summary: string;
+	/** Advisory: when true, the first-party approval surface should require a
+	 *  stronger user gesture — a biometric / passkey (Face ID, Touch ID) — before
+	 *  approving, not just a tap. Set for irreversible money ops (wallet.spend).
+	 *  Cryptographic enforcement is server-side follow-up; this is the host's cue. */
+	stepUp?: boolean;
+}
+
+/** One still-pending confirmation, as returned by `client.pendingConfirms()` —
+ *  display-safe (never the recorded tool call or its raw args). */
+export interface PendingConfirm {
+	confirmId: string;
+	/** The scope of the op needing approval (e.g. `skills.execute`). */
+	scope: string;
+	/** A human, user-facing summary of what approving will do. */
+	summary: string;
+	/** 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
+ *  rebuilding. `panelId` targets one of several on-screen panels when present. */
+export interface InterfaceUpdatePayload {
+	update: {
+		panelId?: string;
+		updates: Array<{ key: string; value: string | number | boolean }>;
+	};
+}
+
+/** Payload of a `companion.audio` event — a TTS clip for the assistant's reply on
+ *  a non-call modality. Either a playable `url` or an opaque `ref` the host
+ *  resolves. */
+export interface AudioClipPayload {
+	url?: string;
+	ref?: string;
+}
+
+/** Payload of a `companion.expression` event — avatar cues for an embed rendering
+ *  the companion's body (e.g. a VRM): a lip-sync `viseme`, an `expression`, or a
+ *  `gesture`. A pure-text/audio host can ignore it. */
+export interface ExpressionPayload {
+	viseme?: string;
+	expression?: string;
+	gesture?: string;
+}
+
+/** Payload of a `control.usage` event — a per-token metering echo the host can
+ *  surface in a usage/billing view. */
+export interface UsagePayload {
+	chatTurns?: number;
+	voiceSeconds?: number;
+	memoryOps?: number;
+}
+
+/** Payload of a `companion.social_message` event — an inbound A2A message from
+ *  one of the user's paired friends, delivered cross-app to any live embed whose
+ *  token holds `social.message`. Lets a native/web host surface friend messages
+ *  in real time without the first-party Pouchy app. Only plain human messages are
+ *  delivered (Pouchy-internal structured envelopes are not). */
+export interface SocialMessagePayload {
+	/** The sender's Pouchy uid. */
+	fromUid: string;
+	/** The sender's display name. */
+	fromName: string;
+	/** The message text. */
+	content: string;
+	/** 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
+ *  spans the whole turn — the tool-loop / thinking phase BEFORE the first text
+ *  delta, which `onDelta` can't observe — so a host can show a "typing…" state
+ *  uniformly across streaming and non-streaming replies. Advisory: a lost event
+ *  never affects the turn; the terminal `companion.message` is authoritative. */
+export interface TypingPayload {
+	active: boolean;
+}
+
+/** Payload of a `companion.message` event — the companion's text reply. When
+ *  the turn was started by this client with sendText, `replyTo` echoes the
+ *  request's turnId (0.28.0) so a reply can be correlated to its turn;
+ *  proactive messages (world-state reactions, confirm outcomes) carry none. */
+export interface MessagePayload {
+	text: string;
+	replyTo?: string;
+}
+
+/** A live world-state event the app streams in. `retained:true` = latest-value
+ *  state (coalesced); `retained:false` = a transient moment carrying `salience`
+ *  and optional `voiceRelevant`. */
+export interface WorldStateEvent<D = unknown> {
+	specversion: '1.0';
+	id: string;
+	source: string;
+	/** Namespaced dotted kind, e.g. `game.player.hp`, `game.event.boss_spawned`. */
+	type: string;
+	time?: string;
+	data: D;
+	retained?: boolean;
+	ttl?: number;
+	salience?: number;
+	voiceRelevant?: boolean;
+}
+
+/** Payload of a `control.error` event — a typed error on the event stream
+ *  (surfaced by `onError`). `code` is one of CONTROL_ERROR_CODES, the
+ *  SDK-synthesized `stream_unauthorized`, or a code newer than this SDK build
+ *  (the open arm keeps forward compat without losing autocomplete). */
+export interface ControlErrorPayload {
+	// eslint-disable-next-line @typescript-eslint/ban-types
+	code: ControlErrorCode | (string & {});
+	message: string;
+}
+
+/** Payload of a `hello.ack` — the handshake reply. On the REST plane this is
+ *  the `/session` response body (what `connect()` normalizes into `HelloAck`);
+ *  the event stream's greeting `open` frame carries a partial echo (just
+ *  `{ resumeCursor }`), so every field is optional at the wire level. */
+export interface HelloAckPayload {
+	session?: string;
+	grantedScopes?: string[];
+	modalities?: string[];
+	resumeCursor?: number;
+	representative?: boolean;
+	visitorPaired?: boolean;
+}
+
+/** Payload of a `control.call_ready` event — the stream echo of `start_call`'s
+ *  accept. Deliberately SECRET-FREE (`provider` plus non-secret metadata such
+ *  as `agentId` / `model` / `voice`); the actual WebRTC credentials only ride
+ *  the `startCall` HTTP response. */
+export interface CallReadyPayload {
+	provider: string;
+	[k: string]: unknown;
+}
+
+/** Per-event payload types, keyed by outbound event name — what `client.on()`
+ *  narrows envelopes with (0.30.0). Type-only; extending the base Record keeps
+ *  indexing valid for every OutboundType, so an event added to the vocabulary
+ *  before it gets a dedicated payload type simply reads as `unknown`. */
+export interface OutboundPayloadMap extends Record<OutboundType, unknown> {
+	'hello.ack': HelloAckPayload;
+	'companion.message': MessagePayload;
+	'companion.audio': AudioClipPayload;
+	'companion.tool_call': ToolCallPayload;
+	'companion.ui_action': RenderInterfacePayload;
+	'companion.ui_update': InterfaceUpdatePayload;
+	'companion.expression': ExpressionPayload;
+	'companion.voice_inject': VoiceInjectPayload;
+	'companion.confirm_request': ConfirmRequestPayload;
+	'companion.social_message': SocialMessagePayload;
+	'companion.typing': TypingPayload;
+	'control.call_ready': CallReadyPayload;
+	'control.error': ControlErrorPayload;
+	'control.usage': UsagePayload;
+}

package/src/scopes.ts

@@ -0,0 +1,94 @@
+// 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). GET /api/companion/wallet (SDK: getWallet(), 0.20.0+) or ask the companion's wallet tools.
+	'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)
+] as const;
+export type CompanionScope = (typeof COMPANION_SCOPES)[number];
+
+/** I/O modalities a key can carry alongside its scopes. */
+export const COMPANION_MODALITIES = ['text', 'voice', 'call', 'files'] as const;
+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 const SENSITIVE_SCOPES: ReadonlySet<CompanionScope> = new Set<CompanionScope>([
+	'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: ReadonlySet<CompanionScope> = new Set<CompanionScope>([
+	'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: readonly CompanionScope[] = [
+	'chat',
+	'voice',
+	'call',
+	'files',
+	'events.subscribe',
+	'worldstate.write',
+	'memory.read:app',
+	'memory.write:app'
+];
+export const DEFAULT_MODALITIES: readonly CompanionModality[] = ['text', 'voice'];
+
+export function isSensitiveScope(s: CompanionScope): boolean {
+	return SENSITIVE_SCOPES.has(s);
+}
+export function isRepresentScope(s: CompanionScope): boolean {
+	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: readonly string[], required: CompanionScope): boolean {
+	return granted.includes(required);
+}

package/src/sse.ts

@@ -0,0 +1,41 @@
+// Minimal, dependency-free SSE frame parser for the companion SDK. The browser's
+// EventSource can't set an Authorization header, so the SDK consumes the stream
+// over fetch() instead and parses frames itself — this is that parser, kept pure
+// so it unit-tests in isolation.
+//
+// An SSE frame is a block of `field: value` lines terminated by a blank line.
+// Comment lines (starting ":") are keep-alives and ignored. A chunk off the wire
+// may end mid-frame, so the parser returns the leftover for the next call.
+
+export interface SseEvent {
+	/** The `event:` field; defaults to "message" per the SSE spec. */
+	event: string;
+	/** The joined `data:` field(s). */
+	data: string;
+}
+
+/** Parse all COMPLETE frames out of an accumulated buffer. Returns the parsed
+ *  events plus the unparsed remainder (an incomplete trailing frame). */
+export function parseSse(buffer: string): { events: SseEvent[]; rest: string } {
+	const events: SseEvent[] = [];
+	let working = buffer.replace(/\r\n/g, '\n');
+	let sep = working.indexOf('\n\n');
+	while (sep !== -1) {
+		const block = working.slice(0, sep);
+		working = working.slice(sep + 2);
+		let event = 'message';
+		const dataLines: string[] = [];
+		for (const line of block.split('\n')) {
+			if (!line || line.startsWith(':')) continue; // blank or comment (keep-alive)
+			const ci = line.indexOf(':');
+			const field = ci === -1 ? line : line.slice(0, ci);
+			let value = ci === -1 ? '' : line.slice(ci + 1);
+			if (value.startsWith(' ')) value = value.slice(1); // single leading space stripped
+			if (field === 'event') event = value;
+			else if (field === 'data') dataLines.push(value);
+		}
+		if (dataLines.length) events.push({ event, data: dataLines.join('\n') });
+		sep = working.indexOf('\n\n');
+	}
+	return { events, rest: working };
+}

package/src/svelte.ts

@@ -0,0 +1,47 @@
+// Svelte adapter (0.31.0) — `@pouchy_ai/companion-sdk/svelte`.
+// Implements the Svelte STORE CONTRACT (subscribe(run) → unsubscribe) by hand,
+// so it needs no `svelte` import and works from Svelte 3 through 5 (`$store`
+// auto-subscription, or `fromStore()` in runes mode). Behavior lives in
+// adapter-core.ts.
+//
+//   const companion = companionStore(client);
+//   $companion.transcript / $companion.draft / $companion.streamState
+//   companion.sendText('hi');
+
+import type { CompanionClient } from './client';
+import {
+	createCompanionView,
+	type CompanionView,
+	type CompanionViewOptions,
+	type CompanionViewSnapshot
+} from './adapter-core';
+
+/** Svelte-store-contract readable of the companion view snapshot. */
+export interface CompanionStore {
+	/** Store contract: calls `run` with the current snapshot immediately and on
+	 *  every change. Returns unsubscribe. */
+	subscribe(run: (snapshot: CompanionViewSnapshot) => void): () => void;
+	sendText: CompanionView['sendText'];
+	confirmAction: CompanionView['confirmAction'];
+	/** Detach from the client (does not close it). */
+	dispose(): void;
+	client: CompanionClient;
+}
+
+/** Wrap a host-owned client as a Svelte-compatible readable store. */
+export function companionStore(
+	client: CompanionClient,
+	opts?: CompanionViewOptions
+): CompanionStore {
+	const view = createCompanionView(client, opts);
+	return {
+		subscribe(run) {
+			run(view.getSnapshot());
+			return view.subscribe(() => run(view.getSnapshot()));
+		},
+		sendText: view.sendText,
+		confirmAction: view.confirmAction,
+		dispose: view.dispose,
+		client
+	};
+}