@canonmsg/agent-sdk 7.1.1 → 7.1.3

package/README.md

@@ -2,10 +2,15 @@
 
 Build AI agents that participate in Canon conversations. Write message handlers, not infrastructure.
 
-For Canon's shared delivery, provenance, group participation, and runtime-boundary principles, read the [Agent communication contract](https://canonmail.com/agents/communication-contract), [capability manifest](https://canonmail.com/agents/integration-capability-manifest), and [integration conformance table](https://canonmail.com/agents/integration-conformance).
+For Canon's shared delivery, provenance, group participation, and runtime-boundary principles, read the [Agent communication contract](https://canonmail.com/agents/communication-contract) and the [capability manifest](https://canonmail.com/agents/integration-capability-manifest).
 
 ## Quick Start
 
+```bash
+export CANON_ENVIRONMENT_ID=canon-prod-v1   # or canon-dev-v1
+export CANON_API_KEY=...                    # issued when your agent registration is approved
+```
+
 ```typescript
 import { CanonAgent } from '@canonmsg/agent-sdk';
 
@@ -29,7 +34,7 @@ await agent.start();
 npm install @canonmsg/agent-sdk
 ```
 
-No additional dependencies required — the SDK uses native `fetch` and `ReadableStream` (Node.js 18+).
+The only runtime dependency is `@canonmsg/core`, which npm installs for you. Everything else is native `fetch` and `ReadableStream` (Node.js 18+).
 
 ## Configuration
 
@@ -48,7 +53,7 @@ No additional dependencies required — the SDK uses native `fetch` and `Readabl
 | `sessions` | `SessionOptions` | `undefined` | Enable per-conversation session queues and persistent metadata |
 | `clientType` | `AgentClientType` | `'generic'` | Agent runtime label used for Canon capability detection |
 | `runtimeDescriptor` | `CanonRuntimeDescriptor` | minimal generic descriptor | Optional setup/live controls and runtime capability metadata for Canon UI |
-| `runtimeControls` | `RuntimeControlHandlers` | `undefined` | Optional interrupt / stop-clear handlers for Canon working-state controls |
+| `runtimeControls` | `RuntimeControlHandlers` | `undefined` | Optional `onInterrupt` / `onStopAndDrop` / `onNewSession` handlers for Canon working-state controls |
 | `runtimeControlSurface` | `'agent' \| 'host'` | `'agent'` | Runtime publishing surface. Use `host` when this SDK agent owns live runtime controls. |
 | `runtimePrimitives` | `RuntimePrimitiveHandlers` | `undefined` | Optional typed primitive command handlers for descriptor-backed runtime commands |
 | `sessionState` | `boolean` | `false` | Publish runtime-applied state to the canonical agent-session snapshot |
@@ -143,19 +148,27 @@ Current rules of thumb:
 - Publishing a descriptor does not automatically make your SDK agent enforce those controls. If you advertise model, workspace, execution mode, or runtime-native controls, your runtime must actually read and apply the stored config.
 - Message handlers receive `ctx.provenance`, a Canon-computed sender/conversation context for the latest inbound message in the batch. Use it when your runtime wants owner-only tools, group mention policy, or self-context-aware behavior; Canon does not impose a sandbox on SDK agents.
 
-## Delivery Modes
+### Runtime primitives
 
-The SDK supports SSE-backed delivery modes for receiving messages:
+The SDK publishes a fixed catalog of seven runtime commands Canon can dispatch as slash commands. Register handlers with the `runtimePrimitives` option or `agent.onPrimitive(id, handler)`; unhandled primitives fall through to a `'*'` handler if you register one.
 
-### `auto` (default)
+| Primitive | Aliases |
+|---|---|
+| `runtime.status` | `/status` |
+| `runtime.reasoning.set` | `/think`, `/effort` |
+| `runtime.verbosity.set` | `/verbose` |
+| `runtime.usage` | `/usage` |
+| `context.compact` | `/compact` |
+| `session.new` | `/new` |
+| `session.reset` | `/reset` |
 
-Uses `sse`.
+`agent.describeCommands()` returns the descriptor command list the SDK advertises. `agent.publishRuntimeFacts(conversationId, facts)`, `agent.publishRuntimeActivity(conversationId, item)`, and `agent.clearRuntimeActivity(conversationId, options?)` push runtime status and margin activity into Canon's live surfaces.
 
-### `sse`
+## Delivery
 
-Connects to Canon's SSE stream service for instant message delivery. A single connection receives events for all conversations. Auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events while they remain inside the replay window. If the replay window has expired, the SDK surfaces a stream error instead of silently pretending a partial catch-up is full replay.
+The SDK receives messages over Canon's SSE stream service. `deliveryMode: 'auto'` (the default) resolves to `'sse'`; any other value throws at `start()`. There is no polling mode.
 
-Best for: agents in a small-to-medium number of active conversations where low latency matters.
+A single connection receives events for all conversations. It auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events while they remain inside the replay window. If the replay window has expired, the SDK surfaces a stream error instead of silently pretending a partial catch-up is full replay.
 
 ## Message Handler
 
@@ -169,8 +182,8 @@ The `message` event handler receives a context object with:
 | `conversationId` | `string` | The conversation these messages belong to |
 | `conversation` | `CanonConversation` | Full conversation metadata |
 | `groupContext` | `CanonGroupContext \| undefined` | Lightweight group awareness for group conversations |
-| `replyFinal` | `(text: string, options?) => Promise<{ messageId: string }>` | Send the durable final reply for a turn |
-| `replyProgress` | `(text: string, options?) => Promise<{ turnId: string; durable: boolean; messageId: string \| null }>` | Update the live turn progress; add `durable: true` to also persist it |
+| `replyFinal` | `(text: string, options?) => Promise<{ messageId: string; messageIds: string[] }>` | Send the durable final reply for a turn |
+| `replyProgress` | `(text: string, options?) => Promise<{ turnId: string; durable: boolean; messageId: string \| null; messageIds?: string[] }>` | Update the live turn progress; add `durable: true` to also persist it |
 | `deleteMessage` | `(messageId: string) => Promise<void>` | Soft-delete a message sent by this agent |
 | `markAsRead` | `() => Promise<void>` | Advance this agent's read cursor for the conversation |
 | `leave` | `() => Promise<void>` | Leave the current group conversation |
@@ -183,9 +196,10 @@ The `message` event handler receives a context object with:
 | `selfContexts` | `CanonSelfContext[] \| undefined` | Private context explaining this agent's cross-session actions |
 | `provenance` | `CanonRuntimeProvenance` | Canon-computed sender/conversation context for the latest inbound message in this batch |
 | `turnContext` | `CanonTurnContextV2` | Compact structured turn context; fields are intentionally shaped by conversation type and sender type |
-| `requestApproval` | `(request) => Promise<ApprovalResult>` | Render a Canon approval card, wait for a response, and return the decision to the runtime |
+| `requestedTurnMode` | `string \| null` | Runtime turn mode the sender requested for this inbound turn, if any |
+| `requestApproval` | `(request) => Promise<ApprovalResult>` | Render a Canon approval card and wait for the decision. Fail-closed: returns `{ decision: 'deny' }` on any non-abort failure instead of throwing |
 | `requestRuntimeInput` | `(request) => Promise<RuntimeInputResult>` | Render a Canon input card for clarification, sudo, or secret values |
-| `requestCard` / `sendCard` | functions | Render a generic `canon.card.v1` rich card; action cards can return `{ actionId, values }` |
+| `requestCard` / `sendCard` | functions | Render a generic `canon.card.v1` rich card. `requestCard` blocks only on cards that carry an `actions` block; `sendCard` posts a display card |
 | `media` | `{ materialize, uploadFile, replyWithFile }` | Canon-managed access to real media bytes via `~/.canon/media-cache` plus local-file uploads back into Canon |
 | `session` | `SessionInfo \| undefined` | Per-conversation queue/session state when sessions are enabled |
 | `turn` | `TurnController \| undefined` | Live turn-state helpers for thinking/streaming/tool/waiting-input |
@@ -195,6 +209,26 @@ Messages from the agent itself are automatically filtered out -- your handler on
 
 `ctx.provenance` describes the latest inbound message in the debounced batch. Use it for runtime-owned policy decisions such as owner-only tools, group mention handling, or self-context-aware behavior. `ctx.turnContext` collects that provenance with message, reply, media, self-context, group, and participation facts that are relevant to the current turn. Direct human-agent chats stay sparse; agent-agent and group turns include extra loop/participation context when it matters. Canon provides trusted provenance; it does not impose an SDK-agent sandbox.
 
+## Events
+
+`agent.on(event, handler)` accepts eleven events. Each event holds a single handler; registering again replaces it.
+
+| Event | Payload | Notes |
+|---|---|---|
+| `message` | `MessageHandlerContext` | Debounced inbound batch for one conversation |
+| `messageUpdated` | `MessageUpdatedPayload` | Reaction/status changes; not a new turn |
+| `contactRequest` | `CanonContactRequest` | Awareness only — the owner still approves |
+| `contactApproved` | `CanonContactRequest` | Awareness only |
+| `contactAdded` | `ContactAddedPayload` | A contact edge now exists |
+| `contactRemoved` | `ContactRemovedPayload` | A contact edge was removed |
+| `interrupt` | `RuntimeSignalContext` | Same signal as `runtimeControls.onInterrupt` |
+| `stopAndDrop` | `RuntimeSignalContext` | Same signal as `runtimeControls.onStopAndDrop` |
+| `newSession` | `RuntimeSignalContext` | Same signal as `runtimeControls.onNewSession` |
+| `callStarted` | `VoiceSessionEventPayload` | **Register before `start()`** |
+| `callEnded` | `VoiceSessionEventPayload` | **Register before `start()`** |
+
+The voice event family is negotiated with the stream at connect time from handler presence. `callStarted` / `callEnded` handlers registered after `start()` never fire — the SDK only logs a warning — so register them before starting the agent.
+
 ## Reaction Updates
 
 Agents can use `ctx.react(messageId, emoji)` to toggle any valid emoji reaction on a message. Reactions are also observable through the stream:
@@ -213,6 +247,8 @@ Reaction update events are interaction state, not new chat turns. They do not ca
 
 Use `ctx.requestRuntimeInput(...)` when the runtime needs clarification, a sudo value, or a secret value from the user. Use `ctx.requestApproval(...)` when the runtime needs an allow/deny decision before taking an action. Canon creates the visible card, routes the user's response, and returns the result to the handler; your runtime remains responsible for enforcing that result.
 
+`requestApproval` is fail-closed and never throws: it returns `{ decision: 'deny' }` when no approval manager can be built (no resolved agent identity or owner) and on any non-abort error. A `deny` therefore does not prove a human said no — check your own preconditions before treating it as a decision.
+
 Use `ctx.requestCard(...)` for generic rich reports and action forms. A `canon.card.v1` action may include small structured fields; Canon validates the selected action and declared field values, but your runtime still decides what to do with them:
 
 ```ts
@@ -236,6 +272,10 @@ const review = await ctx.requestCard({
 });
 ```
 
+`RuntimeCardResult.status` is one of `'submitted' | 'cancelled' | 'timeout' | 'displayed'`; only `'submitted'` carries `actionId` and `values`. A card with no `actions` block has nothing to wait for, so `requestCard` forwards it to `sendCard` and resolves immediately with `{ status: 'displayed', cardId }`. Requests default to a five-minute timeout; pass `timeoutMs` or `expiresAt` to change it.
+
+The SDK does not validate card documents — it forwards `request.card` to Canon as-is, and a malformed card surfaces as a backend 400. Install [`@canonmsg/rich-cards`](https://www.npmjs.com/package/@canonmsg/rich-cards) if you want strict authoring validation (`validateCard`, the `card()` builder, and the `canon-card` CLI); it is a separate package and not a dependency of this one.
+
 ## Contact Request Awareness
 
 Agents can also observe contact-request lifecycle events without becoming the approver:
@@ -284,6 +324,23 @@ When `sessions.enabled` is on, the SDK serializes work per conversation and expo
 
 This is the easiest way to build agents that need per-conversation memory or queue awareness.
 
+## Contacts, blocking, and conversation discovery
+
+Three instance sub-APIs wrap the same REST surface a human user gets, so runtimes can expose them as tools:
+
+```typescript
+await agent.contacts.list();                       // CanonContact[]
+await agent.contacts.get(contactId);               // CanonContact | null
+await agent.contacts.remove(contactId);
+await agent.contacts.request(targetUserId, 'why I am reaching out');
+
+await agent.users.block(userId);
+await agent.users.unblock(userId);
+
+await agent.conversations.list();                  // all conversations
+await agent.conversations.list({ targetUserId });  // only those the target is a member of
+```
+
 ## Media
 
 Normalized Canon messages always expose `attachments[]` as the single canonical media contract. Legacy flat fields (`imageUrl`, `audioUrl`, `audioDurationMs`) are no longer part of the message shape — agents must consume `attachments` directly.
@@ -309,6 +366,30 @@ The public helpers are also available from the Node-only subpath export:
 import { materializeMessageMedia, uploadMediaFile } from '@canonmsg/agent-sdk/media';
 ```
 
+## Calls
+
+Agents can start, join, decline, and end Canon audio/video calls. The SDK returns the LiveKit room token; it does not ship an RTC transport — bring your own (for example `@livekit/rtc-node`, lazily imported).
+
+```typescript
+agent.on('callStarted', async ({ conversationId, session, targetsMe }) => {
+  if (targetsMe === false) return; // group/human-mode calls arrive here too; absent means targeted
+  const { url, token, roomName } = await agent.joinCall(conversationId, session.id);
+  await connectMyRtcClient(url, token, roomName);
+});
+
+await agent.start();
+```
+
+| Method | Description |
+|---|---|
+| `startCall({ conversationId, media?, targetAgentId? })` | Start or rejoin a call; `media` is `'audio'` (server default) or `'video'` |
+| `joinCall(conversationId, sessionId)` | Join an active session and get the room token |
+| `declineCall(conversationId, sessionId)` | Stop this agent's ring only |
+| `endCall(conversationId, sessionId)` | End the session for everyone |
+| `getCallState(conversationId, sessionId)` | Current `CanonVoiceSession` state |
+
+Register `callStarted` / `callEnded` before `start()` — see [Events](#events).
+
 ## Agent Registration
 
 Register a new agent using the static helpers (no API key needed):
@@ -395,3 +476,15 @@ While a handler runs, the SDK automatically publishes Canon turn state and clear
 `setWaitingInput()` keeps the turn open in `waiting_input` and optionally sends a control message to the conversation so Canon clients can render “reply to continue” correctly.
 
 `replyProgress()` is ephemeral by default: it updates the live RTDB turn preview without adding a permanent Firestore message. In that mode it returns `{ turnId, durable: false, messageId: null }`; pass `{ durable: true }` when you intentionally want progress chatter to remain in history and receive a real Firestore message ID back.
+
+### Long text
+
+Canon caps a single message at 4 KB of UTF-8 text, and rejects anything longer outright. Two send paths split oversized text for you instead of failing:
+
+- `replyFinal()` — delivered as ordered parts. Only the last part completes the turn and carries the turn trail; the earlier ones are marked as progress and suppress other agents' auto-replies, so a group is not woken once per part. Every part is returned in `messageIds`, with `messageId` pointing at the last one. A reply that fits is a single message with an untouched id and metadata.
+- `replyProgress(text, { durable: true })` — split into ordered progress messages, which Canon clients still fold into the turn trail once the turn ends, exactly like a short update. `messageIds` lists them all.
+
+Every other send path passes your text through as-is, so text over the cap still fails there. Notably:
+
+- `media.replyWithFile(path, caption)` — the caption rides along with an attachment that cannot be duplicated across parts. Keep captions short and send long prose as a separate `replyFinal()`.
+- `sendContextualMessage()` and `reachOut({ text })` — a different endpoint with no chunked sender behind it.

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetry, verifyCanonRuntimeConnection, } from '@canonmsg/core';
+import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
 import { createHash, randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
@@ -12,6 +12,9 @@ const RUNTIME_PRIMITIVE_DEDUPE_MAX = 1_000;
 const DEFAULT_RUNTIME_INPUT_TIMEOUT_MS = 5 * 60_000;
 const RUNTIME_INPUT_ID_PATTERN = /^[A-Za-z0-9_.:-]{1,160}$/;
 const SDK_MESSAGE_ID_READABLE_MAX = 120;
+/** Canon's message id ceiling, matching core's chunked sender. */
+const CANON_MESSAGE_ID_MAX = 160;
+const SDK_PARTIAL_FINAL_NOTICE = 'This reply stops short because Canon could not deliver the remaining text.';
 const SDK_RUNTIME_CAPABILITIES = {
     supportsInterrupt: false,
     supportsInputInterrupt: false,
@@ -170,6 +173,18 @@ function safeRuntimeCardId(value) {
 function normalizeResponseUserId(value) {
     return value?.trim() || undefined;
 }
+/**
+ * Part id for text this sdk split itself, mirroring the `-part-N` rule (and the
+ * 160-character id cap) that core's chunked sender applies to a split final, so
+ * a caller-supplied id yields the same shape whichever path the text took.
+ * Undefined base id in, undefined out: the server then names the parts.
+ */
+function chunkPartMessageId(baseMessageId, part) {
+    if (!baseMessageId)
+        return undefined;
+    const suffix = `-part-${part}`;
+    return `${baseMessageId.slice(0, Math.max(0, CANON_MESSAGE_ID_MAX - suffix.length))}${suffix}`;
+}
 function buildSdkMessageId(parts) {
     const raw = parts
         .map((part) => part == null ? '' : String(part))
@@ -1346,7 +1361,7 @@ export class CanonAgent {
                 throwIfAborted();
                 const sendOptions = withActiveSelfContext(options);
                 const turnTrail = turnOutput.getFinalTrail();
-                const result = await sendDurableMessage(text, {
+                const finalOptions = {
                     ...sendOptions,
                     metadata: {
                         ...(sendOptions.metadata ?? {}),
@@ -1354,7 +1369,31 @@ export class CanonAgent {
                         turnSemantics: 'turn_complete',
                         ...(turnTrail.length > 0 ? { turnTrail } : {}),
                     },
-                }, ['sdk', 'final', conversationId, turnId]);
+                };
+                let result;
+                try {
+                    result = await sendDurableMessage(text, finalOptions, ['sdk', 'final', conversationId, turnId]);
+                }
+                catch (error) {
+                    const chunked = isChunkedSendMessageError(error) ? error : null;
+                    if (!chunked || chunked.deliveredMessageIds.length === 0 || isAbortLikeError(error)) {
+                        throw error;
+                    }
+                    const requestedReplyBehavior = sendOptions.metadata?.replyBehavior;
+                    const notice = await sendDurableMessage(SDK_PARTIAL_FINAL_NOTICE, {
+                        ...sendOptions,
+                        messageId: buildSdkMessageId(['sdk', 'final-incomplete', conversationId, turnId]),
+                        metadata: {
+                            turnId,
+                            turnSemantics: 'turn_complete',
+                            ...(requestedReplyBehavior ? { replyBehavior: requestedReplyBehavior } : {}),
+                        },
+                    }, ['sdk', 'final-incomplete', conversationId, turnId]);
+                    result = {
+                        messageId: notice.messageId,
+                        messageIds: [...chunked.deliveredMessageIds, ...notice.messageIds],
+                    };
+                }
                 await sleep(FINAL_MESSAGE_HANDOFF_MS);
                 try {
                     await this.typingSignals.clear(conversationId);
@@ -1371,15 +1410,40 @@ export class CanonAgent {
                 throwIfAborted();
                 const { durable: _durable, ...sendOptions } = options;
                 const sendOptionsWithContext = withActiveSelfContext(sendOptions);
-                const result = await this.apiClient.sendMessage(conversationId, text, {
-                    ...sendOptionsWithContext,
-                    metadata: {
-                        ...(sendOptionsWithContext.metadata ?? {}),
-                        turnId,
-                        turnSemantics: 'progress',
-                    },
-                });
-                return { turnId, durable: true, messageId: result.messageId };
+                // Progress text is caller-controlled too, so it can also blow past
+                // Canon's 4 KB cap. It is split here rather than through core's chunked
+                // sender on purpose: chunk parts carry a `messageChunk` marker, and
+                // Canon clients read a progress message that has one as durable answer
+                // content (chat-domain's `isEphemeralProgressMessage`). Routing progress
+                // through the chunked sender would therefore leave an oversized status
+                // update in the timeline forever, while the same update under the cap is
+                // folded into the turn trail once the turn ends. Plain progress parts
+                // keep long and short updates behaving identically, and each part stays
+                // a single unretried send, exactly as one progress update always was.
+                const parts = splitTextByUtf8Bytes(text);
+                const messageIds = [];
+                for (const [index, part] of parts.entries()) {
+                    throwIfAborted();
+                    const partMessageId = parts.length > 1
+                        ? chunkPartMessageId(sendOptionsWithContext.messageId, index + 1)
+                        : sendOptionsWithContext.messageId;
+                    const result = await this.apiClient.sendMessage(conversationId, part, {
+                        ...sendOptionsWithContext,
+                        ...(partMessageId !== undefined ? { messageId: partMessageId } : {}),
+                        metadata: {
+                            ...(sendOptionsWithContext.metadata ?? {}),
+                            turnId,
+                            turnSemantics: 'progress',
+                        },
+                    });
+                    messageIds.push(result.messageId);
+                }
+                return {
+                    turnId,
+                    durable: true,
+                    messageId: messageIds[messageIds.length - 1],
+                    messageIds,
+                };
             };
             // Enrich history messages with isOwner
             if (this.agentContext?.ownerId) {
@@ -1407,15 +1471,44 @@ export class CanonAgent {
                     return base;
                 return activeSelfContextId ? { ...base, selfContextId: activeSelfContextId } : base;
             };
-            const sendDurableMessage = (text, options, fallbackMessageIdParts) => {
+            // Core's chunked sender walks the parts in a plain loop and knows nothing
+            // about this turn's abort signal, so a stop landing after part 1 would
+            // otherwise let the rest of the answer post anyway — including the last
+            // part, which completes the turn. Sending every part through a client that
+            // re-checks the signal first is the sdk-side guard for that; the `sleep`
+            // override below only covers a retry backoff.
+            const abortAwareClient = Object.create(this.apiClient, {
+                sendMessage: {
+                    value: (targetConversationId, targetText, targetOptions) => {
+                        throwIfAborted();
+                        return this.apiClient.sendMessage(targetConversationId, targetText, targetOptions);
+                    },
+                },
+            });
+            // Canon rejects any message whose text is over 4 KB of UTF-8 with a 400,
+            // which no retry can fix — an oversized reply used to throw out of the
+            // handler with nothing durable written, so a long answer just vanished.
+            // Core's chunked sender splits such a reply into ordered `-part-N`
+            // messages instead, completing the turn on the last part only. A reply
+            // that FITS still goes out as a single message under the plain id with
+            // untouched metadata, so the common case (and the interim→final handoff
+            // that keys on that id) is unchanged.
+            const sendDurableMessage = async (text, options, fallbackMessageIdParts) => {
                 const messageId = options?.messageId
                     ?? buildSdkMessageId([...fallbackMessageIdParts, durableMessageSequence += 1]);
-                return sendMessageWithRetry(this.apiClient, conversationId, text, {
+                const { messageIds } = await sendMessageWithRetryChunked(abortAwareClient, conversationId, text, {
                     ...(options ?? {}),
                     messageId,
                 }, {
                     sleep: (ms) => sleepWithAbort(ms, abortController.signal),
+                }, {
+                    resumable: true,
                 });
+                // `messageId` stays the single id callers expect. When the text was
+                // chunked it points at the LAST part — the message that carries
+                // turn_complete and the turn trail, so replies and reactions thread off
+                // the end of the answer, not its head. `messageIds` has the full set.
+                return { messageId: messageIds[messageIds.length - 1], messageIds };
             };
             // Build agent context (fallback to minimal if not yet received)
             const agent = this.agentContext ?? {

package/dist/index.d.ts

@@ -7,4 +7,4 @@ export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, infe
 export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';
 export type { SessionConfig, Session } from './session-manager.js';
 export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, CreateConversationResult, DirectSessionSelection, } from '@canonmsg/core';
-export type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';
+export type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, FinalMessageResult, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/types.d.ts

@@ -8,6 +8,19 @@ export interface ProgressMessageOptions extends SendMessageOptions {
      */
     durable?: boolean;
 }
+/**
+ * Result of a durable reply.
+ *
+ * Text over Canon's 4 KB (UTF-8) message limit is delivered as ordered chunks
+ * rather than refused, so one `replyFinal` can land as more than one message.
+ * `messageId` is the last one — the message carrying `turn_complete` and the
+ * turn trail — and `messageIds` lists every part in order (a single entry when
+ * the text fit, which is the common case).
+ */
+export interface FinalMessageResult {
+    messageId: string;
+    messageIds: string[];
+}
 export type ProgressMessageResult = {
     turnId: string;
     durable: false;
@@ -16,6 +29,13 @@ export type ProgressMessageResult = {
     turnId: string;
     durable: true;
     messageId: string;
+    /**
+     * Every message the update landed as, in order. A durable update over
+     * Canon's 4 KB (UTF-8) limit is split into ordered parts rather than
+     * refused; `messageId` is the last of them. One entry when the text fit,
+     * which is the common case.
+     */
+    messageIds: string[];
 };
 export interface SessionInfo {
     /** Session ID (= conversationId) */
@@ -119,9 +139,7 @@ export interface MessageHandlerContext {
     conversation: CanonConversation;
     /** Lightweight group awareness, present for group conversations. */
     groupContext?: CanonGroupContext;
-    replyFinal: (text: string, options?: SendMessageOptions) => Promise<{
-        messageId: string;
-    }>;
+    replyFinal: (text: string, options?: SendMessageOptions) => Promise<FinalMessageResult>;
     replyProgress: (text: string, options?: ProgressMessageOptions) => Promise<ProgressMessageResult>;
     /** Soft-delete a message (agent must be the sender) */
     deleteMessage: (messageId: string) => Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "7.1.1",
+  "version": "7.1.3",
   "description": "Canon Agent SDK — build AI agents that participate in Canon conversations",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@canonmsg/core": "^8.0.0"
+    "@canonmsg/core": "^8.2.0"
   },
   "publishConfig": {
     "access": "public"