@livedesk/hub 0.1.3 → 0.1.5

package/README.md

@@ -1,15 +1,15 @@
-# @livedesk/hub
-
-Local LiveDesk Hub runtime.
-
-This package is used by the `livedesk` launcher package. Most users should run:
-
-```powershell
-npx -y livedesk
-```
-
-Mode 4 runs its Atlas compositor in a separate worker process. It consumes
-latest-only Mode 2 frames and exposes one H.264 wall stream at
-`/api/remote/atlas/ws`. The grid uses native 320x180 cells until the configured
-1920x1080 bound requires smaller cells; focused control continues to use direct
-Mode 3.
+# @livedesk/hub
+
+Local LiveDesk Hub runtime.
+
+This package is used by the `livedesk` launcher package. Most users should run:
+
+```powershell
+npx -y --prefer-online livedesk@latest
+```
+
+Mode 4 runs its Atlas compositor in a separate worker process. It consumes
+latest-only Mode 2 frames and exposes one H.264 wall stream at
+`/api/remote/atlas/ws`. The grid uses native 320x180 cells until the configured
+1920x1080 bound requires smaller cells; focused control continues to use direct
+Mode 3.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/hub",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "LiveDesk local Hub API and browser frame bridge",
   "type": "module",
   "main": "src/server.js",
@@ -15,6 +15,7 @@
   },
   "dependencies": {
     "@ffmpeg-installer/ffmpeg": "^1.1.0",
+    "@openai/codex-sdk": "0.145.0",
     "cors": "^2.8.5",
     "express": "^4.21.2",
     "ffmpeg-static": "^5.3.0",

package/src/agents/agent-audit-store.js

@@ -0,0 +1,93 @@
+import { appendFile, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import crypto from 'node:crypto';
+import os from 'node:os';
+import path from 'node:path';
+
+const MAX_AUDIT_RECORDS = 2000;
+const MAX_AUDIT_FILE_RECORDS = 2250;
+const MAX_AUDIT_FIELD = 4000;
+
+function safeText(value, max = MAX_AUDIT_FIELD) {
+  return String(value ?? '').replace(/[\0\r\n]/g, ' ').trim().slice(0, max);
+}
+
+function redact(value, depth = 0) {
+  if (depth > 4) return '[truncated]';
+  if (Array.isArray(value)) return value.slice(0, 100).map(item => redact(item, depth + 1));
+  if (!value || typeof value !== 'object') return typeof value === 'string' ? safeText(value) : value;
+  return Object.fromEntries(Object.entries(value).slice(0, 100).map(([key, child]) => [
+    key,
+    /content|command|script|token|secret|password|credential|api[-_]?key|authorization/i.test(key) ? '[redacted]' : redact(child, depth + 1)
+  ]));
+}
+
+export function createAgentAuditStore({ dataDir = path.join(os.homedir(), '.livedesk') } = {}) {
+  const filePath = path.join(dataDir, 'agent-audit.jsonl');
+  let records = null;
+  let rewriteNeeded = false;
+  let fileRecordCount = 0;
+  let writeQueue = Promise.resolve();
+
+  async function load() {
+    if (records) return records;
+    try {
+      const allLines = (await readFile(filePath, 'utf8')).split(/\r?\n/).filter(Boolean);
+      fileRecordCount = allLines.length;
+      rewriteNeeded = allLines.length > MAX_AUDIT_FILE_RECORDS;
+      records = allLines.slice(-MAX_AUDIT_RECORDS).map(line => JSON.parse(line)).filter(item => item && typeof item === 'object');
+    } catch {
+      records = [];
+    }
+    return records;
+  }
+
+  function normalize(event = {}) {
+    return {
+      auditId: safeText(event.auditId || crypto.randomUUID(), 100),
+      timestamp: new Date().toISOString(),
+      runId: safeText(event.runId, 100),
+      deviceIds: Array.isArray(event.deviceIds) ? [...new Set(event.deviceIds.map(item => safeText(item, 128)).filter(Boolean))].slice(0, 500) : [],
+      event: safeText(event.event, 100),
+      toolName: safeText(event.toolName, 120),
+      category: safeText(event.category, 80),
+      decision: safeText(event.decision, 40),
+      status: safeText(event.status, 40),
+      permissionMode: safeText(event.permissionMode, 40),
+      policyHash: safeText(event.policyHash, 100),
+      argumentsHash: safeText(event.argumentsHash, 100),
+      details: redact(event.details || {})
+    };
+  }
+
+  return {
+    async record(event) {
+      const record = normalize(event);
+      writeQueue = writeQueue.then(async () => {
+        const current = await load();
+        current.push(record);
+        fileRecordCount += 1;
+        if (current.length > MAX_AUDIT_RECORDS) {
+          current.splice(0, current.length - MAX_AUDIT_RECORDS);
+        }
+        if (fileRecordCount > MAX_AUDIT_FILE_RECORDS) rewriteNeeded = true;
+        await mkdir(path.dirname(filePath), { recursive: true });
+        if (rewriteNeeded) {
+          const tempPath = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+          await writeFile(tempPath, `${current.map(item => JSON.stringify(item)).join('\n')}\n`, { encoding: 'utf8', mode: 0o600 });
+          await rename(tempPath, filePath);
+          fileRecordCount = current.length;
+          rewriteNeeded = false;
+        } else {
+          await appendFile(filePath, `${JSON.stringify(record)}\n`, { encoding: 'utf8', mode: 0o600 });
+        }
+      });
+      await writeQueue;
+      return record;
+    },
+    async list({ runId = '', limit = 200 } = {}) {
+      const current = await load();
+      const normalizedLimit = Math.max(1, Math.min(500, Number(limit) || 200));
+      return current.filter(item => !runId || item.runId === String(runId)).slice(-normalizedLimit).reverse();
+    }
+  };
+}

package/src/agents/agent-device-scope.js

@@ -0,0 +1,29 @@
+function normalizeIds(value) {
+  const source = Array.isArray(value) ? value : [];
+  return [...new Set(source.map(item => String(item || '').trim()).filter(Boolean))].slice(0, 500);
+}
+
+export function createAgentDeviceScope(allowedDeviceIds, fallbackDeviceIds = []) {
+  const requested = normalizeIds(allowedDeviceIds);
+  const fallback = normalizeIds(fallbackDeviceIds);
+  return new Set(requested.length > 0 ? requested : fallback);
+}
+
+export function selectAgentDeviceIds({ allowedDeviceIds, requestedDeviceIds, connectedDeviceIds }) {
+  const allowed = allowedDeviceIds instanceof Set ? allowedDeviceIds : new Set(normalizeIds(allowedDeviceIds));
+  const requested = normalizeIds(requestedDeviceIds);
+  const connected = new Set(normalizeIds(connectedDeviceIds));
+  const candidates = requested.length > 0 ? requested : [...allowed];
+  return candidates.filter(deviceId => allowed.has(deviceId) && connected.has(deviceId));
+}
+
+export function resolveAgentTargetIds({ allowedDeviceIds, requestedDeviceIds, connectedDeviceIds }) {
+  const requested = normalizeIds(requestedDeviceIds);
+  const allowed = allowedDeviceIds instanceof Set ? allowedDeviceIds : new Set(normalizeIds(allowedDeviceIds));
+  const deviceIds = selectAgentDeviceIds({ allowedDeviceIds: allowed, requestedDeviceIds: requested, connectedDeviceIds });
+  if (deviceIds.length > 0) return { deviceIds, error: '' };
+  if (requested.length > 0 && requested.every(deviceId => !allowed.has(deviceId))) {
+    return { deviceIds: [], error: 'agent-target-outside-selection' };
+  }
+  return { deviceIds: [], error: 'agent-no-target-devices' };
+}

package/src/agents/agent-manager.js

@@ -0,0 +1,175 @@
+import os from 'node:os';
+import path from 'node:path';
+import { AgentSettingsStore, AGENT_PROVIDER_CODEX, AGENT_PROVIDER_OPENCODE_GO } from './agent-settings.js';
+import { createOsSecretStore } from './secret-store.js';
+import { createOpenCodeGoProvider } from './opencode-go-provider.js';
+import { AgentProviderError } from './provider-errors.js';
+import { createCodexAgentRuntime } from './codex-agent-runtime.js';
+
+function maskApiKey(value) {
+  const key = String(value || '');
+  return key.length >= 4 ? `••••${key.slice(-4)}` : '';
+}
+
+function publicCodexStatus(status = {}) {
+  return {
+    installed: status.installed === true,
+    authenticated: ['signed-in', 'not-signed-in'].includes(status.authenticated) ? status.authenticated : 'unknown',
+    status: String(status.status || 'unknown').slice(0, 40),
+    codexPath: String(status.codexPath || '').slice(0, 500),
+    detail: String(status.detail || '').slice(0, 300)
+  };
+}
+
+export function createAgentManager({
+  dataDir = path.join(os.homedir(), '.livedesk'),
+  settingsStore,
+  secretStore,
+  provider,
+  codexRuntime
+} = {}) {
+  const settings = settingsStore || new AgentSettingsStore({ dataDir });
+  const secrets = secretStore || createOsSecretStore({ dataDir });
+  const legacyProvider = provider || createOpenCodeGoProvider();
+  const runtime = codexRuntime;
+  let statusCache = { expiresAt: 0, value: null };
+
+  async function getCodexStatus() {
+    if (!runtime) return { installed: false, authenticated: 'unknown', status: 'unavailable', codexPath: '' };
+    if (statusCache.value && statusCache.expiresAt > Date.now()) return statusCache.value;
+    let value;
+    try {
+      value = publicCodexStatus(await runtime.getStatus());
+    } catch (error) {
+      value = publicCodexStatus({ installed: true, authenticated: 'unknown', status: error?.code || 'security-unavailable', detail: error?.message || 'Codex security isolation is unavailable.' });
+    }
+    statusCache = { value, expiresAt: Date.now() + 10000 };
+    return value;
+  }
+
+  async function publicSettings() {
+    const current = await settings.get();
+    const { codexMaxTurns: _codexMaxTurns, ...exposedSettings } = current;
+    let hasApiKey = false;
+    let apiKeyPreview = '';
+    let secretStoreAvailable = true;
+    if (current.provider === AGENT_PROVIDER_OPENCODE_GO) {
+      try {
+        const key = await secrets.getApiKey(AGENT_PROVIDER_OPENCODE_GO);
+        hasApiKey = Boolean(key);
+        apiKeyPreview = maskApiKey(key);
+      } catch {
+        secretStoreAvailable = false;
+      }
+    }
+    const codex = await getCodexStatus();
+    const securityStatus = runtime?.getSecurityStatus?.() || {
+      isolatedCodexHome: false,
+      restrictedEnvironment: false,
+      livedeskMcpOnly: false,
+      selectedDeviceScopeEnforced: false,
+      failClosed: true,
+      verified: false,
+      state: 'unavailable'
+    };
+    return {
+      ...exposedSettings,
+      hasApiKey,
+      apiKeyPreview,
+      secretStoreAvailable,
+      codexInstallation: codex.installed ? 'installed' : 'not-installed',
+      codexAuth: codex.authenticated,
+      codexStatus: codex.status,
+      codexPath: codex.codexPath,
+      agentWorkspacePath: current.codexWorkingDirectory,
+      securityStatus
+    };
+  }
+
+  async function legacyApiKey() {
+    const key = await secrets.getApiKey(AGENT_PROVIDER_OPENCODE_GO);
+    if (!key) throw new AgentProviderError('agent-api-key-missing', 'OpenCode Go API key is not configured.', { status: 401 });
+    return key;
+  }
+
+  async function currentProvider() {
+    const current = await settings.get();
+    return { current, active: current.provider === AGENT_PROVIDER_CODEX ? runtime : legacyProvider };
+  }
+
+  return {
+    getSettings: publicSettings,
+    async updateSettings(patch = {}) {
+      const nextPatch = { ...patch };
+      const apiKey = typeof nextPatch.apiKey === 'string' ? nextPatch.apiKey.trim() : '';
+      delete nextPatch.apiKey;
+      const current = await settings.get();
+      const requestedProvider = String(nextPatch.provider || current.provider);
+      if (apiKey) {
+        if (requestedProvider !== AGENT_PROVIDER_OPENCODE_GO) {
+          throw new AgentProviderError('agent-codex-does-not-use-api-key', 'Codex authentication is owned by the installed Codex CLI.', { status: 400 });
+        }
+        await secrets.setApiKey(AGENT_PROVIDER_OPENCODE_GO, apiKey);
+      }
+      await settings.update(nextPatch);
+      statusCache = { expiresAt: 0, value: null };
+      return publicSettings();
+    },
+    async resetSettings() {
+      await settings.reset();
+      statusCache = { expiresAt: 0, value: null };
+      return publicSettings();
+    },
+    async deleteApiKey() {
+      await secrets.deleteApiKey(AGENT_PROVIDER_OPENCODE_GO);
+      return publicSettings();
+    },
+    async getModels() {
+      const { current, active } = await currentProvider();
+      if (current.provider === AGENT_PROVIDER_CODEX) {
+        return [{ id: '', name: 'Codex default', protocol: 'codex-sdk', available: true, capabilities: { supportsReasoningLevel: true, supportsStreaming: true, supportsTools: true } }];
+      }
+      return active.getModels(current, await legacyApiKey());
+    },
+    async testConnection() {
+      const { current, active } = await currentProvider();
+      if (current.provider === AGENT_PROVIDER_CODEX) {
+        if (!active) throw new AgentProviderError('codex-sdk-not-installed', 'Codex SDK is not installed.', { status: 503 });
+        statusCache = { expiresAt: 0, value: null };
+        return active.testConnection();
+      }
+      return active.testConnection(current, await legacyApiKey());
+    },
+    async createPlan(input) {
+      const { current, active } = await currentProvider();
+      if (!current.enabled) throw new AgentProviderError('agent-ai-disabled', 'Agent AI is disabled in Settings.', { status: 409 });
+      if (current.provider === AGENT_PROVIDER_CODEX) {
+        throw new AgentProviderError('agent-codex-run-required', 'Codex runs use the LiveDesk tool loop.', { status: 409 });
+      }
+      return active.createPlan(input, current, await legacyApiKey());
+    },
+    async createSummary(input) {
+      const { current, active } = await currentProvider();
+      if (!current.enabled || !current.generateSummary) throw new AgentProviderError('agent-summary-disabled', 'Agent summaries are disabled in Settings.', { status: 409 });
+      if (current.provider === AGENT_PROVIDER_CODEX) {
+        const source = input && typeof input === 'object' ? input : {};
+        const results = Array.isArray(source.results) ? source.results : [];
+        return { summary: String(results.length ? `${source.completed || 0} completed, ${source.failed || 0} failed.` : 'LiveDesk Agent run completed.').slice(0, 1200), modelId: current.codexModelId || 'Codex default' };
+      }
+      const source = input && typeof input === 'object' ? input : {};
+      const results = Array.isArray(source.results) ? source.results : [];
+      const safeResults = current.includeRawDeviceDetails
+        ? results.map(result => ({ deviceName: String(result?.deviceName || '').slice(0, 120), status: String(result?.status || '').slice(0, 40), result: String(result?.result || '').slice(0, 1200), error: String(result?.error || '').slice(0, 500) }))
+        : results.map(result => ({ deviceName: String(result?.deviceName || '').slice(0, 120), status: String(result?.status || '').slice(0, 40), hasResult: Boolean(result?.result), hasError: Boolean(result?.error) }));
+      return active.createSummary({ instruction: String(source.instruction || '').slice(0, 500), operation: String(source.operation || '').slice(0, 80), summary: { total: Number(source.total || results.length), completed: Number(source.completed || 0), failed: Number(source.failed || 0), results: safeResults } }, current, await legacyApiKey());
+    },
+    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 provider.', { status: 409 });
+      return runtime.start(input);
+    },
+    getRun(runId) { return runtime?.get(runId) || null; },
+    cancelRun(runId) { return runtime?.cancel(runId) || null; },
+    cancelAllRuns() { return runtime?.cancelAll?.() || 0; }
+  };
+}

package/src/agents/agent-permission-store.js

@@ -0,0 +1,78 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { DEFAULT_CUSTOM_AGENT_PERMISSION_CATEGORIES, normalizeAgentPermissionCategories } from './agent-permissions.js';
+
+function safePolicyId(value) {
+  const id = String(value || '').trim().replace(/[^a-zA-Z0-9_.:-]/g, '-').slice(0, 80);
+  return id || 'custom-default';
+}
+
+function publicPolicy(policy) {
+  return {
+    id: policy.id,
+    name: policy.name,
+    categories: { ...policy.categories },
+    createdAt: policy.createdAt,
+    updatedAt: policy.updatedAt
+  };
+}
+
+export function createAgentPermissionStore({ dataDir = path.join(os.homedir(), '.livedesk') } = {}) {
+  const filePath = path.join(dataDir, 'agent-permission-policies.json');
+  let policies;
+
+  async function load() {
+    if (policies) return policies;
+    try {
+      const parsed = JSON.parse(await readFile(filePath, 'utf8'));
+      policies = new Map(Object.entries(parsed && typeof parsed === 'object' ? parsed : {}).map(([id, value]) => [safePolicyId(id), {
+        id: safePolicyId(id),
+        name: String(value?.name || id).slice(0, 120),
+        categories: normalizeAgentPermissionCategories(value?.categories, DEFAULT_CUSTOM_AGENT_PERMISSION_CATEGORIES),
+        createdAt: String(value?.createdAt || new Date().toISOString()),
+        updatedAt: String(value?.updatedAt || new Date().toISOString())
+      }]));
+    } catch {
+      policies = new Map();
+    }
+    if (!policies.has('custom-default')) {
+      const now = new Date().toISOString();
+      policies.set('custom-default', { id: 'custom-default', name: 'Custom default', categories: { ...DEFAULT_CUSTOM_AGENT_PERMISSION_CATEGORIES }, createdAt: now, updatedAt: now });
+    }
+    return policies;
+  }
+
+  async function save() {
+    const current = await load();
+    const value = Object.fromEntries([...current].map(([id, policy]) => [id, policy]));
+    await mkdir(path.dirname(filePath), { recursive: true });
+    const temporaryPath = `${filePath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+    await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await rename(temporaryPath, filePath);
+  }
+
+  return {
+    async list() { return [...await load()].map(([, policy]) => publicPolicy(policy)); },
+    async get(id = 'custom-default') {
+      const current = await load();
+      return publicPolicy(current.get(safePolicyId(id)) || current.get('custom-default'));
+    },
+    async upsert({ id = 'custom-default', name = 'Custom default', categories = {} } = {}) {
+      const current = await load();
+      const policyId = safePolicyId(id);
+      const previous = current.get(policyId);
+      const now = new Date().toISOString();
+      current.set(policyId, {
+        id: policyId,
+        name: String(name || policyId).slice(0, 120),
+        categories: normalizeAgentPermissionCategories(categories, previous?.categories || DEFAULT_CUSTOM_AGENT_PERMISSION_CATEGORIES),
+        createdAt: previous?.createdAt || now,
+        updatedAt: now
+      });
+      await save();
+      return publicPolicy(current.get(policyId));
+    }
+  };
+}

package/src/agents/agent-permissions.js

@@ -0,0 +1,209 @@
+import crypto from 'node:crypto';
+import { getAgentToolDefinition } from './agent-tool-registry.js';
+
+export const AGENT_PERMISSION_MODES = Object.freeze(['ask', 'safe-auto', 'full-access', 'custom']);
+export const AGENT_PERMISSION_DECISIONS = Object.freeze(['allow', 'ask', 'deny']);
+export const AGENT_PERMISSION_CATEGORIES = Object.freeze([
+  'read',
+  'processControl',
+  'serviceControl',
+  'applicationControl',
+  'fileRead',
+  'fileWrite',
+  'fileDelete',
+  'shell',
+  'script',
+  'softwareInstall',
+  'network',
+  'systemPower',
+  'systemConfiguration',
+  'userAccount'
+]);
+
+const DEFAULT_CUSTOM_CATEGORIES = Object.freeze({
+  read: 'allow',
+  processControl: 'ask',
+  serviceControl: 'ask',
+  applicationControl: 'ask',
+  fileRead: 'ask',
+  fileWrite: 'ask',
+  fileDelete: 'ask',
+  shell: 'ask',
+  script: 'ask',
+  softwareInstall: 'ask',
+  network: 'ask',
+  systemPower: 'ask',
+  systemConfiguration: 'ask',
+  userAccount: 'deny'
+});
+
+const PRESET_CATEGORIES = Object.freeze({
+  ask: {
+    ...DEFAULT_CUSTOM_CATEGORIES,
+    userAccount: 'ask'
+  },
+  'safe-auto': {
+    read: 'allow',
+    processControl: 'allow',
+    serviceControl: 'allow',
+    // launch_application accepts an executable path, so allowing it would
+    // provide a shell-equivalent escape hatch (for example powershell.exe).
+    applicationControl: 'ask',
+    fileRead: 'allow',
+    fileWrite: 'allow',
+    fileDelete: 'ask',
+    shell: 'ask',
+    // A writable script directory must never become an auto-execution path.
+    script: 'ask',
+    softwareInstall: 'ask',
+    network: 'allow',
+    systemPower: 'ask',
+    systemConfiguration: 'ask',
+    userAccount: 'deny'
+  },
+  'full-access': {
+    read: 'allow',
+    processControl: 'allow',
+    serviceControl: 'allow',
+    applicationControl: 'allow',
+    fileRead: 'allow',
+    fileWrite: 'allow',
+    fileDelete: 'allow',
+    shell: 'allow',
+    script: 'allow',
+    softwareInstall: 'allow',
+    network: 'allow',
+    systemPower: 'allow',
+    systemConfiguration: 'allow',
+    userAccount: 'ask'
+  }
+});
+
+const TOOL_CATEGORY_ALIASES = Object.freeze({
+  'process.list': 'read',
+  'service.status': 'read',
+  'system.health': 'read',
+  'gpu.status': 'read',
+  'disk.status': 'read',
+  'diagnostics.collect': 'read'
+});
+
+function normalizeIds(value) {
+  return [...new Set((Array.isArray(value) ? value : [])
+    .map(item => String(item || '').trim())
+    .filter(Boolean))].sort().slice(0, 500);
+}
+
+function normalizeDecision(value, fallback = 'ask') {
+  return AGENT_PERMISSION_DECISIONS.includes(String(value || '').toLowerCase())
+    ? String(value).toLowerCase()
+    : fallback;
+}
+
+export function normalizeAgentPermissionCategories(value, fallback = DEFAULT_CUSTOM_CATEGORIES) {
+  const source = value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  return Object.fromEntries(AGENT_PERMISSION_CATEGORIES.map(category => [
+    category,
+    normalizeDecision(source[category], fallback[category] || 'ask')
+  ]));
+}
+
+export function getPresetAgentPermissionCategories(mode, customCategories) {
+  const normalizedMode = AGENT_PERMISSION_MODES.includes(mode) ? mode : 'ask';
+  if (normalizedMode === 'custom') return normalizeAgentPermissionCategories(customCategories);
+  return normalizeAgentPermissionCategories(PRESET_CATEGORIES[normalizedMode] || PRESET_CATEGORIES.ask);
+}
+
+export function createAgentPermissionPolicy({ mode = 'ask', deviceIds = [], customCategories, maxToolCalls, now = new Date() } = {}) {
+  const normalizedMode = AGENT_PERMISSION_MODES.includes(String(mode)) ? String(mode) : 'ask';
+  const categories = getPresetAgentPermissionCategories(normalizedMode, customCategories);
+  const defaultMax = normalizedMode === 'ask' ? 30 : normalizedMode === 'safe-auto' ? 50 : normalizedMode === 'full-access' ? 100 : 50;
+  const requestedMax = Number(maxToolCalls);
+  const boundedMax = Number.isFinite(requestedMax) ? Math.max(1, Math.min(100, Math.floor(requestedMax))) : defaultMax;
+  const createdAt = new Date(now).toISOString();
+  const expiresAt = new Date(new Date(now).getTime() + 60 * 60 * 1000).toISOString();
+  return {
+    policyVersion: 1,
+    mode: normalizedMode,
+    deviceIds: normalizeIds(deviceIds),
+    categories,
+    maxToolCalls: boundedMax,
+    expiresAt,
+    createdAt
+  };
+}
+
+export function hashAgentPermissionPolicy(policy) {
+  const canonical = JSON.stringify({
+    policyVersion: policy?.policyVersion,
+    mode: policy?.mode,
+    deviceIds: normalizeIds(policy?.deviceIds),
+    categories: normalizeAgentPermissionCategories(policy?.categories),
+    allowedAppIds: normalizeIds(policy?.allowedAppIds),
+    allowedServiceNames: normalizeIds(policy?.allowedServiceNames),
+    allowedFileRoots: normalizeIds(policy?.allowedFileRoots),
+    allowedDomains: normalizeIds(policy?.allowedDomains),
+    allowedExecutables: normalizeIds(policy?.allowedExecutables),
+    maxToolCalls: Number(policy?.maxToolCalls) || 0,
+    expiresAt: String(policy?.expiresAt || '')
+  });
+  return crypto.createHash('sha256').update(canonical).digest('hex');
+}
+
+function targetIdsFromArgs(args, fallback = []) {
+  return normalizeIds(args?.deviceIds?.length ? args.deviceIds : fallback);
+}
+
+function isSafeAutoRelativePath(value) {
+  const text = String(value || '').trim();
+  if (!text || text.length > 600 || text.startsWith('/') || /^[A-Za-z]:[\\/]/.test(text) || text.startsWith('\\\\')) return false;
+  const segments = text.replaceAll('\\', '/').split('/').filter(Boolean);
+  return segments.length > 0 && !segments.includes('..');
+}
+
+function safeAutoConstraint(tool, args, mode) {
+  if (mode !== 'safe-auto') return '';
+  if (tool.category === 'fileWrite' && !isSafeAutoRelativePath(args?.path)) {
+    return 'Safe Auto file writes are limited to relative paths inside the LiveDesk files directory.';
+  }
+  if (tool.category === 'fileWrite') {
+    const filePath = String(args?.path || '').trim().replaceAll('\\', '/').toLowerCase();
+    if (filePath === 'scripts' || filePath.startsWith('scripts/')) {
+      return 'Safe Auto cannot write files inside the script directory.';
+    }
+  }
+  if (tool.category === 'script') {
+    const scriptPath = String(args?.path || '').trim().toLowerCase();
+    if (!isSafeAutoRelativePath(scriptPath) || !scriptPath.replaceAll('\\', '/').startsWith('scripts/') || !/\.(ps1|psm1|sh|bash|py|js|mjs|cmd|bat)$/.test(scriptPath)) {
+      return 'Safe Auto scripts must be registered relative script files inside the LiveDesk files directory.';
+    }
+  }
+  return '';
+}
+
+export function evaluateAgentToolPermission({ policy, toolName, arguments: args = {}, deviceIds = [] } = {}) {
+  const tool = getAgentToolDefinition(toolName);
+  if (!tool) return { decision: 'deny', category: 'unknown', risk: 'critical', reason: 'Unknown or unregistered Agent tool.' };
+  const allowed = new Set(normalizeIds(policy?.deviceIds));
+  const requested = targetIdsFromArgs(args, deviceIds);
+  if (requested.some(deviceId => !allowed.has(deviceId))) {
+    return { decision: 'deny', category: tool.category, risk: tool.risk, reason: 'The tool requested a device outside the selected Agent scope.' };
+  }
+  if (policy?.expiresAt && Date.parse(policy.expiresAt) <= Date.now()) {
+    return { decision: 'deny', category: tool.category, risk: 'high', reason: 'The Agent permission policy has expired.' };
+  }
+  const category = TOOL_CATEGORY_ALIASES[tool.name.replace(/^livedesk\./, '')] || tool.category;
+  const constraintError = safeAutoConstraint(tool, args, policy?.mode);
+  if (constraintError) {
+    return { decision: 'deny', category, risk: tool.risk, reason: constraintError };
+  }
+  const decision = normalizeDecision(policy?.categories?.[category], 'deny');
+  return {
+    decision,
+    category,
+    risk: tool.risk,
+    reason: decision === 'allow' ? `Allowed by ${policy?.mode || 'current'} policy.` : decision === 'ask' ? 'This operation requires approval in the current policy.' : 'This operation is denied by the current policy.'
+  };
+}
+
+export const DEFAULT_CUSTOM_AGENT_PERMISSION_CATEGORIES = Object.freeze({ ...DEFAULT_CUSTOM_CATEGORIES });