@canonmsg/backend-contracts 2.2.0 → 3.0.0

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

@@ -212,9 +212,68 @@
           ]
         },
         "sessionConfig": {
-          "type": [
-            "object",
-            "null"
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Typed setup policy for an agent target. Values are stable runtime-advertised option ids and are validated against the target descriptor before session creation; labels, prompts, workspace paths, and arbitrary fields are not permitted.",
+              "additionalProperties": false,
+              "properties": {
+                "model": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$",
+                  "maxLength": 256
+                },
+                "permissionMode": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$",
+                  "maxLength": 256
+                },
+                "effort": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$",
+                  "maxLength": 256
+                },
+                "workspaceId": {
+                  "type": "string",
+                  "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+                  "maxLength": 256
+                },
+                "executionMode": {
+                  "enum": [
+                    "worktree",
+                    "locked"
+                  ]
+                },
+                "runtimeControlValues": {
+                  "type": "object",
+                  "maxProperties": 24,
+                  "propertyNames": {
+                    "pattern": "^[A-Za-z0-9_-]{1,80}$",
+                    "not": {
+                      "enum": [
+                        "model",
+                        "workspace",
+                        "executionMode",
+                        "permissionMode",
+                        "effort",
+                        "interrupt",
+                        "runtimeControlValues",
+                        "updatedAt",
+                        "updatedBy"
+                      ]
+                    }
+                  },
+                  "additionalProperties": {
+                    "type": "string",
+                    "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$",
+                    "maxLength": 256
+                  }
+                }
+              }
+            },
+            {
+              "type": "null"
+            }
           ]
         },
         "idempotencyKey": {
@@ -253,7 +312,99 @@
           "$ref": "#/$defs/turn"
         },
         "native": {
-          "type": "object"
+          "type": "object",
+          "description": "Content-free runtime correlation ids. Commands, paths, prompts, summaries, and model labels are not permitted in this public envelope.",
+          "maxProperties": 24,
+          "additionalProperties": false,
+          "properties": {
+            "runtime": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "method": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "requestId": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "provider": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "origin": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "surface": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "threadId": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "turnId": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "runId": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "itemId": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "toolCallId": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "approvalId": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "pluginId": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "sessionKey": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "nodeId": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+              "maxLength": 256
+            },
+            "handles": {
+              "type": "object",
+              "maxProperties": 16,
+              "propertyNames": {
+                "pattern": "^[A-Za-z0-9_.:-]{1,80}$"
+              },
+              "additionalProperties": {
+                "type": "string",
+                "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+                "maxLength": 256
+              }
+            }
+          }
         },
         "runtimeId": {
           "type": "string",

package/dist/canon-verbs.limits.json

@@ -38,6 +38,8 @@
     "nativeKeys": 24,
     "nativeValueChars": 256,
     "nativeHandles": 16,
+    "sessionConfigValues": 24,
+    "sessionConfigValueChars": 256,
     "minTimeoutMs": 1000,
     "maxTimeoutMs": 1800000,
     "maxApprovalTimeoutMs": 259200000,
@@ -55,7 +57,13 @@
     "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}$"
+    "sessionRuleToolPattern": "^[\\w.*:-]{1,128}$",
+    "runtimeCorrelationValue": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+    "runtimeMethod": "^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$",
+    "runtimeOptionValue": "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$",
+    "workspaceOptionId": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+    "runtimeHandleKey": "^[A-Za-z0-9_.:-]{1,80}$",
+    "runtimeControlId": "^[A-Za-z0-9_-]{1,80}$"
   },
   "byteSemantics": {
     "send_to.text": "utf8_bytes<=messageTextBytes",

package/dist/canon-verbs.schema.json

@@ -424,8 +424,156 @@
     },
     "native": {
       "type": "object",
-      "description": "Runtime correlation handles (<= 24 keys, string values <= 256 chars or a nested handles map <= 16; functions/src/api/interactionKinds.ts normalizeNative).",
-      "additionalProperties": true
+      "description": "Content-free runtime correlation ids. Commands, paths, prompts, summaries, and model labels are not permitted in this public envelope.",
+      "maxProperties": 24,
+      "additionalProperties": false,
+      "properties": {
+        "runtime": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "method": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "requestId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "provider": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "origin": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "surface": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "threadId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "turnId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "runId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "itemId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "toolCallId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "approvalId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "pluginId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "sessionKey": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "nodeId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "handles": {
+          "type": "object",
+          "maxProperties": 16,
+          "propertyNames": {
+            "pattern": "^[A-Za-z0-9_.:-]{1,80}$"
+          },
+          "additionalProperties": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+            "maxLength": 256
+          }
+        }
+      }
+    },
+    "sessionConfig": {
+      "type": "object",
+      "description": "Typed setup policy for an agent target. Values are stable runtime-advertised option ids and are validated against the target descriptor before session creation; labels, prompts, workspace paths, and arbitrary fields are not permitted.",
+      "additionalProperties": false,
+      "properties": {
+        "model": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "permissionMode": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "effort": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "workspaceId": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$",
+          "maxLength": 256
+        },
+        "executionMode": {
+          "enum": [
+            "worktree",
+            "locked"
+          ]
+        },
+        "runtimeControlValues": {
+          "type": "object",
+          "maxProperties": 24,
+          "propertyNames": {
+            "pattern": "^[A-Za-z0-9_-]{1,80}$",
+            "not": {
+              "enum": [
+                "model",
+                "workspace",
+                "executionMode",
+                "permissionMode",
+                "effort",
+                "interrupt",
+                "runtimeControlValues",
+                "updatedAt",
+                "updatedBy"
+              ]
+            }
+          },
+          "additionalProperties": {
+            "type": "string",
+            "pattern": "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$",
+            "maxLength": 256
+          }
+        }
+      }
     },
     "send_to_input": {
       "type": "object",
@@ -466,9 +614,13 @@
           "$ref": "#/$defs/sessionSelection"
         },
         "sessionConfig": {
-          "type": [
-            "object",
-            "null"
+          "oneOf": [
+            {
+              "$ref": "#/$defs/sessionConfig"
+            },
+            {
+              "type": "null"
+            }
           ],
           "description": "Coding-agent session setup (model/permissionMode/effort/workspaceId/executionMode); only applied to agent targets, stripped for humans."
         },
@@ -667,7 +819,7 @@
         "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."
+          "description": "Absolute epoch-ms deadline. The REST interaction creators REQUIRE a deadline (input interactions also require input subtype kind): bindings must fill defaults and convert timeoutMs into expiresAt before calling the endpoint."
         }
       }
     },
@@ -836,7 +988,7 @@
         "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."
+          "description": "Absolute epoch-ms deadline. The REST interaction creators REQUIRE a deadline (input interactions also require input subtype kind): bindings must fill defaults and convert timeoutMs into expiresAt before calling the endpoint."
         }
       }
     },
@@ -951,7 +1103,7 @@
       }
     },
     "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.",
+      "description": "'unknown' is NOT a denial — only 'resolved' carries a decision. Canonical statuses map from the approval interaction consume result as: allow/deny -> resolved.decision, timeout -> expired, pending -> pending, HTTP 404 RUNTIME_APPROVAL_NOT_FOUND -> unknown.",
       "oneOf": [
         {
           "type": "object",
@@ -1108,7 +1260,7 @@
         "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."
+          "description": "Absolute epoch-ms deadline. The REST interaction creators REQUIRE a deadline (input interactions also require input subtype kind): bindings must fill defaults and convert timeoutMs into expiresAt before calling the endpoint."
         }
       }
     },

package/dist/cjs/contactRequest.js

@@ -74,7 +74,10 @@ function serializeContactRequest(requestId, data) {
         targetAvatarUrl: typeof data.targetAvatarUrl === 'string' ? data.targetAvatarUrl : null,
         targetUserType: data.targetUserType,
         approverId: data.approverId,
-        message: typeof data.message === 'string' ? data.message : null,
+        // Free-form request content is owner-review material. This shared DTO is
+        // delivered to the target agent over REST/SSE, so it must never cross the
+        // admission boundary before the human approver accepts the reach-out.
+        message: null,
         status: normalizeStatus(data.status),
         kind: kindValue,
         createdAt: normalizeTimestamp(data.createdAt),

package/dist/cjs/environment.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANON_ENVIRONMENT_CONTRACTS = void 0;
+exports.getCanonEnvironmentContract = getCanonEnvironmentContract;
+exports.CANON_ENVIRONMENT_CONTRACTS = Object.freeze({
+    'canon-dev-v1': Object.freeze({
+        name: 'dev',
+        projectId: 'canonmail-dev',
+        region: 'europe-west1',
+    }),
+    'canon-prod-v1': Object.freeze({
+        name: 'prod',
+        projectId: 'canonmail-prod',
+        region: 'europe-west1',
+    }),
+    'canon-legacy-v1': Object.freeze({
+        name: 'legacy',
+        projectId: 'project-007a8e71-ba01-49e6-8aa',
+        region: 'us-central1',
+    }),
+});
+function getCanonEnvironmentContract(value) {
+    const environmentId = value.trim();
+    const contract = exports.CANON_ENVIRONMENT_CONTRACTS[environmentId];
+    if (!contract) {
+        throw new Error(`Unsupported Canon environment ID: ${value}`);
+    }
+    return Object.freeze({ environmentId, ...contract });
+}

package/dist/cjs/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./diffRedaction.js"), exports);
+__exportStar(require("./environment.js"), exports);
 __exportStar(require("./media.js"), exports);
 __exportStar(require("./message.js"), exports);
 __exportStar(require("./runtimeCardFields.js"), exports);

package/dist/cjs/verbContract.js

@@ -41,7 +41,8 @@
  * canon-verbs.limits.json) after schema validation.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CANON_VERB_LIMITS_ARTIFACT = exports.CREATE_GROUP_CREATOR_SETUP_REQUIRED_CODE = exports.CREATE_GROUP_NO_ADDABLE_MEMBERS_CODE = exports.CANON_VERB_NAMES = exports.SELF_CONTEXT_TYPE = exports.VERB_RATE_LIMITS = exports.VERB_LIMITS = exports.VERB_ID_PATTERNS = exports.CANON_CARD_SCHEMA_ID = exports.CANON_VERB_NAMESPACE = exports.CANON_VERBS_SCHEMA_ID = exports.CANON_VERBS_SCHEMA_VERSION = void 0;
+exports.CANON_VERB_LIMITS_ARTIFACT = exports.CREATE_GROUP_CREATOR_SETUP_REQUIRED_CODE = exports.CREATE_GROUP_NO_ADDABLE_MEMBERS_CODE = exports.VERB_NATIVE_METADATA_KEYS = exports.CANON_VERB_NAMES = exports.SELF_CONTEXT_TYPE = exports.VERB_RATE_LIMITS = exports.VERB_LIMITS = exports.VERB_ID_PATTERNS = exports.CANON_CARD_SCHEMA_ID = exports.CANON_VERB_NAMESPACE = exports.CANON_VERBS_SCHEMA_ID = exports.CANON_VERBS_SCHEMA_VERSION = void 0;
+exports.normalizeVerbNativeMetadata = normalizeVerbNativeMetadata;
 exports.canonVerbToolName = canonVerbToolName;
 exports.findVerbByteLimitViolations = findVerbByteLimitViolations;
 /** Identifier for this contract document. */
@@ -72,6 +73,12 @@ exports.VERB_ID_PATTERNS = {
     actionId: '^[A-Za-z0-9_.:-]{1,80}$',
     questionId: '^[A-Za-z0-9_.:-]{1,120}$',
     sessionRuleToolPattern: '^[\\w.*:-]{1,128}$',
+    runtimeCorrelationValue: '^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$',
+    runtimeMethod: '^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$',
+    runtimeOptionValue: '^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$',
+    workspaceOptionId: '^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$',
+    runtimeHandleKey: '^[A-Za-z0-9_.:-]{1,80}$',
+    runtimeControlId: '^[A-Za-z0-9_-]{1,80}$',
 };
 /**
  * Server-enforced limits, single-sourced. Each value cites its enforcement
@@ -139,6 +146,9 @@ exports.VERB_LIMITS = {
     nativeKeys: 24,
     nativeValueChars: 256,
     nativeHandles: 16,
+    /** Initial agent-session setup carried by send_to. */
+    sessionConfigValues: 24,
+    sessionConfigValueChars: 256,
     /** Deadlines (functions/src/utils/runtimeRequestHelpers.ts). */
     minTimeoutMs: 1000,
     /** input/card/plan ceiling (30 minutes). */
@@ -186,6 +196,65 @@ exports.CANON_VERB_NAMES = [
     'list_contact_requests',
     'list_conversations',
 ];
+exports.VERB_NATIVE_METADATA_KEYS = [
+    'runtime',
+    'method',
+    'requestId',
+    'provider',
+    'origin',
+    'surface',
+    'threadId',
+    'turnId',
+    'runId',
+    'itemId',
+    'toolCallId',
+    'approvalId',
+    'pluginId',
+    'sessionKey',
+    'nodeId',
+    'handles',
+];
+const VERB_NATIVE_STRING_KEYS = exports.VERB_NATIVE_METADATA_KEYS.filter((key) => key !== 'handles');
+const RUNTIME_CORRELATION_VALUE_PATTERN = new RegExp(exports.VERB_ID_PATTERNS.runtimeCorrelationValue);
+const RUNTIME_METHOD_PATTERN = new RegExp(exports.VERB_ID_PATTERNS.runtimeMethod);
+const RUNTIME_HANDLE_KEY_PATTERN = new RegExp(exports.VERB_ID_PATTERNS.runtimeHandleKey);
+function isPlainRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+/**
+ * Keep only the typed, content-free runtime correlation contract. Invalid or
+ * unknown fields are omitted on compatibility REST paths; canon.verb-wire.v1
+ * rejects the same fields through its strict JSON Schema.
+ */
+function normalizeVerbNativeMetadata(value) {
+    if (!isPlainRecord(value))
+        return undefined;
+    const native = {};
+    for (const key of VERB_NATIVE_STRING_KEYS) {
+        const raw = value[key];
+        if (typeof raw !== 'string')
+            continue;
+        const normalized = raw.trim();
+        const pattern = key === 'method'
+            ? RUNTIME_METHOD_PATTERN
+            : RUNTIME_CORRELATION_VALUE_PATTERN;
+        if (pattern.test(normalized))
+            native[key] = normalized;
+    }
+    if (isPlainRecord(value.handles)) {
+        const handles = {};
+        for (const [key, raw] of Object.entries(value.handles).slice(0, exports.VERB_LIMITS.nativeHandles)) {
+            if (!RUNTIME_HANDLE_KEY_PATTERN.test(key) || typeof raw !== 'string')
+                continue;
+            const normalized = raw.trim();
+            if (RUNTIME_CORRELATION_VALUE_PATTERN.test(normalized))
+                handles[key] = normalized;
+        }
+        if (Object.keys(handles).length > 0)
+            native.handles = handles;
+    }
+    return Object.keys(native).length > 0 ? native : undefined;
+}
 /**
  * Error code on the 400 a create_group receives when NO member is directly
  * addable (approval-required members can only be invited to an existing