@canonmsg/agent-sdk 8.2.0 → 8.3.0

package/README.md

@@ -476,7 +476,7 @@ While a handler runs, the SDK automatically publishes Canon turn state and clear
 - `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.
+`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.
 

package/dist/canon-agent.js

@@ -1,4 +1,4 @@
-import { ApprovalManager, RuntimeRequestManager, runtimeInputDescriptor, runtimeCardDescriptor, CanonClient, ControlChannelPoller, buildCanonTurnContextV2, buildCanonGroupContext, buildParticipationHistorySnapshot, createTurnOutputController, createRuntimeStatePublisher, createTypingStatusPublisher, diffCanonMemberIds, FINAL_MESSAGE_HANDOFF_MS, RUNTIME_NEW_SESSION_ACTION, RUNTIME_STOP_ACTION, RUNTIME_STOP_AND_DROP_ACTION, buildRuntimeCardOutcome, buildRuntimeInputOutcome, initRTDBAuth, isChunkedSendMessageError, normalizeRuntimeCommandDescriptors, normalizeTurnMetadata, normalizeTurnVerbosityConversationType, reachOutToCanonContact, resolveCanonReplyContext, resolveMessageActiveSelfContextId, resolveRuntimeProvenance, resolveTurnVerbosity, selectActiveSelfContexts, renderCanonHostInboundContent, resolveCanonRuntimeConnection, sendMessageWithRetryChunked, shouldPublishTurnTrail, 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';
@@ -1252,11 +1252,18 @@ export class CanonAgent {
         // 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;
@@ -1309,7 +1316,7 @@ export class CanonAgent {
         //
         // 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 inboundConversationType = normalizeTurnVerbosityConversationType(provenanceByMessageId?.get(triggeringMessageId ?? '')?.conversation?.type);
         const turnVerbosity = resolveTurnVerbosity({
             configured: selectConfiguredTurnVerbosity(this.options.turnVerbosity, inboundConversationType),
             conversationType: inboundConversationType,
@@ -1468,6 +1475,10 @@ export class CanonAgent {
                     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
@@ -1554,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,
@@ -2022,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;
                 }
@@ -2146,11 +2163,19 @@ export class CanonAgent {
                     },
                     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: record only that one was
-                        // given, never the text itself.
+                        // `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');
@@ -2224,6 +2249,22 @@ export class CanonAgent {
             // 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);

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/types.d.ts

@@ -68,7 +68,9 @@ export interface TurnController {
      * 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.
+     * `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;

package/package.json

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