@canonmsg/backend-contracts 5.0.0 → 5.2.0

package/dist/firestoreValues.js

@@ -0,0 +1,23 @@
+// 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.
+/** Trimmed string, or null when absent/empty. */
+export 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.
+ */
+export 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/index.d.ts

@@ -6,7 +6,13 @@ export * from './runtimeCardFields.js';
 export * from './runtimeCardStorage.js';
 export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';
+export * from './agentSearch.js';
 export * from './contactRequest.js';
+export * from './contactSources.js';
 export * from './verbContract.js';
 export * from './verbSchemas.js';
 export * from './verbWire.js';
+export * from './accessPolicy.js';
+export * from './firestoreValues.js';
+export * from './moderation.js';
+export * from './selfContext.js';

package/dist/index.js

@@ -6,7 +6,13 @@ export * from './runtimeCardFields.js';
 export * from './runtimeCardStorage.js';
 export * from './turnProtocol.js';
 export * from './agentBehaviorPolicy.js';
+export * from './agentSearch.js';
 export * from './contactRequest.js';
+export * from './contactSources.js';
 export * from './verbContract.js';
 export * from './verbSchemas.js';
 export * from './verbWire.js';
+export * from './accessPolicy.js';
+export * from './firestoreValues.js';
+export * from './moderation.js';
+export * from './selfContext.js';

package/dist/moderation.d.ts

@@ -0,0 +1,7 @@
+export type ModerationStatus = 'active' | 'ejected';
+/**
+ * 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.
+ */
+export declare function readModerationStatus(data: unknown): ModerationStatus;

package/dist/moderation.js

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export function readModerationStatus(data) {
+    const record = data;
+    return record?.status === 'ejected' ? 'ejected' : 'active';
+}

package/dist/runtimeCardFields.d.ts

@@ -1,4 +1,14 @@
-export type RuntimeCardFieldType = 'text' | 'textarea' | 'select' | 'multiSelect' | 'boolean' | 'date' | 'number' | 'currency' | 'searchSelect' | 'lineItems';
+/**
+ * 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.
+ */
+export declare const RUNTIME_CARD_FIELD_TYPES: readonly ["text", "textarea", "select", "multiSelect", "boolean", "date", "number", "currency", "searchSelect", "lineItems"];
+export type RuntimeCardFieldType = (typeof RUNTIME_CARD_FIELD_TYPES)[number];
 /**
  * Caps shared across runtime-card normalizers, response validation, and
  * authoring tools. Keep these backend-safe so Functions can import them.
@@ -15,7 +25,9 @@ export interface RuntimeCardFieldChoice {
     description?: string;
     preview?: string;
 }
-export type RuntimeCardLineItemColumnType = 'text' | 'number' | 'currency' | 'date' | 'select';
+/** Column cell types allowed inside a `lineItems` field. */
+export declare const RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES: readonly ["text", "number", "currency", "date", "select"];
+export type RuntimeCardLineItemColumnType = (typeof RUNTIME_CARD_LINE_ITEM_COLUMN_TYPES)[number];
 export interface RuntimeCardLineItemColumn {
     id: string;
     label: string;

package/dist/runtimeCardFields.js

@@ -1,3 +1,24 @@
+/**
+ * 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.
+ */
+export const 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.
@@ -8,6 +29,14 @@ export const RUNTIME_CARD_LIMITS = {
     lineItemColumns: 8,
     searchSelectChoices: 100,
 };
+/** Column cell types allowed inside a `lineItems` field. */
+export const 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/selfContext.d.ts

@@ -0,0 +1,9 @@
+/** Stored self-context id, or null when absent, empty, or path-like. */
+export declare function normalizeStoredSelfContextId(value: unknown): string | null;
+/**
+ * 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.
+ */
+export declare function serializeSelfContext(id: string, data: Record<string, unknown>): Record<string, unknown> | null;

package/dist/selfContext.js

@@ -0,0 +1,29 @@
+import { SELF_CONTEXT_TYPE } from './verbContract.js';
+import { firestoreTimestampToISOString, normalizeStoredString } from './firestoreValues.js';
+/** Stored self-context id, or null when absent, empty, or path-like. */
+export function normalizeStoredSelfContextId(value) {
+    const id = 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.
+ */
+export function serializeSelfContext(id, data) {
+    if (data.type !== SELF_CONTEXT_TYPE)
+        return null;
+    const context = normalizeStoredString(data.context);
+    if (!context)
+        return null;
+    return {
+        id,
+        type: SELF_CONTEXT_TYPE,
+        context,
+        createdAt: firestoreTimestampToISOString(data.createdAt),
+        updatedAt: firestoreTimestampToISOString(data.updatedAt),
+    };
+}

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,38 @@ 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 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,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: VERB_ID_PATTERNS.runtimeId },
+        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 +1135,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'] },
 };
 // ---------------------------------------------------------------------------
 // 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 });
+            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, reason: value.reason });
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "5.0.0",
+  "version": "5.2.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",