nexus-agentd 0.2.3 → 0.2.6

package/dist/workspace.d.ts

@@ -5,3 +5,33 @@ export declare class WorkspacePolicy {
     resolve(input: string): Promise<string>;
     listRoots(): string[];
 }
+export declare function isWithin(root: string, candidate: string): boolean;
+export type ContainedReadFailure = 'outside' | 'swapped' | 'not-a-file' | 'too-large';
+/**
+ * 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
+ * MEDIA marker maps it to a terminal_output event.
+ */
+export declare class ContainedReadError extends Error {
+    readonly failure: ContainedReadFailure;
+    constructor(failure: ContainedReadFailure, message: string);
+}
+export interface ContainedFile {
+    root: string;
+    path: string;
+    relative: string;
+    filename: string;
+    bytes: Buffer;
+    size: number;
+}
+/**
+ * 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).
+ */
+export declare function readContainedFile(roots: readonly string[], requested: string, options: {
+    maxBytes: number;
+}): Promise<ContainedFile>;

package/dist/workspace.js

@@ -1,4 +1,4 @@
-import { realpath } from 'node:fs/promises';
+import { open, realpath } from 'node:fs/promises';
 import path from 'node:path';
 export class WorkspacePolicy {
     roots;
@@ -22,13 +22,78 @@ export class WorkspacePolicy {
         return [...this.roots];
     }
 }
-function isWithin(root, candidate) {
+export function isWithin(root, candidate) {
     const relative = path.relative(root, candidate);
     return (relative === '' ||
         (!relative.startsWith(`..${path.sep}`) &&
             relative !== '..' &&
             !path.isAbsolute(relative)));
 }
+/**
+ * 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
+ * MEDIA marker maps it to a terminal_output event.
+ */
+export class ContainedReadError extends Error {
+    failure;
+    constructor(failure, message) {
+        super(message);
+        this.failure = failure;
+        this.name = 'ContainedReadError';
+    }
+}
+/**
+ * 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).
+ */
+export async function readContainedFile(roots, requested, options) {
+    if (!roots.length) {
+        throw new ContainedReadError('outside', 'no workspace root is configured');
+    }
+    const unresolved = path.resolve(roots[0], requested);
+    const target = await realpath(unresolved);
+    const root = roots.find((candidate) => isWithin(candidate, target));
+    if (!root)
+        throw outsideError(requested);
+    let handle;
+    try {
+        handle = await open(target, 'r');
+        // 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))
+            throw outsideError(requested);
+        if (verified !== target) {
+            throw new ContainedReadError('swapped', 'file changed while it was being opened');
+        }
+        const stats = await handle.stat();
+        if (!stats.isFile()) {
+            throw new ContainedReadError('not-a-file', 'path is not a regular file');
+        }
+        if (stats.size > options.maxBytes) {
+            throw new ContainedReadError('too-large', `file exceeds the ${options.maxBytes} byte limit`);
+        }
+        const bytes = await handle.readFile();
+        return {
+            root,
+            path: verified,
+            relative: path.relative(root, verified).split(path.sep).join('/'),
+            filename: path.basename(verified),
+            bytes,
+            size: bytes.length
+        };
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function outsideError(requested) {
+    return new ContainedReadError('outside', `path is outside the configured allowlist: ${requested}`);
+}
 function normalize(value) {
     return path.resolve(value);
 }

package/nexus-agentd.example.json

@@ -1,40 +1,40 @@
-{
-  "initialized": false,
-  "listen": {
-    "host": "0.0.0.0",
-    "port": 8787
-  },
-  "workspaceRoots": [
-    "/data/repos"
-  ],
-  "apiKeys": [],
-  "maxRequestBytes": 1048576,
-  "maxAttachmentBytes": 33554432,
-  "requestTimeoutMs": 30000,
-  "promptTimeoutMs": 1800000,
-  "cleanupIntervalMs": 60000,
-  "maxSessions": 64,
-  "maxSseConnections": 128,
-  "maxConnections": 256,
-  "sessionTtlMs": 86400000,
-  "agents": {
-    "codex": {
-      "protocol": "acp",
-      "driver": "codex",
-      "name": "Codex",
-      "command": "codex-acp",
-      "workspace": "/data/repos/project",
-      "permissionPolicy": "ask"
-    },
-    "research": {
-      "protocol": "a2a",
-      "name": "Research Agent",
-      "agentCardUrl": "http://192.168.1.20:8080/.well-known/agent-card.json",
-      "preferredTransport": "auto",
-      "auth": {
-        "type": "none"
-      },
-      "timeoutMs": 60000
-    }
-  }
-}
+{
+  "initialized": false,
+  "listen": {
+    "host": "0.0.0.0",
+    "port": 8787
+  },
+  "workspaceRoots": [
+    "/data/repos"
+  ],
+  "apiKeys": [],
+  "maxRequestBytes": 1048576,
+  "maxAttachmentBytes": 33554432,
+  "requestTimeoutMs": 30000,
+  "promptTimeoutMs": 1800000,
+  "cleanupIntervalMs": 60000,
+  "maxSessions": 64,
+  "maxSseConnections": 128,
+  "maxConnections": 256,
+  "sessionTtlMs": 86400000,
+  "agents": {
+    "codex": {
+      "protocol": "acp",
+      "driver": "codex",
+      "name": "Codex",
+      "command": "codex-acp",
+      "workspace": "/data/repos/project",
+      "permissionPolicy": "ask"
+    },
+    "research": {
+      "protocol": "a2a",
+      "name": "Research Agent",
+      "agentCardUrl": "http://192.168.1.20:8080/.well-known/agent-card.json",
+      "preferredTransport": "auto",
+      "auth": {
+        "type": "none"
+      },
+      "timeoutMs": 60000
+    }
+  }
+}

package/package.json

@@ -1,52 +1,54 @@
-{
-  "name": "nexus-agentd",
-  "version": "0.2.3",
-  "description": "Local Nexus Gateway daemon that exposes allowlisted Coding Agents through HTTP/SSE and ACP",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "nexus-agentd": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "nexus-agentd.example.json",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=20.0.0"
-  },
-  "author": "lumia1998",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lumia1998/nexus-gateway.git"
-  },
-  "bugs": {
-    "url": "https://github.com/lumia1998/nexus-gateway/issues"
-  },
-  "homepage": "https://github.com/lumia1998/nexus-gateway#readme",
-  "keywords": [
-    "agent-client-protocol",
-    "acp",
-    "agent",
-    "gateway",
-    "coding-agent"
-  ],
-  "scripts": {
-    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "tsx --test test/*.test.ts",
-    "prepack": "npm run build"
-  },
-  "dependencies": {
-    "@a2a-js/sdk": "^1.0.1",
-    "@agentclientprotocol/sdk": "1.3.0",
-    "zod": "^3.25.76"
-  },
-  "devDependencies": {
-    "@types/node": "^20.14.0",
-    "tsx": "^4.21.0",
-    "typescript": "^5.6.0"
-  },
-  "license": "MIT"
-}
+{
+  "name": "nexus-agentd",
+  "version": "0.2.6",
+  "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",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "nexus-agentd": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "nexus-agentd.example.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "lumia1998",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lumia1998/nexus-gateway.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lumia1998/nexus-gateway/issues"
+  },
+  "homepage": "https://github.com/lumia1998/nexus-gateway#readme",
+  "keywords": [
+    "agent-client-protocol",
+    "acp",
+    "agent",
+    "gateway",
+    "coding-agent"
+  ],
+  "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",
+    "test": "tsx --test test/*.test.ts",
+    "test:webui": "node scripts/generate-webui-sources.mjs && playwright test",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@a2a-js/sdk": "^1.0.1",
+    "@agentclientprotocol/sdk": "1.3.0",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.62.1",
+    "@types/node": "^20.14.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.0"
+  },
+  "license": "MIT"
+}

package/dist/webui/app.d.ts

@@ -1 +0,0 @@
-export declare const app: string;