@canonmsg/core 0.7.5 → 0.10.0

package/dist/agent-session.js

@@ -39,6 +39,9 @@ export function buildAgentSessionSnapshot(input) {
             ?? input.sessionConfig?.permissionMode
             ?? input.runtime?.defaultPermissionMode,
         permissionModeOptions: input.runtime?.availablePermissionModes ?? [],
+        effort: input.sessionState?.effort ?? input.sessionConfig?.effort,
+        runtimeControlValues: input.sessionState?.runtimeControlValues
+            ?? input.sessionConfig?.runtimeControlValues,
         workspaceId: input.sessionConfig?.workspaceId
             ?? input.runtime?.defaultWorkspaceId
             ?? workspaceOptions[0]?.id,
@@ -49,8 +52,13 @@ export function buildAgentSessionSnapshot(input) {
             ?? input.runtime?.availableExecutionModes
             ?? [],
         executionBranch: input.sessionState?.executionBranch,
+        resolvedWorkspaceLabel: undefined,
+        resolvedCwd: input.sessionState?.cwd,
+        worktreePath: input.sessionState?.worktreePath,
+        executionFallbackReason: input.sessionState?.executionFallbackReason,
         state: input.sessionState?.state,
         turnState: input.turnState?.state,
+        supportsQueue: input.turnState?.capabilities?.supportsQueue,
         queueDepth: input.turnState?.queueDepth ?? 0,
         waitingForInput: input.turnState?.state === 'waiting_input'
             || input.sessionState?.state === 'requires_action',

package/dist/approval-manager.js

@@ -41,7 +41,7 @@ export class ApprovalManager {
             const summary = this.summarizeTool(toolName, toolInput);
             const logMsg = buildApprovalOutcome('', toolName, summary, decision, 'session-rule');
             this.client.sendMessage(conversationId, logMsg, {
-                metadata: { type: 'approval_outcome' },
+                metadata: { type: 'approval_outcome', decision, reason: 'session-rule' },
             }).catch(() => { });
             return { decision };
         }
@@ -64,7 +64,12 @@ export class ApprovalManager {
                 const summary = this.summarizeTool(toolName, toolInput);
                 const msg = buildApprovalOutcome(approvalId, toolName, summary, 'deny', 'timeout');
                 this.client.sendMessage(conversationId, msg, {
-                    metadata: { type: 'approval_outcome' },
+                    metadata: {
+                        type: 'approval_outcome',
+                        approvalId,
+                        decision: 'deny',
+                        reason: 'timeout',
+                    },
                 }).catch(() => { });
                 resolve({ decision: 'deny' });
             }, this.config.timeoutSeconds * 1000);
@@ -164,14 +169,19 @@ export class ApprovalManager {
         // Send confirmation (fire-and-forget)
         const msg = buildApprovalOutcome(approvalId, entry.toolName, entry.toolSummary, decision, 'replied');
         this.client.sendMessage(conversationId, msg, {
-            metadata: { type: 'approval_outcome' },
+            metadata: {
+                type: 'approval_outcome',
+                approvalId,
+                decision,
+                reason: 'replied',
+            },
         }).catch(() => { });
         // If session rule was set, log that too
         if (sessionRule) {
             const ruleDesc = this.describeRule(sessionRule);
             this.client
                 .sendMessage(conversationId, `Session rule set: ${ruleDesc}`, {
-                metadata: { type: 'approval_outcome' },
+                metadata: { type: 'approval_outcome', decision, reason: 'session-rule' },
             })
                 .catch(() => { });
         }

package/dist/approval-types.d.ts

@@ -7,6 +7,12 @@ export interface ApprovalRequestMetadata {
     riskLevel?: 'normal' | 'destructive';
     expiresAt: string;
 }
+export interface ApprovalOutcomeMetadata {
+    type: 'approval_outcome';
+    approvalId?: string;
+    decision?: 'allow' | 'deny';
+    reason?: 'replied' | 'timeout' | 'session-rule';
+}
 export interface ApprovalReplyMetadata {
     type: 'approval_reply';
     approvalId: string;

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 { AgentCapabilities, AgentClientType, AgentSessionSnapshot, AgentSessionWorkSessionSummary, AgentRuntime, CanonContactRequest, CanonContactRequestStatus, ContactApprovedPayload, ContactRequestPayload, CanonStreamEvent, CreateContactRequestResult, MediaAttachment, MediaAttachmentKind, ModelOption, PermissionModeOption, RuntimeUpdatedPayload, ResolvedAdmission, SessionConfig, TurnUpdatedPayload, WorkspaceOption, } from './types.js';
+export type { AgentCapabilities, AgentClientType, AgentSessionSnapshot, AgentSessionWorkSessionSummary, AgentRuntime, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContactRequest, CanonContactRequestStatus, ContactApprovedPayload, ContactRequestPayload, CanonStreamEvent, CreateContactRequestResult, MediaAttachment, MediaAttachmentKind, ModelOption, PermissionModeOption, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, 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';
@@ -12,6 +12,6 @@ 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, SessionRule, ApprovalResult, ApprovalConfig, } from './approval-types.js';
+export type { ApprovalRequestMetadata, 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';

package/dist/execution-environment.d.ts

@@ -1,4 +1,4 @@
-import type { WorkspaceOption } from './types.js';
+import type { WorkspaceOption, WorkspaceOptionSource } from './types.js';
 import { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, type ExecutionEnvironmentMode } from './execution-environment-mode.js';
 export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode };
 export type { ExecutionEnvironmentMode };
@@ -22,6 +22,10 @@ interface WorkspaceResolverOption {
 }
 export interface ConfiguredWorkspaceOption extends WorkspaceResolverOption {
     label: string;
+    description?: string;
+    workspaceRootId?: string;
+    workspaceRelativePath?: string;
+    source?: WorkspaceOptionSource;
 }
 export interface SessionWorkspaceConfig {
     workspaceId?: string;
@@ -34,7 +38,7 @@ export declare function isEnabledFlag(value: unknown): boolean;
 export declare function buildConversationEnvironmentKey(conversationId: string, workspaceCwd: string): string;
 export declare function buildWorkspaceOptionId(workspaceCwd: string): string;
 export declare function buildConfiguredWorkspaceOptions(primaryCwd: string, configured: string[]): ConfiguredWorkspaceOption[];
-export declare function buildPublicWorkspaceOptions(workspaceOptions: Array<Pick<ConfiguredWorkspaceOption, 'id' | 'label'>>): WorkspaceOption[];
+export declare function buildPublicWorkspaceOptions(workspaceOptions: Array<Pick<ConfiguredWorkspaceOption, 'id' | 'label'> & Partial<Pick<ConfiguredWorkspaceOption, 'description' | 'workspaceRootId' | 'workspaceRelativePath' | 'source'>>>): WorkspaceOption[];
 export declare function readSessionWorkspaceConfig(raw: unknown): SessionWorkspaceConfig | null;
 export declare function resolveConfiguredWorkspaceCwd(input: {
     workspaceOptions: WorkspaceResolverOption[];

package/dist/execution-environment.js

@@ -93,7 +93,7 @@ export function buildWorkspaceOptionId(workspaceCwd) {
 export function buildConfiguredWorkspaceOptions(primaryCwd, configured) {
     const uniqueDirs = Array.from(new Set([primaryCwd, ...configured].map((dir) => resolve(dir))));
     const seenLabels = new Map();
-    return uniqueDirs.map((cwd) => {
+    return uniqueDirs.map((cwd, index) => {
         const baseLabel = basename(cwd) || cwd;
         const seenCount = (seenLabels.get(baseLabel) ?? 0) + 1;
         seenLabels.set(baseLabel, seenCount);
@@ -101,11 +101,19 @@ export function buildConfiguredWorkspaceOptions(primaryCwd, configured) {
             id: buildWorkspaceOptionId(cwd),
             label: seenCount === 1 ? baseLabel : `${baseLabel} (${seenCount})`,
             cwd,
+            source: index === 0 ? 'default' : 'explicit',
         };
     });
 }
 export function buildPublicWorkspaceOptions(workspaceOptions) {
-    return workspaceOptions.map(({ id, label }) => ({ id, label }));
+    return workspaceOptions.map((workspace) => ({
+        id: workspace.id,
+        label: workspace.label,
+        ...(workspace.description ? { description: workspace.description } : {}),
+        ...(workspace.workspaceRootId ? { workspaceRootId: workspace.workspaceRootId } : {}),
+        ...(workspace.workspaceRelativePath ? { workspaceRelativePath: workspace.workspaceRelativePath } : {}),
+        ...(workspace.source ? { source: workspace.source } : {}),
+    }));
 }
 function isRetiredWorkspaceId(value) {
     if (!value)

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
-export type { AgentCapabilities, AgentClientType, CanonContactRequest, CanonContactRequestStatus, ContactApprovedPayload, ContactRequestPayload, 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, ModelOption, PermissionModeOption, WorkspaceOption, } from './types.js';
+export type { AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContactRequest, CanonContactRequestStatus, ContactApprovedPayload, ContactRequestPayload, 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, 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';
+export type { ConfiguredWorkspaceRoot, WorkspaceDiscoveryResult, } from './workspace-discovery.js';
 export { CanonClient, CanonApiError } from './client.js';
 export { buildAgentSessionSnapshot } from './agent-session.js';
 export { CanonStream } from './stream.js';
@@ -14,7 +16,7 @@ export { registerAndWaitForApproval } 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, SessionRule, ApprovalResult, ApprovalConfig, } from './approval-types.js';
+export type { ApprovalRequestMetadata, 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';
@@ -25,7 +27,7 @@ export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agen
 export type { ResolvedAgent } from './agent-resolver.js';
 export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildConversationWorktreeSpec, buildPublicWorkspaceOptions, buildWorkspaceOptionId, EXECUTION_ENVIRONMENT_MODES, isEnabledFlag, isExecutionEnvironmentMode, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, ExecutionEnvironmentError, prepareConversationEnvironment, releaseConversationEnvironment, } from './execution-environment.js';
 export type { ConfiguredWorkspaceOption, ExecutionEnvironmentMode, PreparedExecutionEnvironment, SessionWorkspaceConfig, } from './execution-environment.js';
-export { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
-export type { AgentSessionSnapshotPatch, SessionStatePayload, TurnStatePayload, } from './rtdb-rest.js';
+export { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, patchRuntimeInfo, writeRuntimeInfo, clearRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
+export type { AgentSessionSnapshotPatch, RuntimeInfoPayloadData, SessionStatePayload, TurnStatePayload, } from './rtdb-rest.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
 export { resolveCanonBaseUrl } from './base-url.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 // Types
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
 export { buildWorkSessionPromptLines, buildWorkSessionsPromptLines, mergeWorkSessionContexts, } from './work-session.js';
+export { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, buildWorkspaceRootId, discoverWorkspaceProjects, } from './workspace-discovery.js';
 // Client
 export { CanonClient, CanonApiError } from './client.js';
 export { buildAgentSessionSnapshot } from './agent-session.js';
@@ -25,7 +26,7 @@ export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agen
 // Execution environments for host-mode coding sessions
 export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildConversationWorktreeSpec, buildPublicWorkspaceOptions, buildWorkspaceOptionId, EXECUTION_ENVIRONMENT_MODES, isEnabledFlag, isExecutionEnvironmentMode, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, ExecutionEnvironmentError, prepareConversationEnvironment, releaseConversationEnvironment, } from './execution-environment.js';
 // RTDB REST helpers (token exchange, session state, generic read/write)
-export { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
+export { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, patchRuntimeInfo, writeRuntimeInfo, clearRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
 // Constants
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
 // Base URL resolver

package/dist/rtdb-rest.d.ts

@@ -7,14 +7,18 @@
  */
 import type { CanonClient } from './client.js';
 import type { DeliveryIntent, RuntimeCapabilities, TurnLifecycleState } from './turn-protocol.js';
+import type { CanonControlValue, RuntimeInfoPayload } from './types.js';
 export interface SessionStatePayload {
     lastError?: string;
     model?: string;
     permissionMode?: string;
     effort?: string;
+    runtimeControlValues?: Record<string, CanonControlValue>;
     cwd?: string;
     executionMode?: 'worktree' | 'locked';
     executionBranch?: string;
+    worktreePath?: string;
+    executionFallbackReason?: string;
     hostMode?: boolean;
     clientType?: string;
     isActive: boolean;
@@ -63,6 +67,8 @@ export interface AgentSessionSnapshotPatch {
         value: string;
         label: string;
     }> | null;
+    effort?: string | null;
+    runtimeControlValues?: Record<string, CanonControlValue> | null;
     workspaceId?: string | null;
     workspaceOptions?: Array<{
         id: string;
@@ -71,8 +77,12 @@ export interface AgentSessionSnapshotPatch {
     executionMode?: 'worktree' | 'locked' | null;
     availableExecutionModes?: Array<'worktree' | 'locked'> | null;
     executionBranch?: string | null;
+    resolvedCwd?: string | null;
+    worktreePath?: string | null;
+    executionFallbackReason?: string | null;
     state?: 'idle' | 'running' | 'requires_action' | null;
     turnState?: TurnLifecycleState | null;
+    supportsQueue?: boolean | null;
     queueDepth?: number;
     waitingForInput?: boolean;
     contextUsage?: {
@@ -95,6 +105,11 @@ export interface AgentSessionSnapshotPatch {
         '.sv': 'timestamp';
     };
 }
+export interface RuntimeInfoPayloadData extends Omit<RuntimeInfoPayload, 'updatedAt'> {
+    updatedAt: {
+        '.sv': 'timestamp';
+    };
+}
 interface RTDBAuthOptions {
     rtdbUrl?: string;
     firebaseApiKey?: string;
@@ -109,6 +124,9 @@ interface RTDBClientHandle {
     writeTurnState(conversationId: string, agentId: string, state: Omit<TurnStatePayload, 'updatedAt'>): Promise<void>;
     clearTurnState(conversationId: string, agentId: string): Promise<void>;
     patchAgentSessionSnapshot(conversationId: string, agentId: string, snapshot: Omit<AgentSessionSnapshotPatch, 'updatedAt'>): Promise<void>;
+    writeRuntimeInfo(conversationId: string, agentId: string, payload: Omit<RuntimeInfoPayload, 'updatedAt'>): Promise<void>;
+    patchRuntimeInfo(conversationId: string, agentId: string, payload: Partial<Omit<RuntimeInfoPayload, 'updatedAt'>>): Promise<void>;
+    clearRuntimeInfo(conversationId: string, agentId: string): Promise<void>;
 }
 /**
  * Initializes the default RTDB helper and returns a scoped client for callers
@@ -131,4 +149,7 @@ export declare function clearSessionState(conversationId: string, agentId: strin
 export declare function writeTurnState(conversationId: string, agentId: string, state: Omit<TurnStatePayload, 'updatedAt'>): Promise<void>;
 export declare function clearTurnState(conversationId: string, agentId: string): Promise<void>;
 export declare function patchAgentSessionSnapshot(conversationId: string, agentId: string, snapshot: Omit<AgentSessionSnapshotPatch, 'updatedAt'>): Promise<void>;
+export declare function writeRuntimeInfo(conversationId: string, agentId: string, payload: Omit<RuntimeInfoPayload, 'updatedAt'>): Promise<void>;
+export declare function patchRuntimeInfo(conversationId: string, agentId: string, payload: Partial<Omit<RuntimeInfoPayload, 'updatedAt'>>): Promise<void>;
+export declare function clearRuntimeInfo(conversationId: string, agentId: string): Promise<void>;
 export {};

package/dist/rtdb-rest.js

@@ -18,6 +18,9 @@ function normalizeRTDBPath(path) {
 function buildAgentSessionPath(conversationId, agentId) {
     return `/agent-session/${conversationId}/${agentId}`;
 }
+function buildRuntimeInfoPath(conversationId, agentId) {
+    return `/runtime-info/${conversationId}/${agentId}`;
+}
 function createRTDBClientHandle(client, options) {
     const rtdbBase = normalizeRTDBBase(options?.rtdbUrl || DEFAULT_RTDB_BASE);
     const firebaseApiKey = options?.firebaseApiKey || DEFAULT_FIREBASE_API_KEY;
@@ -137,9 +140,18 @@ function createRTDBClientHandle(client, options) {
             ...(typeof state.hostMode === 'boolean' ? { hostMode: state.hostMode } : {}),
             ...(state.model !== undefined ? { model: state.model } : {}),
             ...(state.permissionMode !== undefined ? { permissionMode: state.permissionMode } : {}),
+            ...(state.effort !== undefined ? { effort: state.effort } : {}),
+            ...(state.runtimeControlValues !== undefined
+                ? { runtimeControlValues: state.runtimeControlValues }
+                : {}),
             ...(state.availableModels !== undefined ? { modelOptions: state.availableModels } : {}),
+            ...(state.cwd !== undefined ? { resolvedCwd: state.cwd } : {}),
             ...(state.executionMode !== undefined ? { executionMode: state.executionMode } : {}),
             ...(state.executionBranch !== undefined ? { executionBranch: state.executionBranch } : {}),
+            ...(state.worktreePath !== undefined ? { worktreePath: state.worktreePath } : {}),
+            ...(state.executionFallbackReason !== undefined
+                ? { executionFallbackReason: state.executionFallbackReason }
+                : {}),
             ...(state.state !== undefined ? { state: state.state } : {}),
             waitingForInput: state.state === 'requires_action',
             ...(state.contextUsage !== undefined ? { contextUsage: state.contextUsage } : {}),
@@ -160,6 +172,8 @@ function createRTDBClientHandle(client, options) {
                 lastError: null,
                 executionBranch: null,
                 contextUsage: null,
+                worktreePath: null,
+                executionFallbackReason: null,
                 updatedAt: { '.sv': 'timestamp' },
             });
         }
@@ -174,6 +188,9 @@ function createRTDBClientHandle(client, options) {
         });
         await patch(buildAgentSessionPath(conversationId, agentId), {
             turnState: state.state,
+            ...(state.capabilities?.supportsQueue !== undefined
+                ? { supportsQueue: state.capabilities.supportsQueue }
+                : {}),
             queueDepth: state.queueDepth,
             waitingForInput: state.state === 'waiting_input',
             lastHeartbeatAt: { '.sv': 'timestamp' },
@@ -205,6 +222,21 @@ function createRTDBClientHandle(client, options) {
             updatedAt: { '.sv': 'timestamp' },
         });
     }
+    async function writeRuntimeInfoImpl(conversationId, agentId, payload) {
+        await write(buildRuntimeInfoPath(conversationId, agentId), {
+            ...payload,
+            updatedAt: { '.sv': 'timestamp' },
+        });
+    }
+    async function patchRuntimeInfoImpl(conversationId, agentId, payload) {
+        await patch(buildRuntimeInfoPath(conversationId, agentId), {
+            ...payload,
+            updatedAt: { '.sv': 'timestamp' },
+        });
+    }
+    async function clearRuntimeInfoImpl(conversationId, agentId) {
+        await remove(buildRuntimeInfoPath(conversationId, agentId));
+    }
     return {
         read,
         write,
@@ -215,6 +247,9 @@ function createRTDBClientHandle(client, options) {
         writeTurnState: writeTurnStateImpl,
         clearTurnState: clearTurnStateImpl,
         patchAgentSessionSnapshot: patchAgentSessionSnapshotImpl,
+        writeRuntimeInfo: writeRuntimeInfoImpl,
+        patchRuntimeInfo: patchRuntimeInfoImpl,
+        clearRuntimeInfo: clearRuntimeInfoImpl,
     };
 }
 /**
@@ -260,3 +295,12 @@ export async function clearTurnState(conversationId, agentId) {
 export async function patchAgentSessionSnapshot(conversationId, agentId, snapshot) {
     await getDefaultRTDBClient()?.patchAgentSessionSnapshot(conversationId, agentId, snapshot);
 }
+export async function writeRuntimeInfo(conversationId, agentId, payload) {
+    await getDefaultRTDBClient()?.writeRuntimeInfo(conversationId, agentId, payload);
+}
+export async function patchRuntimeInfo(conversationId, agentId, payload) {
+    await getDefaultRTDBClient()?.patchRuntimeInfo(conversationId, agentId, payload);
+}
+export async function clearRuntimeInfo(conversationId, agentId) {
+    await getDefaultRTDBClient()?.clearRuntimeInfo(conversationId, agentId);
+}

package/dist/runtime-cards.d.ts

@@ -21,6 +21,13 @@ export interface ClaudeQuestionReplyMetadata {
 export interface PlanApprovalMetadata {
     type: 'plan_approval';
     planId: string;
+    title?: string;
+    summary?: string;
+    body?: string;
+    allowedPrompts?: ReadonlyArray<{
+        tool: string;
+        prompt: string;
+    }>;
 }
 export interface PlanApprovalReplyMetadata {
     type: 'plan_approval_reply';
@@ -36,7 +43,7 @@ export declare function buildQuestionReply(questionId: string, answers: Record<s
     text: string;
     metadata: ClaudeQuestionReplyMetadata;
 };
-export declare function buildPlanApprovalRequest(planId: string, text?: string): {
+export declare function buildPlanApprovalRequest(planId: string, text?: string, details?: Omit<PlanApprovalMetadata, 'type' | 'planId'>): {
     text: string;
     metadata: PlanApprovalMetadata;
 };

package/dist/runtime-cards.js

@@ -22,12 +22,13 @@ export function buildQuestionReply(questionId, answers) {
         },
     };
 }
-export function buildPlanApprovalRequest(planId, text = 'Plan ready for review.') {
+export function buildPlanApprovalRequest(planId, text = 'Plan ready for review.', details) {
     return {
         text,
         metadata: {
             type: 'plan_approval',
             planId,
+            ...(details ?? {}),
         },
     };
 }

package/dist/types.d.ts

@@ -132,10 +132,130 @@ export interface AgentCapabilities {
 export interface ModelOption {
     value: string;
     label: string;
+    description?: string;
+    workspaceRootId?: string;
+    workspaceRelativePath?: string;
+    source?: WorkspaceOptionSource;
 }
+export type WorkspaceOptionSource = 'default' | 'explicit' | 'discovered';
 export interface WorkspaceOption {
     id: string;
     label: string;
+    description?: string;
+    workspaceRootId?: string;
+    workspaceRelativePath?: string;
+    source?: WorkspaceOptionSource;
+}
+export interface CanonWorkspaceRootMetadata {
+    id: string;
+    label: string;
+    description?: string;
+    defaultRelativePath?: string | null;
+}
+export type CanonControlValue = string;
+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 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';
+export type CanonRuntimeActionPlacement = 'composer_slash' | 'command_palette' | 'session_strip';
+export type CanonRuntimeActionCategory = 'plan' | 'turn' | 'session' | 'details' | 'custom';
+export type CanonRuntimeActionDispatch = {
+    kind: 'control';
+    controlId: string;
+    value: CanonControlValue;
+} | {
+    kind: 'signal';
+    signal: 'interrupt' | 'stop_and_drop';
+} | {
+    kind: 'compose';
+    text: string;
+} | {
+    kind: 'open_details';
+    target?: string;
+};
+export interface CanonRuntimeActionDescriptor {
+    id: string;
+    label: string;
+    description?: string;
+    aliases?: ReadonlyArray<string>;
+    category?: CanonRuntimeActionCategory;
+    placements?: ReadonlyArray<CanonRuntimeActionPlacement>;
+    availability?: ReadonlyArray<CanonRuntimeActionAvailability>;
+    ownerOnly?: boolean;
+    disabledReason?: string | null;
+    trailingTextBehavior?: 'ignore' | 'send_as_prompt';
+    dispatch: CanonRuntimeActionDispatch;
+}
+export interface CanonControlDescriptor {
+    id: string;
+    label: string;
+    options?: ReadonlyArray<ModelOption>;
+    defaultValue?: CanonControlValue | null;
+    availability: CanonControlAvailability;
+    liveBehavior: CanonControlLiveBehavior;
+    selectionPolicy: CanonControlSelectionPolicy;
+    description?: string;
+}
+export interface CanonRuntimeDescriptor {
+    coreControls: ReadonlyArray<CanonControlDescriptor>;
+    runtimeControls?: ReadonlyArray<CanonControlDescriptor>;
+    actions?: ReadonlyArray<CanonRuntimeActionDescriptor>;
+    /**
+     * Optional setup-time local roots advertised by a runtime. These are
+     * metadata only for now; existing session config still selects concrete
+     * workspace IDs until root-relative directory selection lands.
+     */
+    workspaceRoots?: ReadonlyArray<CanonWorkspaceRootMetadata>;
+    writableRoots?: ReadonlyArray<CanonWorkspaceRootMetadata>;
+    supportsInterrupt?: boolean;
+    /**
+     * Fidelity of live text exposed through Canon's streaming bubble path.
+     * `delta` means token/content deltas, `block` means chunked live previews,
+     * `snapshot` means completed assistant-message snapshots, and `status`
+     * means activity/tool state without live assistant text.
+     */
+    streamingTextMode?: CanonRuntimeStreamingMode;
+}
+export interface CanonRuntimeExecutionMetadata {
+    resolvedWorkspaceLabel?: string | null;
+    resolvedCwd?: string | null;
+    workspaceRootId?: string | null;
+    workspaceRelativePath?: string | null;
+    executionMode?: ExecutionEnvironmentMode | null;
+    executionBranch?: string | null;
+    worktreePath?: string | null;
+    fallbackReason?: string | null;
+}
+export interface CanonRuntimeStatusItem {
+    id: string;
+    label: string;
+    value: string;
+    tone?: CanonRuntimeStatusTone;
+}
+export interface CanonRuntimeInventoryEntry {
+    id: string;
+    label: string;
+    status?: CanonRuntimeInventoryStatus;
+    description?: string;
+}
+export interface CanonRuntimeInventory {
+    id: string;
+    label: string;
+    entries: ReadonlyArray<CanonRuntimeInventoryEntry>;
+}
+export interface RuntimeInfoPayload {
+    descriptor: CanonRuntimeDescriptor;
+    surfaceMode?: CanonRuntimeSurfaceMode;
+    surfaceLabel?: string;
+    statusItems?: ReadonlyArray<CanonRuntimeStatusItem>;
+    inventories?: ReadonlyArray<CanonRuntimeInventory>;
+    execution?: CanonRuntimeExecutionMetadata | null;
+    notes?: ReadonlyArray<string>;
+    updatedAt?: number;
 }
 /** Capability map keyed by clientType. Add new agent types here. */
 export declare const AGENT_CAPABILITIES: Record<AgentClientType, AgentCapabilities>;
@@ -193,6 +313,7 @@ export interface RuntimeUpdatedPayload {
     conversationId: string;
     agentId: string;
     runtime: AgentRuntime | null;
+    runtimeInfo?: RuntimeInfoPayload | null;
     sessionState: SessionState | null;
     sessionConfig: SessionConfig | null;
 }
@@ -265,8 +386,9 @@ export interface SetStreamingOptions {
 /** Written by Canon app to /control/{convoId}/{agentId}/session in RTDB */
 export interface SessionControl {
     model?: string;
-    permissionMode?: 'default' | 'acceptEdits' | 'plan' | 'bypassPermissions' | 'auto';
-    effort?: 'low' | 'medium' | 'high' | 'max';
+    permissionMode?: string;
+    effort?: string;
+    runtimeControlValues?: Record<string, CanonControlValue>;
     updatedAt: number;
     updatedBy: string;
 }
@@ -276,9 +398,12 @@ export interface SessionState {
     model?: string;
     permissionMode?: string;
     effort?: string;
+    runtimeControlValues?: Record<string, CanonControlValue>;
     cwd?: string;
     executionMode?: 'worktree' | 'locked';
     executionBranch?: string;
+    worktreePath?: string;
+    executionFallbackReason?: string;
     clientType?: AgentClientType;
     /** True when the agent is running under the host wrapper (host.ts) which can apply control signals */
     hostMode?: boolean;
@@ -297,6 +422,8 @@ export interface SessionConfig {
     hostMode?: boolean;
     model?: string;
     permissionMode?: string;
+    effort?: string;
+    runtimeControlValues?: Record<string, CanonControlValue>;
     workspaceId?: string;
     /**
      * Explicitly selected execution mode. Sessions created before this field
@@ -322,6 +449,9 @@ export declare const CLAUDE_PERMISSION_MODE_OPTIONS: readonly [{
 }, {
     readonly value: "plan";
     readonly label: "Plan";
+}, {
+    readonly value: "dontAsk";
+    readonly label: "Don't ask";
 }, {
     readonly value: "bypassPermissions";
     readonly label: "Bypass";
@@ -335,6 +465,7 @@ export interface AgentRuntime {
     defaultModel?: string;
     defaultPermissionMode?: string;
     availablePermissionModes?: PermissionModeOption[];
+    runtimeDescriptor?: CanonRuntimeDescriptor;
     defaultWorkspaceId?: string;
     /**
      * Execution modes the host will accept. The runtime advertises this so the
@@ -367,13 +498,22 @@ export interface AgentSessionSnapshot {
     modelOptions?: ModelOption[];
     permissionMode?: string;
     permissionModeOptions?: PermissionModeOption[];
+    effort?: string;
+    runtimeControlValues?: Record<string, CanonControlValue>;
+    runtimeDescriptor?: CanonRuntimeDescriptor | null;
+    runtimeInfo?: RuntimeInfoPayload | null;
     workspaceId?: string;
     workspaceOptions?: WorkspaceOption[];
     executionMode?: ExecutionEnvironmentMode;
     availableExecutionModes?: ExecutionEnvironmentMode[];
     executionBranch?: string;
+    resolvedWorkspaceLabel?: string | null;
+    resolvedCwd?: string | null;
+    worktreePath?: string | null;
+    executionFallbackReason?: string | null;
     state?: SessionState['state'];
     turnState?: TurnLifecycleState;
+    supportsQueue?: boolean;
     queueDepth: number;
     waitingForInput: boolean;
     contextUsage?: SessionState['contextUsage'];

package/dist/types.js

@@ -36,6 +36,7 @@ export const CLAUDE_PERMISSION_MODE_OPTIONS = [
     { value: 'default', label: 'Default' },
     { value: 'acceptEdits', label: 'Auto-edit' },
     { value: 'plan', label: 'Plan' },
+    { value: 'dontAsk', label: "Don't ask" },
     { value: 'bypassPermissions', label: 'Bypass' },
     { value: 'auto', label: 'Auto' },
 ];

package/dist/workspace-discovery.d.ts

@@ -0,0 +1,18 @@
+import { type ConfiguredWorkspaceOption } from './execution-environment.js';
+import type { CanonWorkspaceRootMetadata } from './types.js';
+export interface ConfiguredWorkspaceRoot extends CanonWorkspaceRootMetadata {
+    cwd: string;
+}
+export interface WorkspaceDiscoveryResult {
+    workspaceOptions: ConfiguredWorkspaceOption[];
+    workspaceRoots: ConfiguredWorkspaceRoot[];
+    warnings: string[];
+}
+export declare function buildWorkspaceRootId(workspaceRoot: string): string;
+export declare function discoverWorkspaceProjects(root: ConfiguredWorkspaceRoot, warnings?: string[]): ConfiguredWorkspaceOption[];
+export declare function buildPublicWorkspaceRoots(roots: ReadonlyArray<ConfiguredWorkspaceRoot>): CanonWorkspaceRootMetadata[];
+export declare function buildConfiguredWorkspaceOptionsWithRoots(input: {
+    primaryCwd: string;
+    configuredWorkspaces?: string[];
+    workspaceRoots?: string[];
+}): WorkspaceDiscoveryResult;

package/dist/workspace-discovery.js

@@ -0,0 +1,193 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs';
+import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { buildConfiguredWorkspaceOptions, buildWorkspaceOptionId, } from './execution-environment.js';
+const PROJECT_MARKERS = [
+    '.git',
+    'package.json',
+    'pyproject.toml',
+    'Cargo.toml',
+    'go.mod',
+];
+const IGNORED_PROJECT_DIRS = new Set([
+    '.cache',
+    '.git',
+    '.hg',
+    '.svn',
+    '.turbo',
+    '.yarn',
+    'build',
+    'coverage',
+    'dist',
+    'node_modules',
+    'target',
+    'vendor',
+]);
+function shortHash(value) {
+    return createHash('sha256').update(value).digest('hex').slice(0, 12);
+}
+export function buildWorkspaceRootId(workspaceRoot) {
+    let stablePath = resolve(workspaceRoot);
+    try {
+        stablePath = realpathSync(stablePath);
+    }
+    catch {
+        // Nonexistent roots are validated elsewhere; keep deterministic IDs.
+    }
+    return `workspace-root-${shortHash(stablePath)}`;
+}
+function realDirectory(path) {
+    try {
+        const resolved = resolve(path);
+        if (!existsSync(resolved) || !statSync(resolved).isDirectory()) {
+            return null;
+        }
+        return realpathSync(resolved);
+    }
+    catch {
+        return null;
+    }
+}
+function isWithin(parent, child) {
+    const rel = relative(parent, child);
+    return rel === '' || (rel.length > 0 && !rel.startsWith('..') && !isAbsolute(rel));
+}
+function toRelativeProjectPath(rootCwd, projectCwd) {
+    const rel = relative(rootCwd, projectCwd).split(sep).join('/');
+    return rel || '.';
+}
+function hasProjectMarker(cwd) {
+    return PROJECT_MARKERS.some((marker) => existsSync(join(cwd, marker)));
+}
+function normalizeWorkspaceRoots(workspaceRoots) {
+    const roots = [];
+    const warnings = [];
+    const seen = new Set();
+    const seenLabels = new Map();
+    for (const rawRoot of workspaceRoots) {
+        const cwd = realDirectory(rawRoot);
+        if (!cwd) {
+            warnings.push(`Workspace root is not a readable directory: ${rawRoot}`);
+            continue;
+        }
+        if (seen.has(cwd)) {
+            continue;
+        }
+        seen.add(cwd);
+        const baseLabel = basename(cwd) || cwd;
+        const seenLabelCount = (seenLabels.get(baseLabel) ?? 0) + 1;
+        seenLabels.set(baseLabel, seenLabelCount);
+        roots.push({
+            id: buildWorkspaceRootId(cwd),
+            label: seenLabelCount === 1 ? baseLabel : `${baseLabel} (${seenLabelCount})`,
+            cwd,
+        });
+    }
+    return { roots, warnings };
+}
+function findWorkspaceRoot(roots, cwd) {
+    const resolved = realDirectory(cwd) ?? resolve(cwd);
+    return [...roots]
+        .sort((a, b) => b.cwd.length - a.cwd.length)
+        .find((root) => isWithin(root.cwd, resolved)) ?? null;
+}
+function annotateWorkspaceOption(option, roots) {
+    const root = findWorkspaceRoot(roots, option.cwd);
+    if (!root) {
+        return option;
+    }
+    const stableCwd = realDirectory(option.cwd) ?? resolve(option.cwd);
+    const relativePath = toRelativeProjectPath(root.cwd, stableCwd);
+    return {
+        ...option,
+        workspaceRootId: root.id,
+        workspaceRelativePath: relativePath,
+        description: relativePath === '.'
+            ? `${root.label} root`
+            : `${root.label}/${relativePath}`,
+    };
+}
+export function discoverWorkspaceProjects(root, warnings) {
+    const projects = [];
+    if (hasProjectMarker(root.cwd)) {
+        projects.push({
+            id: buildWorkspaceOptionId(root.cwd),
+            label: root.label,
+            cwd: root.cwd,
+            workspaceRootId: root.id,
+            workspaceRelativePath: '.',
+            description: `${root.label} root`,
+            source: 'discovered',
+        });
+    }
+    let entries;
+    try {
+        entries = readdirSync(root.cwd, { withFileTypes: true });
+    }
+    catch {
+        warnings?.push(`Workspace root could not be scanned: ${root.cwd}`);
+        return projects;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || IGNORED_PROJECT_DIRS.has(entry.name)) {
+            continue;
+        }
+        const cwd = realDirectory(join(root.cwd, entry.name));
+        if (!cwd || !isWithin(root.cwd, cwd) || !hasProjectMarker(cwd)) {
+            continue;
+        }
+        const relativePath = toRelativeProjectPath(root.cwd, cwd);
+        projects.push({
+            id: buildWorkspaceOptionId(cwd),
+            label: basename(cwd) || relativePath,
+            cwd,
+            workspaceRootId: root.id,
+            workspaceRelativePath: relativePath,
+            description: `${root.label}/${relativePath}`,
+            source: 'discovered',
+        });
+    }
+    return projects;
+}
+export function buildPublicWorkspaceRoots(roots) {
+    return roots.map((root) => ({
+        id: root.id,
+        label: root.label,
+        ...(root.description ? { description: root.description } : {}),
+        ...(root.defaultRelativePath !== undefined
+            ? { defaultRelativePath: root.defaultRelativePath }
+            : {}),
+    }));
+}
+function relabelWorkspaceOptions(options) {
+    const seenLabels = new Map();
+    return options.map((option) => {
+        const seenCount = (seenLabels.get(option.label) ?? 0) + 1;
+        seenLabels.set(option.label, seenCount);
+        return seenCount === 1
+            ? option
+            : { ...option, label: `${option.label} (${seenCount})` };
+    });
+}
+export function buildConfiguredWorkspaceOptionsWithRoots(input) {
+    const normalizedRoots = normalizeWorkspaceRoots(input.workspaceRoots ?? []);
+    const explicitOptions = buildConfiguredWorkspaceOptions(input.primaryCwd, input.configuredWorkspaces ?? []).map((option) => annotateWorkspaceOption(option, normalizedRoots.roots));
+    const discoveryWarnings = [];
+    const discoveredOptions = normalizedRoots.roots.flatMap((root) => (discoverWorkspaceProjects(root, discoveryWarnings)));
+    const byCwd = new Map();
+    for (const option of discoveredOptions) {
+        byCwd.set(resolve(option.cwd), option);
+    }
+    for (const option of explicitOptions) {
+        byCwd.set(resolve(option.cwd), option);
+    }
+    const ordered = [
+        ...explicitOptions,
+        ...discoveredOptions.filter((option) => !explicitOptions.some((explicit) => resolve(explicit.cwd) === resolve(option.cwd))),
+    ].filter((option, index, options) => (options.findIndex((candidate) => resolve(candidate.cwd) === resolve(option.cwd)) === index)).map((option) => byCwd.get(resolve(option.cwd)) ?? option);
+    return {
+        workspaceOptions: relabelWorkspaceOptions(ordered),
+        workspaceRoots: normalizedRoots.roots,
+        warnings: [...normalizedRoots.warnings, ...discoveryWarnings],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/core",
-  "version": "0.7.5",
+  "version": "0.10.0",
   "description": "Canon core — shared types, REST client, SSE stream, and registration for Canon messaging",
   "type": "module",
   "main": "dist/index.js",
@@ -23,6 +23,7 @@
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
     "dev": "tsc --watch",
+    "test": "vitest run",
     "prepack": "npm run build"
   },
   "engines": {