@canonmsg/backend-contracts 2.0.0 → 2.2.0

package/dist/verbSchemas.js

@@ -0,0 +1,1139 @@
+/**
+ * JSON Schemas (draft 2020-12) for the Canon agent verb contract.
+ *
+ * One bundled document, `$id` canon.verbs.v1.json, with a `<verb>_input` and
+ * `<verb>_result` definition per verb under `$defs` plus shared shapes. The
+ * document is emitted verbatim to `dist/canon-verbs.schema.json` at build
+ * time (see scripts/emit-verb-schemas.mjs) so non-TypeScript bindings can
+ * consume the byte-identical contract instead of hand-porting it (the Python
+ * hermes plugin adopts it in a follow-up PR; external integrators and
+ * generated CLIs read it from the npm package).
+ *
+ * Conventions:
+ * - Verb INPUT schemas are strict (`additionalProperties: false`) — a binding
+ *   must not invent fields.
+ * - Verb RESULT schemas are open (`additionalProperties: true`) — servers may
+ *   add fields; consumers must tolerate them. The STATUS vocabularies are
+ *   deliberately closed per major contract version: a new status requires a
+ *   canon.verbs.v2 (or an additive bundle revision), so bindings should fail
+ *   closed on unknown statuses.
+ * - `maxLength` counts UTF-16 code units; where the server enforces UTF-8
+ *   BYTES the description says so and the maxLength is the byte figure (a
+ *   permissive approximation — multibyte text within the char count can still
+ *   exceed the server's byte cap). Bindings MUST therefore run
+ *   `findVerbByteLimitViolations()` after schema validation (the same checks
+ *   ship machine-readably as dist/canon-verbs.limits.json).
+ * - Server enforcement sites are cited in descriptions; this document
+ *   describes, functions/src enforces (until the planned /agent/verbs/*
+ *   endpoints validate against these schemas directly).
+ */
+import { CANON_VERBS_SCHEMA_ID, CANON_VERB_NAMES, SELF_CONTEXT_TYPE, VERB_ID_PATTERNS, VERB_LIMITS, } from './verbContract.js';
+const REF = (def) => ({ $ref: `#/$defs/${def}` });
+const selfContextDef = {
+    type: 'object',
+    description: 'Private note-to-self attached to a cross-conversation send. Visible only to the '
+        + 'sending agent (surfaced back as provenance.activeSelfContext); never shown to '
+        + 'recipients. Enforced by functions/src/utils/selfContexts.ts.',
+    required: ['type', 'context'],
+    additionalProperties: false,
+    properties: {
+        type: { const: SELF_CONTEXT_TYPE },
+        context: {
+            type: 'string',
+            minLength: 1,
+            maxLength: VERB_LIMITS.selfContextChars,
+            description: 'What future-you needs to know about this transfer.',
+        },
+    },
+};
+const sessionSelectionDef = {
+    description: 'How to pick the conversation when targeting a user whose chats are session-shaped '
+        + '(agent targets). Canon default for user-targeted sends: continue_or_create.',
+    oneOf: [
+        {
+            type: 'object',
+            required: ['mode'],
+            additionalProperties: false,
+            properties: { mode: { enum: ['new', 'continue_latest', 'continue_or_create'] } },
+        },
+        {
+            type: 'object',
+            required: ['mode', 'conversationId'],
+            additionalProperties: false,
+            properties: {
+                mode: { const: 'specific' },
+                conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+            },
+        },
+    ],
+};
+const mediaAttachmentDef = {
+    type: 'object',
+    required: ['kind', 'url'],
+    additionalProperties: false,
+    properties: {
+        kind: { enum: ['image', 'audio', 'video', 'file'] },
+        url: {
+            type: 'string',
+            minLength: 1,
+            description: 'Must come from /media/upload (Canon storage) or the GIF picker — server '
+                + 'allowlist, fail-closed (functions/src/utils/mediaUploadSafety.ts).',
+        },
+        mimeType: { type: 'string' },
+        fileName: { type: 'string' },
+        sizeBytes: { type: 'number', minimum: 0 },
+        width: { type: 'number', minimum: 0 },
+        height: { type: 'number', minimum: 0 },
+        durationMs: { type: 'number', minimum: 0 },
+    },
+};
+const turnMetadataDef = {
+    type: 'object',
+    description: `Free-form metadata envelope; JSON.stringify length <= ${VERB_LIMITS.messageMetadataJsonChars} `
+        + 'UTF-16 code units (functions/src/api/sendMessage.ts checks string length, not bytes). '
+        + 'Well-known turn-protocol keys below (authoritative type: turnProtocol.ts TurnMetadata, '
+        + 'which also carries requestedTurnMode); receipt metadata.type values are server-owned '
+        + 'and rejected.',
+    additionalProperties: true,
+    properties: {
+        turnId: { type: ['string', 'null'] },
+        turnSemantics: { enum: ['progress', 'turn_complete', 'control'] },
+        deliveryIntent: {
+            enum: ['queue', 'interrupt', 'interleave', 'stop'],
+            description: 'What the recipient runtime should do if the message lands mid-turn. Default queue.',
+        },
+        replyBehavior: { enum: ['allow_auto_reply', 'suppress_auto_reply'] },
+    },
+};
+const messageIdDef = {
+    type: 'string',
+    pattern: VERB_ID_PATTERNS.runtimeId,
+    not: {
+        pattern: '^(\\.{1,2}|__.*__)$',
+        description: "Reserved forms the server 400s: '.', '..', and __x__ ids.",
+    },
+    description: `Client idempotency key (<= ${VERB_LIMITS.messageIdChars} chars / `
+        + `${VERB_LIMITS.messageIdBytes} UTF-8 bytes; no slashes, control chars, '.', '..', __x__). `
+        + 'Same id + identical payload replays idempotently; different payload -> 409 MESSAGE_ID_EXISTS.',
+};
+const messageOptionsDef = {
+    type: 'object',
+    description: 'Message composition options (mirrors POST /messages/send). Deliberately absent: '
+        + 'contact_card contentType (use share_contact) and forwarded/forwardedFrom '
+        + '(forwarding stays host/REST-mediated; /messages/forward is not a v1 verb).',
+    additionalProperties: false,
+    properties: {
+        messageId: REF('messageId'),
+        contentType: {
+            enum: ['text', 'image', 'audio', 'video', 'file'],
+            description: 'Derived from attachments when omitted. contact_card is deliberately excluded here — '
+                + 'use the share_contact verb.',
+        },
+        attachments: {
+            type: 'array',
+            maxItems: VERB_LIMITS.messageAttachments,
+            items: REF('mediaAttachment'),
+        },
+        mentions: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Member userIds; every id must be a conversation member (400 otherwise).',
+        },
+        replyTo: { type: 'string', description: 'Message id being replied to (not existence-validated).' },
+        replyToPosition: { type: 'integer' },
+        metadata: REF('turnMetadata'),
+    },
+};
+const inputChoiceDef = {
+    type: 'object',
+    required: ['label'],
+    additionalProperties: false,
+    properties: {
+        label: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.inputChoiceLabelChars },
+        value: { type: 'string', maxLength: VERB_LIMITS.inputChoiceValueChars },
+        description: { type: 'string', maxLength: VERB_LIMITS.inputChoiceDescriptionChars },
+    },
+};
+const inputQuestionDef = {
+    type: 'object',
+    required: ['id', 'question'],
+    additionalProperties: false,
+    properties: {
+        id: { type: 'string', pattern: VERB_ID_PATTERNS.questionId },
+        question: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.inputQuestionChars },
+        header: { type: 'string', maxLength: VERB_LIMITS.inputQuestionHeaderChars },
+        choices: { type: 'array', maxItems: VERB_LIMITS.inputChoices, items: REF('inputChoice') },
+        allowOther: { type: 'boolean' },
+        isSecret: {
+            type: 'boolean',
+            description: 'Forces owner-only routing for the whole request.',
+        },
+        multiSelect: { type: 'boolean' },
+    },
+};
+const approvalDetailDef = {
+    type: 'object',
+    required: ['label', 'value'],
+    additionalProperties: false,
+    properties: {
+        label: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.approvalDetailLabelChars },
+        value: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.approvalDetailValueChars },
+        monospace: { type: 'boolean' },
+    },
+};
+const unifiedDiffDef = {
+    type: 'object',
+    description: `Unified diff for file-change approvals. Server sanitizes: sensitive paths suppressed, `
+        + `secret tokens redacted, per-file clip ${VERB_LIMITS.diffFileBytes} bytes, total `
+        + `${VERB_LIMITS.diffTotalBytes} bytes (functions/src/api/interactionApproval.ts; primitives in `
+        + 'backend-contracts diffRedaction.ts).',
+    required: ['files'],
+    additionalProperties: false,
+    properties: {
+        files: {
+            type: 'array',
+            maxItems: VERB_LIMITS.diffFiles,
+            items: {
+                type: 'object',
+                required: ['path', 'status'],
+                additionalProperties: false,
+                properties: {
+                    path: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.diffPathChars },
+                    status: { enum: ['modified', 'created', 'deleted', 'renamed'] },
+                    oldPath: { type: 'string', maxLength: VERB_LIMITS.diffPathChars },
+                    additions: { type: 'integer', minimum: 0 },
+                    deletions: { type: 'integer', minimum: 0 },
+                    diff: { type: 'string' },
+                    suppressed: { type: 'boolean' },
+                },
+            },
+        },
+        truncated: { type: 'boolean' },
+    },
+};
+const sessionRuleDef = {
+    type: 'object',
+    description: 'Standing approval rule. Owner-only: the server forces allowSessionRule=false for '
+        + 'non-owner responders.',
+    required: ['type'],
+    additionalProperties: false,
+    properties: {
+        type: { enum: ['approve-all', 'approve-tool', 'deny-tool'] },
+        toolPattern: { type: 'string', pattern: VERB_ID_PATTERNS.sessionRuleToolPattern },
+        expiresAt: { type: ['string', 'null'], description: 'ISO timestamp or null.' },
+    },
+    if: { properties: { type: { enum: ['approve-tool', 'deny-tool'] } }, required: ['type'] },
+    then: { required: ['toolPattern'], properties: { toolPattern: true } },
+};
+const runtimeCardDef = {
+    type: 'object',
+    description: 'ENVELOPE-ONLY validation of a canon.card.v1 document: block structures are NOT '
+        + 'checked here. Tool bindings MUST compose the full document schema via '
+        + 'getVerbInputSchema(verb, { cardSchema: RUNTIME_CARD_JSON_SCHEMA_V1 }) so models '
+        + 'cannot produce envelope-valid cards the platform rejects. Full document contract: '
+        + '@canonmsg/rich-cards RUNTIME_CARD_JSON_SCHEMA_V1 ($id '
+        + 'https://canonmsg.com/schemas/canon.card.v1.json) — '
+        + `authoring caps title 120 / fallbackText 500 / blocks 24. Server envelope acceptance `
+        + `(interactionCard.ts): <= ${VERB_LIMITS.cardEnvelopeBytes} bytes serialized, title <= `
+        + `${VERB_LIMITS.cardServerTitleChars}, fallbackText <= ${VERB_LIMITS.cardServerFallbackTextChars}, `
+        + `blocks <= ${VERB_LIMITS.cardServerBlocks}; no secret-bearing top-level keys.`,
+    required: ['schema', 'title', 'fallbackText', 'blocks'],
+    additionalProperties: true,
+    properties: {
+        schema: { const: 'canon.card.v1' },
+        cardId: { type: 'string', pattern: VERB_ID_PATTERNS.cardId },
+        title: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.cardServerTitleChars },
+        fallbackText: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.cardServerFallbackTextChars },
+        blocks: { type: 'array', minItems: 1, maxItems: VERB_LIMITS.cardServerBlocks },
+    },
+};
+const nativeDef = {
+    type: 'object',
+    description: `Runtime correlation handles (<= ${VERB_LIMITS.nativeKeys} keys, string values <= `
+        + `${VERB_LIMITS.nativeValueChars} chars or a nested handles map <= ${VERB_LIMITS.nativeHandles}; `
+        + 'functions/src/api/interactionKinds.ts normalizeNative).',
+    additionalProperties: true,
+};
+const timeoutFields = (maxMs, ceilingNote) => ({
+    timeoutMs: {
+        type: 'integer',
+        minimum: VERB_LIMITS.minTimeoutMs,
+        maximum: maxMs,
+        description: `Relative deadline in ms (server ceiling ${ceilingNote}). expiresAt wins when both are given.`,
+    },
+    expiresAt: {
+        type: 'integer',
+        minimum: 0,
+        description: 'Absolute epoch-ms deadline. The REST interaction creators REQUIRE a deadline '
+            + '(and /runtime-input/request also requires kind): bindings must fill defaults '
+            + 'and convert timeoutMs into expiresAt before calling the endpoint.',
+    },
+});
+// ---------------------------------------------------------------------------
+// Verb schemas
+// ---------------------------------------------------------------------------
+const send_to_input = {
+    type: 'object',
+    description: 'Message another conversation or user (admission-aware), optionally carrying a '
+        + 'private self-context. Exactly one of targetConversationId / targetUserId / '
+        + 'canonContactId. canonContactId is NOT a wire field: bindings resolve it via POST '
+        + '/admission/resolve to a targetUserId first. Projections: selfContext sends -> POST '
+        + '/messages/send-contextual (which requires sourceConversationId + selfContext); '
+        + 'known-conversation sends without selfContext -> POST /messages/send; plain user '
+        + 'sends -> admission resolve + create + send (the core reachOut composite). User '
+        + 'targets resolve admission first: open targets get the message, approval-required '
+        + 'targets get a contact request (send deferred and auto-fulfilled on approval), '
+        + "owner-only targets surface as status 'unavailable' with reason owner-only.",
+    additionalProperties: false,
+    properties: {
+        targetConversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        targetUserId: { type: 'string', minLength: 1 },
+        canonContactId: { type: 'string', minLength: 1 },
+        text: {
+            type: 'string',
+            maxLength: VERB_LIMITS.messageTextBytes,
+            description: `<= ${VERB_LIMITS.messageTextBytes} UTF-8 bytes. Required unless messageOptions.attachments carries the content.`,
+        },
+        sourceConversationId: {
+            type: 'string',
+            pattern: VERB_ID_PATTERNS.runtimeId,
+            description: 'Required when selfContext is present; the agent must be a member.',
+        },
+        selfContext: REF('selfContext'),
+        requestMessage: {
+            type: 'string',
+            maxLength: VERB_LIMITS.contactRequestNoteChars,
+            description: `Contact-request note when admission requires approval; defaults to text; senders `
+                + `truncate to ${VERB_LIMITS.contactRequestNoteChars} chars.`,
+        },
+        sessionSelection: REF('sessionSelection'),
+        sessionConfig: {
+            type: ['object', 'null'],
+            description: 'Coding-agent session setup (model/permissionMode/effort/workspaceId/executionMode); '
+                + 'only applied to agent targets, stripped for humans.',
+        },
+        messageOptions: REF('messageOptions'),
+    },
+    oneOf: [
+        { required: ['targetConversationId'], properties: { targetConversationId: true } },
+        { required: ['targetUserId'], properties: { targetUserId: true } },
+        { required: ['canonContactId'], properties: { canonContactId: true } },
+    ],
+    dependentRequired: { selfContext: ['sourceConversationId'] },
+};
+const send_to_result = {
+    description: 'Canonical outcome vocabulary. Legacy binding drift documented in CANON_VERB_BINDINGS '
+        + "(hermes 'opened' -> messaged without messageId; hermes 'denied' -> blocked).",
+    oneOf: [
+        {
+            type: 'object',
+            required: ['status', 'conversationId'],
+            additionalProperties: true,
+            properties: {
+                status: { const: 'messaged' },
+                conversationId: { type: 'string' },
+                messageId: { type: 'string' },
+                selfContextId: { type: 'string' },
+                created: { type: 'boolean' },
+                reused: { type: 'boolean' },
+                sessionSelection: { type: 'string' },
+            },
+        },
+        {
+            type: 'object',
+            required: ['status', 'requestId'],
+            additionalProperties: true,
+            properties: {
+                status: { enum: ['requested', 'pending'] },
+                requestId: { type: ['string', 'null'] },
+                deferredIntentId: {
+                    type: ['string', 'null'],
+                    description: 'Present when the send is deferred until the contact request resolves.',
+                },
+            },
+        },
+        {
+            type: 'object',
+            required: ['status', 'reason'],
+            additionalProperties: true,
+            properties: {
+                status: { enum: ['setup_required', 'no_session', 'blocked', 'unavailable'] },
+                reason: { type: 'string' },
+            },
+        },
+    ],
+};
+const request_input_input = {
+    type: 'object',
+    description: 'Ask a human a structured question mid-turn (HITL input card). sudo/secret kinds, '
+        + 'sensitive:true, or any isSecret question force owner-only routing server-side; '
+        + 'bindings must not let the model redirect the responder for those. Ceiling '
+        + `${VERB_LIMITS.maxTimeoutMs / 60000} minutes.`,
+    additionalProperties: false,
+    properties: {
+        conversationId: {
+            type: 'string',
+            pattern: VERB_ID_PATTERNS.runtimeId,
+            description: 'Bindings default to the active conversation.',
+        },
+        inputId: {
+            type: 'string',
+            pattern: VERB_ID_PATTERNS.runtimeId,
+            description: 'Durable single-use id (reuse -> 409); generated when omitted.',
+        },
+        kind: { enum: ['clarify', 'sudo', 'secret'], default: 'clarify' },
+        title: { type: 'string', maxLength: VERB_LIMITS.inputTitleChars },
+        prompt: { type: 'string', maxLength: VERB_LIMITS.inputPromptChars },
+        choices: { type: 'array', maxItems: VERB_LIMITS.inputChoices, items: REF('inputChoice') },
+        questions: { type: 'array', maxItems: VERB_LIMITS.inputQuestions, items: REF('inputQuestion') },
+        secretName: { type: 'string', maxLength: VERB_LIMITS.inputSecretNameChars },
+        sensitive: { type: 'boolean' },
+        responseUserId: {
+            type: 'string',
+            pattern: VERB_ID_PATTERNS.runtimeId,
+            description: 'Must be a human conversation member. Trust-critical bindings (hermes) derive this '
+                + 'from turn provenance and ignore model-supplied values.',
+        },
+        native: REF('native'),
+        turnId: { type: 'string', maxLength: VERB_LIMITS.turnIdChars },
+        ...timeoutFields(VERB_LIMITS.maxTimeoutMs, '30 minutes'),
+    },
+};
+const request_input_result = {
+    oneOf: [
+        {
+            type: 'object',
+            required: ['status', 'inputId', 'value'],
+            additionalProperties: true,
+            properties: {
+                status: { const: 'submitted' },
+                inputId: { type: 'string' },
+                value: { type: 'string', description: "Free-text answer ('' when structured answers were used)." },
+                answers: {
+                    type: 'object',
+                    description: 'Structured answers keyed by question id.',
+                    additionalProperties: {
+                        type: 'object',
+                        required: ['answers'],
+                        properties: { answers: { type: 'array', items: { type: 'string' } } },
+                    },
+                },
+            },
+        },
+        {
+            type: 'object',
+            required: ['status', 'inputId'],
+            additionalProperties: true,
+            properties: {
+                status: { enum: ['cancelled', 'timeout'] },
+                inputId: { type: 'string' },
+            },
+        },
+    ],
+};
+const request_approval_input = {
+    type: 'object',
+    description: "Ask a human to allow/deny an action. mode 'blocking' (default) waits inside the verb "
+        + "call; mode 'detached' returns pending immediately — fetch the decision later with "
+        + `check_approval. Approval deadline ceiling is ${VERB_LIMITS.maxApprovalTimeoutMs / 3600000} hours `
+        + '(other kinds: 30 minutes). Timeouts fail closed to deny.',
+    required: ['toolName', 'toolSummary'],
+    additionalProperties: false,
+    properties: {
+        conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        approvalId: {
+            type: 'string',
+            pattern: VERB_ID_PATTERNS.runtimeId,
+            description: 'Durable single-use id; server-generated when omitted.',
+        },
+        toolName: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.toolNameChars },
+        toolSummary: {
+            type: 'string',
+            minLength: 1,
+            maxLength: VERB_LIMITS.toolSummaryChars,
+            description: 'Pre-redact secrets — this renders to humans.',
+        },
+        mode: { enum: ['blocking', 'detached'], default: 'blocking' },
+        riskLevel: {
+            enum: ['normal', 'destructive'],
+            description: 'Server accepts only these values; others are silently dropped, not rejected.',
+        },
+        risk: {
+            enum: ['low', 'normal', 'high', 'destructive'],
+            description: 'Advisory; server stores any string <= 64 chars today.',
+        },
+        category: {
+            enum: ['command', 'file', 'network', 'browser', 'mcp', 'plugin', 'canon', 'tool'],
+            description: 'Advisory; server stores any string <= 64 chars today.',
+        },
+        details: { type: 'array', maxItems: VERB_LIMITS.approvalDetails, items: REF('approvalDetail') },
+        diff: REF('unifiedDiff'),
+        native: REF('native'),
+        runtimeId: { type: 'string', maxLength: VERB_LIMITS.turnIdChars },
+        turnId: { type: 'string', maxLength: VERB_LIMITS.turnIdChars },
+        responseUserId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        allowSessionRule: {
+            type: 'boolean',
+            description: 'Server forces false when the responder is not the agent owner.',
+        },
+        ...timeoutFields(VERB_LIMITS.maxApprovalTimeoutMs, '72 hours'),
+    },
+};
+const request_approval_result = {
+    oneOf: [
+        {
+            type: 'object',
+            required: ['status', 'approvalId'],
+            additionalProperties: true,
+            properties: {
+                status: { const: 'allow' },
+                approvalId: { type: 'string' },
+                sessionRule: REF('sessionRule'),
+                respondedBy: { type: 'string', description: 'Canon-authenticated responder userId.' },
+            },
+        },
+        {
+            type: 'object',
+            required: ['status', 'approvalId'],
+            additionalProperties: true,
+            properties: {
+                status: { const: 'deny' },
+                approvalId: { type: 'string' },
+                sessionRule: REF('sessionRule'),
+                respondedBy: { type: 'string' },
+            },
+        },
+        {
+            type: 'object',
+            required: ['status', 'approvalId'],
+            additionalProperties: true,
+            properties: { status: { const: 'timeout' }, approvalId: { type: 'string' } },
+        },
+        {
+            type: 'object',
+            description: 'Detached acceptance — the decision arrives via check_approval.',
+            required: ['status', 'approvalId', 'expiresAt'],
+            additionalProperties: true,
+            properties: {
+                status: { const: 'pending' },
+                approvalId: { type: 'string' },
+                conversationId: { type: 'string' },
+                expiresAt: { type: 'integer' },
+                responseUserId: { type: 'string' },
+            },
+        },
+    ],
+};
+const check_approval_input = {
+    type: 'object',
+    description: 'Fetch the decision of a detached approval. Consume is idempotent within the replay '
+        + 'window: a resolved decision replays for up to 72h after first consume, then the id '
+        + 'becomes unknown. Bindings must bind the check to the conversation that created the '
+        + 'approval.',
+    required: ['approvalId'],
+    additionalProperties: false,
+    properties: {
+        approvalId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+    },
+};
+const check_approval_result = {
+    description: "'unknown' is NOT a denial — only 'resolved' carries a decision. Canonical statuses map "
+        + 'from the /runtime-approval/consume wire as: allow/deny -> resolved.decision, timeout -> '
+        + 'expired, pending -> pending, HTTP 404 RUNTIME_APPROVAL_NOT_FOUND -> unknown.',
+    oneOf: [
+        {
+            type: 'object',
+            required: ['status', 'approvalId', 'decision'],
+            additionalProperties: true,
+            properties: {
+                status: { const: 'resolved' },
+                approvalId: { type: 'string' },
+                decision: { enum: ['allow', 'deny'] },
+                respondedBy: { type: 'string' },
+                conversationId: { type: 'string' },
+            },
+        },
+        {
+            type: 'object',
+            required: ['status', 'approvalId'],
+            additionalProperties: true,
+            properties: {
+                status: { enum: ['pending', 'expired', 'unknown'] },
+                approvalId: { type: 'string' },
+                expiresAt: { type: 'integer' },
+                conversationId: { type: 'string' },
+            },
+        },
+    ],
+};
+const send_card_input = {
+    type: 'object',
+    description: 'Display a card with no actions — fire-and-forget, no pending state, no deadline.',
+    required: ['card'],
+    additionalProperties: false,
+    properties: {
+        conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        card: REF('runtimeCard'),
+        cardId: { type: 'string', pattern: VERB_ID_PATTERNS.cardId },
+        native: REF('native'),
+        runtimeId: { type: 'string', maxLength: VERB_LIMITS.turnIdChars },
+        turnId: { type: 'string', maxLength: VERB_LIMITS.turnIdChars },
+    },
+};
+const send_card_result = {
+    type: 'object',
+    required: ['status', 'cardId'],
+    additionalProperties: true,
+    properties: {
+        status: { const: 'displayed' },
+        cardId: { type: 'string' },
+        conversationId: { type: 'string' },
+        responseUserId: { type: 'string' },
+    },
+};
+const request_card_input = {
+    type: 'object',
+    description: 'Show an interactive card (>= 1 actions block required) and wait for the response. '
+        + `Deadline ceiling ${VERB_LIMITS.maxTimeoutMs / 60000} minutes.`,
+    required: ['card'],
+    additionalProperties: false,
+    properties: {
+        conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        card: REF('runtimeCard'),
+        cardId: { type: 'string', pattern: VERB_ID_PATTERNS.cardId },
+        responseUserId: {
+            type: 'string',
+            pattern: VERB_ID_PATTERNS.runtimeId,
+            description: 'Must be a human conversation member; defaults to the turn-triggering human '
+                + '(trust-critical bindings ignore model-supplied values).',
+        },
+        native: REF('native'),
+        runtimeId: { type: 'string', maxLength: VERB_LIMITS.turnIdChars },
+        turnId: { type: 'string', maxLength: VERB_LIMITS.turnIdChars },
+        ...timeoutFields(VERB_LIMITS.maxTimeoutMs, '30 minutes'),
+    },
+};
+const request_card_result = {
+    oneOf: [
+        {
+            type: 'object',
+            required: ['status', 'cardId'],
+            additionalProperties: true,
+            properties: {
+                status: { const: 'submitted' },
+                cardId: { type: 'string' },
+                actionId: { type: 'string' },
+                values: {
+                    type: 'object',
+                    description: `Validated server-side against the card's actionFields `
+                        + `(validateRuntimeCardFieldValues); <= ${VERB_LIMITS.cardValuesBytes} bytes, `
+                        + `depth <= ${VERB_LIMITS.cardValuesDepth}.`,
+                },
+                respondedBy: {
+                    type: 'string',
+                    description: 'Canon-authenticated responder (server-verified vs responseUserId).',
+                },
+            },
+        },
+        {
+            type: 'object',
+            required: ['status', 'cardId'],
+            additionalProperties: true,
+            properties: {
+                status: { const: 'cancelled' },
+                cardId: { type: 'string' },
+                respondedBy: { type: 'string' },
+            },
+        },
+        {
+            type: 'object',
+            required: ['status', 'cardId'],
+            additionalProperties: true,
+            properties: { status: { const: 'timeout' }, cardId: { type: 'string' } },
+        },
+    ],
+};
+const share_contact_input = {
+    type: 'object',
+    description: "Share a contact card into a conversation (POST /messages/send, contentType "
+        + "'contact_card'). The shared user must be in the sending agent's contacts (403 "
+        + 'otherwise; the owner shortcut applies only to human senders sharing their own '
+        + 'agents). The server snapshots the card.',
+    required: ['conversationId', 'contactUserId'],
+    additionalProperties: false,
+    properties: {
+        conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        contactUserId: { type: 'string', minLength: 1 },
+        text: { type: 'string', maxLength: VERB_LIMITS.messageTextBytes },
+        messageId: REF('messageId'),
+    },
+};
+const share_contact_result = {
+    type: 'object',
+    required: ['status', 'messageId'],
+    additionalProperties: true,
+    properties: {
+        status: { const: 'shared' },
+        messageId: { type: 'string' },
+    },
+};
+const react_input = {
+    type: 'object',
+    description: 'Toggle an emoji reaction on a message (server-side atomic toggle; '
+        + 'functions/src/api/reactToMessage.ts).',
+    required: ['conversationId', 'messageId', 'emoji'],
+    additionalProperties: false,
+    properties: {
+        conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        messageId: { type: 'string', minLength: 1 },
+        emoji: {
+            type: 'string',
+            minLength: 1,
+            maxLength: VERB_LIMITS.reactionEmojiChars,
+            description: 'Reaction key. Content-adjacent (D5) — rides the wire body.',
+        },
+    },
+};
+const react_result = {
+    type: 'object',
+    required: ['status', 'action'],
+    additionalProperties: true,
+    properties: {
+        status: { const: 'reacted' },
+        action: { enum: ['added', 'removed'] },
+        reactions: { type: 'object' },
+    },
+};
+const forward_input = {
+    type: 'object',
+    description: 'Forward an existing message into another conversation. Under E2EE this '
+        + 'becomes client-side re-encrypt; only routing ids + an optional caption '
+        + 'cross the wire.',
+    required: ['sourceConversationId', 'targetConversationId', 'messageId'],
+    additionalProperties: false,
+    properties: {
+        sourceConversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        targetConversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        messageId: { type: 'string', minLength: 1 },
+        text: {
+            type: 'string',
+            maxLength: VERB_LIMITS.messageTextBytes,
+            description: `Optional caption; <= ${VERB_LIMITS.messageTextBytes} UTF-8 bytes.`,
+        },
+    },
+};
+const forward_result = {
+    type: 'object',
+    required: ['status', 'messageId', 'targetConversationId'],
+    additionalProperties: true,
+    properties: {
+        status: { const: 'forwarded' },
+        messageId: { type: 'string' },
+        targetConversationId: { type: 'string' },
+    },
+};
+const create_group_input = {
+    type: 'object',
+    description: "Create a group conversation. Each target's groupJoinPolicy is enforced "
+        + 'server-side with staged admission: directly-addable members join at '
+        + 'creation, approval-required members become pending group_invite '
+        + 'requests, policy-denied members are skipped (see the result). At '
+        + 'least one member must be directly addable — a creator-only group is '
+        + 'rejected with error code CREATE_GROUP_NO_ADDABLE_MEMBERS. v1 scoping: '
+        + 'coding-agent members that require explicit session setup are skipped '
+        + '(reason setup-required), and a creator that itself requires setup '
+        + 'cannot create groups (403 CREATE_GROUP_CREATOR_SETUP_REQUIRED); only '
+        + 'the owner can set such agents up, from the app. Under MLS, membership '
+        + 'changes are Add/Remove proposals + Commit — a group operation is a '
+        + 'cryptographic state change, not a codec swap.',
+    required: ['name', 'memberIds'],
+    additionalProperties: false,
+    properties: {
+        name: { type: 'string', minLength: 1, maxLength: VERB_LIMITS.groupNameChars },
+        memberIds: {
+            type: 'array',
+            minItems: 1,
+            maxItems: VERB_LIMITS.groupMembers - 1,
+            items: { type: 'string', minLength: 1 },
+            description: 'Other members; the caller is added automatically.',
+        },
+    },
+};
+const create_group_result = {
+    type: 'object',
+    description: 'Staged admission: the group exists with the directly-addable members; '
+        + '`pending` lists approval-required members whose group_invite awaits '
+        + 'their approver; `skipped` lists members whose policy denied the add '
+        + '(reasons include owner-only, blocked, not-found, setup-required).',
+    required: ['status', 'conversationId'],
+    additionalProperties: true,
+    properties: {
+        status: { const: 'created' },
+        conversationId: { type: 'string' },
+        pending: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['userId', 'requestId'],
+                additionalProperties: true,
+                properties: {
+                    userId: { type: 'string' },
+                    requestId: { type: 'string' },
+                },
+            },
+        },
+        skipped: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['userId', 'reason'],
+                additionalProperties: true,
+                properties: {
+                    userId: { type: 'string' },
+                    reason: { type: 'string' },
+                },
+            },
+        },
+    },
+};
+const add_member_input = {
+    type: 'object',
+    description: 'v1 scoping: a coding-agent target that requires explicit session setup '
+        + 'is rejected (only its owner can set it up, from the app). Under MLS '
+        + 'an add is an Add proposal + Commit (new epoch), not a server-side '
+        + 'membership write — the verb semantics are stable, the mechanism is '
+        + 'not.',
+    required: ['conversationId', 'userId'],
+    additionalProperties: false,
+    properties: {
+        conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        userId: { type: 'string', minLength: 1 },
+    },
+};
+const add_member_result = {
+    description: 'approval-required targets yield a pending group_invite contact request '
+        + 'routed to their approver.',
+    oneOf: [
+        {
+            type: 'object',
+            required: ['status'],
+            additionalProperties: true,
+            properties: { status: { const: 'added' } },
+        },
+        {
+            type: 'object',
+            required: ['status', 'requestId'],
+            additionalProperties: true,
+            properties: { status: { const: 'pending' }, requestId: { type: 'string' } },
+        },
+    ],
+};
+const remove_member_input = {
+    type: 'object',
+    description: 'Requester must be a group owner/admin (server-enforced). Under MLS a '
+        + 'removal is a Remove proposal + Commit that rotates the group secret '
+        + 'away from the removed leaf.',
+    required: ['conversationId', 'userId'],
+    additionalProperties: false,
+    properties: {
+        conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+        userId: { type: 'string', minLength: 1 },
+    },
+};
+const remove_member_result = {
+    type: 'object',
+    required: ['status'],
+    additionalProperties: true,
+    properties: { status: { const: 'removed' } },
+};
+const leave_conversation_input = {
+    type: 'object',
+    required: ['conversationId'],
+    additionalProperties: false,
+    properties: {
+        conversationId: { type: 'string', pattern: VERB_ID_PATTERNS.runtimeId },
+    },
+};
+const leave_conversation_result = {
+    type: 'object',
+    required: ['status'],
+    additionalProperties: true,
+    properties: { status: { const: 'left' } },
+};
+const list_contacts_input = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {},
+};
+const list_contacts_result = {
+    type: 'object',
+    required: ['contacts'],
+    additionalProperties: true,
+    properties: {
+        contacts: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['id', 'source', 'addedAt', 'displayNameOverride'],
+                additionalProperties: true,
+                properties: {
+                    id: { type: 'string', description: "The contact's userId." },
+                    source: {
+                        type: 'string',
+                        description: 'Vocabulary: direct_add | phone_book | contact_request | link | qr | group | '
+                            + 'open_inbound_message | unknown (server passes strings through).',
+                    },
+                    addedAt: { type: ['string', 'null'] },
+                    displayNameOverride: { type: ['string', 'null'] },
+                },
+            },
+        },
+    },
+};
+const list_contact_requests_input = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {},
+};
+const list_contact_requests_result = {
+    type: 'object',
+    description: 'Pending inbound requests, newest first, capped at 100. Items are '
+        + 'SerializedContactRequest (backend-contracts contactRequest.ts). Read-only awareness: '
+        + "approval routes to the owner; agents cannot approve/reject.",
+    required: ['requests'],
+    additionalProperties: true,
+    properties: {
+        requests: {
+            type: 'array',
+            items: {
+                type: 'object',
+                required: ['id', 'requesterId', 'targetId', 'status', 'kind'],
+                additionalProperties: true,
+                properties: {
+                    id: { type: 'string' },
+                    requesterId: { type: 'string' },
+                    requesterName: { type: 'string' },
+                    targetId: { type: 'string' },
+                    status: { enum: ['pending', 'approved', 'rejected', 'expired'] },
+                    kind: { enum: ['dm', 'group_invite'] },
+                    message: { type: ['string', 'null'] },
+                    createdAt: { type: ['string', 'null'] },
+                    expiresAt: { type: ['string', 'null'] },
+                },
+            },
+        },
+    },
+};
+const list_conversations_input = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        limit: {
+            type: 'integer',
+            minimum: 1,
+            description: 'Optional client-side cap applied by the binding; the REST endpoint has no '
+                + 'pagination and returns all visible memberships.',
+        },
+    },
+};
+const list_conversations_result = {
+    type: 'object',
+    required: ['conversations'],
+    additionalProperties: true,
+    properties: {
+        conversations: {
+            type: 'array',
+            items: {
+                type: 'object',
+                // topic/lastMessage/createdAt are ??-null'd by the serializer (always
+                // present); name is a raw passthrough and may be absent on direct chats.
+                required: ['id', 'type', 'memberIds', 'isAgentChat', 'topic', 'lastMessage', 'createdAt'],
+                additionalProperties: true,
+                properties: {
+                    id: { type: 'string' },
+                    type: { enum: ['direct', 'group'] },
+                    name: { type: ['string', 'null'] },
+                    topic: { type: ['string', 'null'] },
+                    memberIds: { type: 'array', items: { type: 'string' } },
+                    isAgentChat: { type: 'boolean' },
+                    hasUnread: { type: 'boolean' },
+                    lastMessage: {
+                        type: ['object', 'null'],
+                        additionalProperties: true,
+                        properties: {
+                            text: { type: ['string', 'null'] },
+                            messageId: { type: 'string' },
+                            senderId: { type: 'string' },
+                            senderType: { type: 'string' },
+                            contentType: { type: 'string' },
+                            timestamp: { type: ['string', 'null'] },
+                        },
+                    },
+                    createdAt: { type: ['string', 'null'] },
+                },
+            },
+        },
+    },
+};
+// ---------------------------------------------------------------------------
+// Bundle
+// ---------------------------------------------------------------------------
+export const CANON_VERBS_JSON_SCHEMA = {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: CANON_VERBS_SCHEMA_ID,
+    title: 'Canon Agent Verbs v1',
+    description: 'Canonical contract for every deliberate agent action against Canon. Each verb has a '
+        + '<verb>_input and <verb>_result definition. Inputs are strict; results are open for '
+        + 'forward compatibility. Replies, streaming, typing, and read receipts are '
+        + 'deliberately NOT verbs — they stay host-mediated.',
+    $defs: {
+        messageId: messageIdDef,
+        selfContext: selfContextDef,
+        sessionSelection: sessionSelectionDef,
+        mediaAttachment: mediaAttachmentDef,
+        turnMetadata: turnMetadataDef,
+        messageOptions: messageOptionsDef,
+        inputChoice: inputChoiceDef,
+        inputQuestion: inputQuestionDef,
+        approvalDetail: approvalDetailDef,
+        unifiedDiff: unifiedDiffDef,
+        sessionRule: sessionRuleDef,
+        runtimeCard: runtimeCardDef,
+        native: nativeDef,
+        send_to_input,
+        send_to_result,
+        request_input_input,
+        request_input_result,
+        request_approval_input,
+        request_approval_result,
+        check_approval_input,
+        check_approval_result,
+        send_card_input,
+        send_card_result,
+        request_card_input,
+        request_card_result,
+        share_contact_input,
+        share_contact_result,
+        react_input,
+        react_result,
+        forward_input,
+        forward_result,
+        create_group_input,
+        create_group_result,
+        add_member_input,
+        add_member_result,
+        remove_member_input,
+        remove_member_result,
+        leave_conversation_input,
+        leave_conversation_result,
+        list_contacts_input,
+        list_contacts_result,
+        list_contact_requests_input,
+        list_contact_requests_result,
+        list_conversations_input,
+        list_conversations_result,
+    },
+};
+export const CANON_VERB_SCHEMA_REFS = Object.fromEntries(CANON_VERB_NAMES.map((name) => [
+    name,
+    {
+        input: `${CANON_VERBS_SCHEMA_ID}#/$defs/${name}_input`,
+        result: `${CANON_VERBS_SCHEMA_ID}#/$defs/${name}_result`,
+    },
+]));
+function collectDefRefs(node, into) {
+    if (Array.isArray(node)) {
+        for (const item of node)
+            collectDefRefs(item, into);
+        return;
+    }
+    if (node && typeof node === 'object') {
+        for (const [key, value] of Object.entries(node)) {
+            if (key === '$ref' && typeof value === 'string' && value.startsWith('#/$defs/')) {
+                into.add(value.slice('#/$defs/'.length));
+            }
+            else {
+                collectDefRefs(value, into);
+            }
+        }
+    }
+}
+const ALL_DEFS = CANON_VERBS_JSON_SCHEMA.$defs;
+/**
+ * Make an extracted subschema self-contained: `#/$defs/...` refs resolve
+ * against the EMBEDDING document's root, so the transitively referenced
+ * shared definitions are attached to the extracted schema itself. Verb
+ * subschemas embedded into tool definitions (MCP inputSchema, hermes tool
+ * schemas, codex dynamicTools) stay valid standalone.
+ */
+function selfContained(def) {
+    const needed = new Set();
+    collectDefRefs(def, needed);
+    let previousSize = -1;
+    while (previousSize !== needed.size) {
+        previousSize = needed.size;
+        for (const name of [...needed])
+            collectDefRefs(ALL_DEFS[name], needed);
+    }
+    if (needed.size === 0)
+        return { ...def };
+    const $defs = {};
+    for (const name of [...needed].sort())
+        $defs[name] = ALL_DEFS[name];
+    return { ...def, $defs };
+}
+const CARD_DEF_PREFIX = 'card__';
+function rebaseCardRefs(node, cardSchemaId) {
+    if (Array.isArray(node))
+        return node.map((item) => rebaseCardRefs(item, cardSchemaId));
+    if (node && typeof node === 'object') {
+        const out = {};
+        for (const [key, value] of Object.entries(node)) {
+            if (key === '$ref' && typeof value === 'string') {
+                let ref = value;
+                if (cardSchemaId && ref.startsWith(`${cardSchemaId}#`))
+                    ref = ref.slice(cardSchemaId.length);
+                out[key] = ref.startsWith('#/$defs/')
+                    ? `#/$defs/${CARD_DEF_PREFIX}${ref.slice('#/$defs/'.length)}`
+                    : value;
+            }
+            else {
+                out[key] = rebaseCardRefs(value, cardSchemaId);
+            }
+        }
+        return out;
+    }
+    return node;
+}
+function composeCardSchema(verbDefs, cardSchema) {
+    const { $schema: _dialect, $id, $defs: cardDefs, ...cardRoot } = cardSchema;
+    const cardSchemaId = typeof $id === 'string' ? $id : undefined;
+    const merged = {
+        ...verbDefs,
+        runtimeCard: rebaseCardRefs(cardRoot, cardSchemaId),
+    };
+    if (cardDefs && typeof cardDefs === 'object') {
+        for (const [name, def] of Object.entries(cardDefs)) {
+            const key = `${CARD_DEF_PREFIX}${name}`;
+            if (key in verbDefs) {
+                throw new Error(`card schema definition collides with a verb definition: ${key}`);
+            }
+            merged[key] = rebaseCardRefs(def, cardSchemaId);
+        }
+    }
+    return merged;
+}
+/** Self-contained input schema for a verb (for embedding into tool definitions). */
+export function getVerbInputSchema(verb, options) {
+    const schema = selfContained(ALL_DEFS[`${verb}_input`]);
+    const defs = schema.$defs;
+    if (options?.cardSchema && defs && 'runtimeCard' in defs) {
+        schema.$defs = composeCardSchema(defs, options.cardSchema);
+    }
+    return schema;
+}
+/** Self-contained result schema for a verb. */
+export function getVerbResultSchema(verb) {
+    return selfContained(ALL_DEFS[`${verb}_result`]);
+}