@canonmsg/backend-contracts 2.1.0 → 2.2.0

package/dist/verbContract.js

@@ -0,0 +1,283 @@
+/**
+ * Canon agent verb contract — the canonical, runtime-agnostic vocabulary for
+ * the conversational/HITL actions an agent deliberately takes against Canon
+ * (v1 scope: messaging, HITL interactions, contact sharing, and the read
+ * verbs bindings need alongside them).
+ *
+ * One verb = one intent-level action. Each runtime binding (Hermes native
+ * tool, MCP server, codex dynamicTools, agent-sdk method, CLI) projects these
+ * verbs into its native tool surface; the names, argument shapes, limits, and
+ * result vocabularies defined here are the single source of truth. JSON
+ * Schemas for each verb live in `verbSchemas.ts` and are also emitted as a
+ * plain JSON artifact at build time (`dist/canon-verbs.schema.json`) so
+ * non-TypeScript consumers (the Python hermes plugin, external integrators)
+ * can consume the identical contract.
+ *
+ * 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
+ * pass: plan approval (the fourth runtime-interaction kind — coding-host
+ * concern today) and block/mute. Their REST surfaces remain directly
+ * callable.
+ *
+ * Scope note: this module DESCRIBES the contract (canonical shapes + the
+ * server-enforced limits, with enforcement sites cited). Enforcement itself
+ * stays where it runs today — functions/src. Server-side verb endpoints that
+ * validate against these schemas are a planned follow-up.
+ *
+ * Normativity: the JSON Schemas in `verbSchemas.ts` (and the emitted
+ * canon-verbs.schema.json) are the normative contract. The TypeScript types
+ * here are a convenience projection — corrections flow schema -> type, and
+ * the dual-witness fixtures in verbContract.test.ts (each fixture is both
+ * compile-checked against the type and validated against the schema) guard
+ * the two from drifting. Single-sourcing the types from the schemas is a
+ * planned follow-up.
+ *
+ * Byte-sensitive limits: JSON Schema `maxLength` counts UTF-16 code units,
+ * but several server limits count UTF-8 bytes or serialized-JSON length,
+ * which no standard keyword expresses. Bindings MUST run
+ * `findVerbByteLimitViolations()` (or equivalent checks from the emitted
+ * canon-verbs.limits.json) after schema validation.
+ */
+/** Identifier for this contract document. */
+export const CANON_VERBS_SCHEMA_VERSION = 'canon.verbs.v1';
+/** $id of the emitted JSON Schema bundle. */
+export const CANON_VERBS_SCHEMA_ID = 'https://canonmsg.com/schemas/canon.verbs.v1.json';
+/** Namespace prefix bindings should use for flat tool names (e.g. `canon_send_to`). */
+export const CANON_VERB_NAMESPACE = 'canon';
+/**
+ * $id of the canonical canon.card.v1 document schema
+ * (@canonmsg/rich-cards RUNTIME_CARD_JSON_SCHEMA_V1). The verbs bundle only
+ * validates the card ENVELOPE; compose the full document schema into card
+ * verbs via `getVerbInputSchema(verb, { cardSchema })`.
+ */
+export const CANON_CARD_SCHEMA_ID = 'https://canonmsg.com/schemas/canon.card.v1.json';
+/**
+ * Identifier patterns, mirrored from the enforcing sites:
+ * - RUNTIME_ID_PATTERN: conversation/input/approval ids —
+ *   functions/src/utils/runtimeRequestHelpers.ts (`/^[A-Za-z0-9_.:-]{1,160}$/`)
+ * - CARD_ID_PATTERN / ACTION_ID_PATTERN: functions/src/api/interactionCard.ts
+ *   and @canonmsg/rich-cards RUNTIME_CARD_ACTION_ID_PATTERN (80 chars)
+ * - QUESTION_ID_PATTERN: functions/src/api/interactionInput.ts (120 chars)
+ * - SESSION_RULE_TOOL_PATTERN: functions/src/callable/respondToInteraction.ts
+ */
+export const VERB_ID_PATTERNS = {
+    runtimeId: '^[A-Za-z0-9_.:-]{1,160}$',
+    cardId: '^[A-Za-z0-9_.:-]{1,80}$',
+    actionId: '^[A-Za-z0-9_.:-]{1,80}$',
+    questionId: '^[A-Za-z0-9_.:-]{1,120}$',
+    sessionRuleToolPattern: '^[\\w.*:-]{1,128}$',
+};
+/**
+ * Server-enforced limits, single-sourced. Each value cites its enforcement
+ * site; keep the citation current when a limit moves.
+ */
+export const VERB_LIMITS = {
+    /** Message text — UTF-8 bytes (functions/src/api/sendMessage.ts MAX_MESSAGE_TEXT_BYTES). */
+    messageTextBytes: 4096,
+    /**
+     * Serialized metadata JSON length in UTF-16 code units — the server checks
+     * JSON.stringify(metadata).length, not bytes (sendMessage.ts:716-724 inline;
+     * parseBody.ts maxJsonBytes despite the name).
+     */
+    messageMetadataJsonChars: 4096,
+    /** Attachments per message (sendMessage.ts MAX_MESSAGE_ATTACHMENTS). */
+    messageAttachments: 10,
+    /** Client-supplied messageId — chars and UTF-8 bytes (sendMessage.ts). */
+    messageIdChars: 160,
+    messageIdBytes: 256,
+    /** Self-context note (functions/src/utils/selfContexts.ts SELF_CONTEXT_CONTEXT_LIMIT). */
+    selfContextChars: 1000,
+    /**
+     * Contact-request note. Values longer than this are truncated by senders
+     * (slice(0,497)+'...') — the truncation is currently triplicated in
+     * functions/src/api/sendContextualMessage.ts, packages/core/src/reach-out.ts
+     * and the hermes plugin; this constant is the canonical figure.
+     */
+    contactRequestNoteChars: 500,
+    /** Group membership cap incl. creator (functions/src/utils/conversations.ts MAX_GROUP_MEMBERS). */
+    groupMembers: 50,
+    /** Runtime input (functions/src/api/interactionInput.ts). */
+    inputTitleChars: 160,
+    inputPromptChars: 4000,
+    inputChoices: 12,
+    inputChoiceLabelChars: 120,
+    inputChoiceValueChars: 200,
+    inputChoiceDescriptionChars: 300,
+    inputQuestions: 12,
+    inputQuestionChars: 1000,
+    inputQuestionHeaderChars: 120,
+    inputSecretNameChars: 160,
+    inputAnswerChars: 8192,
+    /** Approval (functions/src/api/interactionApproval.ts). */
+    toolNameChars: 128,
+    toolSummaryChars: 1000,
+    approvalDetails: 8,
+    approvalDetailLabelChars: 80,
+    approvalDetailValueChars: 500,
+    diffFiles: 100,
+    diffPathChars: 1024,
+    diffFileBytes: 24 * 1024,
+    diffTotalBytes: 96 * 1024,
+    /** Card envelope acceptance (functions/src/api/interactionCard.ts — server caps;
+     * authoring caps in @canonmsg/rich-cards are stricter: title 120, fallback 500, blocks 24). */
+    cardEnvelopeBytes: 32 * 1024,
+    cardServerTitleChars: 200,
+    cardServerFallbackTextChars: 2000,
+    cardServerBlocks: 64,
+    /** Response-values caps enforced on submit (callable respondToInteraction.ts
+     * MAX_VALUES_BYTES/MAX_VALUES_DEPTH; interactionCard.ts re-checks bytes on
+     * consume via MAX_REPLY_BYTES). */
+    cardValuesBytes: 8 * 1024,
+    cardValuesDepth: 8,
+    /** Native correlation metadata (functions/src/api/interactionKinds.ts normalizeNative). */
+    nativeKeys: 24,
+    nativeValueChars: 256,
+    nativeHandles: 16,
+    /** Deadlines (functions/src/utils/runtimeRequestHelpers.ts). */
+    minTimeoutMs: 1000,
+    /** input/card/plan ceiling (30 minutes). */
+    maxTimeoutMs: 30 * 60 * 1000,
+    /** approval-only ceiling (72 hours — owner ruling 2026-07-10). */
+    maxApprovalTimeoutMs: 72 * 60 * 60 * 1000,
+    /** turnId / runtimeId fields on interaction creators. */
+    turnIdChars: 128,
+    /** Reaction key (functions/src/api/reactToMessage.ts normalizeReactionKey). */
+    reactionEmojiChars: 64,
+    /**
+     * Group name authoring cap (enforced on rename via updateNameServer; group
+     * CREATE does not length-check today — treat as the authoring contract).
+     */
+    groupNameChars: 100,
+};
+/**
+ * Sender-side rate limits enforced by POST /messages/send
+ * (functions/src/api/sendMessage.ts). Bindings should surface 429s with the
+ * retryAfter the server returns rather than re-deriving these.
+ */
+export const VERB_RATE_LIMITS = {
+    senderMessagesPer5Min: 300,
+    conversationMessagesPer5Min: 120,
+    agentPeerMessagesPerHour: 30,
+};
+/** The one self-context type the platform accepts today. */
+export const SELF_CONTEXT_TYPE = 'cross_session';
+/** Canonical verb names. */
+export const CANON_VERB_NAMES = [
+    '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',
+];
+/**
+ * Error code on the 400 a create_group receives when NO member is directly
+ * addable (approval-required members can only be invited to an existing
+ * group; a creator-only group is not created). The error detail carries the
+ * partition: pendingRequired[] and skipped[].
+ */
+export const CREATE_GROUP_NO_ADDABLE_MEMBERS_CODE = 'CREATE_GROUP_NO_ADDABLE_MEMBERS';
+/**
+ * Error code on the 403 a create_group receives when the CREATOR itself is
+ * a coding agent requiring explicit session setup: the group helper prepares
+ * session configs for every coding-agent member including the creator, and
+ * only the agent's human owner may provide them (v1 scoping — the owner
+ * creates the group from the app instead).
+ */
+export const CREATE_GROUP_CREATOR_SETUP_REQUIRED_CODE = 'CREATE_GROUP_CREATOR_SETUP_REQUIRED';
+/** Flat tool name for a verb on namespaced tool surfaces (e.g. `canon_send_to`). */
+export function canonVerbToolName(verb) {
+    return `${CANON_VERB_NAMESPACE}_${verb}`;
+}
+const utf8Bytes = (value) => new TextEncoder().encode(value).length;
+function checkTextBytes(path, value, into) {
+    if (typeof value === 'string' && utf8Bytes(value) > VERB_LIMITS.messageTextBytes) {
+        into.push({
+            path,
+            message: `text exceeds ${VERB_LIMITS.messageTextBytes} UTF-8 bytes (sendMessage.ts MAX_MESSAGE_TEXT_BYTES)`,
+        });
+    }
+}
+function checkMessageId(path, value, into) {
+    if (typeof value === 'string' && utf8Bytes(value) > VERB_LIMITS.messageIdBytes) {
+        into.push({
+            path,
+            message: `messageId exceeds ${VERB_LIMITS.messageIdBytes} UTF-8 bytes (sendMessage.ts MAX_MESSAGE_ID_BYTES)`,
+        });
+    }
+}
+/**
+ * The server limits JSON Schema cannot express: UTF-8 byte caps and
+ * serialized-JSON length caps. Bindings MUST run this after schema
+ * validation; the server enforces the same checks with 400s.
+ */
+export function findVerbByteLimitViolations(verb, input) {
+    const violations = [];
+    if (verb === 'send_to' || verb === 'share_contact' || verb === 'forward') {
+        checkTextBytes('text', input.text, violations);
+    }
+    if (verb === 'share_contact') {
+        checkMessageId('messageId', input.messageId, violations);
+    }
+    if (verb === 'send_to') {
+        const options = input.messageOptions;
+        if (options && typeof options === 'object' && !Array.isArray(options)) {
+            const record = options;
+            checkMessageId('messageOptions.messageId', record.messageId, violations);
+            if (record.metadata !== undefined) {
+                const serialized = JSON.stringify(record.metadata);
+                if (typeof serialized === 'string' && serialized.length > VERB_LIMITS.messageMetadataJsonChars) {
+                    violations.push({
+                        path: 'messageOptions.metadata',
+                        message: `metadata serializes to more than ${VERB_LIMITS.messageMetadataJsonChars} JSON characters `
+                            + '(sendMessage.ts checks JSON.stringify length)',
+                    });
+                }
+            }
+        }
+    }
+    if (verb === 'send_card' || verb === 'request_card') {
+        if (input.card !== undefined) {
+            const serialized = JSON.stringify(input.card);
+            if (typeof serialized === 'string' && utf8Bytes(serialized) > VERB_LIMITS.cardEnvelopeBytes) {
+                violations.push({
+                    path: 'card',
+                    message: `card serializes to more than ${VERB_LIMITS.cardEnvelopeBytes} bytes (interactionCard.ts MAX_CARD_BYTES)`,
+                });
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Machine-readable limits companion to the schema bundle, emitted as
+ * dist/canon-verbs.limits.json so non-TypeScript bindings can apply the
+ * byte-sensitive checks JSON Schema cannot express.
+ */
+export const CANON_VERB_LIMITS_ARTIFACT = {
+    schemaVersion: CANON_VERBS_SCHEMA_VERSION,
+    limits: VERB_LIMITS,
+    rateLimits: VERB_RATE_LIMITS,
+    idPatterns: VERB_ID_PATTERNS,
+    byteSemantics: {
+        'send_to.text': 'utf8_bytes<=messageTextBytes',
+        'share_contact.text': 'utf8_bytes<=messageTextBytes',
+        'forward.text': 'utf8_bytes<=messageTextBytes',
+        'send_to.messageOptions.messageId': 'utf8_bytes<=messageIdBytes',
+        'share_contact.messageId': 'utf8_bytes<=messageIdBytes',
+        'send_to.messageOptions.metadata': 'json_stringify_chars<=messageMetadataJsonChars',
+        'send_card.card': 'json_utf8_bytes<=cardEnvelopeBytes',
+        'request_card.card': 'json_utf8_bytes<=cardEnvelopeBytes',
+    },
+};