nexus-agentd 0.4.0 → 0.4.2

package/README.md

@@ -118,11 +118,16 @@ npm install -g \
   pi-acp
 ```
 
-`command`、`args`、`probeArgs`、`inheritEnv` 和 `env` 是仅可在本机配置文件修改的高级字段，WebUI
+`command`、`args`、`probeArgs`、`probeTimeoutMs`、`inheritEnv` 和 `env` 是仅可在本机配置文件修改的高级字段，WebUI
 不接受这些字段。Workspace 在启动进程前经过 `realpath` 边界校验。通用 `stdio` 驱动用于自定义入口，
 必须指定 `command`，用 `probeArgs` 指定可用性检查参数（例如 `["--version"]`）；编辑其他字段时保留
 这些本地配置。命令探测不等于 ACP 握手成功。
 
+`probeTimeoutMs` 是可用性探测的期限，默认 60000 毫秒。探测会真正拉起一次 Agent 进程，而 Agent 在
+应答探测前往往要加载大量插件（例如 Hermes 会注册 50 多个插件提供者），启动耗时远超普通 shell
+命令；期限过短会把正在正常启动的 Agent 报成「不可用 / probe timed out」。启动较慢的 Agent 按实测
+启动时间调高该值即可。
+
 权限策略支持 `ask`（询问）、`allow`（自动允许单次）和 `deny`（拒绝）。`allow` 只选择 Agent 提供的
 `allow_once`，缺少该选项则取消授权，不回退到永久授权。`ask` 模式下普通 `action: "accept"` 也只选择
 单次授权，永久授权需要客户端明确传入对应 `optionId`。这不限制重复的单次自动授权，但只提供永久选项的

package/dist/config.js

@@ -181,6 +181,7 @@ function parseAgent(id, value) {
         probeArgs: input.probeArgs === undefined
             ? undefined
             : stringArray(input.probeArgs, `agents.${id}.probeArgs`),
+        probeTimeoutMs: integerValue(input.probeTimeoutMs, `agents.${id}.probeTimeoutMs`, 60 * 1000, 1000, 10 * 60 * 1000),
         inheritEnv: input.inheritEnv === undefined
             ? undefined
             : stringArray(input.inheritEnv, `agents.${id}.inheritEnv`),

package/dist/control-plane-validation.js

@@ -117,7 +117,7 @@ export function clampTimeout(value, fallback, min, max) {
 }
 export function preservedAcpAdvanced(previous) {
     const result = {};
-    for (const key of ['command', 'args', 'probeArgs', 'inheritEnv', 'env']) {
+    for (const key of ['command', 'args', 'probeArgs', 'probeTimeoutMs', 'inheritEnv', 'env']) {
         if (previous[key] !== undefined)
             result[key] = structuredClone(previous[key]);
     }

package/dist/control-plane.js

@@ -513,7 +513,8 @@ export class AgentdControlPlane {
             enabled: config.enabled !== false,
             workspace: config.workspace || this.config.workspaceRoots[0] || '',
             permissionPolicy: config.permissionPolicy || 'ask',
-            permissionTimeoutMs: config.permissionTimeoutMs || 15 * 60 * 1000
+            permissionTimeoutMs: config.permissionTimeoutMs || 15 * 60 * 1000,
+            probeTimeoutMs: config.probeTimeoutMs || 60 * 1000
         };
     }
     exclusive(task) {

package/dist/drivers/stdio.d.ts

@@ -1,5 +1,13 @@
 import type { AgentdDriverConfig } from '../types.js';
 import type { AgentDriver } from './types.js';
+/**
+ * How long an availability probe may take before it is reported as a timeout.
+ * Probes spawn a real agent process, and agents that load plugins before
+ * answering (Hermes registers 50+ plugin providers) need far longer than the
+ * five seconds that used to be hard-coded here — they were reported as down
+ * while starting up normally. Override per agent with `probeTimeoutMs`.
+ */
+export declare const DEFAULT_PROBE_TIMEOUT_MS = 60000;
 export interface StdioAcpDriverDefaults {
     name: string;
     description: string;

package/dist/drivers/stdio.js

@@ -27,6 +27,14 @@ const BASE_ENV_KEYS = [
     'ProgramFiles(x86)',
     'PATHEXT'
 ];
+/**
+ * How long an availability probe may take before it is reported as a timeout.
+ * Probes spawn a real agent process, and agents that load plugins before
+ * answering (Hermes registers 50+ plugin providers) need far longer than the
+ * five seconds that used to be hard-coded here — they were reported as down
+ * while starting up normally. Override per agent with `probeTimeoutMs`.
+ */
+export const DEFAULT_PROBE_TIMEOUT_MS = 60_000;
 export function createStdioAcpDriver(id, config, defaults) {
     const command = config.command || defaults.command;
     const args = config.args === undefined ? [...defaults.args] : [...config.args];
@@ -45,7 +53,10 @@ export function createStdioAcpDriver(id, config, defaults) {
         ownsProcessGroup: process.platform !== 'win32',
         async probe() {
             try {
-                const version = await probeCommand(command, config.probeArgs || defaults.probeArgs || ['--version'], env, name, { ownsProcessGroup: process.platform !== 'win32' });
+                const version = await probeCommand(command, config.probeArgs || defaults.probeArgs || ['--version'], env, name, {
+                    ownsProcessGroup: process.platform !== 'win32',
+                    timeoutMs: config.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS
+                });
                 return {
                     id,
                     name,
@@ -155,7 +166,7 @@ export function probeCommand(command, args, env, label, options = {}) {
             // process. Wait for tree termination before rejecting so a timed
             // out health check cannot leave an agent running in the background.
             void cleanup().then(() => finish(new Error(`${label} probe timed out`)), (error) => finish(new Error(`${label} probe timed out; cleanup failed: ${cleanupFailure(error)}`)));
-        }, options.timeoutMs ?? 5000);
+        }, options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS);
         timer.unref?.();
         child.stdout.on('data', (chunk) => {
             output = `${output}${String(chunk)}`.slice(-8192);

package/dist/process-tree.js

@@ -1,12 +1,16 @@
 import { spawn } from 'node:child_process';
 const DEFAULT_GRACE_MS = 2_000;
 const FORCE_KILL_WAIT_MS = 1_000;
-// Enumerating costs about a second on an idle machine and considerably more
-// when the gateway is busy. The sweep runs on every teardown — including a
-// failed ACP startup, which callers bound at five seconds — so it is capped
-// short: an incomplete sweep beats a teardown that never returns.
-const PROCESS_TABLE_TIMEOUT_MS = 1_200;
+// Enumerating the process table costs about 1.3s on an idle machine (roughly
+// 0.4s of PowerShell startup plus the CIM query) and more when the gateway is
+// busy. The previous 1.2s cap sat just below that, so the sweep timed out and
+// silently found nothing; leave headroom for the query to actually finish.
+const PROCESS_TABLE_TIMEOUT_MS = 2_500;
 const PROCESS_TABLE_TTL_MS = 1_000;
+// Ceiling for one orphan sweep. The sweep runs on every teardown — including a
+// failed ACP startup, which callers bound at five seconds — so it must stay
+// bounded: an incomplete sweep beats a teardown that never returns.
+const ORPHAN_SWEEP_BUDGET_MS = 3_000;
 // Windows reports a killed process as gone from `tasklist` slightly before the
 // kernel closes the handles it held, so callers that delete the workspace or
 // temp directory right after a teardown can still see EBUSY.
@@ -22,6 +26,11 @@ export async function terminateProcessTree(child, options = {}) {
         // never handle: the graceful pass always fails and burns the whole
         // grace period before the forced retry. Force the tree kill directly.
         if (!hasExited(child)) {
+            // Enumerating the process table is the slowest step of a Windows
+            // teardown and does not depend on the leader being gone, so start
+            // it alongside the kill instead of after it. The snapshot then
+            // predates the tree kill, which the liveness filter below handles.
+            const table = windowsProcessTable();
             await taskkill(pid, true);
             if (!(await waitForExit(child, Math.max(graceMs, FORCE_KILL_WAIT_MS)))) {
                 // A forced kill can still lose the race on a loaded machine,
@@ -29,13 +38,17 @@ export async function terminateProcessTree(child, options = {}) {
                 await taskkill(pid, true);
                 await waitForExit(child, FORCE_KILL_WAIT_MS);
             }
+            // A forced `taskkill /T` walks the tree as it exists at that
+            // instant, so a child spawned moments before the leader died
+            // survives as an orphan holding ports, file locks and inherited
+            // pipes. Sweep by parent id for whatever the tree kill missed.
+            await terminateOrphanedDescendants(pid, ORPHAN_SWEEP_BUDGET_MS, table);
+        }
+        else {
+            // A leader that exited before we got here cannot be addressed by
+            // taskkill at all, so nothing has swept its descendants yet.
+            await terminateOrphanedDescendants(pid);
         }
-        // A forced `taskkill /T` walks the tree as it exists at that instant,
-        // so a child spawned moments before the leader died survives as an
-        // orphan holding ports, file locks and inherited pipes — and a leader
-        // that exited before we got here cannot be addressed by taskkill at
-        // all. Sweep by parent id in both cases.
-        await terminateOrphanedDescendants(pid);
         if (hasExited(child)) {
             await delay(PROCESS_EXIT_SETTLE_MS);
             return;
@@ -115,17 +128,31 @@ function taskkill(pid, force) {
         const args = ['/PID', String(pid), '/T'];
         if (force)
             args.push('/F');
-        const killer = spawn('taskkill.exe', args, { stdio: 'ignore', windowsHide: true });
-        const timer = setTimeout(() => {
-            killer.kill();
-            resolve();
-        }, FORCE_KILL_WAIT_MS);
-        const finish = () => {
+        let killer;
+        try {
+            killer = spawn('taskkill.exe', args, { stdio: 'ignore', windowsHide: true });
+        }
+        catch {
+            resolve(false);
+            return;
+        }
+        let settled = false;
+        const finish = (killed) => {
+            if (settled)
+                return;
+            settled = true;
             clearTimeout(timer);
-            resolve();
+            resolve(killed);
         };
-        killer.once('error', finish);
-        killer.once('exit', finish);
+        const timer = setTimeout(() => {
+            try {
+                killer.kill();
+            }
+            catch { }
+            finish(false);
+        }, FORCE_KILL_WAIT_MS);
+        killer.once('error', () => finish(false));
+        killer.once('exit', (code) => finish(code === 0));
     });
 }
 /**
@@ -136,16 +163,37 @@ function taskkill(pid, force) {
  * after that, which is enough to find the survivors. Best-effort by design: an
  * unreadable process table just leaves the sweep incomplete.
  */
-async function terminateOrphanedDescendants(pid) {
-    const doomed = collectDescendants(await windowsProcessTable(), pid);
+async function terminateOrphanedDescendants(pid, budgetMs = ORPHAN_SWEEP_BUDGET_MS, table) {
+    const deadline = Date.now() + budgetMs;
+    const snapshot = await (table ?? windowsProcessTable());
+    // The snapshot may predate a caller's tree kill, and each taskkill costs
+    // the better part of a second, so only ever aim at processes still alive.
+    const doomed = collectDescendants(snapshot, pid).filter((target) => processAlive(target));
     if (!doomed.length)
         return;
-    for (const target of doomed)
-        await taskkill(target, true);
-    // Killing a parent can strand its own children, so rescan for what is left.
-    const remaining = collectDescendants(await windowsProcessTable(true), pid);
-    for (const survivor of remaining)
-        await taskkill(survivor, true);
+    // `collectDescendants` already returns the whole descendant tree, so kill
+    // them together rather than paying the taskkill cost once per process.
+    await Promise.all(doomed.map((target) => taskkill(target, true)));
+    // Killing a parent can strand its own children, but the first pass covered
+    // the entire tree, so a rescan only pays off when one of the targets is
+    // still alive. Each rescan costs another full enumeration.
+    if (Date.now() >= deadline)
+        return;
+    if (!doomed.some((target) => processAlive(target)))
+        return;
+    const remaining = collectDescendants(await windowsProcessTable(true), pid)
+        .filter((survivor) => processAlive(survivor));
+    await Promise.all(remaining.map((survivor) => taskkill(survivor, true)));
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM means the process exists but belongs to someone else.
+        return error.code === 'EPERM';
+    }
 }
 function collectDescendants(table, root) {
     if (!table)

package/dist/types.d.ts

@@ -27,6 +27,12 @@ export interface AgentdDriverConfig {
     args?: string[];
     /** Arguments used by a command availability probe. */
     probeArgs?: string[];
+    /**
+     * Milliseconds the availability probe may take before it is reported as a
+     * timeout. Agent CLIs that load plugins before answering a probe need far
+     * more than a shell command; defaults to 60000.
+     */
+    probeTimeoutMs?: number;
     inheritEnv?: string[];
     env?: Record<string, string>;
     permissionPolicy?: PermissionPolicy;
@@ -141,6 +147,7 @@ export interface AgentdAgentConfigView {
     workspace?: string;
     permissionPolicy?: PermissionPolicy;
     permissionTimeoutMs?: number;
+    probeTimeoutMs?: number;
     agentCardUrl?: string;
     agentUrl?: string;
     preferredTransport?: A2ATransportPreference;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-agentd",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Local Nexus Gateway daemon with an HTTP/SSE API and WebUI for allowlisted ACP and remote A2A agents",
   "type": "module",
   "main": "dist/index.js",