nexus-agentd 0.2.0 → 0.2.2

package/README.md

@@ -97,8 +97,12 @@ npm install -g \
   pi-acp
 ```
 
-`command`、`args`、`inheritEnv` 和 `env` 是仅可在本机配置文件修改的高级字段，WebUI 不接受这些
-字段。Workspace 在启动进程前经过 `realpath` 边界校验。
+`command`、`args`、`inheritEnv` 和 `env` 是仅可在本机配置文件修改的高级字段，WebUI 不接受这些
+字段。Workspace 在启动进程前经过 `realpath` 边界校验。
+
+ACP 权限策略支持 `ask`（询问）、`allow`（始终允许）和 `deny`（拒绝）。`allow` 会优先选择
+Agent 提供的 `allow_once`，不创建待确认请求；它适合管理员明确授权、工作区边界可信的自动化 Agent。
+默认仍为 `ask`。
 
 ### A2A
 
@@ -215,7 +219,8 @@ GET  /v1/sessions/:id/events
 `/v1/meta` 和 Session 响应包含 Gateway `instanceId`；完成的 Session 还包含与当前 Run 绑定的
 `completion` 证明，客户端可识别进程重启和迟到/伪造的完成状态。授权与输入通过精确的
 `requestId` 解析；过期 ID 返回 `409`，不会误答后续请求。`DELETE /v1/sessions/:id` 会取消活动任务、
-释放 Agent 进程并移除内存 Session。
+释放 Agent 整个进程组并移除内存 Session。Gateway 停止时会先终止 Session，再在有限宽限期后关闭残留
+HTTP/SSE 连接，避免长连接或 Agent 孙进程阻塞服务重启。
 
 API Key 的 Agent scope 在 Agent inventory、Session 创建和后续 Session 操作上都会检查；Session
 还绑定创建它的 Key，其他 Key 即使拥有同一 Agent scope 也不能读取或控制该 Session。

package/dist/acp/runtime.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { Readable, Writable } from 'node:stream';
 import { pathToFileURL } from 'node:url';
 import * as acp from '@agentclientprotocol/sdk';
+import { terminateProcessTree } from '../process-tree.js';
 import { TURN_COMPLETION_CONTRACT } from '../completion-contract.js';
 export class AcpProcessRuntime {
     driver;
@@ -61,7 +62,7 @@ export class AcpProcessRuntime {
             },
             clientInfo: {
                 name: 'nexus-agentd',
-                version: '0.2.0'
+                version: '0.2.2'
             }
         });
         if (initialize.protocolVersion !== acp.PROTOCOL_VERSION) {
@@ -224,15 +225,17 @@ export class AcpProcessRuntime {
         }
         this.connection?.close();
         this.connection = undefined;
+        const child = this.process;
+        this.process = undefined;
+        if (child) {
+            await terminateProcessTree(child, {
+                ownsProcessGroup: this.driver.ownsProcessGroup
+            });
+        }
         if (this.inputDirectory) {
             await rm(this.inputDirectory, { recursive: true, force: true }).catch(() => undefined);
             this.inputDirectory = undefined;
         }
-        const child = this.process;
-        this.process = undefined;
-        if (child && child.exitCode === null && child.signalCode === null) {
-            child.kill();
-        }
     }
     requestPermission(params) {
         if (this.driver.permissionPolicy === 'deny') {
@@ -246,6 +249,18 @@ export class AcpProcessRuntime {
                 }
                 : { outcome: { outcome: 'cancelled' } };
         }
+        if (this.driver.permissionPolicy === 'allow') {
+            const allow = params.options.find((option) => option.kind.toLowerCase() === 'allow_once') ||
+                params.options.find((option) => option.kind.toLowerCase().startsWith('allow'));
+            return allow
+                ? {
+                    outcome: {
+                        outcome: 'selected',
+                        optionId: allow.optionId
+                    }
+                }
+                : { outcome: { outcome: 'cancelled' } };
+        }
         if (this.pending) {
             return { outcome: { outcome: 'cancelled' } };
         }

package/dist/config.js

@@ -134,7 +134,9 @@ function parseAgent(id, value) {
         throw new Error(`Unsupported nexus-agentd driver: ${driver || id}`);
     }
     const permissionPolicy = optionalString(input.permissionPolicy, `agents.${id}.permissionPolicy`) || 'ask';
-    if (permissionPolicy !== 'ask' && permissionPolicy !== 'deny') {
+    if (permissionPolicy !== 'ask' &&
+        permissionPolicy !== 'allow' &&
+        permissionPolicy !== 'deny') {
         throw new Error(`Invalid permissionPolicy for ${id}`);
     }
     const result = {

package/dist/control-plane.js

@@ -501,8 +501,9 @@ function validateUpdate(update) {
     }
     if (update.permissionPolicy !== undefined &&
         update.permissionPolicy !== 'ask' &&
+        update.permissionPolicy !== 'allow' &&
         update.permissionPolicy !== 'deny') {
-        throw new ControlPlaneError(400, 'permissionPolicy must be ask or deny');
+        throw new ControlPlaneError(400, 'permissionPolicy must be ask, allow, or deny');
     }
     if (update.preferredTransport !== undefined &&
         !['auto', 'jsonrpc', 'http-json'].includes(update.preferredTransport)) {

package/dist/drivers/pi.d.ts

@@ -9,5 +9,6 @@ export declare function createPiDriver(id: string, config: AgentdDriverConfig):
     env: NodeJS.ProcessEnv;
     permissionPolicy: import("../types.js").PermissionPolicy;
     permissionTimeoutMs: number;
+    ownsProcessGroup?: boolean;
     spawn(workspace: string): import("child_process").ChildProcessWithoutNullStreams;
 };

package/dist/drivers/stdio.js

@@ -28,6 +28,7 @@ export function createStdioAcpDriver(id, config, defaults) {
         env,
         permissionPolicy: config.permissionPolicy || 'ask',
         permissionTimeoutMs: config.permissionTimeoutMs || 15 * 60 * 1000,
+        ownsProcessGroup: process.platform !== 'win32',
         async probe() {
             try {
                 const version = await probeCommand(command, defaults.probeArgs || ['--version'], env, name);
@@ -55,6 +56,7 @@ export function createStdioAcpDriver(id, config, defaults) {
             return spawn(command, args, {
                 cwd: workspace,
                 env,
+                detached: process.platform !== 'win32',
                 stdio: ['pipe', 'pipe', 'pipe']
             });
         }

package/dist/drivers/types.d.ts

@@ -9,6 +9,8 @@ export interface AgentDriver {
     env: NodeJS.ProcessEnv;
     permissionPolicy: PermissionPolicy;
     permissionTimeoutMs: number;
+    /** The spawned Agent owns a dedicated process group that can be terminated as a tree. */
+    ownsProcessGroup?: boolean;
     probe(): Promise<AgentdAgentView>;
     spawn(workspace: string): ChildProcessWithoutNullStreams;
 }

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export declare function startAgentd(configPath: string): Promise<{
     controlPlane: AgentdControlPlane;
     close(): Promise<void>;
 }>;
+export declare function closeServer(server: Server, graceMs?: number): Promise<void>;
 export * from './config.js';
 export * from './control-plane.js';
 export * from './server.js';

package/dist/index.js

@@ -24,8 +24,7 @@ export async function startAgentd(configPath) {
         runStore,
         controlPlane,
         async close() {
-            await closeServer(server);
-            await sessions.shutdown();
+            await Promise.all([closeServer(server), sessions.shutdown()]);
             await runStore.flush();
         }
     };
@@ -45,9 +44,24 @@ function listen(server, port, host) {
         server.listen(port, host);
     });
 }
-function closeServer(server) {
+export function closeServer(server, graceMs = 2_000) {
     return new Promise((resolve, reject) => {
-        server.close((error) => (error ? reject(error) : resolve()));
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const timer = setTimeout(() => {
+            server.closeAllConnections?.();
+            finish();
+        }, Math.max(0, graceMs));
+        server.close((error) => finish(error || undefined));
         server.closeIdleConnections?.();
     });
 }

package/dist/process-tree.d.ts

@@ -0,0 +1,5 @@
+import { type ChildProcess } from 'node:child_process';
+export declare function terminateProcessTree(child: ChildProcess, options?: {
+    ownsProcessGroup?: boolean;
+    graceMs?: number;
+}): Promise<void>;

package/dist/process-tree.js

@@ -0,0 +1,105 @@
+import { spawn } from 'node:child_process';
+const DEFAULT_GRACE_MS = 2_000;
+const FORCE_KILL_WAIT_MS = 1_000;
+export async function terminateProcessTree(child, options = {}) {
+    const pid = child.pid;
+    if (!pid || hasExited(child))
+        return;
+    const graceMs = Math.max(0, options.graceMs ?? DEFAULT_GRACE_MS);
+    if (process.platform === 'win32') {
+        await taskkill(pid, false);
+        if (await waitForExit(child, graceMs))
+            return;
+        await taskkill(pid, true);
+        await waitForExit(child, FORCE_KILL_WAIT_MS);
+        return;
+    }
+    if (options.ownsProcessGroup === true) {
+        signalUnixGroup(pid, 'SIGTERM');
+        if (await waitForUnixGroupExit(pid, graceMs))
+            return;
+        signalUnixGroup(pid, 'SIGKILL');
+        await waitForUnixGroupExit(pid, FORCE_KILL_WAIT_MS);
+        return;
+    }
+    signalUnix(child, 'SIGTERM');
+    if (await waitForExit(child, graceMs))
+        return;
+    signalUnix(child, 'SIGKILL');
+    await waitForExit(child, FORCE_KILL_WAIT_MS);
+}
+function signalUnix(child, signal) {
+    try {
+        child.kill(signal);
+    }
+    catch { }
+}
+function signalUnixGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch { }
+}
+async function waitForUnixGroupExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (unixGroupExists(pid)) {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return false;
+        await delay(Math.min(25, remaining));
+    }
+    return true;
+}
+function unixGroupExists(pid) {
+    try {
+        process.kill(-pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+function waitForExit(child, timeoutMs) {
+    if (hasExited(child))
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (exited) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.off('exit', onExit);
+            resolve(exited);
+        };
+        const onExit = () => finish(true);
+        const timer = setTimeout(() => finish(hasExited(child)), timeoutMs);
+        child.once('exit', onExit);
+        if (hasExited(child))
+            finish(true);
+    });
+}
+function taskkill(pid, force) {
+    return new Promise((resolve) => {
+        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 = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        killer.once('error', finish);
+        killer.once('exit', finish);
+    });
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function hasExited(child) {
+    return child.exitCode !== null || child.signalCode !== null;
+}

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 export type AgentdSessionState = 'created' | 'running' | 'input_required' | 'permission_required' | 'completed' | 'failed' | 'canceled';
 export type AgentdProtocol = 'acp' | 'a2a';
-export type PermissionPolicy = 'ask' | 'deny';
+export type PermissionPolicy = 'ask' | 'allow' | 'deny';
 export type AgentdTurnCompletionSource = 'acp_prompt_response' | 'a2a_task_status' | 'a2a_message_stream';
 export interface AgentdTurnCompletionProof {
     source: AgentdTurnCompletionSource;

package/dist/webui/app.js

@@ -441,9 +441,10 @@ export const app = String.raw `
       '</div></td><td><span class="badge">' + escapeHtml(agent.protocol.toUpperCase()) + '</span></td><td>' + escapeHtml(agent.driver || '—') + '</td><td>' + statusMarkup(statusAgent) + '</td><td>' + escapeHtml(agent.workspace || '—') + '</td><td>' + escapeHtml(permissionLabel(agent.permissionPolicy)) + '</td><td><div class="row-actions"><button class="button small" data-agent-edit="' + escapeHtml(agent.id) + '">编辑</button><button class="button small danger" data-agent-delete="' + escapeHtml(agent.id) + '">删除</button></div></td></tr>'
   }
 
-  function permissionLabel(value) {
-    if (value === 'ask') return '询问'
-    if (value === 'deny') return '拒绝'
+  function permissionLabel(value) {
+    if (value === 'ask') return '询问'
+    if (value === 'allow') return '始终允许'
+    if (value === 'deny') return '拒绝'
     return value || '—'
   }
 
@@ -545,7 +546,7 @@ export const app = String.raw `
       '<div class="field-row"><label>协议<select name="protocol"><option value="acp"' + selected(current.protocol, 'acp') + '>ACP</option><option value="a2a"' + selected(current.protocol, 'a2a') + '>A2A</option></select></label><label class="checkbox"><input name="enabled" type="checkbox"' + checked(current.enabled) + '>启用</label></div>' +
       '<label>名称<input name="name" value="' + escapeHtml(current.name || '') + '" required></label>' +
       '<label>描述<textarea name="description">' + escapeHtml(current.description || '') + '</textarea></label>' +
-      '<div data-protocol-section="acp"><label>驱动<select name="driver">' + drivers + '</select></label><label>工作区<input name="workspace" list="workspace-roots" value="' + escapeHtml(current.workspace || state.config.workspaceRoots[0] || '') + '" required><datalist id="workspace-roots">' + roots + '</datalist></label><div class="field-row"><label>权限策略<select name="permissionPolicy"><option value="ask"' + selected(current.permissionPolicy, 'ask') + '>询问</option><option value="deny"' + selected(current.permissionPolicy, 'deny') + '>拒绝</option></select></label><label>权限确认超时（秒）<input name="permissionTimeoutMs" type="number" min="1" max="86400" step="1" value="' + escapeHtml(permissionTimeoutSeconds) + '"><small class="field-help">单位：秒；默认 900 秒，最长 24 小时。</small></label></div></div>' +
+      '<div data-protocol-section="acp"><label>驱动<select name="driver">' + drivers + '</select></label><label>工作区<input name="workspace" list="workspace-roots" value="' + escapeHtml(current.workspace || state.config.workspaceRoots[0] || '') + '" required><datalist id="workspace-roots">' + roots + '</datalist></label><div class="field-row"><label>权限策略<select name="permissionPolicy"><option value="ask"' + selected(current.permissionPolicy, 'ask') + '>询问</option><option value="allow"' + selected(current.permissionPolicy, 'allow') + '>始终允许</option><option value="deny"' + selected(current.permissionPolicy, 'deny') + '>拒绝</option></select></label><label>权限确认超时（秒）<input name="permissionTimeoutMs" type="number" min="1" max="86400" step="1" value="' + escapeHtml(permissionTimeoutSeconds) + '"><small class="field-help">单位：秒；默认 900 秒，最长 24 小时；“始终允许”不会等待确认。</small></label></div></div>' +
       '<div data-protocol-section="a2a"><label>Agent Card URL<input name="agentCardUrl" type="url" value="' + escapeHtml(current.agentCardUrl || '') + '" placeholder="http://agent.local:8080/.well-known/agent-card.json" required><small class="field-help">填写完整的 Agent Card JSON 地址；调用地址和能力将从 Card 自动发现。</small></label><div class="field-row"><label>首选传输<select name="preferredTransport"><option value="auto"' + selected(current.preferredTransport || 'auto', 'auto') + '>自动（按 Card）</option><option value="jsonrpc"' + selected(current.preferredTransport, 'jsonrpc') + '>JSON-RPC</option><option value="http-json"' + selected(current.preferredTransport, 'http-json') + '>HTTP+JSON</option></select></label><label>认证方式<select name="authType"><option value="none"' + selected(current.auth && current.auth.type || 'none', 'none') + '>无认证</option><option value="bearer"' + selected(current.auth && current.auth.type, 'bearer') + '>Bearer Token</option><option value="header"' + selected(current.auth && current.auth.type, 'header') + '>自定义请求头</option></select></label></div><label data-auth-header>请求头名称<input name="authHeaderName" value="' + escapeHtml(current.auth && current.auth.headerName || '') + '" placeholder="X-API-Key"></label><label data-auth-value><span data-auth-value-label>认证凭据</span><input name="authValue" type="password" autocomplete="off" placeholder="' + (editing && current.auth && current.auth.configured ? '留空以保留当前凭据' : '') + '"></label><label>请求超时（秒）<input name="timeoutMs" type="number" min="1" max="1800" step="1" value="' + escapeHtml(requestTimeoutSeconds) + '"><small class="field-help">单位：秒；默认 60 秒；用于限制这个 A2A Agent 的单次请求，最大 1800 秒（30 分钟）。</small></label></div>'
     openDrawer(editing ? '编辑智能体' : '添加智能体', body, editing ? '保存修改' : '添加智能体', async (form) => {
       const data = new FormData(form)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-agentd",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Local Nexus Gateway daemon that exposes allowlisted Coding Agents through HTTP/SSE and ACP",
   "type": "module",
   "main": "dist/index.js",