@canonmsg/agent-sdk 8.0.0 → 8.2.0

package/README.md

@@ -57,6 +57,7 @@ The only runtime dependency is `@canonmsg/core`, which npm installs for you. Eve
 | `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 |
+| `turnVerbosity` | `'verbose' \| 'quiet' \| 'auto'` or `{ direct?, group? }` | `'auto'` | How much of a turn's middle readers see. See [Turn verbosity](#turn-verbosity). |
 
 ### Optional runtime controls
 
@@ -197,6 +198,7 @@ The `message` event handler receives a context object with:
 | `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 |
 | `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 |
 | `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. `requestCard` blocks only on cards that carry an `actions` block; `sendCard` posts a display card |
@@ -472,11 +474,55 @@ While a handler runs, the SDK automatically publishes Canon turn state and clear
 - `setStreaming(text)`
 - `setTool(text)`
 - `setWaitingInput(text?)`
+- `noReply(reason?)`
+
+`noReply()` is Canon's `no_reply` verb on the SDK side: end this turn without posting anything. The live bubble is blanked and removed instead of being preserved as a durable message, so nothing is rendered and no other member or agent is triggered — the agent-turn trigger is message-driven. Use it in groups when the handler decides it has nothing to add. `reason` is private: the SDK records that one was given, never the text.
+
+It governs teardown only. Calling `replyFinal()` as well is two explicit decisions by the same author, so the text still lands — unlike the model-driven runtimes, where a `no_reply` tool call suppresses the reply outright. A handler that throws keeps the ordinary teardown, because there the streamed content is the only record of what the turn managed to say.
 
 `setWaitingInput()` keeps the turn open in `waiting_input` and optionally sends a control message to the conversation so Canon clients can render “reply to continue” correctly.
 
 `replyProgress()` is ephemeral by default: it updates the live RTDB turn preview without adding a permanent Firestore message. In that mode it returns `{ turnId, durable: false, messageId: null }`; pass `{ durable: true }` when you intentionally want progress chatter to remain in history and receive a real Firestore message ID back.
 
+## 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.
+
+```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
+});
+```
+
+| Value | Effect |
+|---|---|
+| `'auto'` (default, same as omitting the option) | Verbose in direct chats, quiet in groups |
+| `'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 |
+
+A conversation whose type Canon could not determine falls back 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.
+
+**Quiet does not suppress**: the typing/thinking indicator (which stays up for the turn's whole working phase; while the turn is parked on an approval the clients suppress an agent's dots and the header line carries the state), turn state, `replyFinal()` including every part of a chunked reply, the partial-final notice, `media.replyWithFile()` itself, `turn.setWaitingInput()`'s note, `sendContextualMessage()`, `publishRuntimeActivity()`, approval/input/card requests, and their outcome receipts.
+
+**`replyProgress(text, { durable: true })` still posts.** Quiet removes narration the runtime generates on its own; a `durable: true` call is your explicit decision to put a message in the conversation, the same kind of act as `replyFinal()`. Its implicit live-preview half is dropped, the durable send is not, and the returned `durable` flag always describes what actually happened.
+
+`ctx.turnVerbosity` carries the resolved value into the handler, so a handler that would otherwise build an expensive live preview can skip it:
+
+```ts
+agent.on('message', async (ctx) => {
+  if (ctx.turnVerbosity === 'verbose') await ctx.turn.setThinking('Reading the repo…');
+  await ctx.replyFinal(await answer(ctx));
+});
+```
+
+This is a developer setting. Canon never changes it, and users cannot set it per conversation.
+
 ### Long text
 
 Canon caps a single message at 4 KB of UTF-8 text, and rejects anything longer outright. Two send paths split oversized text for you instead of failing:

package/dist/canon-agent.d.ts

@@ -1,4 +1,4 @@
-import { type AddMemberResult, type CanonContact, type CanonConversation, type CreateConversationResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult, type CanonVoiceSession, type CanonVoiceSessionToken, type CreateVoiceSessionOptions, type VoiceSessionEventPayload } from '@canonmsg/core';
+import { type AddMemberResult, type CanonContact, type CanonConversation, type CanonConversationsPage, type CanonConversationsPageOptions, type CreateConversationResult, type CanonRuntimeActivityItem, type CanonRuntimeCommandDescriptor, type CanonRuntimeFact, type CanonRuntimePrimitiveId, type ContactCardPayload, type ClearRuntimeActivityOptions, type CreateContactRequestResult, type CanonVoiceSession, type CanonVoiceSessionToken, type CreateVoiceSessionOptions, type VoiceSessionEventPayload } from '@canonmsg/core';
 import type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, CreateConversationOptions, MessageHandler, MessageUpdatedHandler, ReachOutOptions, ReachOutResult, ContactRequestHandler, RuntimeSignalHandler, RuntimePrimitiveHandler } from './types.js';
 /**
  * Contact-graph operations exposed under `agent.contacts`. Wraps the REST
@@ -22,6 +22,15 @@ export interface AgentConversationsAPI {
     list(options?: {
         targetUserId?: string;
     }): Promise<CanonConversation[]>;
+    /**
+     * One page of conversations plus the cursor to continue from, for agents
+     * with enough conversations that fetching all of them on every poll is
+     * wasteful. Continue with `before: page.nextBefore` until it is null.
+     *
+     * Kept separate from `list` on purpose: `list` filters by `targetUserId`
+     * over the complete set, which cannot be honored a page at a time.
+     */
+    page(options?: CanonConversationsPageOptions): Promise<CanonConversationsPage>;
 }
 export declare class CanonAgent {
     private options;

package/dist/canon-agent.js

@@ -1,10 +1,12 @@
-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 { 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, normalizeTurnVerbosityConversationType, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, resolveTurnVerbosity, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, splitTextByUtf8Bytes, verifyCanonRuntimeConnection, } from '@canonmsg/core';
 import { createHash, randomUUID } from 'node:crypto';
 import { AuthManager } from './auth.js';
 import { Debouncer } from './debouncer.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';
+import { buildTurnStreamingRequest } from './turn-streaming-request.js';
+import { selectConfiguredTurnVerbosity } from './turn-verbosity-option.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;
@@ -345,6 +347,7 @@ export class CanonAgent {
                     return conversations;
                 return conversations.filter((conversation) => conversation.memberIds.includes(options.targetUserId));
             },
+            page: (options) => apiClient.getConversationsPage(options),
         };
         if (options.sessions?.enabled) {
             this.sessionManager = new SessionManager({
@@ -1245,6 +1248,14 @@ export class CanonAgent {
         const turnOpenedAt = Date.now();
         let turnState = 'thinking';
         let shouldPersistTurnState = false;
+        // `ctx.turn.noReply()`: the handler chose to end this turn without posting.
+        // Governs TEARDOWN only — `replyFinal` still sends, because in the SDK the
+        // developer's two explicit calls are two explicit decisions.
+        let deliberatelySilent = false;
+        // Set when the handler threw or the turn was aborted. Deliberate silence
+        // must never blank the live node on those paths: the streamed content is
+        // all that survives a turn that died mid-flight.
+        let turnEndedAbnormally = false;
         let durableMessageSequence = 0;
         const agentId = this.agentId;
         const runtimeState = this.createRuntimeStatePublisher();
@@ -1286,17 +1297,32 @@ export class CanonAgent {
                     : {}),
             })).catch(() => { });
         };
+        // Quiet mode is resolved HERE, once, and carried for the whole turn.
+        //
+        // It has to be here because everything downstream is already too late: the
+        // controller's mode is fixed at construction two lines below, the
+        // `'Thinking...'` seed lands before that, and the conversation fetch that
+        // would otherwise name the conversation type is ~30 lines further down,
+        // inside the try. Provenance already carries the type — the stream service
+        // stamps it on every `message.created` frame — so the answer is available
+        // before the first publish of any kind.
+        //
+        // Re-deriving it mid-turn is what must never happen: a turn that started
+        // quiet and finished verbose would emit a trail nothing narrated.
+        const inboundConversationType = normalizeTurnVerbosityConversationType(provenanceByMessageId?.get(messages[messages.length - 1]?.id ?? '')?.conversation?.type);
+        const turnVerbosity = resolveTurnVerbosity({
+            configured: selectConfiguredTurnVerbosity(this.options.turnVerbosity, inboundConversationType),
+            conversationType: inboundConversationType,
+        });
         const turnOutput = createTurnOutputController({
             turnId,
-            mode: 'snapshot',
-            writeSnapshot: (snapshot) => this.apiClient.setStreaming({
-                conversationId,
-                text: snapshot.text,
-                status: snapshot.status,
-                messageId: snapshot.messageId,
-                turnId: snapshot.turnId,
-                blocks: snapshot.blocks,
-            }),
+            // `'status'` keeps every controller call site working and drops only the
+            // RTDB write, which covers all ~12 of them at once — the thinking seed
+            // and its keepalive, `turn.appendDelta`/`appendBlock`/`setTool`, the
+            // approval block, and `replyProgress`'s implicit live half. Blocks still
+            // accumulate in memory, so the trail gate below is a SEPARATE decision.
+            mode: turnVerbosity === 'quiet' ? 'status' : 'snapshot',
+            writeSnapshot: (snapshot) => this.apiClient.setStreaming(buildTurnStreamingRequest({ conversationId, snapshot })),
             clearSnapshot: () => this.apiClient.clearStreaming(conversationId),
         });
         const setLiveState = async (state, text, streamingStatus) => {
@@ -1306,6 +1332,36 @@ export class CanonAgent {
                 await turnOutput.setStatus(streamingStatus, text ?? '');
             }
         };
+        /**
+         * Put the turn back to work after an interaction request settles.
+         *
+         * Both halves matter: the dots were cleared when the turn parked (the
+         * clients suppress an agent's dots on `waiting_input`), and `/turn-state`
+         * plus the live node are still sitting on `waiting_input`. The error paths
+         * need this as much as the success paths — a request that failed still
+         * leaves the handler running, and a quiet turn has no live row to stand in
+         * for the missing dots. Aborts still propagate: `setLiveState` re-checks
+         * the signal, which is how an interrupt lands during cleanup.
+         */
+        const resumeTurnFromWaiting = async () => {
+            try {
+                await this.typingSignals.start(conversationId, 'thinking');
+            }
+            catch { }
+            await setLiveState('thinking', 'Thinking...', 'thinking');
+        };
+        if (turnVerbosity === 'quiet') {
+            // A quiet turn never writes to `/streaming`, so it cannot rely on the
+            // 'Thinking...' seed below to overwrite a node an earlier verbose turn
+            // left behind — and a surviving node under the PREVIOUS turn's id would
+            // sit there, invisible, for this whole turn, then be deleted at teardown:
+            // `onStreamingCleared` would salvage it into a durable bubble landing
+            // AFTER this turn's answer. Deleting at turn open puts that salvage back
+            // where the design intends it, ahead of the answer. Both coding hosts do
+            // the same, one for free (its seed clears unconditionally) and one
+            // explicitly.
+            await turnOutput.clear().catch(() => { });
+        }
         // Show thinking indicator and keep it alive (5s client-side expiry)
         try {
             await this.typingSignals.start(conversationId, 'thinking');
@@ -1352,7 +1408,11 @@ export class CanonAgent {
                 catch { }
                 throwIfAborted();
                 const sendOptions = withActiveSelfContext(options);
-                const turnTrail = turnOutput.getFinalTrail();
+                // Separate from the controller's mode on purpose: `'status'` silences
+                // the live writes but still accumulates blocks, so `getFinalTrail()`
+                // would happily hand back a full trail for a turn that narrated
+                // nothing.
+                const turnTrail = shouldPublishTurnTrail(turnVerbosity) ? turnOutput.getFinalTrail() : [];
                 const finalOptions = {
                     ...sendOptions,
                     metadata: {
@@ -1395,6 +1455,14 @@ export class CanonAgent {
             };
             const replyProgress = async (text, options) => {
                 throwIfAborted();
+                // Owner ruling D1: in quiet the IMPLICIT half of this call — the live
+                // `/streaming` narration — is dropped by the controller's `'status'`
+                // mode, while the turn state it also publishes stays. The EXPLICIT half
+                // below does not: `durable: true` is a developer asking Canon to post a
+                // message, structurally the same act as `replyFinal`, and silently
+                // no-op'ing it would leave a caller reading `durable: true` from a send
+                // that never happened. The result object therefore keeps describing
+                // what actually occurred in both modes.
                 await setLiveState('streaming', text, 'streaming');
                 if (!options?.durable) {
                     return { turnId, durable: false, messageId: null };
@@ -1666,11 +1734,7 @@ export class CanonAgent {
                         });
                     }
                     catch { }
-                    try {
-                        await this.typingSignals.start(conversationId, 'thinking');
-                    }
-                    catch { }
-                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    await resumeTurnFromWaiting();
                     return result;
                 }
                 catch (error) {
@@ -1678,6 +1742,10 @@ export class CanonAgent {
                         throw error;
                     }
                     shouldPersistTurnState = false;
+                    // The turn parked before the request went out and the handler is
+                    // about to carry on with a denial, so put it back to work — the
+                    // success path is not the only way out of `waiting_input`.
+                    await resumeTurnFromWaiting();
                     return { decision: 'deny' };
                 }
             };
@@ -1760,11 +1828,7 @@ export class CanonAgent {
                         });
                     }
                     catch { }
-                    try {
-                        await this.typingSignals.start(conversationId, 'thinking');
-                    }
-                    catch { }
-                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    await resumeTurnFromWaiting();
                     return result;
                 }
                 catch (error) {
@@ -1785,6 +1849,10 @@ export class CanonAgent {
                         throw error;
                     }
                     shouldPersistTurnState = false;
+                    // Parked, then failed rather than answered — the handler carries on
+                    // with the fallback result, so the turn has to look like it is
+                    // working again. The success path is not the only way out.
+                    await resumeTurnFromWaiting();
                     return result;
                 }
             };
@@ -1887,11 +1955,7 @@ export class CanonAgent {
                         });
                     }
                     catch { }
-                    try {
-                        await this.typingSignals.start(conversationId, 'thinking');
-                    }
-                    catch { }
-                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    await resumeTurnFromWaiting();
                     return result;
                 }
                 catch (error) {
@@ -1921,6 +1985,10 @@ export class CanonAgent {
                         throw error;
                     }
                     shouldPersistTurnState = false;
+                    // Parked, then failed rather than answered — the handler carries on
+                    // with the fallback result, so the turn has to look like it is
+                    // working again. The success path is not the only way out.
+                    await resumeTurnFromWaiting();
                     return result;
                 }
             };
@@ -1933,7 +2001,8 @@ export class CanonAgent {
                 catch { }
                 throwIfAborted();
                 try {
-                    const turnTrail = turnOutput.getFinalTrail();
+                    // Same gate as `replyFinal` — this send IS a final, trail included.
+                    const turnTrail = shouldPublishTurnTrail(turnVerbosity) ? turnOutput.getFinalTrail() : [];
                     const result = await sendMediaFileMessage(this.apiClient, conversationId, filePath, text, {
                         ...(options?.replyTo ? { replyTo: options.replyTo } : {}),
                         ...(options?.replyToPosition != null
@@ -1988,6 +2057,7 @@ export class CanonAgent {
                 provenance,
                 turnContext,
                 requestedTurnMode,
+                turnVerbosity,
                 requestApproval,
                 requestRuntimeInput,
                 requestCard,
@@ -2074,6 +2144,14 @@ export class CanonAgent {
                     clear: async () => {
                         await turnOutput.clear();
                     },
+                    noReply: async (reason) => {
+                        throwIfAborted();
+                        deliberatelySilent = true;
+                        // `reason` is handler-authored free text: record only that one was
+                        // given, never the text itself.
+                        console.error(`[canon-sdk] Turn chose no_reply for ${conversationId}`
+                            + ` (reason: ${reason?.trim() ? 'given' : 'none'})`);
+                    },
                     setTool: async (text) => {
                         await writeTurn('tool');
                         await turnOutput.addBlock({
@@ -2118,6 +2196,7 @@ export class CanonAgent {
             }
         }
         catch (err) {
+            turnEndedAbnormally = true;
             if (abortController.signal.aborted || isAbortLikeError(err)) {
                 await writeTurn('interrupted');
                 return;
@@ -2137,13 +2216,29 @@ export class CanonAgent {
                 this.activeTurns.delete(conversationId);
             }
             clearInterval(thinkingKeepalive);
+            // Sequenced AFTER the keepalive stops, and with no handoff delay in front
+            // of it: the 3.5 s keepalive would rewrite 'Thinking...' over a blank
+            // scheduled earlier, and every other runtime retires the row and the
+            // typing dots together the moment a turn goes silent. `replyFinal`'s
+            // handoff window overlaps a durable message that has already landed;
+            // here there is nothing to hand off to, and holding the indicator would
+            // read as "started to answer, then gave up".
+            const silentTeardown = deliberatelySilent && !turnEndedAbnormally;
             // Always clear typing when done
             try {
                 await this.typingSignals.clear(conversationId);
             }
             catch { }
             try {
-                await turnOutput.clear();
+                // Deliberate silence blanks the node (text '' AND an explicit empty
+                // blocks array) before deleting it, so onStreamingCleared sees empty
+                // content and does not salvage the turn's narration into a durable
+                // bubble. A crashed or interrupted turn keeps the plain clear: there
+                // the salvage is the only record of what the turn managed to say.
+                if (silentTeardown)
+                    await turnOutput.blankAndClear();
+                else
+                    await turnOutput.clear();
             }
             catch { }
             if (runtimeState && !shouldPersistTurnState) {

package/dist/index.d.ts

@@ -6,5 +6,6 @@ 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';
 export type { SessionConfig, Session } from './session-manager.js';
-export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, CreateConversationResult, DirectSessionSelection, } from '@canonmsg/core';
+export type { CanonAgentTurnVerbosityOption } from './turn-verbosity-option.js';
+export type { AgentContext, CanonGroupContext, CanonKnownRecentParticipant, CanonMembershipChange, CanonContactRequest, CanonMessage, CanonConversation, CanonConversationsPage, CanonConversationsPageOptions, CanonReplyContext, CanonSelfContext, CanonTurnContextV2, CanonRuntimeDescriptor, MessageUpdatedPayload, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, SendMessageOptions, CreateConversationOptions, CreateConversationResult, DirectSessionSelection, TurnVerbosity, TurnVerbosityConfig, } from '@canonmsg/core';
 export type { CanonAgentConnectionOptions, CanonAgentOptions, ContactAddedHandler, ContactRemovedHandler, ContactRequestHandler, FinalMessageResult, MessageHandler, MessageHandlerContext, MessageUpdatedHandler, ProgressMessageOptions, ProgressMessageResult, ReachOutOptions, ReachOutResult, RuntimeApprovalRequest, RuntimeInputRequest, RuntimeInputResult, RuntimeControlSurface, RuntimePrimitiveContext, RuntimePrimitiveHandler, RuntimePrimitiveHandlers, SessionInfo, SessionOptions, DeliveryMode, } from './types.js';

package/dist/turn-streaming-request.d.ts

@@ -0,0 +1,17 @@
+import type { CanonClient, TurnOutputSnapshot } from '@canonmsg/core';
+export type TurnStreamingRequest = Parameters<CanonClient['setStreaming']>[0];
+/**
+ * Builds the `POST /streaming` body for one turn-output snapshot.
+ *
+ * Extracted from the turn loop for one reason: `blocks` must be forwarded
+ * VERBATIM, empty array included. `POST /streaming` merges into the RTDB node,
+ * so an absent `blocks` key leaves the previous trail in place — and the
+ * `onStreamingCleared` trigger rebuilds salvage text out of block titles. A
+ * silent turn blanks the node with `text: ''` and `blocks: []`; drop the empty
+ * array on the way out and the turn the model declined to send comes back as a
+ * durable bubble made of its own tool-trail headings.
+ */
+export declare function buildTurnStreamingRequest(input: {
+    conversationId: string;
+    snapshot: TurnOutputSnapshot;
+}): TurnStreamingRequest;

package/dist/turn-streaming-request.js

@@ -0,0 +1,22 @@
+/**
+ * Builds the `POST /streaming` body for one turn-output snapshot.
+ *
+ * Extracted from the turn loop for one reason: `blocks` must be forwarded
+ * VERBATIM, empty array included. `POST /streaming` merges into the RTDB node,
+ * so an absent `blocks` key leaves the previous trail in place — and the
+ * `onStreamingCleared` trigger rebuilds salvage text out of block titles. A
+ * silent turn blanks the node with `text: ''` and `blocks: []`; drop the empty
+ * array on the way out and the turn the model declined to send comes back as a
+ * durable bubble made of its own tool-trail headings.
+ */
+export function buildTurnStreamingRequest(input) {
+    const { conversationId, snapshot } = input;
+    return {
+        conversationId,
+        text: snapshot.text,
+        status: snapshot.status,
+        messageId: snapshot.messageId,
+        turnId: snapshot.turnId,
+        blocks: snapshot.blocks,
+    };
+}

package/dist/turn-verbosity-option.d.ts

@@ -0,0 +1,33 @@
+import { type TurnVerbosityConfig, type TurnVerbosityConversationType } from '@canonmsg/core';
+/**
+ * What a developer may write for `CanonAgentOptions.turnVerbosity`.
+ *
+ * The SDK is the one runtime where a per-conversation-type OBJECT is idiomatic:
+ * it has no argv and no config file, so `{ group: 'verbose' }` costs a
+ * developer nothing while the hosts would have to invent a flag grammar for the
+ * same thing. Everything else — the vocabulary, the defaults, `'auto'` ≡ unset
+ * — stays in core's `resolveTurnVerbosity`, which this folds into rather than
+ * reimplements.
+ *
+ * Deliberately NOT promoted to `@canonmsg/core`: the Claude host, the Codex
+ * host, OpenClaw and Hermes all take a scalar (a CLI flag, an env var or a
+ * config-file string), so core would grow a shape with exactly one consumer.
+ */
+export type CanonAgentTurnVerbosityOption = TurnVerbosityConfig | {
+    /** Applies to direct chats — Hermes's `'dm'` spelling included. */
+    direct?: TurnVerbosityConfig;
+    group?: TurnVerbosityConfig;
+};
+/**
+ * Picks the configured value this turn's conversation type is subject to, in
+ * the shape `resolveTurnVerbosity` takes.
+ *
+ * `null` means "nothing configured for this type" and lets core's per-type
+ * default decide — which is also what an `'auto'` entry and an unrecognized
+ * string produce, so an object that names only `group` leaves DMs on the
+ * default rather than forcing them anywhere. A conversation type that resolves
+ * to `'unknown'` (the fetch failed, or provenance was absent) matches no key
+ * and therefore falls through to the fail-open default too: an object form
+ * cannot silence a turn whose shape Canon could not name.
+ */
+export declare function selectConfiguredTurnVerbosity(option: CanonAgentTurnVerbosityOption | null | undefined, conversationType: TurnVerbosityConversationType | null | undefined): TurnVerbosityConfig | null;

package/dist/turn-verbosity-option.js

@@ -0,0 +1,23 @@
+import { normalizeTurnVerbosityConversationType, parseTurnVerbosityConfig, } from '@canonmsg/core';
+/**
+ * Picks the configured value this turn's conversation type is subject to, in
+ * the shape `resolveTurnVerbosity` takes.
+ *
+ * `null` means "nothing configured for this type" and lets core's per-type
+ * default decide — which is also what an `'auto'` entry and an unrecognized
+ * string produce, so an object that names only `group` leaves DMs on the
+ * default rather than forcing them anywhere. A conversation type that resolves
+ * to `'unknown'` (the fetch failed, or provenance was absent) matches no key
+ * and therefore falls through to the fail-open default too: an object form
+ * cannot silence a turn whose shape Canon could not name.
+ */
+export function selectConfiguredTurnVerbosity(option, conversationType) {
+    if (option === null || option === undefined)
+        return null;
+    if (typeof option === 'string')
+        return parseTurnVerbosityConfig(option);
+    const key = normalizeTurnVerbosityConversationType(conversationType);
+    if (key === 'unknown')
+        return null;
+    return parseTurnVerbosityConfig(option[key]);
+}

package/dist/types.d.ts

@@ -62,6 +62,19 @@ export interface TurnController {
     replaceSnapshot: (text: string) => Promise<void>;
     flush: () => Promise<void>;
     clear: () => Promise<void>;
+    /**
+     * End this turn without posting anything (`canon.verbs.v1` `no_reply`). The
+     * live bubble is blanked and removed instead of being salvaged into a durable
+     * message, so nothing is rendered and no other member or agent is triggered —
+     * the agent-turn trigger is message-driven.
+     *
+     * `reason` is private: recorded as present or absent, never sent or rendered.
+     *
+     * Unlike the model-driven runtimes, this does NOT gate `replyFinal`. Calling
+     * both is two explicit decisions by the same author, so the text still lands;
+     * call `noReply` when the handler has decided not to answer at all.
+     */
+    noReply: (reason?: string) => Promise<void>;
     setTool: (text: string) => Promise<void>;
     setWaitingInput: (text?: string) => Promise<void>;
 }
@@ -179,6 +192,14 @@ export interface MessageHandlerContext {
     turnContext: CanonTurnContextV2;
     /** Runtime turn mode requested by the sender for this inbound turn, if any. */
     requestedTurnMode: string | null;
+    /**
+     * How much of this turn's middle the reader sees, already resolved from
+     * `CanonAgentOptions.turnVerbosity` and the conversation type — groups are
+     * quiet by default, DMs verbose. In `'quiet'` the SDK publishes no
+     * `/streaming` narration and attaches no turn trail to the final, so a
+     * handler can skip building either. It stays fixed for the whole turn.
+     */
+    turnVerbosity: import('@canonmsg/core').TurnVerbosity;
     /**
      * Ask the triggering human to approve a native runtime action. This only
      * renders Canon's inline approval card; runtimes must explicitly wait for
@@ -299,6 +320,19 @@ export interface CanonAgentOptions extends CanonAgentConnectionOptions {
      * Turn-state reporting is automatic while handlers run.
      */
     sessionState?: boolean;
+    /**
+     * How much of a turn's middle the reader sees. Unset (or `'auto'`) resolves
+     * per turn from the conversation type: DMs verbose, groups quiet. A scalar
+     * overrides everywhere; the object form overrides one conversation type and
+     * leaves the other on its default.
+     *
+     * `'quiet'` drops the live `/streaming` narration and the final's margin
+     * turn trail. It never touches the typing indicator, the turn state, the
+     * final message, failure notices, or interaction cards and their receipts —
+     * and an explicit `ctx.replyProgress(text, { durable: true })` still posts,
+     * because a developer's explicit send is not runtime narration.
+     */
+    turnVerbosity?: import('./turn-verbosity-option.js').CanonAgentTurnVerbosityOption;
 }
 export type ContactRequestHandler = (request: import('@canonmsg/core').CanonContactRequest) => void | Promise<void>;
 export type ContactAddedHandler = (contact: import('@canonmsg/core').ContactAddedPayload) => void | Promise<void>;

package/package.json

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