@canonmsg/core 0.12.0 → 0.14.0

package/dist/agent-profiles.d.ts

@@ -2,20 +2,49 @@
  * Shared agent profile management — loading, locking, and resolution.
  * Used by both host.ts and server.ts.
  */
+import type { AgentClientType } from './types.js';
 export interface AgentProfile {
     apiKey: string;
     agentId: string;
     agentName: string;
     registeredAt: string;
+    clientType?: AgentClientType;
+    baseUrl?: string;
+    streamUrl?: string;
+    rtdbUrl?: string;
+    runtimeId?: string;
+}
+export interface ProfileLockHandle {
+    profile: string;
+    pid: number;
+    token: string;
+    release(): void;
 }
 export declare const CANON_DIR: string;
 export declare const AGENTS_PATH: string;
 export declare const LOCKS_DIR: string;
+export declare const PENDING_REGISTRATIONS_PATH: string;
 export declare function loadProfiles(): Record<string, AgentProfile>;
+export declare function saveProfiles(profiles: Record<string, AgentProfile>): void;
+export declare function upsertAgentProfile(name: string, profile: AgentProfile): Record<string, AgentProfile>;
 export declare function isProcessAlive(pid: number): boolean;
 export declare function isProfileLocked(profile: string): {
     locked: boolean;
     pid?: number;
 };
-export declare function acquireLock(profile: string): void;
-export declare function releaseLock(profile: string): void;
+export declare function acquireLock(profile: string): ProfileLockHandle;
+export declare function releaseLock(profile: string, token?: string): void;
+export interface PendingRegistration {
+    profile: string;
+    clientType?: AgentClientType;
+    localRegistrationId: string;
+    requestId?: string;
+    pollToken?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export declare function loadPendingRegistrations(): Record<string, PendingRegistration>;
+export declare function savePendingRegistrations(pending: Record<string, PendingRegistration>): void;
+export declare function getOrCreatePendingRegistration(profile: string, clientType?: AgentClientType): PendingRegistration;
+export declare function updatePendingRegistration(profile: string, patch: Partial<Pick<PendingRegistration, 'requestId' | 'pollToken' | 'clientType'>>): PendingRegistration;
+export declare function clearPendingRegistration(profile: string): void;

package/dist/agent-profiles.js

@@ -2,13 +2,18 @@
  * Shared agent profile management — loading, locking, and resolution.
  * Used by both host.ts and server.ts.
  */
-import { readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, renameSync, writeFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { closeSync, openSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 // ── Paths ────────────────────────────────────────────────────────────
-export const CANON_DIR = join(homedir(), '.canon');
+export const CANON_DIR = process.env.CANON_HOME
+    ? resolve(process.env.CANON_HOME)
+    : join(homedir(), '.canon');
 export const AGENTS_PATH = join(CANON_DIR, 'agents.json');
 export const LOCKS_DIR = join(CANON_DIR, 'locks');
+export const PENDING_REGISTRATIONS_PATH = join(CANON_DIR, 'pending-registrations.json');
 // ── Profile loading ──────────────────────────────────────────────────
 export function loadProfiles() {
     try {
@@ -18,6 +23,24 @@ export function loadProfiles() {
         return {};
     }
 }
+function writeJsonFile(path, value, mode = 0o600) {
+    mkdirSync(CANON_DIR, { recursive: true });
+    const tmpPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmpPath, JSON.stringify(value, null, 2), { mode });
+    renameSync(tmpPath, path);
+}
+export function saveProfiles(profiles) {
+    writeJsonFile(AGENTS_PATH, profiles, 0o600);
+}
+export function upsertAgentProfile(name, profile) {
+    const profileName = name.trim();
+    if (!profileName)
+        throw new Error('Profile name is required');
+    const profiles = loadProfiles();
+    profiles[profileName] = profile;
+    saveProfiles(profiles);
+    return profiles;
+}
 // ── Process locking ──────────────────────────────────────────────────
 export function isProcessAlive(pid) {
     try {
@@ -31,8 +54,9 @@ export function isProcessAlive(pid) {
 export function isProfileLocked(profile) {
     const lockPath = join(LOCKS_DIR, `${profile}.lock`);
     try {
-        const pid = parseInt(readFileSync(lockPath, 'utf-8').trim());
-        if (isProcessAlive(pid))
+        const lock = parseLock(readFileSync(lockPath, 'utf-8'));
+        const pid = lock?.pid;
+        if (pid && isProcessAlive(pid))
             return { locked: true, pid };
         // Stale lock — clean it up
         try {
@@ -45,19 +69,130 @@ export function isProfileLocked(profile) {
     }
     return { locked: false };
 }
+function parseLock(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    const legacyPid = Number.parseInt(trimmed, 10);
+    if (Number.isFinite(legacyPid) && String(legacyPid) === trimmed) {
+        return { pid: legacyPid };
+    }
+    try {
+        const data = JSON.parse(trimmed);
+        return typeof data.pid === 'number'
+            ? { pid: data.pid, token: typeof data.token === 'string' ? data.token : undefined }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function acquireLock(profile) {
     mkdirSync(LOCKS_DIR, { recursive: true });
     const lockPath = join(LOCKS_DIR, `${profile}.lock`);
-    const check = isProfileLocked(profile);
-    if (check.locked) {
-        throw new Error(`Agent "${profile}" is in use by another session (PID ${check.pid})`);
+    const token = randomUUID();
+    const payload = JSON.stringify({
+        pid: process.pid,
+        token,
+        acquiredAt: new Date().toISOString(),
+    });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const fd = openSync(lockPath, 'wx', 0o600);
+            try {
+                writeFileSync(fd, payload);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return {
+                profile,
+                pid: process.pid,
+                token,
+                release: () => releaseLock(profile, token),
+            };
+        }
+        catch (error) {
+            if (error?.code !== 'EEXIST')
+                throw error;
+            const check = isProfileLocked(profile);
+            if (check.locked) {
+                throw new Error(`Agent "${profile}" is in use by another session (PID ${check.pid})`);
+            }
+        }
     }
-    writeFileSync(lockPath, String(process.pid));
+    throw new Error(`Agent "${profile}" lock could not be acquired`);
 }
-export function releaseLock(profile) {
+export function releaseLock(profile, token) {
     const lockPath = join(LOCKS_DIR, `${profile}.lock`);
+    if (token) {
+        try {
+            const lock = parseLock(readFileSync(lockPath, 'utf-8'));
+            if (lock?.token && lock.token !== token)
+                return;
+        }
+        catch {
+            return;
+        }
+    }
     try {
         unlinkSync(lockPath);
     }
     catch { }
 }
+export function loadPendingRegistrations() {
+    try {
+        return JSON.parse(readFileSync(PENDING_REGISTRATIONS_PATH, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function savePendingRegistrations(pending) {
+    writeJsonFile(PENDING_REGISTRATIONS_PATH, pending, 0o600);
+}
+export function getOrCreatePendingRegistration(profile, clientType) {
+    const now = new Date().toISOString();
+    const pending = loadPendingRegistrations();
+    const existing = pending[profile];
+    if (existing) {
+        const next = { ...existing, clientType, updatedAt: now };
+        pending[profile] = next;
+        savePendingRegistrations(pending);
+        return next;
+    }
+    const created = {
+        profile,
+        clientType,
+        localRegistrationId: randomUUID(),
+        createdAt: now,
+        updatedAt: now,
+    };
+    pending[profile] = created;
+    savePendingRegistrations(pending);
+    return created;
+}
+export function updatePendingRegistration(profile, patch) {
+    const pending = loadPendingRegistrations();
+    const existing = pending[profile] ?? {
+        profile,
+        localRegistrationId: randomUUID(),
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+    };
+    const next = {
+        ...existing,
+        ...patch,
+        updatedAt: new Date().toISOString(),
+    };
+    pending[profile] = next;
+    savePendingRegistrations(pending);
+    return next;
+}
+export function clearPendingRegistration(profile) {
+    const pending = loadPendingRegistrations();
+    if (pending[profile]) {
+        delete pending[profile];
+        savePendingRegistrations(pending);
+    }
+}

package/dist/agent-resolver.d.ts

@@ -10,16 +10,26 @@
  * 2. CANON_AGENT env var (named profile with lock)
  * 3. Auto-select from profiles (first unlocked, with lock)
  */
+import { type ProfileLockHandle } from './agent-profiles.js';
+import type { AgentClientType } from './types.js';
 export interface ResolvedAgent {
     apiKey: string;
     agentId?: string;
     profile: string | null;
+    agentName?: string;
+    clientType?: AgentClientType;
+    baseUrl?: string;
+    streamUrl?: string;
+    rtdbUrl?: string;
+    lockHandle?: ProfileLockHandle;
 }
 /** Get the currently locked profile name (for cleanup on shutdown). */
 export declare function getActiveProfile(): string | null;
+export declare function getActiveProfileLock(): ProfileLockHandle | null;
 export declare function resolveCanonProfile(name: string, opts?: {
     logPrefix?: string;
     lock?: boolean;
+    expectedClientType?: AgentClientType;
 }): ResolvedAgent;
 /**
  * Resolve Canon agent credentials.
@@ -30,4 +40,6 @@ export declare function resolveCanonProfile(name: string, opts?: {
  */
 export declare function resolveCanonAgent(opts?: {
     logPrefix?: string;
+    expectedClientType?: AgentClientType;
+    lock?: boolean;
 }): ResolvedAgent;

package/dist/agent-resolver.js

@@ -12,10 +12,17 @@
  */
 import { loadProfiles, isProfileLocked, acquireLock, } from './agent-profiles.js';
 let activeResolvedProfile = null;
+let activeLockHandle = null;
 /** Get the currently locked profile name (for cleanup on shutdown). */
 export function getActiveProfile() {
     return activeResolvedProfile;
 }
+export function getActiveProfileLock() {
+    return activeLockHandle;
+}
+function profileMatches(profile, expectedClientType) {
+    return !expectedClientType || !profile.clientType || profile.clientType === expectedClientType;
+}
 export function resolveCanonProfile(name, opts) {
     const prefix = opts?.logPrefix ?? '[canon]';
     const profileName = name.trim();
@@ -27,13 +34,25 @@ export function resolveCanonProfile(name, opts) {
     if (!profile) {
         throw new Error(`${prefix} Profile "${profileName}" not found in ~/.canon/agents.json`);
     }
+    if (!profileMatches(profile, opts?.expectedClientType)) {
+        throw new Error(`${prefix} Profile "${profileName}" is registered for ${profile.clientType}, not ${opts?.expectedClientType}`);
+    }
+    let lockHandle;
     if (opts?.lock) {
-        acquireLock(profileName);
+        lockHandle = acquireLock(profileName);
+        activeResolvedProfile = profileName;
+        activeLockHandle = lockHandle;
     }
     return {
         apiKey: profile.apiKey,
         agentId: profile.agentId,
+        agentName: profile.agentName,
+        clientType: profile.clientType,
+        baseUrl: profile.baseUrl,
+        streamUrl: profile.streamUrl,
+        rtdbUrl: profile.rtdbUrl,
         profile: profileName,
+        lockHandle,
     };
 }
 /**
@@ -45,6 +64,7 @@ export function resolveCanonProfile(name, opts) {
  */
 export function resolveCanonAgent(opts) {
     const prefix = opts?.logPrefix ?? '[canon]';
+    const shouldLock = opts?.lock ?? true;
     // 1. Explicit API key (highest priority, no lock)
     // CANON_API_KEY is set by the host wrapper or user environment.
     // CANON_PLUGIN_API_KEY is set by plugin.json from user_config.
@@ -58,34 +78,30 @@ export function resolveCanonAgent(opts) {
     if (process.env.CANON_AGENT) {
         const resolved = resolveCanonProfile(process.env.CANON_AGENT, {
             logPrefix: prefix,
-            lock: true,
+            lock: shouldLock,
+            expectedClientType: opts?.expectedClientType,
         });
-        activeResolvedProfile = resolved.profile;
         return resolved;
     }
     // 3. Auto-select from profiles
     if (names.length === 0) {
-        throw new Error(`${prefix} No agents registered. Run canon-register first.`);
+        throw new Error(`${prefix} No agents registered. Run a runtime register command first.`);
+    }
+    const viableNames = names.filter((name) => profileMatches(profiles[name], opts?.expectedClientType));
+    if (viableNames.length === 0) {
+        throw new Error(`${prefix} No ${opts?.expectedClientType ?? 'matching'} profiles found in ~/.canon/agents.json.`);
     }
-    if (names.length === 1) {
-        const resolved = resolveCanonProfile(names[0], {
+    if (viableNames.length === 1) {
+        const resolved = resolveCanonProfile(viableNames[0], {
             logPrefix: prefix,
-            lock: true,
+            lock: shouldLock,
+            expectedClientType: opts?.expectedClientType,
         });
-        activeResolvedProfile = resolved.profile;
         return resolved;
     }
-    // Multiple agents — pick first unlocked
-    for (const name of names) {
-        if (!isProfileLocked(name).locked) {
-            const resolved = resolveCanonProfile(name, {
-                logPrefix: prefix,
-                lock: true,
-            });
-            activeResolvedProfile = resolved.profile;
-            console.error(`${prefix} Auto-selected agent "${name}" (${profiles[name].agentName})`);
-            return resolved;
-        }
+    const unlocked = viableNames.filter((name) => !isProfileLocked(name).locked);
+    if (unlocked.length === 0) {
+        throw new Error(`${prefix} All matching agents are in use by other sessions. Run canon-necromance list to inspect them.`);
     }
-    throw new Error(`${prefix} All agents are in use by other sessions.`);
+    throw new Error(`${prefix} Multiple profiles are available (${unlocked.join(', ')}). Set CANON_AGENT=<profile> or use canon-necromance revive <profile>.`);
 }

package/dist/browser.d.ts

@@ -7,6 +7,7 @@ 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';
 export { buildWorkSessionPromptLines, buildWorkSessionsPromptLines, mergeWorkSessionContexts, } from './work-session.js';
 export { buildAgentSessionSnapshot } from './agent-session.js';
+export { CLAUDE_EFFORT_OPTIONS, EXECUTION_MODE_CONTROL_OPTIONS, buildFirstPartyCodingRuntimeDescriptor, buildRuntimeEffortControl, buildRuntimeExecutionModeControl, buildRuntimeExecutionModeOptions, buildRuntimeModelControl, buildRuntimePermissionModeControl, buildRuntimeWorkspaceControl, buildRuntimeWorkspaceControlOptions, } from './runtime-descriptor.js';
 export type { AgentBehaviorSettings, ParticipationHistoryMessage, ParticipationHistorySnapshot, ParticipationStyle, ResolvedAgentBehaviorPolicy, } from './policy.js';
 export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
 export { DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';

package/dist/browser.js

@@ -4,6 +4,7 @@ export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_AP
 export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, } from './execution-environment-mode.js';
 export { buildWorkSessionPromptLines, buildWorkSessionsPromptLines, mergeWorkSessionContexts, } from './work-session.js';
 export { buildAgentSessionSnapshot } from './agent-session.js';
+export { CLAUDE_EFFORT_OPTIONS, EXECUTION_MODE_CONTROL_OPTIONS, buildFirstPartyCodingRuntimeDescriptor, buildRuntimeEffortControl, buildRuntimeExecutionModeControl, buildRuntimeExecutionModeOptions, buildRuntimeModelControl, buildRuntimePermissionModeControl, buildRuntimeWorkspaceControl, buildRuntimeWorkspaceControlOptions, } from './runtime-descriptor.js';
 export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
 export { DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 export { buildApprovalReply, buildApprovalRequest, buildApprovalOutcome, generateApprovalId, parseTextApprovalReply, redactSecrets, } from './approval-format.js';

package/dist/client.d.ts

@@ -16,6 +16,9 @@ export declare class CanonClient {
         agentId: string;
     }>;
     getAgentMe(): Promise<AgentContext>;
+    rotateAgentKey(): Promise<{
+        apiKey: string;
+    }>;
     getConversations(): Promise<CanonConversation[]>;
     getMessages(conversationId: string, limit?: number, before?: string): Promise<CanonMessage[]>;
     getMessagesPage(conversationId: string, limit?: number, before?: string): Promise<CanonMessagesPage>;
@@ -61,10 +64,13 @@ export declare class CanonClient {
         avatarUrl?: string;
         clientType?: string;
         requestedAgentId?: string;
+        localRegistrationId?: string;
     }): Promise<{
         requestId: string;
+        pollToken?: string;
     }>;
-    static checkStatus(baseUrl: string | undefined, requestId: string): Promise<RegistrationStatus>;
+    static checkStatus(baseUrl: string | undefined, requestId: string, pollToken?: string): Promise<RegistrationStatus>;
+    static ackRegistrationStatus(baseUrl: string | undefined, requestId: string, pollToken?: string): Promise<void>;
 }
 export declare class CanonApiError extends Error {
     status: number;

package/dist/client.js

@@ -34,6 +34,15 @@ export class CanonClient {
             throw new CanonApiError(res.status, await res.text());
         return res.json();
     }
+    async rotateAgentKey() {
+        const res = await fetch(`${this.baseUrl}/agents/keys/rotate`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        return res.json();
+    }
     async getConversations() {
         const res = await fetch(`${this.baseUrl}/conversations`, {
             headers: this.authHeaders(),
@@ -360,13 +369,27 @@ export class CanonClient {
             throw new CanonApiError(res.status, await res.text());
         return res.json();
     }
-    static async checkStatus(baseUrl, requestId) {
+    static async checkStatus(baseUrl, requestId, pollToken) {
         const url = baseUrl || DEFAULT_BASE_URL;
-        const res = await fetch(`${url}/agents/status/${requestId}`);
+        const res = await fetch(`${url}/agents/status/${requestId}`, {
+            headers: pollToken ? { 'x-canon-poll-token': pollToken } : undefined,
+        });
         if (!res.ok)
             throw new CanonApiError(res.status, await res.text());
         return res.json();
     }
+    static async ackRegistrationStatus(baseUrl, requestId, pollToken) {
+        const url = baseUrl || DEFAULT_BASE_URL;
+        const res = await fetch(`${url}/agents/status/${requestId}/ack`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                ...(pollToken ? { 'x-canon-poll-token': pollToken } : {}),
+            },
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+    }
 }
 export class CanonApiError extends Error {
     status;

package/dist/host-runtime.d.ts

@@ -0,0 +1,118 @@
+import { type AgentClientType, type AgentRuntime, type CanonConversation, type CanonMessage, type CanonMessagesPage, type MessageCreatedPayload } from './types.js';
+import { type CanonClient } from './client.js';
+import { type SessionWorkspaceConfig } from './execution-environment.js';
+import { type ResolvedAgentBehaviorPolicy } from './policy.js';
+interface HostWorkspaceResolverOption {
+    id: string;
+    cwd: string;
+}
+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'];
+};
+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 are
+ * referenced by short placeholders — their actual bytes are delivered to the
+ * host as native vision/media inputs (Codex `-i <file>`, Anthropic image
+ * blocks). 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 args carry the
+ * file path 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;
+    extraSessionConfigFields?: readonly 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 {};