livedesk 0.1.207 → 0.1.209

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

@@ -0,0 +1,76 @@
+import { appendFile, mkdir, readFile } 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_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 writeQueue = Promise.resolve();
+
+  async function load() {
+    if (records) return records;
+    try {
+      const lines = (await readFile(filePath, 'utf8')).split(/\r?\n/).filter(Boolean).slice(-MAX_AUDIT_RECORDS);
+      records = lines.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);
+      const current = await load();
+      current.push(record);
+      if (current.length > MAX_AUDIT_RECORDS) current.splice(0, current.length - MAX_AUDIT_RECORDS);
+      writeQueue = writeQueue.then(async () => {
+        await mkdir(path.dirname(filePath), { recursive: true });
+        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/hub/src/agents/agent-manager.js

@@ -68,7 +68,9 @@ export function createAgentManager({
       restrictedEnvironment: false,
       livedeskMcpOnly: false,
       selectedDeviceScopeEnforced: false,
-      failClosed: true
+      failClosed: true,
+      verified: false,
+      state: 'unavailable'
     };
     return {
       ...exposedSettings,

package/hub/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/hub/src/agents/agent-permissions.js

@@ -0,0 +1,175 @@
+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: 'ask',
+    serviceControl: 'ask',
+    applicationControl: 'ask',
+    fileRead: 'allow',
+    fileWrite: 'ask',
+    fileDelete: 'deny',
+    shell: 'ask',
+    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);
+}
+
+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 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 });

package/hub/src/agents/agent-tool-registry.js

@@ -0,0 +1,322 @@
+const readOnlyInput = {
+  type: 'object',
+  properties: {
+    deviceIds: { type: 'array', items: { type: 'string' }, maxItems: 500 }
+  },
+  additionalProperties: false
+};
+
+function withQueryInput(properties) {
+  return {
+    type: 'object',
+    properties: { ...properties, deviceIds: readOnlyInput.properties.deviceIds },
+    additionalProperties: false
+  };
+}
+
+function withRequiredInput(properties, required = []) {
+  return {
+    ...withQueryInput(properties),
+    required
+  };
+}
+
+const taskPermission = { ask: 'ask', safeAuto: 'ask', fullAccess: 'allow' };
+const readTaskPermission = { ask: 'allow', safeAuto: 'allow', fullAccess: 'allow' };
+
+export const AGENT_TOOL_DEFINITIONS = Object.freeze([
+  {
+    name: 'livedesk.list_devices',
+    description: 'List connected LiveDesk workstations. This is read-only.',
+    category: 'read',
+    readOnly: true,
+    mutating: false,
+    risk: 'low',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: readOnlyInput,
+    defaultPermission: { ask: 'allow', safeAuto: 'allow', fullAccess: 'allow' }
+  },
+  {
+    name: 'livedesk.get_system_health',
+    description: 'Read system health from the selected workstations.',
+    category: 'read',
+    readOnly: true,
+    mutating: false,
+    risk: 'low',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: readOnlyInput,
+    defaultPermission: { ask: 'allow', safeAuto: 'allow', fullAccess: 'allow' }
+  },
+  {
+    name: 'livedesk.get_gpu_status',
+    description: 'Read GPU status from the selected workstations.',
+    category: 'read',
+    readOnly: true,
+    mutating: false,
+    risk: 'low',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: readOnlyInput,
+    defaultPermission: { ask: 'allow', safeAuto: 'allow', fullAccess: 'allow' }
+  },
+  {
+    name: 'livedesk.get_disk_status',
+    description: 'Read disk status from the selected workstations.',
+    category: 'read',
+    readOnly: true,
+    mutating: false,
+    risk: 'low',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: readOnlyInput,
+    defaultPermission: { ask: 'allow', safeAuto: 'allow', fullAccess: 'allow' }
+  },
+  {
+    name: 'livedesk.list_processes',
+    description: 'Read process status from the selected workstations. Use processName for a named process such as ComfyUI.',
+    category: 'read',
+    readOnly: true,
+    mutating: false,
+    risk: 'low',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withQueryInput({ processName: { type: 'string', maxLength: 120 } }),
+    defaultPermission: { ask: 'allow', safeAuto: 'allow', fullAccess: 'allow' }
+  },
+  {
+    name: 'livedesk.get_service_status',
+    description: 'Read service status from the selected workstations. Use serviceName when the user names a service.',
+    category: 'read',
+    readOnly: true,
+    mutating: false,
+    risk: 'low',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withQueryInput({ serviceName: { type: 'string', maxLength: 120 } }),
+    defaultPermission: { ask: 'allow', safeAuto: 'allow', fullAccess: 'allow' }
+  },
+  {
+    name: 'livedesk.collect_diagnostics',
+    description: 'Collect the existing safe LiveDesk diagnostics payload from the selected workstations.',
+    category: 'read',
+    readOnly: true,
+    mutating: false,
+    risk: 'low',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: readOnlyInput,
+    defaultPermission: { ask: 'allow', safeAuto: 'allow', fullAccess: 'allow' }
+  },
+  {
+    name: 'livedesk.control_process',
+    description: 'Stop or restart a named process on the selected workstations. This changes process state.',
+    category: 'processControl',
+    readOnly: false,
+    mutating: true,
+    risk: 'high',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withRequiredInput({ processName: { type: 'string', minLength: 1, maxLength: 120 }, action: { type: 'string', enum: ['stop', 'restart'] } }, ['processName', 'action']),
+    defaultPermission: taskPermission
+  },
+  {
+    name: 'livedesk.control_service',
+    description: 'Start, stop, or restart a named service on the selected workstations.',
+    category: 'serviceControl',
+    readOnly: false,
+    mutating: true,
+    risk: 'high',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'linux'],
+    inputSchema: withRequiredInput({ serviceName: { type: 'string', minLength: 1, maxLength: 120 }, action: { type: 'string', enum: ['start', 'stop', 'restart'] } }, ['serviceName', 'action']),
+    defaultPermission: taskPermission
+  },
+  {
+    name: 'livedesk.launch_application',
+    description: 'Launch a specific application without using a shell command.',
+    category: 'applicationControl',
+    readOnly: false,
+    mutating: true,
+    risk: 'medium',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withRequiredInput({ executable: { type: 'string', minLength: 1, maxLength: 400 }, args: { type: 'array', items: { type: 'string', maxLength: 400 }, maxItems: 32 }, workingDirectory: { type: 'string', maxLength: 600 } }, ['executable']),
+    defaultPermission: taskPermission
+  },
+  {
+    name: 'livedesk.close_application',
+    description: 'Close a named application process on the selected workstations.',
+    category: 'applicationControl',
+    readOnly: false,
+    mutating: true,
+    risk: 'medium',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withRequiredInput({ processName: { type: 'string', minLength: 1, maxLength: 120 }, force: { type: 'boolean' } }, ['processName']),
+    defaultPermission: taskPermission
+  },
+  {
+    name: 'livedesk.read_file',
+    description: 'Read a bounded UTF-8 text file from the selected workstations, with sensitive credential paths rejected.',
+    category: 'fileRead',
+    readOnly: true,
+    mutating: false,
+    risk: 'medium',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withRequiredInput({ path: { type: 'string', minLength: 1, maxLength: 600 }, maxBytes: { type: 'integer', minimum: 1, maximum: 65536 } }, ['path']),
+    defaultPermission: { ask: 'allow', safeAuto: 'allow', fullAccess: 'allow' }
+  },
+  {
+    name: 'livedesk.write_file',
+    description: 'Write bounded text content to a file on the selected workstations.',
+    category: 'fileWrite',
+    readOnly: false,
+    mutating: true,
+    risk: 'high',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withRequiredInput({ path: { type: 'string', minLength: 1, maxLength: 600 }, content: { type: 'string', maxLength: 1048576 }, append: { type: 'boolean' } }, ['path', 'content']),
+    defaultPermission: taskPermission
+  },
+  {
+    name: 'livedesk.delete_file',
+    description: 'Delete a selected file or explicitly requested directory on the selected workstations.',
+    category: 'fileDelete',
+    readOnly: false,
+    mutating: true,
+    risk: 'critical',
+    reversible: false,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withRequiredInput({ path: { type: 'string', minLength: 1, maxLength: 600 }, recursive: { type: 'boolean' } }, ['path']),
+    defaultPermission: taskPermission
+  },
+  {
+    name: 'livedesk.list_directory',
+    description: 'List bounded file metadata from a directory on the selected workstations.',
+    category: 'fileRead',
+    readOnly: true,
+    mutating: false,
+    risk: 'low',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withRequiredInput({ path: { type: 'string', minLength: 1, maxLength: 600 }, recursive: { type: 'boolean' }, maxEntries: { type: 'integer', minimum: 1, maximum: 500 } }, ['path']),
+    defaultPermission: readTaskPermission
+  },
+  {
+    name: 'livedesk.run_command',
+    description: 'Run a bounded command through the selected workstation command interpreter. This is an audited high-risk action.',
+    category: 'shell',
+    readOnly: false,
+    mutating: true,
+    risk: 'critical',
+    reversible: false,
+    supportsBatch: false,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withRequiredInput({ command: { type: 'string', minLength: 1, maxLength: 4000 }, workingDirectory: { type: 'string', maxLength: 600 }, timeoutMs: { type: 'integer', minimum: 1000, maximum: 30000 } }, ['command']),
+    defaultPermission: taskPermission
+  },
+  {
+    name: 'livedesk.run_script',
+    description: 'Run a bounded script file using the workstation platform interpreter.',
+    category: 'script',
+    readOnly: false,
+    mutating: true,
+    risk: 'high',
+    reversible: false,
+    supportsBatch: false,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withRequiredInput({ path: { type: 'string', minLength: 1, maxLength: 600 }, args: { type: 'array', items: { type: 'string', maxLength: 400 }, maxItems: 32 }, timeoutMs: { type: 'integer', minimum: 1000, maximum: 30000 } }, ['path']),
+    defaultPermission: taskPermission
+  },
+  {
+    name: 'livedesk.install_software',
+    description: 'Install a named package through an explicitly selected package manager.',
+    category: 'softwareInstall',
+    readOnly: false,
+    mutating: true,
+    risk: 'high',
+    reversible: false,
+    supportsBatch: false,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withRequiredInput({ manager: { type: 'string', enum: ['winget', 'brew', 'apt', 'npm'] }, packageName: { type: 'string', minLength: 1, maxLength: 200 }, version: { type: 'string', maxLength: 80 } }, ['manager', 'packageName']),
+    defaultPermission: taskPermission
+  },
+  {
+    name: 'livedesk.get_network_status',
+    description: 'Read bounded network adapter and connectivity status from the selected workstations.',
+    category: 'network',
+    readOnly: true,
+    mutating: false,
+    risk: 'low',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: readOnlyInput,
+    defaultPermission: readTaskPermission
+  },
+  {
+    name: 'livedesk.power_action',
+    description: 'Request an explicit power action on the selected workstations.',
+    category: 'systemPower',
+    readOnly: false,
+    mutating: true,
+    risk: 'critical',
+    reversible: false,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withRequiredInput({ action: { type: 'string', enum: ['lock', 'logoff', 'sleep', 'restart', 'shutdown'] }, delaySec: { type: 'integer', minimum: 0, maximum: 3600 } }, ['action']),
+    defaultPermission: taskPermission
+  },
+  {
+    name: 'livedesk.system_configuration',
+    description: 'Apply one explicitly named system configuration action supported by the workstation agent.',
+    category: 'systemConfiguration',
+    readOnly: false,
+    mutating: true,
+    risk: 'critical',
+    reversible: false,
+    supportsBatch: false,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withRequiredInput({ action: { type: 'string', enum: ['set-timezone', 'set-environment-variable'] }, name: { type: 'string', minLength: 1, maxLength: 120 }, value: { type: 'string', maxLength: 400 } }, ['action', 'name', 'value']),
+    defaultPermission: taskPermission
+  },
+  {
+    name: 'livedesk.collect_logs',
+    description: 'Collect bounded recent application and system log lines without reading credential stores.',
+    category: 'read',
+    readOnly: true,
+    mutating: false,
+    risk: 'medium',
+    reversible: true,
+    supportsBatch: true,
+    supportedPlatforms: ['windows', 'macos', 'linux'],
+    inputSchema: withQueryInput({ source: { type: 'string', maxLength: 120 }, maxLines: { type: 'integer', minimum: 1, maximum: 500 } }),
+    defaultPermission: readTaskPermission
+  }
+]);
+
+export const AGENT_TOOL_NAMES = Object.freeze(AGENT_TOOL_DEFINITIONS.map(tool => tool.name));
+
+const toolByName = new Map(AGENT_TOOL_DEFINITIONS.map(tool => [tool.name, tool]));
+
+export function getAgentToolDefinition(name) {
+  return toolByName.get(String(name || '').trim()) || null;
+}