@canonmsg/backend-contracts 2.2.0 → 3.0.0

package/dist/verbSchemas.d.ts

@@ -28,6 +28,146 @@
  *   endpoints validate against these schemas directly).
  */
 import { type CanonVerbName } from './verbContract.js';
+export declare const VERB_NATIVE_METADATA_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly description: string;
+    readonly maxProperties: 24;
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly runtime: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly method: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly requestId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly provider: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly origin: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly surface: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly threadId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly turnId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly runId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly itemId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly toolCallId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly approvalId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly pluginId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly sessionKey: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly nodeId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly handles: {
+            readonly type: "object";
+            readonly maxProperties: 16;
+            readonly propertyNames: {
+                readonly pattern: "^[A-Za-z0-9_.:-]{1,80}$";
+            };
+            readonly additionalProperties: {
+                readonly type: "string";
+                readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                readonly maxLength: 256;
+            };
+        };
+    };
+};
+export declare const VERB_SESSION_CONFIG_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly description: string;
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly model: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly permissionMode: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly effort: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly workspaceId: {
+            readonly type: "string";
+            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+            readonly maxLength: 256;
+        };
+        readonly executionMode: {
+            readonly enum: readonly ["worktree", "locked"];
+        };
+        readonly runtimeControlValues: {
+            readonly type: "object";
+            readonly maxProperties: 24;
+            readonly propertyNames: {
+                readonly pattern: "^[A-Za-z0-9_-]{1,80}$";
+                readonly not: {
+                    readonly enum: readonly ["model", "workspace", "executionMode", "permissionMode", "effort", "interrupt", "runtimeControlValues", "updatedAt", "updatedBy"];
+                };
+            };
+            readonly additionalProperties: {
+                readonly type: "string";
+                readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                readonly maxLength: 256;
+            };
+        };
+    };
+};
 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";
@@ -372,7 +512,142 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
         readonly native: {
             readonly type: "object";
             readonly description: string;
-            readonly additionalProperties: true;
+            readonly maxProperties: 24;
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly runtime: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly method: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly requestId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly provider: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly origin: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly surface: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly threadId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly turnId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly runId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly itemId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly toolCallId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly approvalId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly pluginId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly sessionKey: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly nodeId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly handles: {
+                    readonly type: "object";
+                    readonly maxProperties: 16;
+                    readonly propertyNames: {
+                        readonly pattern: "^[A-Za-z0-9_.:-]{1,80}$";
+                    };
+                    readonly additionalProperties: {
+                        readonly type: "string";
+                        readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                        readonly maxLength: 256;
+                    };
+                };
+            };
+        };
+        readonly sessionConfig: {
+            readonly type: "object";
+            readonly description: string;
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly model: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly permissionMode: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly effort: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly workspaceId: {
+                    readonly type: "string";
+                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                    readonly maxLength: 256;
+                };
+                readonly executionMode: {
+                    readonly enum: readonly ["worktree", "locked"];
+                };
+                readonly runtimeControlValues: {
+                    readonly type: "object";
+                    readonly maxProperties: 24;
+                    readonly propertyNames: {
+                        readonly pattern: "^[A-Za-z0-9_-]{1,80}$";
+                        readonly not: {
+                            readonly enum: readonly ["model", "workspace", "executionMode", "permissionMode", "effort", "interrupt", "runtimeControlValues", "updatedAt", "updatedBy"];
+                        };
+                    };
+                    readonly additionalProperties: {
+                        readonly type: "string";
+                        readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                        readonly maxLength: 256;
+                    };
+                };
+            };
         };
         readonly send_to_input: {
             readonly type: "object";
@@ -413,7 +688,11 @@ export declare const CANON_VERBS_JSON_SCHEMA: {
                     $ref: string;
                 };
                 readonly sessionConfig: {
-                    readonly type: readonly ["object", "null"];
+                    readonly oneOf: readonly [{
+                        $ref: string;
+                    }, {
+                        readonly type: "null";
+                    }];
                     readonly description: string;
                 };
                 readonly messageOptions: {

package/dist/verbSchemas.js

@@ -247,12 +247,89 @@ const runtimeCardDef = {
         blocks: { type: 'array', minItems: 1, maxItems: VERB_LIMITS.cardServerBlocks },
     },
 };
-const nativeDef = {
+const runtimeCorrelationValueDef = {
+    type: 'string',
+    pattern: VERB_ID_PATTERNS.runtimeCorrelationValue,
+    maxLength: VERB_LIMITS.nativeValueChars,
+};
+const runtimeMethodDef = {
+    type: 'string',
+    pattern: VERB_ID_PATTERNS.runtimeMethod,
+    maxLength: VERB_LIMITS.nativeValueChars,
+};
+export const VERB_NATIVE_METADATA_JSON_SCHEMA = {
     type: 'object',
-    description: `Runtime correlation handles (<= ${VERB_LIMITS.nativeKeys} keys, string values <= `
-        + `${VERB_LIMITS.nativeValueChars} chars or a nested handles map <= ${VERB_LIMITS.nativeHandles}; `
-        + 'functions/src/api/interactionKinds.ts normalizeNative).',
-    additionalProperties: true,
+    description: 'Content-free runtime correlation ids. Commands, paths, prompts, summaries, '
+        + 'and model labels are not permitted in this public envelope.',
+    maxProperties: VERB_LIMITS.nativeKeys,
+    additionalProperties: false,
+    properties: {
+        runtime: runtimeCorrelationValueDef,
+        method: runtimeMethodDef,
+        requestId: runtimeCorrelationValueDef,
+        provider: runtimeCorrelationValueDef,
+        origin: runtimeCorrelationValueDef,
+        surface: runtimeCorrelationValueDef,
+        threadId: runtimeCorrelationValueDef,
+        turnId: runtimeCorrelationValueDef,
+        runId: runtimeCorrelationValueDef,
+        itemId: runtimeCorrelationValueDef,
+        toolCallId: runtimeCorrelationValueDef,
+        approvalId: runtimeCorrelationValueDef,
+        pluginId: runtimeCorrelationValueDef,
+        sessionKey: runtimeCorrelationValueDef,
+        nodeId: runtimeCorrelationValueDef,
+        handles: {
+            type: 'object',
+            maxProperties: VERB_LIMITS.nativeHandles,
+            propertyNames: { pattern: VERB_ID_PATTERNS.runtimeHandleKey },
+            additionalProperties: runtimeCorrelationValueDef,
+        },
+    },
+};
+const sessionConfigValueDef = {
+    type: 'string',
+    pattern: VERB_ID_PATTERNS.runtimeOptionValue,
+    maxLength: VERB_LIMITS.sessionConfigValueChars,
+};
+export const VERB_SESSION_CONFIG_JSON_SCHEMA = {
+    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: sessionConfigValueDef,
+        permissionMode: sessionConfigValueDef,
+        effort: sessionConfigValueDef,
+        workspaceId: {
+            type: 'string',
+            pattern: VERB_ID_PATTERNS.workspaceOptionId,
+            maxLength: VERB_LIMITS.sessionConfigValueChars,
+        },
+        executionMode: { enum: ['worktree', 'locked'] },
+        runtimeControlValues: {
+            type: 'object',
+            maxProperties: VERB_LIMITS.sessionConfigValues,
+            propertyNames: {
+                pattern: VERB_ID_PATTERNS.runtimeControlId,
+                not: {
+                    enum: [
+                        'model',
+                        'workspace',
+                        'executionMode',
+                        'permissionMode',
+                        'effort',
+                        'interrupt',
+                        'runtimeControlValues',
+                        'updatedAt',
+                        'updatedBy',
+                    ],
+                },
+            },
+            additionalProperties: sessionConfigValueDef,
+        },
+    },
 };
 const timeoutFields = (maxMs, ceilingNote) => ({
     timeoutMs: {
@@ -265,7 +342,7 @@ const timeoutFields = (maxMs, ceilingNote) => ({
         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 '
+            + '(input interactions also require input subtype kind): bindings must fill defaults '
             + 'and convert timeoutMs into expiresAt before calling the endpoint.',
     },
 });
@@ -308,7 +385,7 @@ const send_to_input = {
         },
         sessionSelection: REF('sessionSelection'),
         sessionConfig: {
-            type: ['object', 'null'],
+            oneOf: [REF('sessionConfig'), { type: 'null' }],
             description: 'Coding-agent session setup (model/permissionMode/effort/workspaceId/executionMode); '
                 + 'only applied to agent targets, stripped for humans.',
         },
@@ -539,7 +616,7 @@ const check_approval_input = {
 };
 const check_approval_result = {
     description: "'unknown' is NOT a denial — only 'resolved' carries a decision. Canonical statuses map "
-        + 'from the /runtime-approval/consume wire as: allow/deny -> resolved.decision, timeout -> '
+        + 'from the approval interaction consume result as: allow/deny -> resolved.decision, timeout -> '
         + 'expired, pending -> pending, HTTP 404 RUNTIME_APPROVAL_NOT_FOUND -> unknown.',
     oneOf: [
         {
@@ -1000,7 +1077,8 @@ export const CANON_VERBS_JSON_SCHEMA = {
         unifiedDiff: unifiedDiffDef,
         sessionRule: sessionRuleDef,
         runtimeCard: runtimeCardDef,
-        native: nativeDef,
+        native: VERB_NATIVE_METADATA_JSON_SCHEMA,
+        sessionConfig: VERB_SESSION_CONFIG_JSON_SCHEMA,
         send_to_input,
         send_to_result,
         request_input_input,

package/dist/verbWire.d.ts

@@ -25,7 +25,7 @@
  * cards, prompts, questions, tool names/summaries, details, diffs, and
  * self-contexts are body.
  */
-import { type CanonVerbName, type VerbSessionSelection } from './verbContract.js';
+import { type CanonVerbName, type VerbNativeMetadata, type VerbSessionConfig, type VerbSessionSelection } from './verbContract.js';
 export declare const CANON_VERB_WIRE_SCHEMA_VERSION = "canon.verb-wire.v1";
 export declare const CANON_VERB_WIRE_SCHEMA_ID = "https://canonmsg.com/schemas/canon.verb-wire.v1.json";
 export type VerbWireBody = {
@@ -53,8 +53,9 @@ export interface VerbWireTurn {
  * Documented leak decisions (see e2ee-mls.md §10): `mentions` stays
  * plaintext for routing + mention-piercing pushes (D3); `contactUserId` on
  * share_contact reveals who was shared (explicitly accepted for v1);
- * `sessionConfig` may carry workspace ids — borderline, revisit with the
- * session-state encryption decision.
+ * `sessionConfig` carries only typed runtime option ids; `native` carries only
+ * typed correlation ids. Paths, labels, prompts, summaries, and other free
+ * text belong in the body or owner-local runtime state.
  */
 export interface CanonVerbWireEnvelope {
     conversationId?: string;
@@ -74,7 +75,7 @@ export interface CanonVerbWireEnvelope {
     risk?: 'low' | 'normal' | 'high' | 'destructive';
     category?: 'command' | 'file' | 'network' | 'browser' | 'mcp' | 'plugin' | 'canon' | 'tool';
     sessionSelection?: VerbSessionSelection;
-    sessionConfig?: Record<string, unknown> | null;
+    sessionConfig?: VerbSessionConfig | null;
     idempotencyKey?: string;
     /** Target-message reference for react/forward — routing, not content. */
     messageId?: string;
@@ -84,7 +85,7 @@ export interface CanonVerbWireEnvelope {
     /** Group-membership routing ids (create_group) — distinct from mentions. */
     memberIds?: string[];
     turn?: VerbWireTurn;
-    native?: Record<string, unknown>;
+    native?: VerbNativeMetadata;
     runtimeId?: string;
     limit?: number;
 }
@@ -268,7 +269,53 @@ export declare const CANON_VERB_WIRE_JSON_SCHEMA: {
                     }];
                 };
                 readonly sessionConfig: {
-                    readonly type: readonly ["object", "null"];
+                    readonly oneOf: readonly [{
+                        readonly type: "object";
+                        readonly description: string;
+                        readonly additionalProperties: false;
+                        readonly properties: {
+                            readonly model: {
+                                readonly type: "string";
+                                readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                                readonly maxLength: 256;
+                            };
+                            readonly permissionMode: {
+                                readonly type: "string";
+                                readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                                readonly maxLength: 256;
+                            };
+                            readonly effort: {
+                                readonly type: "string";
+                                readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                                readonly maxLength: 256;
+                            };
+                            readonly workspaceId: {
+                                readonly type: "string";
+                                readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                                readonly maxLength: 256;
+                            };
+                            readonly executionMode: {
+                                readonly enum: readonly ["worktree", "locked"];
+                            };
+                            readonly runtimeControlValues: {
+                                readonly type: "object";
+                                readonly maxProperties: 24;
+                                readonly propertyNames: {
+                                    readonly pattern: "^[A-Za-z0-9_-]{1,80}$";
+                                    readonly not: {
+                                        readonly enum: readonly ["model", "workspace", "executionMode", "permissionMode", "effort", "interrupt", "runtimeControlValues", "updatedAt", "updatedBy"];
+                                    };
+                                };
+                                readonly additionalProperties: {
+                                    readonly type: "string";
+                                    readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+                                    readonly maxLength: 256;
+                                };
+                            };
+                        };
+                    }, {
+                        readonly type: "null";
+                    }];
                 };
                 readonly idempotencyKey: {
                     readonly type: "string";
@@ -307,6 +354,98 @@ export declare const CANON_VERB_WIRE_JSON_SCHEMA: {
                 };
                 readonly native: {
                     readonly type: "object";
+                    readonly description: string;
+                    readonly maxProperties: 24;
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly runtime: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly method: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly requestId: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly provider: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly origin: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly surface: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly threadId: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly turnId: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly runId: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly itemId: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly toolCallId: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly approvalId: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly pluginId: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly sessionKey: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly nodeId: {
+                            readonly type: "string";
+                            readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                            readonly maxLength: 256;
+                        };
+                        readonly handles: {
+                            readonly type: "object";
+                            readonly maxProperties: 16;
+                            readonly propertyNames: {
+                                readonly pattern: "^[A-Za-z0-9_.:-]{1,80}$";
+                            };
+                            readonly additionalProperties: {
+                                readonly type: "string";
+                                readonly pattern: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+                                readonly maxLength: 256;
+                            };
+                        };
+                    };
                 };
                 readonly runtimeId: {
                     readonly type: "string";

package/dist/verbWire.js

@@ -26,6 +26,7 @@
  * self-contexts are body.
  */
 import { CANON_VERB_NAMES, VERB_ID_PATTERNS, VERB_LIMITS, } from './verbContract.js';
+import { VERB_NATIVE_METADATA_JSON_SCHEMA, VERB_SESSION_CONFIG_JSON_SCHEMA, } from './verbSchemas.js';
 export const CANON_VERB_WIRE_SCHEMA_VERSION = 'canon.verb-wire.v1';
 export const CANON_VERB_WIRE_SCHEMA_ID = 'https://canonmsg.com/schemas/canon.verb-wire.v1.json';
 // ---------------------------------------------------------------------------
@@ -198,7 +199,9 @@ const wireEnvelopeDef = {
                 },
             ],
         },
-        sessionConfig: { type: ['object', 'null'] },
+        sessionConfig: {
+            oneOf: [VERB_SESSION_CONFIG_JSON_SCHEMA, { type: 'null' }],
+        },
         idempotencyKey: {
             type: 'string',
             pattern: VERB_ID_PATTERNS.runtimeId,
@@ -221,7 +224,7 @@ const wireEnvelopeDef = {
                 + 'overload the mention slot.',
         },
         turn: { $ref: '#/$defs/turn' },
-        native: { type: 'object' },
+        native: VERB_NATIVE_METADATA_JSON_SCHEMA,
         runtimeId: { type: 'string', maxLength: VERB_LIMITS.turnIdChars },
         limit: { type: 'integer', minimum: 1 },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/backend-contracts",
-  "version": "2.2.0",
+  "version": "3.0.0",
   "description": "Canon backend contract helpers shared by Functions and stream-service",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@canonmsg/rich-cards": "^0.8.1",
+    "@canonmsg/rich-cards": "^0.8.4",
     "@types/node": "^22.0.0",
     "ajv": "^8.20.0",
     "typescript": "~5.7.0",