@canonmsg/core 0.11.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/browser.d.ts

@@ -1,7 +1,7 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
 export { resolveCanonBaseUrl } from './base-url.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
-export type { AgentCapabilities, AgentClientType, AgentSessionSnapshot, AgentSessionWorkSessionSummary, AgentRuntime, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContactRequest, CanonContactRequestStatus, ContactApprovedPayload, ContactRequestPayload, CanonStreamEvent, CreateContactRequestResult, MediaAttachment, MediaAttachmentKind, ModelOption, PermissionModeOption, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, ResolvedAdmission, SessionConfig, TurnUpdatedPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, AgentSessionSnapshot, AgentSessionWorkSessionSummary, AgentRuntime, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonResolveAdmissionResult, ContactAddedPayload, ContactApprovedPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonStreamEvent, CreateContactRequestResult, MediaAttachment, MediaAttachmentKind, ModelOption, PermissionModeOption, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, RuntimeUpdatedPayload, RuntimeInfoPayload, ResolvedAdmission, SessionConfig, TurnUpdatedPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
 export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, } from './execution-environment-mode.js';
 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';

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { type CanonMessage, type CanonConversation, type CanonContactRequest, type CanonMessagesPage, type AgentContext, type CreateContactRequestResult, type MediaAttachment, type SendMessageOptions, type CreateConversationOptions, type RegistrationStatus, type SetStreamingOptions } from './types.js';
+import { type CanonMessage, type CanonConversation, type CanonContact, type CanonContactRequest, type CanonMessagesPage, type CanonResolveAdmissionResult, type AgentContext, type AddMemberResult, type CreateContactRequestResult, type MediaAttachment, type SendMessageOptions, type CreateConversationOptions, type RegistrationStatus, type SetStreamingOptions } from './types.js';
 import type { CanonResolvedWorkSession, CreateWorkSessionOptions, SendLinkedMessageOptions, SendLinkedMessageResult, UpdateWorkSessionConversationOptions } from './work-session.js';
 import type { InboundDisposition } from './turn-protocol.js';
 /**
@@ -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>;
@@ -31,6 +34,12 @@ export declare class CanonClient {
     }>;
     createContactRequest(targetUserId: string, message?: string | null): Promise<CreateContactRequestResult>;
     listContactRequests(): Promise<CanonContactRequest[]>;
+    listContacts(): Promise<CanonContact[]>;
+    getContact(contactId: string): Promise<CanonContact | null>;
+    deleteContact(contactId: string): Promise<void>;
+    blockUser(userId: string): Promise<void>;
+    unblockUser(userId: string): Promise<void>;
+    resolveAdmission(targetUserId: string): Promise<CanonResolveAdmissionResult>;
     uploadMedia(conversationId: string, data: string, mimeType: string, fileName?: string): Promise<{
         url: string;
         attachment: MediaAttachment;
@@ -42,7 +51,7 @@ export declare class CanonClient {
     leaveConversation(conversationId: string): Promise<void>;
     react(conversationId: string, messageId: string, emoji: string): Promise<void>;
     updateConversationName(conversationId: string, name: string): Promise<void>;
-    addMember(conversationId: string, userId: string): Promise<void>;
+    addMember(conversationId: string, userId: string): Promise<AddMemberResult>;
     removeMember(conversationId: string, userId: string): Promise<void>;
     setStreaming(options: SetStreamingOptions): Promise<void>;
     clearStreaming(conversationId: string): Promise<void>;
@@ -55,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(),
@@ -142,7 +151,7 @@ export class CanonClient {
         });
         const body = await res.text();
         if (res.status === 200) {
-            return { status: 'open', requestId: null };
+            return { status: 'open' };
         }
         if (res.status === 201) {
             const data = parseJsonBody(body);
@@ -167,6 +176,61 @@ export class CanonClient {
         const data = await res.json();
         return data.requests;
     }
+    async listContacts() {
+        const res = await fetch(`${this.baseUrl}/contacts`, {
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        const data = await res.json();
+        return data.contacts;
+    }
+    async getContact(contactId) {
+        const res = await fetch(`${this.baseUrl}/contacts/${contactId}`, {
+            headers: this.authHeaders(),
+        });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        return res.json();
+    }
+    async deleteContact(contactId) {
+        const res = await fetch(`${this.baseUrl}/contacts/${contactId}`, {
+            method: 'DELETE',
+            headers: this.authHeaders(),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+    }
+    async blockUser(userId) {
+        const res = await fetch(`${this.baseUrl}/users/block`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ userId }),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+    }
+    async unblockUser(userId) {
+        const res = await fetch(`${this.baseUrl}/users/unblock`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ userId }),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+    }
+    async resolveAdmission(targetUserId) {
+        const res = await fetch(`${this.baseUrl}/admission/resolve`, {
+            method: 'POST',
+            headers: this.authHeaders(),
+            body: JSON.stringify({ targetUserId }),
+        });
+        if (!res.ok)
+            throw new CanonApiError(res.status, await res.text());
+        return res.json();
+    }
     async uploadMedia(conversationId, data, mimeType, fileName) {
         const res = await fetch(`${this.baseUrl}/media/upload`, {
             method: 'POST',
@@ -243,8 +307,20 @@ export class CanonClient {
             headers: this.authHeaders(),
             body: JSON.stringify({ userId }),
         });
+        const body = await res.text();
         if (!res.ok)
-            throw new CanonApiError(res.status, await res.text());
+            throw new CanonApiError(res.status, body);
+        // 202 means the target requires approval — server created a contact
+        // request (kind: 'group_invite') routed to the approver. The actual
+        // group join happens when that request is approved.
+        if (res.status === 202) {
+            const data = parseJsonBody(body);
+            if (typeof data.requestId === 'string') {
+                return { status: 'pending', requestId: data.requestId };
+            }
+            throw new CanonApiError(202, 'Server returned 202 without a requestId');
+        }
+        return { status: 'added' };
     }
     async removeMember(conversationId, userId) {
         const res = await fetch(`${this.baseUrl}/conversations/${conversationId}/members/${userId}`, {
@@ -293,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

@@ -1,5 +1,5 @@
 export { AGENT_CAPABILITIES, CLAUDE_PERMISSION_MODE_OPTIONS, } from './types.js';
-export type { AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContactRequest, CanonContactRequestStatus, ContactApprovedPayload, ContactRequestPayload, CanonMessage, CanonConversation, CanonMessagesPage, CreateContactRequestResult, AgentContext, CanonStreamEvent, AgentSessionSnapshot, AgentSessionWorkSessionSummary, ResolvedAdmission, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
+export type { AddMemberResult, AgentCapabilities, AgentClientType, CanonControlAvailability, CanonControlDescriptor, CanonControlLiveBehavior, CanonControlSelectionPolicy, CanonControlValue, CanonContact, CanonContactRequest, CanonContactRequestStatus, CanonResolveAdmissionResult, ContactAddedPayload, ContactApprovedPayload, ContactCardPayload, ContactRemovedPayload, ContactRequestPayload, ContactSource, ResolvedAdmissionState, ResolvedAdmissionTargetSummary, ResolvedTargetAdmissionPayload, CanonMessage, CanonConversation, CanonMessagesPage, CreateContactRequestResult, AgentContext, CanonStreamEvent, AgentSessionSnapshot, AgentSessionWorkSessionSummary, ResolvedAdmission, MediaAttachment, MediaAttachmentKind, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload, SendMessageOptions, CreateConversationOptions, RegistrationInput, RegistrationResult, RegistrationStatus, StreamingStatus, SetStreamingOptions, SessionControl, SessionState, SessionConfig, AgentRuntime, CanonRuntimeDescriptor, CanonRuntimeActionAvailability, CanonRuntimeActionCategory, CanonRuntimeActionDescriptor, CanonRuntimeActionDispatch, CanonRuntimeActionPlacement, CanonRuntimeExecutionMetadata, CanonRuntimeInventory, CanonRuntimeInventoryEntry, CanonRuntimeStreamingMode, CanonRuntimeStatusItem, CanonRuntimeSurfaceMode, CanonWorkspaceRootMetadata, ModelOption, PermissionModeOption, RuntimeInfoPayload, WorkspaceOption, WorkspaceOptionSource, } from './types.js';
 export type { CanonResolvedWorkSession, CanonWorkSession, CanonWorkSessionContext, CanonWorkSessionConversationRole, CreateWorkSessionOptions, CanonWorkSessionDisclosureMode, CanonWorkSessionParticipant, CanonWorkSessionStatus, SendLinkedMessageOptions, SendLinkedMessageResult, UpdateWorkSessionConversationOptions, WorkSessionPromptRenderOptions, } from './work-session.js';
 export { buildWorkSessionPromptLines, buildWorkSessionsPromptLines, mergeWorkSessionContexts, } from './work-session.js';
 export { buildConfiguredWorkspaceOptionsWithRoots, buildPublicWorkspaceRoots, buildWorkspaceRootId, discoverWorkspaceProjects, } from './workspace-discovery.js';
@@ -10,9 +10,9 @@ 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, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';
-export type { DeliveryIntent, TurnMessageSemantics, InboundDisposition, TurnLifecycleState, RuntimeCapabilities, TurnState, TurnMetadata, TriggerDecision, } from './turn-protocol.js';
-export { registerAndWaitForApproval } from './registration.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 { 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

@@ -9,9 +9,9 @@ export { buildAgentSessionSnapshot } from './agent-session.js';
 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, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.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';
 // 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/message-format.js

@@ -39,8 +39,6 @@ function formatContactCard(card) {
     const parts = [card.userType, `userId: ${card.userId}`];
     if (card.ownerName)
         parts.push(`owner: ${card.ownerName}`);
-    if (card.accessLevel)
-        parts.push(`access: ${card.accessLevel}`);
     if (card.about)
         parts.push(`about: ${card.about}`);
     return `[Contact card] "${displayName}" — ${parts.join(' · ')}`;

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/stream.d.ts

@@ -1,9 +1,11 @@
-import type { AgentContext, ContactApprovedPayload, ContactRequestPayload, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload } from './types.js';
+import type { AgentContext, ContactAddedPayload, ContactApprovedPayload, ContactRemovedPayload, ContactRequestPayload, MessageCreatedPayload, TypingPayload, PresencePayload, RuntimeUpdatedPayload, TurnUpdatedPayload } from './types.js';
 export type StreamHandler = {
     onMessage: (payload: MessageCreatedPayload) => void;
     onAgentContext?: (ctx: AgentContext) => void;
     onContactRequest?: (payload: ContactRequestPayload) => void;
     onContactApproved?: (payload: ContactApprovedPayload) => void;
+    onContactAdded?: (payload: ContactAddedPayload) => void;
+    onContactRemoved?: (payload: ContactRemovedPayload) => void;
     onTyping?: (data: TypingPayload) => void;
     onPresence?: (data: PresencePayload) => void;
     onRuntimeUpdated?: (payload: RuntimeUpdatedPayload) => void;
@@ -54,6 +56,8 @@ export declare class CanonStream {
     private handlePresence;
     private handleContactRequest;
     private handleContactApproved;
+    private handleContactAdded;
+    private handleContactRemoved;
     private handleRuntimeUpdated;
     private handleTurnUpdated;
     private handleMessageDeleted;

package/dist/stream.js

@@ -148,6 +148,14 @@ export class CanonStream {
                 this.reconnectAttempt = 0;
                 this.handleContactApproved(data);
                 break;
+            case 'contact.added':
+                this.reconnectAttempt = 0;
+                this.handleContactAdded(data);
+                break;
+            case 'contact.removed':
+                this.reconnectAttempt = 0;
+                this.handleContactRemoved(data);
+                break;
             case 'typing':
                 this.reconnectAttempt = 0;
                 this.handleTyping(data);
@@ -245,6 +253,24 @@ export class CanonStream {
             // Ignore parse errors for non-critical events
         }
     }
+    handleContactAdded(raw) {
+        try {
+            const data = JSON.parse(raw);
+            this.handler.onContactAdded?.(data);
+        }
+        catch {
+            // Ignore parse errors for non-critical events
+        }
+    }
+    handleContactRemoved(raw) {
+        try {
+            const data = JSON.parse(raw);
+            this.handler.onContactRemoved?.(data);
+        }
+        catch {
+            // Ignore parse errors for non-critical events
+        }
+    }
     handleRuntimeUpdated(raw) {
         try {
             const data = JSON.parse(raw);

package/dist/turn-protocol.d.ts

@@ -36,6 +36,24 @@ export interface TriggerDecision {
     reason: string;
 }
 export declare const DEFAULT_RUNTIME_CAPABILITIES: RuntimeCapabilities;
+/**
+ * Contact-graph and admission actions a Canon host runtime exposes through the
+ * agent SDK. Plugins consult this to decide which tools to register on the
+ * LLM's behalf — e.g., whether to advertise a `block_user` tool. A flag is
+ * `true` only when the runtime has both the SDK wrapper *and* a tool surface
+ * wired up that calls it. Until plugin tool wiring ships, runtimes should
+ * advertise `HOST_ADMISSION_ACTIONS_DISABLED` so consumers don't render UI
+ * for actions the runtime can't actually perform.
+ */
+export interface HostAdmissionActionCapabilities {
+    blockUser: boolean;
+    unblockUser: boolean;
+    removeContact: boolean;
+    requestContact: boolean;
+    reachOut: boolean;
+}
+export declare const HOST_ADMISSION_ACTION_CAPABILITIES: HostAdmissionActionCapabilities;
+export declare const HOST_ADMISSION_ACTIONS_DISABLED: HostAdmissionActionCapabilities;
 export declare function normalizeTurnMetadata(metadata: unknown): TurnMetadata | null;
 export declare function normalizeTurnState(value: unknown): TurnState | null;
 export declare function isTurnOpen(turnState: Pick<TurnState, 'state'> | null | undefined): boolean;

package/dist/turn-protocol.js

@@ -26,6 +26,20 @@ export const DEFAULT_RUNTIME_CAPABILITIES = {
     supportsRequiresAction: false,
     supportsNonFinalPermanentMessages: false,
 };
+export const HOST_ADMISSION_ACTION_CAPABILITIES = {
+    blockUser: true,
+    unblockUser: true,
+    removeContact: true,
+    requestContact: true,
+    reachOut: true,
+};
+export const HOST_ADMISSION_ACTIONS_DISABLED = {
+    blockUser: false,
+    unblockUser: false,
+    removeContact: false,
+    requestContact: false,
+    reachOut: false,
+};
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }

package/dist/types.d.ts

@@ -34,7 +34,6 @@ export interface ContactCardPayload {
     isActive?: boolean;
     ownerId?: string;
     ownerName?: string;
-    accessLevel?: 'open' | 'owner-only';
     lifecycleState?: string;
 }
 export interface CanonMessage {
@@ -87,18 +86,40 @@ export interface CanonContactRequest {
     requesterName: string;
     requesterAvatarUrl: string | null;
     targetId: string;
-    approverId?: string | null;
+    approverId: string;
     message: string | null;
     status: CanonContactRequestStatus;
+    /** 'dm' for one-to-one contact request, 'group_invite' for stranger-add. */
+    kind: 'dm' | 'group_invite';
+    groupContext?: {
+        conversationId: string;
+        groupName: string | null;
+    };
     createdAt: string | null;
     resolvedAt?: string | null;
     expiresAt?: string | null;
 }
 export type ContactRequestPayload = CanonContactRequest;
 export type ContactApprovedPayload = CanonContactRequest;
+/**
+ * Outcome of `CanonClient.addMember` / `agent.addMember`. The REST endpoint
+ * returns 201 on immediate add and 202 on approval-required group invite.
+ * Both are success from the protocol's perspective — distinct outcomes for
+ * the caller.
+ */
+export type AddMemberResult = {
+    status: 'added';
+} | {
+    status: 'pending';
+    requestId: string;
+};
+/**
+ * Successful outcomes of `createContactRequest`. Errors (denied,
+ * malformed input) come back as Firebase `HttpsError`s and are not
+ * represented here.
+ */
 export type CreateContactRequestResult = {
     status: 'open';
-    requestId: null;
 } | {
     status: 'created';
     requestId: string;
@@ -106,12 +127,50 @@ export type CreateContactRequestResult = {
     status: 'duplicate';
     requestId: string;
 };
+export type ContactSource = 'direct_add' | 'phone_book' | 'contact_request' | 'link' | 'qr' | 'group' | 'open_inbound_message'
+/** Sentinel value emitted by stream-service when a doc lacks a source field. */
+ | 'unknown';
+/** A single entry from the agent's `users/{agentId}/contacts/` subcollection. */
+export interface CanonContact {
+    /** The contact's userId. */
+    id: string;
+    source: ContactSource;
+    addedAt: string | null;
+    displayNameOverride: string | null;
+}
+export type ContactAddedPayload = CanonContact;
+export type ContactRemovedPayload = {
+    id: string;
+};
+export type ResolvedAdmissionState = 'self' | 'not-found' | 'allowed' | 'request-required' | 'pending-outbound' | 'blocked' | 'inactive' | 'owner-only';
+export interface ResolvedAdmissionTargetSummary {
+    id: string;
+    displayName?: string;
+    avatarUrl?: string | null;
+    about?: string;
+    userType?: 'human' | 'ai_agent';
+    discoverable?: boolean;
+    inboundPolicy?: 'open' | 'approval-required' | 'owner-only';
+    groupJoinPolicy?: 'open' | 'approval-required' | 'owner-only';
+}
+export interface ResolvedTargetAdmissionPayload {
+    state: ResolvedAdmissionState;
+    canMessage: boolean;
+    canRequestContact: boolean;
+    isContact: boolean;
+    pendingRequestId?: string;
+    blockedByViewer?: boolean;
+    blockedByTarget?: boolean;
+}
+export interface CanonResolveAdmissionResult {
+    target: ResolvedAdmissionTargetSummary | null;
+    admission: ResolvedTargetAdmissionPayload;
+}
 export type AgentClientType = 'claude-code' | 'openclaw' | 'codex' | 'generic';
 export interface ResolvedAdmission {
-    accessLevel: 'open' | 'owner-only';
     discoverable: boolean;
-    inboundPolicy: 'open' | 'approval-required' | 'private';
-    groupJoinPolicy: 'open' | 'approval-required' | 'private';
+    inboundPolicy: 'open' | 'approval-required' | 'owner-only';
+    groupJoinPolicy: 'open' | 'approval-required' | 'owner-only';
 }
 /** Declares what session controls an agent type supports. */
 export interface AgentCapabilities {
@@ -219,6 +278,13 @@ export interface CanonRuntimeDescriptor {
      * means activity/tool state without live assistant text.
      */
     streamingTextMode?: CanonRuntimeStreamingMode;
+    /**
+     * Contact-graph and admission actions this runtime exposes through the
+     * agent SDK. Plugins set this to advertise which tools they will surface
+     * to the LLM (e.g., block-user, request-contact). When omitted, no
+     * admission actions are advertised.
+     */
+    admissionActions?: import('./turn-protocol.js').HostAdmissionActionCapabilities;
 }
 export interface CanonRuntimeExecutionMetadata {
     resolvedWorkspaceLabel?: string | null;
@@ -267,7 +333,9 @@ export interface AgentContext {
     description?: string | null;
     ownerId: string;
     ownerName: string;
-    accessLevel: 'open' | 'owner-only';
+    discoverable: boolean;
+    inboundPolicy: 'open' | 'approval-required' | 'owner-only';
+    groupJoinPolicy: 'open' | 'approval-required' | 'owner-only';
     /** Identifies the agent's client platform for UI feature detection */
     clientType?: AgentClientType;
     defaultBehavior?: ResolvedAgentBehaviorPolicy;
@@ -334,6 +402,12 @@ export type CanonStreamEvent = {
 } | {
     type: 'contact.approved';
     payload: ContactApprovedPayload;
+} | {
+    type: 'contact.added';
+    payload: ContactAddedPayload;
+} | {
+    type: 'contact.removed';
+    payload: ContactRemovedPayload;
 } | {
     type: 'typing';
     payload: TypingPayload;
@@ -531,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.11.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",