nexus-agentd 0.2.5 → 0.3.0

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/examples/client.mjs

@@ -0,0 +1,102 @@
+import { setTimeout as delay } from 'node:timers/promises'
+
+/** Minimal Node 20+ client. Keep API Keys out of URLs and browser storage. */
+export function createGatewayClient(baseUrl, apiKey) {
+    const base = new URL(baseUrl)
+    const headers = { Authorization: `Bearer ${apiKey}` }
+    const route = (sessionId) => `/v1/sessions/${encodeURIComponent(sessionId)}`
+    async function request(path, method = 'GET', body, signal) {
+        const response = await fetch(new URL(path, base), {
+            method, headers: { ...headers, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(30_000)]) : AbortSignal.timeout(30_000),
+            redirect: 'error'
+        })
+        if (!response.ok) {
+            const error = new Error(`Gateway request failed (${response.status})`)
+            error.status = response.status
+            await response.body?.cancel()
+            throw error
+        }
+        return response.json()
+    }
+    return {
+        createSession: (agentId, workspace) => request('/v1/sessions', 'POST', { agentId, workspace }),
+        snapshot: (id) => request(route(id)),
+        message: (id, message) => request(`${route(id)}/message`, 'POST', { message }),
+        resolve: (id, requestId, answer) => request(`${route(id)}/requests/${encodeURIComponent(requestId)}/resolve`, 'POST', answer),
+        cancel: (id) => request(`${route(id)}/cancel`, 'POST', {}),
+        close: (id) => request(route(id), 'DELETE'),
+        /** A reset yields a replacement snapshot; old discarded events are not replayed. */
+        async *events(id, { after, signal = new AbortController().signal } = {}) {
+            let cursor = after
+            let retries = 0
+            while (!signal.aborted) {
+                const connection = new AbortController()
+                const combined = AbortSignal.any([signal, connection.signal])
+                let timer = setTimeout(() => connection.abort(new Error('SSE connection timeout')), 15_000)
+                let reader
+                let reset = false
+                try {
+                    const response = await fetch(new URL(`${route(id)}/events`, base), {
+                        headers: { ...headers, ...(cursor === undefined ? {} : { 'Last-Event-ID': cursor }) },
+                        signal: combined, redirect: 'error'
+                    })
+                    clearTimeout(timer)
+                    if (!response.ok) {
+                        const error = new Error(`SSE request failed (${response.status})`)
+                        error.status = response.status
+                        await response.body?.cancel()
+                        throw error
+                    }
+                    reader = response.body.getReader()
+                    const decoder = new TextDecoder()
+                    let buffer = ''
+                    while (!signal.aborted && !reset) {
+                        timer = setTimeout(() => connection.abort(new Error('SSE heartbeat timeout')), 45_000)
+                        const { value, done } = await reader.read()
+                        clearTimeout(timer)
+                        if (done) break
+                        buffer += decoder.decode(value, { stream: true }).replace(/\r/g, '')
+                        if (buffer.length > 2 * 1024 * 1024) throw new Error('SSE frame limit exceeded')
+                        let end
+                        while ((end = buffer.indexOf('\n\n')) >= 0) {
+                            const frame = buffer.slice(0, end)
+                            buffer = buffer.slice(end + 2)
+                            const lines = frame.split('\n')
+                            const data = lines.filter((line) => line.startsWith('data:')).map((line) => line.slice(5).trimStart()).join('\n')
+                            if (!data) continue // Heartbeat comments carry no event.
+                            const type = lines.find((line) => line.startsWith('event:'))?.slice(6).trim()
+                            const eventId = lines.find((line) => line.startsWith('id:'))?.slice(3).trim()
+                            if (type === 'reset') {
+                                // Use our fixed same-origin Session route, never a remote recovery URL.
+                                const snapshot = await request(route(id), 'GET', undefined, signal)
+                                cursor = snapshot.lastEventId || '0'
+                                yield { type: 'reset', data: snapshot, recovery: JSON.parse(data) }
+                                reset = true
+                                break
+                            }
+                            if (!eventId || !/^\d+$/.test(eventId)) continue
+                            if (cursor !== undefined && BigInt(eventId) <= BigInt(cursor)) continue
+                            cursor = eventId
+                            retries = 0
+                            yield JSON.parse(data)
+                        }
+                    }
+                } catch (error) {
+                    if (signal.aborted) return
+                    // A revoked Key, narrowed scope or deleted/restarted Session needs user action.
+                    if ([401, 403, 404].includes(error.status)) throw error
+                } finally {
+                    clearTimeout(timer)
+                    connection.abort()
+                    await reader?.cancel().catch(() => {})
+                }
+                if (!reset && !signal.aborted) {
+                    await delay(Math.min(30_000, 500 * 2 ** Math.min(retries++, 6)) + Math.random() * 250,
+                        undefined, { signal }).catch((error) => { if (!signal.aborted) throw error })
+                }
+            }
+        }
+    }
+}

package/nexus-agentd.example.json

@@ -16,8 +16,27 @@
   "maxSessions": 64,
   "maxSseConnections": 128,
   "maxConnections": 256,
-  "sessionTtlMs": 86400000,
-  "agents": {
+  "sessionTtlMs": 86400000,
+  "quotas": {
+    "maxSessionsPerKey": 16,
+    "maxRunningRunsPerKey": 4,
+    "maxSsePerKey": 8,
+    "maxUploadBytesPerKey": 33554432
+  },
+  "history": { "maxRuns": 1000, "retentionDays": 30, "maxBytes": 67108864 },
+  "artifacts": { "retentionDays": 30, "maxBytes": 536870912, "maxArtifactBytes": 12582912, "maxQueuedBytes": 67108864 },
+  "agents": {
+    "custom": {
+      "protocol": "acp",
+      "driver": "stdio",
+      "name": "Custom ACP",
+      "enabled": false,
+      "command": "your-acp-agent",
+      "args": [],
+      "probeArgs": ["--version"],
+      "workspace": "/data/repos/project",
+      "permissionPolicy": "ask"
+    },
     "codex": {
       "protocol": "acp",
       "driver": "codex",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nexus-agentd",
-  "version": "0.2.5",
-  "description": "Local Nexus Gateway daemon that exposes allowlisted Coding Agents through HTTP/SSE and ACP",
+  "version": "0.3.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",
   "types": "dist/index.d.ts",
@@ -10,6 +10,7 @@
   },
   "files": [
     "dist",
+    "examples",
     "nexus-agentd.example.json",
     "README.md"
   ],
@@ -34,8 +35,9 @@
   ],
   "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",
+    "typecheck": "node scripts/generate-webui-sources.mjs && tsc -p tsconfig.json --noEmit && tsc -p tsconfig.webui.json",
     "test": "tsx --test test/*.test.ts",
+    "test:webui": "node scripts/generate-webui-sources.mjs && playwright test",
     "prepack": "npm run build"
   },
   "dependencies": {
@@ -44,6 +46,7 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@playwright/test": "^1.62.1",
     "@types/node": "^20.14.0",
     "tsx": "^4.21.0",
     "typescript": "^5.6.0"