@canonmsg/backend-contracts 2.2.0 → 3.0.0

package/dist/cjs/verbSchemas.js

@@ -29,7 +29,7 @@
  *   endpoints validate against these schemas directly).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CANON_VERB_SCHEMA_REFS = exports.CANON_VERBS_JSON_SCHEMA = void 0;
+exports.CANON_VERB_SCHEMA_REFS = exports.CANON_VERBS_JSON_SCHEMA = exports.VERB_SESSION_CONFIG_JSON_SCHEMA = exports.VERB_NATIVE_METADATA_JSON_SCHEMA = void 0;
 exports.getVerbInputSchema = getVerbInputSchema;
 exports.getVerbResultSchema = getVerbResultSchema;
 const verbContract_js_1 = require("./verbContract.js");
@@ -252,12 +252,89 @@ const runtimeCardDef = {
         blocks: { type: 'array', minItems: 1, maxItems: verbContract_js_1.VERB_LIMITS.cardServerBlocks },
     },
 };
-const nativeDef = {
+const runtimeCorrelationValueDef = {
+    type: 'string',
+    pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeCorrelationValue,
+    maxLength: verbContract_js_1.VERB_LIMITS.nativeValueChars,
+};
+const runtimeMethodDef = {
+    type: 'string',
+    pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeMethod,
+    maxLength: verbContract_js_1.VERB_LIMITS.nativeValueChars,
+};
+exports.VERB_NATIVE_METADATA_JSON_SCHEMA = {
     type: 'object',
-    description: `Runtime correlation handles (<= ${verbContract_js_1.VERB_LIMITS.nativeKeys} keys, string values <= `
-        + `${verbContract_js_1.VERB_LIMITS.nativeValueChars} chars or a nested handles map <= ${verbContract_js_1.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: verbContract_js_1.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: verbContract_js_1.VERB_LIMITS.nativeHandles,
+            propertyNames: { pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeHandleKey },
+            additionalProperties: runtimeCorrelationValueDef,
+        },
+    },
+};
+const sessionConfigValueDef = {
+    type: 'string',
+    pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeOptionValue,
+    maxLength: verbContract_js_1.VERB_LIMITS.sessionConfigValueChars,
+};
+exports.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: verbContract_js_1.VERB_ID_PATTERNS.workspaceOptionId,
+            maxLength: verbContract_js_1.VERB_LIMITS.sessionConfigValueChars,
+        },
+        executionMode: { enum: ['worktree', 'locked'] },
+        runtimeControlValues: {
+            type: 'object',
+            maxProperties: verbContract_js_1.VERB_LIMITS.sessionConfigValues,
+            propertyNames: {
+                pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeControlId,
+                not: {
+                    enum: [
+                        'model',
+                        'workspace',
+                        'executionMode',
+                        'permissionMode',
+                        'effort',
+                        'interrupt',
+                        'runtimeControlValues',
+                        'updatedAt',
+                        'updatedBy',
+                    ],
+                },
+            },
+            additionalProperties: sessionConfigValueDef,
+        },
+    },
 };
 const timeoutFields = (maxMs, ceilingNote) => ({
     timeoutMs: {
@@ -270,7 +347,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.',
     },
 });
@@ -313,7 +390,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.',
         },
@@ -544,7 +621,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: [
         {
@@ -1005,7 +1082,8 @@ exports.CANON_VERBS_JSON_SCHEMA = {
         unifiedDiff: unifiedDiffDef,
         sessionRule: sessionRuleDef,
         runtimeCard: runtimeCardDef,
-        native: nativeDef,
+        native: exports.VERB_NATIVE_METADATA_JSON_SCHEMA,
+        sessionConfig: exports.VERB_SESSION_CONFIG_JSON_SCHEMA,
         send_to_input,
         send_to_result,
         request_input_input,

package/dist/cjs/verbWire.js

@@ -32,6 +32,7 @@ exports.projectVerbIntentToWire = projectVerbIntentToWire;
 exports.mergeVerbWireToIntent = mergeVerbWireToIntent;
 exports.findVerbWireEnvelopeViolations = findVerbWireEnvelopeViolations;
 const verbContract_js_1 = require("./verbContract.js");
+const verbSchemas_js_1 = require("./verbSchemas.js");
 exports.CANON_VERB_WIRE_SCHEMA_VERSION = 'canon.verb-wire.v1';
 exports.CANON_VERB_WIRE_SCHEMA_ID = 'https://canonmsg.com/schemas/canon.verb-wire.v1.json';
 // ---------------------------------------------------------------------------
@@ -204,7 +205,9 @@ const wireEnvelopeDef = {
                 },
             ],
         },
-        sessionConfig: { type: ['object', 'null'] },
+        sessionConfig: {
+            oneOf: [verbSchemas_js_1.VERB_SESSION_CONFIG_JSON_SCHEMA, { type: 'null' }],
+        },
         idempotencyKey: {
             type: 'string',
             pattern: verbContract_js_1.VERB_ID_PATTERNS.runtimeId,
@@ -227,7 +230,7 @@ const wireEnvelopeDef = {
                 + 'overload the mention slot.',
         },
         turn: { $ref: '#/$defs/turn' },
-        native: { type: 'object' },
+        native: verbSchemas_js_1.VERB_NATIVE_METADATA_JSON_SCHEMA,
         runtimeId: { type: 'string', maxLength: verbContract_js_1.VERB_LIMITS.turnIdChars },
         limit: { type: 'integer', minimum: 1 },
     },

package/dist/contactRequest.d.ts

@@ -10,6 +10,7 @@ export interface SerializedContactRequest {
     targetUserType: 'human' | 'ai_agent';
     targetOwnerId?: string | null;
     approverId: string;
+    /** Always null on agent-facing DTOs; free-form content stays in authorized review storage. */
     message: string | null;
     status: SerializedContactRequestStatus;
     kind: 'dm' | 'group_invite';

package/dist/contactRequest.js

@@ -71,7 +71,10 @@ export 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/environment.d.ts

@@ -0,0 +1,25 @@
+export declare const CANON_ENVIRONMENT_CONTRACTS: Readonly<{
+    readonly 'canon-dev-v1': Readonly<{
+        name: "dev";
+        projectId: "canonmail-dev";
+        region: "europe-west1";
+    }>;
+    readonly 'canon-prod-v1': Readonly<{
+        name: "prod";
+        projectId: "canonmail-prod";
+        region: "europe-west1";
+    }>;
+    readonly 'canon-legacy-v1': Readonly<{
+        name: "legacy";
+        projectId: "project-007a8e71-ba01-49e6-8aa";
+        region: "us-central1";
+    }>;
+}>;
+export type CanonEnvironmentId = keyof typeof CANON_ENVIRONMENT_CONTRACTS;
+export type CanonEnvironmentName = (typeof CANON_ENVIRONMENT_CONTRACTS)[CanonEnvironmentId]['name'];
+export type CanonEnvironmentContract = {
+    [EnvironmentId in CanonEnvironmentId]: {
+        environmentId: EnvironmentId;
+    } & (typeof CANON_ENVIRONMENT_CONTRACTS)[EnvironmentId];
+}[CanonEnvironmentId];
+export declare function getCanonEnvironmentContract(value: string): CanonEnvironmentContract;

package/dist/environment.js

@@ -0,0 +1,25 @@
+export const 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',
+    }),
+});
+export function getCanonEnvironmentContract(value) {
+    const environmentId = value.trim();
+    const contract = CANON_ENVIRONMENT_CONTRACTS[environmentId];
+    if (!contract) {
+        throw new Error(`Unsupported Canon environment ID: ${value}`);
+    }
+    return Object.freeze({ environmentId, ...contract });
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './diffRedaction.js';
+export * from './environment.js';
 export * from './media.js';
 export * from './message.js';
 export * from './runtimeCardFields.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './diffRedaction.js';
+export * from './environment.js';
 export * from './media.js';
 export * from './message.js';
 export * from './runtimeCardFields.js';

package/dist/verbContract.d.ts

@@ -67,6 +67,12 @@ export declare const VERB_ID_PATTERNS: {
     readonly actionId: "^[A-Za-z0-9_.:-]{1,80}$";
     readonly questionId: "^[A-Za-z0-9_.:-]{1,120}$";
     readonly sessionRuleToolPattern: "^[\\w.*:-]{1,128}$";
+    readonly runtimeCorrelationValue: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+    readonly runtimeMethod: "^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$";
+    readonly runtimeOptionValue: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+    readonly workspaceOptionId: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+    readonly runtimeHandleKey: "^[A-Za-z0-9_.:-]{1,80}$";
+    readonly runtimeControlId: "^[A-Za-z0-9_-]{1,80}$";
 };
 /**
  * Server-enforced limits, single-sourced. Each value cites its enforcement
@@ -134,6 +140,9 @@ export declare const VERB_LIMITS: {
     readonly nativeKeys: 24;
     readonly nativeValueChars: 256;
     readonly nativeHandles: 16;
+    /** Initial agent-session setup carried by send_to. */
+    readonly sessionConfigValues: 24;
+    readonly sessionConfigValueChars: 256;
     /** Deadlines (functions/src/utils/runtimeRequestHelpers.ts). */
     readonly minTimeoutMs: 1000;
     /** input/card/plan ceiling (30 minutes). */
@@ -181,6 +190,50 @@ export type VerbSessionSelection = {
     mode: 'specific';
     conversationId: string;
 };
+/**
+ * Public setup policy for the target agent session. Every value is a stable
+ * runtime-advertised option id, never a label, prompt, path, or other free
+ * text. The server also validates each selection against the target's live
+ * descriptor before creating a session.
+ */
+export interface VerbSessionConfig {
+    model?: string;
+    permissionMode?: string;
+    effort?: string;
+    runtimeControlValues?: Record<string, string>;
+    workspaceId?: string;
+    executionMode?: 'worktree' | 'locked';
+}
+/**
+ * Bounded runtime correlation carried in the public wire envelope. These are
+ * opaque identifiers only; workspace paths, commands, prompts, summaries,
+ * and model labels belong in encrypted content or owner-local runtime state.
+ */
+export interface VerbNativeMetadata {
+    runtime?: string;
+    method?: string;
+    requestId?: string;
+    provider?: string;
+    origin?: string;
+    surface?: string;
+    threadId?: string;
+    turnId?: string;
+    runId?: string;
+    itemId?: string;
+    toolCallId?: string;
+    approvalId?: string;
+    pluginId?: string;
+    sessionKey?: string;
+    nodeId?: string;
+    handles?: Record<string, string>;
+}
+export declare const VERB_NATIVE_METADATA_KEYS: readonly ["runtime", "method", "requestId", "provider", "origin", "surface", "threadId", "turnId", "runId", "itemId", "toolCallId", "approvalId", "pluginId", "sessionKey", "nodeId", "handles"];
+/**
+ * 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.
+ */
+export declare function normalizeVerbNativeMetadata(value: unknown): VerbNativeMetadata | undefined;
 export interface VerbMediaAttachment {
     kind: 'image' | 'audio' | 'video' | 'file';
     /** Must come from /media/upload (Canon storage) or the GIF picker — server allowlisted. */
@@ -242,7 +295,7 @@ export interface SendToInput {
     /** Only meaningful for user targets that are agents. Default: continue_or_create. */
     sessionSelection?: VerbSessionSelection;
     /** Coding-agent session setup; only applied when the target is an agent. */
-    sessionConfig?: Record<string, unknown> | null;
+    sessionConfig?: VerbSessionConfig | null;
     messageOptions?: VerbMessageOptions;
 }
 export type SendToResult = {
@@ -308,7 +361,7 @@ export interface RequestInputInput {
     secretName?: string;
     sensitive?: boolean;
     responseUserId?: string;
-    native?: Record<string, unknown>;
+    native?: VerbNativeMetadata;
     turnId?: string;
     /** Relative deadline; server ceiling is VERB_LIMITS.maxTimeoutMs (30 min). */
     timeoutMs?: number;
@@ -376,7 +429,7 @@ export interface RequestApprovalInput {
     category?: VerbApprovalCategory;
     details?: VerbApprovalDetail[];
     diff?: VerbUnifiedDiff;
-    native?: Record<string, unknown>;
+    native?: VerbNativeMetadata;
     runtimeId?: string;
     turnId?: string;
     responseUserId?: string;
@@ -455,7 +508,7 @@ export interface SendCardInput {
     conversationId?: string;
     card: VerbRuntimeCard;
     cardId?: string;
-    native?: Record<string, unknown>;
+    native?: VerbNativeMetadata;
     runtimeId?: string;
     turnId?: string;
 }
@@ -719,6 +772,9 @@ export declare const CANON_VERB_LIMITS_ARTIFACT: {
         readonly nativeKeys: 24;
         readonly nativeValueChars: 256;
         readonly nativeHandles: 16;
+        /** Initial agent-session setup carried by send_to. */
+        readonly sessionConfigValues: 24;
+        readonly sessionConfigValueChars: 256;
         /** Deadlines (functions/src/utils/runtimeRequestHelpers.ts). */
         readonly minTimeoutMs: 1000;
         /** input/card/plan ceiling (30 minutes). */
@@ -746,6 +802,12 @@ export declare const CANON_VERB_LIMITS_ARTIFACT: {
         readonly actionId: "^[A-Za-z0-9_.:-]{1,80}$";
         readonly questionId: "^[A-Za-z0-9_.:-]{1,120}$";
         readonly sessionRuleToolPattern: "^[\\w.*:-]{1,128}$";
+        readonly runtimeCorrelationValue: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+        readonly runtimeMethod: "^[A-Za-z0-9_][A-Za-z0-9_./:\\-]{0,255}$";
+        readonly runtimeOptionValue: "^[A-Za-z0-9@_][A-Za-z0-9_.:/@+\\-]{0,255}$";
+        readonly workspaceOptionId: "^[A-Za-z0-9@_][A-Za-z0-9_.:@+\\-]{0,255}$";
+        readonly runtimeHandleKey: "^[A-Za-z0-9_.:-]{1,80}$";
+        readonly runtimeControlId: "^[A-Za-z0-9_-]{1,80}$";
     };
     readonly byteSemantics: {
         readonly 'send_to.text': "utf8_bytes<=messageTextBytes";

package/dist/verbContract.js

@@ -67,6 +67,12 @@ export const 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
@@ -134,6 +140,9 @@ export const 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). */
@@ -181,6 +190,65 @@ export const CANON_VERB_NAMES = [
     'list_contact_requests',
     'list_conversations',
 ];
+export const 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 = VERB_NATIVE_METADATA_KEYS.filter((key) => key !== 'handles');
+const RUNTIME_CORRELATION_VALUE_PATTERN = new RegExp(VERB_ID_PATTERNS.runtimeCorrelationValue);
+const RUNTIME_METHOD_PATTERN = new RegExp(VERB_ID_PATTERNS.runtimeMethod);
+const RUNTIME_HANDLE_KEY_PATTERN = new RegExp(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.
+ */
+export 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, 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