@pouchy_ai/companion-sdk 0.53.0 → 0.54.0

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to `@pouchy_ai/companion-sdk` are documented in this file.
 
+## [0.54.0]
+
+- **`MessagePayload.attachments`** — files the turn PRODUCED
+  (`create_spreadsheet` / `create_document`: xlsx, csv, docx, md, txt) now ride
+  the `companion.message` envelope structurally: `{ fileId, fileName, mimeType,
+  url }[]` (new `MessageAttachment` type). `url` is the same 7-day capability
+  URL the reply text contains — the field exists so a host can render a
+  download affordance without parsing prose the model may rewrite or drop.
+  Additive and optional; absent on turns that produced no files. No
+  `PROTOCOL_VERSION` change.
+- The `/embed` widget forwards them to the host page on `pouchy:message`
+  (`{ text, attachments? }`).
+
 ## [0.53.0]
 
 - **`forget(id)`** — forget ONE fact by the `id` a `recall()` row now carries

package/README.md

@@ -142,7 +142,7 @@ type-checks without a cast; `'*'` keeps the untyped envelope:
 
 | Helper | Event | Use |
 | --- | --- | --- |
-| `onMessage(fn)` | `companion.message` | the assistant reply (fires exactly once per turn, streaming or not) |
+| `onMessage(fn)` | `companion.message` | the assistant reply (fires exactly once per turn, streaming or not). When the turn PRODUCED files (`create_spreadsheet` / `create_document` on the companion side), `envelope.payload.attachments` (0.54.0) carries them structurally — `MessageAttachment[]`: `{ fileId, fileName, mimeType, url }`, `url` a 7-day capability download URL — so render a download affordance from the field, not by parsing the prose |
 | `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`. The call carries `argsJson` — `args` pre-parsed as JSON (undefined on empty/malformed args). `replayed: true` (0.37.0) marks a re-delivery of a still-outstanding call after a mid-pause reconnect — treat `id` as an idempotency key for side-effecting tools (see "Resuming a paused turn") |
 | `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` |
@@ -352,7 +352,8 @@ of the public index surface). (`stream_unauthorized` above is a
 `control.error`/`onError` code, not a thrown `CompanionError.code`.) Every
 outbound payload has a named type; `ToolCallPayload` (`{ id, name, args,
 replayed? }`) types the `companion.tool_call` event, `MessagePayload`
-(`{ text, replyTo? }`) types `companion.message`, `PendingToolCall` (0.37.0)
+(`{ text, replyTo?, attachments? }`) types `companion.message` (`attachments`:
+`MessageAttachment[]` — files the turn produced, 0.54.0), `PendingToolCall` (0.37.0)
 types the `HelloAck.pendingToolCalls` entries, and `onToolCall`'s callback
 receives `ToolCallEvent` — the payload plus `argsJson` (pre-parsed args).
 

package/dist/protocol.d.ts

@@ -228,13 +228,25 @@ export interface VoiceInjectPayload {
 export interface TypingPayload {
     active: boolean;
 }
+/** A file the turn PRODUCED (create_spreadsheet / create_document), carried
+ *  structurally on the reply (0.54.0). `url` is a 7-day capability URL — the
+ *  same link the reply text contains — so a host can render a download
+ *  affordance without parsing prose the model may rewrite or drop. */
+export interface MessageAttachment {
+    fileId: string;
+    fileName: string;
+    mimeType: string;
+    url: string;
+}
 /** 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. */
+ *  proactive messages (world-state reactions, confirm outcomes) carry none.
+ *  `attachments` is present only when the turn produced files (0.54.0). */
 export interface MessagePayload {
     text: string;
     replyTo?: string;
+    attachments?: MessageAttachment[];
 }
 /** A live world-state event the app streams in. `retained:true` = latest-value
  *  state (coalesced); `retained:false` = a transient moment carrying `salience`

package/dist/protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pouchy_ai/companion-sdk",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "Embed the Pouchy companion \u2014 chat, voice, tools, memory, live world-state, instant UI, and agent-to-agent messaging \u2014 in any app, game, or site.",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE",

package/src/protocol.ts

@@ -297,13 +297,26 @@ export interface TypingPayload {
 	active: boolean;
 }
 
+/** A file the turn PRODUCED (create_spreadsheet / create_document), carried
+ *  structurally on the reply (0.54.0). `url` is a 7-day capability URL — the
+ *  same link the reply text contains — so a host can render a download
+ *  affordance without parsing prose the model may rewrite or drop. */
+export interface MessageAttachment {
+	fileId: string;
+	fileName: string;
+	mimeType: string;
+	url: string;
+}
+
 /** 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. */
+ *  proactive messages (world-state reactions, confirm outcomes) carry none.
+ *  `attachments` is present only when the turn produced files (0.54.0). */
 export interface MessagePayload {
 	text: string;
 	replyTo?: string;
+	attachments?: MessageAttachment[];
 }
 
 /** A live world-state event the app streams in. `retained:true` = latest-value