@canonmsg/core 0.13.0 → 0.15.0

package/dist/agent-session.js

@@ -1,4 +1,21 @@
 import { mergeWorkSessionContexts, } from './work-session.js';
+function listDescriptorControls(runtime) {
+    const descriptor = runtime?.runtimeDescriptor;
+    return [
+        ...(descriptor?.coreControls ?? []),
+        ...(descriptor?.runtimeControls ?? []),
+    ];
+}
+function descriptorOptions(runtime, controlId) {
+    return [...(listDescriptorControls(runtime)
+            .find((control) => control.id === controlId)
+            ?.options ?? [])];
+}
+function descriptorDefaultValue(runtime, controlId) {
+    const control = listDescriptorControls(runtime)
+        .find((candidate) => candidate.id === controlId);
+    return control?.defaultValue ?? control?.options?.[0]?.value ?? undefined;
+}
 function buildWorkSessionSummary(workSession, workSessions) {
     const merged = mergeWorkSessionContexts(workSession, workSessions);
     const primary = merged[0];
@@ -14,13 +31,12 @@ function buildWorkSessionSummary(workSession, workSessions) {
     };
 }
 export function buildAgentSessionSnapshot(input) {
-    const modelOptions = input.sessionState?.availableModels
-        ?? input.sessionConfig?.availableModels
-        ?? input.runtime?.availableModels
-        ?? [];
-    const workspaceOptions = input.sessionConfig?.workspaceOptions
-        ?? input.runtime?.availableWorkspaces
-        ?? [];
+    const modelOptions = descriptorOptions(input.runtime, 'model');
+    const workspaceOptions = descriptorOptions(input.runtime, 'workspace')
+        .map((option) => ({ id: option.value, label: option.label }));
+    const availableExecutionModes = descriptorOptions(input.runtime, 'executionMode')
+        .map((option) => option.value)
+        .filter((value) => value === 'worktree' || value === 'locked');
     return {
         conversationId: input.conversationId,
         agentId: input.agentId,
@@ -32,36 +48,30 @@ export function buildAgentSessionSnapshot(input) {
             ?? input.runtime?.hostMode),
         model: input.sessionState?.model
             ?? input.sessionConfig?.model
-            ?? input.runtime?.defaultModel
-            ?? modelOptions[0]?.value,
+            ?? descriptorDefaultValue(input.runtime, 'model'),
         modelOptions,
         permissionMode: input.sessionState?.permissionMode
             ?? input.sessionConfig?.permissionMode
-            ?? input.runtime?.defaultPermissionMode,
-        permissionModeOptions: input.runtime?.availablePermissionModes ?? [],
+            ?? descriptorDefaultValue(input.runtime, 'permissionMode'),
+        permissionModeOptions: descriptorOptions(input.runtime, 'permissionMode'),
         effort: input.sessionState?.effort ?? input.sessionConfig?.effort,
         runtimeControlValues: input.sessionState?.runtimeControlValues
             ?? input.sessionConfig?.runtimeControlValues,
         workspaceId: input.sessionConfig?.workspaceId
-            ?? input.runtime?.defaultWorkspaceId
-            ?? workspaceOptions[0]?.id,
+            ?? descriptorDefaultValue(input.runtime, 'workspace'),
         workspaceOptions,
         executionMode: input.sessionState?.executionMode
             ?? input.sessionConfig?.executionMode,
-        availableExecutionModes: input.sessionConfig?.availableExecutionModes
-            ?? input.runtime?.availableExecutionModes
-            ?? [],
+        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',
+        waitingForInput: input.turnState?.state === 'waiting_input',
         contextUsage: input.sessionState?.contextUsage,
         lastError: input.sessionState?.lastError,
         lastHeartbeatAt: input.lastHeartbeatAt

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/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 {};

package/dist/host-runtime.js

@@ -0,0 +1,256 @@
+import { buildAgentSessionSnapshot } from './agent-session.js';
+import { buildConversationWorktreeSpec, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, } from './execution-environment.js';
+import { buildBehaviorPolicyLines, buildParticipationHistorySnapshot, } from './policy.js';
+import { buildWorkSessionsPromptLines, mergeWorkSessionContexts, } from './work-session.js';
+import { rtdbRead } from './rtdb-rest.js';
+import { createRuntimeStatePublisher } from './runtime-state-publisher.js';
+const HOST_INBOUND_CONTACT_CARD_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 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 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.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_INBOUND_CONTACT_CARD_ACTION_CAPABILITIES.canStartDirectConversation
+            ? 'start a direct conversation'
+            : null,
+        !HOST_INBOUND_CONTACT_CARD_ACTION_CAPABILITIES.canSendContactRequest
+            ? 'send a contact request'
+            : null,
+        !HOST_INBOUND_CONTACT_CARD_ACTION_CAPABILITIES.canApprovePendingContactRequests
+            ? 'approve pending requests'
+            : null,
+        !HOST_INBOUND_CONTACT_CARD_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 createRuntimeStatePublisher({ agentId, clientType, hostMode: true })
+        .publishAgentRuntime(runtime);
+}
+export async function publishHostSessionSnapshots(input) {
+    if (input.conversationIds.length === 0) {
+        return;
+    }
+    const publisher = createRuntimeStatePublisher({
+        agentId: input.agentId,
+        clientType: input.clientType,
+        hostMode: true,
+    });
+    await Promise.all(input.conversationIds.map(async (conversationId) => {
+        const persistedConfig = await loadHostSessionConfig({
+            conversationId,
+            agentId: input.agentId,
+            extraStringFields: input.extraSessionConfigFields ?? ['permissionMode'],
+        });
+        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 publisher.patchAgentSessionSnapshot(conversationId, {
+            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,
+    };
+}

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, bu
 export type { ConfiguredWorkspaceRoot, WorkspaceDiscoveryResult, } from './workspace-discovery.js';
 export { CanonClient, CanonApiError } from './client.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 { CanonStream } from './stream.js';
 export type { StreamHandler } from './stream.js';
 export type { PolicyRole, ParticipationStyle, RepresentationMode, PermissionLevel, ConversationScope, AgentBehaviorSettings, Participant, Relationship, ContextOverlay, BehaviorProfile, AdmissionPolicy, RuntimeControlPolicy, ActionApprovalPolicy, ParticipationPolicy, WorkSession, ResolvedPolicy, ResolvedTurnEligibility, ResolvedAgentBehaviorPolicy, ParticipationHistoryMessage, ParticipationHistorySnapshot, ParticipationDecisionInput, ParticipationDecision, } from './policy.js';
@@ -30,7 +31,11 @@ export type { LocalRuntimeCatalogEntry, LocalRuntimeKind, LocalRuntimeReviveCapa
 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, patchRuntimeInfo, writeRuntimeInfo, clearRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
-export type { AgentSessionSnapshotPatch, RuntimeInfoPayloadData, SessionStatePayload, TurnStatePayload, } from './rtdb-rest.js';
+export type { AgentSessionSnapshotPatch, RTDBClientHandle, RuntimeInfoPayloadData, SessionStatePayload, TurnStatePayload, } from './rtdb-rest.js';
+export { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, publishHostSessionSnapshots, readHostSessionConfig, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
+export type { HostInboundParticipantContext, } from './host-runtime.js';
+export { createRuntimeStatePublisher, } from './runtime-state-publisher.js';
+export type { RuntimeStatePublisher, RuntimeStatePublisherOptions, RuntimeStreamingPayload, } from './runtime-state-publisher.js';
 export { formatCanonMessageAsText } from './message-format.js';
 export { 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

@@ -5,6 +5,7 @@ export { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, bu
 // Client
 export { CanonClient, CanonApiError } from './client.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';
 // Stream
 export { CanonStream } from './stream.js';
 export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
@@ -29,6 +30,9 @@ export { RUNTIMES_DIR, buildLocalRuntimeId, clearRuntimeSessionState, describePr
 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, patchRuntimeInfo, writeRuntimeInfo, clearRuntimeInfo, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
+// Runtime host plumbing
+export { buildCanonHostPrompt, buildHydratedInboundContext, createConversationMetadataLoader, loadHostSessionConfig, publishHostAgentRuntime, publishHostSessionSnapshots, readHostSessionConfig, renderCanonHostInboundContent, resolveHostWorkspaceCwd, } from './host-runtime.js';
+export { createRuntimeStatePublisher, } from './runtime-state-publisher.js';
 // Message formatting (LLM-facing text projection)
 export { formatCanonMessageAsText } from './message-format.js';
 // Constants

package/dist/rtdb-rest.d.ts

@@ -22,16 +22,11 @@ export interface SessionStatePayload {
     hostMode?: boolean;
     clientType?: string;
     isActive: boolean;
-    state?: 'idle' | 'running' | 'requires_action';
     contextUsage?: {
         percentage: number;
         totalTokens: number;
         maxTokens: number;
     };
-    availableModels?: Array<{
-        value: string;
-        label: string;
-    }>;
     updatedAt: {
         '.sv': 'timestamp';
     };
@@ -80,7 +75,7 @@ export interface AgentSessionSnapshotPatch {
     resolvedCwd?: string | null;
     worktreePath?: string | null;
     executionFallbackReason?: string | null;
-    state?: 'idle' | 'running' | 'requires_action' | null;
+    state?: null;
     turnState?: TurnLifecycleState | null;
     supportsQueue?: boolean | null;
     queueDepth?: number;
@@ -114,7 +109,7 @@ interface RTDBAuthOptions {
     rtdbUrl?: string;
     firebaseApiKey?: string;
 }
-interface RTDBClientHandle {
+export interface RTDBClientHandle {
     read(path: string): Promise<unknown>;
     write(path: string, data: unknown): Promise<void>;
     patch(path: string, data: unknown): Promise<void>;

package/dist/rtdb-rest.js

@@ -144,7 +144,6 @@ function createRTDBClientHandle(client, options) {
             ...(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 } : {}),
@@ -152,8 +151,8 @@ function createRTDBClientHandle(client, options) {
             ...(state.executionFallbackReason !== undefined
                 ? { executionFallbackReason: state.executionFallbackReason }
                 : {}),
-            ...(state.state !== undefined ? { state: state.state } : {}),
-            waitingForInput: state.state === 'requires_action',
+            state: null,
+            waitingForInput: false,
             ...(state.contextUsage !== undefined ? { contextUsage: state.contextUsage } : {}),
             ...(state.lastError !== undefined ? { lastError: state.lastError } : {}),
             lastHeartbeatAt: { '.sv': 'timestamp' },
@@ -167,7 +166,7 @@ function createRTDBClientHandle(client, options) {
                 updatedAt: { '.sv': 'timestamp' },
             });
             await patch(buildAgentSessionPath(conversationId, agentId), {
-                state: 'idle',
+                state: null,
                 waitingForInput: false,
                 lastError: null,
                 executionBranch: null,

package/dist/runtime-descriptor.d.ts

@@ -0,0 +1,50 @@
+import type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
+import { type AgentClientType, type CanonControlDescriptor, type CanonRuntimeActionDescriptor, type CanonRuntimeDescriptor, type CanonRuntimeStreamingMode, type CanonWorkspaceRootMetadata, type ModelOption, type PermissionModeOption, type WorkspaceOption } from './types.js';
+import type { HostAdmissionActionCapabilities } from './turn-protocol.js';
+export declare const CLAUDE_EFFORT_OPTIONS: readonly [{
+    readonly value: "low";
+    readonly label: "Low";
+}, {
+    readonly value: "medium";
+    readonly label: "Medium";
+}, {
+    readonly value: "high";
+    readonly label: "High";
+}];
+export declare const EXECUTION_MODE_CONTROL_OPTIONS: ReadonlyArray<{
+    value: ExecutionEnvironmentMode;
+    label: string;
+    description: string;
+}>;
+export declare function buildRuntimeWorkspaceControlOptions(workspaces: ReadonlyArray<WorkspaceOption>): ModelOption[];
+export declare function buildRuntimeExecutionModeOptions(modes: ReadonlyArray<ExecutionEnvironmentMode>): ModelOption[];
+export declare function buildRuntimeModelControl(input: {
+    models: ReadonlyArray<ModelOption>;
+    liveBehavior: 'immediate' | 'next_turn';
+    defaultValue?: string | null;
+}): CanonControlDescriptor;
+export declare function buildRuntimeWorkspaceControl(input: {
+    workspaces: ReadonlyArray<WorkspaceOption>;
+    workspaceRoots?: ReadonlyArray<CanonWorkspaceRootMetadata>;
+    label?: string;
+    defaultValue?: string | null;
+}): CanonControlDescriptor;
+export declare function buildRuntimeExecutionModeControl(executionModes: ReadonlyArray<ExecutionEnvironmentMode>): CanonControlDescriptor;
+export declare function buildRuntimePermissionModeControl(input: {
+    clientType: 'claude-code' | 'codex';
+    options: ReadonlyArray<PermissionModeOption>;
+    defaultValue?: string | null;
+}): CanonControlDescriptor;
+export declare function buildRuntimeEffortControl(): CanonControlDescriptor;
+export declare function buildFirstPartyCodingRuntimeDescriptor(input: {
+    clientType: Extract<AgentClientType, 'claude-code' | 'codex'>;
+    models: ReadonlyArray<ModelOption>;
+    workspaces: ReadonlyArray<WorkspaceOption>;
+    workspaceRoots?: ReadonlyArray<CanonWorkspaceRootMetadata>;
+    executionModes: ReadonlyArray<ExecutionEnvironmentMode>;
+    permissionModes?: ReadonlyArray<PermissionModeOption>;
+    defaultPermissionMode?: string | null;
+    actions?: ReadonlyArray<CanonRuntimeActionDescriptor>;
+    streamingTextMode: CanonRuntimeStreamingMode;
+    admissionActions?: HostAdmissionActionCapabilities;
+}): CanonRuntimeDescriptor;

package/dist/runtime-descriptor.js

@@ -0,0 +1,128 @@
+import { CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
+export const CLAUDE_EFFORT_OPTIONS = [
+    { value: 'low', label: 'Low' },
+    { value: 'medium', label: 'Medium' },
+    { value: 'high', label: 'High' },
+];
+export const EXECUTION_MODE_CONTROL_OPTIONS = [
+    {
+        value: 'worktree',
+        label: 'Isolated worktree',
+        description: 'Creates or reuses a per-conversation git worktree under ~/.canon/conversation-worktrees when the selected project is a git repo.',
+    },
+    {
+        value: 'locked',
+        label: 'Use shared project',
+        description: 'Runs directly in the selected project folder. Changes happen there.',
+    },
+];
+export function buildRuntimeWorkspaceControlOptions(workspaces) {
+    return 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 } : {}),
+    }));
+}
+export function buildRuntimeExecutionModeOptions(modes) {
+    return modes.map((mode) => {
+        const option = EXECUTION_MODE_CONTROL_OPTIONS.find((candidate) => candidate.value === mode);
+        return option
+            ? { ...option }
+            : { value: mode, label: mode, description: mode };
+    });
+}
+export function buildRuntimeModelControl(input) {
+    return {
+        id: 'model',
+        label: 'Model',
+        options: input.models,
+        defaultValue: input.defaultValue ?? input.models[0]?.value ?? null,
+        availability: 'setup_and_live',
+        liveBehavior: input.liveBehavior,
+        selectionPolicy: 'inherit',
+    };
+}
+export function buildRuntimeWorkspaceControl(input) {
+    return {
+        id: 'workspace',
+        label: input.label ?? 'Project',
+        options: buildRuntimeWorkspaceControlOptions(input.workspaces),
+        defaultValue: input.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.',
+    };
+}
+export function buildRuntimeExecutionModeControl(executionModes) {
+    return {
+        id: 'executionMode',
+        label: 'Execution mode',
+        options: buildRuntimeExecutionModeOptions(executionModes),
+        defaultValue: null,
+        availability: 'setup',
+        liveBehavior: 'none',
+        selectionPolicy: 'required_explicit',
+    };
+}
+export function buildRuntimePermissionModeControl(input) {
+    const isCodex = input.clientType === 'codex';
+    return {
+        id: 'permissionMode',
+        label: isCodex ? 'Execution policy' : 'Permission mode',
+        options: input.options,
+        defaultValue: input.defaultValue ?? null,
+        availability: isCodex ? 'setup' : 'setup_and_live',
+        liveBehavior: isCodex ? 'none' : 'immediate',
+        selectionPolicy: 'inherit',
+    };
+}
+export function buildRuntimeEffortControl() {
+    return {
+        id: 'effort',
+        label: 'Thinking level',
+        options: [...CLAUDE_EFFORT_OPTIONS],
+        defaultValue: 'medium',
+        availability: 'setup_and_live',
+        liveBehavior: 'immediate',
+        selectionPolicy: 'inherit',
+    };
+}
+export function buildFirstPartyCodingRuntimeDescriptor(input) {
+    const permissionModes = input.permissionModes
+        ?? (input.clientType === 'claude-code' ? CLAUDE_PERMISSION_MODE_OPTIONS : []);
+    return {
+        coreControls: [
+            buildRuntimeModelControl({
+                models: input.models,
+                liveBehavior: input.clientType === 'codex' ? 'next_turn' : 'immediate',
+            }),
+            buildRuntimeWorkspaceControl({
+                workspaces: input.workspaces,
+                workspaceRoots: input.workspaceRoots,
+            }),
+            buildRuntimeExecutionModeControl(input.executionModes),
+        ],
+        runtimeControls: [
+            ...(permissionModes.length > 0
+                ? [buildRuntimePermissionModeControl({
+                        clientType: input.clientType,
+                        options: permissionModes,
+                        defaultValue: input.defaultPermissionMode
+                            ?? (input.clientType === 'claude-code' ? 'default' : null),
+                    })]
+                : []),
+            ...(input.clientType === 'claude-code' ? [buildRuntimeEffortControl()] : []),
+        ],
+        actions: input.actions,
+        workspaceRoots: input.workspaceRoots,
+        supportsInterrupt: true,
+        streamingTextMode: input.streamingTextMode,
+        admissionActions: input.admissionActions,
+    };
+}

package/dist/runtime-state-publisher.d.ts

@@ -0,0 +1,31 @@
+import type { AgentClientType, AgentRuntime, RuntimeInfoPayload } from './types.js';
+import { type AgentSessionSnapshotPatch, type RTDBClientHandle, type SessionStatePayload, type TurnStatePayload } from './rtdb-rest.js';
+export interface RuntimeStatePublisherOptions {
+    agentId: string;
+    clientType: AgentClientType;
+    hostMode: boolean;
+    rtdb?: RTDBClientHandle;
+}
+export interface RuntimeStreamingPayload {
+    text: string;
+    status: 'thinking' | 'streaming' | 'tool';
+    messageId?: string;
+    updatedAt?: number | {
+        '.sv': 'timestamp';
+    };
+}
+export interface RuntimeStatePublisher {
+    publishAgentRuntime(runtime: AgentRuntime): Promise<void>;
+    clearAgentRuntime(): Promise<void>;
+    writeSessionState(conversationId: string, state: Omit<SessionStatePayload, 'updatedAt'>): Promise<void>;
+    clearSessionState(conversationId: string): Promise<void>;
+    writeTurnState(conversationId: string, state: Omit<TurnStatePayload, 'updatedAt'>): Promise<void>;
+    clearTurnState(conversationId: string): Promise<void>;
+    patchAgentSessionSnapshot(conversationId: string, snapshot: Omit<AgentSessionSnapshotPatch, 'updatedAt'>): Promise<void>;
+    writeRuntimeInfo(conversationId: string, payload: Omit<RuntimeInfoPayload, 'updatedAt'>): Promise<void>;
+    patchRuntimeInfo(conversationId: string, payload: Partial<Omit<RuntimeInfoPayload, 'updatedAt'>>): Promise<void>;
+    clearRuntimeInfo(conversationId: string): Promise<void>;
+    writeStreaming(conversationId: string, payload: RuntimeStreamingPayload): Promise<void>;
+    clearStreaming(conversationId: string): Promise<void>;
+}
+export declare function createRuntimeStatePublisher(options: RuntimeStatePublisherOptions): RuntimeStatePublisher;

package/dist/runtime-state-publisher.js

@@ -0,0 +1,68 @@
+import { clearRuntimeInfo, clearSessionState, clearTurnState, patchAgentSessionSnapshot, patchRuntimeInfo, rtdbWrite, writeRuntimeInfo, writeSessionState, writeTurnState, } from './rtdb-rest.js';
+const SERVER_TIMESTAMP = { '.sv': 'timestamp' };
+export function createRuntimeStatePublisher(options) {
+    const { agentId, clientType, hostMode, rtdb } = options;
+    const writePath = (path, data) => (rtdb ? rtdb.write(path, data) : rtdbWrite(path, data));
+    return {
+        async publishAgentRuntime(runtime) {
+            await writePath(`/agent-runtime/${agentId}`, {
+                clientType,
+                hostMode,
+                ...runtime,
+                updatedAt: SERVER_TIMESTAMP,
+            });
+        },
+        async clearAgentRuntime() {
+            await writePath(`/agent-runtime/${agentId}`, null);
+        },
+        async writeSessionState(conversationId, state) {
+            await (rtdb
+                ? rtdb.writeSessionState(conversationId, agentId, state)
+                : writeSessionState(conversationId, agentId, state));
+        },
+        async clearSessionState(conversationId) {
+            await (rtdb
+                ? rtdb.clearSessionState(conversationId, agentId)
+                : clearSessionState(conversationId, agentId));
+        },
+        async writeTurnState(conversationId, state) {
+            await (rtdb
+                ? rtdb.writeTurnState(conversationId, agentId, state)
+                : writeTurnState(conversationId, agentId, state));
+        },
+        async clearTurnState(conversationId) {
+            await (rtdb
+                ? rtdb.clearTurnState(conversationId, agentId)
+                : clearTurnState(conversationId, agentId));
+        },
+        async patchAgentSessionSnapshot(conversationId, snapshot) {
+            await (rtdb
+                ? rtdb.patchAgentSessionSnapshot(conversationId, agentId, snapshot)
+                : patchAgentSessionSnapshot(conversationId, agentId, snapshot));
+        },
+        async writeRuntimeInfo(conversationId, payload) {
+            await (rtdb
+                ? rtdb.writeRuntimeInfo(conversationId, agentId, payload)
+                : writeRuntimeInfo(conversationId, agentId, payload));
+        },
+        async patchRuntimeInfo(conversationId, payload) {
+            await (rtdb
+                ? rtdb.patchRuntimeInfo(conversationId, agentId, payload)
+                : patchRuntimeInfo(conversationId, agentId, payload));
+        },
+        async clearRuntimeInfo(conversationId) {
+            await (rtdb
+                ? rtdb.clearRuntimeInfo(conversationId, agentId)
+                : clearRuntimeInfo(conversationId, agentId));
+        },
+        async writeStreaming(conversationId, payload) {
+            await writePath(`/streaming/${conversationId}/${agentId}`, {
+                ...payload,
+                updatedAt: payload.updatedAt ?? SERVER_TIMESTAMP,
+            });
+        },
+        async clearStreaming(conversationId) {
+            await writePath(`/streaming/${conversationId}/${agentId}`, null);
+        },
+    };
+}

package/dist/types.d.ts

@@ -482,7 +482,6 @@ export interface SessionState {
     /** True when the agent is running under the host wrapper (host.ts) which can apply control signals */
     hostMode?: boolean;
     isActive: boolean;
-    state?: 'idle' | 'running' | 'requires_action';
     contextUsage?: {
         percentage: number;
         totalTokens: number;
@@ -585,7 +584,6 @@ export interface AgentSessionSnapshot {
     resolvedCwd?: string | null;
     worktreePath?: string | null;
     executionFallbackReason?: string | null;
-    state?: SessionState['state'];
     turnState?: TurnLifecycleState;
     supportsQueue?: boolean;
     queueDepth: number;

package/package.json

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