@canonmsg/agent-sdk 7.1.1 → 7.1.2

package/README.md

@@ -169,8 +169,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 |
@@ -395,3 +395,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, 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,8 @@ 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_RUNTIME_CAPABILITIES = {
     supportsInterrupt: false,
     supportsInputInterrupt: false,
@@ -170,6 +172,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))
@@ -1371,15 +1385,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 +1446,42 @@ 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),
                 });
+                // `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.2",
   "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.1.0"
   },
   "publishConfig": {
     "access": "public"