@canonmsg/backend-contracts 2.1.0 → 2.2.0

package/dist/verbSchemas.d.ts

@@ -0,0 +1,1460 @@
+/**
+ * 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 { type CanonVerbName } from './verbContract.js';
+export declare const CANON_VERBS_JSON_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: "https://canonmsg.com/schemas/canon.verbs.v1.json";
+    readonly title: "Canon Agent Verbs v1";
+    readonly description: string;
+    readonly $defs: {
+        readonly messageId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+            readonly not: {
+                readonly pattern: "^(\\.{1,2}|__.*__)$";
+                readonly description: "Reserved forms the server 400s: '.', '..', and __x__ ids.";
+            };
+            readonly description: string;
+        };
+        readonly selfContext: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["type", "context"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly type: {
+                    readonly const: "cross_session";
+                };
+                readonly context: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 1000;
+                    readonly description: "What future-you needs to know about this transfer.";
+                };
+            };
+        };
+        readonly sessionSelection: {
+            readonly description: string;
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly required: readonly ["mode"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly mode: {
+                        readonly enum: readonly ["new", "continue_latest", "continue_or_create"];
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["mode", "conversationId"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly mode: {
+                        readonly const: "specific";
+                    };
+                    readonly conversationId: {
+                        readonly type: "string";
+                        readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                    };
+                };
+            }];
+        };
+        readonly mediaAttachment: {
+            readonly type: "object";
+            readonly required: readonly ["kind", "url"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly kind: {
+                    readonly enum: readonly ["image", "audio", "video", "file"];
+                };
+                readonly url: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly description: string;
+                };
+                readonly mimeType: {
+                    readonly type: "string";
+                };
+                readonly fileName: {
+                    readonly type: "string";
+                };
+                readonly sizeBytes: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+                readonly width: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+                readonly height: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+                readonly durationMs: {
+                    readonly type: "number";
+                    readonly minimum: 0;
+                };
+            };
+        };
+        readonly turnMetadata: {
+            readonly type: "object";
+            readonly description: string;
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly turnId: {
+                    readonly type: readonly ["string", "null"];
+                };
+                readonly turnSemantics: {
+                    readonly enum: readonly ["progress", "turn_complete", "control"];
+                };
+                readonly deliveryIntent: {
+                    readonly enum: readonly ["queue", "interrupt", "interleave", "stop"];
+                    readonly description: "What the recipient runtime should do if the message lands mid-turn. Default queue.";
+                };
+                readonly replyBehavior: {
+                    readonly enum: readonly ["allow_auto_reply", "suppress_auto_reply"];
+                };
+            };
+        };
+        readonly messageOptions: {
+            readonly type: "object";
+            readonly description: string;
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly messageId: {
+                    $ref: string;
+                };
+                readonly contentType: {
+                    readonly enum: readonly ["text", "image", "audio", "video", "file"];
+                    readonly description: string;
+                };
+                readonly attachments: {
+                    readonly type: "array";
+                    readonly maxItems: 10;
+                    readonly items: {
+                        $ref: string;
+                    };
+                };
+                readonly mentions: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Member userIds; every id must be a conversation member (400 otherwise).";
+                };
+                readonly replyTo: {
+                    readonly type: "string";
+                    readonly description: "Message id being replied to (not existence-validated).";
+                };
+                readonly replyToPosition: {
+                    readonly type: "integer";
+                };
+                readonly metadata: {
+                    $ref: string;
+                };
+            };
+        };
+        readonly inputChoice: {
+            readonly type: "object";
+            readonly required: readonly ["label"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly label: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 120;
+                };
+                readonly value: {
+                    readonly type: "string";
+                    readonly maxLength: 200;
+                };
+                readonly description: {
+                    readonly type: "string";
+                    readonly maxLength: 300;
+                };
+            };
+        };
+        readonly inputQuestion: {
+            readonly type: "object";
+            readonly required: readonly ["id", "question"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly id: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,120}$";
+                };
+                readonly question: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 1000;
+                };
+                readonly header: {
+                    readonly type: "string";
+                    readonly maxLength: 120;
+                };
+                readonly choices: {
+                    readonly type: "array";
+                    readonly maxItems: 12;
+                    readonly items: {
+                        $ref: string;
+                    };
+                };
+                readonly allowOther: {
+                    readonly type: "boolean";
+                };
+                readonly isSecret: {
+                    readonly type: "boolean";
+                    readonly description: "Forces owner-only routing for the whole request.";
+                };
+                readonly multiSelect: {
+                    readonly type: "boolean";
+                };
+            };
+        };
+        readonly approvalDetail: {
+            readonly type: "object";
+            readonly required: readonly ["label", "value"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly label: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 80;
+                };
+                readonly value: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 500;
+                };
+                readonly monospace: {
+                    readonly type: "boolean";
+                };
+            };
+        };
+        readonly unifiedDiff: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["files"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly files: {
+                    readonly type: "array";
+                    readonly maxItems: 100;
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["path", "status"];
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly path: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                                readonly maxLength: 1024;
+                            };
+                            readonly status: {
+                                readonly enum: readonly ["modified", "created", "deleted", "renamed"];
+                            };
+                            readonly oldPath: {
+                                readonly type: "string";
+                                readonly maxLength: 1024;
+                            };
+                            readonly additions: {
+                                readonly type: "integer";
+                                readonly minimum: 0;
+                            };
+                            readonly deletions: {
+                                readonly type: "integer";
+                                readonly minimum: 0;
+                            };
+                            readonly diff: {
+                                readonly type: "string";
+                            };
+                            readonly suppressed: {
+                                readonly type: "boolean";
+                            };
+                        };
+                    };
+                };
+                readonly truncated: {
+                    readonly type: "boolean";
+                };
+            };
+        };
+        readonly sessionRule: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["type"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly type: {
+                    readonly enum: readonly ["approve-all", "approve-tool", "deny-tool"];
+                };
+                readonly toolPattern: {
+                    readonly type: "string";
+                    readonly pattern: "^[\\w.*:-]{1,128}$";
+                };
+                readonly expiresAt: {
+                    readonly type: readonly ["string", "null"];
+                    readonly description: "ISO timestamp or null.";
+                };
+            };
+            readonly if: {
+                readonly properties: {
+                    readonly type: {
+                        readonly enum: readonly ["approve-tool", "deny-tool"];
+                    };
+                };
+                readonly required: readonly ["type"];
+            };
+            readonly then: {
+                readonly required: readonly ["toolPattern"];
+                readonly properties: {
+                    readonly toolPattern: true;
+                };
+            };
+        };
+        readonly runtimeCard: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["schema", "title", "fallbackText", "blocks"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly schema: {
+                    readonly const: "canon.card.v1";
+                };
+                readonly cardId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,80}$";
+                };
+                readonly title: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 200;
+                };
+                readonly fallbackText: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 2000;
+                };
+                readonly blocks: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly maxItems: 64;
+                };
+            };
+        };
+        readonly native: {
+            readonly type: "object";
+            readonly description: string;
+            readonly additionalProperties: true;
+        };
+        readonly send_to_input: {
+            readonly type: "object";
+            readonly description: string;
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly targetConversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly targetUserId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly canonContactId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly text: {
+                    readonly type: "string";
+                    readonly maxLength: 4096;
+                    readonly description: "<= 4096 UTF-8 bytes. Required unless messageOptions.attachments carries the content.";
+                };
+                readonly sourceConversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                    readonly description: "Required when selfContext is present; the agent must be a member.";
+                };
+                readonly selfContext: {
+                    $ref: string;
+                };
+                readonly requestMessage: {
+                    readonly type: "string";
+                    readonly maxLength: 500;
+                    readonly description: string;
+                };
+                readonly sessionSelection: {
+                    $ref: string;
+                };
+                readonly sessionConfig: {
+                    readonly type: readonly ["object", "null"];
+                    readonly description: string;
+                };
+                readonly messageOptions: {
+                    $ref: string;
+                };
+            };
+            readonly oneOf: readonly [{
+                readonly required: readonly ["targetConversationId"];
+                readonly properties: {
+                    readonly targetConversationId: true;
+                };
+            }, {
+                readonly required: readonly ["targetUserId"];
+                readonly properties: {
+                    readonly targetUserId: true;
+                };
+            }, {
+                readonly required: readonly ["canonContactId"];
+                readonly properties: {
+                    readonly canonContactId: true;
+                };
+            }];
+            readonly dependentRequired: {
+                readonly selfContext: readonly ["sourceConversationId"];
+            };
+        };
+        readonly send_to_result: {
+            readonly description: string;
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly required: readonly ["status", "conversationId"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly const: "messaged";
+                    };
+                    readonly conversationId: {
+                        readonly type: "string";
+                    };
+                    readonly messageId: {
+                        readonly type: "string";
+                    };
+                    readonly selfContextId: {
+                        readonly type: "string";
+                    };
+                    readonly created: {
+                        readonly type: "boolean";
+                    };
+                    readonly reused: {
+                        readonly type: "boolean";
+                    };
+                    readonly sessionSelection: {
+                        readonly type: "string";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["status", "requestId"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly enum: readonly ["requested", "pending"];
+                    };
+                    readonly requestId: {
+                        readonly type: readonly ["string", "null"];
+                    };
+                    readonly deferredIntentId: {
+                        readonly type: readonly ["string", "null"];
+                        readonly description: "Present when the send is deferred until the contact request resolves.";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["status", "reason"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly enum: readonly ["setup_required", "no_session", "blocked", "unavailable"];
+                    };
+                    readonly reason: {
+                        readonly type: "string";
+                    };
+                };
+            }];
+        };
+        readonly request_input_input: {
+            readonly type: "object";
+            readonly description: string;
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly timeoutMs: {
+                    readonly type: "integer";
+                    readonly minimum: 1000;
+                    readonly maximum: number;
+                    readonly description: `Relative deadline in ms (server ceiling ${string}). expiresAt wins when both are given.`;
+                };
+                readonly expiresAt: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: string;
+                };
+                readonly conversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                    readonly description: "Bindings default to the active conversation.";
+                };
+                readonly inputId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                    readonly description: "Durable single-use id (reuse -> 409); generated when omitted.";
+                };
+                readonly kind: {
+                    readonly enum: readonly ["clarify", "sudo", "secret"];
+                    readonly default: "clarify";
+                };
+                readonly title: {
+                    readonly type: "string";
+                    readonly maxLength: 160;
+                };
+                readonly prompt: {
+                    readonly type: "string";
+                    readonly maxLength: 4000;
+                };
+                readonly choices: {
+                    readonly type: "array";
+                    readonly maxItems: 12;
+                    readonly items: {
+                        $ref: string;
+                    };
+                };
+                readonly questions: {
+                    readonly type: "array";
+                    readonly maxItems: 12;
+                    readonly items: {
+                        $ref: string;
+                    };
+                };
+                readonly secretName: {
+                    readonly type: "string";
+                    readonly maxLength: 160;
+                };
+                readonly sensitive: {
+                    readonly type: "boolean";
+                };
+                readonly responseUserId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                    readonly description: string;
+                };
+                readonly native: {
+                    $ref: string;
+                };
+                readonly turnId: {
+                    readonly type: "string";
+                    readonly maxLength: 128;
+                };
+            };
+        };
+        readonly request_input_result: {
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly required: readonly ["status", "inputId", "value"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly const: "submitted";
+                    };
+                    readonly inputId: {
+                        readonly type: "string";
+                    };
+                    readonly value: {
+                        readonly type: "string";
+                        readonly description: "Free-text answer ('' when structured answers were used).";
+                    };
+                    readonly answers: {
+                        readonly type: "object";
+                        readonly description: "Structured answers keyed by question id.";
+                        readonly additionalProperties: {
+                            readonly type: "object";
+                            readonly required: readonly ["answers"];
+                            readonly properties: {
+                                readonly answers: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly type: "string";
+                                    };
+                                };
+                            };
+                        };
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["status", "inputId"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly enum: readonly ["cancelled", "timeout"];
+                    };
+                    readonly inputId: {
+                        readonly type: "string";
+                    };
+                };
+            }];
+        };
+        readonly request_approval_input: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["toolName", "toolSummary"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly timeoutMs: {
+                    readonly type: "integer";
+                    readonly minimum: 1000;
+                    readonly maximum: number;
+                    readonly description: `Relative deadline in ms (server ceiling ${string}). expiresAt wins when both are given.`;
+                };
+                readonly expiresAt: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: string;
+                };
+                readonly conversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly approvalId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                    readonly description: "Durable single-use id; server-generated when omitted.";
+                };
+                readonly toolName: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 128;
+                };
+                readonly toolSummary: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 1000;
+                    readonly description: "Pre-redact secrets — this renders to humans.";
+                };
+                readonly mode: {
+                    readonly enum: readonly ["blocking", "detached"];
+                    readonly default: "blocking";
+                };
+                readonly riskLevel: {
+                    readonly enum: readonly ["normal", "destructive"];
+                    readonly description: "Server accepts only these values; others are silently dropped, not rejected.";
+                };
+                readonly risk: {
+                    readonly enum: readonly ["low", "normal", "high", "destructive"];
+                    readonly description: "Advisory; server stores any string <= 64 chars today.";
+                };
+                readonly category: {
+                    readonly enum: readonly ["command", "file", "network", "browser", "mcp", "plugin", "canon", "tool"];
+                    readonly description: "Advisory; server stores any string <= 64 chars today.";
+                };
+                readonly details: {
+                    readonly type: "array";
+                    readonly maxItems: 8;
+                    readonly items: {
+                        $ref: string;
+                    };
+                };
+                readonly diff: {
+                    $ref: string;
+                };
+                readonly native: {
+                    $ref: string;
+                };
+                readonly runtimeId: {
+                    readonly type: "string";
+                    readonly maxLength: 128;
+                };
+                readonly turnId: {
+                    readonly type: "string";
+                    readonly maxLength: 128;
+                };
+                readonly responseUserId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly allowSessionRule: {
+                    readonly type: "boolean";
+                    readonly description: "Server forces false when the responder is not the agent owner.";
+                };
+            };
+        };
+        readonly request_approval_result: {
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly required: readonly ["status", "approvalId"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly const: "allow";
+                    };
+                    readonly approvalId: {
+                        readonly type: "string";
+                    };
+                    readonly sessionRule: {
+                        $ref: string;
+                    };
+                    readonly respondedBy: {
+                        readonly type: "string";
+                        readonly description: "Canon-authenticated responder userId.";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["status", "approvalId"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly const: "deny";
+                    };
+                    readonly approvalId: {
+                        readonly type: "string";
+                    };
+                    readonly sessionRule: {
+                        $ref: string;
+                    };
+                    readonly respondedBy: {
+                        readonly type: "string";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["status", "approvalId"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly const: "timeout";
+                    };
+                    readonly approvalId: {
+                        readonly type: "string";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly description: "Detached acceptance — the decision arrives via check_approval.";
+                readonly required: readonly ["status", "approvalId", "expiresAt"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly const: "pending";
+                    };
+                    readonly approvalId: {
+                        readonly type: "string";
+                    };
+                    readonly conversationId: {
+                        readonly type: "string";
+                    };
+                    readonly expiresAt: {
+                        readonly type: "integer";
+                    };
+                    readonly responseUserId: {
+                        readonly type: "string";
+                    };
+                };
+            }];
+        };
+        readonly check_approval_input: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["approvalId"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly approvalId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly conversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+            };
+        };
+        readonly check_approval_result: {
+            readonly description: string;
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly required: readonly ["status", "approvalId", "decision"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly const: "resolved";
+                    };
+                    readonly approvalId: {
+                        readonly type: "string";
+                    };
+                    readonly decision: {
+                        readonly enum: readonly ["allow", "deny"];
+                    };
+                    readonly respondedBy: {
+                        readonly type: "string";
+                    };
+                    readonly conversationId: {
+                        readonly type: "string";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["status", "approvalId"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly enum: readonly ["pending", "expired", "unknown"];
+                    };
+                    readonly approvalId: {
+                        readonly type: "string";
+                    };
+                    readonly expiresAt: {
+                        readonly type: "integer";
+                    };
+                    readonly conversationId: {
+                        readonly type: "string";
+                    };
+                };
+            }];
+        };
+        readonly send_card_input: {
+            readonly type: "object";
+            readonly description: "Display a card with no actions — fire-and-forget, no pending state, no deadline.";
+            readonly required: readonly ["card"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly conversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly card: {
+                    $ref: string;
+                };
+                readonly cardId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,80}$";
+                };
+                readonly native: {
+                    $ref: string;
+                };
+                readonly runtimeId: {
+                    readonly type: "string";
+                    readonly maxLength: 128;
+                };
+                readonly turnId: {
+                    readonly type: "string";
+                    readonly maxLength: 128;
+                };
+            };
+        };
+        readonly send_card_result: {
+            readonly type: "object";
+            readonly required: readonly ["status", "cardId"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly status: {
+                    readonly const: "displayed";
+                };
+                readonly cardId: {
+                    readonly type: "string";
+                };
+                readonly conversationId: {
+                    readonly type: "string";
+                };
+                readonly responseUserId: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly request_card_input: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["card"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly timeoutMs: {
+                    readonly type: "integer";
+                    readonly minimum: 1000;
+                    readonly maximum: number;
+                    readonly description: `Relative deadline in ms (server ceiling ${string}). expiresAt wins when both are given.`;
+                };
+                readonly expiresAt: {
+                    readonly type: "integer";
+                    readonly minimum: 0;
+                    readonly description: string;
+                };
+                readonly conversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly card: {
+                    $ref: string;
+                };
+                readonly cardId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,80}$";
+                };
+                readonly responseUserId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                    readonly description: string;
+                };
+                readonly native: {
+                    $ref: string;
+                };
+                readonly runtimeId: {
+                    readonly type: "string";
+                    readonly maxLength: 128;
+                };
+                readonly turnId: {
+                    readonly type: "string";
+                    readonly maxLength: 128;
+                };
+            };
+        };
+        readonly request_card_result: {
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly required: readonly ["status", "cardId"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly const: "submitted";
+                    };
+                    readonly cardId: {
+                        readonly type: "string";
+                    };
+                    readonly actionId: {
+                        readonly type: "string";
+                    };
+                    readonly values: {
+                        readonly type: "object";
+                        readonly description: string;
+                    };
+                    readonly respondedBy: {
+                        readonly type: "string";
+                        readonly description: "Canon-authenticated responder (server-verified vs responseUserId).";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["status", "cardId"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly const: "cancelled";
+                    };
+                    readonly cardId: {
+                        readonly type: "string";
+                    };
+                    readonly respondedBy: {
+                        readonly type: "string";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["status", "cardId"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly const: "timeout";
+                    };
+                    readonly cardId: {
+                        readonly type: "string";
+                    };
+                };
+            }];
+        };
+        readonly share_contact_input: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["conversationId", "contactUserId"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly conversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly contactUserId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly text: {
+                    readonly type: "string";
+                    readonly maxLength: 4096;
+                };
+                readonly messageId: {
+                    $ref: string;
+                };
+            };
+        };
+        readonly share_contact_result: {
+            readonly type: "object";
+            readonly required: readonly ["status", "messageId"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly status: {
+                    readonly const: "shared";
+                };
+                readonly messageId: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly react_input: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["conversationId", "messageId", "emoji"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly conversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly messageId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly emoji: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 64;
+                    readonly description: "Reaction key. Content-adjacent (D5) — rides the wire body.";
+                };
+            };
+        };
+        readonly react_result: {
+            readonly type: "object";
+            readonly required: readonly ["status", "action"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly status: {
+                    readonly const: "reacted";
+                };
+                readonly action: {
+                    readonly enum: readonly ["added", "removed"];
+                };
+                readonly reactions: {
+                    readonly type: "object";
+                };
+            };
+        };
+        readonly forward_input: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["sourceConversationId", "targetConversationId", "messageId"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly sourceConversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly targetConversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly messageId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+                readonly text: {
+                    readonly type: "string";
+                    readonly maxLength: 4096;
+                    readonly description: "Optional caption; <= 4096 UTF-8 bytes.";
+                };
+            };
+        };
+        readonly forward_result: {
+            readonly type: "object";
+            readonly required: readonly ["status", "messageId", "targetConversationId"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly status: {
+                    readonly const: "forwarded";
+                };
+                readonly messageId: {
+                    readonly type: "string";
+                };
+                readonly targetConversationId: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly create_group_input: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["name", "memberIds"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                    readonly maxLength: 100;
+                };
+                readonly memberIds: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly maxItems: number;
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly description: "Other members; the caller is added automatically.";
+                };
+            };
+        };
+        readonly create_group_result: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["status", "conversationId"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly status: {
+                    readonly const: "created";
+                };
+                readonly conversationId: {
+                    readonly type: "string";
+                };
+                readonly pending: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["userId", "requestId"];
+                        readonly additionalProperties: true;
+                        readonly properties: {
+                            readonly userId: {
+                                readonly type: "string";
+                            };
+                            readonly requestId: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+                readonly skipped: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["userId", "reason"];
+                        readonly additionalProperties: true;
+                        readonly properties: {
+                            readonly userId: {
+                                readonly type: "string";
+                            };
+                            readonly reason: {
+                                readonly type: "string";
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly add_member_input: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["conversationId", "userId"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly conversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly userId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+            };
+        };
+        readonly add_member_result: {
+            readonly description: string;
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly required: readonly ["status"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly const: "added";
+                    };
+                };
+            }, {
+                readonly type: "object";
+                readonly required: readonly ["status", "requestId"];
+                readonly additionalProperties: true;
+                readonly properties: {
+                    readonly status: {
+                        readonly const: "pending";
+                    };
+                    readonly requestId: {
+                        readonly type: "string";
+                    };
+                };
+            }];
+        };
+        readonly remove_member_input: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["conversationId", "userId"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly conversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+                readonly userId: {
+                    readonly type: "string";
+                    readonly minLength: 1;
+                };
+            };
+        };
+        readonly remove_member_result: {
+            readonly type: "object";
+            readonly required: readonly ["status"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly status: {
+                    readonly const: "removed";
+                };
+            };
+        };
+        readonly leave_conversation_input: {
+            readonly type: "object";
+            readonly required: readonly ["conversationId"];
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly conversationId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_.:-]{1,160}$";
+                };
+            };
+        };
+        readonly leave_conversation_result: {
+            readonly type: "object";
+            readonly required: readonly ["status"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly status: {
+                    readonly const: "left";
+                };
+            };
+        };
+        readonly list_contacts_input: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {};
+        };
+        readonly list_contacts_result: {
+            readonly type: "object";
+            readonly required: readonly ["contacts"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly contacts: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["id", "source", "addedAt", "displayNameOverride"];
+                        readonly additionalProperties: true;
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                                readonly description: "The contact's userId.";
+                            };
+                            readonly source: {
+                                readonly type: "string";
+                                readonly description: string;
+                            };
+                            readonly addedAt: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly displayNameOverride: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly list_contact_requests_input: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {};
+        };
+        readonly list_contact_requests_result: {
+            readonly type: "object";
+            readonly description: string;
+            readonly required: readonly ["requests"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly requests: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["id", "requesterId", "targetId", "status", "kind"];
+                        readonly additionalProperties: true;
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                            readonly requesterId: {
+                                readonly type: "string";
+                            };
+                            readonly requesterName: {
+                                readonly type: "string";
+                            };
+                            readonly targetId: {
+                                readonly type: "string";
+                            };
+                            readonly status: {
+                                readonly enum: readonly ["pending", "approved", "rejected", "expired"];
+                            };
+                            readonly kind: {
+                                readonly enum: readonly ["dm", "group_invite"];
+                            };
+                            readonly message: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly createdAt: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly expiresAt: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        readonly list_conversations_input: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly limit: {
+                    readonly type: "integer";
+                    readonly minimum: 1;
+                    readonly description: string;
+                };
+            };
+        };
+        readonly list_conversations_result: {
+            readonly type: "object";
+            readonly required: readonly ["conversations"];
+            readonly additionalProperties: true;
+            readonly properties: {
+                readonly conversations: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly required: readonly ["id", "type", "memberIds", "isAgentChat", "topic", "lastMessage", "createdAt"];
+                        readonly additionalProperties: true;
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                            };
+                            readonly type: {
+                                readonly enum: readonly ["direct", "group"];
+                            };
+                            readonly name: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly topic: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                            readonly memberIds: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly isAgentChat: {
+                                readonly type: "boolean";
+                            };
+                            readonly hasUnread: {
+                                readonly type: "boolean";
+                            };
+                            readonly lastMessage: {
+                                readonly type: readonly ["object", "null"];
+                                readonly additionalProperties: true;
+                                readonly properties: {
+                                    readonly text: {
+                                        readonly type: readonly ["string", "null"];
+                                    };
+                                    readonly messageId: {
+                                        readonly type: "string";
+                                    };
+                                    readonly senderId: {
+                                        readonly type: "string";
+                                    };
+                                    readonly senderType: {
+                                        readonly type: "string";
+                                    };
+                                    readonly contentType: {
+                                        readonly type: "string";
+                                    };
+                                    readonly timestamp: {
+                                        readonly type: readonly ["string", "null"];
+                                    };
+                                };
+                            };
+                            readonly createdAt: {
+                                readonly type: readonly ["string", "null"];
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+/** Pointer pair into the bundle for one verb. */
+export interface CanonVerbSchemaRefs {
+    input: string;
+    result: string;
+}
+export declare const CANON_VERB_SCHEMA_REFS: Record<CanonVerbName, CanonVerbSchemaRefs>;
+/** A verb subschema extracted from the bundle, self-contained for embedding. */
+export type CanonVerbJsonSchema = Record<string, unknown>;
+export interface GetVerbSchemaOptions {
+    /**
+     * The full canon.card.v1 document schema (@canonmsg/rich-cards
+     * RUNTIME_CARD_JSON_SCHEMA_V1) to compose into card-carrying verbs. When
+     * provided, the envelope-only `runtimeCard` definition is replaced so block
+     * structures validate too. backend-contracts deliberately does not depend
+     * on rich-cards (build-order/dependency direction), so the binding supplies
+     * the schema.
+     *
+     * The card schema is REBASED, not nested: its own `$defs` are merged into
+     * the verb schema's `$defs` under `card__`-prefixed names and every
+     * internal `#/$defs/...` ref (including `<card $id>#/$defs/...` forms) is
+     * rewritten accordingly. The result is a single self-contained schema
+     * resource with plain internal refs — no embedded `$id` — so it compiles
+     * on naive validators and never conflicts with a separately registered
+     * canon.card.v1 resource on the same Ajv instance.
+     *
+     * Ajv note: the real card schema uses spec-valid union types
+     * (min/max: number | date-string), so compile composed schemas with
+     * `{ strict: true, allowUnionTypes: true }`.
+     */
+    cardSchema?: Record<string, unknown>;
+}
+/** Self-contained input schema for a verb (for embedding into tool definitions). */
+export declare function getVerbInputSchema(verb: CanonVerbName, options?: GetVerbSchemaOptions): CanonVerbJsonSchema;
+/** Self-contained result schema for a verb. */
+export declare function getVerbResultSchema(verb: CanonVerbName): CanonVerbJsonSchema;