@canonmsg/agent-sdk 1.7.0 → 2.1.0

package/README.md

@@ -38,10 +38,13 @@ No additional dependencies required — the SDK uses native `fetch` and `Readabl
 | `deliveryMode` | `'auto' \| 'sse'` | `'auto'` | How the SDK receives new messages |
 | `debounceMs` | `number` | `2000` | Batching window for incoming messages per conversation |
 | `historyLimit` | `number` | `50` | Number of historical messages to fetch (max 100) |
+| `autoMarkRead` | `boolean` | `true` | Advance Canon's read cursor explicitly after handling inbound messages. History fetches are read-only. |
 | `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 |
+| `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 RTDB session-state for the conversations this agent is active in |
 
 ### Optional runtime controls
@@ -154,17 +157,38 @@ The `message` event handler receives a context object with:
 |---|---|---|
 | `messages` | `CanonMessage[]` | New messages in this batch (debounced, sorted by time) |
 | `history` | `CanonMessage[]` | Last N messages before these new ones |
+| `replyContext` | `CanonReplyContext \| null` | Resolved swipe-reply target for the latest inbound message, when available |
 | `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 |
+| `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 |
+| `react` | `(messageId, emoji) => Promise<void>` | Toggle an emoji reaction |
+| `addMember` / `removeMember` | functions | Manage group members when the agent has permission |
+| `sendContextualMessage` | function | Send into another conversation with private self-context from this conversation |
+| `reachOut` | function | Act on a Canon contact card using live admission resolution |
 | `agent` | `AgentContext` | Trusted Canon agent identity and access context |
+| `activeSelfContextId` | `string \| null` | Active private self-context id for this turn |
+| `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 |
+| `requestApproval` | `(request) => Promise<ApprovalResult>` | Render a Canon approval card, wait for a response, and return the decision to the runtime |
+| `requestRuntimeInput` | `(request) => Promise<RuntimeInputResult>` | Render a Canon input card for clarification, sudo, or secret values |
 | `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 |
+| `abortSignal` | `AbortSignal` | Cooperative cancellation signal for interrupt/stop handling |
 
 Messages from the agent itself are automatically filtered out -- your handler only receives messages from other participants.
 
+`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. Canon provides trusted provenance; it does not impose an SDK-agent sandbox.
+
+### Human-in-the-loop cards
+
+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.
+
 ## Contact Request Awareness
 
 Agents can also observe contact-request lifecycle events without becoming the approver:
@@ -252,7 +276,7 @@ const { requestId, pollToken } = await CanonAgent.register({
 });
 
 console.log('Registration submitted:', requestId);
-console.log('Poll token:', pollToken);
+await saveRegistrationPickup({ requestId, pollToken });
 
 // 2. Poll for approval
 const status = await CanonAgent.checkStatus(requestId, { pollToken });
@@ -260,12 +284,13 @@ console.log('Status:', status.status); // 'pending' | 'approved' | 'rejected'
 
 if (status.status === 'approved' && status.apiKey) {
   console.log('Agent ID:', status.agentId);
-  console.log('API Key:', status.apiKey); // Store this immediately
+  await saveAgentCredentials({ agentId: status.agentId, apiKey: status.apiKey });
   await CanonAgent.ackStatus(requestId, { pollToken });
 }
 ```
 
 The approved response only includes the API key until you acknowledge delivery. Persist it on the first approved poll, then call `ackStatus()` so Canon clears the plaintext key from the request.
+Replace `saveRegistrationPickup` and `saveAgentCredentials` with your own encrypted/local secret-store writes; do not print these values in logs.
 
 ## Error Handling
 

package/dist/canon-agent.js

@@ -1,7 +1,8 @@
-import { ApprovalManager, CanonClient, buildCanonGroupContext, createTurnOutputController, createRuntimeStatePublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeInputOutcome, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, } from '@canonmsg/core';
+import { ApprovalManager, CanonClient, buildCanonGroupContext, createTurnOutputController, createRuntimeStatePublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, rtdbRead, rtdbWrite, normalizeTurnMetadata, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, selectActiveSelfContexts, } from '@canonmsg/core';
 import { randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.js';
+import { buildRuntimeCardCreateArgs } from './runtime-card.js';
 import { materializeMessageMedia, materializeReplyContextMedia, sendMediaFileMessage, uploadMediaFile, } from './media.js';
 import { SessionManager } from './session-manager.js';
 const AGENT_RUNTIME_HEARTBEAT_MS = 30_000;
@@ -23,6 +24,17 @@ const DEFAULT_SDK_RUNTIME_DESCRIPTOR = {
     runtimeControls: [],
     supportsInterrupt: false,
     streamingTextMode: 'snapshot',
+    runtimeCards: {
+        rich: {
+            schema: 'canon.card.v1',
+            lifecycle: 'blocking_requires_action',
+            responder: 'agent_owner',
+            result: 'action_or_values',
+            maxTimeoutMs: 30 * 60_000,
+            blockKinds: ['summary', 'metricGrid', 'chart', 'table', 'list', 'callout', 'actions'],
+            native: true,
+        },
+    },
 };
 const STANDARD_PRIMITIVE_COMMANDS = {
     'runtime.status': {
@@ -146,6 +158,13 @@ function safeRuntimeInputId(value, kind) {
         ? normalized
         : `${kind}_${randomUUID()}`;
 }
+function safeRuntimeCardId(value) {
+    const raw = value?.trim() || `card_${randomUUID()}`;
+    const normalized = raw.replace(/[.#$\[\]\/\s]+/g, '_').slice(0, 80);
+    return RUNTIME_INPUT_ID_PATTERN.test(normalized)
+        ? normalized
+        : `card_${randomUUID()}`;
+}
 function isRuntimePrimitiveId(value) {
     return value === 'runtime.status'
         || value === 'runtime.reasoning.set'
@@ -319,7 +338,6 @@ export class CanonAgent {
                 : null;
             const consumed = manager.handleMessage(conversationId, {
                 senderId: message.senderId,
-                ...(typeof message.text === 'string' ? { text: message.text } : {}),
                 ...(metadataRecord ? { metadata: metadataRecord } : {}),
             });
             return !consumed && metadataRecord?.type !== 'approval_reply';
@@ -673,35 +691,33 @@ export class CanonAgent {
         const hasInterrupt = this.hasInterruptSupport();
         const hasStopAndDrop = this.hasStopAndDropSupport();
         const hasNewSession = this.hasNewSessionSupport();
-        const actions = [...(source.actions ?? [])].filter((action) => {
-            if (action.dispatch.kind !== 'signal')
+        const commands = [...(source.commands ?? [])].filter((command) => {
+            if (command.dispatch.kind === 'signal') {
+                if (command.dispatch.signal === 'interrupt')
+                    return hasInterrupt;
+                if (command.dispatch.signal === 'stop_and_drop')
+                    return hasStopAndDrop;
+                if (command.dispatch.signal === 'new_session')
+                    return hasNewSession;
+                return false;
+            }
+            if (command.dispatch.kind !== 'primitive')
                 return true;
-            if (action.dispatch.signal === 'interrupt')
-                return hasInterrupt;
-            if (action.dispatch.signal === 'stop_and_drop')
-                return hasStopAndDrop;
-            if (action.dispatch.signal === 'new_session')
-                return hasNewSession;
-            return false;
+            return this.primitiveHandlers.has(command.dispatch.primitive)
+                || Boolean(this.primitiveFallbackHandler);
         });
-        const hasInterruptAction = actions.some((action) => action.dispatch.kind === 'signal' && action.dispatch.signal === 'interrupt');
-        const hasStopAndDropAction = actions.some((action) => action.dispatch.kind === 'signal' && action.dispatch.signal === 'stop_and_drop');
-        const hasNewSessionAction = actions.some((action) => action.dispatch.kind === 'signal' && action.dispatch.signal === 'new_session');
+        const hasInterruptAction = commands.some((action) => action.dispatch.kind === 'signal' && action.dispatch.signal === 'interrupt');
+        const hasStopAndDropAction = commands.some((action) => action.dispatch.kind === 'signal' && action.dispatch.signal === 'stop_and_drop');
+        const hasNewSessionAction = commands.some((action) => action.dispatch.kind === 'signal' && action.dispatch.signal === 'new_session');
         if (hasInterrupt && !hasInterruptAction) {
-            actions.push(RUNTIME_STOP_ACTION);
+            commands.push(RUNTIME_STOP_ACTION);
         }
         if (hasStopAndDrop && this.sessionManager && !hasStopAndDropAction) {
-            actions.push(RUNTIME_STOP_AND_DROP_ACTION);
+            commands.push(RUNTIME_STOP_AND_DROP_ACTION);
         }
         if (hasNewSession && !hasNewSessionAction) {
-            actions.push(RUNTIME_NEW_SESSION_ACTION);
+            commands.push(RUNTIME_NEW_SESSION_ACTION);
         }
-        const commands = [...(source.commands ?? [])].filter((command) => {
-            if (command.dispatch.kind !== 'primitive')
-                return true;
-            return this.primitiveHandlers.has(command.dispatch.primitive)
-                || Boolean(this.primitiveFallbackHandler);
-        });
         const hasCommandForPrimitive = (primitive) => commands.some((command) => (command.primitive === primitive
             || (command.dispatch.kind === 'primitive' && command.dispatch.primitive === primitive)));
         for (const primitive of this.primitiveHandlers.keys()) {
@@ -714,7 +730,6 @@ export class CanonAgent {
             supportsInterrupt: hasInterrupt,
             supportsInputInterrupt: source.supportsInputInterrupt === false ? false : hasInterrupt,
             commands,
-            actions,
         };
     }
     buildRuntimeCapabilities() {
@@ -1121,6 +1136,7 @@ export class CanonAgent {
                 status: snapshot.status,
                 messageId: snapshot.messageId,
                 turnId: snapshot.turnId,
+                blocks: snapshot.blocks,
             }),
             clearSnapshot: () => this.apiClient.clearStreaming(conversationId),
         });
@@ -1178,13 +1194,14 @@ export class CanonAgent {
                 catch { }
                 throwIfAborted();
                 const sendOptions = withActiveSelfContext(options);
+                const turnTrail = turnOutput.getFinalTrail();
                 const result = await this.apiClient.sendMessage(conversationId, text, {
                     ...sendOptions,
                     metadata: {
                         ...(sendOptions.metadata ?? {}),
                         turnId,
                         turnSemantics: 'turn_complete',
-                        turnComplete: true,
+                        ...(turnTrail.length > 0 ? { turnTrail } : {}),
                     },
                 });
                 await sleep(FINAL_MESSAGE_HANDOFF_MS);
@@ -1209,7 +1226,6 @@ export class CanonAgent {
                         ...(sendOptionsWithContext.metadata ?? {}),
                         turnId,
                         turnSemantics: 'progress',
-                        turnComplete: false,
                     },
                 });
                 return { turnId, durable: true, messageId: result.messageId };
@@ -1311,7 +1327,6 @@ export class CanonAgent {
                         ...(options.messageOptions?.metadata ?? {}),
                         turnId,
                         turnSemantics: 'turn_complete',
-                        turnComplete: true,
                     },
                 },
             });
@@ -1328,6 +1343,13 @@ export class CanonAgent {
                 shouldPersistTurnState = true;
                 try {
                     try {
+                        await turnOutput.addBlock({
+                            id: `approval:${request.runtimeId ?? request.toolName}:${turnId}`,
+                            kind: 'approval',
+                            status: 'pending',
+                            title: request.toolSummary ?? request.toolName,
+                            summary: request.risk ?? request.category,
+                        });
                         await turnOutput.waitingInput();
                     }
                     catch { }
@@ -1350,6 +1372,12 @@ export class CanonAgent {
                     });
                     throwIfAborted();
                     shouldPersistTurnState = false;
+                    try {
+                        await turnOutput.completeBlock(`approval:${request.runtimeId ?? request.toolName}:${turnId}`, {
+                            summary: `Decision: ${result.decision}`,
+                        });
+                    }
+                    catch { }
                     try {
                         await this.apiClient.setTyping(conversationId, true, 'thinking');
                     }
@@ -1398,6 +1426,7 @@ export class CanonAgent {
                         title: request.title,
                         prompt: request.prompt,
                         ...(request.choices ? { choices: request.choices } : {}),
+                        ...(request.questions ? { questions: request.questions } : {}),
                         ...(request.secretName ? { secretName: request.secretName } : {}),
                         ...(request.native ? { native: request.native } : {}),
                         ...(request.sensitive !== undefined ? { sensitive: request.sensitive } : {}),
@@ -1405,6 +1434,13 @@ export class CanonAgent {
                     });
                     requestCreated = true;
                     try {
+                        await turnOutput.addBlock({
+                            id: `input:${inputId}`,
+                            kind: 'input',
+                            status: 'pending',
+                            title: request.title ?? request.prompt ?? request.kind,
+                            summary: request.kind,
+                        });
                         await turnOutput.waitingInput();
                     }
                     catch { }
@@ -1425,6 +1461,7 @@ export class CanonAgent {
                                 result = {
                                     status: 'submitted',
                                     value: response.value,
+                                    answers: response.answers,
                                     inputId,
                                 };
                                 break;
@@ -1448,7 +1485,12 @@ export class CanonAgent {
                                 inputId,
                             });
                             if (response.status === 'submitted') {
-                                result = { status: 'submitted', value: response.value, inputId };
+                                result = {
+                                    status: 'submitted',
+                                    value: response.value,
+                                    answers: response.answers,
+                                    inputId,
+                                };
                             }
                             else if (response.status === 'cancelled' || response.status === 'timeout') {
                                 result = { status: response.status, inputId };
@@ -1471,6 +1513,12 @@ export class CanonAgent {
                     });
                     throwIfAborted();
                     shouldPersistTurnState = false;
+                    try {
+                        await turnOutput.completeBlock(`input:${inputId}`, {
+                            summary: `Input ${result.status}`,
+                        });
+                    }
+                    catch { }
                     try {
                         await this.apiClient.setTyping(conversationId, true, 'thinking');
                     }
@@ -1483,6 +1531,193 @@ export class CanonAgent {
                     if (abortController.signal.aborted || isAbortLikeError(error)) {
                         throw error;
                     }
+                    if (!requestCreated) {
+                        throw error;
+                    }
+                    shouldPersistTurnState = false;
+                    return result;
+                }
+            };
+            const sendCard = async (request) => {
+                throwIfAborted();
+                const cardId = safeRuntimeCardId(request.cardId ?? request.card.cardId);
+                const explicitExpiresAt = request.expiresAt instanceof Date
+                    ? request.expiresAt.getTime()
+                    : typeof request.expiresAt === 'number'
+                        ? request.expiresAt
+                        : typeof request.expiresAt === 'string'
+                            ? Date.parse(request.expiresAt)
+                            : null;
+                const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
+                const expiresAtMs = explicitExpiresAt && Number.isFinite(explicitExpiresAt)
+                    ? explicitExpiresAt
+                    : Date.now() + timeoutMs;
+                // Fire-and-forget: post the durable card and return. The backend treats an
+                // action-less card as display (no pending state, no response expected).
+                await this.apiClient.createRuntimeCardRequest(buildRuntimeCardCreateArgs({ request, conversationId, cardId, fallbackTurnId: turnId, expiresAtMs }));
+                try {
+                    await turnOutput.addBlock({
+                        id: `card:${cardId}`,
+                        kind: 'status',
+                        status: 'completed',
+                        title: request.card.title,
+                        summary: request.card.template ?? 'runtime card',
+                    });
+                }
+                catch { }
+                return { status: 'displayed', cardId };
+            };
+            const requestCard = async (request) => {
+                throwIfAborted();
+                // Action-less cards are fire-and-forget display/report cards — never block.
+                const hasActions = Array.isArray(request.card.blocks)
+                    && request.card.blocks.some((block) => block.kind === 'actions');
+                if (!hasActions)
+                    return sendCard(request);
+                const cardId = safeRuntimeCardId(request.cardId ?? request.card.cardId);
+                const explicitExpiresAt = request.expiresAt instanceof Date
+                    ? request.expiresAt.getTime()
+                    : typeof request.expiresAt === 'number'
+                        ? request.expiresAt
+                        : typeof request.expiresAt === 'string'
+                            ? Date.parse(request.expiresAt)
+                            : null;
+                const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
+                const expiresAtMs = explicitExpiresAt && Number.isFinite(explicitExpiresAt)
+                    ? explicitExpiresAt
+                    : Date.now() + timeoutMs;
+                let result = { status: 'timeout', cardId };
+                let requestCreated = false;
+                let requestResolved = false;
+                const cancelPendingRequest = async () => {
+                    if (!requestCreated || requestResolved)
+                        return;
+                    try {
+                        await this.apiClient.consumeRuntimeCardResponse({
+                            conversationId,
+                            cardId,
+                            cancel: true,
+                        });
+                        requestResolved = true;
+                    }
+                    catch { }
+                };
+                shouldPersistTurnState = true;
+                try {
+                    await this.apiClient.createRuntimeCardRequest(buildRuntimeCardCreateArgs({ request, conversationId, cardId, fallbackTurnId: turnId, expiresAtMs }));
+                    requestCreated = true;
+                    try {
+                        await turnOutput.addBlock({
+                            id: `card:${cardId}`,
+                            kind: 'input',
+                            status: 'pending',
+                            title: request.card.title,
+                            summary: request.card.template ?? 'runtime card',
+                        });
+                        await turnOutput.waitingInput();
+                    }
+                    catch { }
+                    await writeTurn('waiting_input');
+                    try {
+                        await this.apiClient.setTyping(conversationId, false);
+                    }
+                    catch { }
+                    while (Date.now() < expiresAtMs) {
+                        throwIfAborted();
+                        try {
+                            const response = await this.apiClient.consumeRuntimeCardResponse({
+                                conversationId,
+                                cardId,
+                            });
+                            if (response.status === 'submitted') {
+                                requestResolved = true;
+                                result = {
+                                    status: 'submitted',
+                                    cardId,
+                                    ...(response.actionId ? { actionId: response.actionId } : {}),
+                                    ...(response.values ? { values: response.values } : {}),
+                                };
+                                break;
+                            }
+                            if (response.status === 'cancelled' || response.status === 'timeout') {
+                                requestResolved = true;
+                                result = { status: response.status, cardId };
+                                break;
+                            }
+                        }
+                        catch {
+                            // Keep waiting; the control path is the authoritative source and
+                            // transient consume failures should not leak response values.
+                        }
+                        await sleepWithAbort(Math.min(RUNTIME_INPUT_POLL_MS, Math.max(1, expiresAtMs - Date.now())), abortController.signal);
+                    }
+                    if (!requestResolved) {
+                        try {
+                            const response = await this.apiClient.consumeRuntimeCardResponse({
+                                conversationId,
+                                cardId,
+                            });
+                            if (response.status === 'submitted') {
+                                result = {
+                                    status: 'submitted',
+                                    cardId,
+                                    ...(response.actionId ? { actionId: response.actionId } : {}),
+                                    ...(response.values ? { values: response.values } : {}),
+                                };
+                            }
+                            else if (response.status === 'cancelled' || response.status === 'timeout') {
+                                result = { status: response.status, cardId };
+                            }
+                        }
+                        catch { }
+                        requestResolved = true;
+                    }
+                    // The interactive path never yields 'displayed' (that returns early via
+                    // sendCard); narrow for buildRuntimeCardOutcome's resolution status.
+                    const resolutionStatus = result.status === 'displayed' ? 'timeout' : result.status;
+                    const outcome = buildRuntimeCardOutcome(cardId, resolutionStatus, {
+                        reason: resolutionStatus,
+                    });
+                    await this.apiClient.sendMessage(conversationId, outcome.text, {
+                        metadata: {
+                            ...outcome.metadata,
+                            turnId: request.turnId ?? turnId,
+                            turnSemantics: 'control',
+                            replyBehavior: 'suppress_auto_reply',
+                        },
+                    });
+                    throwIfAborted();
+                    shouldPersistTurnState = false;
+                    try {
+                        await turnOutput.completeBlock(`card:${cardId}`, {
+                            summary: `Card ${result.status}`,
+                        });
+                    }
+                    catch { }
+                    try {
+                        await this.apiClient.setTyping(conversationId, true, 'thinking');
+                    }
+                    catch { }
+                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    return result;
+                }
+                catch (error) {
+                    const shouldSendInterruptedOutcome = requestCreated && !requestResolved;
+                    await cancelPendingRequest();
+                    if (abortController.signal.aborted || isAbortLikeError(error)) {
+                        if (shouldSendInterruptedOutcome) {
+                            const outcome = buildRuntimeCardOutcome(cardId, 'cancelled', { reason: 'interrupted' });
+                            await this.apiClient.sendMessage(conversationId, outcome.text, {
+                                metadata: {
+                                    ...outcome.metadata,
+                                    turnId: request.turnId ?? turnId,
+                                    turnSemantics: 'control',
+                                    replyBehavior: 'suppress_auto_reply',
+                                },
+                            }).catch(() => { });
+                        }
+                        throw error;
+                    }
                     shouldPersistTurnState = false;
                     return result;
                 }
@@ -1496,6 +1731,7 @@ export class CanonAgent {
                 catch { }
                 throwIfAborted();
                 try {
+                    const turnTrail = turnOutput.getFinalTrail();
                     const result = await sendMediaFileMessage(this.apiClient, conversationId, filePath, text, {
                         ...(options?.replyTo ? { replyTo: options.replyTo } : {}),
                         ...(options?.replyToPosition != null
@@ -1509,7 +1745,7 @@ export class CanonAgent {
                             ...(options?.metadata ?? {}),
                             turnId,
                             turnSemantics: 'turn_complete',
-                            turnComplete: true,
+                            ...(turnTrail.length > 0 ? { turnTrail } : {}),
                         },
                         ...(options?.fileName ? { fileName: options.fileName } : {}),
                         ...(options?.mimeType ? { mimeType: options.mimeType } : {}),
@@ -1550,6 +1786,8 @@ export class CanonAgent {
                 provenance,
                 requestApproval,
                 requestRuntimeInput,
+                requestCard,
+                sendCard,
                 abortSignal: abortController.signal,
                 media: {
                     materialize: (message = hydratedMessages[hydratedMessages.length - 1], options) => {
@@ -1595,6 +1833,22 @@ export class CanonAgent {
                         turnOutput.appendBlock(block);
                         void writeTurn('streaming');
                     },
+                    addBlock: async (block) => {
+                        throwIfAborted();
+                        return turnOutput.addBlock(block);
+                    },
+                    updateBlock: async (id, patch) => {
+                        throwIfAborted();
+                        return turnOutput.updateBlock(id, patch);
+                    },
+                    completeBlock: async (id, patch) => {
+                        throwIfAborted();
+                        return turnOutput.completeBlock(id, patch);
+                    },
+                    failBlock: async (id, patch) => {
+                        throwIfAborted();
+                        return turnOutput.failBlock(id, patch);
+                    },
                     replaceSnapshot: async (text) => {
                         await setLiveState('streaming', text, 'streaming');
                     },
@@ -1605,7 +1859,14 @@ export class CanonAgent {
                         await turnOutput.clear();
                     },
                     setTool: async (text) => {
-                        await setLiveState('tool', text, 'tool');
+                        await writeTurn('tool');
+                        await turnOutput.addBlock({
+                            id: `tool:${Date.now()}`,
+                            kind: 'tool',
+                            status: 'running',
+                            title: text,
+                        });
+                        await turnOutput.setStatus('tool');
                     },
                     setWaitingInput: async (text) => {
                         shouldPersistTurnState = true;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { CanonAgent } from './canon-agent.js';
 export type { AgentContactsAPI, AgentUsersAPI } from './canon-agent.js';
-export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, parseTextApprovalReply, redactSecrets, } from '@canonmsg/core';
-export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, SessionRule, } from '@canonmsg/core';
+export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, redactSecrets, } from '@canonmsg/core';
+export type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalOutcomeMetadata, ApprovalReplyMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalResult, ApprovalRisk, CanonContact, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonResolveAdmissionResult, ContactAddedPayload, ContactCardPayload, ContactRemovedPayload, ContactSource, HostAdmissionActionCapabilities, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, RuntimeInputAnswers, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, SessionRule, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
 export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.js';
 export type { AnthropicImageBlock, AnthropicImageMimeType, MaterializeMediaOptions, MaterializedCanonAttachment, MaterializedCanonReplyContext, ReplyWithFileOptions, UploadMediaFileOptions, } from './media.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { CanonAgent } from './canon-agent.js';
-export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, parseTextApprovalReply, redactSecrets, } from '@canonmsg/core';
+export { ApprovalManager, buildApprovalOutcome, buildApprovalReply, buildApprovalRequest, CanonApiError, DEFAULT_APPROVAL_CONFIG, generateApprovalId, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, parseApprovalReplyMetadata, parseApprovalRequestMetadata, parseSessionRule, redactSecrets, } from '@canonmsg/core';
 export { SessionManager } from './session-manager.js';
 export { DEFAULT_MEDIA_CACHE_DIR, getCodexImagePath, getMessageAttachments, inferUploadMimeType, isAnthropicImageAttachment, materializeAttachment, materializeMessageMedia, materializeReplyContextMedia, resolveAttachmentMimeType, sendMediaFileMessage, toAnthropicImageBlock, uploadMediaFile, } from './media.js';

package/dist/runtime-card.d.ts

@@ -0,0 +1,29 @@
+import type { RuntimeCardNativeMetadata, RuntimeCardV1 } from '@canonmsg/core';
+import type { RuntimeCardRequest } from './types';
+/** Arguments passed to `CanonClient.createRuntimeCardRequest`. */
+export interface RuntimeCardCreateArgs {
+    conversationId: string;
+    card: RuntimeCardV1;
+    cardId: string;
+    expiresAt: number;
+    responseUserId?: string;
+    runtimeId?: string;
+    turnId?: string;
+    native?: RuntimeCardNativeMetadata;
+}
+/**
+ * Build the `createRuntimeCardRequest` payload shared by `sendCard` (display)
+ * and `requestCard` (interactive).
+ *
+ * `responseUserId` is OMITTED unless the developer supplied one, so the Canon
+ * backend infers a reachable responder (the owner when they are a conversation
+ * member, otherwise the sole other member). Pre-filling the owner here would
+ * break agent-to-user DMs where the owner is not a member of the conversation.
+ */
+export declare function buildRuntimeCardCreateArgs(input: {
+    request: RuntimeCardRequest;
+    conversationId: string;
+    cardId: string;
+    fallbackTurnId?: string;
+    expiresAtMs: number;
+}): RuntimeCardCreateArgs;

package/dist/runtime-card.js

@@ -0,0 +1,22 @@
+/**
+ * Build the `createRuntimeCardRequest` payload shared by `sendCard` (display)
+ * and `requestCard` (interactive).
+ *
+ * `responseUserId` is OMITTED unless the developer supplied one, so the Canon
+ * backend infers a reachable responder (the owner when they are a conversation
+ * member, otherwise the sole other member). Pre-filling the owner here would
+ * break agent-to-user DMs where the owner is not a member of the conversation.
+ */
+export function buildRuntimeCardCreateArgs(input) {
+    const { request, conversationId, cardId, fallbackTurnId, expiresAtMs } = input;
+    return {
+        conversationId,
+        cardId,
+        card: { ...request.card, cardId },
+        expiresAt: expiresAtMs,
+        ...(request.responseUserId ? { responseUserId: request.responseUserId } : {}),
+        ...(request.runtimeId ? { runtimeId: request.runtimeId } : {}),
+        turnId: request.turnId ?? fallbackTurnId,
+        ...(request.native ? { native: request.native } : {}),
+    };
+}

package/dist/turn-filter.d.ts

@@ -1,5 +1,5 @@
 import { type ResolvedAgentBehaviorPolicy, type CanonMessage } from '@canonmsg/core';
-export declare function shouldDispatchInboundMessage(conversationId: string, agentId: string, message: CanonMessage, options?: {
+export declare function shouldDispatchInboundMessage(_conversationId: string, agentId: string, message: CanonMessage, options?: {
     conversationType?: 'direct' | 'group' | 'unknown';
     behavior?: ResolvedAgentBehaviorPolicy | null;
     recentHumanCount?: number;

package/dist/turn-filter.js

@@ -1,35 +1,10 @@
-import { evaluateParticipationPolicy, normalizeTurnState, rtdbRead, shouldTriggerAgentTurn, } from '@canonmsg/core';
-function normalizeRuntimeTurnState(value) {
-    const turnState = normalizeTurnState(value);
-    if (turnState) {
-        return {
-            state: turnState.state,
-            ...(turnState.openedAt !== undefined ? { openedAt: turnState.openedAt } : {}),
-            ...(turnState.updatedAt !== undefined ? { updatedAt: turnState.updatedAt } : {}),
-            ...(turnState.turnUpdatedAt !== undefined ? { turnUpdatedAt: turnState.turnUpdatedAt } : {}),
-        };
-    }
-    return null;
-}
-export async function shouldDispatchInboundMessage(conversationId, agentId, message, options) {
+import { evaluateParticipationPolicy, shouldTriggerAgentTurn, } from '@canonmsg/core';
+export async function shouldDispatchInboundMessage(_conversationId, agentId, message, options) {
     if (message.senderId === agentId)
         return false;
-    let senderTurnState = null;
-    try {
-        const [turnState, sessionState] = await Promise.all([
-            rtdbRead(`/turn-state/${conversationId}/${message.senderId}`),
-            rtdbRead(`/session-state/${conversationId}/${message.senderId}`),
-        ]);
-        senderTurnState = normalizeRuntimeTurnState(turnState)
-            ?? normalizeRuntimeTurnState(sessionState);
-    }
-    catch {
-        senderTurnState = null;
-    }
     const triggerDecision = shouldTriggerAgentTurn({
         senderType: message.senderType,
         metadata: message.metadata,
-        senderTurnState,
     });
     if (!triggerDecision.allow)
         return false;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, SessionRule, ApprovalResult, } from '@canonmsg/core';
-import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputKind, RuntimeInputNativeMetadata, SendMessageOptions, SendContextualSelfContextInput, SessionConfig } from '@canonmsg/core';
+export type { AddMemberResult, AgentClientType, CanonGroupContext, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeDescriptor, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimePrimitiveId, CanonRuntimeProvenance, CanonMessage, CanonConversation, CanonReplyContext, CanonContact, CanonContactRequest, CanonResolveAdmissionResult, ContactAddedPayload, ContactRemovedPayload, ContactSource, AgentContext, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonSelfContext, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, SessionConfig, CreateConversationOptions, TurnLifecycleState, TurnOutputBlock, TurnOutputBlockInput, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SessionRule, ApprovalResult, } from '@canonmsg/core';
+import type { AddMemberResult, CanonGroupContext, CanonMessage, CanonConversation, CanonReplyContext, ContactCardPayload, CanonRuntimeActionDispatch, CanonRuntimePrimitiveId, CanonRuntimeProvenance, ApprovalNativeRequestMetadata, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalResult, ApprovalRisk, RuntimeInputChoice, RuntimeInputAnswers, RuntimeInputKind, RuntimeInputNativeMetadata, RuntimeInputQuestion, RuntimeCardNativeMetadata, RuntimeCardV1, SendMessageOptions, SendContextualSelfContextInput, SessionConfig, TurnOutputBlock, TurnOutputBlockInput } from '@canonmsg/core';
 import type { MaterializeMediaOptions, MaterializedCanonAttachment, ReplyWithFileOptions, UploadMediaFileOptions } from './media.js';
 export interface ProgressMessageOptions extends SendMessageOptions {
     /**
@@ -33,6 +33,10 @@ export interface TurnController {
     setStreaming: (text: string) => Promise<void>;
     appendDelta: (delta: string) => void;
     appendBlock: (block: string) => void;
+    addBlock: (block: TurnOutputBlockInput) => Promise<TurnOutputBlock>;
+    updateBlock: (id: string, patch: Partial<Omit<TurnOutputBlockInput, 'id' | 'sequence'>>) => Promise<TurnOutputBlock | null>;
+    completeBlock: (id: string, patch?: Partial<Omit<TurnOutputBlockInput, 'id' | 'sequence' | 'status'>>) => Promise<TurnOutputBlock | null>;
+    failBlock: (id: string, patch?: Partial<Omit<TurnOutputBlockInput, 'id' | 'sequence' | 'status'>>) => Promise<TurnOutputBlock | null>;
     replaceSnapshot: (text: string) => Promise<void>;
     flush: () => Promise<void>;
     clear: () => Promise<void>;
@@ -66,6 +70,7 @@ export interface RuntimeInputRequest {
     title: string;
     prompt: string;
     choices?: RuntimeInputChoice[];
+    questions?: RuntimeInputQuestion[];
     secretName?: string;
     sensitive?: boolean;
     runtimeId?: string;
@@ -77,8 +82,25 @@ export interface RuntimeInputRequest {
 export interface RuntimeInputResult {
     status: 'submitted' | 'cancelled' | 'timeout';
     value?: string;
+    answers?: RuntimeInputAnswers;
     inputId: string;
 }
+export interface RuntimeCardRequest {
+    card: RuntimeCardV1;
+    cardId?: string;
+    expiresAt?: string | number | Date;
+    responseUserId?: string;
+    timeoutMs?: number;
+    runtimeId?: string;
+    turnId?: string;
+    native?: RuntimeCardNativeMetadata;
+}
+export interface RuntimeCardResult {
+    status: 'submitted' | 'cancelled' | 'timeout' | 'displayed';
+    cardId: string;
+    actionId?: string;
+    values?: Record<string, unknown>;
+}
 export interface MessageHandlerContext {
     messages: CanonMessage[];
     history: CanonMessage[];
@@ -138,6 +160,19 @@ export interface MessageHandlerContext {
      * never persisted in Canon message metadata.
      */
     requestRuntimeInput: (request: RuntimeInputRequest) => Promise<RuntimeInputResult>;
+    /**
+     * Ask the agent owner to review/respond to a generic rich card. The visible
+     * card document is redacted for presentation; raw response values return
+     * only to the calling runtime through Canon's control path.
+     */
+    requestCard: (request: RuntimeCardRequest) => Promise<RuntimeCardResult>;
+    /**
+     * Post a fire-and-forget display/report card and return immediately with
+     * `{ status: 'displayed' }` — no waiting-input lifecycle. Use requestCard for
+     * cards that expect a response. (requestCard also auto-detects action-less
+     * cards and delegates here.)
+     */
+    sendCard: (request: RuntimeCardRequest) => Promise<RuntimeCardResult>;
     /** Canon-managed local media access for the current conversation. */
     media: {
         materialize: (message?: CanonMessage, options?: Omit<MaterializeMediaOptions, 'agentId' | 'conversationId' | 'messageId'>) => Promise<MaterializedCanonAttachment[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "1.7.0",
+  "version": "2.1.0",
   "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": "^0.24.0"
+    "@canonmsg/core": "^1.2.0"
   },
   "publishConfig": {
     "access": "public"