@canonmsg/agent-sdk 8.1.0 → 8.3.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 text never leaves the process. Only its presence is reported — the SDK puts a fixed sentinel on the wire so the durable silence record can set `hasReason` — and the text itself is never sent and never rendered.
+
+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.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, reportNoReplyOutcome, 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;
@@ -1246,7 +1248,22 @@ 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;
+        // The FIRST noReply call's reason (one silence decision per turn), carried
+        // to teardown where the outcome report fires. Only its presence rides the
+        // wire — see reportNoReplyOutcome's sentinel.
+        let noReplyReason;
+        // 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;
+        // The freshest message in the batch is the turn's trigger — same convention
+        // as the provenance lookup for turn verbosity below.
+        const triggeringMessageId = messages[messages.length - 1]?.id;
         const agentId = this.agentId;
         const runtimeState = this.createRuntimeStatePublisher();
         const queueDepth = () => this.sessionManager?.getQueueDepth(conversationId) ?? 0;
@@ -1287,17 +1304,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(triggeringMessageId ?? '')?.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) => {
@@ -1307,6 +1339,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');
@@ -1353,7 +1415,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: {
@@ -1396,11 +1462,23 @@ 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 };
                 }
                 throwIfAborted();
+                // Durable progress skips `sendDurableMessage` (see the chunking note
+                // below) but it is still a durable message in the timeline, so it must
+                // advance the same counter teardown reads for the silence report.
+                durableMessageSequence += 1;
                 const { durable: _durable, ...sendOptions } = options;
                 const sendOptionsWithContext = withActiveSelfContext(sendOptions);
                 // Progress text is caller-controlled too, so it can also blow past
@@ -1487,8 +1565,13 @@ export class CanonAgent {
             // untouched metadata, so the common case (and the interim→final handoff
             // that keys on that id) is unchanged.
             const sendDurableMessage = async (text, options, fallbackMessageIdParts) => {
+                // Counts every durable send the turn attempts, not just the ones that
+                // needed a generated id: teardown reads `durableMessageSequence` to
+                // decide whether the turn genuinely ended silent, and a reply sent
+                // under an explicit caller messageId must not look like silence.
+                durableMessageSequence += 1;
                 const messageId = options?.messageId
-                    ?? buildSdkMessageId([...fallbackMessageIdParts, durableMessageSequence += 1]);
+                    ?? buildSdkMessageId([...fallbackMessageIdParts, durableMessageSequence]);
                 const { messageIds } = await sendMessageWithRetryChunked(abortAwareClient, conversationId, text, {
                     ...(options ?? {}),
                     messageId,
@@ -1667,11 +1750,7 @@ export class CanonAgent {
                         });
                     }
                     catch { }
-                    try {
-                        await this.typingSignals.start(conversationId, 'thinking');
-                    }
-                    catch { }
-                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    await resumeTurnFromWaiting();
                     return result;
                 }
                 catch (error) {
@@ -1679,6 +1758,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' };
                 }
             };
@@ -1761,11 +1844,7 @@ export class CanonAgent {
                         });
                     }
                     catch { }
-                    try {
-                        await this.typingSignals.start(conversationId, 'thinking');
-                    }
-                    catch { }
-                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    await resumeTurnFromWaiting();
                     return result;
                 }
                 catch (error) {
@@ -1786,6 +1865,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;
                 }
             };
@@ -1888,11 +1971,7 @@ export class CanonAgent {
                         });
                     }
                     catch { }
-                    try {
-                        await this.typingSignals.start(conversationId, 'thinking');
-                    }
-                    catch { }
-                    await setLiveState('thinking', 'Thinking...', 'thinking');
+                    await resumeTurnFromWaiting();
                     return result;
                 }
                 catch (error) {
@@ -1922,6 +2001,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;
                 }
             };
@@ -1934,7 +2017,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
@@ -1954,6 +2038,7 @@ export class CanonAgent {
                         ...(options?.mimeType ? { mimeType: options.mimeType } : {}),
                         ...(options?.durationMs != null ? { durationMs: options.durationMs } : {}),
                     });
+                    durableMessageSequence += 1;
                     await sleep(FINAL_MESSAGE_HANDOFF_MS);
                     return result;
                 }
@@ -1989,6 +2074,7 @@ export class CanonAgent {
                 provenance,
                 turnContext,
                 requestedTurnMode,
+                turnVerbosity,
                 requestApproval,
                 requestRuntimeInput,
                 requestCard,
@@ -2075,6 +2161,22 @@ export class CanonAgent {
                     clear: async () => {
                         await turnOutput.clear();
                     },
+                    noReply: async (reason) => {
+                        throwIfAborted();
+                        // First call wins — one silence decision per turn.
+                        if (!deliberatelySilent && reason?.trim()) {
+                            noReplyReason = reason;
+                        }
+                        deliberatelySilent = true;
+                        // `reason` is handler-authored free text: log only that one was given.
+                        console.error(`[canon-sdk] Turn chose no_reply for ${conversationId}`
+                            + ` (reason: ${reason?.trim() ? 'given' : 'none'})`);
+                        // The outcome report deliberately does NOT fire here: `replyFinal`
+                        // still sends after `noReply` (the SDK carve-out — see
+                        // TurnController.noReply in types.ts) and the handler may yet throw
+                        // or be aborted, so only teardown knows whether the silence was
+                        // real. It fires there, once, off the flag set above.
+                    },
                     setTool: async (text) => {
                         await writeTurn('tool');
                         await turnOutput.addBlock({
@@ -2119,6 +2221,7 @@ export class CanonAgent {
             }
         }
         catch (err) {
+            turnEndedAbnormally = true;
             if (abortController.signal.aborted || isAbortLikeError(err)) {
                 await writeTurn('interrupted');
                 return;
@@ -2138,13 +2241,45 @@ 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;
+            // Telemetry parity with the server-answered verb path, decided HERE
+            // because only teardown knows how the turn actually ended: `noReply`
+            // does not gate `replyFinal` in the SDK, and the handler may throw or be
+            // aborted after choosing silence — either would make a report sent at
+            // noReply-call time record silence for a turn that delivered or died.
+            // `durableMessageSequence` counts the turn's durable sends: any durable
+            // message means the turn did not end silent, deliberate flag or not.
+            // reportNoReplyOutcome is fire-and-forget and never throws, so a failed
+            // or rejecting report degrades to exactly the pre-report behavior.
+            if (silentTeardown && durableMessageSequence === 0) {
+                reportNoReplyOutcome(this.apiClient, {
+                    conversationId,
+                    ...(triggeringMessageId ? { messageId: triggeringMessageId } : {}),
+                    ...(noReplyReason ? { reason: noReplyReason } : {}),
+                });
+            }
             // 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, CanonConversationsPage, CanonConversationsPageOptions, 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/realtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentContext, 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 ParticipationSuppressedPayload, type VoiceSessionEventPayload } from '@canonmsg/core';
 import { Debouncer } from './debouncer.js';
 /**
  * Wraps @canonmsg/core's CanonStream with SDK-specific features:
@@ -20,6 +20,7 @@ export declare class RealtimeManager {
     private onContactAdded;
     private onContactRemoved;
     private onConversationUpdated;
+    private onParticipationSuppressed;
     private onMessageUpdated;
     private onMessageDeleted;
     private onConnected;
@@ -43,6 +44,12 @@ export declare class RealtimeManager {
         onContactRemoved?: (payload: ContactRemovedPayload) => void;
     }): void;
     setConversationUpdatedHandler(cb: (payload: ConversationUpdatedPayload) => void): void;
+    /**
+     * Observe-only notice that Canon's participation gate withheld a turn this
+     * agent would otherwise have been dispatched. Never run a turn off it — it
+     * exists so an agent can tell deliberate policy from a dead stream.
+     */
+    setParticipationSuppressedHandler(cb: (payload: ParticipationSuppressedPayload) => void): void;
     setMessageUpdatedHandler(cb: (payload: MessageUpdatedPayload) => void): void;
     setMessageDeletedHandler(cb: (payload: {
         conversationId: string;

package/dist/realtime.js

@@ -21,6 +21,7 @@ export class RealtimeManager {
     onContactAdded = null;
     onContactRemoved = null;
     onConversationUpdated = null;
+    onParticipationSuppressed = null;
     onMessageUpdated = null;
     onMessageDeleted = null;
     onConnected = null;
@@ -113,6 +114,9 @@ export class RealtimeManager {
                 onConversationUpdated: (payload) => {
                     this.onConversationUpdated?.(payload);
                 },
+                onParticipationSuppressed: (payload) => {
+                    this.onParticipationSuppressed?.(payload);
+                },
                 onConnected: () => {
                     this.onConnected?.();
                 },
@@ -180,6 +184,14 @@ export class RealtimeManager {
     setConversationUpdatedHandler(cb) {
         this.onConversationUpdated = cb;
     }
+    /**
+     * Observe-only notice that Canon's participation gate withheld a turn this
+     * agent would otherwise have been dispatched. Never run a turn off it — it
+     * exists so an agent can tell deliberate policy from a dead stream.
+     */
+    setParticipationSuppressedHandler(cb) {
+        this.onParticipationSuppressed = cb;
+    }
     setMessageUpdatedHandler(cb) {
         this.onMessageUpdated = cb;
     }

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,21 @@ 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: the text never leaves the process. Only its presence
+     * is reported (a fixed sentinel on the wire), so the durable silence record
+     * can set `hasReason` — the text itself is never sent and never 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 +194,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 +322,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.1.0",
+  "version": "8.3.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.2.0"
+    "@canonmsg/core": "^10.2.0"
   },
   "publishConfig": {
     "access": "public"