nexus-agentd 0.4.1 → 0.5.0

package/README.md

@@ -108,6 +108,23 @@ Agent 的编辑页单独设置，默认 60 秒、最大 30 分钟。
 | `pi` | `pi-acp` |
 | `openclaw` | `openclaw acp` |
 | `hermes` | `hermes acp` |
+| `dsh` | `dsh --profile acp` |
+| `grok` | `grok --no-auto-update agent stdio` |
+
+`dsh` 与 `grok` 使用各自 CLI 自带的 ACP 入口，不需要 Adapter。
+
+`dsh`（DeepSeek Harness）默认执行 `dsh --profile acp`，要求 `dsh` 在 PATH 上。DeepSeek Harness
+桌面版把启动器放在 `<安装目录>\resources\runtime\cli\bin\dsh.cmd`，但不会自动出现在已运行进程的
+PATH 里；两种接法二选一：把该目录加入用户 PATH（桌面版的命令管理功能会写 HKCU 用户环境变量，新开的
+进程才看得到），或在本机配置里用 `command` 覆盖成绝对路径，例如
+`"command": "D:/DeepSeek/resources/runtime/cli/bin/dsh.cmd"`。
+
+`grok`（Grok Build）默认执行 `grok --no-auto-update agent stdio`；`--no-auto-update` 用于跳过
+自动化环境中的后台更新检查，可用本机配置的 `args` 覆盖。前置条件是 CLI 已完成认证，三选一：先跑
+`grok login` 缓存 token、用 `"inheritEnv": ["XAI_API_KEY"]` 把守护进程环境里的变量透传给 grok
+子进程、或用 `"env": { "XAI_API_KEY": "env:XAI_API_KEY" }` 显式赋值（`env:` 前缀从守护进程环境
+取值，变量缺失时配置加载直接报错）。Gateway 的 ACP 客户端不做 `authenticate` 请求，未认证时 grok
+会在握手后失败。DSH 是本地 agent，没有这个前置条件。
 
 Claude Code、Codex、Pi 通常需要对应 Adapter：
 
@@ -118,11 +135,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/artifact-store.js

@@ -2,6 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { chmod as fsChmod, lstat as fsLstat, mkdir as fsMkdir, open as fsOpen, readdir as fsReaddir, readFile as fsReadFile, rename as fsRename, rm as fsRm, unlink as fsUnlink, writeFile as fsWriteFile } from 'node:fs/promises';
 import { performance } from 'node:perf_hooks';
 import path from 'node:path';
+import { isPathInside } from './workspace.js';
 const DAY_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_MAX_ARTIFACT_BYTES = 12 * 1024 * 1024;
 const DEFAULT_MAX_ARTIFACTS_PER_RUN = 32;
@@ -354,7 +355,7 @@ export class ArtifactStore {
             await this.ensureDirectory(runDir, false);
             const runReal = await this.realDirectory(runDir);
             const fileReal = await this.realPath(entry.filePath);
-            if (!isContained(runReal, fileReal))
+            if (!isPathInside(runReal, fileReal))
                 return undefined;
             const stat = await this.io.lstat(entry.filePath);
             if (!stat.isFile() || stat.isSymbolicLink())
@@ -566,12 +567,16 @@ export class ArtifactStore {
         await this.io.mkdir(runDir, { recursive: true, mode: 0o700 });
         await this.ensureDirectory(runDir, false);
         const runReal = await this.realDirectory(runDir);
-        if (!isContained(await this.realDirectory(this.rootDir), runReal)) {
+        if (!isPathInside(await this.realDirectory(this.rootDir), runReal)) {
             throw new Error('Artifact run directory escaped the artifact root');
         }
         const filePath = this.payloadPath(item.runId, item.id);
-        const fileRealParent = path.dirname(filePath);
-        if (!isContained(runReal, fileRealParent))
+        // payloadPath() derives from the configured artifact root, which is not
+        // necessarily canonical (a Windows 8.3 short path or a symlinked parent),
+        // while runReal was resolved through realDirectory(). Compare the payload
+        // with the same canonical directory instead of the raw string.
+        const fileRealParent = await this.realDirectory(path.dirname(filePath));
+        if (!isPathInside(runReal, fileRealParent))
             throw new Error('Invalid artifact payload path');
         const delta = item.bytes.length - (entry.bytes || 0);
         const previousView = entry.durableView;
@@ -1161,10 +1166,6 @@ function nonNegativeInteger(value, fallback) {
 function nonNegativeNumber(value, fallback) {
     return Number.isFinite(value) && Number(value) >= 0 ? Number(value) : fallback;
 }
-function isContained(root, target) {
-    const relative = path.relative(root, target);
-    return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
-}
 function isMissing(error) {
     return error?.code === 'ENOENT';
 }

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/dsh.d.ts

@@ -0,0 +1,2 @@
+import type { AgentdDriverConfig } from '../types.js';
+export declare function createDshDriver(id: string, config: AgentdDriverConfig): import("./types.js").AgentDriver;

package/dist/drivers/dsh.js

@@ -0,0 +1,10 @@
+import { createStdioAcpDriver } from './stdio.js';
+export function createDshDriver(id, config) {
+    return createStdioAcpDriver(id, config, {
+        name: 'DeepSeek Harness',
+        description: 'DeepSeek Harness through its native ACP stdio profile',
+        command: 'dsh',
+        args: ['--profile', 'acp'],
+        probeArgs: ['--version']
+    });
+}

package/dist/drivers/grok.d.ts

@@ -0,0 +1,2 @@
+import type { AgentdDriverConfig } from '../types.js';
+export declare function createGrokDriver(id: string, config: AgentdDriverConfig): import("./types.js").AgentDriver;

package/dist/drivers/grok.js

@@ -0,0 +1,12 @@
+import { createStdioAcpDriver } from './stdio.js';
+export function createGrokDriver(id, config) {
+    return createStdioAcpDriver(id, config, {
+        name: 'Grok Build',
+        description: 'Grok Build through its native ACP stdio agent',
+        command: 'grok',
+        // The xAI CLI documents `--no-auto-update` for `grok agent stdio` in
+        // scripts and CI, which is exactly how this gateway launches it.
+        args: ['--no-auto-update', 'agent', 'stdio'],
+        probeArgs: ['version']
+    });
+}

package/dist/drivers/index.js

@@ -1,5 +1,7 @@
 import { createClaudeDriver } from './claude.js';
 import { createCodexDriver } from './codex.js';
+import { createDshDriver } from './dsh.js';
+import { createGrokDriver } from './grok.js';
 import { createHermesDriver } from './hermes.js';
 import { createOpenCodeDriver } from './opencode.js';
 import { createOpenClawDriver } from './openclaw.js';
@@ -42,6 +44,12 @@ export function createDriverRegistry(config) {
             case 'hermes':
                 drivers.set(id, createHermesDriver(id, driver));
                 break;
+            case 'dsh':
+                drivers.set(id, createDshDriver(id, driver));
+                break;
+            case 'grok':
+                drivers.set(id, createGrokDriver(id, driver));
+                break;
         }
     }
     return drivers;

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/session.d.ts

@@ -52,6 +52,11 @@ export declare class ManagedSession implements AgentSessionSink, AcpSessionSink
     private runtime?;
     private readonly artifactStore?;
     private readonly onRunUpdate?;
+    /**
+     * `workspace` must be the canonical path the workspace policy resolved at
+     * session creation. Callers that hand over a raw path would make publish
+     * compare a non-canonical root against realpath'd targets.
+     */
     constructor(agentId: string, protocol: AgentdProtocol, workspace: string | undefined, ownerKeyId: string, maxEvents: number, maxOutputChars: number, agentName: string, runStore?: RunStore | undefined, instanceId?: string, artifactStore?: SessionArtifactStore, onRunUpdate?: (runId: string, state: AgentdSessionState) => void);
     attach(runtime: AgentSessionRuntime): void;
     runtimeAvailable(): boolean;

package/dist/session.js

@@ -1,5 +1,4 @@
 import { randomUUID } from 'node:crypto';
-import { realpath } from 'node:fs/promises';
 import { extname } from 'node:path';
 import { AcpProcessRuntime } from './acp/runtime.js';
 import { A2AClientRuntime } from './a2a/runtime.js';
@@ -40,6 +39,11 @@ export class ManagedSession {
     runtime;
     artifactStore;
     onRunUpdate;
+    /**
+     * `workspace` must be the canonical path the workspace policy resolved at
+     * session creation. Callers that hand over a raw path would make publish
+     * compare a non-canonical root against realpath'd targets.
+     */
     constructor(agentId, protocol, workspace, ownerKeyId, maxEvents, maxOutputChars, agentName, runStore, instanceId = randomUUID(), artifactStore, onRunUpdate) {
         this.agentId = agentId;
         this.protocol = protocol;
@@ -204,8 +208,12 @@ export class ManagedSession {
     }
     async publishSingleFile(requestedPath) {
         try {
-            const workspaceRoot = await realpath(this.workspace);
-            const file = await readContainedFile([workspaceRoot], requestedPath, {
+            // `this.workspace` is the canonical path the session was created
+            // with, already resolved through the workspace policy. Resolving it
+            // again here would hand the trust decision back to the file system,
+            // so a workspace replaced by a link after creation would silently
+            // become the new root and publish would read outside the allowlist.
+            const file = await readContainedFile([this.workspace], requestedPath, {
                 maxBytes: MAX_PUBLISHED_FILE_BYTES
             });
             const artifact = {

package/dist/types.d.ts

@@ -14,7 +14,7 @@ export interface AgentdTurnCompletion extends AgentdTurnCompletionProof {
     artifactCount: number;
     completedAt: number;
 }
-export declare const agentdDriverKinds: readonly ["stdio", "opencode", "claude", "codex", "pi", "openclaw", "hermes"];
+export declare const agentdDriverKinds: readonly ["stdio", "opencode", "claude", "codex", "pi", "openclaw", "hermes", "dsh", "grok"];
 export type AgentdDriverKind = (typeof agentdDriverKinds)[number];
 export interface AgentdDriverConfig {
     protocol?: 'acp';
@@ -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/dist/types.js

@@ -5,5 +5,7 @@ export const agentdDriverKinds = [
     'codex',
     'pi',
     'openclaw',
-    'hermes'
+    'hermes',
+    'dsh',
+    'grok'
 ];

package/dist/workspace.d.ts

@@ -5,7 +5,27 @@ export declare class WorkspacePolicy {
     resolve(input: string): Promise<string>;
     listRoots(): string[];
 }
-export declare function isWithin(root: string, candidate: string): boolean;
+/**
+ * Reports whether `target` is `root` itself or lives below it.
+ *
+ * Both arguments must already be canonical (realpath'd) absolute paths.
+ * `realpath` returns the spelling stored on disk, so on a normal
+ * case-insensitive volume two differently-cased spellings of one directory still
+ * compare equal here. A prefix comparison is used rather than `path.relative`,
+ * whose win32 implementation lower-cases both sides and would therefore read a
+ * case-variant sibling inside a case-sensitive directory as contained. The
+ * separator is required so that `\\server\share2` is not read as living inside
+ * `\\server\share`.
+ *
+ * `path.resolve` only folds lexical noise (`.`, `..`, duplicate separators) for
+ * callers that hand over a hand-written path, which the previous
+ * `path.relative` implementation also tolerated. It must never be replaced with
+ * `realpath`: resolving against the file system here would hand the trust
+ * decision back to whatever the directory currently points at.
+ */
+export declare function isPathInside(root: string, target: string): boolean;
+/** @deprecated Use {@link isPathInside}. Kept because this module is re-exported. */
+export declare const isWithin: typeof isPathInside;
 export type ContainedReadFailure = 'outside' | 'swapped' | 'not-a-file' | 'too-large';
 /**
  * Reported as a kind rather than a finished message because each caller owns a
@@ -27,10 +47,15 @@ export interface ContainedFile {
 /**
  * Reads a file that must resolve inside one of `roots`.
  *
- * `roots` must already be realpath'd absolute paths; `WorkspacePolicy.listRoots()`
- * satisfies this. A caller that passes an unresolved root fails closed, because
- * containment is checked against a realpath'd target. `requested` may be absolute
- * (an agent-declared path) or relative to `roots[0]` (a client-supplied path).
+ * `roots` must be the canonical paths the caller decided to trust — not the
+ * result of a fresh `realpath()` of that same path. Re-resolving a root at call
+ * time hands the containment decision back to the file system, so a link
+ * planted after the decision (for example a workspace swapped for a junction)
+ * would move the trust boundary with it. `WorkspacePolicy.listRoots()` and a
+ * session's own canonical workspace both satisfy this. An unresolved root fails
+ * closed, because containment is checked against a realpath'd target.
+ * `requested` may be absolute (an agent-declared path) or relative to `roots[0]`
+ * (a client-supplied path).
  */
 export declare function readContainedFile(roots: readonly string[], requested: string, options: {
     maxBytes: number;

package/dist/workspace.js

@@ -13,7 +13,7 @@ export class WorkspacePolicy {
         if (!input?.trim())
             throw new Error('workspace is required');
         const candidate = normalize(await realpath(input));
-        const allowed = this.roots.some((root) => isWithin(root, candidate));
+        const allowed = this.roots.some((root) => isPathInside(root, candidate));
         if (!allowed)
             throw new Error(`workspace is outside the configured allowlist: ${input}`);
         return candidate;
@@ -22,13 +22,34 @@ export class WorkspacePolicy {
         return [...this.roots];
     }
 }
-export function isWithin(root, candidate) {
-    const relative = path.relative(root, candidate);
-    return (relative === '' ||
-        (!relative.startsWith(`..${path.sep}`) &&
-            relative !== '..' &&
-            !path.isAbsolute(relative)));
+/**
+ * Reports whether `target` is `root` itself or lives below it.
+ *
+ * Both arguments must already be canonical (realpath'd) absolute paths.
+ * `realpath` returns the spelling stored on disk, so on a normal
+ * case-insensitive volume two differently-cased spellings of one directory still
+ * compare equal here. A prefix comparison is used rather than `path.relative`,
+ * whose win32 implementation lower-cases both sides and would therefore read a
+ * case-variant sibling inside a case-sensitive directory as contained. The
+ * separator is required so that `\\server\share2` is not read as living inside
+ * `\\server\share`.
+ *
+ * `path.resolve` only folds lexical noise (`.`, `..`, duplicate separators) for
+ * callers that hand over a hand-written path, which the previous
+ * `path.relative` implementation also tolerated. It must never be replaced with
+ * `realpath`: resolving against the file system here would hand the trust
+ * decision back to whatever the directory currently points at.
+ */
+export function isPathInside(root, target) {
+    const base = path.resolve(root);
+    const candidate = path.resolve(target);
+    if (candidate === base)
+        return true;
+    const prefix = base.endsWith(path.sep) ? base : base + path.sep;
+    return candidate.startsWith(prefix);
 }
+/** @deprecated Use {@link isPathInside}. Kept because this module is re-exported. */
+export const isWithin = isPathInside;
 /**
  * Reported as a kind rather than a finished message because each caller owns a
  * different error contract: workspace publish maps it to an HTTP status, while a
@@ -45,10 +66,15 @@ export class ContainedReadError extends Error {
 /**
  * Reads a file that must resolve inside one of `roots`.
  *
- * `roots` must already be realpath'd absolute paths; `WorkspacePolicy.listRoots()`
- * satisfies this. A caller that passes an unresolved root fails closed, because
- * containment is checked against a realpath'd target. `requested` may be absolute
- * (an agent-declared path) or relative to `roots[0]` (a client-supplied path).
+ * `roots` must be the canonical paths the caller decided to trust — not the
+ * result of a fresh `realpath()` of that same path. Re-resolving a root at call
+ * time hands the containment decision back to the file system, so a link
+ * planted after the decision (for example a workspace swapped for a junction)
+ * would move the trust boundary with it. `WorkspacePolicy.listRoots()` and a
+ * session's own canonical workspace both satisfy this. An unresolved root fails
+ * closed, because containment is checked against a realpath'd target.
+ * `requested` may be absolute (an agent-declared path) or relative to `roots[0]`
+ * (a client-supplied path).
  */
 export async function readContainedFile(roots, requested, options) {
     if (!roots.length) {
@@ -56,7 +82,7 @@ export async function readContainedFile(roots, requested, options) {
     }
     const unresolved = path.resolve(roots[0], requested);
     const target = await realpath(unresolved);
-    const root = roots.find((candidate) => isWithin(candidate, target));
+    const root = roots.find((candidate) => isPathInside(candidate, target));
     if (!root)
         throw outsideError(requested);
     let handle;
@@ -65,7 +91,7 @@ export async function readContainedFile(roots, requested, options) {
         // Resolve again after opening so a swapped symlink cannot silently
         // redirect the read outside the allowlist.
         const verified = await realpath(unresolved);
-        if (!isWithin(root, verified))
+        if (!isPathInside(root, verified))
             throw outsideError(requested);
         if (verified !== target) {
             throw new ContainedReadError('swapped', 'file changed while it was being opened');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexus-agentd",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "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",
@@ -36,7 +36,7 @@
   "scripts": {
     "build": "node scripts/generate-webui-sources.mjs && node scripts/clean-dist.mjs && tsc -p tsconfig.json",
     "typecheck": "node scripts/generate-webui-sources.mjs && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.webui.json",
-    "test": "tsx --test --test-force-exit --test-concurrency=1 test/*.test.ts",
+    "test": "node scripts/run-tests.mjs",
     "test:webui": "node scripts/generate-webui-sources.mjs && playwright test",
     "prepack": "npm run build"
   },