nexus-agentd 0.2.3 → 0.2.5

package/README.md

@@ -62,22 +62,22 @@ Workspace 配置保持不变。
   默认值分别是 24 小时、30 分钟和 60 秒；A2A 请求超时在每个 Agent 的编辑页单独设置，默认 60 秒、
   最大 30 分钟。
 
-## Agent 协议
-
-每个任务都会附带协议级完成约束：Agent 在结束 turn 前必须处理完工作，等待用户输入或授权时必须使用
-协议请求，并提供非空最终说明或 Artifact。Gateway 只接受以下完成证明：
-
-- ACP `session/prompt` 返回 `stopReason=end_turn`；`max_tokens`、`max_turn_requests`、拒绝和取消不会被
-  误报为成功。
-- A2A Task 明确进入 `COMPLETED`；如果远端直接返回 Message 而没有创建 Task，则以完整消息流结束作为
-  turn 边界。已经出现 Task 状态但没有终态的流会标记失败。
-- Session 仍有待处理的 permission/input 请求，或者最终文本与 Artifact 都为空时，不允许进入
-  `completed`。
-
-成功的 Session 响应包含 `completion`，其中记录当前 Run ID、协议、完成来源、stop reason、最终文本和
-产物存在性以及完成时间。这个证明验证的是协议边界和结果存在性，不替代业务内容本身的语义验收。
-
-### ACP
+## Agent 协议
+
+每个任务都会附带协议级完成约束：Agent 在结束 turn 前必须处理完工作，等待用户输入或授权时必须使用
+协议请求，并提供非空最终说明或 Artifact。Gateway 只接受以下完成证明：
+
+- ACP `session/prompt` 返回 `stopReason=end_turn`；`max_tokens`、`max_turn_requests`、拒绝和取消不会被
+  误报为成功。
+- A2A Task 明确进入 `COMPLETED`；如果远端直接返回 Message 而没有创建 Task，则以完整消息流结束作为
+  turn 边界。已经出现 Task 状态但没有终态的流会标记失败。
+- Session 仍有待处理的 permission/input 请求，或者最终文本与 Artifact 都为空时，不允许进入
+  `completed`。
+
+成功的 Session 响应包含 `completion`，其中记录当前 Run ID、协议、完成来源、stop reason、最终文本和
+产物存在性以及完成时间。这个证明验证的是协议边界和结果存在性，不替代业务内容本身的语义验收。
+
+### ACP
 
 | Driver | 默认入口 |
 |---|---|
@@ -97,12 +97,12 @@ npm install -g \
   pi-acp
 ```
 
-`command`、`args`、`inheritEnv` 和 `env` 是仅可在本机配置文件修改的高级字段，WebUI 不接受这些
-字段。Workspace 在启动进程前经过 `realpath` 边界校验。
-
-ACP 权限策略支持 `ask`（询问）、`allow`（始终允许）和 `deny`（拒绝）。`allow` 会优先选择
-Agent 提供的 `allow_once`，不创建待确认请求；它适合管理员明确授权、工作区边界可信的自动化 Agent。
-默认仍为 `ask`。
+`command`、`args`、`inheritEnv` 和 `env` 是仅可在本机配置文件修改的高级字段，WebUI 不接受这些
+字段。Workspace 在启动进程前经过 `realpath` 边界校验。
+
+ACP 权限策略支持 `ask`（询问）、`allow`（始终允许）和 `deny`（拒绝）。`allow` 会优先选择
+Agent 提供的 `allow_once`，不创建待确认请求；它适合管理员明确授权、工作区边界可信的自动化 Agent。
+默认仍为 `ask`。
 
 ### A2A
 
@@ -150,14 +150,15 @@ A2A 使用官方 `@a2a-js/sdk` 客户端，通过完整的 Agent Card URL 发现
 }
 ```
 
-输入附件通过 Session 临时保存，默认单个文件最多 16 MiB、单个 Session 最多 32 MiB、最多 16 个文件；
+输入附件通过 Session 临时保存，默认单个文件最多 16 MiB、单个 Session 最多 32 MiB、最多 16 个文件；
 HTTP 上传总上限由 `maxAttachmentBytes` 控制，默认 32 MiB，允许调整到 64 MiB。Session 释放时附件也会
 一起清理。ACP 会优先使用 Agent 声明支持的 image/audio/embeddedContext 能力，否则为 Agent 提供受限的
-`file://` resource link；A2A 则以带文件名和媒体类型的二进制 Part 发送。
-
-ACP Session 还支持显式发布工作区文件。发布接口只接受 realpath 仍位于该 Session 工作区中的普通文件，
-拒绝目录、路径穿越和符号链接逃逸，单个文件最多 12 MiB。响应将文件作为 Session Artifact 返回；不会
-暴露宿主机绝对路径。
+`file://` resource link；A2A 则以带文件名和媒体类型的二进制 Part 发送。
+
+ACP Session 还支持显式发布工作区文件。发布接口只接受 realpath 仍位于该 Session 工作区中的普通文件，
+拒绝目录、路径穿越和符号链接逃逸，单个文件最多 12 MiB。请求 body 支持单文件 `{ "path": "..." }` 或
+批量 `{ "paths": ["..."] }`（一次最多 32 条），响应在正常 Session 视图上附加
+`publishedArtifacts` 数组，本次发布的文件以 base64 内联返回；不会暴露宿主机绝对路径，也不生成外部 URL。
 
 API Key 与 A2A 认证值支持 `env:VAR`。Console Password 哈希由 WebUI 管理，不要手工生成或把
 旧 `authToken` 复制到该字段。
@@ -200,27 +201,27 @@ POST   /v1/admin/api-keys/:id/reveal
 POST   /v1/admin/api-keys/:id/regenerate
 ```
 
-Bearer API Key 数据面：
-
-```text
-GET  /v1/meta
-GET  /v1/agents
-POST /v1/sessions
-GET  /v1/sessions/:id
-DELETE /v1/sessions/:id
-POST /v1/sessions/:id/attachments
-POST /v1/sessions/:id/message
-POST /v1/sessions/:id/requests/:requestId/resolve
-POST /v1/sessions/:id/artifacts/publish
-POST /v1/sessions/:id/cancel
-GET  /v1/sessions/:id/events
-```
-
-`/v1/meta` 和 Session 响应包含 Gateway `instanceId`；完成的 Session 还包含与当前 Run 绑定的
-`completion` 证明，客户端可识别进程重启和迟到/伪造的完成状态。授权与输入通过精确的
-`requestId` 解析；过期 ID 返回 `409`，不会误答后续请求。`DELETE /v1/sessions/:id` 会取消活动任务、
-释放 Agent 整个进程组并移除内存 Session。Gateway 停止时会先终止 Session，再在有限宽限期后关闭残留
-HTTP/SSE 连接，避免长连接或 Agent 孙进程阻塞服务重启。
+Bearer API Key 数据面：
+
+```text
+GET  /v1/meta
+GET  /v1/agents
+POST /v1/sessions
+GET  /v1/sessions/:id
+DELETE /v1/sessions/:id
+POST /v1/sessions/:id/attachments
+POST /v1/sessions/:id/message
+POST /v1/sessions/:id/requests/:requestId/resolve
+POST /v1/sessions/:id/artifacts/publish
+POST /v1/sessions/:id/cancel
+GET  /v1/sessions/:id/events
+```
+
+`/v1/meta` 和 Session 响应包含 Gateway `instanceId`；完成的 Session 还包含与当前 Run 绑定的
+`completion` 证明，客户端可识别进程重启和迟到/伪造的完成状态。授权与输入通过精确的
+`requestId` 解析；过期 ID 返回 `409`，不会误答后续请求。`DELETE /v1/sessions/:id` 会取消活动任务、
+释放 Agent 整个进程组并移除内存 Session。Gateway 停止时会先终止 Session，再在有限宽限期后关闭残留
+HTTP/SSE 连接，避免长连接或 Agent 孙进程阻塞服务重启。
 
 API Key 的 Agent scope 在 Agent inventory、Session 创建和后续 Session 操作上都会检查；Session
 还绑定创建它的 Key，其他 Key 即使拥有同一 Agent scope 也不能读取或控制该 Session。

package/dist/a2a/runtime.js

@@ -280,13 +280,16 @@ export class A2AClientRuntime {
                 this.sink.clearPending();
                 this.sink.setState('canceled');
                 break;
-            case TaskState.TASK_STATE_INPUT_REQUIRED:
+            case TaskState.TASK_STATE_INPUT_REQUIRED: {
+                const classification = a2aInputClassification(statusText, status.message);
                 this.sink.setPending({
                     id: this.taskId || randomUUID(),
                     kind: 'input',
-                    prompt: statusText || 'The A2A agent requires additional input.'
+                    prompt: statusText || 'The A2A agent requires additional input.',
+                    ...classification
                 });
                 break;
+            }
             case TaskState.TASK_STATE_FAILED:
             case TaskState.TASK_STATE_REJECTED:
             case TaskState.TASK_STATE_AUTH_REQUIRED:
@@ -450,3 +453,37 @@ function disabledView(id, config) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * Detect payment / confirmation / choice hints in an A2A `input_required`
+ * message so the Gateway can surface them on `pendingRequest.metadata` and
+ * `inputType`. The A2A protocol has no first-class field for these so we
+ * scan text parts for URLs and simple keywords.
+ */
+function a2aInputClassification(statusText, message) {
+    const metadata = {};
+    const haystack = [
+        statusText,
+        ...(message?.parts ? textParts(message.parts) : [])
+    ]
+        .filter(Boolean)
+        .join('\n');
+    const urlMatch = haystack.match(/https?:\/\/\S+/);
+    if (urlMatch)
+        metadata.url = urlMatch[0];
+    let inputType = 'text';
+    if (/pay|支付|invoice|checkout|订单支付/i.test(haystack)) {
+        inputType = 'payment';
+        if (urlMatch)
+            metadata.paymentUrl = urlMatch[0];
+    }
+    else if (/[（(]\s*[yY]\s*\/\s*[nN]\s*[)）]|确认|是否/i.test(haystack)) {
+        inputType = 'confirmation';
+    }
+    else if (/(?:\n|^)\s*(?:\d+[.、]|[-*])\s+\S/.test(haystack)) {
+        inputType = 'choice';
+    }
+    return {
+        inputType,
+        ...(Object.keys(metadata).length ? { metadata } : {})
+    };
+}

package/dist/acp/runtime.js

@@ -275,11 +275,16 @@ export class AcpProcessRuntime {
             kind: 'permission',
             prompt: params.toolCall.title ||
                 `Permission requested for tool ${params.toolCall.toolCallId}`,
+            inputType: 'confirmation',
+            step: params.toolCall.toolCallId
+                ? `tool:${params.toolCall.toolCallId}`
+                : undefined,
             options: params.options.map((option) => ({
                 id: option.optionId,
                 name: option.name,
                 kind: option.kind
-            }))
+            })),
+            metadata: permissionMetadata(params)
         };
         this.sink.setPending(request);
         return new Promise((resolve, reject) => {
@@ -314,7 +319,8 @@ export class AcpProcessRuntime {
             prompt: params.mode === 'url'
                 ? `${params.message}\n${params.url}`
                 : params.message,
-            options: elicitationOptions(params)
+            options: elicitationOptions(params),
+            ...elicitationClassification(params)
         };
         this.sink.setPending(request);
         return new Promise((resolve) => {
@@ -441,6 +447,11 @@ export class AcpProcessRuntime {
         }
     }
     captureStderr(child) {
+        // Explicit UTF-8 streaming decoder: `String(chunk)` on a Buffer uses the
+        // default binary encoding, which mangles multi-byte characters if a
+        // chunk boundary splits a rune. `TextDecoder` with `stream: true`
+        // preserves the split byte between calls.
+        const decoder = new TextDecoder('utf-8');
         let buffer = '';
         let flushed = false;
         const emit = (text) => {
@@ -471,10 +482,16 @@ export class AcpProcessRuntime {
             if (flushed)
                 return;
             flushed = true;
+            buffer += decoder.decode();
             drain(true);
         };
         child.stderr.on('data', (chunk) => {
-            buffer += String(chunk);
+            const bytes = chunk instanceof Uint8Array
+                ? chunk
+                : Buffer.isBuffer(chunk)
+                    ? chunk
+                    : Buffer.from(String(chunk));
+            buffer += decoder.decode(bytes, { stream: true });
             drain();
         });
         child.stderr.once('end', flush);
@@ -824,3 +841,88 @@ function isFormElicitation(params) {
             typeof params.requestedSchema ===
                 'object'));
 }
+/**
+ * Derive Agent Nexus semantic classification (inputType / step / metadata) from
+ * an ACP elicitation request. This is a best-effort projection: we look at the
+ * elicitation mode, the requested schema shape and well-known field names to
+ * decide whether the pending request is a plain text prompt, a choice, a
+ * yes/no confirmation, or a payment URL flow.
+ */
+function elicitationClassification(params) {
+    const metadata = {};
+    let inputType = 'unknown';
+    let step;
+    if (params.mode === 'url') {
+        const url = String(params.url || '').trim();
+        if (url) {
+            metadata.paymentUrl = url;
+            metadata.url = url;
+        }
+        inputType = /pay|支付|invoice|order/i.test(`${params.message || ''} ${url}`)
+            ? 'payment'
+            : 'text';
+        step = 'url';
+    }
+    else if (isFormElicitation(params)) {
+        const properties = params.requestedSchema.properties || {};
+        const entries = Object.entries(properties);
+        step = entries.length === 1 ? entries[0][0] : 'form';
+        if (entries.length === 1) {
+            const [, schema] = entries[0];
+            if (schema.type === 'boolean')
+                inputType = 'confirmation';
+            else if (Array.isArray(schema.oneOf) ||
+                Array.isArray(schema.enum)) {
+                inputType = 'choice';
+            }
+            else {
+                inputType = 'text';
+            }
+        }
+        else {
+            inputType = 'text';
+        }
+        const paymentUrl = firstStringFromSchema(properties, [
+            'paymentUrl',
+            'payUrl',
+            'payment_url',
+            'checkoutUrl'
+        ]);
+        if (paymentUrl) {
+            metadata.paymentUrl = paymentUrl;
+            inputType = 'payment';
+        }
+    }
+    else {
+        inputType = 'text';
+    }
+    return {
+        inputType,
+        ...(step ? { step } : {}),
+        ...(Object.keys(metadata).length ? { metadata } : {})
+    };
+}
+function permissionMetadata(params) {
+    const metadata = {};
+    const call = params.toolCall;
+    if (typeof call?.toolCallId === 'string' && call.toolCallId) {
+        metadata.toolCallId = call.toolCallId;
+    }
+    if (typeof call?.name === 'string' && call.name) {
+        metadata.tool = call.name;
+    }
+    return Object.keys(metadata).length ? metadata : undefined;
+}
+function firstStringFromSchema(properties, candidates) {
+    for (const key of candidates) {
+        const schema = properties[key];
+        if (!schema)
+            continue;
+        const value = (typeof schema.const === 'string' && schema.const) ||
+            (typeof schema.default === 'string' && schema.default) ||
+            '';
+        if (value)
+            return value;
+    }
+    return undefined;
+}

package/dist/auth.js

@@ -1,4 +1,4 @@
-import { randomBytes, scrypt as scryptCallback, timingSafeEqual } from 'node:crypto';
+import { createHash, randomBytes, scrypt as scryptCallback, timingSafeEqual } from 'node:crypto';
 import { promisify } from 'node:util';
 const scrypt = promisify(scryptCallback);
 const KEY_LENGTH = 64;
@@ -41,28 +41,46 @@ export function validateAdminPassword(input) {
 }
 export class AdminSessionStore {
     ttlMs;
+    // Stored keys are SHA-256 digests of the raw session id so a timing attack
+    // on Map lookup / string comparison cannot learn a valid prefix. The raw
+    // id never leaves the HttpOnly cookie.
     sessions = new Map();
     constructor(ttlMs) {
         this.ttlMs = ttlMs;
     }
     create() {
         this.cleanup();
-        const id = randomBytes(32).toString('base64url');
-        this.sessions.set(id, Date.now() + this.ttlMs);
-        return id;
+        const raw = randomBytes(32).toString('base64url');
+        this.sessions.set(digest(raw), Date.now() + this.ttlMs);
+        return raw;
     }
     has(id) {
-        const expiresAt = this.sessions.get(id);
-        if (!expiresAt)
+        if (typeof id !== 'string' || !id)
             return false;
+        const key = digest(id);
+        let match;
+        // Walk every stored digest in constant time. `timingSafeEqual` requires
+        // equal-length inputs, which is guaranteed because all digests have the
+        // same byte length.
+        for (const stored of this.sessions.keys()) {
+            const a = Buffer.from(stored, 'hex');
+            const b = Buffer.from(key, 'hex');
+            if (a.length === b.length && timingSafeEqual(a, b))
+                match = stored;
+        }
+        if (!match)
+            return false;
+        const expiresAt = this.sessions.get(match);
         if (expiresAt <= Date.now()) {
-            this.sessions.delete(id);
+            this.sessions.delete(match);
             return false;
         }
         return true;
     }
     delete(id) {
-        this.sessions.delete(id);
+        if (typeof id !== 'string' || !id)
+            return;
+        this.sessions.delete(digest(id));
     }
     clear() {
         this.sessions.clear();
@@ -75,3 +93,6 @@ export class AdminSessionStore {
         }
     }
 }
+function digest(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}

package/dist/server.js

@@ -3,7 +3,7 @@ import http from 'node:http';
 import { AdminSessionStore } from './auth.js';
 import { ControlPlaneError } from './control-plane.js';
 import { RunNotFoundError, SessionNotFoundError, SessionRequestError } from './session.js';
-import { redirectToAgentdWebUi, writeAgentdWebUi } from './webui/index.js';
+import { redirectToAgentdWebUi, writeAgentdWebUi, writeAgentdWebUiModule } from './webui/index.js';
 const ADMIN_COOKIE = 'agent_nexus_admin';
 export function createAgentdServer(config, sessions, controlPlane) {
     const adminSessions = new AdminSessionStore(config.adminSessionTtlMs || 12 * 60 * 60 * 1000);
@@ -72,6 +72,10 @@ async function handleRequest(context) {
         writeAgentdWebUi(response);
         return;
     }
+    if (url.pathname.startsWith('/ui/') && request.method === 'GET') {
+        writeAgentdWebUiModule(response, url.pathname);
+        return;
+    }
     if (url.pathname === '/health' && request.method === 'GET') {
         writeJson(response, 200, {
             ok: true,
@@ -220,8 +224,13 @@ async function handleRequest(context) {
         assertAgentScope(principal, session.agentId);
         assertJsonContentType(request);
         const body = await readJsonBody(request, config.maxRequestBytes);
-        assertOnlyKeys(body, ['path']);
-        writeJson(response, 201, await sessions.publishFile(sessionId, requiredString(body.path, 'path')));
+        assertOnlyKeys(body, ['path', 'paths']);
+        const paths = normalizePublishPaths(body);
+        const result = await sessions.publishFile(sessionId, paths);
+        writeJson(response, 201, {
+            ...result.session,
+            publishedArtifacts: result.artifacts
+        });
         return;
     }
     const match = url.pathname.match(/^\/v1\/sessions\/([^/]+)(?:\/(message|cancel|events))?$/);
@@ -456,11 +465,12 @@ function streamEvents(request, response, sessions, sessionId, after, release) {
     for (const event of sessions.eventsAfter(sessionId, after))
         writeEvent(response, event);
     const unsubscribe = sessions.subscribe(sessionId, (event) => writeEvent(response, event));
-    const heartbeat = setInterval(() => {
-        if (!response.destroyed && !response.writableEnded)
-            response.write(': heartbeat\n\n');
-    }, 15_000);
-    heartbeat.unref?.();
+    // Give idle SSE clients ~90 s to react before Node's default socket timeout
+    // trips. Combined with the writableEnded check inside the heartbeat this
+    // guarantees stuck keep-alive sessions eventually release their slot even
+    // if the peer never sends a FIN.
+    const idleMs = 90_000;
+    request.socket.setTimeout?.(idleMs);
     let closed = false;
     const close = () => {
         if (closed)
@@ -468,10 +478,37 @@ function streamEvents(request, response, sessions, sessionId, after, release) {
         closed = true;
         clearInterval(heartbeat);
         unsubscribe();
+        // Ensure both ends of the socket are actually torn down so the SSE
+        // slot returns to the pool even when the peer stops reading without
+        // closing the TCP connection cleanly.
+        try {
+            if (!response.writableEnded)
+                response.end();
+        }
+        catch { }
+        try {
+            request.socket.destroy();
+        }
+        catch { }
         release();
     };
+    const heartbeat = setInterval(() => {
+        if (response.destroyed || response.writableEnded) {
+            close();
+            return;
+        }
+        try {
+            response.write(': heartbeat\n\n');
+        }
+        catch {
+            close();
+        }
+    }, 15_000);
+    heartbeat.unref?.();
     request.once('close', close);
     response.once('close', close);
+    request.socket.once('timeout', close);
+    request.socket.once('error', close);
 }
 function writeEvent(response, event) {
     if (response.destroyed || response.writableEnded)
@@ -644,6 +681,19 @@ function optionalAttachmentIds(value) {
     }
     return value.map((item) => requiredString(item, 'attachments'));
 }
+function normalizePublishPaths(body) {
+    const bodyPaths = body.paths;
+    if (bodyPaths !== undefined) {
+        if (!Array.isArray(bodyPaths) || bodyPaths.length === 0) {
+            throw new RequestError(400, 'paths must be a non-empty array of strings');
+        }
+        if (bodyPaths.length > 32) {
+            throw new RequestError(400, 'paths accepts at most 32 entries');
+        }
+        return bodyPaths.map((item) => requiredString(item, 'paths'));
+    }
+    return [requiredString(body.path, 'path')];
+}
 function normalizedMediaType(value) {
     const mediaType = stringHeader(value).split(';', 1)[0].trim().toLowerCase();
     return mediaType || undefined;

package/dist/session.d.ts

@@ -37,6 +37,8 @@ export declare class ManagedSession implements AgentSessionSink, AcpSessionSink
     replaceOutput(text: string): void;
     addArtifact(artifact: AgentdArtifact): void;
     publishFile(filePath: string): Promise<AgentdArtifact>;
+    publishFiles(filePaths: string[]): Promise<AgentdArtifact[]>;
+    private publishSingleFile;
     setPending(request: AgentdPendingRequest): void;
     clearPending(): void;
     emit(type: AgentdEventType, data?: unknown): void;
@@ -58,6 +60,7 @@ export declare class SessionManager {
     private readonly runStore?;
     readonly instanceId: `${string}-${string}-${string}-${string}-${string}`;
     private sessions;
+    private sessionLocks;
     private cleanupTimer?;
     private readinessCache?;
     constructor(config: AgentdConfig, workspacePolicy: WorkspacePolicy, drivers: Map<string, AgentDriver>, runStore?: RunStore | undefined);
@@ -76,12 +79,16 @@ export declare class SessionManager {
     message(id: string, message: string, attachmentIds?: string[]): Promise<AgentdSessionView>;
     resolvePending(id: string, response: AgentdPendingResponse, attachmentIds?: string[]): Promise<AgentdSessionView>;
     addInputAttachment(id: string, name: string, mediaType: string | undefined, bytes: Buffer): AgentdInputAttachmentView;
-    publishFile(id: string, path: string): Promise<AgentdSessionView>;
+    publishFile(id: string, paths: string[]): Promise<{
+        session: AgentdSessionView;
+        artifacts: AgentdArtifact[];
+    }>;
     cancel(id: string): Promise<AgentdSessionView>;
     close(id: string): Promise<AgentdSessionView>;
     eventsAfter(id: string, after?: string): AgentdEvent[];
     subscribe(id: string, listener: (event: AgentdEvent) => void): () => boolean;
     shutdown(): Promise<void>;
+    private withSessionLock;
     private require;
     private ensureCapacity;
     private cleanup;