@pouchy_ai/companion-sdk 0.35.0 → 0.37.0

package/src/client.ts

@@ -22,6 +22,7 @@ import type {
 	OutboundPayloadMap,
 	OutboundType,
 	PendingConfirm,
+	PendingToolCall,
 	RenderInterfacePayload,
 	SocialMessagePayload,
 	ToolCallPayload,
@@ -62,7 +63,11 @@ export interface CompanionClientOptions {
 	surface?: string;
 	/** Requested I/O modalities (intersected with the token's grant server-side). */
 	modalities?: string[];
-	/** Action types this surface can perform (declared at handshake). */
+	/** Action types this surface can perform (declared at handshake). Stored but
+	 *  never consumed server-side today — a client-side capability hint whose one
+	 *  SDK effect is opting a tool-less embed into the auto-offered host-control
+	 *  verbs on connectCall() voice sessions. It does NOT register tools for text
+	 *  turns: a tool you want called on a text turn must be declared in `tools`. */
 	handles?: string[];
 	/** World-state kinds this surface emits (declared at handshake). */
 	contextKinds?: string[];
@@ -117,6 +122,19 @@ export interface CompanionClientOptions {
 	 *  error responses (4xx/5xx incl. 429) are NEVER queued — the server saw
 	 *  those; they keep the normal throw semantics. Default false. */
 	queueOffline?: boolean;
+	/** Replay of pause-orphaned tool calls (0.37.0). When `connect()` resumes a
+	 *  session whose turn is paused on tool calls THIS surface never answered
+	 *  (the page reloaded / crashed mid-pause), the handshake carries them as
+	 *  `pendingToolCalls` and the client re-emits each to your onToolCall
+	 *  handler with `replayed: true` — post the results as usual and the paused
+	 *  turn completes instead of being abandoned. Register onToolCall BEFORE
+	 *  calling connect()/start() to receive them. The result apply is
+	 *  idempotent per call id, but the APP-side effect may not be: if a tool
+	 *  has side effects, treat `call.id` as an idempotency key when
+	 *  `replayed` is set. Pass false to disable the re-emit — the calls stay
+	 *  readable on the `HelloAck.pendingToolCalls` you get from connect().
+	 *  Default true. */
+	replayPendingToolCalls?: boolean;
 	/** Persistence for the offline queue (see `queueOffline`). Defaults to
 	 *  localStorage when available (privacy-mode / quota failures fall back
 	 *  silently), else an in-memory page-lifetime store. The key is
@@ -146,6 +164,11 @@ export interface HelloAck {
 	 *  the owner (their two companions are friends). Lets you skip offering a
 	 *  "pair" affordance to an already-connected visitor. */
 	visitorPaired: boolean;
+	/** Outstanding tool calls of a turn that paused before this handshake —
+	 *  non-empty only when resuming mid-pause (0.37.0). Unless
+	 *  `replayPendingToolCalls: false`, each is also re-emitted to onToolCall
+	 *  with `replayed: true` right after connect() resolves. */
+	pendingToolCalls: PendingToolCall[];
 }
 
 /** A tool the embedding declares the companion may ask it to perform. */
@@ -393,6 +416,9 @@ export class CompanionClient {
 	private readonly doFetch: typeof fetch;
 	private _session: string | null = null;
 	private cursor = 0;
+	/** Pause-orphaned call replay fired (0.37.0) — once per client instance, so
+	 *  a manual second connect() can't double-deliver to a live handler. */
+	private replayedPendingToolCalls = false;
 	private streaming = false;
 	private abort: AbortController | null = null;
 	// Bumped on every start()/stop(): a loop whose generation is stale exits
@@ -734,6 +760,7 @@ export class CompanionClient {
 			resumeCursor: number;
 			representative?: boolean;
 			visitorPaired?: boolean;
+			pendingToolCalls?: PendingToolCall[];
 		}>('/api/companion/session', {
 			surface: this.opts.surface ?? 'default',
 			modalities: this.opts.modalities,
@@ -748,10 +775,44 @@ export class CompanionClient {
 		// A successful handshake proves reachability — replay any sends queued
 		// while offline (0.34.0; no-op when the queue is empty).
 		if (this.opts.queueOffline) void this.flushOutbox().catch(() => {});
+		const pendingToolCalls = Array.isArray(json.pendingToolCalls)
+			? json.pendingToolCalls.filter(
+					(c): c is PendingToolCall => !!c && typeof c.id === 'string' && typeof c.name === 'string'
+				)
+			: [];
+		// Pause-orphaned call replay (0.37.0): re-emit each outstanding call to
+		// onToolCall so a reloaded embed completes the paused turn. Deferred a
+		// tick so `await connect()` callers can still register handlers first;
+		// once-per-client so a second connect() (manual re-handshake) can't
+		// double-deliver alongside a live handler that already got them. The
+		// synthetic envelope id is derived from the callId, so the stream-replay
+		// of the ORIGINAL envelope (a client resuming with a persisted cursor)
+		// carries a different id and the app-facing `replayed` flag is the
+		// dedup signal — see the option's jsdoc on idempotency.
+		if (
+			pendingToolCalls.length &&
+			this.opts.replayPendingToolCalls !== false &&
+			!this.replayedPendingToolCalls
+		) {
+			this.replayedPendingToolCalls = true;
+			setTimeout(() => {
+				for (const c of pendingToolCalls) {
+					this.emit({
+						v: PROTOCOL_VERSION,
+						id: `replay_${c.id}`,
+						ts: Date.now(),
+						session: json.session,
+						type: 'companion.tool_call',
+						payload: { id: c.id, name: c.name, args: c.args ?? '', replayed: true }
+					} as CompanionEnvelope);
+				}
+			}, 0);
+		}
 		return {
 			...json,
 			representative: json.representative ?? false,
-			visitorPaired: json.visitorPaired ?? false
+			visitorPaired: json.visitorPaired ?? false,
+			pendingToolCalls
 		};
 	}
 
@@ -1576,10 +1637,20 @@ export class CompanionClient {
 		handler: (call: ToolCallEvent, envelope: CompanionEnvelope) => void
 	): () => void {
 		return this.on('companion.tool_call', (env) => {
-			const p = env.payload as { id?: unknown; name?: unknown; args?: unknown };
+			const p = env.payload as { id?: unknown; name?: unknown; args?: unknown; replayed?: unknown };
 			if (typeof p?.id === 'string' && typeof p?.name === 'string') {
 				const args = typeof p.args === 'string' ? p.args : '';
-				handler({ id: p.id, name: p.name, args, argsJson: parseArgsJson(args) }, env);
+				handler(
+					{
+						id: p.id,
+						name: p.name,
+						args,
+						argsJson: parseArgsJson(args),
+						// Pause-orphaned replay (0.37.0) — see replayPendingToolCalls.
+						...(p.replayed === true ? { replayed: true } : {})
+					},
+					env
+				);
 			}
 		});
 	}

package/src/index.ts

@@ -64,6 +64,7 @@ export type {
 	SocialMessagePayload,
 	ConfirmRequestPayload,
 	PendingConfirm,
+	PendingToolCall,
 	ToolCallPayload,
 	AudioClipPayload,
 	ExpressionPayload,

package/src/protocol.ts

@@ -161,6 +161,32 @@ export interface ToolCallPayload {
 	name: string;
 	/** The model's arguments as a raw JSON string. */
 	args: string;
+	/** True when this delivery is a REPLAY of a still-outstanding call from a
+	 *  turn that paused before a reconnect (see hello.ack `pendingToolCalls`) —
+	 *  the app may have already performed it and crashed before posting the
+	 *  result. Side-effecting tools should treat `id` as an idempotency key.
+	 *  Absent on the original live delivery. */
+	replayed?: boolean;
+}
+
+/** One outstanding tool call from a turn that paused BEFORE this handshake —
+ *  carried on `hello.ack` (0.37.0) so an embed that lost its state (tab
+ *  reload / crash mid-pause) can rediscover what it owes and COMPLETE the
+ *  paused turn instead of abandoning it via `/end`. Post each result with
+ *  `sendToolResult(id, …)` exactly like a live `companion.tool_call`; the
+ *  server's apply is idempotent per id, so double-posting is safe. */
+export interface PendingToolCall {
+	/** 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;
+	/** Correlation id of the paused turn (when the pausing client minted one). */
+	turnId?: string;
+	/** Epoch ms the turn paused / last progressed — judge staleness before
+	 *  replaying a side-effecting call. */
+	pausedAt?: number;
 }
 
 /** Payload of a `companion.ui_update` event — a live change to an
@@ -283,6 +309,11 @@ export interface HelloAckPayload {
 	resumeCursor?: number;
 	representative?: boolean;
 	visitorPaired?: boolean;
+	/** Outstanding tool calls from a turn that paused before this handshake —
+	 *  present (non-empty) only when resuming a session mid-pause. See
+	 *  PendingToolCall; the SDK re-emits them to onToolCall with
+	 *  `replayed: true` unless `replayPendingToolCalls: false`. */
+	pendingToolCalls?: PendingToolCall[];
 }
 
 /** Payload of a `control.call_ready` event — the stream echo of `start_call`'s