@canonmsg/claude-code-plugin 0.12.0 → 0.12.2

package/README.md

@@ -15,7 +15,15 @@ canon-register --name "My Claude" --description "My Claude Code agent" --phone "
 canon-claude
 ```
 
-Send a message to your agent in the Canon app. Claude Code responds with full capabilities (file read/write, bash, etc.).
+Send a message to your agent in the Canon app. Claude Code responds with full capabilities (file read/write, bash, etc.). Keep the `canon-claude` terminal open; closing it takes this local agent offline.
+
+After a restart or closed terminal, use the shared local manager to list and revive all recorded local agents:
+
+```bash
+npm install -g @canonmsg/local-agents
+canon-necromance
+canon-necromance revive frontend
+```
 
 ## Features
 
@@ -60,6 +68,8 @@ CANON_AGENT=frontend canon-claude --cwd ~/projects/frontend
 
 For a lighter integration without session controls, run Canon as a channel plugin inside your own Claude Code session. See [full setup guide](../../docs/claude-code-setup.md#channel-mode-alternative).
 
+Channel mode is embedded inside Claude Code and is shown as non-revivable by `canon-necromance`. Use `canon-claude` host mode when you want phone-controlled runtime sessions.
+
 ## Development
 
 ```bash

package/dist/host.js

@@ -26,8 +26,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { query, } from '@anthropic-ai/claude-agent-sdk';
 import { isAnthropicImageAttachment, materializeMessageMedia, toAnthropicImageBlock, } from '@canonmsg/agent-sdk';
-import { CLAUDE_PERMISSION_MODE_OPTIONS, buildConfiguredWorkspaceOptionsWithRoots, buildConversationEnvironmentKey, buildPlanApprovalRequest, buildQuestionRequest, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, EXECUTION_ENVIRONMENT_MODES, CanonClient, CanonStream, clearTurnState, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, normalizeTurnMetadata, prepareConversationEnvironment, resolveCanonAgent, getActiveProfile, releaseLock, initRTDBAuth, rtdbRead, rtdbWrite, writeRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, releaseConversationEnvironment, } from '@canonmsg/core';
-import { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
+import { CLAUDE_PERMISSION_MODE_OPTIONS, buildCanonHostPrompt, buildConfiguredWorkspaceOptionsWithRoots, buildConversationEnvironmentKey, buildFirstPartyCodingRuntimeDescriptor, buildHydratedInboundContext, buildPlanApprovalRequest, buildQuestionRequest, buildPublicWorkspaceRoots, buildPublicWorkspaceOptions, createConversationMetadataLoader, createRuntimeStatePublisher, EXECUTION_ENVIRONMENT_MODES, CanonClient, CanonStream, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, ExecutionEnvironmentError, FINAL_MESSAGE_HANDOFF_MS, buildLocalRuntimeId, getActiveProfileLock, heartbeatLocalRuntimeEntry, normalizeTurnMetadata, prepareConversationEnvironment, resolveCanonAgent, initRTDBAuth, rtdbRead, loadHostSessionConfig, loadRuntimeSessionState, markLocalRuntimeStopped, releaseConversationEnvironment, saveRuntimeSessionState, clearRuntimeSessionState, publishHostAgentRuntime, publishHostSessionSnapshots, renderCanonHostInboundContent, resolveHostWorkspaceCwd, upsertLocalRuntimeEntry, } from '@canonmsg/core';
 import { buildInboundContextLines, decideAutoReply, } from './inbound-policy.js';
 import { createStreamingBuffer } from './streaming-buffer.js';
 import { runCli } from './cli-entry.js';
@@ -47,76 +46,16 @@ let runtimeMetadata = {
 };
 let runtimeMetadataRefresh = null;
 function buildClaudeRuntimeDescriptor(input) {
-    return {
-        coreControls: [
-            {
-                id: 'model',
-                label: 'Model',
-                options: input.models,
-                defaultValue: input.models[0]?.value ?? null,
-                availability: 'setup_and_live',
-                liveBehavior: 'immediate',
-                selectionPolicy: 'inherit',
-            },
-            {
-                id: 'workspace',
-                label: 'Project',
-                options: input.workspaces.map((workspace) => ({
-                    value: 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 } : {}),
-                })),
-                defaultValue: input.workspaces[0]?.id ?? null,
-                availability: 'setup',
-                liveBehavior: 'none',
-                selectionPolicy: 'inherit',
-                description: input.workspaceRoots?.length
-                    ? 'Choose one of the projects discovered inside the approved local roots for this host.'
-                    : 'Choose one of the local projects advertised by this host.',
-            },
-            {
-                id: 'executionMode',
-                label: 'Execution mode',
-                options: input.executionModes.map((mode) => ({
-                    value: mode,
-                    label: mode === 'worktree' ? 'Isolated worktree' : 'Use shared project',
-                    description: mode === 'worktree'
-                        ? 'Creates or reuses a per-conversation git worktree under ~/.canon/conversation-worktrees when the selected project is a git repo.'
-                        : 'Runs directly in the selected project folder. Changes happen there.',
-                })),
-                defaultValue: null,
-                availability: 'setup',
-                liveBehavior: 'none',
-                selectionPolicy: 'required_explicit',
-            },
-        ],
-        runtimeControls: [
-            {
-                id: 'permissionMode',
-                label: 'Permission mode',
-                options: [...CLAUDE_PERMISSION_MODE_OPTIONS],
-                defaultValue: 'default',
-                availability: 'setup_and_live',
-                liveBehavior: 'immediate',
-                selectionPolicy: 'inherit',
-            },
-            {
-                id: 'effort',
-                label: 'Thinking level',
-                options: [
-                    { value: 'low', label: 'Low' },
-                    { value: 'medium', label: 'Medium' },
-                    { value: 'high', label: 'High' },
-                ],
-                defaultValue: 'medium',
-                availability: 'setup_and_live',
-                liveBehavior: 'immediate',
-                selectionPolicy: 'inherit',
-            },
-        ],
+    return buildFirstPartyCodingRuntimeDescriptor({
+        clientType: 'claude-code',
+        models: input.models,
+        workspaces: input.workspaces,
+        workspaceRoots: input.workspaceRoots,
+        executionModes: input.executionModes,
+        permissionModes: CLAUDE_PERMISSION_MODE_OPTIONS,
+        defaultPermissionMode: 'default',
+        streamingTextMode: 'delta',
+        admissionActions: HOST_ADMISSION_ACTIONS_DISABLED,
         actions: [
             {
                 id: 'plan',
@@ -204,10 +143,7 @@ function buildClaudeRuntimeDescriptor(input) {
                 dispatch: { kind: 'signal', signal: 'interrupt' },
             },
         ],
-        workspaceRoots: input.workspaceRoots,
-        supportsInterrupt: true,
-        streamingTextMode: 'delta',
-    };
+    });
 }
 function normalizeClaudeEffortLevel(value) {
     return value === 'low' || value === 'medium' || value === 'high'
@@ -549,7 +485,7 @@ async function buildCanonUserContent(input) {
     ];
 }
 // ── Session factory ─────────────────────────────────────────────────
-function createSession(conversationId, environment, agentId, client, onSessionEnd, onRuntimeDescriptorUpdate, config, resumeSessionId) {
+function createSession(conversationId, environment, agentId, client, runtimeState, onSessionEnd, onRuntimeDescriptorUpdate, config, resumeSessionId) {
     const { cwd } = environment;
     // Per-session input stream with message queue
     let resolveInput = null;
@@ -756,10 +692,9 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
             session.streamingTimer = timer;
         },
         onWrite: (text) => {
-            rtdbWrite(`/streaming/${conversationId}/${agentId}`, {
+            runtimeState.writeStreaming(conversationId, {
                 text,
                 status: 'streaming',
-                updatedAt: { '.sv': 'timestamp' },
             }).catch(() => { });
         },
     });
@@ -772,7 +707,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
     }
     function clearStreaming() {
         streamingBuffer.clear();
-        rtdbWrite(`/streaming/${conversationId}/${agentId}`, null).catch(() => { });
+        runtimeState.clearStreaming(conversationId).catch(() => { });
     }
     function clearIdleResetTimer() {
         if (!session.idleResetTimer)
@@ -861,7 +796,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
         }, FINAL_DELIVERY_RETRY_MS);
     }
     function writeState() {
-        writeSessionState(conversationId, agentId, {
+        runtimeState.writeSessionState(conversationId, {
             ...session.state,
             ...(session.availableModels.length ? { availableModels: session.availableModels } : {}),
             cwd,
@@ -876,7 +811,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
         }).catch(() => { });
     }
     function writeTurn() {
-        writeTurnState(conversationId, agentId, {
+        runtimeState.writeTurnState(conversationId, {
             turnId: session.currentTurnId,
             state: session.turnState,
             queueDepth: session.pendingInputs.length,
@@ -1137,7 +1072,7 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
                     executionModes: config.availableExecutionModes,
                 }),
             });
-            writeSessionState(conversationId, agentId, {
+            runtimeState.writeSessionState(conversationId, {
                 ...session.state,
                 availableModels: modelList,
                 cwd,
@@ -1158,7 +1093,13 @@ function createSession(conversationId, environment, agentId, client, onSessionEn
         console.error(`[canon-host] [${conversationId.slice(0, 8)}] Session ${resumeSessionId ? 'resumed' : 'started'} `
             + `(mode: ${environment.mode}, cwd: ${cwd})`);
     };
-    init().catch((err) => console.error(`[canon-host] [${conversationId.slice(0, 8)}] Init failed:`, err));
+    init().catch((err) => {
+        console.error(`[canon-host] [${conversationId.slice(0, 8)}] Init failed:`, err);
+        if (resumeSessionId) {
+            session.sdkSessionId = null;
+            onSessionEnd(conversationId, null);
+        }
+    });
     return session;
 }
 // ── Main ────────────────────────────────────────────────────────────
@@ -1186,10 +1127,10 @@ export async function main() {
     for (const warning of workspaceDiscovery.warnings) {
         console.error(`[canon-host] ${warning}`);
     }
-    const { apiKey, agentId: profileAgentId, profile } = resolveCanonAgent({ logPrefix: '[canon-host]' });
+    const { apiKey, agentId: profileAgentId, agentName: profileAgentName, profile, baseUrl, lockHandle, } = resolveCanonAgent({ logPrefix: '[canon-host]', expectedClientType: 'claude-code' });
     console.error(`[canon-host] Starting${profile ? ` (profile: ${profile})` : ''} in ${workingDir}`);
     // ── Canon API client + RTDB auth ──
-    const client = new CanonClient(apiKey);
+    const client = new CanonClient(apiKey, baseUrl);
     initRTDBAuth(client);
     let agentId;
     let ownerId = null;
@@ -1209,6 +1150,39 @@ export async function main() {
         }
         console.error(`[canon-host] Authenticated as ${agentId}`);
     }
+    const launchArgs = [...process.argv.slice(2)];
+    if (!launchArgs.some((arg) => arg === '--cwd' || arg.startsWith('--cwd='))) {
+        launchArgs.push('--cwd', workingDir);
+    }
+    const runtimeId = buildLocalRuntimeId({
+        runtime: 'claude-code',
+        profile,
+        cwd: workingDir,
+        launchCommand: ['canon-claude', ...launchArgs],
+    });
+    upsertLocalRuntimeEntry({
+        id: runtimeId,
+        runtime: 'claude-code',
+        profile,
+        agentId,
+        agentName: profileAgentName,
+        cwd: workingDir,
+        baseCwd: workingDir,
+        workspaceRoots: workspaceRoots.map((root) => root.cwd),
+        workspaces: workspaceOptions.map((workspace) => workspace.cwd),
+        launchCommand: ['canon-claude', ...launchArgs],
+        pid: process.pid,
+        status: profile ? 'running' : 'manual',
+        reviveCapability: profile ? 'revivable' : 'manual',
+        surfaceMode: 'host',
+        lastStartedAt: new Date().toISOString(),
+        lastHeartbeatAt: new Date().toISOString(),
+    });
+    const runtimeState = createRuntimeStatePublisher({
+        agentId,
+        clientType: 'claude-code',
+        hostMode: true,
+    });
     let streamConnected = false;
     const hostAvailableExecutionModes = [
         ...EXECUTION_ENVIRONMENT_MODES,
@@ -1230,6 +1204,12 @@ export async function main() {
     const knownConversationIds = new Set();
     let lastKnownConversationRefreshAt = 0;
     const publishRuntimeHeartbeat = async () => {
+        heartbeatLocalRuntimeEntry(runtimeId, {
+            agentId,
+            agentName: profileAgentName,
+            cwd: workingDir,
+            baseCwd: workingDir,
+        });
         if (!streamConnected)
             return;
         await refreshKnownConversationIds().catch((error) => {
@@ -1253,6 +1233,7 @@ export async function main() {
             runtime: runtimeDescriptor,
             workspaceOptions,
             defaultCwd: workingDir,
+            extraSessionConfigFields: ['permissionMode', 'effort'],
             liveSessionConfigByConversation: new Map(Array.from(sessions.values()).map((session) => {
                 const workspaceId = resolveWorkspaceIdForBaseCwd(session.environment.baseCwd);
                 return [
@@ -1293,7 +1274,7 @@ export async function main() {
                 worktreePath: session?.environment.worktreePath ?? null,
                 fallbackReason: resolveExecutionFallbackReason(session?.environment),
             });
-            await writeRuntimeInfo(conversationId, agentId, payload);
+            await runtimeState.writeRuntimeInfo(conversationId, payload);
         })).catch((error) => {
             console.error('[canon-host] Failed to publish runtime info:', error);
         });
@@ -1395,11 +1376,17 @@ export async function main() {
         // Save SDK session ID for future resume
         if (session.sdkSessionId) {
             savedSessionIds.set(buildConversationEnvironmentKey(conversationId, session.environment.baseCwd), session.sdkSessionId);
+            saveRuntimeSessionState(runtimeId, {
+                conversationId,
+                baseCwd: session.environment.baseCwd,
+                executionMode: session.environment.mode,
+                claudeSessionId: session.sdkSessionId,
+            });
         }
         if (session.streamingTimer)
             clearTimeout(session.streamingTimer);
         session.streamingText = '';
-        rtdbWrite(`/streaming/${conversationId}/${agentId}`, null).catch(() => { });
+        runtimeState.clearStreaming(conversationId).catch(() => { });
         if (session.idleResetTimer) {
             clearTimeout(session.idleResetTimer);
             session.idleResetTimer = null;
@@ -1408,8 +1395,8 @@ export async function main() {
             clearTimeout(session.finalDeliveryTimer);
             session.finalDeliveryTimer = null;
         }
-        clearSessionState(conversationId, agentId).catch(() => { });
-        clearTurnState(conversationId, agentId).catch(() => { });
+        runtimeState.clearSessionState(conversationId).catch(() => { });
+        runtimeState.clearTurnState(conversationId).catch(() => { });
         client.setTyping(conversationId, false).catch(() => { });
         try {
             session.query.close();
@@ -1457,19 +1444,37 @@ export async function main() {
             });
             try {
                 const resumeKey = buildConversationEnvironmentKey(conversationId, environment.baseCwd);
-                const resumeId = savedSessionIds.get(resumeKey);
-                const session = createSession(conversationId, environment, agentId, client, (convoId, sdkSessionId) => {
+                const persisted = loadRuntimeSessionState(runtimeId, {
+                    conversationId,
+                    baseCwd: environment.baseCwd,
+                    executionMode: environment.mode,
+                });
+                const resumeId = savedSessionIds.get(resumeKey) ?? persisted?.claudeSessionId;
+                const session = createSession(conversationId, environment, agentId, client, runtimeState, (convoId, sdkSessionId) => {
                     // Called when session processing loop ends — save session ID for resume
                     const existing = sessions.get(convoId);
                     if (existing) {
                         releaseConversationEnvironment(existing.environment);
                         if (sdkSessionId) {
                             savedSessionIds.set(buildConversationEnvironmentKey(convoId, existing.environment.baseCwd), sdkSessionId);
+                            saveRuntimeSessionState(runtimeId, {
+                                conversationId: convoId,
+                                baseCwd: existing.environment.baseCwd,
+                                executionMode: existing.environment.mode,
+                                claudeSessionId: sdkSessionId,
+                            });
+                        }
+                        else {
+                            clearRuntimeSessionState(runtimeId, {
+                                conversationId: convoId,
+                                baseCwd: existing.environment.baseCwd,
+                                executionMode: existing.environment.mode,
+                            });
                         }
                     }
                     sessions.delete(convoId);
-                    clearSessionState(convoId, agentId).catch(() => { });
-                    clearTurnState(convoId, agentId).catch(() => { });
+                    runtimeState.clearSessionState(convoId).catch(() => { });
+                    runtimeState.clearTurnState(convoId).catch(() => { });
                 }, (descriptor) => {
                     runtimeDescriptor = descriptor;
                     void publishRuntimeHeartbeat();
@@ -1496,6 +1501,112 @@ export async function main() {
             pendingSessionCreations.delete(conversationId);
         }
     }
+    async function enqueueRecoveredInboundMessage(input) {
+        const m = input.message;
+        if (m.senderId === agentId)
+            return;
+        let materialized = [];
+        if (m.id) {
+            try {
+                materialized = await materializeMessageMedia({
+                    id: m.id,
+                    attachments: m.attachments ?? [],
+                }, { agentId, conversationId: input.conversationId });
+            }
+            catch (error) {
+                console.error(`[canon-host] [${input.conversationId.slice(0, 8)}] Failed to materialize recovered media:`, error instanceof Error ? error.message : error);
+            }
+        }
+        const sender = m.senderName || m.senderId;
+        const isOwner = m.isOwner ?? (ownerId != null && m.senderId === ownerId);
+        const content = renderInboundContent(m, materialized);
+        const hydrated = await loadHydratedInboundContext({
+            conversationId: input.conversationId,
+            message: m,
+            senderName: sender,
+            isOwner,
+        });
+        const behavior = input.hydratedPage?.behavior ?? hydrated.behavior;
+        const workSessions = input.hydratedPage?.workSessions ?? hydrated.workSessions;
+        const participantContext = hydrated.participantContext;
+        const autoReply = decideAutoReply(participantContext, behavior);
+        if (!autoReply.allow) {
+            console.error(`[canon-host] [${input.conversationId.slice(0, 8)}] Suppressed recovered auto-reply: ${autoReply.reason}`);
+            return;
+        }
+        let session;
+        try {
+            session = await getOrCreateSession(input.conversationId);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const userMessage = error instanceof ExecutionEnvironmentError ? error.userMessage : message;
+            console.error(`[canon-host] [${input.conversationId.slice(0, 8)}] Failed to create recovered session: ${message}`);
+            await client.sendMessage(input.conversationId, `I couldn't start a coding session for this workspace: ${userMessage}`, {
+                metadata: {
+                    turnSemantics: 'turn_complete',
+                    turnComplete: true,
+                },
+            }).catch(() => { });
+            return;
+        }
+        const turnMetadata = normalizeTurnMetadata(m.metadata);
+        const deliveryIntent = turnMetadata?.deliveryIntent ?? 'queue';
+        const shouldMarkAccepted = turnMetadata?.inboundDisposition === 'queued';
+        const promptText = buildCanonPrompt({
+            content,
+            conversationId: input.conversationId,
+            participantContext,
+            behavior,
+            workSession: m.workSession,
+            workSessions,
+        });
+        const messageContent = await buildCanonUserContent({ promptText, materialized });
+        session.enqueueInbound({
+            type: 'user',
+            message: {
+                role: 'user',
+                content: messageContent,
+            },
+            parent_tool_use_id: null,
+        }, deliveryIntent, m.id ?? null, shouldMarkAccepted);
+        if (m.id) {
+            saveRuntimeSessionState(runtimeId, {
+                conversationId: input.conversationId,
+                baseCwd: workingDir,
+                lastInboundMessageId: m.id,
+            });
+        }
+    }
+    try {
+        for (const conversation of conversationCache.values()) {
+            const cursor = loadRuntimeSessionState(runtimeId, {
+                conversationId: conversation.id,
+                baseCwd: workingDir,
+            })?.lastInboundMessageId;
+            const page = await client.getMessagesPage(conversation.id, 25);
+            const inboundMessages = page.messages
+                .filter((message) => message.senderId !== agentId)
+                .sort((a, b) => String(a.createdAt ?? '').localeCompare(String(b.createdAt ?? '')));
+            const cursorIndex = cursor
+                ? inboundMessages.findIndex((message) => message.id === cursor)
+                : -1;
+            const messagesToRecover = cursorIndex >= 0
+                ? inboundMessages.slice(cursorIndex + 1)
+                : inboundMessages.slice(-1);
+            for (const message of messagesToRecover) {
+                console.error(`[canon-host] [${conversation.id.slice(0, 8)}] Recovering inbound message on startup`);
+                await enqueueRecoveredInboundMessage({
+                    conversationId: conversation.id,
+                    message: message,
+                    hydratedPage: page,
+                });
+            }
+        }
+    }
+    catch (error) {
+        console.error('[canon-host] Failed startup recovery:', error instanceof Error ? error.message : error);
+    }
     // ── Connect SSE stream for inbound Canon messages ──
     const stream = new CanonStream({
         apiKey,
@@ -1607,6 +1718,13 @@ export async function main() {
                         },
                         parent_tool_use_id: null,
                     }, deliveryIntent, m.id ?? null, shouldMarkAccepted);
+                    if (m.id) {
+                        saveRuntimeSessionState(runtimeId, {
+                            conversationId: convoId,
+                            baseCwd: workingDir,
+                            lastInboundMessageId: m.id,
+                        });
+                    }
                 })();
             },
             onConnected: () => {
@@ -1616,7 +1734,7 @@ export async function main() {
             },
             onDisconnected: () => {
                 streamConnected = false;
-                rtdbWrite(`/agent-runtime/${agentId}`, null).catch(() => { });
+                runtimeState.clearAgentRuntime().catch(() => { });
                 console.error('[canon-host] SSE disconnected');
             },
             onError: (err) => console.error(`[canon-host] SSE error: ${err.message}`),
@@ -1674,7 +1792,7 @@ export async function main() {
                                         console.error(`[canon-host] [${convoId.slice(0, 8)}] Failed to set effort:`, err);
                                     }
                                 }
-                                writeSessionState(convoId, agentId, {
+                                runtimeState.writeSessionState(convoId, {
                                     ...session.state,
                                     ...(session.availableModels.length ? { availableModels: session.availableModels } : {}),
                                     cwd: session.cwd,
@@ -1702,7 +1820,7 @@ export async function main() {
                                 console.error(`[canon-host] [${convoId.slice(0, 8)}] Interrupt signal`);
                                 try {
                                     session.turnState = 'interrupted';
-                                    writeTurnState(convoId, agentId, {
+                                    runtimeState.writeTurnState(convoId, {
                                         turnId: session.currentTurnId,
                                         state: 'interrupted',
                                         queueDepth: session.pendingInputs.length,
@@ -1718,7 +1836,7 @@ export async function main() {
                                         session.streamingTimer = null;
                                     }
                                     session.streamingText = '';
-                                    rtdbWrite(`/streaming/${convoId}/${agentId}`, null).catch(() => { });
+                                    runtimeState.clearStreaming(convoId).catch(() => { });
                                     client.setTyping(convoId, false).catch(() => { });
                                 }
                                 catch (err) {
@@ -1739,7 +1857,7 @@ export async function main() {
     // ── Heartbeat (per-session) ──
     const heartbeat = setInterval(() => {
         for (const session of sessions.values()) {
-            writeSessionState(session.conversationId, agentId, {
+            runtimeState.writeSessionState(session.conversationId, {
                 ...session.state,
                 ...(session.availableModels.length ? { availableModels: session.availableModels } : {}),
                 cwd: session.cwd,
@@ -1749,7 +1867,7 @@ export async function main() {
                 hostMode: true,
                 isActive: true,
             }).catch(() => { });
-            writeTurnState(session.conversationId, agentId, {
+            runtimeState.writeTurnState(session.conversationId, {
                 turnId: session.currentTurnId,
                 state: session.turnState,
                 queueDepth: session.pendingInputs.length,
@@ -1784,17 +1902,17 @@ export async function main() {
         clearInterval(heartbeat);
         clearInterval(idleCheck);
         stream.stop();
-        await rtdbWrite(`/agent-runtime/${agentId}`, null).catch(() => { });
+        await runtimeState.clearAgentRuntime().catch(() => { });
         for (const convoId of [...sessions.keys()]) {
             closeSession(convoId);
         }
-        const ap = getActiveProfile();
-        if (ap)
-            releaseLock(ap);
+        markLocalRuntimeStopped(runtimeId);
+        (lockHandle ?? getActiveProfileLock())?.release();
         process.exit(0);
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
+    process.on('SIGHUP', shutdown);
     console.error('[canon-host] Ready — sessions created on demand');
     // Keep alive
     await new Promise(() => { });
@@ -1802,8 +1920,6 @@ export async function main() {
 // ── Entry ───────────────────────────────────────────────────────────
 runCli(import.meta.url, main, (err) => {
     console.error('[canon-host] Fatal error:', err);
-    const ap = getActiveProfile();
-    if (ap)
-        releaseLock(ap);
+    getActiveProfileLock()?.release();
     process.exit(1);
 });

package/dist/register.js

@@ -9,14 +9,10 @@ import { setDefaultResultOrder } from 'node:dns';
  *
  * On approval, saves the agent to ~/.canon/agents.json under the profile name.
  */
-import { registerAndWaitForApproval } from '@canonmsg/core';
-import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
-import { homedir } from 'node:os';
+import { ackRegistrationApproval, clearPendingRegistration, getOrCreatePendingRegistration, registerAndWaitForApproval, updatePendingRegistration, upsertAgentProfile, AGENTS_PATH, } from '@canonmsg/core';
+import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
 import { runCli } from './cli-entry.js';
-const CANON_DIR = join(homedir(), '.canon');
-const AGENTS_PATH = join(CANON_DIR, 'agents.json');
 export async function main() {
     setDefaultResultOrder('ipv4first');
     const { values } = parseArgs({
@@ -44,6 +40,7 @@ export async function main() {
         // File doesn't exist yet
     }
     console.log(`Registering agent "${values.name}" (profile: ${profileName})...`);
+    const pending = getOrCreatePendingRegistration(profileName, 'claude-code');
     const result = await registerAndWaitForApproval({
         name: values.name,
         description: values.description,
@@ -52,8 +49,14 @@ export async function main() {
         clientType: 'claude-code',
         baseUrl: values['base-url'],
         requestedAgentId: existingAgentId,
+        localRegistrationId: pending.localRegistrationId,
     }, {
-        onSubmitted: (requestId) => {
+        onSubmitted: (requestId, pollToken) => {
+            updatePendingRegistration(profileName, {
+                requestId,
+                pollToken,
+                clientType: 'claude-code',
+            });
             console.log(`Registration submitted (request ID: ${requestId}).`);
             console.log('Waiting for approval in Canon app...');
         },
@@ -64,25 +67,26 @@ export async function main() {
     console.log(''); // newline after dots
     switch (result.status) {
         case 'approved': {
-            // Save to ~/.canon/agents.json
-            mkdirSync(CANON_DIR, { recursive: true });
-            let profiles = {};
-            try {
-                profiles = JSON.parse(readFileSync(AGENTS_PATH, 'utf-8'));
+            if (!result.apiKey || !result.agentId || !result.agentName) {
+                console.error('Approval completed but Canon did not return a usable API key. Run this command again to resume key pickup.');
+                process.exit(1);
             }
-            catch {
-                // File doesn't exist yet
-            }
-            profiles[profileName] = {
+            upsertAgentProfile(profileName, {
                 apiKey: result.apiKey,
                 agentId: result.agentId,
                 agentName: result.agentName,
                 registeredAt: new Date().toISOString(),
-            };
-            writeFileSync(AGENTS_PATH, JSON.stringify(profiles, null, 2));
+                clientType: 'claude-code',
+                ...(typeof values['base-url'] === 'string' ? { baseUrl: values['base-url'] } : {}),
+            });
+            if (result.requestId) {
+                await ackRegistrationApproval(values['base-url'], result.requestId, result.pollToken);
+            }
+            clearPendingRegistration(profileName);
             console.log(`Approved! Agent: ${result.agentName} (${result.agentId})`);
             console.log(`Saved as profile "${profileName}" in ~/.canon/agents.json`);
-            console.log('Restart Claude Code to connect.');
+            console.log('Start it with: CANON_AGENT=' + profileName + ' canon-claude --cwd /path/to/project');
+            console.log('Keep that terminal open. Closing it takes this local agent offline.');
             break;
         }
         case 'rejected':

package/dist/server.js

@@ -10,7 +10,7 @@ import { setDefaultResultOrder } from 'node:dns';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { CanonClient, CanonStream, ApprovalManager, loadProfiles, isProfileLocked, resolveCanonAgent, getActiveProfile, releaseLock, initRTDBAuth, writeSessionState, clearSessionState, } from '@canonmsg/core';
+import { CanonClient, CanonStream, ApprovalManager, buildLocalRuntimeId, getActiveProfileLock, markLocalRuntimeStopped, loadProfiles, isProfileLocked, resolveCanonAgent, getActiveProfile, releaseLock, upsertLocalRuntimeEntry, initRTDBAuth, writeSessionState, clearSessionState, } from '@canonmsg/core';
 import { ApprovalHttpServer } from './approval-server.js';
 import { runCli } from './cli-entry.js';
 // ── MCP server ─────────────────────────────────────────────────────────
@@ -525,10 +525,14 @@ async function handleInboundMessage(payload) {
 async function startChannel() {
     let apiKey;
     let profile;
+    let baseUrl;
+    let profileAgentName;
     try {
-        const resolved = resolveCanonAgent({ logPrefix: '[canon]' });
+        const resolved = resolveCanonAgent({ logPrefix: '[canon]', expectedClientType: 'claude-code' });
         apiKey = resolved.apiKey;
         profile = resolved.profile;
+        baseUrl = resolved.baseUrl;
+        profileAgentName = resolved.agentName;
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : err);
@@ -537,7 +541,7 @@ async function startChannel() {
     if (profile) {
         console.error(`[canon] Using agent profile: ${profile}`);
     }
-    client = new CanonClient(apiKey);
+    client = new CanonClient(apiKey, baseUrl);
     // Get agent identity — try /agents/me first, fall back to /agents/auth-token
     let agentId;
     try {
@@ -560,6 +564,27 @@ async function startChannel() {
     }
     // Initialize RTDB auth for session state reporting
     initRTDBAuth(client);
+    const runtimeId = buildLocalRuntimeId({
+        runtime: 'claude-code',
+        profile,
+        cwd: process.cwd(),
+        launchCommand: ['canon-channel-server'],
+    });
+    upsertLocalRuntimeEntry({
+        id: runtimeId,
+        runtime: 'claude-code',
+        profile,
+        agentId,
+        agentName: agentContext?.displayName ?? profileAgentName,
+        cwd: process.cwd(),
+        launchCommand: ['canon-channel-server'],
+        pid: process.pid,
+        status: 'embedded',
+        reviveCapability: 'embedded',
+        surfaceMode: 'channel',
+        lastStartedAt: new Date().toISOString(),
+        lastHeartbeatAt: new Date().toISOString(),
+    });
     // Populate conversation cache
     try {
         const convos = await client.getConversations();
@@ -627,13 +652,22 @@ export async function main() {
         approvalManager?.dispose();
         approvalServer?.stop().catch(() => { });
         stream?.stop();
+        const runtimeId = buildLocalRuntimeId({
+            runtime: 'claude-code',
+            profile: getActiveProfile(),
+            cwd: process.cwd(),
+            launchCommand: ['canon-channel-server'],
+        });
+        markLocalRuntimeStopped(runtimeId);
         const ap = getActiveProfile();
         if (ap)
             releaseLock(ap);
+        getActiveProfileLock()?.release();
         process.exit(0);
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
+    process.on('SIGHUP', shutdown);
 }
 runCli(import.meta.url, main, (err) => {
     console.error('[canon] Fatal error:', err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/claude-code-plugin",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Canon channel plugin for Claude Code — messaging where AI agents are first-class citizens",
   "type": "module",
   "main": "dist/index.js",
@@ -31,8 +31,8 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.101",
-    "@canonmsg/agent-sdk": "^0.9.2",
-    "@canonmsg/core": "^0.10.0",
+    "@canonmsg/agent-sdk": "^0.10.2",
+    "@canonmsg/core": "^0.14.0",
     "@modelcontextprotocol/sdk": "^1.12.0"
   },
   "engines": {

package/dist/host-runtime.d.ts

@@ -1,134 +0,0 @@
-/**
- * Host-runtime helpers, inlined from @canonmsg/core.
- *
- * These helpers glue Canon host wrappers (Codex, Claude Code) to the Canon
- * RTDB session/runtime surface. They used to live in
- * `@canonmsg/core/src/host-runtime/` but were moved into each plugin in
- * media-parity PR C so core does not have to carry host-specific concerns.
- *
- * Keep this file in lockstep with the equivalent file in
- * `packages/codex-plugin/src/host-runtime.ts`. If you change the
- * behavior here, update that copy too and adjust the shared golden
- * fixture test (`packages/claude-code-plugin/src/host-runtime.test.ts`).
- */
-import { type AgentClientType, type AgentRuntime, type CanonClient, type CanonConversation, type CanonMessage, type CanonMessagesPage, type MessageCreatedPayload, type ResolvedAgentBehaviorPolicy, type SessionWorkspaceConfig } from '@canonmsg/core';
-export interface HostInboundParticipantContext {
-    conversationType: CanonConversation['type'] | 'unknown';
-    memberCount: number | null;
-    senderType: 'human' | 'ai_agent';
-    senderName: string;
-    isOwner: boolean;
-    mentionedAgent: boolean;
-    recentSenderTypes: Array<'human' | 'ai_agent'>;
-    recentHumanCount: number;
-    recentAgentCount: number;
-    consecutiveAgentTurns: number;
-    currentAgentStreakStartedByHuman: boolean;
-}
-type HostInboundMessage = {
-    text?: string | null;
-    contentType?: CanonMessage['contentType'] | null;
-    attachments?: CanonMessage['attachments'];
-    senderType?: CanonMessage['senderType'];
-    mentions?: string[] | null;
-    contactCard?: CanonMessage['contactCard'];
-};
-interface HostWorkspaceResolverOption {
-    id: string;
-    cwd: string;
-}
-export declare const HOST_ADMISSION_ACTION_CAPABILITIES: Readonly<{
-    canStartDirectConversation: false;
-    canSendContactRequest: false;
-    canApprovePendingContactRequests: false;
-    canRejectPendingContactRequests: false;
-}>;
-export declare function buildCanonHostPrompt(input: {
-    hostLabel: string;
-    content: string;
-    conversationId: string;
-    participantContext: HostInboundParticipantContext;
-    behavior?: ResolvedAgentBehaviorPolicy | null;
-    workSession?: MessageCreatedPayload['message']['workSession'];
-    workSessions?: MessageCreatedPayload['workSessions'];
-    buildInboundContextLines: (context: HostInboundParticipantContext) => string[];
-}): string;
-/**
- * Render the **text portion** of an inbound Canon message. Images and other
- * binary attachments are referenced by short placeholders — their actual
- * bytes are delivered to the host as native vision/media inputs (Anthropic
- * image blocks, Codex `-i` file args). URLs are intentionally *not* inlined,
- * since the harness never needs to refetch and earlier `[Image: <url>]`
- * inlining caused vision models to see a string about an image instead of
- * the image itself.
- *
- * `materialized` may be passed so non-image attachments can reference a
- * local path the agent can Read. Without it we fall back to an unadorned
- * placeholder; the vision path still works because image blocks carry the
- * bytes directly.
- */
-export declare function renderCanonHostInboundContent(message: HostInboundMessage, materialized?: ReadonlyArray<{
-    kind: 'image' | 'audio' | 'file';
-    path: string;
-    fileName?: string;
-    durationMs?: number;
-    index: number;
-}>): string;
-export declare function buildHydratedInboundContext(input: {
-    agentId: string;
-    conversation: CanonConversation | null;
-    page?: CanonMessagesPage | null;
-    message: HostInboundMessage;
-    senderName: string;
-    isOwner: boolean;
-}): {
-    participantContext: HostInboundParticipantContext;
-    behavior?: ResolvedAgentBehaviorPolicy | null;
-    workSessions: NonNullable<MessageCreatedPayload['workSessions']>;
-    hydratedFromPage: boolean;
-};
-export declare function publishHostAgentRuntime(agentId: string, clientType: AgentClientType, runtime: AgentRuntime): Promise<void>;
-export declare function publishHostSessionSnapshots(input: {
-    conversationIds: string[];
-    agentId: string;
-    clientType: AgentClientType;
-    runtime: AgentRuntime;
-    workspaceOptions: HostWorkspaceResolverOption[];
-    defaultCwd: string;
-    liveSessionConfigByConversation?: ReadonlyMap<string, {
-        model?: string;
-        permissionMode?: string;
-        effort?: string;
-        runtimeControlValues?: Record<string, string>;
-        workspaceId?: string;
-        executionMode?: SessionWorkspaceConfig['executionMode'];
-        executionBranch?: string | null;
-    }>;
-}): Promise<void>;
-export declare function readHostSessionConfig<TExtra extends string = never>(raw: unknown, extraStringFields?: readonly TExtra[]): (SessionWorkspaceConfig & Partial<Record<TExtra, string>> & {
-    runtimeControlValues?: Record<string, string>;
-}) | null;
-export declare function loadHostSessionConfig<TExtra extends string = never>(input: {
-    conversationId: string;
-    agentId: string;
-    extraStringFields?: readonly TExtra[];
-}): Promise<(SessionWorkspaceConfig & Partial<Record<TExtra, string>> & {
-    runtimeControlValues?: Record<string, string>;
-}) | null>;
-export declare function resolveHostWorkspaceCwd(input: {
-    workspaceOptions: HostWorkspaceResolverOption[];
-    config: {
-        workspaceId?: string;
-        retiredWorkspaceConfig?: boolean;
-    } | null;
-    defaultCwd: string;
-}): string;
-export declare function createConversationMetadataLoader(input: {
-    client: CanonClient;
-    conversationCache: Map<string, CanonConversation>;
-    cacheTtlMs?: number;
-}): {
-    refreshConversationCache(force?: boolean): Promise<void>;
-    getConversationMeta(conversationId: string): Promise<CanonConversation | null>;
-};
-export {};

package/dist/host-runtime.js

@@ -1,266 +0,0 @@
-/**
- * Host-runtime helpers, inlined from @canonmsg/core.
- *
- * These helpers glue Canon host wrappers (Codex, Claude Code) to the Canon
- * RTDB session/runtime surface. They used to live in
- * `@canonmsg/core/src/host-runtime/` but were moved into each plugin in
- * media-parity PR C so core does not have to carry host-specific concerns.
- *
- * Keep this file in lockstep with the equivalent file in
- * `packages/codex-plugin/src/host-runtime.ts`. If you change the
- * behavior here, update that copy too and adjust the shared golden
- * fixture test (`packages/claude-code-plugin/src/host-runtime.test.ts`).
- */
-import { buildAgentSessionSnapshot, buildConversationWorktreeSpec, buildBehaviorPolicyLines, buildParticipationHistorySnapshot, buildWorkSessionsPromptLines, mergeWorkSessionContexts, normalizeOptionalString, patchAgentSessionSnapshot, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, rtdbRead, rtdbWrite, } from '@canonmsg/core';
-export const HOST_ADMISSION_ACTION_CAPABILITIES = Object.freeze({
-    canStartDirectConversation: false,
-    canSendContactRequest: false,
-    canApprovePendingContactRequests: false,
-    canRejectPendingContactRequests: false,
-});
-export function buildCanonHostPrompt(input) {
-    const resolvedWorkSessions = mergeWorkSessionContexts(input.workSession, input.workSessions);
-    return [
-        `You are connected to Canon messaging through a ${input.hostLabel} host wrapper.`,
-        'Only the last assistant message from this turn will be delivered as the permanent Canon reply.',
-        'Short intermediate assistant messages may be shown as ephemeral status while you work.',
-        ...input.buildInboundContextLines(input.participantContext),
-        ...buildBehaviorPolicyLines(input.behavior),
-        ...buildWorkSessionsPromptLines(resolvedWorkSessions),
-        'Canon participants may be humans or AI agents.',
-        'Honor the Canon behavior policy above when deciding how proactively to participate.',
-        ...(resolvedWorkSessions.length > 0
-            ? ['Honor the Canon work-session context above within its stated disclosure limits.']
-            : []),
-        `Conversation ID: ${input.conversationId}`,
-        '',
-        'New Canon message:',
-        input.content,
-    ].join('\n');
-}
-/**
- * Render the **text portion** of an inbound Canon message. Images and other
- * binary attachments are referenced by short placeholders — their actual
- * bytes are delivered to the host as native vision/media inputs (Anthropic
- * image blocks, Codex `-i` file args). URLs are intentionally *not* inlined,
- * since the harness never needs to refetch and earlier `[Image: <url>]`
- * inlining caused vision models to see a string about an image instead of
- * the image itself.
- *
- * `materialized` may be passed so non-image attachments can reference a
- * local path the agent can Read. Without it we fall back to an unadorned
- * placeholder; the vision path still works because image blocks carry the
- * bytes directly.
- */
-export function renderCanonHostInboundContent(message, materialized) {
-    const body = message.text || '';
-    const placeholders = [];
-    const attachments = message.attachments ?? [];
-    for (let i = 0; i < attachments.length; i += 1) {
-        const att = attachments[i];
-        const mat = materialized?.find((m) => m.index === i) ?? null;
-        placeholders.push(describeAttachment(att, mat));
-    }
-    if (message.contentType === 'contact_card' && message.contactCard) {
-        placeholders.push(describeContactCard(message.contactCard));
-    }
-    const rendered = [...placeholders, body].filter(Boolean).join('\n');
-    return rendered || '[Empty message]';
-}
-function describeContactCard(card) {
-    const parts = [`${card.userType} · userId: ${card.userId}`];
-    if (card.accessLevel)
-        parts.push(`access: ${card.accessLevel}`);
-    if (card.ownerName)
-        parts.push(`owner: ${card.ownerName}`);
-    if (card.about)
-        parts.push(`about: ${card.about}`);
-    const identity = `📇 Contact card: "${card.displayName}" (${parts.join(' · ')}).`;
-    const missingCapabilities = [
-        !HOST_ADMISSION_ACTION_CAPABILITIES.canStartDirectConversation
-            ? 'start a direct conversation'
-            : null,
-        !HOST_ADMISSION_ACTION_CAPABILITIES.canSendContactRequest
-            ? 'send a contact request'
-            : null,
-        !HOST_ADMISSION_ACTION_CAPABILITIES.canApprovePendingContactRequests
-            ? 'approve pending requests'
-            : null,
-        !HOST_ADMISSION_ACTION_CAPABILITIES.canRejectPendingContactRequests
-            ? '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}.`;
-    return `${identity}\n${hint}`;
-}
-function describeAttachment(attachment, materialized) {
-    if (attachment.kind === 'image') {
-        return '[Image attached]';
-    }
-    if (attachment.kind === 'audio') {
-        const durationMs = materialized?.durationMs ?? attachment.durationMs;
-        const duration = durationMs ? ` (${Math.round(durationMs / 1000)}s)` : '';
-        const ref = materialized?.path ? ` ${materialized.path}` : '';
-        return `[Voice message${duration}${ref}]`;
-    }
-    // file
-    const label = materialized?.fileName ?? attachment.fileName ?? 'File';
-    const ref = materialized?.path ? ` ${materialized.path}` : '';
-    return `[File: ${label}${ref}]`;
-}
-export function buildHydratedInboundContext(input) {
-    const history = buildParticipationHistorySnapshot(input.page?.messages ?? [], input.agentId);
-    return {
-        participantContext: {
-            conversationType: input.conversation?.type ?? 'unknown',
-            memberCount: input.conversation?.memberIds?.length ?? null,
-            senderType: input.message.senderType ?? 'human',
-            senderName: input.senderName,
-            isOwner: input.isOwner,
-            mentionedAgent: Array.isArray(input.message.mentions) && input.message.mentions.includes(input.agentId),
-            recentSenderTypes: history.recentSenderTypes,
-            recentHumanCount: history.recentHumanCount,
-            recentAgentCount: history.recentAgentCount,
-            consecutiveAgentTurns: history.consecutiveAgentTurns,
-            currentAgentStreakStartedByHuman: history.currentAgentStreakStartedByHuman,
-        },
-        behavior: input.page?.behavior ?? input.conversation?.behavior,
-        workSessions: input.page?.workSessions ?? [],
-        hydratedFromPage: input.page != null,
-    };
-}
-export async function publishHostAgentRuntime(agentId, clientType, runtime) {
-    await rtdbWrite(`/agent-runtime/${agentId}`, {
-        clientType,
-        hostMode: true,
-        ...runtime,
-        updatedAt: { '.sv': 'timestamp' },
-    });
-}
-export async function publishHostSessionSnapshots(input) {
-    if (input.conversationIds.length === 0) {
-        return;
-    }
-    await Promise.all(input.conversationIds.map(async (conversationId) => {
-        const persistedConfig = await loadHostSessionConfig({
-            conversationId,
-            agentId: input.agentId,
-            extraStringFields: ['permissionMode', 'effort'],
-        });
-        const liveConfig = input.liveSessionConfigByConversation?.get(conversationId) ?? null;
-        const mergedConfig = {
-            ...(persistedConfig ?? {}),
-            ...(liveConfig ?? {}),
-        };
-        const snapshot = buildAgentSessionSnapshot({
-            conversationId,
-            agentId: input.agentId,
-            runtime: {
-                ...input.runtime,
-                clientType: input.clientType,
-                hostMode: true,
-            },
-            sessionConfig: {
-                ...(mergedConfig.model ? { model: mergedConfig.model } : {}),
-                ...(mergedConfig.permissionMode ? { permissionMode: mergedConfig.permissionMode } : {}),
-                ...(mergedConfig.effort ? { effort: mergedConfig.effort } : {}),
-                ...(mergedConfig.runtimeControlValues
-                    ? { runtimeControlValues: mergedConfig.runtimeControlValues }
-                    : {}),
-                ...(mergedConfig.workspaceId ? { workspaceId: mergedConfig.workspaceId } : {}),
-                ...(mergedConfig.executionMode ? { executionMode: mergedConfig.executionMode } : {}),
-            },
-            lastHeartbeatAt: undefined,
-        });
-        let executionBranch = liveConfig?.executionBranch ?? null;
-        if (!executionBranch && snapshot.executionMode === 'worktree' && snapshot.workspaceId) {
-            const workspace = input.workspaceOptions.find((option) => option.id === snapshot.workspaceId);
-            if (workspace) {
-                executionBranch = buildConversationWorktreeSpec({
-                    agentId: input.agentId,
-                    conversationId,
-                    workspaceCwd: workspace.cwd,
-                }).branch;
-            }
-        }
-        return patchAgentSessionSnapshot(conversationId, input.agentId, {
-            clientType: input.clientType,
-            hostMode: true,
-            model: snapshot.model ?? null,
-            permissionMode: snapshot.permissionMode ?? null,
-            effort: snapshot.effort ?? null,
-            runtimeControlValues: snapshot.runtimeControlValues ?? null,
-            workspaceId: snapshot.workspaceId ?? null,
-            executionMode: snapshot.executionMode ?? null,
-            executionBranch,
-            modelOptions: snapshot.modelOptions,
-            permissionModeOptions: snapshot.permissionModeOptions,
-            workspaceOptions: snapshot.workspaceOptions,
-            availableExecutionModes: snapshot.availableExecutionModes,
-            lastHeartbeatAt: { '.sv': 'timestamp' },
-        });
-    }));
-}
-export function readHostSessionConfig(raw, extraStringFields = []) {
-    const baseConfig = readSessionWorkspaceConfig(raw);
-    if (!raw || typeof raw !== 'object') {
-        return baseConfig;
-    }
-    const data = raw;
-    const extraConfig = Object.fromEntries(extraStringFields.flatMap((field) => {
-        const value = normalizeOptionalString(data[field]);
-        return value ? [[field, value]] : [];
-    }));
-    const runtimeControlValues = Object.fromEntries(Object.entries(data.runtimeControlValues && typeof data.runtimeControlValues === 'object'
-        ? data.runtimeControlValues
-        : {}).flatMap(([key, value]) => {
-        const normalizedValue = normalizeOptionalString(value);
-        return normalizedValue ? [[key, normalizedValue]] : [];
-    }));
-    return {
-        ...(baseConfig ?? {}),
-        ...extraConfig,
-        ...(Object.keys(runtimeControlValues).length > 0 ? { runtimeControlValues } : {}),
-    };
-}
-export async function loadHostSessionConfig(input) {
-    const raw = await rtdbRead(`/session-config/${input.conversationId}/${input.agentId}`);
-    return readHostSessionConfig(raw, input.extraStringFields);
-}
-export function resolveHostWorkspaceCwd(input) {
-    return resolveConfiguredWorkspaceCwd(input);
-}
-export function createConversationMetadataLoader(input) {
-    const cacheTtlMs = input.cacheTtlMs ?? 10_000;
-    let conversationCacheLoadedAt = 0;
-    async function refreshConversationCache(force = false) {
-        if (!force
-            && input.conversationCache.size > 0
-            && Date.now() - conversationCacheLoadedAt < cacheTtlMs) {
-            return;
-        }
-        const conversations = await input.client.getConversations();
-        input.conversationCache.clear();
-        for (const conversation of conversations) {
-            input.conversationCache.set(conversation.id, conversation);
-        }
-        conversationCacheLoadedAt = Date.now();
-    }
-    async function getConversationMeta(conversationId) {
-        try {
-            await refreshConversationCache();
-            const cached = input.conversationCache.get(conversationId);
-            if (cached)
-                return cached;
-            await refreshConversationCache(true);
-            return input.conversationCache.get(conversationId) ?? null;
-        }
-        catch {
-            return input.conversationCache.get(conversationId) ?? null;
-        }
-    }
-    return {
-        refreshConversationCache,
-        getConversationMeta,
-    };
-}