nexus-agentd 0.1.6 → 0.1.8

package/README.md

@@ -11,22 +11,23 @@ Agent，并向 Koishi AgentNexus 或其他客户端提供 HTTP/SSE API。管理
 
 ## 快速开始
 
-当前仓库代码建议按下面的源码部署流程启动；安装、首次初始化、systemd 和 Agent 准备的完整说明见下文。
+当前稳定版本已发布到 npm，推荐按下面的 npm 流程启动；如果要运行 GitHub 上尚未发布的分支代码，
+再使用下方的源码部署方式。首次初始化、systemd 和 Agent 准备的完整说明见下文。
 
 ```bash
-git clone https://github.com/lumia1998/nexus-gateway.git
-cd nexus-gateway
+NPM_CONFIG_PREFIX="$HOME/.local"
+npm install --global --prefix "$NPM_CONFIG_PREFIX" nexus-agentd@latest
+export PATH="$NPM_CONFIG_PREFIX/bin:$PATH"
 mkdir -p "$HOME/.config/agent-nexus" "$HOME/projects"
-npm ci
-npm run build
-node dist/cli.js \
-  --config "$HOME/.config/agent-nexus/nexus-agentd.json" \
-  --host 0.0.0.0 \
-  --port 8787 \
-  --workspace "$HOME/projects"
+nexus-agentd \
+ --config "$HOME/.config/agent-nexus/nexus-agentd.json" \
+ --host 0.0.0.0 \
+ --port 8787 \
+ --workspace "$HOME/projects"
 ```
 
-如果使用 npm 包，请先用 `npm view nexus-agentd version` 确认 registry 中的版本。当前仓库的 package.json 版本不代表该版本已经发布到 npm；未发布时不要把 `npm install nexus-agentd` 当成当前仓库的安装方式。
+当前仓库版本 `0.1.8` 已发布到 npm；可用 `npm view nexus-agentd version` 检查 registry 的 latest，
+也可以将安装命令固定为 `nexus-agentd@0.1.8`。
 
 ## 安装与部署
 
@@ -41,15 +42,15 @@ Gateway 不会替你安装 Agent，也不会替你执行 OpenCode、Claude Code
 
 ### npm 包安装（已发布版本）
 
-注意：只有当目标版本已经发布到 npm 时才使用此方式。否则请使用下面的源码部署，或将本仓库打包后的 tarball 安装到目标机器。
+`0.1.8` 已发布到 npm。目标版本尚未发布时，请使用下面的源码部署，或将本仓库打包后的 tarball 安装到目标机器。
 
-当前仓库的 package.json 版本可能高于 npm registry 的 latest；发布状态可用 `npm view nexus-agentd version` 检查。
+发布状态可用 `npm view nexus-agentd version` 检查；生产环境需要可复现部署时，建议固定为 `nexus-agentd@0.1.8`。
 
 生产环境建议使用专用的低权限系统用户，并把 npm 全局包安装到用户目录：
 
 ~~~bash
 NPM_CONFIG_PREFIX="$HOME/.local"
-npm install --global --prefix "$NPM_CONFIG_PREFIX" nexus-agentd
+npm install --global --prefix "$NPM_CONFIG_PREFIX" nexus-agentd@0.1.8
 export PATH="$NPM_CONFIG_PREFIX/bin:$PATH"
 ~~~
 
@@ -129,7 +130,7 @@ curl http://127.0.0.1:8787/health
 绝对路径加上 `dist/cli.js`，例如：`/usr/bin/node %h/nexus-gateway/dist/cli.js --config
 %h/.config/agent-nexus/nexus-agentd.json`。不要在 systemd 中依赖交互式 Shell 的 nvm 初始化。
 
-### 源码部署（当前仓库推荐）
+### 源码部署（开发分支或未发布版本）
 
 源码部署适合当前仓库和尚未发布到 npm 的版本；生产环境请使用外部进程管理器负责守护，
 不要把运行数据、Artifact 仓库或密钥放进 Git 工作树：
@@ -268,6 +269,17 @@ command -v hermes && hermes acp --check
 
 `workspace` 必须位于 `workspaceRoots` 之下；如果只通过 WebUI 配置，Gateway 会校验并保存这些字段。
 
+ACP Agent 的 `permissionPolicy` 有三种取值：`ask`（默认，每次权限请求交给用户确认）、`allow`（始终允许，
+自动选择 ACP 返回的允许项，不创建等待确认的请求）和 `deny`（始终拒绝，自动选择拒绝项）。`allow` 会放行该
+Agent 发起的所有 ACP 权限请求，请只对可信的 Agent 和工作区使用；没有明确的允许项时 Gateway 会安全地取消请求。
+该字段只适用于 ACP，A2A Agent 不使用本地 ACP 权限策略。
+
+Gateway 会在每个 Agent Session 的首次请求前自动注入一段 Agent Nexus 交互规范，提醒 Agent 在需要
+用户选择、确认、支付或补充信息时使用 ACP elicitation/A2A `input-required`，不要只输出普通文本问题。
+这段规范不需要为 OpenCode、Claude Code 或 Hermes 手工重复配置。若某个 Agent 还需要额外规则，可在 Agent
+配置中增加 `instructions`；它会在内置规范之后追加，并限制为最多 32768 个字符。提示词注入只是行为约定，
+Agent 仍必须实际支持相应的 ACP/A2A/MCP 用户输入机制，Gateway 不会把普通文本自动猜成等待状态。
+
 ### A2A
 
 A2A 使用官方 `@a2a-js/sdk` 客户端，通过完整的 Agent Card URL 发现名称、能力和实际调用地址，
@@ -279,6 +291,7 @@ A2A 使用官方 `@a2a-js/sdk` 客户端，通过完整的 Agent Card URL 发现
 {
   "protocol": "a2a",
   "name": "Research Agent",
+  "instructions": "需要用户确认时保持任务等待，并使用 Agent 的 input-required 能力。",
   "agentCardUrl": "http://192.168.1.20:8080/.well-known/agent-card.json",
   "preferredTransport": "auto",
   "auth": {
@@ -328,6 +341,34 @@ HTTP 上传总上限由 `maxAttachmentBytes` 控制，默认 32 MiB，允许调
 输出文件发布由 Gateway 自己的 `artifactStoragePath` 管理，默认单文件上限 512 MiB、链接有效期
 24 小时。上传和复制均使用流，不把文件编码进 JSON；公开 URL 使用 256 位随机 token，过期文件由
 后台清理。ACP/A2A 返回的内联二进制 Artifact 也会先落入该仓库，再在 Session 响应中改为 URL。
+客户端应使用 Artifact 的 `mediaType` 选择展示方式，而不是把所有产物都当作普通文件：音频使用原生
+音频元素、视频使用原生视频元素，其他内容使用文件元素。`koishi-plugin-agent-nexus` 会分别调用
+Koishi 的 `h.audio`、`h.video`、`h.image` 和 `h.file`；URL 只作为底层传输地址，大文件不会在客户端
+重新编码成 Base64。
+
+### 多轮输入与确认
+
+ACP elicitation、ACP permission request 和 A2A `input_required` 都会让 Session 进入等待状态，并在
+Session 响应的 `pendingRequest` 中返回等待提示和可选项。客户端只需重复调用同一个
+`POST /v1/sessions/:id/message`：
+
+~~~text
+POST /v1/sessions/:id/message
+{"message":"第一个"}
+~~~
+
+Gateway 会复用原来的协议 Session/Task/Context，不会创建新任务。Agent 可以在下一轮再次进入
+`input_required`，因此套餐选择、堂食方式、取餐时间和支付完成可以组成一条连续流程。需要表达业务
+授权时，客户端可以发送可选项的数字序号、ID 或名称；Gateway 也会将常见的 `同意`、`允许`、`可以`、
+`确认`、`yes` 和 `allow` 映射到安全的允许项。无法识别的授权答案会返回 400，并保留等待状态，便于
+客户端根据 `pendingRequest.options` 重新提示用户。
+步骤时，可在 `pendingRequest` 中提供可选的 `step`、`inputType` 和 JSON-safe `metadata`；这些字段
+不应放入密钥或其他敏感信息。支付完成消息仍必须由上游 MCP 根据订单/支付状态核验，不能只信任用户文本。
+
+对 ACP Agent，Gateway 会在 Session 首次 prompt 前注入内置交互规范；对 A2A Agent，则把同一规范放在首个
+用户消息的前缀中。由于 A2A/ACP 的 system-message 能力在不同 Agent 实现中并不统一，这是一种兼容性更好的
+宿主提示方式。它不能替代 Agent 对 elicitation 或 `input-required` 的实现：Agent 必须真正发起协议级等待，
+Gateway 才能暂停 Session 并在用户回复后继续。
 
 API Key 与 A2A 认证值支持 `env:VAR`。Console Password 哈希由 WebUI 管理，不要手工生成或把
 旧 `authToken` 复制到该字段。

package/dist/a2a/runtime.d.ts

@@ -10,6 +10,8 @@ export declare class A2AClientRuntime implements AgentSessionRuntime {
     private taskId;
     private contextId;
     private prompting;
+    private firstPrompt;
+    private readonly instructions;
     private disposed;
     private activeController?;
     private readonly artifactCache;

package/dist/a2a/runtime.js

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { Role, TaskState } from '@a2a-js/sdk';
 import { ClientFactory, DefaultAgentCardResolver, JsonRpcTransportFactory, RestTransportFactory } from '@a2a-js/sdk/client';
+import { buildAgentInstructions, composeInitialAgentPrompt } from '../agent-instructions.js';
 export async function probeA2AAgent(id, config) {
     const startedAt = Date.now();
     if (config.enabled === false)
@@ -43,6 +44,8 @@ export class A2AClientRuntime {
     taskId = '';
     contextId = '';
     prompting = false;
+    firstPrompt = true;
+    instructions;
     disposed = false;
     activeController;
     artifactCache = new Map();
@@ -51,6 +54,7 @@ export class A2AClientRuntime {
         this.config = config;
         this.sink = sink;
         this.promptTimeoutMs = promptTimeoutMs;
+        this.instructions = buildAgentInstructions(config.instructions);
     }
     async start() {
         const resolver = createResolver(this.config);
@@ -78,12 +82,16 @@ export class A2AClientRuntime {
         this.prompting = true;
         this.sink.clearPending();
         this.sink.setState('running');
+        const promptMessage = this.firstPrompt
+            ? composeInitialAgentPrompt(this.instructions, message)
+            : message;
+        this.firstPrompt = false;
         const controller = new AbortController();
         this.activeController = controller;
         const timer = setTimeout(() => controller.abort(new Error('A2A message timed out')), Math.min(this.promptTimeoutMs, this.config.timeoutMs || this.promptTimeoutMs));
         timer.unref?.();
         try {
-            const request = this.messageRequest(message, attachments);
+            const request = this.messageRequest(promptMessage, attachments);
             for await (const response of this.client.sendMessageStream(request, {
                 signal: controller.signal
             })) {

package/dist/acp/runtime.d.ts

@@ -1,6 +1,9 @@
 import type { AgentDriver } from '../drivers/index.js';
 import type { AcpSessionSink } from '../session-contract.js';
 import type { AgentdInputAttachment } from '../types.js';
+export declare class InvalidPermissionAnswerError extends Error {
+    constructor(message: string);
+}
 export declare class AcpProcessRuntime {
     private readonly driver;
     private readonly sink;
@@ -12,9 +15,11 @@ export declare class AcpProcessRuntime {
     private prompting;
     private readonly maxStderrChunkChars;
     private readonly promptTimeoutMs;
+    private readonly instructions;
+    private firstPrompt;
     private promptCapabilities;
     private inputDirectory?;
-    constructor(driver: AgentDriver, sink: AcpSessionSink, maxStderrChunkChars?: number, promptTimeoutMs?: number);
+    constructor(driver: AgentDriver, sink: AcpSessionSink, maxStderrChunkChars?: number, promptTimeoutMs?: number, customInstructions?: string);
     start(workspace: string): Promise<void>;
     prompt(message: string, attachments?: AgentdInputAttachment[]): Promise<void>;
     respondPending(message: string, _attachments?: AgentdInputAttachment[]): Promise<void>;

package/dist/acp/runtime.js

@@ -4,6 +4,13 @@ import path from 'node:path';
 import { Readable, Writable } from 'node:stream';
 import { pathToFileURL } from 'node:url';
 import * as acp from '@agentclientprotocol/sdk';
+import { buildAgentInstructions, composeInitialAgentPrompt } from '../agent-instructions.js';
+export class InvalidPermissionAnswerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidPermissionAnswerError';
+    }
+}
 export class AcpProcessRuntime {
     driver;
     sink;
@@ -15,9 +22,11 @@ export class AcpProcessRuntime {
     prompting = false;
     maxStderrChunkChars;
     promptTimeoutMs;
+    instructions;
+    firstPrompt = true;
     promptCapabilities = {};
     inputDirectory;
-    constructor(driver, sink, maxStderrChunkChars = 16 * 1024, promptTimeoutMs = 30 * 60 * 1000) {
+    constructor(driver, sink, maxStderrChunkChars = 16 * 1024, promptTimeoutMs = 30 * 60 * 1000, customInstructions) {
         this.driver = driver;
         this.sink = sink;
         const limit = Number.isFinite(maxStderrChunkChars)
@@ -25,6 +34,7 @@ export class AcpProcessRuntime {
             : 16 * 1024;
         this.maxStderrChunkChars = Math.max(1, Math.min(16 * 1024, limit));
         this.promptTimeoutMs = Math.max(10_000, Math.trunc(promptTimeoutMs));
+        this.instructions = buildAgentInstructions(customInstructions);
     }
     async start(workspace) {
         if (this.process)
@@ -86,10 +96,14 @@ export class AcpProcessRuntime {
         this.prompting = true;
         this.sink.clearPending();
         this.sink.setState('running');
+        const promptMessage = this.firstPrompt
+            ? composeInitialAgentPrompt(this.instructions, message)
+            : message;
+        this.firstPrompt = false;
         try {
             const response = await withTimeout(this.connection.agent.request(acp.methods.agent.session.prompt, {
                 sessionId,
-                prompt: await this.promptBlocks(message, attachments)
+                prompt: await this.promptBlocks(promptMessage, attachments)
             }), this.promptTimeoutMs, 'ACP prompt timed out');
             if (this.sink.state === 'canceled' || this.sink.state === 'failed') {
                 return;
@@ -133,9 +147,9 @@ export class AcpProcessRuntime {
         const option = Number.isInteger(numeric) && numeric >= 1
             ? options[numeric - 1]
             : options.find((item) => item.id.toLowerCase() === normalized ||
-                item.name.toLowerCase() === normalized);
+                item.name.toLowerCase() === normalized) || permissionApprovalOption(normalized, options);
         if (!option) {
-            throw new Error(`Permission answer must be an option id/name or index: ${options
+            throw new InvalidPermissionAnswerError(`Permission answer must be an option id/name or index: ${options
                 .map((item, index) => `${index + 1}. ${item.name} (${item.id})`)
                 .join('; ')}`);
         }
@@ -207,6 +221,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' } };
         }
@@ -451,6 +477,39 @@ export class AcpProcessRuntime {
         };
     }
 }
+function permissionApprovalOption(answer, options) {
+    const approvals = new Set([
+        'yes',
+        'y',
+        'ok',
+        'okay',
+        'approve',
+        'approved',
+        'accept',
+        'allow',
+        'proceed',
+        '同意',
+        '允许',
+        '允许一次',
+        '确认',
+        '好的',
+        '可以',
+        '继续',
+        '是',
+        '是的'
+    ]);
+    if (!approvals.has(answer))
+        return undefined;
+    return (options.find((item) => item.kind?.toLowerCase() === 'allow_once') ||
+        options.find((item) => isApprovalOption(item)));
+}
+function isApprovalOption(option) {
+    const kind = option.kind?.toLowerCase() || '';
+    if (kind.startsWith('allow'))
+        return true;
+    const values = [option.id, option.name].map((value) => value.trim().toLowerCase());
+    return values.some((value) => ['allow', 'approve', 'accept', 'permit', '允许', '同意'].some((word) => value === word || value.startsWith(`${word} `) || value.startsWith(`${word}_`)));
+}
 class PromptTimeoutError extends Error {
 }
 function safeFilename(value) {

package/dist/agent-instructions.d.ts

@@ -0,0 +1,11 @@
+export declare const MAX_AGENT_INSTRUCTIONS_CHARS: number;
+/**
+ * Baseline guidance for Agents running behind Agent Nexus.
+ *
+ * This is delivered as the first prompt because ACP and A2A do not expose a
+ * portable system-message field across all supported Agent implementations.
+ */
+export declare const DEFAULT_AGENT_INSTRUCTIONS: string;
+export declare function normalizeAgentInstructions(value: unknown, field?: string): string | undefined;
+export declare function buildAgentInstructions(custom?: string): string;
+export declare function composeInitialAgentPrompt(instructions: string, userMessage: string): string;

package/dist/agent-instructions.js

@@ -0,0 +1,44 @@
+export const MAX_AGENT_INSTRUCTIONS_CHARS = 32 * 1024;
+/**
+ * Baseline guidance for Agents running behind Agent Nexus.
+ *
+ * This is delivered as the first prompt because ACP and A2A do not expose a
+ * portable system-message field across all supported Agent implementations.
+ */
+export const DEFAULT_AGENT_INSTRUCTIONS = [
+    'You are running behind the Agent Nexus conversational host.',
+    'When an external tool or operation needs the user to choose, confirm, authorize, pay, or provide more information before it can continue:',
+    '1. Do not present the task as completed.',
+    '2. Use the host\'s native user-input, elicitation, or permission request mechanism when available; do not only print a normal-text question and stop.',
+    '3. Include a concise prompt and structured options when the mechanism supports them. For payment, include the payment URL and stable order metadata.',
+    '4. After the user replies, validate the result with the upstream tool. Never treat a message such as "payment completed" as proof that payment succeeded.',
+    'Only finish the task after the external operation has actually completed.'
+].join('\n');
+export function normalizeAgentInstructions(value, field = 'instructions') {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new Error(`${field} must be a string`);
+    const text = value.trim();
+    if (text.length > MAX_AGENT_INSTRUCTIONS_CHARS) {
+        throw new Error(`${field} must be at most ${MAX_AGENT_INSTRUCTIONS_CHARS} characters`);
+    }
+    return text || undefined;
+}
+export function buildAgentInstructions(custom) {
+    const extra = normalizeAgentInstructions(custom);
+    return extra
+        ? `${DEFAULT_AGENT_INSTRUCTIONS}\n\nAdditional agent-specific instructions:\n${extra}`
+        : DEFAULT_AGENT_INSTRUCTIONS;
+}
+export function composeInitialAgentPrompt(instructions, userMessage) {
+    return [
+        '<agent-nexus-host-instructions>',
+        instructions,
+        '</agent-nexus-host-instructions>',
+        '',
+        '<user-request>',
+        userMessage,
+        '</user-request>'
+    ].join('\n');
+}

package/dist/config.js

@@ -1,5 +1,6 @@
 import { mkdir, open, readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { normalizeAgentInstructions } from './agent-instructions.js';
 import { agentdDriverKinds } from './types.js';
 export async function ensureAgentdConfig(filePath, options = {}) {
     const absolute = path.resolve(filePath);
@@ -140,7 +141,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 = {
@@ -148,6 +151,7 @@ function parseAgent(id, value) {
         driver,
         name: optionalString(input.name, `agents.${id}.name`),
         description: optionalString(input.description, `agents.${id}.description`),
+        instructions: normalizeAgentInstructions(input.instructions, `agents.${id}.instructions`),
         enabled: optionalBoolean(input.enabled, `agents.${id}.enabled`) ?? true,
         workspace: optionalString(input.workspace, `agents.${id}.workspace`),
         command: optionalString(input.command, `agents.${id}.command`),
@@ -203,6 +207,7 @@ function parseA2AAgent(id, input) {
         protocol: 'a2a',
         name: optionalString(input.name, `agents.${id}.name`),
         description: optionalString(input.description, `agents.${id}.description`),
+        instructions: normalizeAgentInstructions(input.instructions, `agents.${id}.instructions`),
         enabled: optionalBoolean(input.enabled, `agents.${id}.enabled`) ?? true,
         agentCardUrl,
         agentUrl,

package/dist/control-plane.d.ts

@@ -5,6 +5,7 @@ export interface AgentdAgentUpdate {
     driver?: AgentdDriverKind;
     name?: string;
     description?: string;
+    instructions?: string;
     enabled?: boolean;
     workspace?: string;
     permissionPolicy?: PermissionPolicy;

package/dist/control-plane.js

@@ -2,6 +2,7 @@ import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { chmod, open, readFile, rename, rm } from 'node:fs/promises';
 import path from 'node:path';
 import { hashAdminPassword, validateAdminPassword, verifyAdminPassword } from './auth.js';
+import { normalizeAgentInstructions } from './agent-instructions.js';
 import { loadAgentdConfig } from './config.js';
 import { createDriverRegistry } from './drivers/index.js';
 import { agentdDriverKinds } from './types.js';
@@ -311,6 +312,7 @@ export class AgentdControlPlane {
                 next.name = cleanString(update.name) || cleanString(previous.name);
             }
         }
+        setOptionalInstructions(next, update.instructions ?? cleanString(previous.instructions));
         setOptionalString(next, 'description', update.description ?? cleanString(previous.description));
         agents[id] = next;
         raw.agents = agents;
@@ -448,6 +450,7 @@ export class AgentdControlPlane {
                 protocol: 'a2a',
                 name: config.name || id,
                 description: config.description,
+                instructions: config.instructions,
                 enabled: config.enabled !== false,
                 agentCardUrl: config.agentCardUrl || defaultAgentCardUrl(config.agentUrl),
                 agentUrl: config.agentUrl,
@@ -466,6 +469,7 @@ export class AgentdControlPlane {
             driver: config.driver,
             name: config.name || id,
             description: config.description,
+            instructions: config.instructions,
             enabled: config.enabled !== false,
             workspace: config.workspace || this.config.workspaceRoots[0] || '',
             permissionPolicy: config.permissionPolicy || 'ask',
@@ -501,8 +505,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)) {
@@ -607,6 +612,19 @@ function setOptionalString(target, key, value) {
     else
         delete target[key];
 }
+function setOptionalInstructions(target, value) {
+    let text;
+    try {
+        text = normalizeAgentInstructions(value);
+    }
+    catch (error) {
+        throw new ControlPlaneError(400, errorMessage(error));
+    }
+    if (text)
+        target.instructions = text;
+    else
+        delete target.instructions;
+}
 function validHeaderName(value) {
     return /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(value);
 }

package/dist/server.js

@@ -441,6 +441,7 @@ function readAgentUpdate(body) {
         'driver',
         'name',
         'description',
+        'instructions',
         'enabled',
         'workspace',
         'permissionPolicy',
@@ -458,6 +459,7 @@ function readAgentUpdate(body) {
         driver: optionalString(body.driver),
         name: optionalString(body.name),
         description: optionalString(body.description),
+        instructions: optionalString(body.instructions),
         enabled: optionalBoolean(body.enabled, 'enabled'),
         workspace: optionalString(body.workspace),
         permissionPolicy: optionalString(body.permissionPolicy),

package/dist/session.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { AcpProcessRuntime } from './acp/runtime.js';
+import { AcpProcessRuntime, InvalidPermissionAnswerError } from './acp/runtime.js';
 import { A2AClientRuntime, probeA2AAgent } from './a2a/runtime.js';
 import { SessionEventLog } from './events.js';
 const MAX_SESSION_ARTIFACTS = 64;
@@ -170,7 +170,15 @@ export class ManagedSession {
             this.syncRun({
                 progress: { phase: '继续执行', message: '已提交补充信息' }
             });
-            await this.runtime.respondPending(message, attachments);
+            try {
+                await this.runtime.respondPending(message, attachments);
+            }
+            catch (error) {
+                if (error instanceof InvalidPermissionAnswerError) {
+                    throw new SessionRequestError(400, error.message);
+                }
+                throw error;
+            }
             return;
         }
         if (this.state === 'running') {
@@ -374,7 +382,7 @@ export class SessionManager {
         const session = new ManagedSession(agentId, config.protocol === 'a2a' ? 'a2a' : 'acp', workspace, ownerKeyId, this.config.maxEventsPerSession, this.config.maxOutputChars, config.name || agentId, this.runStore);
         const runtime = config.protocol === 'a2a'
             ? new A2AClientRuntime(config, session, this.config.promptTimeoutMs || 30 * 60_000)
-            : new AcpProcessRuntime(driver, session, this.config.maxOutputChars, this.config.promptTimeoutMs || 30 * 60_000);
+            : new AcpProcessRuntime(driver, session, this.config.maxOutputChars, this.config.promptTimeoutMs || 30 * 60_000, config.instructions);
         this.sessions.set(session.id, session);
         session.attach(runtime);
         try {

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 declare const agentdDriverKinds: readonly ["opencode", "claude", "codex", "pi", "openclaw", "hermes"];
 export type AgentdDriverKind = (typeof agentdDriverKinds)[number];
 export interface AgentdDriverConfig {
@@ -14,6 +14,8 @@ export interface AgentdDriverConfig {
     args?: string[];
     inheritEnv?: string[];
     env?: Record<string, string>;
+    /** Optional extra instructions appended to the built-in Agent Nexus guidance. */
+    instructions?: string;
     permissionPolicy?: PermissionPolicy;
     permissionTimeoutMs?: number;
 }
@@ -23,6 +25,8 @@ export interface AgentdA2AConfig {
     protocol: 'a2a';
     name?: string;
     description?: string;
+    /** Optional extra instructions sent with the first A2A user message. */
+    instructions?: string;
     enabled?: boolean;
     /** Full Agent Card JSON URL. Preferred for new configurations. */
     agentCardUrl?: string;
@@ -128,6 +132,7 @@ export interface AgentdAgentConfigView {
     protocol: AgentdProtocol;
     name: string;
     description?: string;
+    instructions?: string;
     enabled: boolean;
     driver?: AgentdDriverKind;
     workspace?: string;
@@ -181,11 +186,17 @@ export interface AgentdPendingRequest {
     id: string;
     kind: 'permission' | 'input';
     prompt: string;
+    /** Optional business-facing step, for example `payment` or `pickup_time`. */
+    step?: string;
+    /** Optional hint for clients rendering the pending interaction. */
+    inputType?: 'text' | 'choice' | 'confirmation' | 'payment' | 'unknown';
     options?: Array<{
         id: string;
         name: string;
         kind?: string;
     }>;
+    /** JSON-safe metadata for the owning integration. Never put secrets here. */
+    metadata?: Record<string, unknown>;
 }
 export interface AgentdArtifact {
     id?: string;

package/dist/webui/app.js

@@ -456,6 +456,7 @@ export const app = String.raw `
 
   function permissionLabel(value) {
     if (value === 'ask') return '询问'
+    if (value === 'allow') return '始终允许'
     if (value === 'deny') return '拒绝'
     return value || '—'
   }
@@ -672,7 +673,8 @@ 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>' +
+      '<label>Agent 交互指令<textarea name="instructions" rows="8" placeholder="可选：补充这个 Agent 的专属规则。Gateway 会自动注入多轮确认和用户输入规范。">' + escapeHtml(current.instructions || '') + '</textarea><small class="field-help">可选补充规则，最多 32768 个字符；不要填写密钥等敏感信息。</small></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="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)
@@ -682,6 +684,7 @@ export const app = String.raw `
         protocol,
         name: String(data.get('name') || '').trim(),
         description: String(data.get('description') || '').trim(),
+        instructions: String(data.get('instructions') || '').trim(),
         enabled: data.get('enabled') === 'on'
       }
       if (protocol === 'acp') {

package/nexus-agentd.example.json

@@ -28,6 +28,7 @@
       "protocol": "acp",
       "driver": "codex",
       "name": "Codex",
+      "instructions": "如果外部工具需要用户选择、确认或支付，请使用宿主的用户输入机制并保持任务等待；不要只输出普通文本问题。",
       "command": "codex-acp",
       "workspace": "/data/repos/project",
       "permissionPolicy": "ask"

package/package.json

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