@canonmsg/backend-contracts 5.0.0 → 5.2.0

package/dist/cjs/agentBehaviorPolicy.js

@@ -1,15 +1,41 @@
 "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;
+exports.getDefaultParticipationPolicy = getDefaultParticipationPolicy;
 exports.resolveAgentBehaviorPolicy = resolveAgentBehaviorPolicy;
 exports.buildParticipationHistorySnapshot = buildParticipationHistorySnapshot;
 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',
@@ -129,6 +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;
@@ -147,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] : []),
@@ -159,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;
 }
@@ -205,37 +258,71 @@ function appendParticipationHistoryMessage(snapshot, message, limit = exports.PA
     ].slice(0, limit));
 }
 function evaluateParticipationPolicy(policy, input) {
-    const consecutiveAgentTurns = Math.max(input.consecutiveAgentTurns ?? (input.senderType === 'ai_agent' ? 1 : 0), input.senderType === 'ai_agent' ? 1 : 0);
+    const resolved = policy ?? resolveAgentBehaviorPolicy({ conversationType: input.conversationType });
+    const participation = resolved.participation;
+    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'
-        && policy.participation.requireMentionForGroupReplies
+        && participation.requireMentionForGroupReplies
         && !input.mentionedAgent) {
         return {
             allow: false,
+            reasonCode: 'group_mention_required',
             reason: 'group replies require a direct mention',
         };
     }
     if (input.isOwner) {
-        return { allow: true, reason: 'owner messages pass through outside mention-required group turns' };
+        return {
+            allow: true,
+            reasonCode: 'owner_sender',
+            reason: 'owner messages pass through outside mention-required group turns',
+        };
     }
     if (input.senderType !== 'ai_agent') {
-        return { allow: true, reason: 'latest sender is human' };
+        return { allow: true, reasonCode: 'human_sender', reason: 'latest sender is human' };
     }
-    if (!policy.participation.allowAgentToAgent) {
-        return { allow: false, reason: 'agent-to-agent participation disabled by policy' };
+    if (!participation.allowAgentToAgent) {
+        return {
+            allow: false,
+            reasonCode: 'agent_to_agent_disabled',
+            reason: 'agent-to-agent participation is disabled by policy',
+        };
     }
-    if (!policy.participation.allowLongRunningCollaboration
+    if (!participation.allowLongRunningCollaboration
         && (consecutiveAgentTurns > 1
             || !currentAgentStreakStartedByHuman)) {
         return {
             allow: false,
+            reasonCode: 'human_reset_required',
             reason: 'a fresh human steer is required before continuing agent collaboration',
         };
     }
-    if (typeof policy.participation.maxConsecutiveAgentTurns === 'number'
-        && policy.participation.maxConsecutiveAgentTurns >= 0
-        && consecutiveAgentTurns > policy.participation.maxConsecutiveAgentTurns) {
-        return { allow: false, reason: 'maximum consecutive agent turns reached' };
+    // `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
+        && agentTurnsWithCurrent >= participation.maxConsecutiveAgentTurns) {
+        return {
+            allow: false,
+            reasonCode: 'agent_turn_limit_reached',
+            reason: 'maximum consecutive agent turns reached',
+        };
     }
-    return { allow: true, reason: 'agent-to-agent participation allowed by policy' };
+    return {
+        allow: true,
+        reasonCode: input.conversationType === 'group' ? 'group_agent_allowed' : 'direct_agent_allowed',
+        reason: participation.requireMentionForGroupReplies
+            ? 'policy allows this directly mentioned group reply'
+            : 'agent-to-agent participation allowed by policy',
+    };
 }

package/dist/cjs/agentSearch.js

@@ -0,0 +1,64 @@
+"use strict";
+// The single agent-directory search implementation, shared by Cloud Functions
+// (which writes `users/{agentId}.searchPrefixes` and filters discovery reads)
+// and `@canonmsg/chat-domain` (which filters the same agents client-side in the
+// app and on web). The server index and the client filter must agree, so both
+// sides derive from these bodies rather than from hand-synced copies.
+//
+// Pure ECMAScript: no imports, no Node built-ins, no Firestore types — safe in
+// CJS, in the browser bundle, and on Hermes.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAgentDirectoryQuery = normalizeAgentDirectoryQuery;
+exports.getAgentDirectoryQueryTokens = getAgentDirectoryQueryTokens;
+exports.buildAgentSearchPrefixes = buildAgentSearchPrefixes;
+exports.matchesAgentSearchQuery = matchesAgentSearchQuery;
+const MAX_QUERY_LENGTH = 64;
+const MAX_TOKEN_PREFIX_LENGTH = 32;
+const MAX_SEARCH_PREFIXES = 256;
+const TOKEN_PATTERN = /[\p{L}\p{N}]+/gu;
+function tokenizeAgentSearchValue(value) {
+    const normalized = value
+        .normalize('NFKD')
+        .toLowerCase()
+        .trim();
+    return normalized.match(TOKEN_PATTERN) ?? [];
+}
+/** Tolerant: non-string input normalises to ''. */
+function normalizeAgentDirectoryQuery(value) {
+    if (typeof value !== 'string')
+        return '';
+    return tokenizeAgentSearchValue(value).join(' ').slice(0, MAX_QUERY_LENGTH);
+}
+function getAgentDirectoryQueryTokens(query) {
+    return tokenizeAgentSearchValue(query).map((token) => token.slice(0, MAX_QUERY_LENGTH));
+}
+function buildAgentSearchPrefixes(input) {
+    const seen = new Set();
+    for (const token of tokenizeAgentSearchValue([input.displayName, input.description].filter(Boolean).join(' '))) {
+        const normalizedToken = token.slice(0, MAX_QUERY_LENGTH);
+        const prefixLength = Math.min(normalizedToken.length, MAX_TOKEN_PREFIX_LENGTH);
+        for (let index = 1; index <= prefixLength; index += 1) {
+            seen.add(normalizedToken.slice(0, index));
+            if (seen.size >= MAX_SEARCH_PREFIXES) {
+                return [...seen];
+            }
+        }
+        if (normalizedToken.length > MAX_TOKEN_PREFIX_LENGTH) {
+            seen.add(normalizedToken);
+            if (seen.size >= MAX_SEARCH_PREFIXES) {
+                return [...seen];
+            }
+        }
+    }
+    return [...seen];
+}
+function matchesAgentSearchQuery(profile, query) {
+    const tokens = getAgentDirectoryQueryTokens(query);
+    if (tokens.length === 0)
+        return true;
+    const prefixes = new Set(buildAgentSearchPrefixes({
+        displayName: profile.displayName,
+        description: profile.agentConfig?.description,
+    }));
+    return tokens.every((token) => prefixes.has(token));
+}

package/dist/cjs/contactSources.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADMISSION_GRANTING_SOURCES = void 0;
+exports.isAdmissionGrantingContactSource = isAdmissionGrantingContactSource;
+/**
+ * Sources that represent a user-initiated relationship which grants admission
+ * past `inboundPolicy: 'approval-required'` and
+ * `groupJoinPolicy: 'approval-required'`.
+ *
+ * - `contact_request`: an explicit approval flow.
+ * - `direct_add`: the user added the other side directly.
+ * - `link` / `qr`: out-of-band invitations that imply consent.
+ * - `group`: established by being in a shared group.
+ * - `phone_book`: included intentionally — if a human has a registered Canon
+ *   user in their device contacts, that is enough to start a human-human DM
+ *   without a separate Canon request.
+ * - `open_inbound_message`: the unified source written when a delivered direct
+ *   interaction reaches an `inboundPolicy: 'open'` recipient. The recipient
+ *   consented to open inbound; the resulting mutual contact is real.
+ *
+ * Hard caps (`owner-only`, blocks, inactive agent) override admission grants
+ * regardless of source — ordering lives in `functions/src/utils/access.ts`
+ * (`evaluatePolicy` / `buildPolicyContext`).
+ */
+const ADMISSION_GRANTING_CONTACT_SOURCES = [
+    'contact_request',
+    'direct_add',
+    'link',
+    'qr',
+    'group',
+    'phone_book',
+    'open_inbound_message',
+];
+exports.ADMISSION_GRANTING_SOURCES = new Set(ADMISSION_GRANTING_CONTACT_SOURCES);
+/**
+ * Returns true if a contact-doc source counts as an admission-granting
+ * relationship. `null` / `undefined` (no doc, or doc with a missing source)
+ * both return `false` — every contact doc must have an explicit source after
+ * the cleanup.
+ */
+function isAdmissionGrantingContactSource(source) {
+    if (source === null || source === undefined)
+        return false;
+    return exports.ADMISSION_GRANTING_SOURCES.has(source);
+}

package/dist/cjs/firestoreValues.js

@@ -0,0 +1,27 @@
+"use strict";
+// Normalizers for values read straight off a Firestore document. Callers pass
+// plain doc-shaped data, never a Firestore handle — this package holds no I/O.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeStoredString = normalizeStoredString;
+exports.firestoreTimestampToISOString = firestoreTimestampToISOString;
+/** Trimmed string, or null when absent/empty. */
+function normalizeStoredString(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Firestore Timestamp-like -> ISO 8601, or null. Accepts only objects exposing
+ * `toDate()`. A raw `Date` is deliberately NOT accepted: that matches both call
+ * sites this replaced. `message.ts` and `contactRequest.ts` keep their own
+ * Date-tolerant normalizers — a different contract, not this one.
+ */
+function firestoreTimestampToISOString(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const maybeTimestamp = value;
+    if (typeof maybeTimestamp.toDate !== 'function')
+        return null;
+    return maybeTimestamp.toDate().toISOString();
+}

package/dist/cjs/index.js

@@ -22,7 +22,13 @@ __exportStar(require("./runtimeCardFields.js"), exports);
 __exportStar(require("./runtimeCardStorage.js"), exports);
 __exportStar(require("./turnProtocol.js"), exports);
 __exportStar(require("./agentBehaviorPolicy.js"), exports);
+__exportStar(require("./agentSearch.js"), exports);
 __exportStar(require("./contactRequest.js"), exports);
+__exportStar(require("./contactSources.js"), exports);
 __exportStar(require("./verbContract.js"), exports);
 __exportStar(require("./verbSchemas.js"), exports);
 __exportStar(require("./verbWire.js"), exports);
+__exportStar(require("./accessPolicy.js"), exports);
+__exportStar(require("./firestoreValues.js"), exports);
+__exportStar(require("./moderation.js"), exports);
+__exportStar(require("./selfContext.js"), exports);

package/dist/cjs/moderation.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readModerationStatus = readModerationStatus;
+/**
+ * The single definition of "this account is ejected", read off an
+ * already-fetched `moderationUsers/{id}` document. A missing document reads
+ * 'active'. Fetching is the caller's job — this package holds no Firestore handle.
+ */
+function readModerationStatus(data) {
+    const record = data;
+    return record?.status === 'ejected' ? 'ejected' : 'active';
+}

package/dist/cjs/runtimeCardFields.js

@@ -1,7 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RUNTIME_CARD_LIMITS = void 0;
+exports.RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES = exports.RUNTIME_CARD_LIMITS = exports.RUNTIME_CARD_FIELD_TYPES = void 0;
 exports.validateRuntimeCardFieldValues = validateRuntimeCardFieldValues;
+/**
+ * Canonical `canon.card.v1` action-field type vocabulary. The runtime array is
+ * the single source of truth and the type is derived from it, so a value and a
+ * type cannot drift.
+ *
+ * ORDER IS LOAD-BEARING: scripts/generate-skill-bundles.mjs renders this list
+ * verbatim (via @canonmsg/rich-cards) into two committed SKILL.md files, and
+ * `npm run check:skill-bundles` fails on a byte change.
+ */
+exports.RUNTIME_CARD_FIELD_TYPES = [
+    'text',
+    'textarea',
+    'select',
+    'multiSelect',
+    'boolean',
+    'date',
+    'number',
+    'currency',
+    'searchSelect',
+    'lineItems',
+];
 /**
  * Caps shared across runtime-card normalizers, response validation, and
  * authoring tools. Keep these backend-safe so Functions can import them.
@@ -12,6 +33,14 @@ exports.RUNTIME_CARD_LIMITS = {
     lineItemColumns: 8,
     searchSelectChoices: 100,
 };
+/** Column cell types allowed inside a `lineItems` field. */
+exports.RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES = [
+    'text',
+    'number',
+    'currency',
+    'date',
+    'select',
+];
 const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);

package/dist/cjs/selfContext.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeStoredSelfContextId = normalizeStoredSelfContextId;
+exports.serializeSelfContext = serializeSelfContext;
+const verbContract_js_1 = require("./verbContract.js");
+const firestoreValues_js_1 = require("./firestoreValues.js");
+/** Stored self-context id, or null when absent, empty, or path-like. */
+function normalizeStoredSelfContextId(value) {
+    const id = (0, firestoreValues_js_1.normalizeStoredString)(value);
+    if (!id || id.includes('/'))
+        return null;
+    return id;
+}
+/**
+ * Agent-facing projection of an `agentSelfContexts` document; null for anything
+ * that is not a usable cross-session context. Ownership and conversation
+ * scoping stay with the CALLER — both consumers check them against their own
+ * Firestore handle before calling this.
+ */
+function serializeSelfContext(id, data) {
+    if (data.type !== verbContract_js_1.SELF_CONTEXT_TYPE)
+        return null;
+    const context = (0, firestoreValues_js_1.normalizeStoredString)(data.context);
+    if (!context)
+        return null;
+    return {
+        id,
+        type: verbContract_js_1.SELF_CONTEXT_TYPE,
+        context,
+        createdAt: (0, firestoreValues_js_1.firestoreTimestampToISOString)(data.createdAt),
+        updatedAt: (0, firestoreValues_js_1.firestoreTimestampToISOString)(data.updatedAt),
+    };
+}

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,30 @@ 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 },
+        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 +1140,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'] },
 };
 // ---------------------------------------------------------------------------
 // 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 });
+            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, reason: value.reason });
     }
 }
 /**

package/dist/contactSources.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Sources that represent a user-initiated relationship which grants admission
+ * past `inboundPolicy: 'approval-required'` and
+ * `groupJoinPolicy: 'approval-required'`.
+ *
+ * - `contact_request`: an explicit approval flow.
+ * - `direct_add`: the user added the other side directly.
+ * - `link` / `qr`: out-of-band invitations that imply consent.
+ * - `group`: established by being in a shared group.
+ * - `phone_book`: included intentionally — if a human has a registered Canon
+ *   user in their device contacts, that is enough to start a human-human DM
+ *   without a separate Canon request.
+ * - `open_inbound_message`: the unified source written when a delivered direct
+ *   interaction reaches an `inboundPolicy: 'open'` recipient. The recipient
+ *   consented to open inbound; the resulting mutual contact is real.
+ *
+ * Hard caps (`owner-only`, blocks, inactive agent) override admission grants
+ * regardless of source — ordering lives in `functions/src/utils/access.ts`
+ * (`evaluatePolicy` / `buildPolicyContext`).
+ */
+declare const ADMISSION_GRANTING_CONTACT_SOURCES: readonly ["contact_request", "direct_add", "link", "qr", "group", "phone_book", "open_inbound_message"];
+export type AdmissionGrantingContactSource = (typeof ADMISSION_GRANTING_CONTACT_SOURCES)[number];
+export declare const ADMISSION_GRANTING_SOURCES: ReadonlySet<AdmissionGrantingContactSource>;
+/**
+ * Returns true if a contact-doc source counts as an admission-granting
+ * relationship. `null` / `undefined` (no doc, or doc with a missing source)
+ * both return `false` — every contact doc must have an explicit source after
+ * the cleanup.
+ */
+export declare function isAdmissionGrantingContactSource(source: string | null | undefined): boolean;
+export {};

package/dist/contactSources.js

@@ -0,0 +1,41 @@
+/**
+ * Sources that represent a user-initiated relationship which grants admission
+ * past `inboundPolicy: 'approval-required'` and
+ * `groupJoinPolicy: 'approval-required'`.
+ *
+ * - `contact_request`: an explicit approval flow.
+ * - `direct_add`: the user added the other side directly.
+ * - `link` / `qr`: out-of-band invitations that imply consent.
+ * - `group`: established by being in a shared group.
+ * - `phone_book`: included intentionally — if a human has a registered Canon
+ *   user in their device contacts, that is enough to start a human-human DM
+ *   without a separate Canon request.
+ * - `open_inbound_message`: the unified source written when a delivered direct
+ *   interaction reaches an `inboundPolicy: 'open'` recipient. The recipient
+ *   consented to open inbound; the resulting mutual contact is real.
+ *
+ * Hard caps (`owner-only`, blocks, inactive agent) override admission grants
+ * regardless of source — ordering lives in `functions/src/utils/access.ts`
+ * (`evaluatePolicy` / `buildPolicyContext`).
+ */
+const ADMISSION_GRANTING_CONTACT_SOURCES = [
+    'contact_request',
+    'direct_add',
+    'link',
+    'qr',
+    'group',
+    'phone_book',
+    'open_inbound_message',
+];
+export const ADMISSION_GRANTING_SOURCES = new Set(ADMISSION_GRANTING_CONTACT_SOURCES);
+/**
+ * Returns true if a contact-doc source counts as an admission-granting
+ * relationship. `null` / `undefined` (no doc, or doc with a missing source)
+ * both return `false` — every contact doc must have an explicit source after
+ * the cleanup.
+ */
+export function isAdmissionGrantingContactSource(source) {
+    if (source === null || source === undefined)
+        return false;
+    return ADMISSION_GRANTING_SOURCES.has(source);
+}

package/dist/firestoreValues.d.ts

@@ -0,0 +1,9 @@
+/** Trimmed string, or null when absent/empty. */
+export declare function normalizeStoredString(value: unknown): string | null;
+/**
+ * Firestore Timestamp-like -> ISO 8601, or null. Accepts only objects exposing
+ * `toDate()`. A raw `Date` is deliberately NOT accepted: that matches both call
+ * sites this replaced. `message.ts` and `contactRequest.ts` keep their own
+ * Date-tolerant normalizers — a different contract, not this one.
+ */
+export declare function firestoreTimestampToISOString(value: unknown): string | null;