@canonmsg/core 0.6.0 → 0.7.1

package/dist/base-url.d.ts

@@ -0,0 +1 @@
+export declare function resolveCanonBaseUrl(input?: string | null): string;

package/dist/base-url.js

@@ -0,0 +1,9 @@
+import { DEFAULT_BASE_URL } from './constants.js';
+export function resolveCanonBaseUrl(input) {
+    if (typeof input !== 'string')
+        return DEFAULT_BASE_URL;
+    const trimmed = input.trim();
+    if (!trimmed)
+        return DEFAULT_BASE_URL;
+    return trimmed.replace(/\/+$/, '');
+}

package/dist/browser.d.ts

@@ -1,5 +1,9 @@
 export { AGENT_CAPABILITIES, } 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, AgentRuntime, MediaAttachment, MediaAttachmentKind, ModelOption, SessionConfig, WorkspaceOption, } 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';
 export { buildWorkSessionPromptLines, buildWorkSessionsPromptLines, mergeWorkSessionContexts, } from './work-session.js';
 export type { AgentBehaviorSettings, ParticipationHistoryMessage, ParticipationHistorySnapshot, ParticipationStyle, ResolvedAgentBehaviorPolicy, } from './policy.js';

package/dist/browser.js

@@ -1,4 +1,7 @@
 export { AGENT_CAPABILITIES, } 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 { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, } from './execution-environment-mode.js';
 export { buildWorkSessionPromptLines, buildWorkSessionsPromptLines, mergeWorkSessionContexts, } from './work-session.js';
 export { buildParticipationHistorySnapshot, buildParticipationHistorySnapshots, buildBehaviorPolicyLines, DEFAULT_PARTICIPATION_HISTORY_FETCH_LIMIT, evaluateParticipationPolicy, getDefaultParticipationPolicy, resolveAgentBehaviorPolicy, } from './policy.js';
 export { DEFAULT_RUNTIME_CAPABILITIES, FINAL_MESSAGE_HANDOFF_MS, isTurnOpen, normalizeTurnMetadata, normalizeTurnState, resolveTurnMessageSemantics, shouldPromoteConversationMessage, shouldTriggerAgentTurn, } from './turn-protocol.js';

package/dist/execution-environment-mode.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Browser-safe helpers for Canon execution modes. Separated from
+ * `execution-environment.ts` (which pulls in Node-only modules) so both
+ * Node hosts and browser/Expo clients can import these primitives.
+ */
+export type ExecutionEnvironmentMode = 'worktree' | 'locked';
+export declare const EXECUTION_ENVIRONMENT_MODES: readonly ExecutionEnvironmentMode[];
+export declare function isExecutionEnvironmentMode(value: unknown): value is ExecutionEnvironmentMode;

package/dist/execution-environment-mode.js

@@ -0,0 +1,12 @@
+/**
+ * Browser-safe helpers for Canon execution modes. Separated from
+ * `execution-environment.ts` (which pulls in Node-only modules) so both
+ * Node hosts and browser/Expo clients can import these primitives.
+ */
+export const EXECUTION_ENVIRONMENT_MODES = [
+    'worktree',
+    'locked',
+];
+export function isExecutionEnvironmentMode(value) {
+    return value === 'worktree' || value === 'locked';
+}

package/dist/execution-environment.d.ts

@@ -1,5 +1,7 @@
 import type { WorkspaceOption } from './types.js';
-export type ExecutionEnvironmentMode = 'worktree' | 'locked';
+import { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, type ExecutionEnvironmentMode } from './execution-environment-mode.js';
+export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode };
+export type { ExecutionEnvironmentMode };
 export interface PreparedExecutionEnvironment {
     cwd: string;
     baseCwd: string;
@@ -23,8 +25,9 @@ export interface ConfiguredWorkspaceOption extends WorkspaceResolverOption {
 }
 export interface SessionWorkspaceConfig {
     workspaceId?: string;
-    legacyCwd?: string;
     model?: string;
+    executionMode?: ExecutionEnvironmentMode;
+    retiredWorkspaceConfig?: boolean;
 }
 export declare function normalizeOptionalString(value: unknown): string | undefined;
 export declare function isEnabledFlag(value: unknown): boolean;
@@ -37,7 +40,7 @@ export declare function resolveConfiguredWorkspaceCwd(input: {
     workspaceOptions: WorkspaceResolverOption[];
     config: {
         workspaceId?: string;
-        legacyCwd?: string;
+        retiredWorkspaceConfig?: boolean;
     } | null;
     defaultCwd: string;
 }): string;
@@ -56,4 +59,3 @@ export declare function prepareConversationEnvironment(input: {
     allowWorktrees?: boolean;
 }): PreparedExecutionEnvironment;
 export declare function releaseConversationEnvironment(environment: Pick<PreparedExecutionEnvironment, 'lockPath'>): void;
-export {};

package/dist/execution-environment.js

@@ -3,6 +3,8 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, join, relative, resolve } from 'node:path';
 import { CANON_DIR, isProcessAlive } from './agent-profiles.js';
+import { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode, } from './execution-environment-mode.js';
+export { EXECUTION_ENVIRONMENT_MODES, isExecutionEnvironmentMode };
 export class ExecutionEnvironmentError extends Error {
     userMessage;
     constructor(message, userMessage = message) {
@@ -153,48 +155,48 @@ export function buildConfiguredWorkspaceOptions(primaryCwd, configured) {
 export function buildPublicWorkspaceOptions(workspaceOptions) {
     return workspaceOptions.map(({ id, label }) => ({ id, label }));
 }
+function isRetiredWorkspaceId(value) {
+    if (!value)
+        return false;
+    return value === 'default' || /^workspace-\d+$/.test(value);
+}
 export function readSessionWorkspaceConfig(raw) {
     if (!raw || typeof raw !== 'object')
         return null;
     const data = raw;
+    const rawWorkspaceId = normalizeOptionalString(data.workspaceId);
+    const stableWorkspaceId = rawWorkspaceId && !isRetiredWorkspaceId(rawWorkspaceId)
+        ? rawWorkspaceId
+        : undefined;
+    const hasRetiredWorkspaceReference = (normalizeOptionalString(data.cwd) !== undefined
+        || isRetiredWorkspaceId(rawWorkspaceId));
+    const rawExecutionMode = data.executionMode;
+    const executionMode = isExecutionEnvironmentMode(rawExecutionMode)
+        ? rawExecutionMode
+        : undefined;
     return {
-        workspaceId: normalizeOptionalString(data.workspaceId),
-        legacyCwd: normalizeOptionalString(data.cwd),
+        workspaceId: stableWorkspaceId,
         model: normalizeOptionalString(data.model),
+        ...(executionMode ? { executionMode } : {}),
+        ...(!stableWorkspaceId && hasRetiredWorkspaceReference
+            ? { retiredWorkspaceConfig: true }
+            : {}),
     };
 }
-function findWorkspaceByLegacyCwd(workspaceOptions, legacyCwd) {
-    if (!legacyCwd)
-        return undefined;
-    const resolvedLegacyCwd = resolve(legacyCwd);
-    return workspaceOptions.find((workspace) => resolve(workspace.cwd) === resolvedLegacyCwd);
-}
 export function resolveConfiguredWorkspaceCwd(input) {
     const fallbackCwd = input.workspaceOptions[0]?.cwd ?? resolve(input.defaultCwd);
     if (!input.config)
         return fallbackCwd;
-    const legacyWorkspace = findWorkspaceByLegacyCwd(input.workspaceOptions, input.config.legacyCwd);
+    if (input.config.retiredWorkspaceConfig) {
+        throw new ExecutionEnvironmentError('Session config still references a retired workspace format.', 'This Canon coding session was saved with a retired workspace format. Recreate the session or select a current workspace.');
+    }
     const workspaceId = input.config.workspaceId;
     if (workspaceId) {
         const workspace = input.workspaceOptions.find((option) => option.id === workspaceId);
         if (workspace)
             return workspace.cwd;
-        if (workspaceId === 'default') {
-            return fallbackCwd;
-        }
-        const legacyWorkspaceMatch = /^workspace-(\d+)$/.exec(workspaceId);
-        if (legacyWorkspaceMatch) {
-            const legacyIndex = Number.parseInt(legacyWorkspaceMatch[1] ?? '', 10) - 1;
-            if (legacyIndex >= 0 && input.workspaceOptions[legacyIndex]) {
-                return input.workspaceOptions[legacyIndex].cwd;
-            }
-        }
-        if (legacyWorkspace)
-            return legacyWorkspace.cwd;
         throw new ExecutionEnvironmentError(`Workspace ${workspaceId} is not configured on this machine.`, 'The workspace saved for this Canon coding session is no longer configured on this machine.');
     }
-    if (legacyWorkspace)
-        return legacyWorkspace.cwd;
     return fallbackCwd;
 }
 export function buildConversationWorktreeSpec(input) {

package/dist/index.d.ts

@@ -20,8 +20,9 @@ export { loadProfiles, isProfileLocked, acquireLock, releaseLock, isProcessAlive
 export type { AgentProfile } from './agent-profiles.js';
 export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agent-resolver.js';
 export type { ResolvedAgent } from './agent-resolver.js';
-export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildConversationWorktreeSpec, buildPublicWorkspaceOptions, buildWorkspaceOptionId, isEnabledFlag, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, ExecutionEnvironmentError, prepareConversationEnvironment, releaseConversationEnvironment, } from './execution-environment.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, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
 export type { SessionStatePayload, TurnStatePayload } from './rtdb-rest.js';
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
+export { resolveCanonBaseUrl } from './base-url.js';

package/dist/index.js

@@ -21,8 +21,10 @@ export { loadProfiles, isProfileLocked, acquireLock, releaseLock, isProcessAlive
 // Agent resolver
 export { resolveCanonAgent, resolveCanonProfile, getActiveProfile } from './agent-resolver.js';
 // Execution environments for host-mode coding sessions
-export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildConversationWorktreeSpec, buildPublicWorkspaceOptions, buildWorkspaceOptionId, isEnabledFlag, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, ExecutionEnvironmentError, prepareConversationEnvironment, releaseConversationEnvironment, } from './execution-environment.js';
+export { buildConfiguredWorkspaceOptions, buildConversationEnvironmentKey, buildConversationWorktreeSpec, buildPublicWorkspaceOptions, buildWorkspaceOptionId, EXECUTION_ENVIRONMENT_MODES, isEnabledFlag, isExecutionEnvironmentMode, normalizeOptionalString, readSessionWorkspaceConfig, resolveConfiguredWorkspaceCwd, ExecutionEnvironmentError, prepareConversationEnvironment, releaseConversationEnvironment, } from './execution-environment.js';
 // RTDB REST helpers (token exchange, session state, generic read/write)
 export { initRTDBAuth, rtdbWrite, rtdbRead, writeSessionState, clearSessionState, writeTurnState, clearTurnState, } from './rtdb-rest.js';
 // Constants
 export { DEFAULT_BASE_URL, DEFAULT_STREAM_URL, DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
+// Base URL resolver
+export { resolveCanonBaseUrl } from './base-url.js';

package/dist/rtdb-rest.d.ts

@@ -50,8 +50,25 @@ export interface TurnStatePayload {
         '.sv': 'timestamp';
     };
 }
-/** Must be called once before any RTDB operations. */
-export declare function initRTDBAuth(client: CanonClient): void;
+interface RTDBAuthOptions {
+    rtdbUrl?: string;
+    firebaseApiKey?: string;
+}
+interface RTDBClientHandle {
+    read(path: string): Promise<unknown>;
+    write(path: string, data: unknown): Promise<void>;
+    patch(path: string, data: unknown): Promise<void>;
+    remove(path: string): Promise<void>;
+    writeSessionState(conversationId: string, agentId: string, state: Omit<SessionStatePayload, 'updatedAt'>): Promise<void>;
+    clearSessionState(conversationId: string, agentId: string): Promise<void>;
+    writeTurnState(conversationId: string, agentId: string, state: Omit<TurnStatePayload, 'updatedAt'>): Promise<void>;
+    clearTurnState(conversationId: string, agentId: string): Promise<void>;
+}
+/**
+ * Initializes the default RTDB helper and returns a scoped client for callers
+ * that need per-runtime auth and base-url isolation.
+ */
+export declare function initRTDBAuth(client: CanonClient, options?: RTDBAuthOptions): RTDBClientHandle;
 /** Generic RTDB REST write (PUT). */
 export declare function rtdbWrite(path: string, data: unknown): Promise<void>;
 /** Generic RTDB REST read (GET). */
@@ -67,3 +84,4 @@ export declare function writeSessionState(conversationId: string, agentId: strin
 export declare function clearSessionState(conversationId: string, agentId: string): Promise<void>;
 export declare function writeTurnState(conversationId: string, agentId: string, state: Omit<TurnStatePayload, 'updatedAt'>): Promise<void>;
 export declare function clearTurnState(conversationId: string, agentId: string): Promise<void>;
+export {};

package/dist/rtdb-rest.js

@@ -6,163 +6,208 @@
  * is exchanged for a Firebase ID token before use with RTDB REST.
  */
 import { DEFAULT_RTDB_URL, FIREBASE_WEB_API_KEY } from './constants.js';
-const RTDB_BASE = process.env.CANON_RTDB_URL || DEFAULT_RTDB_URL;
-const FIREBASE_API_KEY = process.env.CANON_FIREBASE_API_KEY || FIREBASE_WEB_API_KEY;
-// ── Token management ──────────────────────────────────────────────────
-let cachedIdToken = null;
-let idTokenExpiresAt = 0;
-let tokenClient = null;
-/** Must be called once before any RTDB operations. */
-export function initRTDBAuth(client) {
-    tokenClient = client;
+const DEFAULT_RTDB_BASE = normalizeRTDBBase(process.env.CANON_RTDB_URL || DEFAULT_RTDB_URL);
+const DEFAULT_FIREBASE_API_KEY = process.env.CANON_FIREBASE_API_KEY || FIREBASE_WEB_API_KEY;
+let defaultRTDBClient = null;
+function normalizeRTDBBase(url) {
+    return url.replace(/\/+$/, '');
 }
-/**
- * Exchange a Firebase custom token for an ID token via the Identity Toolkit API.
- */
-async function exchangeCustomTokenForIdToken(customToken) {
-    const url = `https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=${FIREBASE_API_KEY}`;
-    const res = await fetch(url, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ token: customToken, returnSecureToken: true }),
-    });
-    if (!res.ok) {
-        const text = await res.text();
-        throw new Error(`Token exchange failed (${res.status}): ${text}`);
-    }
-    const data = await res.json();
-    return { idToken: data.idToken, expiresIn: parseInt(data.expiresIn, 10) };
+function normalizeRTDBPath(path) {
+    return path.startsWith('/') ? path : `/${path}`;
 }
-/** Get a valid ID token for RTDB REST, refreshing if expired or expiring soon. */
-async function getToken() {
-    // Refresh if missing, expired, or expiring within 5 minutes
-    if (!cachedIdToken || Date.now() > idTokenExpiresAt - 5 * 60 * 1000) {
-        if (!tokenClient)
+function createRTDBClientHandle(client, options) {
+    const rtdbBase = normalizeRTDBBase(options?.rtdbUrl || DEFAULT_RTDB_BASE);
+    const firebaseApiKey = options?.firebaseApiKey || DEFAULT_FIREBASE_API_KEY;
+    let cachedIdToken = null;
+    let idTokenExpiresAt = 0;
+    let refreshPromise = null;
+    async function exchangeCustomTokenForIdToken(customToken) {
+        const url = `https://identitytoolkit.googleapis.com/v1/accounts:signInWithCustomToken?key=${firebaseApiKey}`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ token: customToken, returnSecureToken: true }),
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`Token exchange failed (${res.status}): ${text}`);
+        }
+        const data = await res.json();
+        return {
+            idToken: data.idToken,
+            expiresIn: Number.parseInt(data.expiresIn, 10),
+        };
+    }
+    async function getToken(forceRefresh = false) {
+        const now = Date.now();
+        if (!forceRefresh && cachedIdToken && now <= idTokenExpiresAt - 5 * 60 * 1000) {
+            return cachedIdToken;
+        }
+        if (refreshPromise) {
+            return refreshPromise;
+        }
+        const staleToken = forceRefresh ? null : cachedIdToken;
+        refreshPromise = (async () => {
+            try {
+                const auth = await client.getAuthToken();
+                const { idToken, expiresIn } = await exchangeCustomTokenForIdToken(auth.token);
+                cachedIdToken = idToken;
+                idTokenExpiresAt = Date.now() + (expiresIn * 1000);
+                return cachedIdToken;
+            }
+            catch (err) {
+                console.error('[canon] RTDB token refresh failed:', err);
+                return staleToken;
+            }
+            finally {
+                refreshPromise = null;
+            }
+        })();
+        return refreshPromise;
+    }
+    async function request(method, path, data, options = {}) {
+        const token = await getToken(false);
+        if (!token)
             return null;
+        const url = `${rtdbBase}${normalizeRTDBPath(path)}.json?auth=${encodeURIComponent(token)}`;
+        const res = await fetch(url, {
+            method,
+            ...(method === 'GET'
+                ? {}
+                : {
+                    headers: { 'Content-Type': 'application/json' },
+                    ...(data === undefined ? {} : { body: JSON.stringify(data) }),
+                }),
+        });
+        if (options.retryUnauthorized !== false
+            && (res.status === 401 || res.status === 403)) {
+            cachedIdToken = null;
+            idTokenExpiresAt = 0;
+            const refreshedToken = await getToken(true);
+            if (!refreshedToken) {
+                return res;
+            }
+            const retryUrl = `${rtdbBase}${normalizeRTDBPath(path)}.json?auth=${encodeURIComponent(refreshedToken)}`;
+            return fetch(retryUrl, {
+                method,
+                ...(method === 'GET'
+                    ? {}
+                    : {
+                        headers: { 'Content-Type': 'application/json' },
+                        ...(data === undefined ? {} : { body: JSON.stringify(data) }),
+                    }),
+            });
+        }
+        return res;
+    }
+    async function requireSuccess(method, path, data, errorPrefix) {
+        const res = await request(method, path, data);
+        if (!res)
+            return;
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`${errorPrefix} (${res.status}): ${text}`);
+        }
+    }
+    async function read(path) {
+        const res = await request('GET', path);
+        if (!res?.ok)
+            return null;
+        return res.json();
+    }
+    async function write(path, data) {
+        await requireSuccess('PUT', path, data, 'RTDB write failed');
+    }
+    async function patch(path, data) {
+        await requireSuccess('PATCH', path, data, 'RTDB patch failed');
+    }
+    async function remove(path) {
+        await requireSuccess('DELETE', path, undefined, 'RTDB delete failed');
+    }
+    async function writeSessionStateImpl(conversationId, agentId, state) {
+        await write(`/session-state/${conversationId}/${agentId}`, {
+            ...state,
+            updatedAt: { '.sv': 'timestamp' },
+        });
+    }
+    async function clearSessionStateImpl(conversationId, agentId) {
         try {
-            const auth = await tokenClient.getAuthToken();
-            const { idToken, expiresIn } = await exchangeCustomTokenForIdToken(auth.token);
-            cachedIdToken = idToken;
-            idTokenExpiresAt = Date.now() + expiresIn * 1000;
+            await write(`/session-state/${conversationId}/${agentId}`, {
+                isActive: false,
+                updatedAt: { '.sv': 'timestamp' },
+            });
         }
-        catch (err) {
-            console.error('[canon] RTDB token refresh failed:', err);
-            return cachedIdToken; // Return stale token as fallback
+        catch (error) {
+            console.error('[canon] RTDB clear failed:', error);
         }
     }
-    return cachedIdToken;
+    async function writeTurnStateImpl(conversationId, agentId, state) {
+        await write(`/turn-state/${conversationId}/${agentId}`, {
+            ...state,
+            updatedAt: { '.sv': 'timestamp' },
+        });
+    }
+    async function clearTurnStateImpl(conversationId, agentId) {
+        try {
+            await write(`/turn-state/${conversationId}/${agentId}`, {
+                state: 'idle',
+                queueDepth: 0,
+                updatedAt: { '.sv': 'timestamp' },
+                completedAt: { '.sv': 'timestamp' },
+            });
+        }
+        catch (error) {
+            console.error('[canon] RTDB turn clear failed:', error);
+        }
+    }
+    return {
+        read,
+        write,
+        patch,
+        remove,
+        writeSessionState: writeSessionStateImpl,
+        clearSessionState: clearSessionStateImpl,
+        writeTurnState: writeTurnStateImpl,
+        clearTurnState: clearTurnStateImpl,
+    };
+}
+/**
+ * Initializes the default RTDB helper and returns a scoped client for callers
+ * that need per-runtime auth and base-url isolation.
+ */
+export function initRTDBAuth(client, options) {
+    const scopedClient = createRTDBClientHandle(client, options);
+    defaultRTDBClient = scopedClient;
+    return scopedClient;
+}
+function getDefaultRTDBClient() {
+    return defaultRTDBClient;
 }
 // ── RTDB operations ───────────────────────────────────────────────────
 /** Generic RTDB REST write (PUT). */
 export async function rtdbWrite(path, data) {
-    const token = await getToken();
-    if (!token)
-        return;
-    const url = `${RTDB_BASE}${path}.json?auth=${token}`;
-    const res = await fetch(url, {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(data),
-    });
-    if (!res.ok) {
-        const text = await res.text();
-        throw new Error(`RTDB write failed (${res.status}): ${text}`);
-    }
+    await getDefaultRTDBClient()?.write(path, data);
 }
 /** Generic RTDB REST read (GET). */
 export async function rtdbRead(path) {
-    const token = await getToken();
-    if (!token)
-        return null;
-    const url = `${RTDB_BASE}${path}.json?auth=${token}`;
-    const res = await fetch(url);
-    if (!res.ok)
-        return null;
-    return res.json();
+    return getDefaultRTDBClient()?.read(path) ?? null;
 }
 /**
  * Write session state to RTDB via REST API.
  * Path: /session-state/{conversationId}/{agentId}
  */
 export async function writeSessionState(conversationId, agentId, state) {
-    const token = await getToken();
-    if (!token)
-        return;
-    const url = `${RTDB_BASE}/session-state/${conversationId}/${agentId}.json?auth=${token}`;
-    const body = {
-        ...state,
-        updatedAt: { '.sv': 'timestamp' },
-    };
-    const res = await fetch(url, {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
-    });
-    if (!res.ok) {
-        const text = await res.text();
-        throw new Error(`RTDB write failed (${res.status}): ${text}`);
-    }
+    await getDefaultRTDBClient()?.writeSessionState(conversationId, agentId, state);
 }
 /**
  * Clear session state from RTDB (full overwrite with isActive: false).
  */
 export async function clearSessionState(conversationId, agentId) {
-    const token = await getToken();
-    if (!token)
-        return;
-    const url = `${RTDB_BASE}/session-state/${conversationId}/${agentId}.json?auth=${token}`;
-    const body = {
-        isActive: false,
-        updatedAt: { '.sv': 'timestamp' },
-    };
-    // Use PUT (not PATCH) to clear stale fields like model/cwd
-    const res = await fetch(url, {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
-    });
-    if (!res.ok) {
-        const text = await res.text();
-        console.error(`[canon] RTDB clear failed (${res.status}): ${text}`);
-    }
+    await getDefaultRTDBClient()?.clearSessionState(conversationId, agentId);
 }
 export async function writeTurnState(conversationId, agentId, state) {
-    const token = await getToken();
-    if (!token)
-        return;
-    const url = `${RTDB_BASE}/turn-state/${conversationId}/${agentId}.json?auth=${token}`;
-    const body = {
-        ...state,
-        updatedAt: { '.sv': 'timestamp' },
-    };
-    const res = await fetch(url, {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
-    });
-    if (!res.ok) {
-        const text = await res.text();
-        throw new Error(`RTDB write failed (${res.status}): ${text}`);
-    }
+    await getDefaultRTDBClient()?.writeTurnState(conversationId, agentId, state);
 }
 export async function clearTurnState(conversationId, agentId) {
-    const token = await getToken();
-    if (!token)
-        return;
-    const url = `${RTDB_BASE}/turn-state/${conversationId}/${agentId}.json?auth=${token}`;
-    const body = {
-        state: 'idle',
-        queueDepth: 0,
-        updatedAt: { '.sv': 'timestamp' },
-        completedAt: { '.sv': 'timestamp' },
-    };
-    const res = await fetch(url, {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
-    });
-    if (!res.ok) {
-        const text = await res.text();
-        console.error(`[canon] RTDB turn clear failed (${res.status}): ${text}`);
-    }
+    await getDefaultRTDBClient()?.clearTurnState(conversationId, agentId);
 }

package/dist/types.d.ts

@@ -1,5 +1,7 @@
+import type { ExecutionEnvironmentMode } from './execution-environment-mode.js';
 import type { ResolvedAgentBehaviorPolicy } from './policy.js';
 import type { CanonWorkSessionContext } from './work-session.js';
+export type { ExecutionEnvironmentMode };
 export type MediaAttachmentKind = 'image' | 'audio' | 'file';
 export interface MediaAttachment {
     kind: MediaAttachmentKind;
@@ -11,6 +13,10 @@ export interface MediaAttachment {
     height?: number;
     durationMs?: number;
 }
+export interface ForwardedFrom {
+    sourceConversationId: string;
+    messageId: string;
+}
 export interface CanonMessage {
     id: string;
     senderId: string;
@@ -19,13 +25,12 @@ export interface CanonMessage {
     isOwner: boolean;
     contentType: 'text' | 'image' | 'audio' | 'file' | 'contact_card';
     text: string | null;
-    imageUrl: string | null;
-    audioUrl: string | null;
-    audioDurationMs: number | null;
-    attachments?: MediaAttachment[];
+    attachments: MediaAttachment[];
     mentions: string[];
     replyTo: string | null;
     replyToPosition: number | null;
+    forwarded?: boolean;
+    forwardedFrom?: ForwardedFrom;
     workSession?: CanonWorkSessionContext | null;
     metadata?: Record<string, unknown>;
     status: 'sent' | 'read';
@@ -59,6 +64,12 @@ export type AgentClientType = 'claude-code' | 'openclaw' | 'codex' | 'generic';
 export interface AgentCapabilities {
     supportsModelSwitch: boolean;
     supportsPermissionMode: boolean;
+    /**
+     * Whether permissionMode can be changed mid-session. When undefined,
+     * defaults to `supportsPermissionMode` — keep the UI chip non-interactive
+     * for agents whose approval mode is locked at session creation.
+     */
+    supportsRuntimePermissionMode?: boolean;
     supportsEffort: boolean;
     supportsSessionState: boolean;
     supportsInterrupt: boolean;
@@ -101,12 +112,11 @@ export interface MessageCreatedPayload {
         isOwner?: boolean;
         text?: string;
         contentType?: 'text' | 'image' | 'audio' | 'file' | 'contact_card';
-        imageUrl?: string;
-        audioUrl?: string;
-        audioDurationMs?: number;
         attachments?: MediaAttachment[];
         replyTo?: string;
         replyToPosition?: number;
+        forwarded?: boolean;
+        forwardedFrom?: ForwardedFrom;
         mentions?: string[];
         createdAt?: string;
         workSession?: CanonWorkSessionContext | null;
@@ -128,9 +138,6 @@ export interface SendMessageOptions {
     contentType?: 'text' | 'audio' | 'image' | 'file' | 'contact_card';
     replyTo?: string;
     replyToPosition?: number;
-    audioUrl?: string;
-    audioDurationMs?: number;
-    imageUrl?: string;
     attachments?: MediaAttachment[];
     contactCardUserId?: string;
     mentions?: string[];
@@ -186,16 +193,39 @@ export interface SessionConfig {
     model?: string;
     permissionMode?: string;
     workspaceId?: string;
+    /**
+     * Explicitly selected execution mode. Sessions created before this field
+     * existed stay `undefined`; UIs must prompt for a value and plugin hosts
+     * fail-closed rather than inferring one.
+     */
+    executionMode?: ExecutionEnvironmentMode;
     availableModels?: ModelOption[];
     workspaceOptions?: WorkspaceOption[];
+    availableExecutionModes?: ExecutionEnvironmentMode[];
     updatedAt?: number;
 }
+export interface PermissionModeOption {
+    value: string;
+    label: string;
+}
 export interface AgentRuntime {
     clientType?: AgentClientType;
     hostMode?: boolean;
     defaultModel?: string;
     defaultPermissionMode?: string;
+    availablePermissionModes?: PermissionModeOption[];
     defaultWorkspaceId?: string;
+    /**
+     * Execution modes the host will accept. The runtime advertises this so the
+     * app can offer matching choices; it is NOT used to auto-populate missing
+     * session-config values.
+     */
+    availableExecutionModes?: ExecutionEnvironmentMode[];
+    /**
+     * Reference default surfaced to UI. Treated as advisory only — callers must
+     * still have the user confirm a selection before persisting.
+     */
+    defaultExecutionMode?: ExecutionEnvironmentMode;
     availableModels?: ModelOption[];
     availableWorkspaces?: WorkspaceOption[];
     updatedAt?: number;

package/dist/types.js

@@ -12,6 +12,7 @@ export const AGENT_CAPABILITIES = {
     'claude-code': {
         supportsModelSwitch: true,
         supportsPermissionMode: true,
+        supportsRuntimePermissionMode: true,
         supportsEffort: true,
         supportsSessionState: true,
         supportsInterrupt: true,
@@ -20,7 +21,8 @@ export const AGENT_CAPABILITIES = {
     },
     'codex': {
         supportsModelSwitch: false,
-        supportsPermissionMode: false,
+        supportsPermissionMode: true,
+        supportsRuntimePermissionMode: false,
         supportsEffort: false,
         supportsSessionState: true,
         supportsInterrupt: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonmsg/core",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Canon core — shared types, REST client, SSE stream, and registration for Canon messaging",
   "type": "module",
   "main": "dist/index.js",
@@ -8,10 +8,12 @@
   "exports": {
     ".": {
       "import": "./dist/index.js",
+      "default": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
     "./browser": {
       "import": "./dist/browser.js",
+      "default": "./dist/browser.js",
       "types": "./dist/browser.d.ts"
     }
   },