@canonmsg/core 0.12.0 → 0.13.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/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/index.d.ts

@@ -12,7 +12,7 @@ export type { PolicyRole, ParticipationStyle, RepresentationMode, PermissionLeve
 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,10 +21,12 @@ 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';

package/dist/index.js

@@ -11,7 +11,7 @@ export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots,
 // 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,9 +20,11 @@ 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)

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>;

package/dist/registration.js

@@ -10,7 +10,12 @@ const POLL_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
  * 3. On approval, returns the API key
  */
 export async function registerAndWaitForApproval(input, callbacks) {
-    const { requestId } = await CanonClient.register(input.baseUrl, {
+    const submitted = await submitRegistrationRequest(input);
+    callbacks?.onSubmitted?.(submitted.requestId, submitted.pollToken);
+    return waitForRegistrationApproval(input.baseUrl, submitted.requestId, submitted.pollToken, callbacks);
+}
+export async function submitRegistrationRequest(input) {
+    return CanonClient.register(input.baseUrl, {
         name: input.name,
         description: input.description,
         ownerPhone: input.ownerPhone,
@@ -18,29 +23,47 @@ export async function registerAndWaitForApproval(input, callbacks) {
         avatarUrl: input.avatarUrl,
         clientType: input.clientType,
         requestedAgentId: input.requestedAgentId,
+        localRegistrationId: input.localRegistrationId,
     });
-    callbacks?.onSubmitted?.(requestId);
+}
+export async function waitForRegistrationApproval(baseUrl, requestId, pollToken, callbacks) {
     const deadline = Date.now() + POLL_TIMEOUT_MS;
     while (Date.now() < deadline) {
         await sleep(POLL_INTERVAL_MS);
-        const result = await CanonClient.checkStatus(input.baseUrl, requestId);
+        const result = await CanonClient.checkStatus(baseUrl, requestId, pollToken);
         callbacks?.onPollUpdate?.(result);
         if (result.status === 'approved') {
+            if (!result.apiKey) {
+                return {
+                    status: 'timeout',
+                    requestId,
+                    pollToken,
+                    agentId: result.agentId,
+                    agentName: result.agentName,
+                };
+            }
             return {
                 status: 'approved',
                 apiKey: result.apiKey,
                 agentId: result.agentId,
                 agentName: result.agentName,
+                requestId,
+                pollToken,
             };
         }
         if (result.status === 'rejected') {
             return {
                 status: 'rejected',
                 agentName: result.agentName,
+                requestId,
+                pollToken,
             };
         }
     }
-    return { status: 'timeout' };
+    return { status: 'timeout', requestId, pollToken };
+}
+export async function ackRegistrationApproval(baseUrl, requestId, pollToken) {
+    await CanonClient.ackRegistrationStatus(baseUrl, requestId, pollToken);
 }
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));

package/dist/types.d.ts

@@ -605,15 +605,18 @@ export interface RegistrationInput {
     baseUrl?: string;
     clientType?: AgentClientType;
     requestedAgentId?: string;
+    localRegistrationId?: string;
 }
 export interface RegistrationResult {
     status: 'approved' | 'rejected' | 'timeout';
     apiKey?: string;
     agentId?: string;
     agentName?: string;
+    requestId?: string;
+    pollToken?: string;
 }
 export interface RegistrationStatus {
-    status: 'pending' | 'approved' | 'rejected';
+    status: 'pending' | 'approving' | 'approved' | 'rejected';
     agentName: string;
     agentId?: string;
     apiKey?: string;

package/package.json

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