livedesk 0.1.451 → 0.1.453

package/client/bin/livedesk-client.js

@@ -47,8 +47,7 @@ const FRESH_REGISTRY_TIMEOUT_MAX_MS = 10000;
 // polling must stay interactive instead of backing off to multi-minute waits.
 const DISCOVERY_RETRY_SCHEDULE_MS = [750, 750, 750, 750, 750, 750, 750, 750, 5000];
 const DISCOVERY_RETRY_JITTER_RATIO = 0.2;
-const HUB_WAKE_QUERY_JITTER_MAX_MS = 2000;
-const EXIT_INVALID_PAIR_TOKEN = 23;
+const EXIT_INVALID_PAIR_TOKEN = 23;
 const EXIT_CLIENT_UPDATE = 42;
 const SESSION_REFRESH_SKEW_SECONDS = 60;
 const HUB_TARGET_CACHE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
@@ -2706,9 +2705,10 @@ export async function resolveManagerFromPin(supabase, pin, options = {}) {
         allowRelayFallback: options.allowRelayFallback === true,
         relayEndpoint: options.relayEndpoint,
         probeEndpoint: options.probeEndpoint,
-        resolveFreshTarget: async () => {
+        resolveFreshTarget: async signal => {
             const { data, error } = await supabase.functions.invoke('livedesk-resolve-remote-host', {
-                body: { pin: normalizedPin }
+                body: { pin: normalizedPin },
+                signal
             });
             if (error) {
                 throw await normalizePinResolverInvocationError(error);
@@ -3667,28 +3667,73 @@ export function resolveManagerFromCachedRelayFallback(ownerKey, options = {}) {
     };
 }
 
+function normalizeFreshRegistryTimeoutMs(value) {
+    const configured = Number(value);
+    return Number.isFinite(configured)
+        ? Math.max(FRESH_REGISTRY_TIMEOUT_MIN_MS, Math.min(FRESH_REGISTRY_TIMEOUT_MAX_MS, configured))
+        : FRESH_REGISTRY_TIMEOUT_MS;
+}
+
+export async function runFreshHubRegistryLookup(resolveFreshTarget, options = {}) {
+    if (typeof resolveFreshTarget !== 'function') {
+        throw createHubDiscoveryError(
+            'fresh-registry-resolver-required',
+            'Fresh Hub registry resolver is required.'
+        );
+    }
+    const timeoutMs = normalizeFreshRegistryTimeoutMs(options.timeoutMs);
+    const controller = new AbortController();
+    let timeoutHandle = null;
+    const lookupOutcome = Promise.resolve()
+        .then(() => resolveFreshTarget(controller.signal))
+        .then(
+            target => ({ type: 'target', target }),
+            error => ({ type: 'error', error })
+        );
+    const timeoutOutcome = new Promise(resolveTimeout => {
+        timeoutHandle = setTimeout(
+            () => resolveTimeout({ type: 'timeout' }),
+            timeoutMs
+        );
+    });
+    const outcomes = [lookupOutcome, timeoutOutcome];
+    if (options.wakePromise && typeof options.wakePromise.then === 'function') {
+        outcomes.push(Promise.resolve(options.wakePromise).then(
+            event => ({ type: 'hub-online', event }),
+            () => new Promise(() => {})
+        ));
+    }
+    const outcome = await Promise.race(outcomes).finally(() => {
+        clearTimeout(timeoutHandle);
+    });
+    if (outcome.type === 'hub-online') {
+        controller.abort('hub-online');
+        return outcome;
+    }
+    if (outcome.type === 'timeout') {
+        controller.abort('hub-registry-timeout');
+        throw createHubDiscoveryError(
+            'hub-registry-timeout',
+            `Fresh LiveDesk Hub registry lookup exceeded ${timeoutMs}ms.`
+        );
+    }
+    if (outcome.type === 'error') {
+        controller.abort('hub-registry-error');
+        throw outcome.error;
+    }
+    return outcome;
+}
+
 export async function resolveManagerWithCachedRecovery(ownerKey, options = {}) {
     const cached = Object.prototype.hasOwnProperty.call(options, 'cachedTarget')
         ? normalizeCachedHubTarget(options.cachedTarget, ownerKey, options.now)
         : readCachedHubTarget(ownerKey);
     try {
-        if (typeof options.resolveFreshTarget !== 'function') {
-            throw createHubDiscoveryError('fresh-registry-resolver-required', 'Fresh Hub registry resolver is required.');
-        }
-        const configuredFreshTimeoutMs = Number(options.freshTimeoutMs);
-        const freshTimeoutMs = Number.isFinite(configuredFreshTimeoutMs)
-            ? Math.max(FRESH_REGISTRY_TIMEOUT_MIN_MS, Math.min(FRESH_REGISTRY_TIMEOUT_MAX_MS, configuredFreshTimeoutMs))
-            : FRESH_REGISTRY_TIMEOUT_MS;
-        let timeoutHandle = null;
-        const fresh = await Promise.race([
-            Promise.resolve().then(() => options.resolveFreshTarget()),
-            new Promise((_, reject) => {
-                timeoutHandle = setTimeout(() => reject(createHubDiscoveryError(
-                    'hub-registry-timeout',
-                    `Fresh LiveDesk Hub registry lookup exceeded ${freshTimeoutMs}ms.`
-                )), freshTimeoutMs);
-            })
-        ]).finally(() => clearTimeout(timeoutHandle));
+        const freshOutcome = await runFreshHubRegistryLookup(
+            options.resolveFreshTarget,
+            { timeoutMs: options.freshTimeoutMs }
+        );
+        const fresh = freshOutcome.target;
         if (!fresh?.manager || !fresh?.pair) {
             throw createHubDiscoveryError('fresh-registry-target-invalid', 'Fresh Hub registry target is incomplete.');
         }
@@ -3770,12 +3815,21 @@ function normalizeEndpointCandidates(target) {
 }
 
 export async function resolveManagerFromSupabase(supabase, options = {}) {
-    await refreshSessionIfNeeded(supabase);
-    const { data, error } = await supabase
-        .from('livedesk_remote_host_targets')
-        .select('node_id, endpoint, endpoint_candidates, pair_token, active, expires_at, updated_at, manager_version')
-        .eq('product_key', 'livedesk')
-        .maybeSingle();
+    if (options.signal?.aborted) {
+        throw createHubDiscoveryError('hub-registry-aborted', 'LiveDesk Hub registry lookup was cancelled.');
+    }
+    await refreshSessionIfNeeded(supabase);
+    if (options.signal?.aborted) {
+        throw createHubDiscoveryError('hub-registry-aborted', 'LiveDesk Hub registry lookup was cancelled.');
+    }
+    let query = supabase
+        .from('livedesk_remote_host_targets')
+        .select('node_id, endpoint, endpoint_candidates, pair_token, active, expires_at, updated_at, manager_version')
+        .eq('product_key', 'livedesk');
+    if (options.signal && typeof query.abortSignal === 'function') {
+        query = query.abortSignal(options.signal);
+    }
+    const { data, error } = await query.maybeSingle();
     if (error) {
         throw error;
     }
@@ -3849,9 +3903,12 @@ async function registerClientDeviceWithSupabase(supabase, options = {}) {
     }
 }
 
-async function waitForManagerFromSupabase(supabase, options = {}) {
+export async function waitForManagerFromSupabase(supabase, options = {}) {
     const configuredIntervalMs = Number(options.intervalMs || 0);
     const shouldStop = typeof options.shouldStop === 'function' ? options.shouldStop : () => false;
+    const createWakeListener = typeof options.createWakeListener === 'function'
+        ? options.createWakeListener
+        : createHubWakeListener;
     let attempts = 0;
     let lastMessage = '';
     let wakeListener = null;
@@ -3862,6 +3919,17 @@ async function waitForManagerFromSupabase(supabase, options = {}) {
             if (shouldStop()) {
                 return null;
             }
+            if (!wakeListener) {
+                try {
+                    wakeListener = await createWakeListener({
+                        getAccessToken: async () => (await refreshSessionIfNeeded(supabase))?.access_token || ''
+                    });
+                } catch (error) {
+                    if (attempts === 0) {
+                        console.warn(`[LiveDesk Client] Hub-online event channel unavailable; adaptive registry retries remain active: ${error?.message || error}`);
+                    }
+                }
+            }
             attempts += 1;
             try {
                 if (initialError) {
@@ -3869,9 +3937,24 @@ async function waitForManagerFromSupabase(supabase, options = {}) {
                     initialError = null;
                     throw error;
                 }
-                return await resolveManagerFromSupabase(supabase, {
-                    allowRelayFallback: options.allowRelayFallback === true
-                });
+                const outcome = await runFreshHubRegistryLookup(
+                    signal => resolveManagerFromSupabase(supabase, {
+                        allowRelayFallback: options.allowRelayFallback === true,
+                        probeEndpoint: options.probeEndpoint,
+                        signal
+                    }),
+                    {
+                        timeoutMs: options.freshTimeoutMs,
+                        wakePromise: wakeListener?.promise
+                    }
+                );
+                if (outcome.type === 'hub-online') {
+                    wakeListener?.close();
+                    wakeListener = null;
+                    console.log('[LiveDesk Client] Hub-online event received. Rechecking the registry now.');
+                    continue;
+                }
+                return outcome.target;
             } catch (err) {
                 const message = formatDiscoveryError(err);
                 if (message !== lastMessage || attempts === 1 || attempts % 6 === 0) {
@@ -3881,18 +3964,6 @@ async function waitForManagerFromSupabase(supabase, options = {}) {
                 }
             }
 
-            if (!wakeListener) {
-                try {
-                    wakeListener = await createHubWakeListener({
-                        getAccessToken: async () => (await refreshSessionIfNeeded(supabase))?.access_token || ''
-                    });
-                } catch (error) {
-                    if (attempts === 1) {
-                        console.warn(`[LiveDesk Client] Hub-online event channel unavailable; adaptive registry retries remain active: ${error?.message || error}`);
-                    }
-                }
-            }
-
             const trigger = await waitForDiscoveryTrigger(
                 getDiscoveryRetryDelay(attempts, configuredIntervalMs),
                 wakeListener?.promise,
@@ -3901,9 +3972,7 @@ async function waitForManagerFromSupabase(supabase, options = {}) {
             if (trigger.type === 'hub-online') {
                 wakeListener?.close();
                 wakeListener = null;
-                const jitterMs = Math.floor(Math.random() * (HUB_WAKE_QUERY_JITTER_MAX_MS + 1));
-                console.log(`[LiveDesk Client] Hub-online event received. Rechecking the registry in ${jitterMs}ms.`);
-                await waitForDiscoveryTrigger(jitterMs, null, shouldStop);
+                console.log('[LiveDesk Client] Hub-online event received. Rechecking the registry now.');
             }
         }
     } finally {
@@ -3993,7 +4062,7 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
                 resolved = await resolveManagerWithCachedRecovery(cacheOwnerKey, {
                     allowRelayFallback,
                     relayEndpoint: parsed.relay,
-                    resolveFreshTarget: async () => {
+                    resolveFreshTarget: async signal => {
                         // The signed registry is authoritative for Hub replacement
                         // and pair-token rotation. Cache direct/relay recovery is
                         // considered only after this one current lookup reports
@@ -4006,7 +4075,8 @@ async function prepareLoginConnection(parsed, existingConnectionPage = null) {
                             console.warn('[LiveDesk Client] Another auth owner rotated the refresh token. Keeping the runtime alive while the saved session catches up.');
                         }
                         return await resolveManagerFromSupabase(supabase, {
-                            allowRelayFallback
+                            allowRelayFallback,
+                            signal
                         });
                     }
                 });

package/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.206",
+  "version": "0.1.208",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -40,10 +40,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.412",
-    "@livedesk/fast-osx-arm64": "0.1.412",
-    "@livedesk/fast-osx-x64": "0.1.412",
-    "@livedesk/fast-win-x64": "0.1.412"
+    "@livedesk/fast-linux-x64": "0.1.413",
+    "@livedesk/fast-osx-arm64": "0.1.413",
+    "@livedesk/fast-osx-x64": "0.1.413",
+    "@livedesk/fast-win-x64": "0.1.413"
   },
   "publishConfig": {
     "access": "public"

package/hub/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "description": "LiveDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",

package/hub/src/agents/agent-manager.js

@@ -1,7 +1,7 @@
 import os from 'node:os';
 import path from 'node:path';
-import { AgentSettingsStore, AGENT_PROVIDER_CODEX } from './agent-settings.js';
-import { AgentProviderError } from './provider-errors.js';
+import { AgentSettingsStore } from './agent-settings.js';
+import { AgentRuntimeError } from './agent-runtime-error.js';
 
 function publicCodexStatus(status = {}) {
   return {
@@ -42,69 +42,22 @@ export function createAgentManager({
 
   async function publicSettings() {
     const current = await settings.get();
-    const {
-      codexMaxTurns: _codexMaxTurns,
-      provider: _provider,
-      ...exposedSettings
-    } = current;
     const codex = await getCodexStatus();
-    const securityStatus = runtime?.getSecurityStatus?.() || {
-      isolatedCodexHome: false,
-      restrictedEnvironment: false,
-      livedeskMcpOnly: false,
-      selectedDeviceScopeEnforced: false,
-      failClosed: true,
-      verified: false,
-      state: 'unavailable'
-    };
     return {
-      ...exposedSettings,
+      enabled: current.enabled === true,
       codexInstallation: codex.installed ? 'installed' : 'not-installed',
       codexAuth: codex.authenticated,
-      codexStatus: codex.status,
-      codexPath: codex.codexPath,
-      agentWorkspacePath: current.codexWorkingDirectory,
-      securityStatus
+      codexStatus: codex.status
     };
   }
 
   return {
     getSettings: publicSettings,
-    async updateSettings(patch = {}) {
-      const nextPatch = { ...patch };
-      const requestedProvider = String(nextPatch.provider || AGENT_PROVIDER_CODEX).trim().toLowerCase();
-      const suppliedLegacyKey = typeof nextPatch.apiKey === 'string' && nextPatch.apiKey.trim().length > 0;
-      delete nextPatch.provider;
-      delete nextPatch.apiKey;
-      if (requestedProvider !== AGENT_PROVIDER_CODEX || suppliedLegacyKey) {
-        throw new AgentProviderError(
-          'agent-provider-retired',
-          'LiveDesk uses the Hub-hosted Codex Agent and does not configure alternate model providers.',
-          { status: 400 }
-        );
-      }
-      await settings.update({ ...nextPatch, provider: AGENT_PROVIDER_CODEX });
-      statusCache = { expiresAt: 0, value: null };
-      return publicSettings();
-    },
-    async resetSettings() {
-      await settings.reset();
-      statusCache = { expiresAt: 0, value: null };
-      return publicSettings();
-    },
-    // Kept as a harmless compatibility endpoint for an older cached web UI.
-    // No credential is read, written, or returned by the current Hub.
-    async deleteApiKey() {
-      return publicSettings();
-    },
     async testConnection() {
-      if (!runtime) throw new AgentProviderError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
+      if (!runtime) throw new AgentRuntimeError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
       statusCache = { expiresAt: 0, value: null };
       return runtime.testConnection();
     },
-    async createPlan() {
-      throw new AgentProviderError('agent-codex-run-required', 'Codex Agent requests use the LiveDesk tool loop.', { status: 409 });
-    },
     async createSummary(input) {
       const source = input && typeof input === 'object' ? input : {};
       const results = Array.isArray(source.results) ? source.results : [];
@@ -113,9 +66,8 @@ export function createAgentManager({
       };
     },
     async startRun(input) {
-      const current = await settings.get();
-      if (current.provider !== AGENT_PROVIDER_CODEX || !runtime) {
-        throw new AgentProviderError('agent-codex-not-active', 'Codex SDK is not the active Agent runtime.', { status: 409 });
+      if (!runtime) {
+        throw new AgentRuntimeError('agent-codex-not-active', 'Codex SDK is not available for LiveDesk Agent commands.', { status: 409 });
       }
       return runtime.start(input);
     },

package/hub/src/agents/agent-runtime-error.js

@@ -0,0 +1,9 @@
+export class AgentRuntimeError extends Error {
+  constructor(code, message, { status = 502, retryable = false } = {}) {
+    super(message);
+    this.name = 'AgentRuntimeError';
+    this.code = code;
+    this.status = status;
+    this.retryable = retryable;
+  }
+}

package/hub/src/agents/agent-settings.js

@@ -2,23 +2,13 @@ import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-export const AGENT_PROVIDER_CODEX = 'codex';
-export const DEFAULT_AGENT_PROVIDER = AGENT_PROVIDER_CODEX;
-export const DEFAULT_AGENT_WORKSPACE = path.join(os.homedir(), '.livedesk', 'agent-workspace');
 export const DEFAULT_AGENT_SETTINGS = Object.freeze({
-  settingsVersion: 4,
+  settingsVersion: 5,
   enabled: true,
-  provider: DEFAULT_AGENT_PROVIDER,
-  codexSandboxMode: 'read-only',
-  codexApprovalPolicy: 'never',
-  codexWorkingDirectory: DEFAULT_AGENT_WORKSPACE,
   codexTaskTimeoutMs: 600000,
   codexMaxTurns: 12,
   codexMaxToolCalls: 20,
   codexResumeSessions: true,
-  codexShowDetailedEvents: true,
-  codexNetworkAccessEnabled: false,
-  codexWebSearchMode: 'disabled',
   maxConcurrentRequests: 2
 });
 
@@ -33,32 +23,15 @@ function numberValue(value, min, max, fallback, integer = false) {
   return integer ? Math.round(clamped) : clamped;
 }
 
-function normalizeWorkingDirectory() {
-  // The agent runtime owns this directory. Do not allow a browser/API caller
-  // to move Codex into a user project or an arbitrary filesystem root.
-  return DEFAULT_AGENT_WORKSPACE;
-}
-
 export function normalizeAgentSettings(value = {}) {
   const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
   return {
-    settingsVersion: 4,
+    settingsVersion: 5,
     enabled: booleanValue(source.enabled, DEFAULT_AGENT_SETTINGS.enabled),
-    // LiveDesk has one Agent runtime. Old provider values are deliberately
-    // normalized to Codex so an upgrade cannot reactivate a retired provider.
-    provider: AGENT_PROVIDER_CODEX,
-    // These are safety settings, not user-controlled execution toggles. They
-    // are accepted for compatibility but always normalized to the safe floor.
-    codexSandboxMode: 'read-only',
-    codexApprovalPolicy: 'never',
-    codexWorkingDirectory: normalizeWorkingDirectory(),
     codexTaskTimeoutMs: numberValue(source.codexTaskTimeoutMs, 30000, 1800000, DEFAULT_AGENT_SETTINGS.codexTaskTimeoutMs, true),
     codexMaxTurns: numberValue(source.codexMaxTurns, 1, 40, DEFAULT_AGENT_SETTINGS.codexMaxTurns, true),
     codexMaxToolCalls: numberValue(source.codexMaxToolCalls, 1, 100, DEFAULT_AGENT_SETTINGS.codexMaxToolCalls, true),
     codexResumeSessions: booleanValue(source.codexResumeSessions, DEFAULT_AGENT_SETTINGS.codexResumeSessions),
-    codexShowDetailedEvents: booleanValue(source.codexShowDetailedEvents, DEFAULT_AGENT_SETTINGS.codexShowDetailedEvents),
-    codexNetworkAccessEnabled: false,
-    codexWebSearchMode: 'disabled',
     maxConcurrentRequests: numberValue(source.maxConcurrentRequests, 1, 8, DEFAULT_AGENT_SETTINGS.maxConcurrentRequests, true)
   };
 }
@@ -95,10 +68,4 @@ export class AgentSettingsStore {
     return { ...next };
   }
 
-  async reset() {
-    const next = normalizeAgentSettings(DEFAULT_AGENT_SETTINGS);
-    await writeJsonAtomic(this.filePath, next);
-    this.settings = next;
-    return { ...next };
-  }
 }

package/hub/src/agents/codex-agent-runtime.js

@@ -4,7 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-import { AgentProviderError } from './provider-errors.js';
+import { AgentRuntimeError } from './agent-runtime-error.js';
 import { AGENT_TOOL_NAMES } from './agent-tool-registry.js';
 import { createAgentPermissionPolicy, hashAgentPermissionPolicy } from './agent-permissions.js';
 
@@ -57,12 +57,12 @@ function isAbortError(error) {
 
 function normalizeCodexError(error) {
   const message = safeText(error?.message, 800) || 'Codex run failed.';
-  if (error instanceof AgentProviderError && error.code !== 'codex-run-failed') return error;
-  if (/out of credits|usage limit|rate limit|too many requests/i.test(message)) return new AgentProviderError('codex-usage-limit-reached', 'The Codex workspace has no remaining usage.', { status: 402, retryable: true });
-  if (/refresh[_ -]?token[_ -]?(?:already[_ -]?)?used|token refresh|refresh credential/i.test(message)) return new AgentProviderError('codex-auth-stale', 'The saved Codex sign-in is stale. LiveDesk refreshed its Codex authentication bridge and will retry.', { status: 401, retryable: true });
-  if (/not authenticated|not logged in|authentication|unauthorized|login required/i.test(message)) return new AgentProviderError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
-  if (/user cancelled MCP tool call/i.test(message)) return new AgentProviderError('codex-mcp-tool-rejected', 'Codex rejected the LiveDesk MCP tool before it reached the Hub.', { status: 502 });
-  return new AgentProviderError('codex-run-failed', message, { status: 502, retryable: true });
+  if (error instanceof AgentRuntimeError && error.code !== 'codex-run-failed') return error;
+  if (/out of credits|usage limit|rate limit|too many requests/i.test(message)) return new AgentRuntimeError('codex-usage-limit-reached', 'The Codex workspace has no remaining usage.', { status: 402, retryable: true });
+  if (/refresh[_ -]?token[_ -]?(?:already[_ -]?)?used|token refresh|refresh credential/i.test(message)) return new AgentRuntimeError('codex-auth-stale', 'The saved Codex sign-in is stale. LiveDesk refreshed its Codex authentication bridge and will retry.', { status: 401, retryable: true });
+  if (/not authenticated|not logged in|authentication|unauthorized|login required/i.test(message)) return new AgentRuntimeError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
+  if (/user cancelled MCP tool call/i.test(message)) return new AgentRuntimeError('codex-mcp-tool-rejected', 'Codex rejected the LiveDesk MCP tool before it reached the Hub.', { status: 502 });
+  return new AgentRuntimeError('codex-run-failed', message, { status: 502, retryable: true });
 }
 
 function codexThreadOptions(workspace) {
@@ -164,16 +164,16 @@ async function ensureCodexHome(codexHome, globalCodexHome, { preferGlobalAuth =
   const resolvedHome = path.resolve(codexHome);
   const globalHome = path.resolve(globalCodexHome);
   if (!resolvedHome || resolvedHome === globalHome) {
-    throw new AgentProviderError('codex-isolation-unavailable', 'Codex requires a dedicated LiveDesk home.', { status: 503 });
+    throw new AgentRuntimeError('codex-isolation-unavailable', 'Codex requires a dedicated LiveDesk home.', { status: 503 });
   }
   try {
     await mkdir(resolvedHome, { recursive: true, mode: 0o700 });
     if (await access(path.join(resolvedHome, 'config.toml')).then(() => true, () => false)) {
-      throw new AgentProviderError('codex-environment-isolation-failed', 'The dedicated Codex home contains an unmanaged config.toml.', { status: 503 });
+      throw new AgentRuntimeError('codex-environment-isolation-failed', 'The dedicated Codex home contains an unmanaged config.toml.', { status: 503 });
     }
   } catch (error) {
-    if (error instanceof AgentProviderError) throw error;
-    const wrapped = new AgentProviderError('codex-environment-isolation-failed', 'The dedicated Codex home could not be prepared.', { status: 503 });
+    if (error instanceof AgentRuntimeError) throw error;
+    const wrapped = new AgentRuntimeError('codex-environment-isolation-failed', 'The dedicated Codex home could not be prepared.', { status: 503 });
     wrapped.cause = error;
     throw wrapped;
   }
@@ -200,7 +200,7 @@ async function ensureCodexHome(codexHome, globalCodexHome, { preferGlobalAuth =
       await replaceAuthHardLink(sourceAuthPath, targetAuthPath);
     }
   } catch (error) {
-    const wrapped = new AgentProviderError('codex-environment-isolation-failed', 'The Codex authentication bridge could not be prepared.', { status: 503 });
+    const wrapped = new AgentRuntimeError('codex-environment-isolation-failed', 'The Codex authentication bridge could not be prepared.', { status: 503 });
     wrapped.cause = error;
     throw wrapped;
   }
@@ -243,7 +243,7 @@ function runAgeMs(run) {
 }
 
 function codexAbortError(code, message) {
-  return new AgentProviderError(code, message, { status: code === 'codex-run-timeout' ? 504 : 409, retryable: code === 'codex-run-timeout' });
+  return new AgentRuntimeError(code, message, { status: code === 'codex-run-timeout' ? 504 : 409, retryable: code === 'codex-run-timeout' });
 }
 
 function safeAgentDeviceIds(value) {
@@ -331,7 +331,7 @@ export function createCodexAgentRuntime({
   function assertSecurityConfiguration() {
     const status = securityStatus();
     if (!status.isolatedCodexHome || !status.restrictedEnvironment || !status.livedeskMcpOnly || !status.selectedDeviceScopeEnforced) {
-      throw new AgentProviderError('codex-unsupported-security-config', 'Codex security isolation is not available.', { status: 503 });
+      throw new AgentRuntimeError('codex-unsupported-security-config', 'Codex security isolation is not available.', { status: 503 });
     }
   }
 
@@ -364,7 +364,7 @@ export function createCodexAgentRuntime({
 
   async function loadCodex() {
     if (!codexModulePromise) codexModulePromise = import('@openai/codex-sdk').catch(error => {
-      const wrapped = new AgentProviderError('codex-sdk-not-installed', 'Codex SDK is not installed in this LiveDesk package.', { status: 503 });
+      const wrapped = new AgentRuntimeError('codex-sdk-not-installed', 'Codex SDK is not installed in this LiveDesk package.', { status: 503 });
       wrapped.cause = error;
       throw wrapped;
     });
@@ -395,7 +395,7 @@ export function createCodexAgentRuntime({
         ? 'signed-in'
         : 'not-signed-in';
     } catch (error) {
-      if (error instanceof AgentProviderError) throw error;
+      if (error instanceof AgentRuntimeError) throw error;
       detail = safeText(error?.message, 300);
     }
     return { installed: true, authenticated, status: authenticated === 'signed-in' ? 'ready' : 'auth-required', codexPath: pathToCli, detail };
@@ -405,8 +405,8 @@ export function createCodexAgentRuntime({
     assertSecurityConfiguration();
     const startedAt = Date.now();
     const status = await getStatus();
-    if (!status.installed) throw new AgentProviderError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
-    if (status.authenticated !== 'signed-in') throw new AgentProviderError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
+    if (!status.installed) throw new AgentRuntimeError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
+    if (status.authenticated !== 'signed-in') throw new AgentRuntimeError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
     const settings = await settingsStore.get();
     await mkdir(workspace, { recursive: true });
     await prepareCodexHome();
@@ -416,7 +416,7 @@ export function createCodexAgentRuntime({
     try {
       const thread = codex.startThread(codexThreadOptions(workspace));
       const turn = await thread.run('Reply with the single word READY. Do not use tools.', { signal: controller.signal });
-      if (!String(turn.finalResponse || '').trim()) throw new AgentProviderError('codex-empty-response', 'Codex returned an empty response.', { status: 502 });
+      if (!String(turn.finalResponse || '').trim()) throw new AgentRuntimeError('codex-empty-response', 'Codex returned an empty response.', { status: 502 });
       return { ok: true, latencyMs: Date.now() - startedAt, threadId: thread.id || '' };
     } catch (error) {
       throw normalizeCodexError(error);
@@ -492,15 +492,15 @@ export function createCodexAgentRuntime({
       timeoutTimer.unref?.();
       await mkdir(workspace, { recursive: true });
       if (activeCount > settings.maxConcurrentRequests) {
-        throw new AgentProviderError('agent-concurrency-limit', 'The LiveDesk Agent concurrency limit is reached.', { status: 429, retryable: true });
+        throw new AgentRuntimeError('agent-concurrency-limit', 'The LiveDesk Agent concurrency limit is reached.', { status: 429, retryable: true });
       }
       if (run.abortController.signal.aborted) {
         if (run.abortReason === 'timeout') throw codexAbortError('codex-run-timeout', 'The Codex task exceeded its timeout.');
         throw Object.assign(new Error('The Codex task was cancelled.'), { name: 'AbortError' });
       }
       const status = await getStatus();
-      if (!status.installed) throw new AgentProviderError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
-      if (status.authenticated !== 'signed-in') throw new AgentProviderError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
+      if (!status.installed) throw new AgentRuntimeError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
+      if (status.authenticated !== 'signed-in') throw new AgentRuntimeError('codex-auth-required', 'Sign in with the Codex CLI first.', { status: 401 });
       reportProgress(run, 'preparing-tools', 'Codex is ready. Preparing the LiveDesk tools for this Client.');
       session = createMcpSession({
         runId: run.runId,
@@ -552,14 +552,14 @@ export function createCodexAgentRuntime({
                 run.abortReason = 'turn-limit';
                 run.abortController.abort();
                 session.cancel();
-                throw new AgentProviderError('codex-turn-limit-reached', 'Codex exceeded the LiveDesk turn limit.', { status: 409 });
+                throw new AgentRuntimeError('codex-turn-limit-reached', 'Codex exceeded the LiveDesk turn limit.', { status: 409 });
               }
             }
             if (run.toolCallCount > run.permissionPolicy.maxToolCalls) {
               run.abortReason = 'tool-limit';
               run.abortController.abort();
               session.cancel();
-              throw new AgentProviderError('codex-tool-limit-reached', 'Codex exceeded the LiveDesk tool-call limit.', { status: 409 });
+              throw new AgentRuntimeError('codex-tool-limit-reached', 'Codex exceeded the LiveDesk tool-call limit.', { status: 409 });
             }
             if (event.type === 'item.completed' && event.item?.type === 'mcp_tool_call' && event.item?.status === 'failed') {
               throw new Error(safeText(event.item?.error?.message, 800) || `LiveDesk tool ${safeText(event.item?.tool, 120) || 'call'} failed.`);
@@ -641,14 +641,14 @@ export function createCodexAgentRuntime({
 
   async function start(input = {}) {
     const instruction = safeText(input.instruction, 4000);
-    if (!instruction) throw new AgentProviderError('agent-invalid-instruction', 'Instruction is required.', { status: 400 });
+    if (!instruction) throw new AgentRuntimeError('agent-invalid-instruction', 'Instruction is required.', { status: 400 });
     const deviceIds = safeAgentDeviceIds(input.deviceIds);
-    if (deviceIds.length === 0) throw new AgentProviderError('agent-no-target-devices', 'Select at least one connected device.', { status: 400 });
+    if (deviceIds.length === 0) throw new AgentRuntimeError('agent-no-target-devices', 'Select at least one connected device.', { status: 400 });
     const settings = await settingsStore.get();
-    if (!settings.enabled) throw new AgentProviderError('agent-ai-disabled', 'Codex Agent is disabled in Settings.', { status: 409 });
+    if (!settings.enabled) throw new AgentRuntimeError('agent-disabled', 'Codex Agent is disabled in Settings.', { status: 409 });
     assertSecurityConfiguration();
     pruneRuns();
-    if (runs.size >= MAX_RUNS) throw new AgentProviderError('agent-run-limit', 'The LiveDesk Agent run history is full.', { status: 429, retryable: true });
+    if (runs.size >= MAX_RUNS) throw new AgentRuntimeError('agent-run-limit', 'The LiveDesk Agent run history is full.', { status: 429, retryable: true });
     const permissionPolicy = freezeAgentPermissionPolicy(input.permissionPolicy && typeof input.permissionPolicy === 'object'
       ? input.permissionPolicy
       : createAgentPermissionPolicy({ mode: input.permissionMode || 'safe-auto', deviceIds, maxToolCalls: settings.codexMaxToolCalls }));