@canonmsg/backend-contracts 5.1.0 → 5.3.0

package/README.md

@@ -16,7 +16,7 @@ Node.js 18+. Ships both ESM and CommonJS builds — Cloud Functions consume the
 
 ## What is in it
 
-**The verb contract.** `canon.verbs.v1` (`verbContract.ts`) is the plaintext *intent* schema — sixteen verbs, their input and result schemas, byte limits, and rate limits. `canon.verb-wire.v1` (`verbWire.ts`) is what actually crosses the network: a server-readable envelope plus a body that is either `{ encoding: 'json', value }` or `{ encoding: 'mls', … }`. `projectVerbIntentToWire` and `mergeVerbWireToIntent` are the two halves of that split, so bindings and the server never disagree about which fields are envelope and which are content.
+**The verb contract.** `canon.verbs.v1` (`verbContract.ts`) is the plaintext *intent* schema — seventeen verbs, their input and result schemas, byte limits, and rate limits. `canon.verb-wire.v1` (`verbWire.ts`) is what actually crosses the network: a server-readable envelope plus a body that is either `{ encoding: 'json', value }` or `{ encoding: 'mls', … }`. `projectVerbIntentToWire` and `mergeVerbWireToIntent` are the two halves of that split, so bindings and the server never disagree about which fields are envelope and which are content.
 
 ```ts
 import {

package/dist/agentBehaviorPolicy.d.ts

@@ -1,3 +1,5 @@
+/** Conversation scope a policy is resolved for. Absent means "agent scope". */
+export type PolicyConversationType = 'direct' | 'group' | 'unknown';
 export type ParticipationStyle = 'natural' | 'collaborative' | 'mention-first' | 'approval-gated' | 'handoff-only' | 'observer';
 /**
  * The stored/parsed shape. This is the RETURN type of
@@ -45,11 +47,17 @@ export interface ResolvedAgentBehaviorPolicyRecord {
     };
 }
 export interface ParticipationDecisionInput {
-    conversationType: 'direct' | 'group' | 'unknown';
+    conversationType: PolicyConversationType;
     senderType: 'human' | 'ai_agent';
     isOwner: boolean;
     mentionedAgent: boolean;
     recentHumanCount?: number;
+    /**
+     * Consecutive agent turns already in the streak, NOT counting the message
+     * being evaluated. The message itself adds one more when its sender is an
+     * agent, and a delivery would add a further one — see the turn-cap check in
+     * {@link evaluateParticipationPolicy}.
+     */
     consecutiveAgentTurns?: number;
     currentAgentStreakStartedByHuman?: boolean;
 }
@@ -72,13 +80,50 @@ export interface ParticipationHistorySnapshot {
     currentAgentStreakStartedByHuman: boolean;
 }
 export declare const PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
+/**
+ * Safety backstop for groups with no explicit turn cap: at most this many
+ * consecutive agent turns before a human has to speak again.
+ *
+ * This is a backstop, not the steering wheel — agents are expected to stop on
+ * their own. Direct conversations deliberately stay unlimited: only a non-agent
+ * message resets the streak, so a default cap in a pure agent-to-agent DM would
+ * halt the room permanently instead of merely bounding a loop.
+ *
+ * The same caveat applies to the one group shape this default does cover: a
+ * group whose members are all agents (reachable — agent-created groups need no
+ * human member) has nothing that resets the streak, so it stops auto-replying
+ * for good once the cap is reached. That is deliberate: an unattended room is
+ * where a runaway loop is most expensive. Recovery needs a human member — the
+ * per-conversation `null` opt-out is writable only by a group owner or admin,
+ * who must be a member. Teaching the resolver "does this room contain a
+ * human?" would mean loading member types at every resolution site, including
+ * the stream gate, which does not read them today.
+ */
+export declare const DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS = 4;
 export declare function parseAgentBehaviorSettings(raw: unknown): AgentBehaviorSettingsRecord;
 export declare function normalizeStoredAgentBehaviorPolicy(raw: Record<string, unknown> | undefined): AgentBehaviorSettingsRecord | null;
 export declare function normalizeAgentBehaviorInstructions(value: string | null | undefined): string | null;
+/**
+ * The scope-independent participation defaults. `maxConsecutiveAgentTurns` is
+ * `null` here because the turn cap is scope-dependent — a group with no stored
+ * setting resolves to {@link DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS}. Use
+ * {@link resolveAgentBehaviorPolicy} with a `conversationType` to learn what a
+ * given conversation actually enforces.
+ */
 export declare function getDefaultParticipationPolicy(): ParticipationPolicy;
+/**
+ * Coalesce agent defaults and a conversation override into the resolved record
+ * every runtime reads. `conversationType` selects the Canon-wide fallbacks that
+ * differ per scope — today only the turn cap, which defaults to
+ * {@link DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS} in groups and to unlimited
+ * everywhere else. Omit it when resolving for the agent scope (no conversation);
+ * an absent or unknown type always resolves to the unlimited default, so a call
+ * site that forgets to thread it can never invent a cap.
+ */
 export declare function resolveAgentBehaviorPolicy(params?: {
     agentDefault?: AgentBehaviorSettingsInput | null;
     conversationOverride?: AgentBehaviorSettingsInput | null;
+    conversationType?: PolicyConversationType;
 }): ResolvedAgentBehaviorPolicyRecord;
 export declare function buildParticipationHistorySnapshot(messages: ParticipationHistoryMessage[], agentId?: string): ParticipationHistorySnapshot;
 export declare function appendParticipationHistoryMessage(snapshot: ParticipationHistorySnapshot, message: ParticipationHistoryMessage, limit?: number): ParticipationHistorySnapshot;

package/dist/agentBehaviorPolicy.js

@@ -1,5 +1,30 @@
-import { resolveTurnMessageSemantics } from './turnProtocol.js';
+import { shouldTriggerAgentTurn } from './turnProtocol.js';
 export const PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
+/**
+ * Safety backstop for groups with no explicit turn cap: at most this many
+ * consecutive agent turns before a human has to speak again.
+ *
+ * This is a backstop, not the steering wheel — agents are expected to stop on
+ * their own. Direct conversations deliberately stay unlimited: only a non-agent
+ * message resets the streak, so a default cap in a pure agent-to-agent DM would
+ * halt the room permanently instead of merely bounding a loop.
+ *
+ * The same caveat applies to the one group shape this default does cover: a
+ * group whose members are all agents (reachable — agent-created groups need no
+ * human member) has nothing that resets the streak, so it stops auto-replying
+ * for good once the cap is reached. That is deliberate: an unattended room is
+ * where a runaway loop is most expensive. Recovery needs a human member — the
+ * per-conversation `null` opt-out is writable only by a group owner or admin,
+ * who must be a member. Teaching the resolver "does this room contain a
+ * human?" would mean loading member types at every resolution site, including
+ * the stream gate, which does not read them today.
+ */
+export const DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS = 4;
+function defaultMaxConsecutiveAgentTurns(conversationType) {
+    return conversationType === 'group'
+        ? DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS
+        : null;
+}
 const VALID_PARTICIPATION_STYLES = new Set([
     'natural',
     'collaborative',
@@ -119,9 +144,25 @@ export function normalizeAgentBehaviorInstructions(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : null;
 }
+/**
+ * The scope-independent participation defaults. `maxConsecutiveAgentTurns` is
+ * `null` here because the turn cap is scope-dependent — a group with no stored
+ * setting resolves to {@link DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS}. Use
+ * {@link resolveAgentBehaviorPolicy} with a `conversationType` to learn what a
+ * given conversation actually enforces.
+ */
 export function getDefaultParticipationPolicy() {
     return { ...DEFAULT_POLICY.participation };
 }
+/**
+ * Coalesce agent defaults and a conversation override into the resolved record
+ * every runtime reads. `conversationType` selects the Canon-wide fallbacks that
+ * differ per scope — today only the turn cap, which defaults to
+ * {@link DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS} in groups and to unlimited
+ * everywhere else. Omit it when resolving for the agent scope (no conversation);
+ * an absent or unknown type always resolves to the unlimited default, so a call
+ * site that forgets to thread it can never invent a cap.
+ */
 export function resolveAgentBehaviorPolicy(params) {
     const agentDefault = params?.agentDefault ?? null;
     const conversationOverride = params?.conversationOverride ?? null;
@@ -140,7 +181,7 @@ export function resolveAgentBehaviorPolicy(params) {
                 ? conversationOverride.maxConsecutiveAgentTurns ?? null
                 : agentDefault?.maxConsecutiveAgentTurns !== undefined
                     ? agentDefault.maxConsecutiveAgentTurns ?? null
-                    : DEFAULT_POLICY.participation.maxConsecutiveAgentTurns,
+                    : defaultMaxConsecutiveAgentTurns(params?.conversationType),
         },
         instructions: [
             ...(defaultInstructions ? [defaultInstructions] : []),
@@ -152,14 +193,22 @@ export function resolveAgentBehaviorPolicy(params) {
         },
     };
 }
+/**
+ * The streak counts exactly the agent messages that can trigger another agent —
+ * the only messages a loop can be built from. Reusing the trigger gate keeps the
+ * two in lockstep: it admits `control` messages that do not suppress auto-reply
+ * (hand-crafted runtime metadata can otherwise drive an uncounted loop) and
+ * still drops chunk parts, interim progress, card round-trips and media/failure
+ * notices, none of which trigger anyone and none of which should burn a slot.
+ */
 function toHistorySenderType(message) {
     if (message.senderType !== 'ai_agent') {
         return 'human';
     }
-    return resolveTurnMessageSemantics({
-        senderType: message.senderType,
+    return shouldTriggerAgentTurn({
+        senderType: 'ai_agent',
         metadata: message.metadata,
-    }) === 'turn_complete'
+    }).allow
         ? 'ai_agent'
         : null;
 }
@@ -198,9 +247,17 @@ export function appendParticipationHistoryMessage(snapshot, message, limit = PAR
     ].slice(0, limit));
 }
 export function evaluateParticipationPolicy(policy, input) {
-    const resolved = policy ?? resolveAgentBehaviorPolicy();
+    const resolved = policy ?? resolveAgentBehaviorPolicy({ conversationType: input.conversationType });
     const participation = resolved.participation;
-    const consecutiveAgentTurns = Math.max(input.consecutiveAgentTurns ?? (input.senderType === 'ai_agent' ? 1 : 0), input.senderType === 'ai_agent' ? 1 : 0);
+    const priorAgentTurns = Math.max(input.consecutiveAgentTurns ?? 0, 0);
+    /** Streak length once the message being evaluated is counted. */
+    const agentTurnsWithCurrent = priorAgentTurns
+        + (input.senderType === 'ai_agent' ? 1 : 0);
+    /**
+     * The long-running-collaboration brake reads "more than the current turn",
+     * so it keeps its historical floor rather than the exact streak length.
+     */
+    const consecutiveAgentTurns = Math.max(priorAgentTurns, input.senderType === 'ai_agent' ? 1 : 0);
     const currentAgentStreakStartedByHuman = input.currentAgentStreakStartedByHuman === true;
     if (input.conversationType === 'group'
         && participation.requireMentionForGroupReplies
@@ -237,9 +294,13 @@ export function evaluateParticipationPolicy(policy, input) {
             reason: 'a fresh human steer is required before continuing agent collaboration',
         };
     }
+    // `maxConsecutiveAgentTurns: N` means at most N consecutive agent turns
+    // without a human in between. Delivering this message triggers turn
+    // `agentTurnsWithCurrent + 1`, so it is suppressed as soon as the streak has
+    // already reached N.
     if (typeof participation.maxConsecutiveAgentTurns === 'number'
         && participation.maxConsecutiveAgentTurns >= 0
-        && consecutiveAgentTurns > participation.maxConsecutiveAgentTurns) {
+        && agentTurnsWithCurrent >= participation.maxConsecutiveAgentTurns) {
         return {
             allow: false,
             reasonCode: 'agent_turn_limit_reached',

package/dist/canon-verb-wire.schema.json

@@ -32,7 +32,8 @@
         "leave_conversation",
         "list_contacts",
         "list_contact_requests",
-        "list_conversations"
+        "list_conversations",
+        "no_reply"
       ]
     },
     "envelope": {
@@ -506,7 +507,8 @@
             "leave_conversation",
             "list_contacts",
             "list_contact_requests",
-            "list_conversations"
+            "list_conversations",
+            "no_reply"
           ]
         },
         "result": {

package/dist/canon-verbs.limits.json

@@ -45,7 +45,8 @@
     "maxApprovalTimeoutMs": 259200000,
     "turnIdChars": 128,
     "reactionEmojiChars": 64,
-    "groupNameChars": 100
+    "groupNameChars": 100,
+    "noReplyReasonChars": 500
   },
   "rateLimits": {
     "senderMessagesPer5Min": 300,

package/dist/canon-verbs.schema.json

@@ -1891,6 +1891,45 @@
           }
         }
       }
+    },
+    "no_reply_input": {
+      "type": "object",
+      "description": "End this turn without posting anything to the conversation. Nothing is rendered and no other member or agent is triggered.",
+      "additionalProperties": false,
+      "properties": {
+        "conversationId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_.:-]{1,160}$"
+        },
+        "messageId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_.:-]{1,160}$",
+          "description": "The triggering message this silence answers, so the record cannot be misread against a later message."
+        },
+        "reason": {
+          "type": "string",
+          "maxLength": 500,
+          "description": "Never rendered; logged only."
+        }
+      }
+    },
+    "no_reply_result": {
+      "type": "object",
+      "required": [
+        "status"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "status": {
+          "const": "acknowledged"
+        },
+        "conversationId": {
+          "type": "string"
+        },
+        "note": {
+          "type": "string"
+        }
+      }
     }
   }
 }

package/dist/cjs/agentBehaviorPolicy.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PARTICIPATION_HISTORY_FETCH_LIMIT = void 0;
+exports.DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS = exports.PARTICIPATION_HISTORY_FETCH_LIMIT = void 0;
 exports.parseAgentBehaviorSettings = parseAgentBehaviorSettings;
 exports.normalizeStoredAgentBehaviorPolicy = normalizeStoredAgentBehaviorPolicy;
 exports.normalizeAgentBehaviorInstructions = normalizeAgentBehaviorInstructions;
@@ -11,6 +11,31 @@ exports.appendParticipationHistoryMessage = appendParticipationHistoryMessage;
 exports.evaluateParticipationPolicy = evaluateParticipationPolicy;
 const turnProtocol_js_1 = require("./turnProtocol.js");
 exports.PARTICIPATION_HISTORY_FETCH_LIMIT = 50;
+/**
+ * Safety backstop for groups with no explicit turn cap: at most this many
+ * consecutive agent turns before a human has to speak again.
+ *
+ * This is a backstop, not the steering wheel — agents are expected to stop on
+ * their own. Direct conversations deliberately stay unlimited: only a non-agent
+ * message resets the streak, so a default cap in a pure agent-to-agent DM would
+ * halt the room permanently instead of merely bounding a loop.
+ *
+ * The same caveat applies to the one group shape this default does cover: a
+ * group whose members are all agents (reachable — agent-created groups need no
+ * human member) has nothing that resets the streak, so it stops auto-replying
+ * for good once the cap is reached. That is deliberate: an unattended room is
+ * where a runaway loop is most expensive. Recovery needs a human member — the
+ * per-conversation `null` opt-out is writable only by a group owner or admin,
+ * who must be a member. Teaching the resolver "does this room contain a
+ * human?" would mean loading member types at every resolution site, including
+ * the stream gate, which does not read them today.
+ */
+exports.DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS = 4;
+function defaultMaxConsecutiveAgentTurns(conversationType) {
+    return conversationType === 'group'
+        ? exports.DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS
+        : null;
+}
 const VALID_PARTICIPATION_STYLES = new Set([
     'natural',
     'collaborative',
@@ -130,9 +155,25 @@ function normalizeAgentBehaviorInstructions(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : null;
 }
+/**
+ * The scope-independent participation defaults. `maxConsecutiveAgentTurns` is
+ * `null` here because the turn cap is scope-dependent — a group with no stored
+ * setting resolves to {@link DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS}. Use
+ * {@link resolveAgentBehaviorPolicy} with a `conversationType` to learn what a
+ * given conversation actually enforces.
+ */
 function getDefaultParticipationPolicy() {
     return { ...DEFAULT_POLICY.participation };
 }
+/**
+ * Coalesce agent defaults and a conversation override into the resolved record
+ * every runtime reads. `conversationType` selects the Canon-wide fallbacks that
+ * differ per scope — today only the turn cap, which defaults to
+ * {@link DEFAULT_GROUP_MAX_CONSECUTIVE_AGENT_TURNS} in groups and to unlimited
+ * everywhere else. Omit it when resolving for the agent scope (no conversation);
+ * an absent or unknown type always resolves to the unlimited default, so a call
+ * site that forgets to thread it can never invent a cap.
+ */
 function resolveAgentBehaviorPolicy(params) {
     const agentDefault = params?.agentDefault ?? null;
     const conversationOverride = params?.conversationOverride ?? null;
@@ -151,7 +192,7 @@ function resolveAgentBehaviorPolicy(params) {
                 ? conversationOverride.maxConsecutiveAgentTurns ?? null
                 : agentDefault?.maxConsecutiveAgentTurns !== undefined
                     ? agentDefault.maxConsecutiveAgentTurns ?? null
-                    : DEFAULT_POLICY.participation.maxConsecutiveAgentTurns,
+                    : defaultMaxConsecutiveAgentTurns(params?.conversationType),
         },
         instructions: [
             ...(defaultInstructions ? [defaultInstructions] : []),
@@ -163,14 +204,22 @@ function resolveAgentBehaviorPolicy(params) {
         },
     };
 }
+/**
+ * The streak counts exactly the agent messages that can trigger another agent —
+ * the only messages a loop can be built from. Reusing the trigger gate keeps the
+ * two in lockstep: it admits `control` messages that do not suppress auto-reply
+ * (hand-crafted runtime metadata can otherwise drive an uncounted loop) and
+ * still drops chunk parts, interim progress, card round-trips and media/failure
+ * notices, none of which trigger anyone and none of which should burn a slot.
+ */
 function toHistorySenderType(message) {
     if (message.senderType !== 'ai_agent') {
         return 'human';
     }
-    return (0, turnProtocol_js_1.resolveTurnMessageSemantics)({
-        senderType: message.senderType,
+    return (0, turnProtocol_js_1.shouldTriggerAgentTurn)({
+        senderType: 'ai_agent',
         metadata: message.metadata,
-    }) === 'turn_complete'
+    }).allow
         ? 'ai_agent'
         : null;
 }
@@ -209,9 +258,17 @@ function appendParticipationHistoryMessage(snapshot, message, limit = exports.PA
     ].slice(0, limit));
 }
 function evaluateParticipationPolicy(policy, input) {
-    const resolved = policy ?? resolveAgentBehaviorPolicy();
+    const resolved = policy ?? resolveAgentBehaviorPolicy({ conversationType: input.conversationType });
     const participation = resolved.participation;
-    const consecutiveAgentTurns = Math.max(input.consecutiveAgentTurns ?? (input.senderType === 'ai_agent' ? 1 : 0), input.senderType === 'ai_agent' ? 1 : 0);
+    const priorAgentTurns = Math.max(input.consecutiveAgentTurns ?? 0, 0);
+    /** Streak length once the message being evaluated is counted. */
+    const agentTurnsWithCurrent = priorAgentTurns
+        + (input.senderType === 'ai_agent' ? 1 : 0);
+    /**
+     * The long-running-collaboration brake reads "more than the current turn",
+     * so it keeps its historical floor rather than the exact streak length.
+     */
+    const consecutiveAgentTurns = Math.max(priorAgentTurns, input.senderType === 'ai_agent' ? 1 : 0);
     const currentAgentStreakStartedByHuman = input.currentAgentStreakStartedByHuman === true;
     if (input.conversationType === 'group'
         && participation.requireMentionForGroupReplies
@@ -248,9 +305,13 @@ function evaluateParticipationPolicy(policy, input) {
             reason: 'a fresh human steer is required before continuing agent collaboration',
         };
     }
+    // `maxConsecutiveAgentTurns: N` means at most N consecutive agent turns
+    // without a human in between. Delivering this message triggers turn
+    // `agentTurnsWithCurrent + 1`, so it is suppressed as soon as the streak has
+    // already reached N.
     if (typeof participation.maxConsecutiveAgentTurns === 'number'
         && participation.maxConsecutiveAgentTurns >= 0
-        && consecutiveAgentTurns > participation.maxConsecutiveAgentTurns) {
+        && agentTurnsWithCurrent >= participation.maxConsecutiveAgentTurns) {
         return {
             allow: false,
             reasonCode: 'agent_turn_limit_reached',

package/dist/cjs/verbContract.js

@@ -16,7 +16,9 @@
  *
  * Deliberately NOT verbs: replying in the active conversation, streaming
  * partials, typing, and read receipts stay host-mediated — the model talks
- * and the platform delivers. Still out of scope pending their own design
+ * and the platform delivers. `no_reply` is the deliberate exception: it is the
+ * ABSENCE of a reply, and only an intent can express that — silence has no
+ * host-mediated channel of its own. Still out of scope pending their own design
  * pass: plan approval (the fourth runtime-interaction kind — coding-host
  * concern today) and block/mute. Their REST surfaces remain directly
  * callable.
@@ -42,7 +44,7 @@
  * canon-verbs.limits.json) after schema validation.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CANON_VERB_LIMITS_ARTIFACT = exports.CREATE_GROUP_CREATOR_SETUP_REQUIRED_CODE = exports.CREATE_GROUP_NO_ADDABLE_MEMBERS_CODE = exports.VERB_NATIVE_METADATA_KEYS = exports.CANON_VERB_NAMES = exports.SELF_CONTEXT_TYPE = exports.VERB_RATE_LIMITS = exports.VERB_LIMITS = exports.VERB_ID_PATTERNS = exports.CANON_CARD_SCHEMA_ID = exports.CANON_VERB_NAMESPACE = exports.CANON_VERBS_SCHEMA_ID = exports.CANON_VERBS_SCHEMA_VERSION = void 0;
+exports.CANON_VERB_LIMITS_ARTIFACT = exports.NO_REPLY_ACK_NOTE = exports.CREATE_GROUP_CREATOR_SETUP_REQUIRED_CODE = exports.CREATE_GROUP_NO_ADDABLE_MEMBERS_CODE = exports.VERB_NATIVE_METADATA_KEYS = exports.CANON_VERB_NAMES = exports.SELF_CONTEXT_TYPE = exports.VERB_RATE_LIMITS = exports.VERB_LIMITS = exports.VERB_ID_PATTERNS = exports.CANON_CARD_SCHEMA_ID = exports.CANON_VERB_NAMESPACE = exports.CANON_VERBS_SCHEMA_ID = exports.CANON_VERBS_SCHEMA_VERSION = void 0;
 exports.normalizeVerbNativeMetadata = normalizeVerbNativeMetadata;
 exports.canonVerbToolName = canonVerbToolName;
 exports.findVerbByteLimitViolations = findVerbByteLimitViolations;
@@ -165,6 +167,12 @@ exports.VERB_LIMITS = {
      * CREATE does not length-check today — treat as the authoring contract).
      */
     groupNameChars: 100,
+    /**
+     * `no_reply.reason` authoring cap. There is no server enforcement beyond the
+     * intent schema — the handler logs the reason's presence and nothing else —
+     * so this constant is the canonical figure.
+     */
+    noReplyReasonChars: 500,
 };
 /**
  * Sender-side rate limits enforced by POST /messages/send
@@ -196,6 +204,7 @@ exports.CANON_VERB_NAMES = [
     'list_contacts',
     'list_contact_requests',
     'list_conversations',
+    'no_reply',
 ];
 exports.VERB_NATIVE_METADATA_KEYS = [
     'runtime',
@@ -271,6 +280,13 @@ exports.CREATE_GROUP_NO_ADDABLE_MEMBERS_CODE = 'CREATE_GROUP_NO_ADDABLE_MEMBERS'
  * creates the group from the app instead).
  */
 exports.CREATE_GROUP_CREATOR_SETUP_REQUIRED_CODE = 'CREATE_GROUP_CREATOR_SETUP_REQUIRED';
+/**
+ * The `note` the server returns on a `no_reply` ack — the model's closure
+ * sentence. It lives here, not in a host, because every binding surfaces the
+ * server's result verbatim and a runtime that answers `no_reply` locally must
+ * say the same thing.
+ */
+exports.NO_REPLY_ACK_NOTE = 'Acknowledged — nothing was posted to the conversation.';
 /** Flat tool name for a verb on namespaced tool surfaces (e.g. `canon_send_to`). */
 function canonVerbToolName(verb) {
     return `${exports.CANON_VERB_NAMESPACE}_${verb}`;

package/dist/cjs/verbSchemas.js

@@ -1058,6 +1058,35 @@ const list_conversations_result = {
         },
     },
 };
+const no_reply_input = {
+    type: 'object',
+    description: 'End this turn without posting anything to the conversation. Nothing is '
+        + 'rendered and no other member or agent is triggered.',
+    additionalProperties: false,
+    properties: {
+        conversationId: { type: 'string', pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeId },
+        messageId: {
+            type: 'string',
+            pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeId,
+            description: 'The triggering message this silence answers, so the record cannot be misread against a later message.',
+        },
+        reason: {
+            type: 'string',
+            maxLength: verbContract_js_1.VERB_LIMITS.noReplyReasonChars,
+            description: 'Never rendered; logged only.',
+        },
+    },
+};
+const no_reply_result = {
+    type: 'object',
+    required: ['status'],
+    additionalProperties: true,
+    properties: {
+        status: { const: 'acknowledged' },
+        conversationId: { type: 'string' },
+        note: { type: 'string' },
+    },
+};
 // ---------------------------------------------------------------------------
 // Bundle
 // ---------------------------------------------------------------------------
@@ -1116,6 +1145,8 @@ exports.CANON_VERBS_JSON_SCHEMA = {
         list_contact_requests_result,
         list_conversations_input,
         list_conversations_result,
+        no_reply_input,
+        no_reply_result,
     },
 };
 exports.CANON_VERB_SCHEMA_REFS = Object.fromEntries(verbContract_js_1.CANON_VERB_NAMES.map((name) => [

package/dist/cjs/verbWire.js

@@ -118,6 +118,7 @@ exports.VERB_WIRE_ENVELOPE_FIELDS = {
     list_contacts: { required: [], optional: [] },
     list_contact_requests: { required: [], optional: [] },
     list_conversations: { required: [], optional: ['limit'] },
+    no_reply: { required: [], optional: ['conversationId', 'messageId'] },
 };
 // ---------------------------------------------------------------------------
 // JSON Schema
@@ -476,6 +477,11 @@ function projectVerbIntentToWire(verb, intent, options) {
             envelope = compact({ limit: input.limit });
             break;
         }
+        case 'no_reply': {
+            envelope = compact({ conversationId: input.conversationId, messageId: input.messageId });
+            value = compact({ reason: input.reason });
+            break;
+        }
     }
     return {
         wire: exports.CANON_VERB_WIRE_SCHEMA_VERSION,
@@ -613,6 +619,8 @@ function mergeVerbWireToIntent(request) {
             return {};
         case 'list_conversations':
             return compact({ limit: envelope.limit });
+        case 'no_reply':
+            return compact({ conversationId: envelope.conversationId, messageId: envelope.messageId, reason: value.reason });
     }
 }
 /**

package/dist/verbContract.d.ts

@@ -15,7 +15,9 @@
  *
  * Deliberately NOT verbs: replying in the active conversation, streaming
  * partials, typing, and read receipts stay host-mediated — the model talks
- * and the platform delivers. Still out of scope pending their own design
+ * and the platform delivers. `no_reply` is the deliberate exception: it is the
+ * ABSENCE of a reply, and only an intent can express that — silence has no
+ * host-mediated channel of its own. Still out of scope pending their own design
  * pass: plan approval (the fourth runtime-interaction kind — coding-host
  * concern today) and block/mute. Their REST surfaces remain directly
  * callable.
@@ -159,6 +161,12 @@ export declare const VERB_LIMITS: {
      * CREATE does not length-check today — treat as the authoring contract).
      */
     readonly groupNameChars: 100;
+    /**
+     * `no_reply.reason` authoring cap. There is no server enforcement beyond the
+     * intent schema — the handler logs the reason's presence and nothing else —
+     * so this constant is the canonical figure.
+     */
+    readonly noReplyReasonChars: 500;
 };
 /**
  * Sender-side rate limits enforced by POST /messages/send
@@ -173,7 +181,7 @@ export declare const VERB_RATE_LIMITS: {
 /** The one self-context type the platform accepts today. */
 export declare const SELF_CONTEXT_TYPE = "cross_session";
 /** Canonical verb names. */
-export declare const CANON_VERB_NAMES: readonly ["send_to", "request_input", "request_approval", "check_approval", "send_card", "request_card", "share_contact", "react", "forward", "create_group", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_contact_requests", "list_conversations"];
+export declare const CANON_VERB_NAMES: readonly ["send_to", "request_input", "request_approval", "check_approval", "send_card", "request_card", "share_contact", "react", "forward", "create_group", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_contact_requests", "list_conversations", "no_reply"];
 export type CanonVerbName = (typeof CANON_VERB_NAMES)[number];
 /** Private note-to-self attached to a cross-conversation send. */
 export interface VerbSelfContext {
@@ -692,6 +700,25 @@ export interface VerbConversationSummary {
 export interface ListConversationsResult {
     conversations: VerbConversationSummary[];
 }
+/** Deliberate silence: end the turn without posting anything. */
+export interface NoReplyInput {
+    /** Bindings default this to the active conversation when they have one. */
+    conversationId?: string;
+    /** Private rationale — logged only, never rendered. <= noReplyReasonChars. */
+    reason?: string;
+}
+export interface NoReplyResult {
+    status: 'acknowledged';
+    conversationId?: string;
+    note?: string;
+}
+/**
+ * The `note` the server returns on a `no_reply` ack — the model's closure
+ * sentence. It lives here, not in a host, because every binding surfaces the
+ * server's result verbatim and a runtime that answers `no_reply` locally must
+ * say the same thing.
+ */
+export declare const NO_REPLY_ACK_NOTE = "Acknowledged \u2014 nothing was posted to the conversation.";
 /** Flat tool name for a verb on namespaced tool surfaces (e.g. `canon_send_to`). */
 export declare function canonVerbToolName(verb: CanonVerbName): string;
 export interface VerbLimitViolation {
@@ -791,6 +818,12 @@ export declare const CANON_VERB_LIMITS_ARTIFACT: {
          * CREATE does not length-check today — treat as the authoring contract).
          */
         readonly groupNameChars: 100;
+        /**
+         * `no_reply.reason` authoring cap. There is no server enforcement beyond the
+         * intent schema — the handler logs the reason's presence and nothing else —
+         * so this constant is the canonical figure.
+         */
+        readonly noReplyReasonChars: 500;
     };
     readonly rateLimits: {
         readonly senderMessagesPer5Min: 300;

package/dist/verbContract.js

@@ -15,7 +15,9 @@
  *
  * Deliberately NOT verbs: replying in the active conversation, streaming
  * partials, typing, and read receipts stay host-mediated — the model talks
- * and the platform delivers. Still out of scope pending their own design
+ * and the platform delivers. `no_reply` is the deliberate exception: it is the
+ * ABSENCE of a reply, and only an intent can express that — silence has no
+ * host-mediated channel of its own. Still out of scope pending their own design
  * pass: plan approval (the fourth runtime-interaction kind — coding-host
  * concern today) and block/mute. Their REST surfaces remain directly
  * callable.
@@ -159,6 +161,12 @@ export const VERB_LIMITS = {
      * CREATE does not length-check today — treat as the authoring contract).
      */
     groupNameChars: 100,
+    /**
+     * `no_reply.reason` authoring cap. There is no server enforcement beyond the
+     * intent schema — the handler logs the reason's presence and nothing else —
+     * so this constant is the canonical figure.
+     */
+    noReplyReasonChars: 500,
 };
 /**
  * Sender-side rate limits enforced by POST /messages/send
@@ -190,6 +198,7 @@ export const CANON_VERB_NAMES = [
     'list_contacts',
     'list_contact_requests',
     'list_conversations',
+    'no_reply',
 ];
 export const VERB_NATIVE_METADATA_KEYS = [
     'runtime',
@@ -265,6 +274,13 @@ export const CREATE_GROUP_NO_ADDABLE_MEMBERS_CODE = 'CREATE_GROUP_NO_ADDABLE_MEM
  * creates the group from the app instead).
  */
 export const CREATE_GROUP_CREATOR_SETUP_REQUIRED_CODE = 'CREATE_GROUP_CREATOR_SETUP_REQUIRED';
+/**
+ * The `note` the server returns on a `no_reply` ack — the model's closure
+ * sentence. It lives here, not in a host, because every binding surfaces the
+ * server's result verbatim and a runtime that answers `no_reply` locally must
+ * say the same thing.
+ */
+export const NO_REPLY_ACK_NOTE = 'Acknowledged — nothing was posted to the conversation.';
 /** Flat tool name for a verb on namespaced tool surfaces (e.g. `canon_send_to`). */
 export function canonVerbToolName(verb) {
     return `${CANON_VERB_NAMESPACE}_${verb}`;

package/dist/verbSchemas.d.ts

@@ -1700,6 +1700,43 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
                 };
             };
         };
+        readonly no_reply_input: {
+            readonly type: "object";
+            readonly description: string;
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly conversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly messageId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                    readonly description: "The triggering message this silence answers, so the record cannot be misread against a later message.";
+                };
+                readonly reason: {
+                    readonly type: "string";
+                    readonly maxLength: 500;
+                    readonly description: "Never rendered; logged only.";
+                };
+            };
+        };
+        readonly no_reply_result: {
+            readonly type: "object";
+            readonly required: readonly ["status"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly status: {
+                    readonly const: "acknowledged";
+                };
+                readonly conversationId: {
+                    readonly type: "string";
+                };
+                readonly note: {
+                    readonly type: "string";
+                };
+            };
+        };
     };
 };
 /** Pointer pair into the bundle for one verb. */

package/dist/verbSchemas.js

@@ -1053,6 +1053,35 @@ const list_conversations_result = {
         },
     },
 };
+const no_reply_input = {
+    type: 'object',
+    description: 'End this turn without posting anything to the conversation. Nothing is '
+        + 'rendered and no other member or agent is triggered.',
+    additionalProperties: false,
+    properties: {
+        conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        messageId: {
+            type: 'string',
+            pattern: VERB_ID_PATTERNS.runtimeId,
+            description: 'The triggering message this silence answers, so the record cannot be misread against a later message.',
+        },
+        reason: {
+            type: 'string',
+            maxLength: VERB_LIMITS.noReplyReasonChars,
+            description: 'Never rendered; logged only.',
+        },
+    },
+};
+const no_reply_result = {
+    type: 'object',
+    required: ['status'],
+    additionalProperties: true,
+    properties: {
+        status: { const: 'acknowledged' },
+        conversationId: { type: 'string' },
+        note: { type: 'string' },
+    },
+};
 // ---------------------------------------------------------------------------
 // Bundle
 // ---------------------------------------------------------------------------
@@ -1111,6 +1140,8 @@ export const CANON_VERBS_JSON_SCHEMA = {
         list_contact_requests_result,
         list_conversations_input,
         list_conversations_result,
+        no_reply_input,
+        no_reply_result,
     },
 };
 export const CANON_VERB_SCHEMA_REFS = Object.fromEntries(CANON_VERB_NAMES.map((name) => [

package/dist/verbWire.d.ts

@@ -137,7 +137,7 @@ export declare const CANON_VERB_WIRE_JSON_SCHEMA: {
             readonly const: "canon.verb-wire.v1";
         };
         readonly verb: {
-            readonly enum: readonly ["send_to", "request_input", "request_approval", "check_approval", "send_card", "request_card", "share_contact", "react", "forward", "create_group", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_contact_requests", "list_conversations"];
+            readonly enum: readonly ["send_to", "request_input", "request_approval", "check_approval", "send_card", "request_card", "share_contact", "react", "forward", "create_group", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_contact_requests", "list_conversations", "no_reply"];
         };
         readonly envelope: {
             readonly $ref: "#/$defs/envelope";
@@ -509,7 +509,7 @@ export declare const CANON_VERB_WIRE_JSON_SCHEMA: {
                     readonly const: "canon.verb-wire.v1";
                 };
                 readonly verb: {
-                    readonly enum: readonly ["send_to", "request_input", "request_approval", "check_approval", "send_card", "request_card", "share_contact", "react", "forward", "create_group", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_contact_requests", "list_conversations"];
+                    readonly enum: readonly ["send_to", "request_input", "request_approval", "check_approval", "send_card", "request_card", "share_contact", "react", "forward", "create_group", "add_member", "remove_member", "leave_conversation", "list_contacts", "list_contact_requests", "list_conversations", "no_reply"];
                 };
                 readonly result: {
                     readonly $ref: "#/$defs/body";

package/dist/verbWire.js

@@ -112,6 +112,7 @@ export const VERB_WIRE_ENVELOPE_FIELDS = {
     list_contacts: { required: [], optional: [] },
     list_contact_requests: { required: [], optional: [] },
     list_conversations: { required: [], optional: ['limit'] },
+    no_reply: { required: [], optional: ['conversationId', 'messageId'] },
 };
 // ---------------------------------------------------------------------------
 // JSON Schema
@@ -470,6 +471,11 @@ export function projectVerbIntentToWire(verb, intent, options) {
             envelope = compact({ limit: input.limit });
             break;
         }
+        case 'no_reply': {
+            envelope = compact({ conversationId: input.conversationId, messageId: input.messageId });
+            value = compact({ reason: input.reason });
+            break;
+        }
     }
     return {
         wire: CANON_VERB_WIRE_SCHEMA_VERSION,
@@ -607,6 +613,8 @@ export function mergeVerbWireToIntent(request) {
             return {};
         case 'list_conversations':
             return compact({ limit: envelope.limit });
+        case 'no_reply':
+            return compact({ conversationId: envelope.conversationId, messageId: envelope.messageId, reason: value.reason });
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "5.1.0",
+  "version": "5.3.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@canonmsg/rich-cards": "^0.8.7",
+    "@canonmsg/rich-cards": "^0.9.1",
     "@types/node": "^22.0.0",
     "ajv": "^8.20.0",
     "typescript": "~5.7.0",