@canonmsg/agent-sdk 7.1.2 → 8.0.0

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
 
@@ -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):

package/dist/auth.d.ts

@@ -1,11 +1,8 @@
 import { CanonClient } from '@canonmsg/core';
 export declare class AuthManager {
     private apiClient;
-    private token;
-    private agentId;
     private expiresAt;
     private refreshTimer;
-    private onRefreshCallback;
     private refreshRetryCount;
     constructor(apiClient: CanonClient);
     authenticate(): Promise<{
@@ -15,8 +12,5 @@ export declare class AuthManager {
     private scheduleRefresh;
     /** Retry with exponential backoff (30s -> 60s -> 120s -> 240s cap, max 10 attempts) */
     private scheduleRetry;
-    setOnRefresh(cb: (token: string) => void): void;
-    getToken(): string | null;
-    getAgentId(): string | null;
     destroy(): void;
 }

package/dist/auth.js

@@ -3,19 +3,14 @@ const BASE_RETRY_MS = 30_000;
 const MAX_RETRY_BACKOFF_MS = 240_000;
 export class AuthManager {
     apiClient;
-    token = null;
-    agentId = null;
     expiresAt = 0;
     refreshTimer = null;
-    onRefreshCallback = null;
     refreshRetryCount = 0;
     constructor(apiClient) {
         this.apiClient = apiClient;
     }
     async authenticate() {
         const result = await this.apiClient.getAuthToken();
-        this.token = result.token;
-        this.agentId = result.agentId;
         this.expiresAt = new Date(result.expiresAt).getTime();
         this.refreshRetryCount = 0;
         this.scheduleRefresh();
@@ -29,12 +24,9 @@ export class AuthManager {
         this.refreshTimer = setTimeout(async () => {
             try {
                 const result = await this.apiClient.getAuthToken();
-                this.token = result.token;
                 this.expiresAt = new Date(result.expiresAt).getTime();
                 this.refreshRetryCount = 0;
                 this.scheduleRefresh();
-                if (this.onRefreshCallback)
-                    this.onRefreshCallback(result.token);
             }
             catch (err) {
                 console.error('[canon-sdk] Token refresh failed:', err);
@@ -53,21 +45,10 @@ export class AuthManager {
         console.warn(`[canon-sdk] Retrying token refresh in ${backoff / 1000}s (attempt ${this.refreshRetryCount}/${MAX_REFRESH_RETRIES})`);
         this.refreshTimer = setTimeout(() => this.scheduleRefresh(), backoff);
     }
-    setOnRefresh(cb) {
-        this.onRefreshCallback = cb;
-    }
-    getToken() {
-        return this.token;
-    }
-    getAgentId() {
-        return this.agentId;
-    }
     destroy() {
         if (this.refreshTimer) {
             clearTimeout(this.refreshTimer);
             this.refreshTimer = null;
         }
-        this.token = null;
-        this.agentId = null;
     }
 }

package/dist/canon-agent.d.ts

@@ -103,7 +103,7 @@ export declare class CanonAgent {
     on(event: 'callStarted', handler: (payload: VoiceSessionEventPayload) => void | Promise<void>): void;
     on(event: 'callEnded', handler: (payload: VoiceSessionEventPayload) => void | Promise<void>): void;
     onPrimitive(primitive: CanonRuntimePrimitiveId | '*', handler: RuntimePrimitiveHandler): void;
-    describeCommands(_provider?: string): ReadonlyArray<CanonRuntimeCommandDescriptor>;
+    describeCommands(): ReadonlyArray<CanonRuntimeCommandDescriptor>;
     publishRuntimeFacts(conversationId: string, facts: ReadonlyArray<CanonRuntimeFact>): Promise<void>;
     publishRuntimeActivity(conversationId: string, item: CanonRuntimeActivityItem): Promise<void>;
     clearRuntimeActivity(conversationId: string, options?: ClearRuntimeActivityOptions): Promise<void>;

package/dist/canon-agent.js

@@ -1,19 +1,18 @@
-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 { 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';
-import { buildRuntimeCardCreateArgs } from './runtime-card.js';
+import { DEFAULT_RUNTIME_INPUT_TIMEOUT_MS, RUNTIME_INPUT_ID_PATTERN, buildRuntimeCardCreateArgs, normalizeResponseUserId, resolveRuntimeCardRouting, } 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;
 const RUNTIME_CONTROL_POLL_INTERVAL_MS = 2_000;
 const RUNTIME_PRIMITIVE_DEDUPE_TTL_MS = 5 * 60 * 1000;
 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,
@@ -162,16 +161,6 @@ 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 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
@@ -522,7 +511,7 @@ export class CanonAgent {
         }
         void this.publishAgentRuntime().catch(() => { });
     }
-    describeCommands(_provider) {
+    describeCommands() {
         return this.buildRuntimeDescriptor().commands ?? [];
     }
     async publishRuntimeFacts(conversationId, facts) {
@@ -689,7 +678,7 @@ export class CanonAgent {
         // 4. Start delivery
         const { RealtimeManager } = await import('./realtime.js');
         this.voiceEventsEnabled = Boolean(this.callStartedHandler || this.callEndedHandler);
-        const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, this.apiClient, { enableVoiceEvents: this.voiceEventsEnabled });
+        const rtm = new RealtimeManager(this.options.apiKey, this.debouncer, agentId, this.options.streamUrl, { enableVoiceEvents: this.voiceEventsEnabled });
         if (this.voiceEventsEnabled) {
             rtm.setCallHandlers({
                 onCallStarted: (payload) => {
@@ -1207,11 +1196,15 @@ export class CanonAgent {
     createRuntimeStatePublisher() {
         if (!this.agentId)
             return null;
+        // start() assigns rtdbHandle before agentId, so this can only be null
+        // when the agent has not started — same condition as the guard above.
+        if (!this.rtdbHandle)
+            return null;
         return createRuntimeStatePublisher({
             agentId: this.agentId,
             clientType: this.options.clientType ?? 'generic',
             hostMode: this.options.runtimeControlSurface === 'host',
-            ...(this.rtdbHandle ? { rtdb: this.rtdbHandle } : {}),
+            rtdb: this.rtdbHandle,
         });
     }
     requireRuntimeStatePublisher() {
@@ -1360,7 +1353,7 @@ export class CanonAgent {
                 throwIfAborted();
                 const sendOptions = withActiveSelfContext(options);
                 const turnTrail = turnOutput.getFinalTrail();
-                const result = await sendDurableMessage(text, {
+                const finalOptions = {
                     ...sendOptions,
                     metadata: {
                         ...(sendOptions.metadata ?? {}),
@@ -1368,7 +1361,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);
@@ -1476,6 +1493,8 @@ export class CanonAgent {
                     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
@@ -1539,7 +1558,7 @@ export class CanonAgent {
                 agent,
                 membershipChange,
             });
-            const participationHistory = buildParticipationHistorySnapshot(history, agent.agentId);
+            const participationHistory = buildParticipationHistorySnapshot(history);
             const turnContext = buildCanonTurnContextV2({
                 content: latestMessage ? renderCanonHostInboundContent(latestMessage) : '[Empty message]',
                 conversationId,
@@ -1667,7 +1686,6 @@ export class CanonAgent {
                 const inputId = safeRuntimeInputId(request.inputId, request.kind);
                 const timeoutMs = Math.max(1_000, request.timeoutMs ?? DEFAULT_RUNTIME_INPUT_TIMEOUT_MS);
                 const expiresAtMs = Date.now() + timeoutMs;
-                const expiresAt = new Date(expiresAtMs).toISOString();
                 let result = { status: 'timeout', inputId };
                 let requestCreated = false;
                 const ownerOnly = request.kind === 'secret'
@@ -1772,23 +1790,10 @@ export class CanonAgent {
             };
             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;
-                const responseUserId = normalizeResponseUserId(request.responseUserId)
-                    ?? triggeringHumanId;
-                const routedRequest = responseUserId
-                    ? { ...request, responseUserId }
-                    : request;
+                const { cardId, expiresAtMs, routedRequest } = resolveRuntimeCardRouting({
+                    request,
+                    triggeringHumanId,
+                });
                 // 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({
@@ -1817,23 +1822,10 @@ export class CanonAgent {
                     && 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;
-                const responseUserId = normalizeResponseUserId(request.responseUserId)
-                    ?? triggeringHumanId;
-                const routedRequest = responseUserId
-                    ? { ...request, responseUserId }
-                    : request;
+                const { cardId, expiresAtMs, routedRequest } = resolveRuntimeCardRouting({
+                    request,
+                    triggeringHumanId,
+                });
                 let result = { status: 'timeout', cardId };
                 let requestCreated = false;
                 let requestResolved = false;

package/dist/realtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentContext, type CanonClient, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
+import { type AgentContext, type ContactAddedPayload, type ContactApprovedPayload, type ContactRemovedPayload, type ContactRequestPayload, type ConversationUpdatedPayload, type MessageUpdatedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
@@ -8,9 +8,7 @@ import { Debouncer } from './debouncer.js';
  */
 export declare class RealtimeManager {
     private debouncer;
-    private agentId;
     private stream;
-    private running;
     /** Recent inbound message IDs (`conversationId:messageId`) for cross-flush dedupe. */
     private readonly recentInboundMessageIds;
     private lastSseErrorKey;
@@ -28,7 +26,7 @@ export declare class RealtimeManager {
     private onDisconnected;
     private onCallStarted;
     private onCallEnded;
-    constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, apiClient?: CanonClient, options?: {
+    constructor(apiKey: string, debouncer: Debouncer, agentId: string, streamUrl?: string, options?: {
         enableVoiceEvents?: boolean;
     });
     private hasSeenInboundMessage;

package/dist/realtime.js

@@ -1,12 +1,6 @@
 import { CanonStream, } from '@canonmsg/core';
 const RECENT_INBOUND_TTL_MS = 30 * 60 * 1000;
 const MAX_RECENT_INBOUND_MESSAGE_IDS = 5000;
-function messageCreatedAtMs(createdAt) {
-    if (!createdAt)
-        return 0;
-    const parsed = new Date(createdAt).getTime();
-    return Number.isFinite(parsed) ? parsed : 0;
-}
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
  * - Debouncer integration (message batching)
@@ -15,9 +9,7 @@ function messageCreatedAtMs(createdAt) {
  */
 export class RealtimeManager {
     debouncer;
-    agentId;
     stream;
-    running = false;
     /** Recent inbound message IDs (`conversationId:messageId`) for cross-flush dedupe. */
     recentInboundMessageIds = new Map();
     lastSseErrorKey = null;
@@ -35,9 +27,8 @@ export class RealtimeManager {
     onDisconnected = null;
     onCallStarted = null;
     onCallEnded = null;
-    constructor(apiKey, debouncer, agentId, streamUrl, apiClient, options) {
+    constructor(apiKey, debouncer, agentId, streamUrl, options) {
         this.debouncer = debouncer;
-        this.agentId = agentId;
         this.stream = new CanonStream({
             apiKey,
             agentId,
@@ -64,7 +55,7 @@ export class RealtimeManager {
                     if (this.hasSeenInboundMessage(payload.conversationId, payload.message.id)) {
                         return;
                     }
-                    this.recordSeenInboundMessage(payload.conversationId, payload.message.id, messageCreatedAtMs(payload.message.createdAt));
+                    this.recordSeenInboundMessage(payload.conversationId, payload.message.id);
                     if (payload.turnDispatch && payload.turnDispatch.kind !== 'run_turn') {
                         console.error(`[canon-sdk] Ignoring server-dispatched observe-only message in ${payload.conversationId}: ${payload.turnDispatch.reason}`);
                         return;
@@ -140,10 +131,9 @@ export class RealtimeManager {
     hasSeenInboundMessage(conversationId, messageId) {
         return this.recentInboundMessageIds.has(`${conversationId}:${messageId}`);
     }
-    recordSeenInboundMessage(conversationId, messageId, createdAtMs) {
+    recordSeenInboundMessage(conversationId, messageId) {
         const now = Date.now();
         this.recentInboundMessageIds.set(`${conversationId}:${messageId}`, now);
-        void createdAtMs;
         this.pruneRecentInboundMessageIds(now);
     }
     pruneRecentInboundMessageIds(now = Date.now()) {
@@ -205,11 +195,9 @@ export class RealtimeManager {
         this.onCallEnded = handlers.onCallEnded ?? null;
     }
     async start() {
-        this.running = true;
         await this.stream.start();
     }
     stop() {
-        this.running = false;
         this.stream.stop();
     }
 }

package/dist/runtime-card.d.ts

@@ -1,5 +1,24 @@
 import type { RuntimeCardNativeMetadata, RuntimeCardV1 } from '@canonmsg/core';
 import type { RuntimeCardRequest } from './types';
+export declare const DEFAULT_RUNTIME_INPUT_TIMEOUT_MS: number;
+export declare const RUNTIME_INPUT_ID_PATTERN: RegExp;
+export declare function normalizeResponseUserId(value: string | undefined): string | undefined;
+/**
+ * Resolve the routing prelude shared verbatim by `sendCard` (display) and
+ * `requestCard` (interactive): the sanitized card id, the effective expiry,
+ * and the request with an explicit responder folded in.
+ *
+ * `triggeringHumanId` must be passed in by the caller rather than re-derived
+ * here — it is captured from the enclosing message handler's scope.
+ */
+export declare function resolveRuntimeCardRouting(input: {
+    request: RuntimeCardRequest;
+    triggeringHumanId?: string;
+}): {
+    cardId: string;
+    expiresAtMs: number;
+    routedRequest: RuntimeCardRequest;
+};
 /** Arguments passed to `CanonClient.createRuntimeCardRequest`. */
 export interface RuntimeCardCreateArgs {
     conversationId: string;

package/dist/runtime-card.js

@@ -1,3 +1,45 @@
+import { randomUUID } from 'node:crypto';
+export const DEFAULT_RUNTIME_INPUT_TIMEOUT_MS = 5 * 60_000;
+export const RUNTIME_INPUT_ID_PATTERN = /^[A-Za-z0-9_.:-]{1,160}$/;
+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()}`;
+}
+export function normalizeResponseUserId(value) {
+    return value?.trim() || undefined;
+}
+/**
+ * Resolve the routing prelude shared verbatim by `sendCard` (display) and
+ * `requestCard` (interactive): the sanitized card id, the effective expiry,
+ * and the request with an explicit responder folded in.
+ *
+ * `triggeringHumanId` must be passed in by the caller rather than re-derived
+ * here — it is captured from the enclosing message handler's scope.
+ */
+export function resolveRuntimeCardRouting(input) {
+    const { request, triggeringHumanId } = input;
+    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;
+    const responseUserId = normalizeResponseUserId(request.responseUserId)
+        ?? triggeringHumanId;
+    const routedRequest = responseUserId
+        ? { ...request, responseUserId }
+        : request;
+    return { cardId, expiresAtMs, routedRequest };
+}
 /**
  * Build the `createRuntimeCardRequest` payload shared by `sendCard` (display)
  * and `requestCard` (interactive).

package/dist/session-manager.d.ts

@@ -59,8 +59,6 @@ export declare class SessionManager {
     seedHistory(conversationId: string, history: CanonMessage[]): void;
     /** Remove idle sessions */
     private sweep;
-    /** Number of active sessions */
-    get sessionCount(): number;
     /** Number of queued batches waiting behind the active turn for this conversation. */
     getQueueDepth(conversationId: string): number;
     /** Drop one not-yet-running queued message for a conversation. */

package/dist/session-manager.js

@@ -191,10 +191,6 @@ export class SessionManager {
             }
         }
     }
-    /** Number of active sessions */
-    get sessionCount() {
-        return this.sessions.size;
-    }
     /** Number of queued batches waiting behind the active turn for this conversation. */
     getQueueDepth(conversationId) {
         return this.queues.get(conversationId)?.length ?? 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/agent-sdk",
-  "version": "7.1.2",
+  "version": "8.0.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": "^8.1.0"
+    "@canonmsg/core": "^9.0.0"
   },
   "publishConfig": {
     "access": "public"

package/dist/policy-history.d.ts

@@ -1,10 +0,0 @@
-import { type CanonMessage, type ParticipationHistorySnapshot } from '@canonmsg/core';
-export type { ParticipationHistorySnapshot } from '@canonmsg/core';
-/**
- * Builds message-specific participation history snapshots for backlog delivery.
- *
- * `messages` must be ordered newest-first, matching Canon's `getMessages()`
- * API. Each snapshot is computed from older history only, never from the
- * target message itself or newer messages that had not occurred yet.
- */
-export declare function buildParticipationHistorySnapshots(messages: CanonMessage[], agentId: string): Map<string, ParticipationHistorySnapshot>;

package/dist/policy-history.js

@@ -1,11 +0,0 @@
-import { buildParticipationHistorySnapshots as buildSharedParticipationHistorySnapshots, } from '@canonmsg/core';
-/**
- * Builds message-specific participation history snapshots for backlog delivery.
- *
- * `messages` must be ordered newest-first, matching Canon's `getMessages()`
- * API. Each snapshot is computed from older history only, never from the
- * target message itself or newer messages that had not occurred yet.
- */
-export function buildParticipationHistorySnapshots(messages, agentId) {
-    return buildSharedParticipationHistorySnapshots(messages, agentId);
-}

package/dist/turn-filter.d.ts

@@ -1,9 +0,0 @@
-import { type ResolvedAgentBehaviorPolicy, type CanonMessage, type MessageCreatedPayload } from '@canonmsg/core';
-export declare function shouldDispatchInboundMessage(_conversationId: string, agentId: string, message: CanonMessage, options?: {
-    conversationType?: 'direct' | 'group' | 'unknown';
-    behavior?: ResolvedAgentBehaviorPolicy | null;
-    recentHumanCount?: number;
-    consecutiveAgentTurns?: number;
-    currentAgentStreakStartedByHuman?: boolean;
-    turnDispatch?: MessageCreatedPayload['turnDispatch'];
-}): Promise<boolean>;

package/dist/turn-filter.js

@@ -1,25 +0,0 @@
-import { evaluateParticipationPolicy, shouldTriggerAgentTurn, } from '@canonmsg/core';
-export async function shouldDispatchInboundMessage(_conversationId, agentId, message, options) {
-    if (message.senderId === agentId)
-        return false;
-    if (options?.turnDispatch) {
-        return options.turnDispatch.kind === 'run_turn';
-    }
-    const triggerDecision = shouldTriggerAgentTurn({
-        senderType: message.senderType,
-        metadata: message.metadata,
-    });
-    if (!triggerDecision.allow)
-        return false;
-    if (!options?.behavior)
-        return true;
-    return evaluateParticipationPolicy(options.behavior, {
-        conversationType: options.conversationType ?? 'unknown',
-        senderType: message.senderType,
-        isOwner: message.isOwner,
-        mentionedAgent: Array.isArray(message.mentions) && message.mentions.includes(agentId),
-        recentHumanCount: options.recentHumanCount,
-        consecutiveAgentTurns: options.consecutiveAgentTurns,
-        currentAgentStreakStartedByHuman: options.currentAgentStreakStartedByHuman,
-    }).allow;
-}