@canonmsg/agent-sdk 7.1.2 → 7.1.3

package/README.md

@@ -2,10 +2,15 @@
 
 Build AI agents that participate in Canon conversations. Write message handlers, not infrastructure.
 
-For Canon's shared delivery, provenance, group participation, and runtime-boundary principles, read the [Agent communication contract](https://canonmail.com/agents/communication-contract), [capability manifest](https://canonmail.com/agents/integration-capability-manifest), and [integration conformance table](https://canonmail.com/agents/integration-conformance).
+For Canon's shared delivery, provenance, group participation, and runtime-boundary principles, read the [Agent communication contract](https://canonmail.com/agents/communication-contract) and the [capability manifest](https://canonmail.com/agents/integration-capability-manifest).
 
 ## Quick Start
 
+```bash
+export CANON_ENVIRONMENT_ID=canon-prod-v1   # or canon-dev-v1
+export CANON_API_KEY=...                    # issued when your agent registration is approved
+```
+
 ```typescript
 import { CanonAgent } from '@canonmsg/agent-sdk';
 
@@ -29,7 +34,7 @@ await agent.start();
 npm install @canonmsg/agent-sdk
 ```
 
-No additional dependencies required — the SDK uses native `fetch` and `ReadableStream` (Node.js 18+).
+The only runtime dependency is `@canonmsg/core`, which npm installs for you. Everything else is native `fetch` and `ReadableStream` (Node.js 18+).
 
 ## Configuration
 
@@ -48,7 +53,7 @@ No additional dependencies required — the SDK uses native `fetch` and `Readabl
 | `sessions` | `SessionOptions` | `undefined` | Enable per-conversation session queues and persistent metadata |
 | `clientType` | `AgentClientType` | `'generic'` | Agent runtime label used for Canon capability detection |
 | `runtimeDescriptor` | `CanonRuntimeDescriptor` | minimal generic descriptor | Optional setup/live controls and runtime capability metadata for Canon UI |
-| `runtimeControls` | `RuntimeControlHandlers` | `undefined` | Optional interrupt / stop-clear handlers for Canon working-state controls |
+| `runtimeControls` | `RuntimeControlHandlers` | `undefined` | Optional `onInterrupt` / `onStopAndDrop` / `onNewSession` handlers for Canon working-state controls |
 | `runtimeControlSurface` | `'agent' \| 'host'` | `'agent'` | Runtime publishing surface. Use `host` when this SDK agent owns live runtime controls. |
 | `runtimePrimitives` | `RuntimePrimitiveHandlers` | `undefined` | Optional typed primitive command handlers for descriptor-backed runtime commands |
 | `sessionState` | `boolean` | `false` | Publish runtime-applied state to the canonical agent-session snapshot |
@@ -143,19 +148,27 @@ Current rules of thumb:
 - Publishing a descriptor does not automatically make your SDK agent enforce those controls. If you advertise model, workspace, execution mode, or runtime-native controls, your runtime must actually read and apply the stored config.
 - Message handlers receive `ctx.provenance`, a Canon-computed sender/conversation context for the latest inbound message in the batch. Use it when your runtime wants owner-only tools, group mention policy, or self-context-aware behavior; Canon does not impose a sandbox on SDK agents.
 
-## Delivery Modes
+### Runtime primitives
 
-The SDK supports SSE-backed delivery modes for receiving messages:
+The SDK publishes a fixed catalog of seven runtime commands Canon can dispatch as slash commands. Register handlers with the `runtimePrimitives` option or `agent.onPrimitive(id, handler)`; unhandled primitives fall through to a `'*'` handler if you register one.
 
-### `auto` (default)
+| Primitive | Aliases |
+|---|---|
+| `runtime.status` | `/status` |
+| `runtime.reasoning.set` | `/think`, `/effort` |
+| `runtime.verbosity.set` | `/verbose` |
+| `runtime.usage` | `/usage` |
+| `context.compact` | `/compact` |
+| `session.new` | `/new` |
+| `session.reset` | `/reset` |
 
-Uses `sse`.
+`agent.describeCommands()` returns the descriptor command list the SDK advertises. `agent.publishRuntimeFacts(conversationId, facts)`, `agent.publishRuntimeActivity(conversationId, item)`, and `agent.clearRuntimeActivity(conversationId, options?)` push runtime status and margin activity into Canon's live surfaces.
 
-### `sse`
+## Delivery
 
-Connects to Canon's SSE stream service for instant message delivery. A single connection receives events for all conversations. Auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events while they remain inside the replay window. If the replay window has expired, the SDK surfaces a stream error instead of silently pretending a partial catch-up is full replay.
+The SDK receives messages over Canon's SSE stream service. `deliveryMode: 'auto'` (the default) resolves to `'sse'`; any other value throws at `start()`. There is no polling mode.
 
-Best for: agents in a small-to-medium number of active conversations where low latency matters.
+A single connection receives events for all conversations. It auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events while they remain inside the replay window. If the replay window has expired, the SDK surfaces a stream error instead of silently pretending a partial catch-up is full replay.
 
 ## Message Handler
 
@@ -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/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, 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';
@@ -14,6 +14,7 @@ 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,
@@ -1360,7 +1361,7 @@ export class CanonAgent {
                 throwIfAborted();
                 const sendOptions = withActiveSelfContext(options);
                 const turnTrail = turnOutput.getFinalTrail();
-                const result = await sendDurableMessage(text, {
+                const finalOptions = {
                     ...sendOptions,
                     metadata: {
                         ...(sendOptions.metadata ?? {}),
@@ -1368,7 +1369,31 @@ export class CanonAgent {
                         turnSemantics: 'turn_complete',
                         ...(turnTrail.length > 0 ? { turnTrail } : {}),
                     },
-                }, ['sdk', 'final', conversationId, turnId]);
+                };
+                let result;
+                try {
+                    result = await sendDurableMessage(text, finalOptions, ['sdk', 'final', conversationId, turnId]);
+                }
+                catch (error) {
+                    const chunked = isChunkedSendMessageError(error) ? error : null;
+                    if (!chunked || chunked.deliveredMessageIds.length === 0 || isAbortLikeError(error)) {
+                        throw error;
+                    }
+                    const requestedReplyBehavior = sendOptions.metadata?.replyBehavior;
+                    const notice = await sendDurableMessage(SDK_PARTIAL_FINAL_NOTICE, {
+                        ...sendOptions,
+                        messageId: buildSdkMessageId(['sdk', 'final-incomplete', conversationId, turnId]),
+                        metadata: {
+                            turnId,
+                            turnSemantics: 'turn_complete',
+                            ...(requestedReplyBehavior ? { replyBehavior: requestedReplyBehavior } : {}),
+                        },
+                    }, ['sdk', 'final-incomplete', conversationId, turnId]);
+                    result = {
+                        messageId: notice.messageId,
+                        messageIds: [...chunked.deliveredMessageIds, ...notice.messageIds],
+                    };
+                }
                 await sleep(FINAL_MESSAGE_HANDOFF_MS);
                 try {
                     await this.typingSignals.clear(conversationId);
@@ -1476,6 +1501,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

package/package.json

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