@canonmsg/core 0.12.0 → 0.14.0

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,13 +6,14 @@ 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';
 export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
 export { DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 export type { DeliveryIntent, TurnMessageSemantics, InboundDisposition, TurnLifecycleState, RuntimeCapabilities, HostAdmissionActionCapabilities, TurnState, TurnMetadata, TriggerDecision, } from './turn-protocol.js';
-export { registerAndWaitForApproval } from './registration.js';
+export { ackRegistrationApproval, registerAndWaitForApproval, submitRegistrationRequest, waitForRegistrationApproval, } from './registration.js';
 export { ApprovalManager } from './approval-manager.js';
 export { generateApprovalId, buildApprovalRequest, buildApprovalReply, buildApprovalOutcome, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
 export { DEFAULT_APPROVAL_CONFIG, } from './approval-types.js';
@@ -21,14 +22,20 @@ export { buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, b
 export type { ClaudeQuestionMetadata, ClaudeQuestionReplyMetadata, PlanApprovalMetadata, PlanApprovalReplyMetadata, RuntimeQuestionDefinition, RuntimeQuestionOption, } from './runtime-cards.js';
 export { createStreamingHelper } from './streaming.js';
 export type { RTDBHandle, RTDBRef, ServerTimestamp, StreamingHelperOptions, StreamingNode } from './streaming.js';
-export { loadProfiles, isProfileLocked, acquireLock, releaseLock, isProcessAlive, CANON_DIR, AGENTS_PATH, LOCKS_DIR, } from './agent-profiles.js';
-export type { AgentProfile } from './agent-profiles.js';
-export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agent-resolver.js';
+export { clearPendingRegistration, getOrCreatePendingRegistration, loadPendingRegistrations, loadProfiles, savePendingRegistrations, saveProfiles, updatePendingRegistration, upsertAgentProfile, isProfileLocked, acquireLock, releaseLock, isProcessAlive, CANON_DIR, AGENTS_PATH, LOCKS_DIR, } from './agent-profiles.js';
+export type { AgentProfile, PendingRegistration, ProfileLockHandle } from './agent-profiles.js';
+export { resolveCanonAgent, resolveCanonProfile, getActiveProfile, getActiveProfileLock } from './agent-resolver.js';
 export type { ResolvedAgent } from './agent-resolver.js';
+export { RUNTIMES_DIR, buildLocalRuntimeId, clearRuntimeSessionState, describeProfileLock, heartbeatLocalRuntimeEntry, listLocalRuntimeEntries, loadRuntimeSessionState, markLocalRuntimeStopped, readLocalRuntimeEntry, removeLocalRuntimeEntry, saveRuntimeSessionState, upsertLocalRuntimeEntry, } from './local-runtime-catalog.js';
+export type { LocalRuntimeCatalogEntry, LocalRuntimeKind, LocalRuntimeReviveCapability, LocalRuntimeSessionState, LocalRuntimeStatus, } from './local-runtime-catalog.js';
 export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildConversationWorktreeSpec, buildPublicWorkspaceOptions, buildWorkspaceOptionId, EXECUTION_ENVIRONMENT_MODES, isEnabledFlag, isExecutionEnvironmentMode, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, ExecutionEnvironmentError, prepareConversationEnvironment, releaseConversationEnvironment, } from './execution-environment.js';
 export type { ConfiguredWorkspaceOption, ExecutionEnvironmentMode, PreparedExecutionEnvironment, SessionWorkspaceConfig, } from './execution-environment.js';
 export { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, 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,13 +5,14 @@ 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';
 // Turn protocol
 export { DEFAULT_RUNTIME_CAPABILITIES, HOST_ADMISSION_ACTION_CAPABILITIES, HOST_ADMISSION_ACTIONS_DISABLED, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
 // Registration
-export { registerAndWaitForApproval } from './registration.js';
+export { ackRegistrationApproval, registerAndWaitForApproval, submitRegistrationRequest, waitForRegistrationApproval, } from './registration.js';
 // Approval
 export { ApprovalManager } from './approval-manager.js';
 export { generateApprovalId, buildApprovalRequest, buildApprovalReply, buildApprovalOutcome, parseTextApprovalReply, redactSecrets, } from './approval-format.js';
@@ -20,13 +21,18 @@ export { buildPlanApprovalReply, buildPlanApprovalRequest, buildQuestionReply, b
 // Streaming (RTDB helpers)
 export { createStreamingHelper } from './streaming.js';
 // Agent profiles (loading, locking, resolution)
-export { loadProfiles, isProfileLocked, acquireLock, releaseLock, isProcessAlive, CANON_DIR, AGENTS_PATH, LOCKS_DIR, } from './agent-profiles.js';
+export { clearPendingRegistration, getOrCreatePendingRegistration, loadPendingRegistrations, loadProfiles, savePendingRegistrations, saveProfiles, updatePendingRegistration, upsertAgentProfile, isProfileLocked, acquireLock, releaseLock, isProcessAlive, CANON_DIR, AGENTS_PATH, LOCKS_DIR, } from './agent-profiles.js';
 // Agent resolver
-export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agent-resolver.js';
+export { resolveCanonAgent, resolveCanonProfile, getActiveProfile, getActiveProfileLock } from './agent-resolver.js';
+// Local runtime catalog
+export { RUNTIMES_DIR, buildLocalRuntimeId, clearRuntimeSessionState, describeProfileLock, heartbeatLocalRuntimeEntry, listLocalRuntimeEntries, loadRuntimeSessionState, markLocalRuntimeStopped, readLocalRuntimeEntry, removeLocalRuntimeEntry, saveRuntimeSessionState, upsertLocalRuntimeEntry, } from './local-runtime-catalog.js';
 // Execution environments for host-mode coding sessions
 export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildConversationWorktreeSpec, buildPublicWorkspaceOptions, buildWorkspaceOptionId, EXECUTION_ENVIRONMENT_MODES, isEnabledFlag, isExecutionEnvironmentMode, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, ExecutionEnvironmentError, prepareConversationEnvironment, releaseConversationEnvironment, } from './execution-environment.js';
 // RTDB REST helpers (token exchange, session state, generic read/write)
 export { initRTDBAuth, rtdbWrite, rtdbRead, patchAgentSessionSnapshot, 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/local-runtime-catalog.d.ts

@@ -0,0 +1,65 @@
+import type { AgentClientType, ExecutionEnvironmentMode } from './types.js';
+export type LocalRuntimeKind = AgentClientType | 'sdk';
+export type LocalRuntimeStatus = 'running' | 'offline' | 'stale' | 'manual' | 'embedded';
+export type LocalRuntimeReviveCapability = 'revivable' | 'manual' | 'embedded' | 'missing-profile';
+export interface LocalRuntimeSessionState {
+    conversationId: string;
+    workspaceId?: string;
+    baseCwd: string;
+    executionMode?: ExecutionEnvironmentMode;
+    threadId?: string;
+    claudeSessionId?: string;
+    lastInboundMessageId?: string;
+    updatedAt: string;
+}
+export interface LocalRuntimeCatalogEntry {
+    id: string;
+    runtime: LocalRuntimeKind;
+    profile: string | null;
+    agentId?: string;
+    agentName?: string;
+    cwd: string;
+    baseCwd?: string;
+    workspaceRoots?: string[];
+    workspaces?: string[];
+    launchCommand: string[];
+    pid?: number;
+    status: LocalRuntimeStatus;
+    reviveCapability: LocalRuntimeReviveCapability;
+    surfaceMode?: 'host' | 'channel' | 'embedded';
+    lastStartedAt?: string;
+    lastHeartbeatAt?: string;
+    lastStoppedAt?: string;
+    lastAuthError?: string;
+    lastError?: string;
+    sessions?: Record<string, LocalRuntimeSessionState>;
+}
+export declare const RUNTIMES_DIR: string;
+export declare function buildLocalRuntimeId(input: {
+    runtime: LocalRuntimeKind;
+    profile?: string | null;
+    cwd: string;
+    launchCommand?: string[];
+}): string;
+export declare function readLocalRuntimeEntry(id: string): LocalRuntimeCatalogEntry | null;
+export declare function upsertLocalRuntimeEntry(entry: LocalRuntimeCatalogEntry): LocalRuntimeCatalogEntry;
+export declare function heartbeatLocalRuntimeEntry(id: string, patch?: Partial<LocalRuntimeCatalogEntry>): LocalRuntimeCatalogEntry | null;
+export declare function markLocalRuntimeStopped(id: string, patch?: Partial<LocalRuntimeCatalogEntry>): LocalRuntimeCatalogEntry | null;
+export declare function removeLocalRuntimeEntry(id: string): void;
+export declare function listLocalRuntimeEntries(options?: {
+    runtime?: LocalRuntimeKind;
+}): LocalRuntimeCatalogEntry[];
+export declare function loadRuntimeSessionState(runtimeId: string, input: {
+    conversationId: string;
+    baseCwd: string;
+    executionMode?: ExecutionEnvironmentMode;
+    workspaceId?: string;
+}): LocalRuntimeSessionState | null;
+export declare function saveRuntimeSessionState(runtimeId: string, input: Omit<LocalRuntimeSessionState, 'updatedAt'>): LocalRuntimeSessionState;
+export declare function clearRuntimeSessionState(runtimeId: string, input: {
+    conversationId: string;
+    baseCwd?: string;
+    executionMode?: ExecutionEnvironmentMode;
+    workspaceId?: string;
+}): void;
+export declare function describeProfileLock(profile: string): string;

package/dist/local-runtime-catalog.js

@@ -0,0 +1,200 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { CANON_DIR, isProcessAlive, isProfileLocked, loadProfiles } from './agent-profiles.js';
+export const RUNTIMES_DIR = join(CANON_DIR, 'runtimes');
+const LEGACY_CODEX_SESSIONS_PATH = join(CANON_DIR, 'codex-sessions.json');
+function shortHash(value) {
+    return createHash('sha256').update(value).digest('hex').slice(0, 16);
+}
+function safeRuntimeFileName(id) {
+    return `${shortHash(id)}.json`;
+}
+function runtimePath(id) {
+    return join(RUNTIMES_DIR, safeRuntimeFileName(id));
+}
+function writeJsonAtomic(path, value) {
+    mkdirSync(RUNTIMES_DIR, { recursive: true });
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    writeFileSync(tmp, JSON.stringify(value, null, 2), { mode: 0o600 });
+    renameSync(tmp, path);
+}
+export function buildLocalRuntimeId(input) {
+    const profile = input.profile ?? 'manual';
+    return `${input.runtime}:${profile}:${shortHash(`${resolve(input.cwd)}:${(input.launchCommand ?? []).join('\0')}`)}`;
+}
+export function readLocalRuntimeEntry(id) {
+    try {
+        const parsed = JSON.parse(readFileSync(runtimePath(id), 'utf-8'));
+        return parsed.id === id ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function upsertLocalRuntimeEntry(entry) {
+    const existing = readLocalRuntimeEntry(entry.id);
+    const next = {
+        ...existing,
+        ...entry,
+        sessions: {
+            ...(existing?.sessions ?? {}),
+            ...(entry.sessions ?? {}),
+        },
+    };
+    writeJsonAtomic(runtimePath(entry.id), next);
+    return next;
+}
+export function heartbeatLocalRuntimeEntry(id, patch = {}) {
+    const existing = readLocalRuntimeEntry(id);
+    if (!existing)
+        return null;
+    return upsertLocalRuntimeEntry({
+        ...existing,
+        ...patch,
+        id,
+        status: 'running',
+        pid: patch.pid ?? process.pid,
+        lastHeartbeatAt: new Date().toISOString(),
+    });
+}
+export function markLocalRuntimeStopped(id, patch = {}) {
+    const existing = readLocalRuntimeEntry(id);
+    if (!existing)
+        return null;
+    return upsertLocalRuntimeEntry({
+        ...existing,
+        ...patch,
+        id,
+        status: existing.reviveCapability === 'embedded' ? 'embedded' : 'offline',
+        pid: undefined,
+        lastStoppedAt: new Date().toISOString(),
+    });
+}
+export function removeLocalRuntimeEntry(id) {
+    try {
+        unlinkSync(runtimePath(id));
+    }
+    catch { }
+}
+function deriveRuntimeState(entry) {
+    let status = entry.status;
+    if (status === 'running' && entry.pid && !isProcessAlive(entry.pid)) {
+        status = 'stale';
+    }
+    const profiles = loadProfiles();
+    let reviveCapability = entry.reviveCapability;
+    if (entry.profile && !profiles[entry.profile]) {
+        reviveCapability = 'missing-profile';
+    }
+    return { ...entry, status, reviveCapability };
+}
+export function listLocalRuntimeEntries(options = {}) {
+    if (!existsSync(RUNTIMES_DIR))
+        return [];
+    const entries = [];
+    for (const name of readdirSync(RUNTIMES_DIR)) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const entry = JSON.parse(readFileSync(join(RUNTIMES_DIR, name), 'utf-8'));
+            if (options.runtime && entry.runtime !== options.runtime)
+                continue;
+            entries.push(deriveRuntimeState(entry));
+        }
+        catch {
+            // Ignore corrupt breadcrumbs; they should not block the manager.
+        }
+    }
+    return entries.sort((a, b) => {
+        const at = a.lastHeartbeatAt ?? a.lastStartedAt ?? a.lastStoppedAt ?? '';
+        const bt = b.lastHeartbeatAt ?? b.lastStartedAt ?? b.lastStoppedAt ?? '';
+        return bt.localeCompare(at);
+    });
+}
+function sessionKey(input) {
+    return shortHash([
+        input.conversationId,
+        resolve(input.baseCwd),
+        input.executionMode ?? 'unknown',
+        input.workspaceId ?? '',
+    ].join('\0'));
+}
+export function loadRuntimeSessionState(runtimeId, input) {
+    migrateLegacyCodexSessions(runtimeId);
+    const entry = readLocalRuntimeEntry(runtimeId);
+    return entry?.sessions?.[sessionKey(input)] ?? null;
+}
+export function saveRuntimeSessionState(runtimeId, input) {
+    const entry = readLocalRuntimeEntry(runtimeId);
+    if (!entry) {
+        throw new Error(`Runtime catalog entry not found: ${runtimeId}`);
+    }
+    const key = sessionKey(input);
+    const existingState = entry.sessions?.[key];
+    const nextState = {
+        ...existingState,
+        ...input,
+        updatedAt: new Date().toISOString(),
+    };
+    upsertLocalRuntimeEntry({
+        ...entry,
+        sessions: {
+            ...(entry.sessions ?? {}),
+            [key]: nextState,
+        },
+    });
+    return nextState;
+}
+export function clearRuntimeSessionState(runtimeId, input) {
+    const entry = readLocalRuntimeEntry(runtimeId);
+    if (!entry?.sessions)
+        return;
+    const sessions = { ...entry.sessions };
+    if (input.baseCwd) {
+        delete sessions[sessionKey({
+            conversationId: input.conversationId,
+            baseCwd: input.baseCwd,
+            executionMode: input.executionMode,
+            workspaceId: input.workspaceId,
+        })];
+    }
+    else {
+        for (const [key, state] of Object.entries(sessions)) {
+            if (state.conversationId === input.conversationId)
+                delete sessions[key];
+        }
+    }
+    upsertLocalRuntimeEntry({ ...entry, sessions });
+}
+function migrateLegacyCodexSessions(runtimeId) {
+    if (!existsSync(LEGACY_CODEX_SESSIONS_PATH))
+        return;
+    const entry = readLocalRuntimeEntry(runtimeId);
+    if (!entry || entry.runtime !== 'codex')
+        return;
+    try {
+        const legacy = JSON.parse(readFileSync(LEGACY_CODEX_SESSIONS_PATH, 'utf-8'));
+        const agentSessions = entry.agentId ? legacy.agents?.[entry.agentId] : null;
+        if (!agentSessions)
+            return;
+        const sessions = { ...(entry.sessions ?? {}) };
+        for (const [conversationId, state] of Object.entries(agentSessions)) {
+            const baseCwd = state.cwd;
+            sessions[sessionKey({ conversationId, baseCwd })] = {
+                conversationId,
+                baseCwd,
+                threadId: state.threadId,
+                updatedAt: state.updatedAt,
+            };
+        }
+        upsertLocalRuntimeEntry({ ...entry, sessions });
+    }
+    catch {
+        return;
+    }
+}
+export function describeProfileLock(profile) {
+    const lock = isProfileLocked(profile);
+    return lock.locked ? `locked by PID ${lock.pid}` : 'available';
+}

package/dist/registration.d.ts

@@ -8,6 +8,14 @@ import type { RegistrationInput, RegistrationResult, RegistrationStatus } from '
  * 3. On approval, returns the API key
  */
 export declare function registerAndWaitForApproval(input: RegistrationInput, callbacks?: {
-    onSubmitted?: (requestId: string) => void;
+    onSubmitted?: (requestId: string, pollToken?: string) => void;
     onPollUpdate?: (status: RegistrationStatus) => void;
 }): Promise<RegistrationResult>;
+export declare function submitRegistrationRequest(input: RegistrationInput): Promise<{
+    requestId: string;
+    pollToken?: string;
+}>;
+export declare function waitForRegistrationApproval(baseUrl: string | undefined, requestId: string, pollToken?: string, callbacks?: {
+    onPollUpdate?: (status: RegistrationStatus) => void;
+}): Promise<RegistrationResult>;
+export declare function ackRegistrationApproval(baseUrl: string | undefined, requestId: string, pollToken?: string): Promise<void>;