@livedesk/hub 0.1.3 → 0.1.5

package/src/agents/agent-settings.js

@@ -0,0 +1,195 @@
+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 AGENT_PROVIDER_OPENCODE_GO = 'opencode-go';
+export const DEFAULT_AGENT_PROVIDER = AGENT_PROVIDER_CODEX;
+export const DEFAULT_AGENT_BASE_URL = 'https://opencode.ai/zen/go/v1';
+export const DEFAULT_CODEX_MODEL_ID = '';
+export const DEFAULT_AGENT_WORKSPACE = path.join(os.homedir(), '.livedesk', 'agent-workspace');
+export const DEFAULT_AGENT_SETTINGS = Object.freeze({
+  settingsVersion: 2,
+  enabled: true,
+  provider: DEFAULT_AGENT_PROVIDER,
+  codexModelId: DEFAULT_CODEX_MODEL_ID,
+  codexReasoningEffort: 'medium',
+  codexSandboxMode: 'read-only',
+  codexApprovalPolicy: 'never',
+  codexWorkingDirectory: DEFAULT_AGENT_WORKSPACE,
+  codexTaskTimeoutMs: 600000,
+  codexMaxTurns: 12,
+  codexMaxToolCalls: 20,
+  codexResumeSessions: true,
+  codexShowDetailedEvents: true,
+  codexNetworkAccessEnabled: false,
+  codexWebSearchMode: 'disabled',
+  deterministicParserFirst: true,
+  generateSummary: true,
+  fallbackSummary: true,
+  includeRawDeviceDetails: false,
+  maxConcurrentRequests: 2,
+  baseUrl: DEFAULT_AGENT_BASE_URL,
+  defaultModelId: 'deepseek-v4-flash',
+  planModelId: '',
+  summaryModelId: '',
+  reasoningLevel: 'auto',
+  planTemperature: 0.1,
+  summaryTemperature: 0.2,
+  topP: 1,
+  planMaxOutputTokens: 1024,
+  summaryMaxOutputTokens: 1024,
+  planTimeoutMs: 60000,
+  summaryTimeoutMs: 60000,
+  retryCount: 1,
+  retryDelayMs: 1000,
+  streamSummary: false
+});
+
+const PROVIDERS = new Set([AGENT_PROVIDER_CODEX, AGENT_PROVIDER_OPENCODE_GO]);
+const REASONING_EFFORTS = new Set(['minimal', 'low', 'medium', 'high', 'xhigh']);
+const SANDBOX_MODES = new Set(['read-only', 'workspace-write', 'danger-full-access']);
+const APPROVAL_POLICIES = new Set(['never', 'on-request', 'on-failure', 'untrusted']);
+const WEB_SEARCH_MODES = new Set(['disabled', 'cached', 'live']);
+const LEGACY_REASONING_LEVELS = new Set(['auto', 'low', 'medium', 'high']);
+
+export class AgentSettingsError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'AgentSettingsError';
+    this.code = code;
+    this.status = 400;
+  }
+}
+
+function booleanValue(value, fallback) {
+  return typeof value === 'boolean' ? value : fallback;
+}
+
+function numberValue(value, min, max, fallback, integer = false) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  const clamped = Math.max(min, Math.min(max, number));
+  return integer ? Math.round(clamped) : clamped;
+}
+
+function stringValue(value, fallback, maxLength = 240) {
+  if (typeof value !== 'string') return fallback;
+  return value.trim().slice(0, maxLength);
+}
+
+function enumValue(value, allowed, fallback, code) {
+  const normalized = stringValue(value, fallback, 80).toLowerCase();
+  if (!allowed.has(normalized)) throw new AgentSettingsError(code, `Invalid agent setting: ${normalized}.`);
+  return normalized;
+}
+
+function normalizeBaseUrl(value) {
+  const candidate = stringValue(value, DEFAULT_AGENT_SETTINGS.baseUrl, 500).replace(/\/+$/, '');
+  try {
+    const parsed = new URL(candidate);
+    if (!['http:', 'https:'].includes(parsed.protocol) || !parsed.hostname) throw new Error('invalid protocol');
+    parsed.hash = '';
+    parsed.search = '';
+    return parsed.toString().replace(/\/+$/, '');
+  } catch {
+    throw new AgentSettingsError('agent-invalid-base-url', 'Base URL must be a valid HTTP or HTTPS URL.');
+  }
+}
+
+function normalizeWorkingDirectory(value) {
+  // 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 : {};
+  // The pre-Codex settings file was written by LiveDesk itself and had no
+  // migration marker. Keep the legacy values but move that first-run config
+  // to the new Codex default.
+  const migratingLegacy = Number(source.settingsVersion || 0) < 2 && source.provider === AGENT_PROVIDER_OPENCODE_GO;
+  const provider = migratingLegacy
+    ? DEFAULT_AGENT_PROVIDER
+    : enumValue(source.provider, PROVIDERS, DEFAULT_AGENT_PROVIDER, 'agent-unsupported-provider');
+  const reasoningLevel = enumValue(source.reasoningLevel, LEGACY_REASONING_LEVELS, DEFAULT_AGENT_SETTINGS.reasoningLevel, 'agent-invalid-reasoning-level');
+  return {
+    settingsVersion: 2,
+    enabled: booleanValue(source.enabled, DEFAULT_AGENT_SETTINGS.enabled),
+    provider,
+    codexModelId: stringValue(source.codexModelId, DEFAULT_AGENT_SETTINGS.codexModelId, 160),
+    codexReasoningEffort: enumValue(source.codexReasoningEffort, REASONING_EFFORTS, DEFAULT_AGENT_SETTINGS.codexReasoningEffort, 'agent-invalid-reasoning-effort'),
+    // 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(source.codexWorkingDirectory),
+    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',
+    deterministicParserFirst: booleanValue(source.deterministicParserFirst, DEFAULT_AGENT_SETTINGS.deterministicParserFirst),
+    generateSummary: booleanValue(source.generateSummary, DEFAULT_AGENT_SETTINGS.generateSummary),
+    fallbackSummary: booleanValue(source.fallbackSummary, DEFAULT_AGENT_SETTINGS.fallbackSummary),
+    includeRawDeviceDetails: booleanValue(source.includeRawDeviceDetails, DEFAULT_AGENT_SETTINGS.includeRawDeviceDetails),
+    maxConcurrentRequests: numberValue(source.maxConcurrentRequests, 1, 8, DEFAULT_AGENT_SETTINGS.maxConcurrentRequests, true),
+    baseUrl: normalizeBaseUrl(source.baseUrl ?? DEFAULT_AGENT_SETTINGS.baseUrl),
+    defaultModelId: stringValue(source.defaultModelId, DEFAULT_AGENT_SETTINGS.defaultModelId, 160),
+    planModelId: stringValue(source.planModelId, DEFAULT_AGENT_SETTINGS.planModelId, 160),
+    summaryModelId: stringValue(source.summaryModelId, DEFAULT_AGENT_SETTINGS.summaryModelId, 160),
+    reasoningLevel,
+    planTemperature: numberValue(source.planTemperature, 0, 2, DEFAULT_AGENT_SETTINGS.planTemperature),
+    summaryTemperature: numberValue(source.summaryTemperature, 0, 2, DEFAULT_AGENT_SETTINGS.summaryTemperature),
+    topP: numberValue(source.topP, 0, 1, DEFAULT_AGENT_SETTINGS.topP),
+    planMaxOutputTokens: numberValue(source.planMaxOutputTokens, 128, 16384, DEFAULT_AGENT_SETTINGS.planMaxOutputTokens, true),
+    summaryMaxOutputTokens: numberValue(source.summaryMaxOutputTokens, 128, 16384, DEFAULT_AGENT_SETTINGS.summaryMaxOutputTokens, true),
+    planTimeoutMs: numberValue(source.planTimeoutMs, 5000, 180000, DEFAULT_AGENT_SETTINGS.planTimeoutMs, true),
+    summaryTimeoutMs: numberValue(source.summaryTimeoutMs, 5000, 180000, DEFAULT_AGENT_SETTINGS.summaryTimeoutMs, true),
+    retryCount: numberValue(source.retryCount, 0, 4, DEFAULT_AGENT_SETTINGS.retryCount, true),
+    retryDelayMs: numberValue(source.retryDelayMs, 100, 10000, DEFAULT_AGENT_SETTINGS.retryDelayMs, true),
+    streamSummary: booleanValue(source.streamSummary, DEFAULT_AGENT_SETTINGS.streamSummary)
+  };
+}
+
+async function writeJsonAtomic(filePath, value) {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  await rename(temporaryPath, filePath);
+}
+
+export class AgentSettingsStore {
+  constructor({ dataDir = path.join(os.homedir(), '.livedesk') } = {}) {
+    this.filePath = path.join(dataDir, 'agent-settings.json');
+    this.settings = null;
+  }
+
+  async get() {
+    if (this.settings) return { ...this.settings };
+    try {
+      const raw = await readFile(this.filePath, 'utf8');
+      this.settings = normalizeAgentSettings(JSON.parse(raw));
+    } catch {
+      this.settings = normalizeAgentSettings(DEFAULT_AGENT_SETTINGS);
+    }
+    return { ...this.settings };
+  }
+
+  async update(patch = {}) {
+    const current = await this.get();
+    const next = normalizeAgentSettings({ ...current, ...patch });
+    await writeJsonAtomic(this.filePath, next);
+    this.settings = next;
+    return { ...next };
+  }
+
+  async reset() {
+    const next = normalizeAgentSettings(DEFAULT_AGENT_SETTINGS);
+    await writeJsonAtomic(this.filePath, next);
+    this.settings = next;
+    return { ...next };
+  }
+}

package/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;
+}