@pouchy_ai/companion-sdk 0.53.0 → 0.54.1

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to `@pouchy_ai/companion-sdk` are documented in this file.
 
+## [0.54.1]
+
+### Fixed
+
+- **`TurnUsage` and `MessageAttachment` are now importable from the package
+  root.** Both were declared and documented as public — 0.52.0's entry says
+  "new exported type `TurnUsage`", the README names `MessageAttachment[]` on
+  `companion.message` — and both are the field types of exports that DID
+  resolve (`SendTextReply.usage`, `MessagePayload.attachments`), but neither
+  was re-exported from `index.ts`, so `import type { TurnUsage } from
+  '@pouchy_ai/companion-sdk'` failed with TS2305 and an integrator had to
+  retype the shape or reach for `NonNullable<SendTextReply['usage']>`. The
+  export-surface gate that caught the previous instance of this (0.36.x,
+  `DataActivityPayload`) only walked the types named directly in
+  `OutboundPayloadMap`; it now also asserts that every type the READMEs or
+  this changelog name as public is importable from the root. Types only —
+  the bundle's runtime bytes are unchanged.
+
+## [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/index.d.ts

@@ -2,13 +2,13 @@ import { CompanionClient, type CompanionClientOptions } from './client.js';
 export { CompanionClient, CompanionError, pouchyBrandIconUrl, OUTBOX_AMBIGUOUS_MAX_AGE_MS, OUTBOX_MAX_REPLAY_ATTEMPTS } from './client.js';
 export type { CompanionDebugEvent } from './client.js';
 export type { CompanionErrorCodeValue, ControlErrorCodeValue } from './errors.js';
-export type { CompanionClientOptions, CompanionStreamState, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, ToolCallEvent, WorldStateInput, CompanionAvatar, CompanionWallet, WalletBalance, BrandIconSize, EndSessionResult, SendTextReply, QueuedSend, OutboxStore } from './client.js';
+export type { CompanionClientOptions, CompanionStreamState, HelloAck, RecalledMemory, CompanionTurn, CallCredentials, CompanionToolDecl, ToolCallEvent, WorldStateInput, CompanionAvatar, CompanionWallet, WalletBalance, BrandIconSize, EndSessionResult, SendTextReply, TurnUsage, QueuedSend, OutboxStore } 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 { VOICE_TOOL_VARIABLE, VOICE_TOOL_VARIABLE_PLAIN, VOICE_TOOL_HEADER_PLAIN } from './voice-tool.js';
 export { COMPANION_SCOPES, COMPANION_MODALITIES, SENSITIVE_SCOPES, REPRESENT_SCOPES, DEFAULT_SCOPES, DEFAULT_MODALITIES, isSensitiveScope, isRepresentScope, hasScope, grantsScope } from './scopes.js';
 export type { CompanionScope, CompanionModality } from './scopes.js';
-export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, DataActivityPayload, SkillCardPayload, ConfirmRequestPayload, PendingConfirm, PendingToolCall, ToolCallPayload, AudioClipPayload, ExpressionPayload, TypingPayload, VoiceInjectPayload, UsagePayload, MessagePayload, ControlErrorPayload, HelloAckPayload, CallReadyPayload, OutboundPayloadMap } from './protocol.js';
+export type { CompanionEnvelope, OutboundType, InboundType, WorldStateEvent, RenderInterfacePayload, InterfaceUpdatePayload, SocialMessagePayload, DataActivityPayload, SkillCardPayload, ConfirmRequestPayload, PendingConfirm, PendingToolCall, ToolCallPayload, AudioClipPayload, ExpressionPayload, TypingPayload, VoiceInjectPayload, UsagePayload, MessagePayload, MessageAttachment, ControlErrorPayload, HelloAckPayload, CallReadyPayload, OutboundPayloadMap } from './protocol.js';
 export { PROTOCOL_VERSION, INBOUND_TYPES, OUTBOUND_TYPES, COMPANION_ERROR_CODES, CONTROL_ERROR_CODES } from './protocol.js';
 export type { CompanionErrorCode, ControlErrorCode } from './protocol.js';
 export { toA2UI, fromA2UI, INSTANT_UI_NODE_TYPES } from './a2ui.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAExE,OAAO,EACN,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,2BAA2B,EAC3B,0BAA0B,EAC1B,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,YAAY,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAC/E,YAAY,EACX,sBAAsB,EACtB,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,eAAe,EACf,eAAe,EACf,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,WAAW,EACX,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAInF,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvG,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClE,YAAY,EACX,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,MAAM,YAAY,CAAC;AAKpB,OAAO,EACN,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMvE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AACjE,YAAY,EACX,WAAW,EACX,aAAa,EACb,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,cAAc,EACd,MAAM,QAAQ,CAAC;AAMhB,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,YAAY,EACX,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,MAAM,gBAAgB,CAAC;AAExB,iCAAiC;AACjC,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,eAAe,CAE7E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAExE,OAAO,EACN,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,2BAA2B,EAC3B,0BAA0B,EAC1B,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,YAAY,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAC/E,YAAY,EACX,sBAAsB,EACtB,oBAAoB,EACpB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,eAAe,EACf,eAAe,EACf,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,SAAS,EACT,UAAU,EACV,WAAW,EACX,MAAM,UAAU,CAAC;AAClB,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AAInF,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvG,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAClE,YAAY,EACX,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,eAAe,EACf,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,cAAc,EACd,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EAClB,MAAM,YAAY,CAAC;AAKpB,OAAO,EACN,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAMvE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AACjE,YAAY,EACX,WAAW,EACX,aAAa,EACb,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,cAAc,EACd,MAAM,QAAQ,CAAC;AAMhB,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACrD,YAAY,EACX,aAAa,EACb,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,MAAM,gBAAgB,CAAC;AAExB,iCAAiC;AACjC,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,eAAe,CAE7E"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,yEAAyE;AACzE,sDAAsD;AACtD,EAAE;AACF,0DAA0D;AAC1D,6EAA6E;AAC7E,uBAAuB;AACvB,8CAA8C;AAC9C,eAAe;AACf,8EAA8E;AAC9E,2CAA2C;AAE3C,OAAO,EAAE,eAAe,EAA+B,MAAM,UAAU,CAAC;AAExE,OAAO,EACN,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,2BAA2B,EAC3B,0BAA0B,EAC1B,MAAM,UAAU,CAAC;AAsBlB,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,MAAM,QAAQ,CAAC;AAEhB,4EAA4E;AAC5E,4EAA4E;AAC5E,+EAA+E;AAC/E,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvG,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,MAAM,UAAU,CAAC;AA2BlB,wEAAwE;AACxE,2EAA2E;AAC3E,8EAA8E;AAC9E,gEAAgE;AAChE,OAAO,EACN,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,MAAM,YAAY,CAAC;AAGpB,+EAA+E;AAC/E,0EAA0E;AAC1E,2EAA2E;AAC3E,4EAA4E;AAC5E,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAWjE,6EAA6E;AAC7E,6EAA6E;AAC7E,0EAA0E;AAC1E,+BAA+B;AAC/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAQrD,iCAAiC;AACjC,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC3D,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,yEAAyE;AACzE,sDAAsD;AACtD,EAAE;AACF,0DAA0D;AAC1D,6EAA6E;AAC7E,uBAAuB;AACvB,8CAA8C;AAC9C,eAAe;AACf,8EAA8E;AAC9E,2CAA2C;AAE3C,OAAO,EAAE,eAAe,EAA+B,MAAM,UAAU,CAAC;AAExE,OAAO,EACN,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,2BAA2B,EAC3B,0BAA0B,EAC1B,MAAM,UAAU,CAAC;AAuBlB,OAAO,EACN,iBAAiB,EACjB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,MAAM,QAAQ,CAAC;AAEhB,4EAA4E;AAC5E,4EAA4E;AAC5E,+EAA+E;AAC/E,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvG,OAAO,EACN,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,MAAM,UAAU,CAAC;AA4BlB,wEAAwE;AACxE,2EAA2E;AAC3E,8EAA8E;AAC9E,gEAAgE;AAChE,OAAO,EACN,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,MAAM,YAAY,CAAC;AAGpB,+EAA+E;AAC/E,0EAA0E;AAC1E,2EAA2E;AAC3E,4EAA4E;AAC5E,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAC;AAWjE,6EAA6E;AAC7E,6EAA6E;AAC7E,0EAA0E;AAC1E,+BAA+B;AAC/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAQrD,iCAAiC;AACjC,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC3D,OAAO,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}

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.1",
   "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/index.ts

@@ -37,6 +37,7 @@ export type {
 	BrandIconSize,
 	EndSessionResult,
 	SendTextReply,
+	TurnUsage,
 	QueuedSend,
 	OutboxStore
 } from './client';
@@ -85,6 +86,7 @@ export type {
 	VoiceInjectPayload,
 	UsagePayload,
 	MessagePayload,
+	MessageAttachment,
 	ControlErrorPayload,
 	HelloAckPayload,
 	CallReadyPayload,

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