@canonmsg/backend-contracts 2.1.0 → 2.3.0

package/dist/canon-verb-wire.schema.json

@@ -0,0 +1,367 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://canonmsg.com/schemas/canon.verb-wire.v1.json",
+  "title": "Canon Verb Wire v1",
+  "description": "The remote wire contract for agent verbs: authenticated envelope + json-or-mls body. The semantic intent contract (canon.verbs.v1) is local; this is what crosses the network.",
+  "type": "object",
+  "required": [
+    "wire",
+    "verb",
+    "envelope",
+    "body"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "wire": {
+      "const": "canon.verb-wire.v1"
+    },
+    "verb": {
+      "enum": [
+        "send_to",
+        "request_input",
+        "request_approval",
+        "check_approval",
+        "send_card",
+        "request_card",
+        "share_contact",
+        "react",
+        "forward",
+        "create_group",
+        "add_member",
+        "remove_member",
+        "leave_conversation",
+        "list_contacts",
+        "list_contact_requests",
+        "list_conversations"
+      ]
+    },
+    "envelope": {
+      "$ref": "#/$defs/envelope"
+    },
+    "body": {
+      "$ref": "#/$defs/body"
+    }
+  },
+  "$defs": {
+    "body": {
+      "description": "The verb body: plaintext JSON for temporary/plaintext conversations, MLS ciphertext for encrypted ones. In json mode the server may read value to execute legacy behavior; in mls mode it is opaque.",
+      "oneOf": [
+        {
+          "type": "object",
+          "required": [
+            "encoding",
+            "value"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "encoding": {
+              "const": "json"
+            },
+            "value": {
+              "type": "object"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": [
+            "encoding",
+            "epoch",
+            "ciphertext",
+            "aadHash"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "encoding": {
+              "const": "mls"
+            },
+            "epoch": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "ciphertext": {
+              "type": "string",
+              "minLength": 1
+            },
+            "aadHash": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Hash binding the envelope (AAD) to the ciphertext."
+            }
+          }
+        }
+      ]
+    },
+    "envelope": {
+      "type": "object",
+      "description": "Authenticated public envelope: routing/policy metadata only, never content. Per-verb field discipline: VERB_WIRE_ENVELOPE_FIELDS.",
+      "additionalProperties": false,
+      "properties": {
+        "conversationId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_.:-]{1,160}$"
+        },
+        "targetUserId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "canonContactId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sourceConversationId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_.:-]{1,160}$"
+        },
+        "contactUserId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "requestId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_.:-]{1,160}$"
+        },
+        "responseUserId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_.:-]{1,160}$"
+        },
+        "expiresAt": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "mode": {
+          "enum": [
+            "blocking",
+            "detached"
+          ]
+        },
+        "kind": {
+          "enum": [
+            "clarify",
+            "sudo",
+            "secret"
+          ]
+        },
+        "sensitive": {
+          "type": "boolean"
+        },
+        "allowSessionRule": {
+          "type": "boolean"
+        },
+        "riskLevel": {
+          "enum": [
+            "normal",
+            "destructive"
+          ]
+        },
+        "risk": {
+          "enum": [
+            "low",
+            "normal",
+            "high",
+            "destructive"
+          ]
+        },
+        "category": {
+          "enum": [
+            "command",
+            "file",
+            "network",
+            "browser",
+            "mcp",
+            "plugin",
+            "canon",
+            "tool"
+          ]
+        },
+        "sessionSelection": {
+          "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": "^[A-Za-z0-9_.:-]{1,160}$"
+                }
+              }
+            }
+          ]
+        },
+        "sessionConfig": {
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "idempotencyKey": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_.:-]{1,160}$",
+          "not": {
+            "pattern": "^(\\.{1,2}|__.*__)$"
+          }
+        },
+        "messageId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "replyTo": {
+          "type": "string"
+        },
+        "replyToPosition": {
+          "type": "integer"
+        },
+        "mentions": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Plaintext by decision D3 (routing + mention-piercing pushes)."
+        },
+        "memberIds": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1,
+          "description": "Group-membership routing ids (create_group). Plaintext like mentions (D3 rationale) but a distinct field — membership operations must not overload the mention slot."
+        },
+        "turn": {
+          "$ref": "#/$defs/turn"
+        },
+        "native": {
+          "type": "object"
+        },
+        "runtimeId": {
+          "type": "string",
+          "maxLength": 128
+        },
+        "limit": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "turn": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "turnId": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "turnSemantics": {
+          "enum": [
+            "progress",
+            "turn_complete",
+            "control"
+          ]
+        },
+        "deliveryIntent": {
+          "enum": [
+            "queue",
+            "interrupt",
+            "interleave",
+            "stop"
+          ]
+        },
+        "replyBehavior": {
+          "enum": [
+            "allow_auto_reply",
+            "suppress_auto_reply"
+          ]
+        }
+      }
+    },
+    "accepted": {
+      "type": "object",
+      "required": [
+        "status",
+        "requestId"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "status": {
+          "const": "accepted"
+        },
+        "requestId": {
+          "type": "string"
+        },
+        "expiresAt": {
+          "type": "integer"
+        },
+        "messageId": {
+          "type": "string"
+        },
+        "responseUserId": {
+          "type": "string"
+        },
+        "interactive": {
+          "type": "boolean"
+        }
+      }
+    },
+    "response": {
+      "type": "object",
+      "required": [
+        "wire",
+        "verb",
+        "result"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "wire": {
+          "const": "canon.verb-wire.v1"
+        },
+        "verb": {
+          "enum": [
+            "send_to",
+            "request_input",
+            "request_approval",
+            "check_approval",
+            "send_card",
+            "request_card",
+            "share_contact",
+            "react",
+            "forward",
+            "create_group",
+            "add_member",
+            "remove_member",
+            "leave_conversation",
+            "list_contacts",
+            "list_contact_requests",
+            "list_conversations"
+          ]
+        },
+        "result": {
+          "$ref": "#/$defs/body"
+        }
+      }
+    }
+  }
+}

package/dist/canon-verbs.limits.json

@@ -0,0 +1,70 @@
+{
+  "schemaVersion": "canon.verbs.v1",
+  "limits": {
+    "messageTextBytes": 4096,
+    "messageMetadataJsonChars": 4096,
+    "messageAttachments": 10,
+    "messageIdChars": 160,
+    "messageIdBytes": 256,
+    "selfContextChars": 1000,
+    "contactRequestNoteChars": 500,
+    "groupMembers": 50,
+    "inputTitleChars": 160,
+    "inputPromptChars": 4000,
+    "inputChoices": 12,
+    "inputChoiceLabelChars": 120,
+    "inputChoiceValueChars": 200,
+    "inputChoiceDescriptionChars": 300,
+    "inputQuestions": 12,
+    "inputQuestionChars": 1000,
+    "inputQuestionHeaderChars": 120,
+    "inputSecretNameChars": 160,
+    "inputAnswerChars": 8192,
+    "toolNameChars": 128,
+    "toolSummaryChars": 1000,
+    "approvalDetails": 8,
+    "approvalDetailLabelChars": 80,
+    "approvalDetailValueChars": 500,
+    "diffFiles": 100,
+    "diffPathChars": 1024,
+    "diffFileBytes": 24576,
+    "diffTotalBytes": 98304,
+    "cardEnvelopeBytes": 32768,
+    "cardServerTitleChars": 200,
+    "cardServerFallbackTextChars": 2000,
+    "cardServerBlocks": 64,
+    "cardValuesBytes": 8192,
+    "cardValuesDepth": 8,
+    "nativeKeys": 24,
+    "nativeValueChars": 256,
+    "nativeHandles": 16,
+    "minTimeoutMs": 1000,
+    "maxTimeoutMs": 1800000,
+    "maxApprovalTimeoutMs": 259200000,
+    "turnIdChars": 128,
+    "reactionEmojiChars": 64,
+    "groupNameChars": 100
+  },
+  "rateLimits": {
+    "senderMessagesPer5Min": 300,
+    "conversationMessagesPer5Min": 120,
+    "agentPeerMessagesPerHour": 30
+  },
+  "idPatterns": {
+    "runtimeId": "^[A-Za-z0-9_.:-]{1,160}$",
+    "cardId": "^[A-Za-z0-9_.:-]{1,80}$",
+    "actionId": "^[A-Za-z0-9_.:-]{1,80}$",
+    "questionId": "^[A-Za-z0-9_.:-]{1,120}$",
+    "sessionRuleToolPattern": "^[\\w.*:-]{1,128}$"
+  },
+  "byteSemantics": {
+    "send_to.text": "utf8_bytes<=messageTextBytes",
+    "share_contact.text": "utf8_bytes<=messageTextBytes",
+    "forward.text": "utf8_bytes<=messageTextBytes",
+    "send_to.messageOptions.messageId": "utf8_bytes<=messageIdBytes",
+    "share_contact.messageId": "utf8_bytes<=messageIdBytes",
+    "send_to.messageOptions.metadata": "json_stringify_chars<=messageMetadataJsonChars",
+    "send_card.card": "json_utf8_bytes<=cardEnvelopeBytes",
+    "request_card.card": "json_utf8_bytes<=cardEnvelopeBytes"
+  }
+}