@canonmsg/core 0.18.1 → 0.19.0

package/dist/approval-format.d.ts

@@ -1,8 +1,15 @@
-import type { ApprovalRequestMetadata, ApprovalReplyMetadata, SessionRule } from './approval-types.js';
+import type { ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalNativeRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, SessionRule } from './approval-types.js';
 export declare function generateApprovalId(): string;
 export declare function redactSecrets(text: string, patterns: string[]): string;
 export declare function buildApprovalRequest(approvalId: string, toolName: string, toolInput: Record<string, unknown>, opts: {
     riskLevel?: 'normal' | 'destructive';
+    risk?: ApprovalRisk;
+    category?: ApprovalRequestCategory;
+    runtimeId?: string;
+    turnId?: string;
+    native?: ApprovalNativeRequestMetadata;
+    toolSummary?: string;
+    details?: ApprovalRequestDetail[];
     expiresAt: string;
     redactPatterns?: string[];
 }): {

package/dist/approval-format.js

@@ -27,22 +27,37 @@ export function redactSecrets(text, patterns) {
     }
     return result;
 }
+function redactApprovalDetails(details, patterns) {
+    if (!details?.length)
+        return undefined;
+    return details.slice(0, 8).map((detail) => ({
+        ...detail,
+        label: detail.label.slice(0, 80),
+        value: patterns?.length
+            ? redactSecrets(detail.value.slice(0, 500), patterns)
+            : detail.value.slice(0, 500),
+    }));
+}
 // ── Build approval request message ──────────────────────────────────
 export function buildApprovalRequest(approvalId, toolName, toolInput, opts) {
-    let summary = summarizeToolInput(toolName, toolInput);
+    let summary = opts.toolSummary ?? summarizeToolInput(toolName, toolInput);
     if (opts.redactPatterns?.length) {
         summary = redactSecrets(summary, opts.redactPatterns);
     }
+    summary = summary.slice(0, 1000);
+    const risk = opts.risk ?? opts.riskLevel ?? 'normal';
+    const riskLevel = risk === 'destructive' ? 'destructive' : (opts.riskLevel ?? 'normal');
+    const details = redactApprovalDetails(opts.details, opts.redactPatterns);
     const timeoutMin = Math.round((new Date(opts.expiresAt).getTime() - Date.now()) / 60_000);
     const lines = [
-        `Tool Approval Required [${approvalId}]`,
+        `Action Approval Required [${approvalId}]`,
         '',
         `Tool: ${toolName}`,
         summary,
         '',
     ];
-    if (opts.riskLevel === 'destructive') {
-        lines.push('This is a destructive operation');
+    if (risk === 'high' || risk === 'destructive') {
+        lines.push(risk === 'destructive' ? 'This is a destructive operation' : 'This is a high-risk operation');
         lines.push('');
     }
     lines.push(`Reply "approve" or "deny" (expires in ${timeoutMin}m)`);
@@ -51,7 +66,13 @@ export function buildApprovalRequest(approvalId, toolName, toolInput, opts) {
         approvalId,
         toolName,
         toolSummary: summary,
-        riskLevel: opts.riskLevel ?? 'normal',
+        ...(opts.category ? { category: opts.category } : {}),
+        risk,
+        riskLevel,
+        ...(opts.runtimeId ? { runtimeId: opts.runtimeId } : {}),
+        ...(opts.turnId ? { turnId: opts.turnId } : {}),
+        ...(opts.native ? { native: opts.native } : {}),
+        ...(details ? { details } : {}),
         expiresAt: opts.expiresAt,
     };
     return { text: lines.join('\n'), metadata };
@@ -77,7 +98,8 @@ export function buildApprovalOutcome(approvalId, toolName, toolSummary, decision
         return `Expired [${approvalId}] -- ${toolName}: ${short} (auto-denied)`;
     }
     if (reason === 'session-rule') {
-        return `Auto-approved (session rule) -- ${toolName}: ${short}`;
+        const label = decision === 'allow' ? 'Auto-approved' : 'Auto-denied';
+        return `${label} (session rule) -- ${toolName}: ${short}`;
     }
     return `${icon} [${approvalId}] -- ${toolName}: ${short}`;
 }

package/dist/approval-manager.d.ts

@@ -1,5 +1,5 @@
 import type { CanonClient } from './client.js';
-import type { ApprovalConfig, ApprovalResult, SessionRule } from './approval-types.js';
+import type { ApprovalConfig, ApprovalNativeRequestMetadata, ApprovalResult, ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRisk, SessionRule } from './approval-types.js';
 /**
  * Platform-agnostic approval protocol for Canon.
  *
@@ -27,6 +27,15 @@ export declare class ApprovalManager {
      */
     requestApproval(conversationId: string, toolName: string, toolInput: Record<string, unknown>, opts?: {
         riskLevel?: 'normal' | 'destructive';
+        risk?: ApprovalRisk;
+        category?: ApprovalRequestCategory;
+        runtimeId?: string;
+        turnId?: string;
+        native?: ApprovalNativeRequestMetadata;
+        toolSummary?: string;
+        details?: ApprovalRequestDetail[];
+        ignoreSessionRules?: boolean;
+        allowSessionRule?: boolean;
     }): Promise<ApprovalResult>;
     /**
      * Feed an inbound message to the approval manager.
@@ -38,7 +47,7 @@ export declare class ApprovalManager {
         metadata?: Record<string, unknown>;
     }): boolean;
     /** Check if a tool would be auto-resolved by a session rule */
-    checkSessionRules(toolName: string): SessionRule | null;
+    checkSessionRules(toolName: string, conversationId?: string): SessionRule | null;
     getSessionRules(): SessionRule[];
     clearSessionRules(): void;
     get pendingCount(): number;

package/dist/approval-manager.js

@@ -1,5 +1,5 @@
-import { DEFAULT_APPROVAL_CONFIG } from './approval-types.js';
-import { generateApprovalId, buildApprovalRequest, buildApprovalOutcome, parseTextApprovalReply, } from './approval-format.js';
+import { DEFAULT_APPROVAL_CONFIG, parseApprovalReplyMetadata } from './approval-types.js';
+import { generateApprovalId, buildApprovalRequest, buildApprovalOutcome, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
 // ── ApprovalManager ─────────────────────────────────────────────────
 /**
  * Platform-agnostic approval protocol for Canon.
@@ -34,11 +34,14 @@ export class ApprovalManager {
      */
     async requestApproval(conversationId, toolName, toolInput, opts) {
         // Check session rules first
-        const matchingRule = this.checkSessionRules(toolName);
+        const matchingRule = opts?.ignoreSessionRules ? null : this.checkSessionRules(toolName, conversationId);
         if (matchingRule) {
             const decision = matchingRule.type === 'deny-tool' ? 'deny' : 'allow';
             // Send silent log (fire-and-forget)
-            const summary = this.summarizeTool(toolName, toolInput);
+            const rawSummary = opts?.toolSummary ?? this.summarizeTool(toolName, toolInput);
+            const summary = this.config.redactPatterns.length
+                ? redactSecrets(rawSummary, this.config.redactPatterns)
+                : rawSummary;
             const logMsg = buildApprovalOutcome('', toolName, summary, decision, 'session-rule');
             this.client.sendMessage(conversationId, logMsg, {
                 metadata: { type: 'approval_outcome', decision, reason: 'session-rule' },
@@ -49,6 +52,13 @@ export class ApprovalManager {
         const expiresAt = new Date(Date.now() + this.config.timeoutSeconds * 1000).toISOString();
         const { text, metadata } = buildApprovalRequest(approvalId, toolName, toolInput, {
             riskLevel: opts?.riskLevel,
+            risk: opts?.risk,
+            category: opts?.category,
+            runtimeId: opts?.runtimeId,
+            turnId: opts?.turnId,
+            native: opts?.native,
+            toolSummary: opts?.toolSummary,
+            details: opts?.details,
             expiresAt,
             redactPatterns: this.config.redactPatterns,
         });
@@ -61,8 +71,7 @@ export class ApprovalManager {
         return new Promise((resolve) => {
             const timer = setTimeout(() => {
                 this.pending.delete(approvalId);
-                const summary = this.summarizeTool(toolName, toolInput);
-                const msg = buildApprovalOutcome(approvalId, toolName, summary, 'deny', 'timeout');
+                const msg = buildApprovalOutcome(approvalId, toolName, metadata.toolSummary, 'deny', 'timeout');
                 this.client.sendMessage(conversationId, msg, {
                     metadata: {
                         type: 'approval_outcome',
@@ -77,7 +86,8 @@ export class ApprovalManager {
                 approvalId,
                 conversationId,
                 toolName,
-                toolSummary: this.summarizeTool(toolName, toolInput),
+                toolSummary: metadata.toolSummary,
+                allowSessionRule: opts?.allowSessionRule !== false,
                 resolve,
                 timer,
             });
@@ -95,11 +105,10 @@ export class ApprovalManager {
             return false;
         // Try structured metadata first (from card UI)
         if (message.metadata?.type === 'approval_reply') {
-            const m = message.metadata;
-            const approvalId = m.approvalId;
-            const decision = m.decision;
-            const sessionRule = m.sessionRule;
-            return this.resolveApproval(approvalId, decision, sessionRule, conversationId);
+            const parsed = parseApprovalReplyMetadata(message.metadata);
+            if (!parsed)
+                return false;
+            return this.resolveApproval(parsed.approvalId, parsed.decision, parsed.sessionRule, conversationId);
         }
         // Fall back to text parsing
         if (message.text) {
@@ -119,23 +128,31 @@ export class ApprovalManager {
         return false;
     }
     /** Check if a tool would be auto-resolved by a session rule */
-    checkSessionRules(toolName) {
+    checkSessionRules(toolName, conversationId) {
         this.pruneExpiredRules();
-        for (const rule of this.rules) {
+        for (const stored of this.rules) {
+            if (conversationId && stored.conversationId !== conversationId)
+                continue;
+            const { rule } = stored;
             if (rule.type === 'approve-all')
                 return rule;
             if ((rule.type === 'approve-tool' || rule.type === 'deny-tool') &&
                 rule.toolPattern) {
-                const re = new RegExp(`^${rule.toolPattern}$`, 'i');
-                if (re.test(toolName))
-                    return rule;
+                try {
+                    const re = new RegExp(`^${rule.toolPattern}$`, 'i');
+                    if (re.test(toolName))
+                        return rule;
+                }
+                catch {
+                    continue;
+                }
             }
         }
         return null;
     }
     getSessionRules() {
         this.pruneExpiredRules();
-        return [...this.rules];
+        return this.rules.map((stored) => stored.rule);
     }
     clearSessionRules() {
         this.rules = [];
@@ -160,11 +177,18 @@ export class ApprovalManager {
             }
             return false;
         }
+        if (entry.conversationId !== conversationId) {
+            return false;
+        }
         clearTimeout(entry.timer);
         this.pending.delete(approvalId);
-        // Store session rule if provided
-        if (sessionRule) {
-            this.rules.push(sessionRule);
+        const acceptedSessionRule = entry.allowSessionRule ? sessionRule : undefined;
+        // Store session rule if provided and allowed for this request
+        if (acceptedSessionRule) {
+            this.rules.push({
+                conversationId: entry.conversationId,
+                rule: acceptedSessionRule,
+            });
         }
         // Send confirmation (fire-and-forget)
         const msg = buildApprovalOutcome(approvalId, entry.toolName, entry.toolSummary, decision, 'replied');
@@ -177,15 +201,15 @@ export class ApprovalManager {
             },
         }).catch(() => { });
         // If session rule was set, log that too
-        if (sessionRule) {
-            const ruleDesc = this.describeRule(sessionRule);
+        if (acceptedSessionRule) {
+            const ruleDesc = this.describeRule(acceptedSessionRule);
             this.client
                 .sendMessage(conversationId, `Session rule set: ${ruleDesc}`, {
                 metadata: { type: 'approval_outcome', decision, reason: 'session-rule' },
             })
                 .catch(() => { });
         }
-        entry.resolve({ decision, sessionRule });
+        entry.resolve({ decision, ...(acceptedSessionRule ? { sessionRule: acceptedSessionRule } : {}) });
         return true;
     }
     findMostRecentPending(conversationId) {
@@ -199,10 +223,10 @@ export class ApprovalManager {
     }
     pruneExpiredRules() {
         const now = Date.now();
-        this.rules = this.rules.filter((r) => {
-            if (!r.expiresAt)
+        this.rules = this.rules.filter(({ rule }) => {
+            if (!rule.expiresAt)
                 return true;
-            return new Date(r.expiresAt).getTime() > now;
+            return new Date(rule.expiresAt).getTime() > now;
         });
     }
     summarizeTool(toolName, toolInput) {

package/dist/approval-types.d.ts

@@ -4,7 +4,17 @@ export interface ApprovalRequestMetadata {
     toolName: string;
     /** Pre-computed, redacted summary — raw toolInput is never stored */
     toolSummary: string;
+    /** Broad action family for richer Canon approval cards. */
+    category?: ApprovalRequestCategory;
+    /** Preferred v2 risk signal. `riskLevel` remains for older clients. */
+    risk?: ApprovalRisk;
     riskLevel?: 'normal' | 'destructive';
+    runtimeId?: string;
+    turnId?: string;
+    /** Native runtime correlation handle. Canon stores this opaquely for plugins/SDK bridges. */
+    native?: ApprovalNativeRequestMetadata;
+    /** Redacted, normalized details. Raw tool input must not be stored here. */
+    details?: ApprovalRequestDetail[];
     expiresAt: string;
 }
 export interface ApprovalOutcomeMetadata {
@@ -19,6 +29,33 @@ export interface ApprovalReplyMetadata {
     decision: 'allow' | 'deny';
     sessionRule?: SessionRule;
 }
+export type ApprovalRequestCategory = 'command' | 'file' | 'network' | 'browser' | 'mcp' | 'plugin' | 'canon' | 'tool';
+export type ApprovalRisk = 'low' | 'normal' | 'high' | 'destructive';
+export interface ApprovalRequestDetail {
+    label: string;
+    value: string;
+    monospace?: boolean;
+}
+export interface ApprovalNativeRequestMetadata {
+    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;
+    cwd?: string;
+    model?: string;
+    nodeId?: string;
+    handles?: Record<string, string>;
+}
 export interface SessionRule {
     type: 'approve-all' | 'approve-tool' | 'deny-tool';
     /** Tool name pattern (regex) — only for approve-tool/deny-tool */
@@ -37,3 +74,6 @@ export interface ApprovalConfig {
     redactPatterns: string[];
 }
 export declare const DEFAULT_APPROVAL_CONFIG: ApprovalConfig;
+export declare function parseSessionRule(value: unknown): SessionRule | null;
+export declare function parseApprovalReplyMetadata(value: unknown): ApprovalReplyMetadata | null;
+export declare function parseApprovalRequestMetadata(value: unknown): ApprovalRequestMetadata | null;

package/dist/approval-types.js

@@ -7,3 +7,192 @@ export const DEFAULT_APPROVAL_CONFIG = {
         '(?:api[_-]?key|token|secret|password)\\s*[:=]\\s*\\S+',
     ],
 };
+function isRecord(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function normalizeString(value, maxLength) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.length > maxLength)
+        return null;
+    return trimmed;
+}
+function normalizeCategory(value) {
+    return value === 'command'
+        || value === 'file'
+        || value === 'network'
+        || value === 'browser'
+        || value === 'mcp'
+        || value === 'plugin'
+        || value === 'canon'
+        || value === 'tool'
+        ? value
+        : undefined;
+}
+function normalizeRisk(value) {
+    return value === 'low'
+        || value === 'normal'
+        || value === 'high'
+        || value === 'destructive'
+        ? value
+        : undefined;
+}
+function normalizeDetails(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const details = value.slice(0, 8).flatMap((entry) => {
+        if (!isRecord(entry))
+            return [];
+        const label = normalizeString(entry.label, 80);
+        const detailValue = normalizeString(entry.value, 500);
+        if (!label || !detailValue)
+            return [];
+        return [{
+                label,
+                value: detailValue,
+                ...(entry.monospace === true ? { monospace: true } : {}),
+            }];
+    });
+    return details.length > 0 ? details : undefined;
+}
+function normalizeNativeRequest(value) {
+    if (!isRecord(value))
+        return undefined;
+    const native = {};
+    for (const key of [
+        'runtime',
+        'method',
+        'requestId',
+        'provider',
+        'origin',
+        'surface',
+        'threadId',
+        'turnId',
+        'runId',
+        'itemId',
+        'toolCallId',
+        'approvalId',
+        'pluginId',
+        'sessionKey',
+        'cwd',
+        'model',
+        'nodeId',
+    ]) {
+        const normalized = normalizeString(value[key], 256);
+        if (normalized)
+            native[key] = normalized;
+    }
+    const handles = isRecord(value.handles) ? value.handles : null;
+    if (handles) {
+        const normalizedHandles = {};
+        for (const [key, raw] of Object.entries(handles).slice(0, 16)) {
+            const normalizedKey = /^[a-zA-Z0-9_.:-]{1,80}$/.test(key) ? key : null;
+            const normalizedValue = normalizeString(raw, 256);
+            if (normalizedKey && normalizedValue) {
+                normalizedHandles[normalizedKey] = normalizedValue;
+            }
+        }
+        if (Object.keys(normalizedHandles).length > 0) {
+            native.handles = normalizedHandles;
+        }
+    }
+    return Object.keys(native).length > 0 ? native : undefined;
+}
+export function parseSessionRule(value) {
+    if (!isRecord(value))
+        return null;
+    const type = value.type;
+    if (type !== 'approve-all' && type !== 'approve-tool' && type !== 'deny-tool') {
+        return null;
+    }
+    let expiresAt;
+    if (value.expiresAt !== undefined) {
+        if (value.expiresAt === null) {
+            expiresAt = null;
+        }
+        else {
+            const normalizedExpiresAt = normalizeString(value.expiresAt, 128);
+            if (!normalizedExpiresAt)
+                return null;
+            const expiresMs = Date.parse(normalizedExpiresAt);
+            if (!Number.isFinite(expiresMs) || expiresMs <= Date.now())
+                return null;
+            expiresAt = new Date(expiresMs).toISOString();
+        }
+    }
+    if (type === 'approve-all') {
+        return {
+            type,
+            ...(expiresAt !== undefined ? { expiresAt } : {}),
+        };
+    }
+    const toolPattern = normalizeString(value.toolPattern, 128);
+    if (!toolPattern || !/^[\w.*:-]+$/.test(toolPattern)) {
+        return null;
+    }
+    return {
+        type,
+        toolPattern,
+        ...(expiresAt !== undefined ? { expiresAt } : {}),
+    };
+}
+export function parseApprovalReplyMetadata(value) {
+    if (!isRecord(value) || value.type !== 'approval_reply')
+        return null;
+    const approvalId = normalizeString(value.approvalId, 128);
+    if (!approvalId)
+        return null;
+    const decision = value.decision;
+    if (decision !== 'allow' && decision !== 'deny')
+        return null;
+    let sessionRule;
+    if (value.sessionRule !== undefined) {
+        const parsed = parseSessionRule(value.sessionRule);
+        if (!parsed)
+            return null;
+        sessionRule = parsed;
+    }
+    return {
+        type: 'approval_reply',
+        approvalId,
+        decision,
+        ...(sessionRule ? { sessionRule } : {}),
+    };
+}
+export function parseApprovalRequestMetadata(value) {
+    if (!isRecord(value) || value.type !== 'approval_request')
+        return null;
+    const approvalId = normalizeString(value.approvalId, 128);
+    const toolName = normalizeString(value.toolName, 128);
+    const toolSummary = normalizeString(value.toolSummary, 1000);
+    const expiresAt = normalizeString(value.expiresAt, 128);
+    if (!approvalId || !toolName || !toolSummary || !expiresAt)
+        return null;
+    const expiresMs = Date.parse(expiresAt);
+    if (!Number.isFinite(expiresMs))
+        return null;
+    const riskLevel = value.riskLevel === 'destructive' || value.riskLevel === 'normal'
+        ? value.riskLevel
+        : undefined;
+    const risk = normalizeRisk(value.risk) ?? (riskLevel === 'destructive' ? 'destructive' : undefined);
+    const category = normalizeCategory(value.category);
+    const runtimeId = normalizeString(value.runtimeId, 128) ?? undefined;
+    const turnId = normalizeString(value.turnId, 128) ?? undefined;
+    const native = normalizeNativeRequest(value.native);
+    const details = normalizeDetails(value.details);
+    return {
+        type: 'approval_request',
+        approvalId,
+        toolName,
+        toolSummary,
+        ...(category ? { category } : {}),
+        ...(risk ? { risk } : {}),
+        ...(riskLevel ? { riskLevel } : {}),
+        ...(runtimeId ? { runtimeId } : {}),
+        ...(turnId ? { turnId } : {}),
+        ...(native ? { native } : {}),
+        ...(details ? { details } : {}),
+        expiresAt: new Date(expiresMs).toISOString(),
+    };
+}

package/dist/browser.d.ts

@@ -1,7 +1,8 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
 export { resolveCanonBaseUrl } from './base-url.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
-export type { AddMemberResult, AgentCapabilities, AgentClientType, AgentSessionSnapshot, AgentRuntime, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonResolveAdmissionResult, ContactAddedPayload, ContactApprovedPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonStreamEvent, CreateContactRequestResult, MediaAttachment, MediaAttachmentKind, ModelOption, PermissionModeOption, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, ResolvedAdmission, SessionConfig, TurnUpdatedPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, AgentSessionSnapshot, AgentRuntime, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonResolveAdmissionResult, ContactAddedPayload, ContactApprovedPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonStreamEvent, CreateContactRequestResult, MediaAttachment, MediaAttachmentKind, ModelOption, PermissionModeOption, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimeProvenance, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, ResolvedAdmission, SessionConfig, TurnUpdatedPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export { buildRuntimeProvenance, resolveRuntimeProvenance, } from './provenance.js';
 export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, } from './execution-environment-mode.js';
 export type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
 export type { CanonSelfContext, CanonSelfContextType, SelfContextPromptRenderOptions, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, } from './self-context.js';
@@ -13,6 +14,7 @@ export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots,
 export { DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 export type { DeliveryIntent, InboundDisposition, RuntimeCapabilities, TriggerDecision, TurnLifecycleState, TurnMessageSemantics, TurnMetadata, TurnState, } from './turn-protocol.js';
 export { buildApprovalReply, buildApprovalRequest, buildApprovalOutcome, generateApprovalId, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
-export type { ApprovalRequestMetadata, ApprovalReplyMetadata, ApprovalOutcomeMetadata, SessionRule, ApprovalResult, ApprovalConfig, } from './approval-types.js';
+export type { ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalNativeRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, SessionRule, ApprovalResult, ApprovalConfig, } from './approval-types.js';
+export { DEFAULT_APPROVAL_CONFIG, parseApprovalRequestMetadata, parseApprovalReplyMetadata, parseSessionRule, } from './approval-types.js';
 export { buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, } from './runtime-cards.js';
 export type { ClaudeQuestionMetadata, ClaudeQuestionReplyMetadata, PlanApprovalMetadata, PlanApprovalReplyMetadata, RuntimeQuestionDefinition, RuntimeQuestionOption, } from './runtime-cards.js';

package/dist/browser.js

@@ -1,6 +1,7 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
 export { resolveCanonBaseUrl } from './base-url.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
+export { buildRuntimeProvenance, resolveRuntimeProvenance, } from './provenance.js';
 export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, } from './execution-environment-mode.js';
 export { buildSelfContextPromptLines, normalizeSelfContexts, } from './self-context.js';
 export { buildAgentSessionSnapshot } from './agent-session.js';
@@ -8,4 +9,5 @@ export { CLAUDE_EFFORT_OPTIONS, EXECUTION_MODE_CONTROL_OPTIONS, RUNTIME_NEW_SESS
 export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
 export { DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 export { buildApprovalReply, buildApprovalRequest, buildApprovalOutcome, generateApprovalId, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
+export { DEFAULT_APPROVAL_CONFIG, parseApprovalRequestMetadata, parseApprovalReplyMetadata, parseSessionRule, } from './approval-types.js';
 export { buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, } from './runtime-cards.js';

package/dist/host-runtime.d.ts

@@ -1,4 +1,4 @@
-import { type AgentClientType, type AgentRuntime, type CanonConversation, type CanonGroupContext, type CanonGroupContextMode, type CanonMembershipChange, type CanonMessage, type CanonMessagesPage, type MessageCreatedPayload } from './types.js';
+import { type AgentClientType, type AgentRuntime, type CanonConversation, type CanonGroupContext, type CanonGroupContextMode, type CanonMembershipChange, type CanonMessage, type CanonMessagesPage, type CanonRuntimeProvenance, type MessageCreatedPayload } from './types.js';
 import { type CanonClient } from './client.js';
 import { type SessionWorkspaceConfig } from './execution-environment.js';
 import { type ResolvedAgentBehaviorPolicy } from './policy.js';
@@ -86,10 +86,12 @@ export declare function resolveCanonReplyContext(input: {
 }): CanonReplyContext | null;
 export declare function buildHydratedInboundContext(input: {
     agentId: string;
+    conversationId: string;
     conversation: CanonConversation | null;
     page?: CanonMessagesPage | null;
     activeSelfContextId?: string | null;
     selfContexts?: MessageCreatedPayload['selfContexts'];
+    provenance?: MessageCreatedPayload['provenance'];
     message: HostInboundMessage;
     senderName: string;
     isOwner: boolean;
@@ -102,6 +104,7 @@ export declare function buildHydratedInboundContext(input: {
     behavior?: ResolvedAgentBehaviorPolicy | null;
     activeSelfContextId: string | null;
     selfContexts: NonNullable<MessageCreatedPayload['selfContexts']>;
+    provenance: CanonRuntimeProvenance;
     replyContext: CanonReplyContext | null;
     hydratedFromPage: boolean;
 };

package/dist/host-runtime.js

@@ -3,6 +3,7 @@ import { buildAgentSessionSnapshot } from './agent-session.js';
 import { buildConversationWorktreeSpec, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, } from './execution-environment.js';
 import { buildBehaviorPolicyLines, buildParticipationHistorySnapshot, } from './policy.js';
 import { buildSelfContextPromptLines, normalizeSelfContexts, resolveMessageActiveSelfContextId, selectActiveSelfContexts, } from './self-context.js';
+import { resolveRuntimeProvenance } from './provenance.js';
 import { rtdbRead } from './rtdb-rest.js';
 import { createRuntimeStatePublisher } from './runtime-state-publisher.js';
 const HOST_INBOUND_CONTACT_CARD_ACTION_CAPABILITIES = Object.freeze({
@@ -173,6 +174,21 @@ export function buildHydratedInboundContext(input) {
         ...(input.page?.selfContexts ?? []),
         ...(input.selfContexts ?? []),
     ], activeSelfContextId);
+    const resolvedActiveSelfContextId = activeSelfContexts.length > 0 ? activeSelfContextId : null;
+    const provenance = resolveRuntimeProvenance({
+        provenance: input.provenance,
+        conversationId: input.conversationId,
+        conversationType: input.conversation?.type ?? 'unknown',
+        memberCount: input.conversation?.memberIds?.length ?? null,
+        senderId: input.message.senderId ?? '',
+        senderName: input.senderName,
+        senderType: input.message.senderType ?? 'human',
+        isOwner: input.isOwner,
+        agentId: input.agentId,
+        mentions: input.message.mentions ?? [],
+        activeSelfContextId: resolvedActiveSelfContextId,
+        selfContexts: activeSelfContexts,
+    });
     const groupContext = buildCanonGroupContext({
         conversation: input.conversation,
         messages: [
@@ -201,8 +217,9 @@ export function buildHydratedInboundContext(input) {
             currentAgentStreakStartedByHuman: history.currentAgentStreakStartedByHuman,
         },
         behavior: input.page?.behavior ?? input.conversation?.behavior,
-        activeSelfContextId: activeSelfContexts.length > 0 ? activeSelfContextId : null,
+        activeSelfContextId: resolvedActiveSelfContextId,
         selfContexts: activeSelfContexts,
+        provenance,
         replyContext: resolveCanonReplyContext({
             message: input.message,
             messages: input.page?.messages ?? [],

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
-export type { AddMemberResult, AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonGroupContext, CanonGroupContextMode, CanonKnownRecentParticipant, CanonMembershipChange, CanonResolveAdmissionResult, ConversationUpdatedPayload, ContactAddedPayload, ContactApprovedPayload, ContactCardPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonMessage, CanonConversation, CanonMessagesPage, CreateContactRequestResult, AgentContext, CanonStreamEvent, AgentSessionSnapshot, ResolvedAdmission, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonGroupContext, CanonGroupContextMode, CanonKnownRecentParticipant, CanonMembershipChange, CanonResolveAdmissionResult, ConversationUpdatedPayload, ContactAddedPayload, ContactApprovedPayload, ContactCardPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonMessage, CanonRuntimeProvenance, CanonConversation, CanonMessagesPage, CreateContactRequestResult, AgentContext, CanonStreamEvent, AgentSessionSnapshot, ResolvedAdmission, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeCommandArgumentChoice, CanonRuntimeCommandArgumentDescriptor, CanonRuntimeCommandArgumentKind, CanonRuntimeCommandDescriptor, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimeActivityItem, CanonRuntimeActivityKind, CanonRuntimeActivityStatus, CanonRuntimeFact, CanonRuntimeFactGroup, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimePrimitiveId, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export { buildRuntimeProvenance, resolveRuntimeProvenance, } from './provenance.js';
 export type { CanonSelfContext, CanonSelfContextType, SelfContextPromptRenderOptions, SendContextualMessageOptions, SendContextualMessageResult, SendContextualSelfContextInput, } from './self-context.js';
 export { buildSelfContextPromptLines, normalizeSelfContexts, resolveMessageActiveSelfContextId, selectActiveSelfContexts, } from './self-context.js';
 export { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, buildWorkspaceRootId, discoverWorkspaceProjects, } from './workspace-discovery.js';
@@ -16,8 +17,8 @@ export type { DeliveryIntent, TurnMessageSemantics, InboundDisposition, TurnLife
 export { ackRegistrationApproval, registerAndWaitForApproval, submitRegistrationRequest, waitForRegistrationApproval, } from './registration.js';
 export { ApprovalManager } from './approval-manager.js';
 export { generateApprovalId, buildApprovalRequest, buildApprovalReply, buildApprovalOutcome, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
-export { DEFAULT_APPROVAL_CONFIG, } from './approval-types.js';
-export type { ApprovalRequestMetadata, ApprovalReplyMetadata, ApprovalOutcomeMetadata, SessionRule, ApprovalResult, ApprovalConfig, } from './approval-types.js';
+export { DEFAULT_APPROVAL_CONFIG, parseApprovalRequestMetadata, parseApprovalReplyMetadata, parseSessionRule, } from './approval-types.js';
+export type { ApprovalRequestCategory, ApprovalRequestDetail, ApprovalRequestMetadata, ApprovalNativeRequestMetadata, ApprovalRisk, ApprovalReplyMetadata, ApprovalOutcomeMetadata, SessionRule, ApprovalResult, ApprovalConfig, } from './approval-types.js';
 export { buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, } from './runtime-cards.js';
 export type { ClaudeQuestionMetadata, ClaudeQuestionReplyMetadata, PlanApprovalMetadata, PlanApprovalReplyMetadata, RuntimeQuestionDefinition, RuntimeQuestionOption, } from './runtime-cards.js';
 export { createStreamingHelper } from './streaming.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 // Types
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
+export { buildRuntimeProvenance, resolveRuntimeProvenance, } from './provenance.js';
 export { buildSelfContextPromptLines, normalizeSelfContexts, resolveMessageActiveSelfContextId, selectActiveSelfContexts, } from './self-context.js';
 export { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, buildWorkspaceRootId, discoverWorkspaceProjects, } from './workspace-discovery.js';
 // Client
@@ -16,7 +17,7 @@ export { ackRegistrationApproval, registerAndWaitForApproval, submitRegistration
 // Approval
 export { ApprovalManager } from './approval-manager.js';
 export { generateApprovalId, buildApprovalRequest, buildApprovalReply, buildApprovalOutcome, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
-export { DEFAULT_APPROVAL_CONFIG, } from './approval-types.js';
+export { DEFAULT_APPROVAL_CONFIG, parseApprovalRequestMetadata, parseApprovalReplyMetadata, parseSessionRule, } from './approval-types.js';
 export { buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, buildQuestionRequest, } from './runtime-cards.js';
 // Streaming (RTDB helpers)
 export { createStreamingHelper } from './streaming.js';

package/dist/provenance.d.ts

@@ -0,0 +1,31 @@
+import type { CanonConversation, CanonMessage, CanonRuntimeProvenance } from './types.js';
+import type { CanonSelfContext } from './self-context.js';
+export declare function buildRuntimeProvenance(input: {
+    conversationId: string;
+    conversationType?: CanonConversation['type'] | 'unknown' | string | null;
+    memberCount?: number | null;
+    senderId: string;
+    senderName?: string | null;
+    senderType?: CanonMessage['senderType'] | string | null;
+    isOwner?: boolean | null;
+    agentId?: string | null;
+    mentions?: readonly string[] | null;
+    mentionedAgent?: boolean | null;
+    activeSelfContextId?: string | null;
+    selfContexts?: readonly CanonSelfContext[] | null;
+}): CanonRuntimeProvenance;
+export declare function resolveRuntimeProvenance(input: {
+    provenance?: CanonRuntimeProvenance | null;
+    conversationId: string;
+    conversationType?: CanonConversation['type'] | 'unknown' | string | null;
+    memberCount?: number | null;
+    senderId: string;
+    senderName?: string | null;
+    senderType?: CanonMessage['senderType'] | string | null;
+    isOwner?: boolean | null;
+    agentId?: string | null;
+    mentions?: readonly string[] | null;
+    mentionedAgent?: boolean | null;
+    activeSelfContextId?: string | null;
+    selfContexts?: readonly CanonSelfContext[] | null;
+}): CanonRuntimeProvenance;

package/dist/provenance.js

@@ -0,0 +1,71 @@
+function normalizeConversationType(value) {
+    return value === 'direct' || value === 'group' ? value : 'unknown';
+}
+function normalizeSenderType(value) {
+    return value === 'ai_agent' ? 'ai_agent' : 'human';
+}
+function normalizeMemberCount(value) {
+    if (value == null)
+        return value;
+    return Number.isFinite(value) && value >= 0 ? Math.floor(value) : null;
+}
+function normalizeName(value) {
+    if (typeof value !== 'string')
+        return value == null ? value : undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed : null;
+}
+function findSelfContextType(selfContexts, activeSelfContextId) {
+    if (!activeSelfContextId)
+        return null;
+    return selfContexts?.find((entry) => entry.id === activeSelfContextId)?.type ?? null;
+}
+export function buildRuntimeProvenance(input) {
+    const activeSelfContextId = typeof input.activeSelfContextId === 'string' && input.activeSelfContextId.trim()
+        ? input.activeSelfContextId.trim()
+        : null;
+    const mentionedAgent = typeof input.mentionedAgent === 'boolean'
+        ? input.mentionedAgent
+        : Boolean(input.agentId && input.mentions?.includes(input.agentId));
+    return {
+        conversation: {
+            id: input.conversationId,
+            type: normalizeConversationType(input.conversationType),
+            ...(input.memberCount !== undefined
+                ? { memberCount: normalizeMemberCount(input.memberCount) }
+                : {}),
+        },
+        sender: {
+            id: input.senderId,
+            ...(input.senderName !== undefined ? { name: normalizeName(input.senderName) } : {}),
+            type: normalizeSenderType(input.senderType),
+            isOwner: input.isOwner === true,
+        },
+        mentionedAgent,
+        activeSelfContext: activeSelfContextId
+            ? {
+                id: activeSelfContextId,
+                type: findSelfContextType(input.selfContexts, activeSelfContextId),
+            }
+            : null,
+    };
+}
+export function resolveRuntimeProvenance(input) {
+    if (!input.provenance) {
+        return buildRuntimeProvenance(input);
+    }
+    return buildRuntimeProvenance({
+        conversationId: input.provenance.conversation?.id || input.conversationId,
+        conversationType: input.provenance.conversation?.type ?? input.conversationType,
+        memberCount: input.provenance.conversation?.memberCount ?? input.memberCount,
+        senderId: input.provenance.sender?.id || input.senderId,
+        senderName: input.provenance.sender?.name ?? input.senderName,
+        senderType: input.provenance.sender?.type ?? input.senderType,
+        isOwner: input.provenance.sender?.isOwner ?? input.isOwner,
+        agentId: input.agentId,
+        mentions: input.mentions,
+        mentionedAgent: input.provenance.mentionedAgent ?? input.mentionedAgent,
+        activeSelfContextId: input.provenance.activeSelfContext?.id ?? input.activeSelfContextId,
+        selfContexts: input.selfContexts,
+    });
+}

package/dist/types.d.ts

@@ -81,6 +81,24 @@ export interface CanonMessagesPage {
     activeSelfContextIdByMessageId?: Record<string, string>;
     selfContexts?: CanonSelfContext[];
 }
+export interface CanonRuntimeProvenance {
+    conversation: {
+        id: string;
+        type: CanonConversation['type'] | 'unknown';
+        memberCount?: number | null;
+    };
+    sender: {
+        id: string;
+        name?: string | null;
+        type: CanonMessage['senderType'];
+        isOwner: boolean;
+    };
+    mentionedAgent: boolean;
+    activeSelfContext?: {
+        id: string;
+        type?: CanonSelfContext['type'] | string | null;
+    } | null;
+}
 export type CanonContactRequestStatus = 'pending' | 'approved' | 'rejected' | 'expired';
 export interface CanonContactRequest {
     id: string;
@@ -88,6 +106,10 @@ export interface CanonContactRequest {
     requesterName: string;
     requesterAvatarUrl: string | null;
     targetId: string;
+    targetName?: string | null;
+    targetAvatarUrl?: string | null;
+    targetUserType?: 'human' | 'ai_agent' | null;
+    targetOwnerId?: string | null;
     approverId: string;
     message: string | null;
     status: CanonContactRequestStatus;
@@ -415,6 +437,7 @@ export interface MessageCreatedPayload {
     behavior?: ResolvedAgentBehaviorPolicy;
     activeSelfContextId?: string | null;
     selfContexts?: CanonSelfContext[];
+    provenance?: CanonRuntimeProvenance;
     message: {
         id: string;
         senderId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/core",
-  "version": "0.18.1",
+  "version": "0.19.0",
   "description": "Canon core — shared types, REST client, SSE stream, and registration for Canon messaging",
   "type": "module",
   "main": "dist/index.js",