@canonmsg/agent-sdk 11.0.0 → 11.0.1

package/README.md

@@ -42,7 +42,7 @@ Replicated or ephemeral cloud deployments must inject an operator-owned endpoint
 
 Existing conversations require the rollout tool's reconciled history baseline before agent execution. The immutable recovery cutover permits later room creations and new admissions to receive their bounded history automatically. Missing baselines appear as explicit recovery errors; startup never treats all old messages as new tasks.
 
-Runtime heartbeats and Firebase token refresh come from Core, using the same machinery as the integrated plugins. The SDK adds handler dispatch and lifecycle wiring. Concurrent `start()` calls share one startup; failed startup can be retried, and `stop()` prevents an unfinished startup from reconnecting afterward. Heartbeat failures are reported and later heartbeats retry. This does not guarantee cancellation of arbitrary application work already running in a handler.
+Runtime heartbeats come from Core through the shared endpoint, using the same machinery as the integrated plugins. No separate runtime Firebase token exchange is needed. The SDK adds handler dispatch and lifecycle wiring. Concurrent `start()` calls share one startup; failed startup can be retried, and `stop()` prevents an unfinished startup from reconnecting afterward. Heartbeat failures are reported and later heartbeats retry. This does not guarantee cancellation of arbitrary application work already running in a handler.
 
 ## Configuration
 
@@ -52,8 +52,8 @@ Runtime heartbeats and Firebase token refresh come from Core, using the same mac
 | `environmentId` | `string` | **required** | Canon trust domain shared by API, stream, RTDB, and future cryptographic state |
 | `baseUrl` | `string` | Environment default | Override the API base URL when the selected environment has no packaged default |
 | `streamUrl` | `string` | Environment default | Override the SSE stream URL when the selected environment has no packaged default |
-| `rtdbUrl` | `string` | Environment default | Override the Realtime Database URL for runtime state |
-| `firebaseApiKey` | `string` | Environment default | Override the public Firebase web API key used for RTDB token exchange |
+| `rtdbUrl` | `string` | Environment default | Legacy connection option; runtime state uses the shared endpoint |
+| `firebaseApiKey` | `string` | Environment default | Legacy connection option; no runtime Firebase token exchange |
 | `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) |
@@ -129,15 +129,15 @@ The SDK provides a standard catalog of seven runtime primitives. It advertises a
 
 ## Delivery
 
-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.
+The SDK receives messages through the shared endpoint's SSE connection. `deliveryMode: 'auto'` (the default) resolves to `'sse'`; any other value throws at `start()`. There is no polling mode.
 
-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.
+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 that expiry; the shared endpoint owns durable synchronization and admission-checked recovery beyond the live replay window. Adapters must not add a second history dispatch loop.
 
 The SDK publishes runtime heartbeats every 30 seconds while SSE is connected and clears its runtime freshness on disconnect. Controls remain limited to the handlers and descriptor your runtime actually supports.
 
 Handler reply helpers carry the inbound SSE event's reply authority automatically. Outbound-closed agents need that authority for non-owner/group replies; it expires 15 minutes after the source message was created. Delayed processing or fetching history does not renew it. See [Replies and polling](https://canonmail.com/agents/contracts#replies-and-polling) for the current limits.
 
-With `autoMarkRead: true`, the SDK marks the conversation read after successful handler completion. The current REST endpoint advances to server time, so messages arriving during the handler can also be marked read before they are handled. `ctx.markAsRead()` uses the same endpoint. Keep your processing checkpoint separate from this chat read receipt; the API currently has no exact-batch read cursor.
+With `autoMarkRead: true`, the SDK marks the conversation read after successful handler completion. The current `mark_read` action advances to server time, so messages arriving during the handler can also be marked read before they are handled. `ctx.markAsRead()` uses the same endpoint. Keep your processing checkpoint separate from this chat read receipt; the API currently has no exact-batch read cursor.
 
 ## Message Handler
 
@@ -150,20 +150,20 @@ The `message` event handler receives a context object with:
 | `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 |
+| `groupContext` | `CanonGroupContext \| undefined` | Participant context based on the current conversation roster |
 | `replyFinal` | `(text: string, options?) => Promise<{ messageId: string; messageIds: string[] }>` | Send the durable final reply for a turn |
 | `replyProgress` | `(text: string, options?) => Promise<{ turnId: string; durable: boolean; messageId: string \| null; messageIds?: string[] }>` | Update the live turn progress; add `durable: true` to also persist it |
 | `deleteMessage` | `(messageId: string) => Promise<void>` | Soft-delete a message sent by this agent |
 | `markAsRead` | `() => Promise<void>` | Advance this agent's read cursor for the conversation |
-| `leave` | `() => Promise<void>` | Leave the current group conversation |
+| `leave` | `() => Promise<void>` | Leave the current conversation |
 | `react` | `(messageId, emoji) => Promise<void>` | Toggle an emoji reaction |
-| `addMember` / `removeMember` | functions | Manage group members when the agent has permission |
-| `communicate` | function | Message an existing conversation, start a direct conversation, create a group, forward an exact message, share a contact, or manage group members |
+| `addMember` / `removeMember` | functions | Manage participants when the agent has permission |
+| `communicate` | function | Message an existing conversation, start a conversation, create a conversation with several participants, forward an exact message, share a contact, or manage participants |
 | `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 |
-| `turnContext` | `CanonTurnContextV2` | Compact structured turn context; fields are intentionally shaped by conversation type and sender type |
+| `turnContext` | `CanonTurnContextV2` | Compact structured turn context; fields reflect the current roster, sender and participation policy |
 | `requestedTurnMode` | `string \| null` | Runtime turn mode the sender requested for this inbound turn, if any |
 | `turnVerbosity` | `'verbose' \| 'quiet'` | Resolved emission mode for this turn — see [Turn verbosity](#turn-verbosity). Fixed for the whole turn |
 | `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 |
@@ -177,7 +177,7 @@ The `message` event handler receives a context object with:
 
 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. `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.
+`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. Two-person human-agent turns stay sparse; agent-agent and larger-roster turns include extra loop/participation context when it matters. Canon provides trusted provenance; it does not impose an SDK-agent sandbox.
 
 ## Events
 
@@ -457,25 +457,27 @@ It governs teardown only. Calling `replyFinal()` as well is two explicit decisio
 
 ## Turn verbosity
 
-By default an agent is **quiet in group conversations and verbose in direct chats**. A quiet turn shows the thinking indicator and the answer, and nothing in between.
+By default an agent is **quiet with more than two participants and verbose with two**, based on the refreshed roster. A quiet turn shows the thinking indicator and the answer, and nothing in between.
 
 ```ts
 const agent = new CanonAgent({
   apiKey: process.env.CANON_API_KEY!,
   environmentId: 'canon-prod-v1',
   turnVerbosity: 'verbose',              // scalar: applies everywhere
-  // turnVerbosity: { group: 'verbose' }, // object: override one conversation type
+  // turnVerbosity: { group: 'verbose' }, // object: override one roster policy scope
 });
 ```
 
 | Value | Effect |
 |---|---|
-| `'auto'` (default, same as omitting the option) | Verbose in direct chats, quiet in groups |
+| `'auto'` (default, same as omitting the option) | Verbose with two participants, quiet with more than two |
 | `'verbose'` | Live turn state and the margin activity trail, everywhere |
 | `'quiet'` | Thinking indicator and the final message only, everywhere |
-| `{ direct?, group? }` | Overrides the named conversation type; the unnamed one keeps its default |
+| `{ direct?, group? }` | Compatibility keys for the two-person/larger-roster scopes; the unnamed scope keeps its default |
 
-A conversation whose type Canon could not determine falls back to verbose, never to silence.
+Adding or removing participants can change the default on the next turn. The SDK
+holds verbosity fixed within a turn. Legacy type is a fallback when roster data
+is unavailable; an unknown scope defaults to verbose, never to silence.
 
 **Quiet suppresses**: every `/streaming` publication — the `'Thinking...'` seed and its keepalive, `turn.setThinking/setStreaming/setTool`, `turn.appendDelta`/`appendBlock`/segment updates, `turn.addBlock` and friends, and the live half of `replyProgress()` — plus the `turnTrail` on `replyFinal()` and `media.replyWithFile()`. Every one of those calls still works and still returns normally; only the publication is dropped.
 

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createRuntimeHeartbeat, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, isPendingCanonOperation, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reportNoReplyOutcome, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, resolveTurnVerbosity, resolveConversationPolicyScope, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
+import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createRuntimeHeartbeat, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, isPendingCanonOperation, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reportNoReplyOutcome, hydrateCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, resolveTurnVerbosity, resolveConversationPolicyScope, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
 import { createHash, randomUUID } from 'node:crypto';
 import { Debouncer } from './debouncer.js';
 import { DEFAULT_RUNTIME_INPUT_TIMEOUT_MS, RUNTIME_INPUT_ID_PATTERN, buildRuntimeCardCreateArgs, normalizeResponseUserId, resolveRuntimeCardRouting, } from './runtime-card.js';
@@ -1605,7 +1605,9 @@ export class CanonAgent {
                 ? normalizeResponseUserId(latestMessage.senderId)
                 : undefined;
             let replyContext = latestMessage
-                ? resolveCanonReplyContext({ message: latestMessage, messages: history })
+                ? await hydrateCanonReplyContext({
+                    client: this.apiClient, conversationId, message: latestMessage, messages: history,
+                })
                 : null;
             const resolvedActiveSelfContextId = resolveMessageActiveSelfContextId({
                 messageId: latestMessage?.id,

package/package.json

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