@canonmsg/core 0.15.1 → 0.15.3

package/dist/agent-session.js

@@ -14,7 +14,7 @@ function descriptorOptions(runtime, controlId) {
 function descriptorDefaultValue(runtime, controlId) {
     const control = listDescriptorControls(runtime)
         .find((candidate) => candidate.id === controlId);
-    return control?.defaultValue ?? control?.options?.[0]?.value ?? undefined;
+    return control?.defaultValue ?? undefined;
 }
 function buildWorkSessionSummary(workSession, workSessions) {
     const merged = mergeWorkSessionContexts(workSession, workSessions);
@@ -30,6 +30,70 @@ function buildWorkSessionSummary(workSession, workSessions) {
         status: primary.status ?? null,
     };
 }
+function setControlState(controlState, id, value, source, appliedAt) {
+    if (value === undefined)
+        return;
+    controlState[id] = {
+        value,
+        source,
+        ...(source === 'applied' && appliedAt ? { appliedAt } : {}),
+    };
+}
+function buildControlState(input) {
+    const controlState = {};
+    const appliedAt = input.sessionState?.updatedAt ?? input.lastHeartbeatAt ?? input.updatedAt ?? undefined;
+    const modelDefault = descriptorDefaultValue(input.runtime, 'model');
+    if (input.sessionState?.model !== undefined) {
+        setControlState(controlState, 'model', input.sessionState.model, 'applied', appliedAt);
+    }
+    else if (input.sessionConfig?.model !== undefined) {
+        setControlState(controlState, 'model', input.sessionConfig.model, 'requested');
+    }
+    else if (modelDefault !== undefined) {
+        setControlState(controlState, 'model', modelDefault, 'host-default');
+    }
+    const permissionDefault = descriptorDefaultValue(input.runtime, 'permissionMode');
+    if (input.sessionState?.permissionMode !== undefined) {
+        setControlState(controlState, 'permissionMode', input.sessionState.permissionMode, 'applied', appliedAt);
+    }
+    else if (input.sessionConfig?.permissionMode !== undefined) {
+        setControlState(controlState, 'permissionMode', input.sessionConfig.permissionMode, 'requested');
+    }
+    else if (permissionDefault !== undefined) {
+        setControlState(controlState, 'permissionMode', permissionDefault, 'host-default');
+    }
+    const effortDefault = descriptorDefaultValue(input.runtime, 'effort');
+    if (input.sessionState?.effort !== undefined) {
+        setControlState(controlState, 'effort', input.sessionState.effort, 'applied', appliedAt);
+    }
+    else if (input.sessionConfig?.effort !== undefined) {
+        setControlState(controlState, 'effort', input.sessionConfig.effort, 'requested');
+    }
+    else if (effortDefault !== undefined) {
+        setControlState(controlState, 'effort', effortDefault, 'host-default');
+    }
+    const workspaceDefault = descriptorDefaultValue(input.runtime, 'workspace');
+    if (input.sessionConfig?.workspaceId !== undefined) {
+        setControlState(controlState, 'workspace', input.sessionConfig.workspaceId, 'requested');
+    }
+    else if (workspaceDefault !== undefined) {
+        setControlState(controlState, 'workspace', workspaceDefault, 'host-default');
+    }
+    if (input.sessionState?.executionMode !== undefined) {
+        setControlState(controlState, 'executionMode', input.sessionState.executionMode, 'applied', appliedAt);
+    }
+    else if (input.sessionConfig?.executionMode !== undefined) {
+        setControlState(controlState, 'executionMode', input.sessionConfig.executionMode, 'requested');
+    }
+    for (const [id, value] of Object.entries(input.sessionConfig?.runtimeControlValues ?? {})) {
+        setControlState(controlState, id, value, 'requested');
+    }
+    for (const [id, value] of Object.entries(input.sessionState?.runtimeControlValues ?? {})) {
+        setControlState(controlState, id, value, 'applied', appliedAt);
+    }
+    Object.assign(controlState, input.sessionState?.controlState ?? {});
+    return Object.keys(controlState).length > 0 ? controlState : undefined;
+}
 export function buildAgentSessionSnapshot(input) {
     const modelOptions = input.sessionState?.availableModels?.length
         ? input.sessionState.availableModels
@@ -39,6 +103,22 @@ export function buildAgentSessionSnapshot(input) {
     const availableExecutionModes = descriptorOptions(input.runtime, 'executionMode')
         .map((option) => option.value)
         .filter((value) => value === 'worktree' || value === 'locked');
+    const model = input.sessionState?.model
+        ?? input.sessionConfig?.model
+        ?? descriptorDefaultValue(input.runtime, 'model');
+    const permissionMode = input.sessionState?.permissionMode
+        ?? input.sessionConfig?.permissionMode
+        ?? descriptorDefaultValue(input.runtime, 'permissionMode');
+    const effort = input.sessionState?.effort
+        ?? input.sessionConfig?.effort
+        ?? descriptorDefaultValue(input.runtime, 'effort');
+    const runtimeControlValues = input.sessionState?.runtimeControlValues
+        ?? input.sessionConfig?.runtimeControlValues;
+    const workspaceId = input.sessionConfig?.workspaceId
+        ?? descriptorDefaultValue(input.runtime, 'workspace');
+    const executionMode = input.sessionState?.executionMode
+        ?? input.sessionConfig?.executionMode;
+    const controlState = buildControlState(input);
     return {
         conversationId: input.conversationId,
         agentId: input.agentId,
@@ -48,23 +128,17 @@ export function buildAgentSessionSnapshot(input) {
         hostMode: Boolean(input.sessionState?.hostMode
             ?? input.sessionConfig?.hostMode
             ?? input.runtime?.hostMode),
-        model: input.sessionState?.model
-            ?? input.sessionConfig?.model
-            ?? descriptorDefaultValue(input.runtime, 'model'),
+        model,
         modelOptions,
-        permissionMode: input.sessionState?.permissionMode
-            ?? input.sessionConfig?.permissionMode
-            ?? descriptorDefaultValue(input.runtime, 'permissionMode'),
+        permissionMode,
         permissionModeOptions: descriptorOptions(input.runtime, 'permissionMode'),
-        effort: input.sessionState?.effort ?? input.sessionConfig?.effort,
-        runtimeControlValues: input.sessionState?.runtimeControlValues
-            ?? input.sessionConfig?.runtimeControlValues,
+        effort,
+        runtimeControlValues,
+        controlState,
         runtimeControlErrors: input.sessionState?.runtimeControlErrors ?? undefined,
-        workspaceId: input.sessionConfig?.workspaceId
-            ?? descriptorDefaultValue(input.runtime, 'workspace'),
+        workspaceId,
         workspaceOptions,
-        executionMode: input.sessionState?.executionMode
-            ?? input.sessionConfig?.executionMode,
+        executionMode,
         availableExecutionModes,
         executionBranch: input.sessionState?.executionBranch,
         resolvedWorkspaceLabel: undefined,

package/dist/browser.d.ts

@@ -1,7 +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 type { AddMemberResult, AgentCapabilities, AgentClientType, AgentSessionSnapshot, AgentSessionWorkSessionSummary, 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, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, RuntimeControlError, ResolvedAdmission, SessionConfig, TurnUpdatedPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, AgentSessionSnapshot, AgentSessionWorkSessionSummary, 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, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, ResolvedAdmission, SessionConfig, TurnUpdatedPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
 export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, } from './execution-environment-mode.js';
 export type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
 export type { CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, UpdateWorkSessionConversationOptions, WorkSessionPromptRenderOptions, } from './work-session.js';

package/dist/host-runtime.js

@@ -82,7 +82,7 @@ function describeContactCard(card) {
             ? 'reject pending requests'
             : null,
     ].filter(Boolean).join(', ');
-    const hint = `This host can inspect the card, but Canon admission actions are missing here. Missing capabilities: ${missingCapabilities}. Use another Canon surface for userId ${card.userId}.`;
+    const hint = `This host can inspect the card, but this wrapper does not expose callable Canon admission actions yet. Missing capabilities here: ${missingCapabilities}. Use an SDK/OpenClaw reach-out surface or another Canon client for userId ${card.userId}.`;
     return `${identity}\n${hint}`;
 }
 function describeAttachment(attachment, materialized) {
@@ -183,6 +183,7 @@ export async function publishHostSessionSnapshots(input) {
             permissionMode: snapshot.permissionMode ?? null,
             effort: snapshot.effort ?? null,
             runtimeControlValues: snapshot.runtimeControlValues ?? null,
+            controlState: snapshot.controlState ?? null,
             workspaceId: snapshot.workspaceId ?? null,
             executionMode: snapshot.executionMode ?? null,
             executionBranch,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
-export type { AddMemberResult, AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonResolveAdmissionResult, ContactAddedPayload, ContactApprovedPayload, ContactCardPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonMessage, CanonConversation, CanonMessagesPage, CreateContactRequestResult, AgentContext, CanonStreamEvent, AgentSessionSnapshot, AgentSessionWorkSessionSummary, 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, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, RuntimeControlError, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonResolveAdmissionResult, ContactAddedPayload, ContactApprovedPayload, ContactCardPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonMessage, CanonConversation, CanonMessagesPage, CreateContactRequestResult, AgentContext, CanonStreamEvent, AgentSessionSnapshot, AgentSessionWorkSessionSummary, 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, CanonRuntimeDetailTier, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, RuntimeControlError, RuntimeControlState, RuntimeControlValueSource, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
 export type { CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CreateWorkSessionOptions, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, SendLinkedMessageOptions, SendLinkedMessageResult, UpdateWorkSessionConversationOptions, WorkSessionPromptRenderOptions, } from './work-session.js';
 export { buildWorkSessionPromptLines, buildWorkSessionsPromptLines, mergeWorkSessionContexts, } from './work-session.js';
 export { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, buildWorkspaceRootId, discoverWorkspaceProjects, } from './workspace-discovery.js';
@@ -37,6 +37,8 @@ export type { HostInboundParticipantContext, } from './host-runtime.js';
 export { createRuntimeStatePublisher, } from './runtime-state-publisher.js';
 export type { RuntimeStatePublisher, RuntimeStatePublisherOptions, RuntimeStreamingPayload, } from './runtime-state-publisher.js';
 export { formatCanonMessageAsText } from './message-format.js';
+export { reachOutToCanonContact } from './reach-out.js';
+export type { CanonReachOutClient, CanonReachOutOptions, CanonReachOutResult, } from './reach-out.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
 export { resolveCanonBaseUrl } from './base-url.js';
 export { handleCliMetadataRequest, isDirectExecution, readCliPackageVersion, runCli, } from './cli-metadata.js';

package/dist/index.js

@@ -35,6 +35,8 @@ export { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMe
 export { createRuntimeStatePublisher, } from './runtime-state-publisher.js';
 // Message formatting (LLM-facing text projection)
 export { formatCanonMessageAsText } from './message-format.js';
+// Admission-aware reach-out helpers for runtime clients
+export { reachOutToCanonContact } from './reach-out.js';
 // Constants
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
 // Base URL resolver

package/dist/message-format.js

@@ -10,11 +10,12 @@
  * regression in every consumer plugin.
  */
 export function formatCanonMessageAsText(message) {
+    const trimmedText = typeof message.text === 'string' ? message.text.trim() : '';
     if (message.contentType === 'contact_card' && message.contactCard) {
-        return formatContactCard(message.contactCard);
+        const cardText = formatContactCard(message.contactCard);
+        return trimmedText ? `${cardText}\n${trimmedText}` : cardText;
     }
     const attachment = pickPrimaryAttachment(message.attachments);
-    const trimmedText = typeof message.text === 'string' ? message.text.trim() : '';
     if (attachment?.kind === 'image') {
         return trimmedText ? `[image] ${trimmedText}` : '[image]';
     }

package/dist/reach-out.d.ts

@@ -0,0 +1,37 @@
+import type { CanonResolveAdmissionResult, CreateContactRequestResult, CreateConversationOptions, SendMessageOptions } from './types.js';
+export interface CanonReachOutClient {
+    resolveAdmission(targetUserId: string): Promise<CanonResolveAdmissionResult>;
+    createConversation(options: CreateConversationOptions): Promise<{
+        conversationId: string;
+    }>;
+    sendMessage(conversationId: string, text: string, options?: SendMessageOptions): Promise<{
+        messageId: string;
+    }>;
+    createContactRequest(targetUserId: string, message?: string | null): Promise<CreateContactRequestResult>;
+}
+export interface CanonReachOutOptions {
+    targetUserId: string;
+    text?: string | null;
+    requestMessage?: string | null;
+    sendMessageOptions?: SendMessageOptions;
+}
+export type CanonReachOutResult = {
+    status: 'messaged';
+    conversationId: string;
+    messageId?: string;
+} | {
+    status: 'requested';
+    requestId: string | null;
+} | {
+    status: 'pending';
+    requestId: string | null;
+} | {
+    status: 'blocked' | 'unavailable';
+    reason: string;
+};
+/**
+ * Admission-aware direct reach-out for runtime clients. It deliberately keeps
+ * backend conversation creation fail-closed; callers choose this helper when
+ * their product behavior is "message if reachable, otherwise request access."
+ */
+export declare function reachOutToCanonContact(client: CanonReachOutClient, options: CanonReachOutOptions): Promise<CanonReachOutResult>;

package/dist/reach-out.js

@@ -0,0 +1,73 @@
+const CONTACT_REQUEST_MESSAGE_LIMIT = 500;
+function normalizeOptionalText(value) {
+    const trimmed = typeof value === 'string' ? value.trim() : '';
+    return trimmed.length > 0 ? trimmed : null;
+}
+function normalizeContactRequestMessage(requestMessage, fallbackText) {
+    const text = normalizeOptionalText(requestMessage) ?? normalizeOptionalText(fallbackText);
+    if (!text)
+        return null;
+    if (text.length <= CONTACT_REQUEST_MESSAGE_LIMIT)
+        return text;
+    return `${text.slice(0, CONTACT_REQUEST_MESSAGE_LIMIT - 3)}...`;
+}
+function isConnectionRequiredError(error) {
+    const status = error && typeof error === 'object' && 'status' in error
+        ? Number(error.status)
+        : null;
+    const message = error instanceof Error ? error.message : String(error ?? '');
+    return status === 403 && /CONNECTION_REQUIRED|connection required/i.test(message);
+}
+async function openConversationAndMaybeMessage(client, options) {
+    const { conversationId } = await client.createConversation({
+        type: 'direct',
+        targetUserId: options.targetUserId,
+    });
+    const text = normalizeOptionalText(options.text);
+    if (text) {
+        const { messageId } = options.sendMessageOptions
+            ? await client.sendMessage(conversationId, text, options.sendMessageOptions)
+            : await client.sendMessage(conversationId, text);
+        return { status: 'messaged', conversationId, messageId };
+    }
+    return { status: 'messaged', conversationId };
+}
+async function requestContact(client, options) {
+    const result = await client.createContactRequest(options.targetUserId, normalizeContactRequestMessage(options.requestMessage, options.text));
+    if (result.status === 'open') {
+        return openConversationAndMaybeMessage(client, { ...options, requestMessage: null });
+    }
+    if (result.status === 'duplicate') {
+        return { status: 'pending', requestId: result.requestId };
+    }
+    return { status: 'requested', requestId: result.requestId };
+}
+/**
+ * Admission-aware direct reach-out for runtime clients. It deliberately keeps
+ * backend conversation creation fail-closed; callers choose this helper when
+ * their product behavior is "message if reachable, otherwise request access."
+ */
+export async function reachOutToCanonContact(client, options) {
+    const { admission } = await client.resolveAdmission(options.targetUserId);
+    if (admission.state === 'allowed' && admission.canMessage) {
+        try {
+            return await openConversationAndMaybeMessage(client, options);
+        }
+        catch (error) {
+            if (isConnectionRequiredError(error)) {
+                return requestContact(client, options);
+            }
+            throw error;
+        }
+    }
+    if (admission.state === 'pending-outbound') {
+        return { status: 'pending', requestId: admission.pendingRequestId ?? null };
+    }
+    if (admission.state === 'request-required' && admission.canRequestContact) {
+        return requestContact(client, options);
+    }
+    if (admission.state === 'blocked') {
+        return { status: 'blocked', reason: 'blocked' };
+    }
+    return { status: 'unavailable', reason: admission.state };
+}

package/dist/rtdb-rest.d.ts

@@ -7,13 +7,14 @@
  */
 import type { CanonClient } from './client.js';
 import type { DeliveryIntent, RuntimeCapabilities, TurnLifecycleState } from './turn-protocol.js';
-import type { CanonControlValue, ModelOption, RuntimeControlError, RuntimeInfoPayload } from './types.js';
+import type { CanonControlValue, ModelOption, RuntimeControlError, RuntimeControlState, RuntimeInfoPayload } from './types.js';
 export interface SessionStatePayload {
     lastError?: string;
     model?: string;
     permissionMode?: string;
     effort?: string;
     runtimeControlValues?: Record<string, CanonControlValue>;
+    controlState?: Record<string, RuntimeControlState>;
     runtimeControlErrors?: Record<string, RuntimeControlError> | null;
     cwd?: string;
     executionMode?: 'worktree' | 'locked';
@@ -63,6 +64,7 @@ export interface AgentSessionSnapshotPatch {
     }> | null;
     effort?: string | null;
     runtimeControlValues?: Record<string, CanonControlValue> | null;
+    controlState?: Record<string, RuntimeControlState> | null;
     runtimeControlErrors?: Record<string, RuntimeControlError> | null;
     workspaceId?: string | null;
     workspaceOptions?: Array<{

package/dist/rtdb-rest.js

@@ -144,6 +144,9 @@ function createRTDBClientHandle(client, options) {
             ...(state.runtimeControlValues !== undefined
                 ? { runtimeControlValues: state.runtimeControlValues }
                 : {}),
+            ...(state.controlState !== undefined
+                ? { controlState: state.controlState }
+                : {}),
             ...(state.runtimeControlErrors !== undefined
                 ? { runtimeControlErrors: state.runtimeControlErrors }
                 : {}),
@@ -173,6 +176,7 @@ function createRTDBClientHandle(client, options) {
                 state: null,
                 waitingForInput: false,
                 lastError: null,
+                controlState: null,
                 executionBranch: null,
                 contextUsage: null,
                 worktreePath: null,

package/dist/types.d.ts

@@ -21,9 +21,9 @@ export interface ForwardedFrom {
 /**
  * Server-serialized contact-card payload. Emitted on messages with
  * `contentType: 'contact_card'` so agents receive the referenced user's
- * identity alongside the card. Agents use the referenced `userId` with the
- * standard send-message path; if the target's inbound policy blocks cold
- * contact, they first send a contact request and retry after approval.
+ * identity alongside the card. Agents use the referenced `userId` with an
+ * admission-aware reach-out path; if the target's inbound policy blocks cold
+ * contact, they create a contact request and retry after approval.
  */
 export interface ContactCardPayload {
     userId: string;
@@ -212,11 +212,18 @@ export interface CanonWorkspaceRootMetadata {
     defaultRelativePath?: string | null;
 }
 export type CanonControlValue = string;
+export type RuntimeControlValueSource = 'applied' | 'requested' | 'host-default' | 'route-default' | 'unknown';
+export interface RuntimeControlState {
+    value: CanonControlValue | null;
+    source: RuntimeControlValueSource;
+    appliedAt?: number;
+}
 export type CanonControlAvailability = 'setup' | 'live' | 'setup_and_live';
 export type CanonControlLiveBehavior = 'immediate' | 'next_turn' | 'none';
 export type CanonControlSelectionPolicy = 'inherit' | 'required_explicit';
 export type CanonRuntimeStreamingMode = 'none' | 'status' | 'snapshot' | 'block' | 'delta';
 export type CanonRuntimeSurfaceMode = 'host' | 'channel' | 'limited_channel' | 'operator';
+export type CanonRuntimeDetailTier = 'primary' | 'detail' | 'diagnostic';
 export type CanonRuntimeInventoryStatus = 'ready' | 'auth_needed' | 'unknown' | 'configured' | 'running' | 'error';
 export type CanonRuntimeStatusTone = 'default' | 'success' | 'warning' | 'danger';
 export type CanonRuntimeActionAvailability = 'idle' | 'busy' | 'busy_with_queue' | 'waiting_input' | 'always';
@@ -301,6 +308,9 @@ export interface CanonRuntimeStatusItem {
     label: string;
     value: string;
     tone?: CanonRuntimeStatusTone;
+    tier?: CanonRuntimeDetailTier;
+    sensitive?: boolean;
+    source?: RuntimeControlValueSource;
 }
 export interface CanonRuntimeInventoryEntry {
     id: string;
@@ -312,6 +322,7 @@ export interface CanonRuntimeInventory {
     id: string;
     label: string;
     entries: ReadonlyArray<CanonRuntimeInventoryEntry>;
+    tier?: CanonRuntimeDetailTier;
 }
 export interface RuntimeInfoPayload {
     descriptor: CanonRuntimeDescriptor;
@@ -479,6 +490,7 @@ export interface SessionState {
     permissionMode?: string;
     effort?: string;
     runtimeControlValues?: Record<string, CanonControlValue>;
+    controlState?: Record<string, RuntimeControlState>;
     runtimeControlErrors?: Record<string, RuntimeControlError> | null;
     cwd?: string;
     executionMode?: 'worktree' | 'locked';
@@ -580,6 +592,7 @@ export interface AgentSessionSnapshot {
     permissionModeOptions?: PermissionModeOption[];
     effort?: string;
     runtimeControlValues?: Record<string, CanonControlValue>;
+    controlState?: Record<string, RuntimeControlState>;
     runtimeControlErrors?: Record<string, RuntimeControlError> | null;
     runtimeDescriptor?: CanonRuntimeDescriptor | null;
     runtimeInfo?: RuntimeInfoPayload | null;

package/package.json

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