@pouchy_ai/companion-sdk 0.12.1 → 0.13.0

package/CHANGELOG.md

@@ -12,6 +12,24 @@ a protocol bump is always called out explicitly here.
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-07-06
+
+### Added
+
+- **Token streaming** — the reply can now render as it is generated instead
+  of arriving as one block. Register `onDelta((chunk, meta) => …)` and
+  `sendText` automatically streams: the POST response itself carries SSE
+  `delta` frames (raw text chunks), an optional `reset` (a hop that streamed
+  text turned out to be tool-call deliberation — clear the partial render),
+  and a final `done` frame. `onMessage` still fires exactly ONCE with the
+  authoritative final text (the done frame's envelope is emitted locally and
+  the event-stream replay of the same envelope id is deduplicated), so
+  existing render code keeps working unchanged — deltas are a pure add-on.
+  Pass `sendText(text, { stream: false })` to force the buffered path, or
+  `{ stream: true }` to stream without a subscriber. Requires a server with
+  streaming input support; on older servers the SDK transparently falls back
+  to the buffered response. No wire-protocol (envelope) change.
+
 ## [0.12.1] - 2026-07-05
 
 ### Added
@@ -127,7 +145,7 @@ self-hosted/CDN build; this entry captures the surface that ships publicly.
 - **Public distribution.** Installable from the public npm registry as
   `@pouchy_ai/companion-sdk`; also resolvable via `esm.sh` / `jsDelivr` for
   no-bundler / import-map consumers, and self-hosted at
-  `https://www.pouchy.ai/sdk/companion-sdk.js`.
+  `https://pouchy.ai/sdk/companion-sdk.js`.
 - **Chat.** Text and multimodal (text + images) messaging.
 - **Voice.** Live WebRTC call (`connectCall`), provider-agnostic across OpenAI
   Realtime (zero extra deps) and ElevenLabs Convai (optional

package/README.md

@@ -18,10 +18,26 @@ No bundler? Pull it from a CDN via an import map instead — see
 [`docs/companion-integration-faq.md`](../../docs/companion-integration-faq.md).
 Changes per release are tracked in [`CHANGELOG.md`](./CHANGELOG.md).
 
+## Quickstart
+
+Two steps. **1)** Your backend exchanges the project **Secret Key** (create one
+in the [dashboard](https://pouchy.ai/dashboard) → Keys) for a per-user
+session token — first-seen `external_user_id`s are provisioned automatically:
+
+```http
+POST https://pouchy.ai/v1/sessions
+Authorization: Bearer pchy_sk_…
+{ "agent": "<agentId>", "external_user_id": "user_4211" }
+
+→ { "session_token": "pchy_…", "expires_in": 3600, "instance": { … } }
+```
+
+**2)** The client connects with the session token (never ship the Secret Key):
+
 ```ts
 import { createCompanion } from '@pouchy_ai/companion-sdk';
 
-const companion = createCompanion({ baseUrl: 'https://www.pouchy.ai', token: PAT });
+const companion = createCompanion({ baseUrl: 'https://pouchy.ai', token: sessionToken });
 await companion.connect();
 companion.onMessage((t) => console.log(t));
 companion.start();
@@ -30,6 +46,9 @@ await companion.connectCall();              // live voice (browser)
 companion.sendWorldState({ type: 'game.player.hp', data: { hp: 12 }, retained: true });
 ```
 
+(Personal/single-user integrations can pass a server-minted Personal Access
+Token as `token` instead — same API. See the docs' authentication section.)
+
 - **Guide:** [`docs/companion-quickstart.md`](../../docs/companion-quickstart.md)
 - **Spec:** [`docs/companion-sdk-protocol.md`](../../docs/companion-sdk-protocol.md)
 - **API reference:** [`docs/companion-api-reference.md`](../../docs/companion-api-reference.md)
@@ -42,7 +61,8 @@ Subscribe with `on(type, fn)` (or `'*'`), or these typed convenience helpers:
 
 | Helper | Event | Use |
 | --- | --- | --- |
-| `onMessage(fn)` | `companion.message` | streamed assistant text |
+| `onMessage(fn)` | `companion.message` | the assistant reply (fires exactly once per turn, streaming or not) |
+| `onDelta(fn)` | *(POST-response SSE)* | **token streaming** — registering makes `sendText` stream the reply as it is generated: `fn(chunk, {reset?})` fires per text chunk (`reset` = clear the partial — that text was tool-call deliberation); `onMessage` then fires once with the authoritative final text (replay-deduplicated). Force per call with `sendText(text, { stream: true \| false })` |
 | `onToolCall(fn)` | `companion.tool_call` | the companion asks your app to run a declared tool → `sendToolResult` |
 | `onRender(fn)` | `companion.ui_action` | **Instant UI** — draw `payload.interface` (platform-neutral genui schema) with your own renderer (web / iOS / Android / CLI). Needs `ui.render` |
 | `onInterfaceUpdate(fn)` | `companion.ui_update` | live `{key,value}` update to an already-rendered panel (no rebuild) |
@@ -75,7 +95,7 @@ memory, system prompt, or PII. Works over text and voice.
 
 ```ts
 const c = createCompanion({
-  baseUrl: 'https://www.pouchy.ai',
+  baseUrl: 'https://pouchy.ai',
   token: OWNER_PAT,                 // must hold the `represent` scope
   surface: 'support-widget',
   appContext: { name: 'AcmeShop', description: 'Order support' },

package/dist/client.d.ts

@@ -4,7 +4,7 @@ import type { AudioClipPayload, CompanionEnvelope, ConfirmRequestPayload, Expres
 export type WorldStateInput<D = unknown> = Omit<WorldStateEvent<D>, 'specversion' | 'id' | 'source'> & Partial<Pick<WorldStateEvent<D>, 'specversion' | 'id' | 'source'>>;
 import { type CompanionCall, type CompanionCallOptions } from './call.js';
 export interface CompanionClientOptions {
-    /** Origin of the Pouchy deployment, e.g. "https://www.pouchy.ai". */
+    /** Origin of the Pouchy deployment, e.g. "https://pouchy.ai". */
     baseUrl: string;
     /** A Pouchy access token (PAT). */
     token: string;
@@ -126,6 +126,15 @@ export declare class CompanionError extends Error {
     constructor(message: string, status: number);
 }
 type Handler = (envelope: CompanionEnvelope) => void;
+/** Token-streaming subscriber (P1-2). `chunk` is a raw text delta of the reply
+ *  being generated; `meta.reset` (with an empty chunk) tells the renderer to
+ *  CLEAR the partial text (a hop that streamed text turned out to be tool-call
+ *  deliberation, not the reply). Deltas are advisory — the final
+ *  companion.message (fired through onMessage as usual) is authoritative and
+ *  should replace whatever the deltas rendered. */
+type DeltaHandler = (chunk: string, meta: {
+    reset?: boolean;
+}) => void;
 export declare class CompanionClient {
     private readonly opts;
     private readonly doFetch;
@@ -135,6 +144,7 @@ export declare class CompanionClient {
     private abort;
     private readonly handlers;
     private readonly seen;
+    private readonly deltaHandlers;
     private readonly pendingVoiceTools;
     constructor(opts: CompanionClientOptions);
     /** The active session id, or null before connect(). */
@@ -158,12 +168,31 @@ export declare class CompanionClient {
     }>;
     /** Send a user text turn, optionally with images (data URLs) for a multimodal
      *  turn — images need the `files` scope. The reply arrives on the event stream
-     *  as a `companion.message` — subscribe via onMessage()/start() to receive it. */
+     *  as a `companion.message` — subscribe via onMessage()/start() to receive it.
+     *
+     *  TOKEN STREAMING (P1-2): when any onDelta() subscriber is registered (or
+     *  `opts.stream` is true), the reply streams token-by-token on this very
+     *  request — delta subscribers fire as chunks arrive, and onMessage still
+     *  fires exactly ONCE with the authoritative final text (the streamed copy
+     *  is emitted locally; the event-stream replay of the same envelope is
+     *  deduplicated by id). Pass `stream: false` to force the buffered path. */
     sendText(text: string, opts?: {
         images?: string[];
+        stream?: boolean;
     }): Promise<{
         seq: number | null;
     }>;
+    /** The streaming leg of sendText: parse the POST response's SSE frames —
+     *  `delta` / `reset` → delta subscribers, `done` → resolve (emitting the
+     *  final envelope locally so onMessage fires immediately and the log replay
+     *  dedups by id). Falls back to buffered semantics if the server ever
+     *  responds with plain JSON (e.g. an old deployment). */
+    private sendTextStreaming;
+    /** Subscribe to token-streaming deltas of the reply (P1-2). Registering a
+     *  subscriber makes sendText stream automatically. Returns an unsubscribe
+     *  function. Render chunks as they arrive; on `meta.reset` clear the partial;
+     *  when onMessage fires, replace the partial with the final text. */
+    onDelta(handler: DeltaHandler): () => void;
     /** Push live world-state — a single event or a batch. Retained events
      *  (retained:true) coalesce per kind; transient ones carry a salience.
      *

package/dist/client.js

@@ -37,6 +37,9 @@ export class CompanionClient {
     abort = null;
     handlers = new Map();
     seen = new Set();
+    // Token-streaming delta subscribers (P1-2). When any are registered,
+    // sendText automatically streams the reply.
+    deltaHandlers = new Set();
     // Voice tool-calls awaiting the app's sendToolResult, keyed by a synthetic id.
     pendingVoiceTools = new Map();
     constructor(opts) {
@@ -115,11 +118,98 @@ export class CompanionClient {
     }
     /** Send a user text turn, optionally with images (data URLs) for a multimodal
      *  turn — images need the `files` scope. The reply arrives on the event stream
-     *  as a `companion.message` — subscribe via onMessage()/start() to receive it. */
+     *  as a `companion.message` — subscribe via onMessage()/start() to receive it.
+     *
+     *  TOKEN STREAMING (P1-2): when any onDelta() subscriber is registered (or
+     *  `opts.stream` is true), the reply streams token-by-token on this very
+     *  request — delta subscribers fire as chunks arrive, and onMessage still
+     *  fires exactly ONCE with the authoritative final text (the streamed copy
+     *  is emitted locally; the event-stream replay of the same envelope is
+     *  deduplicated by id). Pass `stream: false` to force the buffered path. */
     async sendText(text, opts) {
         const id = this.requireSession();
-        const json = await this.postJson(`/api/companion/session/${id}/input`, { text, ...(opts?.images?.length ? { images: opts.images } : {}) });
-        return { seq: json.seq ?? null };
+        const wantStream = opts?.stream ?? this.deltaHandlers.size > 0;
+        const body = { text, ...(opts?.images?.length ? { images: opts.images } : {}) };
+        if (!wantStream) {
+            const json = await this.postJson(`/api/companion/session/${id}/input`, body);
+            return { seq: json.seq ?? null };
+        }
+        return this.sendTextStreaming(id, body);
+    }
+    /** The streaming leg of sendText: parse the POST response's SSE frames —
+     *  `delta` / `reset` → delta subscribers, `done` → resolve (emitting the
+     *  final envelope locally so onMessage fires immediately and the log replay
+     *  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`), {
+            method: 'POST',
+            headers: this.jsonHeaders(),
+            body: JSON.stringify({ ...body, stream: true })
+        });
+        const ctype = res.headers.get('content-type') ?? '';
+        if (!ctype.includes('text/event-stream')) {
+            // Old server / error before the stream opened — behave like postJson.
+            const json = (await res.json().catch(() => null));
+            if (!res.ok || !json || json.ok === false) {
+                throw new CompanionError(json?.error || `request failed (${res.status})`, res.status);
+            }
+            return { seq: json.seq ?? null };
+        }
+        if (!res.body)
+            throw new CompanionError('streaming response has no body', 502);
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = '';
+        const fireDelta = (chunk, meta) => {
+            for (const h of this.deltaHandlers)
+                h(chunk, meta);
+        };
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (value)
+                buf += decoder.decode(value, { stream: true });
+            const { events, rest } = parseSse(buf);
+            buf = rest;
+            for (const ev of events) {
+                if (ev.event === 'delta') {
+                    const d = JSON.parse(ev.data);
+                    if (typeof d.text === 'string' && d.text)
+                        fireDelta(d.text, {});
+                }
+                else if (ev.event === 'reset') {
+                    fireDelta('', { reset: true });
+                }
+                else if (ev.event === 'done') {
+                    const d = JSON.parse(ev.data);
+                    try {
+                        await reader.cancel();
+                    }
+                    catch {
+                        /* stream already finished */
+                    }
+                    if (d.ok === false) {
+                        throw new CompanionError(d.error || 'turn failed', d.status ?? 500);
+                    }
+                    // Emit the final envelope NOW so onMessage fires with zero poll
+                    // latency; the event-stream replay of the same id is deduped.
+                    if (d.envelope && typeof d.envelope === 'object')
+                        this.emit(d.envelope);
+                    return { seq: d.seq ?? null };
+                }
+            }
+            if (done)
+                break;
+        }
+        throw new CompanionError('stream ended without a done frame', 502);
+    }
+    /** Subscribe to token-streaming deltas of the reply (P1-2). Registering a
+     *  subscriber makes sendText stream automatically. Returns an unsubscribe
+     *  function. Render chunks as they arrive; on `meta.reset` clear the partial;
+     *  when onMessage fires, replace the partial with the final text. */
+    onDelta(handler) {
+        this.deltaHandlers.add(handler);
+        return () => this.deltaHandlers.delete(handler);
     }
     /** Push live world-state — a single event or a batch. Retained events
      *  (retained:true) coalesce per kind; transient ones carry a salience.

package/dist/index.js

@@ -2,7 +2,7 @@
 // surface (web / app / game / hardware) over the REST/SSE plane.
 //
 //   import { createCompanion } from '$lib/companion-sdk';
-//   const c = createCompanion({ baseUrl: 'https://www.pouchy.ai', token: PAT });
+//   const c = createCompanion({ baseUrl: 'https://pouchy.ai', token: PAT });
 //   await c.connect();
 //   c.onMessage((text) => console.log(text));
 //   c.start();

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.12.1",
+  "version": "0.13.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",
-  "homepage": "https://www.pouchy.ai",
+  "homepage": "https://pouchy.ai",
   "repository": {
     "type": "git",
     "url": "https://github.com/oviswang/Pouchy.git",