nexus-agentd 0.2.6 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/lumia1998/nexus-gateway/actions/workflows/ci.yml/badge.svg)](https://github.com/lumia1998/nexus-gateway/actions/workflows/ci.yml)
 
-`nexus-agentd` 是 Agent Nexus 的本地 Gateway。它在一台机器上统一管理 ACP 进程和远程 A2A
+`nexus-agentd` 是面向通用客户端的 Agent Nexus Gateway。它在一台机器上统一管理 ACP 进程和远程 A2A
 Agent，并向 Koishi AgentNexus 或其他客户端提供 HTTP/SSE API。管理控制台使用 **Agent Nexus**
 品牌，不依赖 CDN、前端框架或父仓库。
 
@@ -13,11 +13,11 @@ npm install -g nexus-agentd
 nexus-agentd
 ```
 
-首次启动会创建 `./nexus-agentd.json`，默认监听 `127.0.0.1:8787`。打开打印出的 WebUI 地址，
-设置至少 12 位的 Console Password，然后登录。新安装不会自动创建 API Key；在控制台的
+首次启动会创建 `./nexus-agentd.json`，默认监听 `0.0.0.0:8787`。打开打印出的 WebUI 地址，
+输入启动终端中的 **Setup token**，设置至少 12 位的 Console Password，然后登录。新安装不会自动创建 API Key；在控制台的
 **API Keys** 页面按实际客户端需要创建。
 
-局域网使用时显式监听所有网卡：
+局域网使用（所有网卡已是默认值，也可显式指定）：
 
 ```bash
 mkdir -p /data/repos
@@ -47,6 +47,10 @@ nexus-agentd --config /etc/agent-nexus/nexus-agentd.json
 被当成 Console Password。升级后第一次打开 WebUI 会要求单独设置管理员密码，原有 Agent 和
 Workspace 配置保持不变。
 
+首次安装和旧配置补设控制台密码均需要 Setup token。令牌仅存在当前进程中，初始化成功即失效，
+未初始化时每次启动重新生成；不会写入 URL、配置文件或匿名接口。嵌入使用时从
+`startAgentd(...).controlPlane.setupToken` 获取它。不要向不可信人员开放服务启动日志。
+
 ## WebUI
 
 侧栏按“运行”和“网关配置”分组，提供总览、运行记录、智能体、工作区、API 密钥五个页面；底部提供独立的“设置”和“退出登录”入口。
@@ -55,15 +59,18 @@ Workspace 配置保持不变。
 - 总览显示智能体、就绪和当前内存会话数量，并列出需要注意的智能体。
 - 运行记录把当前任务和历史任务分开显示，记录用户原始任务、真实运行阶段、状态、结果摘要、
   耗时和产物；每 5 秒自动刷新，也可查看完整详情。
-  顶部统计涵盖全部保留记录；列表载入最近 200 条，搜索和筛选作用于已载入的记录。
+  搜索、筛选和统计作用于全部保留记录（默认最多 1000 条），默认每页 50 条，可翻页。列表只返回最多 240 字符的任务预览，详情按需读取全文。详情随列表轮询更新，
+  断线会明确标注旧数据；历史产物仅保留元数据，等待输入/授权请回到创建任务的客户端处理。
   轮询保留搜索框、输入法组合态与筛选控件，表格详情和菜单支持键盘操作。
-- Agents 支持本地 ACP 与远程 A2A；readiness 每 20 秒自动刷新，也可手动刷新。
+- Agents 支持本地 ACP 与远程 A2A；总览/智能体页在前台时每 20 秒刷新 readiness，也可手动刷新。
+  ACP 的“命令可用”只表示命令探测通过，不代表 ACP 握手成功；A2A 的“Card 可用”也不保证任务执行成功。
 - Workspaces 管理 ACP 的 realpath allowlist；A2A 不使用本地 Workspace。
 - API Keys 显示真实状态和最后使用时间，并提供独立的显式 reveal 操作。
-- 设置中的运行参数可以直接修改会话空闲有效期、ACP 单次任务超时和清理任务周期，保存后立即热生效。
-  运行参数与控制台密码共用右上角“保存更改”，修改智能体权限策略后列表会立即刷新。
+- 登录成功即显示控制台；配置、密钥、历史和 Agent 探测独立加载。探测失败保留应用和编辑入口，并显示重试与上次成功时间。
+- 设置中的运行参数与控制台密码独立保存，保留毫秒精度；只改密码不会写运行参数。
+  会话空闲有效期和清理周期热生效，任务期限及智能体参数影响新建会话，已有会话保留创建时参数。
   默认值分别是 24 小时、30 分钟和 60 秒；A2A 请求超时在每个 Agent 的编辑页单独设置，默认 60 秒、
-  最大 30 分钟。
+  最大 30 分钟。A2A 另有任务总期限和流无进度期限，见下文。
 
 ## Agent 协议
 
@@ -84,6 +91,7 @@ Workspace 配置保持不变。
 
 | Driver | 默认入口 |
 |---|---|
+| `stdio` | 本地配置文件中的显式 `command`、`args` |
 | `opencode` | `opencode acp` |
 | `claude` | `claude-agent-acp` |
 | `codex` | `codex-acp` |
@@ -100,11 +108,15 @@ npm install -g \
   pi-acp
 ```
 
-`command`、`args`、`inheritEnv` 和 `env` 是仅可在本机配置文件修改的高级字段，WebUI 不接受这些
+`command`、`args`、`probeArgs`、`inheritEnv` 和 `env` 是仅可在本机配置文件修改的高级字段，WebUI 不接受这些
 字段。Workspace 在启动进程前经过 `realpath` 边界校验。
 
-ACP 权限策略支持 `ask`（询问）、`allow`（始终允许）和 `deny`（拒绝）。`allow` 会优先选择
-Agent 提供的 `allow_once`，不创建待确认请求；它适合管理员明确授权、工作区边界可信的自动化 Agent。
+通用 `stdio` 驱动用于自定义 ACP 入口，必须指定 `command`；用 `probeArgs` 指定命令可用性检查参数（例如 `["--version"]`）。编辑其他字段时保留这些本地配置。命令探测不等于 ACP 握手成功。
+
+ACP 权限策略支持 `ask`（询问）、`allow`（自动允许单次）和 `deny`（拒绝）。`allow` 只选择
+Agent 提供的 `allow_once`，缺少该选项则取消授权，不再回退到永久授权。`ask` 模式下普通
+`action: "accept"` 也只选择单次授权；永久授权需要客户端明确传入对应 `optionId`。
+这不限制重复的单次自动授权，但只提供永久选项的 Agent 需要改用 `ask` 并显式处理。
 默认仍为 `ask`。
 
 ### A2A
@@ -135,6 +147,25 @@ Agent Card 和它声明的全部接口 URL 必须使用 HTTP(S)，不含用户
 旧配置中的 `agentUrl` 仍按“服务根地址 + `/.well-known/agent-card.json`”方式发现 Card，无需手工
 迁移；在 WebUI 中保存一次后会写入新的 `agentCardUrl` 字段。
 
+A2A 超时分为三种，均为整数毫秒：
+
+| 字段 | 作用 | 默认 / 范围 |
+|---|---|---|
+| `timeoutMs` | Card、普通请求全程及流建连 | 60 秒；1 秒至 30 分钟 |
+| `taskTimeoutMs` | 单轮任务总期限 | 继承全局 `promptTimeoutMs`；10 秒至 24 小时 |
+| `streamIdleTimeoutMs` | 流持续没有进度时的等待期限 | 继承 `timeoutMs`；1 秒至 30 分钟 |
+
+旧配置的 `timeoutMs` 继续限制请求，并作为未配置流失联期限时的默认值；不再隐式缩短任务总期限。长任务持续输出时可超过请求超时。通过管理 API 更新时，省略可选字段保留原值，传 `null` 清除覆盖并恢复继承。
+
+控制面更新的影响如下（直接编辑本地文件后需重启，或由下一次控制面保存重新载入）：
+
+| 配置 | 已有会话 / 新会话 |
+|---|---|
+| Key 启用、scope、轮换与删除 | 新请求立即校验，受影响旧 SSE 立即关闭；任务继续 |
+| 会话 TTL、清理周期 | 当前清理任务使用新值 |
+| Agent 参数、权限策略、任务期限、Workspace | 新会话使用新值；已有会话和 ACP 文件来源根保留创建时值 |
+| 监听地址、端口、来源、Cookie/HTTP 连接设置 | 重启生效 |
+
 ## 配置
 
 推荐从首次启动生成的待初始化配置开始。完整示例见
@@ -228,8 +259,21 @@ POST /v1/sessions/:id/requests/:requestId/resolve
 POST /v1/sessions/:id/artifacts/publish
 POST /v1/sessions/:id/cancel
 GET  /v1/sessions/:id/events
+GET  /v1/runs/:runId/artifacts/:artifactId
 ```
 
+控制台运行详情支持取消、补充输入、显式选择权限和重试。管理员 Cookie 可以跨 Key 执行这些操作；数据面仍检查原 Key 归属及 Agent scope。对应接口为 `POST /v1/admin/runs/:id/cancel`、`POST /v1/admin/runs/:id/respond` 和 `POST /v1/admin/runs/:id/retry`。取消和重试发送 `{}`；回复发送当前 `requestId` 与 `message`、`optionId` 或 `action`。过期请求及非当前轮次不能修改后续任务。
+
+“重置/重试”以原任务创建新 Session，保留旧记录和原 Key 归属，并记录 `retryOfRunId`。运行中、任务文本被截断或带输入附件的历史不能直接重试；这些情况需要调用方重新提交完整任务及附件。新任务使用当前 Agent 配置。
+
+重复的重试请求在进程内复用已创建的任务：成功去重记录最多保留 512 条、24 小时，目标历史已被淘汰时失效。该机制防止重复点击，不提供跨网关重启的持久幂等保证；重启或保留窗口结束后，再次重试可能创建新任务。
+
+产物有可用内容时持久化到运行历史文件旁的 `.artifacts` 目录；仅有远端 URL 的产物保留元数据，不主动下载。详情中的 `downloadable` 和 `storageStatus` 表示下载状态；管理员使用 `GET /v1/admin/runs/:runId/artifacts/:artifactId`，数据面使用上表接口。下载需要身份验证，不能将链接作为公开分享地址。
+
+本地配置的 `quotas` 设置每 Key 的 Session、运行任务、SSE 和上传字节限制；默认分别为 16、4、8、32 MiB，连接数量默认也受全局上限约束。`history` 默认保留 1000 条、30 天、64 MiB；`artifacts` 默认保留 30 天、总量 512 MiB、单项 12 MiB、排队内容 64 MiB。活动任务受保护，因此历史预算不是强制截断活动记录的硬上限。完整字段见 `nexus-agentd.example.json`。
+
+`GET /v1/admin/metrics` 提供管理指标；`POST /v1/admin/agents/:id/diagnostics` 以空 JSON 对象发起显式连接诊断，不提交任务提示词。通用 ACP 命令、参数和环境变量仍在本地配置中管理，控制台提供接入说明与诊断入口。
+
 `/v1/meta` 和 Session 响应包含 Gateway `instanceId`；完成的 Session 还包含与当前 Run 绑定的
 `completion` 证明，客户端可识别进程重启和迟到/伪造的完成状态。授权与输入通过精确的
 `requestId` 解析；过期 ID 返回 `409`，不会误答后续请求。`DELETE /v1/sessions/:id` 会取消活动任务、
@@ -245,17 +289,60 @@ API Key 的 Agent scope 在 Agent inventory、Session 创建和后续 Session
 还绑定创建它的 Key，其他 Key 即使拥有同一 Agent scope 也不能读取或控制该 Session。
 运行记录接口仅接受管理员 Cookie，数据面 API Key 无权读取。
 
+Key 停用、删除、轮换及 scope 缩小时，受影响的现有 SSE 会断开；已经接受的任务继续执行，断开输出不等于取消任务。轮换保留 Key ID，新密钥可在原 scope 内继续原 Session；停用后可重新启用恢复访问。删除后不能用其他 Key 接管原 Session，任务结果仍可在管理员历史中查看，等待输入的任务受原有超时及清理规则约束。
+
+### SSE 断线恢复
+
+使用 `Last-Event-ID` 请求头或 `?after=` 恢复，客户端按事件 ID 去重。游标非法、超前或已被淘汰时，网关发送独立的 `event: reset` 控制帧，包含 `reason`（`invalid` / `ahead` / `expired`）、`earliestId`、`latestId` 与 `snapshotUrl`。空日志的最早 ID 为 `null`，最新 ID 为 `"0"`。
+
+收到 reset 后，读取同一 Session 的快照、替换当前展示，再使用快照的 `lastEventId` 重连。快照只恢复当前状态，不能补回已淘汰的完整事件历史。首次连接没有游标且历史已淘汰时也会 reset；网关重启导致原 Session 返回 404，需要新建会话。
+
+[`examples/client.mjs`](./examples/client.mjs) 提供带 Bearer 鉴权、去重、指数退避、心跳期限及缺口恢复的 Node 20+ 客户端：
+
+```js
+import { createGatewayClient } from './examples/client.mjs'
+const client = createGatewayClient('http://127.0.0.1:8787', process.env.NEXUS_API_KEY)
+const session = await client.createSession('codex')
+await client.message(session.id, '检查当前项目')
+for await (const event of client.events(session.id)) {
+  if (event.type === 'reset') console.log('替换当前状态：', event.data)
+  else console.log(event)
+  if (['completed', 'failed', 'canceled'].includes(event.type) ||
+      event.type === 'reset' && ['completed', 'failed', 'canceled'].includes(event.data.state)) break
+}
+// 收到 pendingRequest 后，由用户明确选择对应 optionId 或输入：
+// await client.resolve(session.id, pendingRequest.id, { optionId: '实际的一次授权选项ID' })
+// await client.resolve(session.id, pendingRequest.id, { message: '用户的回复' })
+// await client.cancel(session.id) // 取消任务；AbortSignal 只停止客户端监听
+// await client.close(session.id)  // 释放 Session
+```
+
+示例遇到 401 / 403 / 404 会停止重连并向调用方抛错，需要更新凭据、权限或会话。不要把自动重连误当成任务重试。
+
 ## 局域网安全
 
-- 默认仍只监听 localhost；需要 LAN 时显式使用 `--host 0.0.0.0`，并用主机防火墙限制来源。
+- 默认监听 `0.0.0.0`；已有配置的监听值不会被覆盖。用主机防火墙限制来源。
 - LAN 上的纯 HTTP 为兼容 Cookie 默认不设置 `Secure`；跨不可信网络应放在 HTTPS/mTLS 反向代理
   或可信隧道后，并将 `secureAdminCookies` 设为 `true`。
-- 管理写操作要求同源 `Origin`，Cookie 使用 `SameSite=Strict`；登录和无效 API Key 有失败限速。
+- 控制台和初始化接口校验 Host，默认允许 localhost、回环地址、请求到达的本机 IP 和配置的具体监听主机。
+  自定义域名 / TLS 反代在配置中增加 `"publicOrigins": ["https://gateway.example.com"]`，修改后重启。
+  配置值必须是准确的协议、主机、端口组合，不带路径或尾斜杠；反代保留该 Host 与 Origin。
+  不信任客户端提供的 X-Forwarded-*。数据面不强制浏览器 Origin，保留通用 Bearer 客户端兼容性。
+- 管理写操作要求完整同源 `Origin`，Cookie 使用 `SameSite=Strict`；登录、初始化失败、无效 API Key 有限速。
+  reveal 每来源每分钟最多 20 次并记录不含密钥的审计事件。停用、删除和轮换后的旧 Key 不再回退到启动配置。
+- 并发 Session 创建在异步初始化前预占容量；readiness 按 Key scope 先过滤，每 Agent 合并探测，
+  手动刷新最短间隔 5 秒，普通缓存 20 秒，最多 4 个探测同时进行。
+- 每条 SSE 连接的待发送缓冲最多 512 KiB，背压超过 5 秒断开并释放槽位；客户端应携带 Last-Event-ID
+  重连；游标缺口按上述 reset 协议恢复。控制面持久化 Key 变更后立即关闭失去授权的旧流。
+- `workspaceRoots` 限制网关处理的 cwd / 文件来源，Agent 的 workspace 是默认值，客户端仍可选择任何允许根内路径。
+  这不是 OS 沙箱，也不是不互信租户隔离；ACP 子进程拥有服务账号的系统权限。
 - 不直接暴露公网。使用专用低权限系统账号运行 Gateway。
 - 配置更新使用 `0600` 临时文件校验后原子替换；Secret 不进入普通响应和结构化错误日志。
 
 ## 验证
 
+生产部署与升级使用统一的 SSH Key / systemd 流程，见[部署手册](./deploy-manual.md)。配置和历史存放在独立状态目录，升级失败会恢复旧版本。项目内的开发运行数据可放在已忽略的 `data/` 或 `runtime/` 中。
+
 ```bash
 npm test
 npm run typecheck
@@ -263,6 +350,8 @@ npm run build
 npx playwright install chromium
 npm run test:webui
 npm pack --dry-run --json
+node scripts/package-deploy.mjs
+node scripts/package-smoke.mjs nexus-gateway.tar.gz
 ```
 
 ## License

package/dist/a2a/runtime.d.ts

@@ -19,9 +19,12 @@ export declare class A2AClientRuntime implements AgentSessionRuntime {
     private sawTaskStatus;
     private sawAgentMessage;
     private completionProof?;
+    private readonly taskTimeoutMs;
+    private readonly streamIdleTimeoutMs;
+    private taskDeadlineAt?;
     constructor(config: AgentdA2AConfig, sink: AgentSessionSink, promptTimeoutMs: number);
     start(): Promise<void>;
-    prompt(message: string, attachments?: AgentdInputAttachment[]): Promise<void>;
+    prompt(message: string, attachments?: AgentdInputAttachment[], continuation?: boolean): Promise<void>;
     respondPending(response: AgentdPendingResponse | string, attachments?: AgentdInputAttachment[]): Promise<void>;
     cancel(): Promise<void>;
     dispose(): Promise<void>;

package/dist/a2a/runtime.js

@@ -53,10 +53,19 @@ export class A2AClientRuntime {
     sawTaskStatus = false;
     sawAgentMessage = false;
     completionProof;
+    taskTimeoutMs;
+    streamIdleTimeoutMs;
+    taskDeadlineAt;
     constructor(config, sink, promptTimeoutMs) {
         this.config = config;
         this.sink = sink;
         this.promptTimeoutMs = promptTimeoutMs;
+        // Keep inheritance at runtime so changing the gateway-wide prompt
+        // timeout continues to affect agents that did not opt into a local
+        // task deadline. The per-request timeout is deliberately excluded
+        // from this calculation: it only bounds connection/headers.
+        this.taskTimeoutMs = positiveTimeout(config.taskTimeoutMs ?? promptTimeoutMs, promptTimeoutMs);
+        this.streamIdleTimeoutMs = positiveTimeout(config.streamIdleTimeoutMs ?? config.timeoutMs, config.timeoutMs || 60_000);
     }
     async start() {
         if (this.disposed)
@@ -78,7 +87,7 @@ export class A2AClientRuntime {
             throw new Error('A2A runtime is disposed');
         this.sink.setState('created');
     }
-    async prompt(message, attachments = []) {
+    async prompt(message, attachments = [], continuation = false) {
         if (!this.client || !this.card)
             throw new Error('A2A runtime is not connected');
         if (this.prompting)
@@ -93,9 +102,14 @@ export class A2AClientRuntime {
         this.completionProof = undefined;
         this.sink.clearPending();
         this.sink.setState('running');
+        const taskDeadlineAt = continuation && this.taskDeadlineAt !== undefined
+            ? this.taskDeadlineAt
+            : Date.now() + this.taskTimeoutMs;
+        this.taskDeadlineAt = taskDeadlineAt;
         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));
+        const remainingTaskMs = Math.max(1, taskDeadlineAt - Date.now());
+        const timer = setTimeout(() => controller.abort(new A2ATaskTimeoutError(this.taskTimeoutMs)), remainingTaskMs);
         timer.unref?.();
         try {
             const request = this.messageRequest(message, attachments);
@@ -137,6 +151,9 @@ export class A2AClientRuntime {
             if (this.activeController === controller)
                 this.activeController = undefined;
             this.prompting = false;
+            if (this.sink.state !== 'input_required' && !this.queuedResponse) {
+                this.taskDeadlineAt = undefined;
+            }
             finish();
             this.promptFinished = undefined;
         }
@@ -162,15 +179,19 @@ export class A2AClientRuntime {
         this.sink.setState('running');
         void previous.then(async () => {
             this.queuedResponse = false;
-            if (this.disposed || this.sink.state === 'canceled')
+            if (this.disposed ||
+                this.sink.state === 'canceled' ||
+                this.sink.state === 'failed' ||
+                (this.taskDeadlineAt !== undefined && this.taskDeadlineAt <= Date.now()))
                 return;
-            await this.prompt(message, attachments);
+            await this.prompt(message, attachments, true);
         }).catch((error) => {
             if (!this.disposed && this.sink.state !== 'canceled')
                 this.sink.setState('failed', errorMessage(error));
         });
     }
     async cancel() {
+        this.taskDeadlineAt = undefined;
         this.sink.clearPending();
         this.sink.setState('canceled');
         this.activeController?.abort(new Error('A2A session canceled'));
@@ -190,6 +211,7 @@ export class A2AClientRuntime {
     }
     async dispose() {
         this.disposed = true;
+        this.taskDeadlineAt = undefined;
         this.activeController?.abort(new Error('A2A runtime disposed'));
         this.activeController = undefined;
     }
@@ -432,13 +454,194 @@ function authenticatedFetch(config) {
             config.auth.value) {
             headers.set(config.auth.headerName, config.auth.value);
         }
-        return fetch(input, {
-            ...init,
-            headers,
-            redirect: 'error',
-            signal: init.signal || AbortSignal.timeout(config.timeoutMs || 60_000)
-        });
+        const timeoutMs = config.timeoutMs || 60_000;
+        const timeoutController = new AbortController();
+        const signals = [timeoutController.signal];
+        if (init.signal)
+            signals.push(init.signal);
+        const signal = AbortSignal.any(signals);
+        const requestTimeout = new A2ARequestTimeoutError(timeoutMs);
+        let bodyAbort;
+        const timer = setTimeout(() => {
+            timeoutController.abort(requestTimeout);
+            bodyAbort?.();
+        }, timeoutMs);
+        timer.unref?.();
+        try {
+            const response = await fetch(input, {
+                ...init,
+                headers,
+                redirect: 'error',
+                signal
+            });
+            // Only an SSE response is an intentionally long-lived request.
+            // Card and ordinary JSON calls retain timeoutMs through the body;
+            // otherwise a slow/trickling Card could evade the request bound.
+            if (isEventStream(response)) {
+                clearTimeout(timer);
+                return withStreamIdleTimeout(response, config.streamIdleTimeoutMs || timeoutMs);
+            }
+            if (!response.body) {
+                clearTimeout(timer);
+                return response;
+            }
+            const deadline = responseDeadlineBody(response.body, requestTimeout, () => clearTimeout(timer));
+            bodyAbort = deadline.abort;
+            return new Response(deadline.stream, {
+                status: response.status,
+                statusText: response.statusText,
+                headers: response.headers
+            });
+        }
+        catch (error) {
+            clearTimeout(timer);
+            if (timeoutController.signal.aborted && !init.signal?.aborted) {
+                throw requestTimeout;
+            }
+            throw error;
+        }
+    };
+}
+class A2ARequestTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`A2A request timed out after ${timeoutMs}ms`);
+        this.name = 'A2ARequestTimeoutError';
+    }
+}
+class A2ATaskTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`A2A task timed out after ${timeoutMs}ms`);
+        this.name = 'A2ATaskTimeoutError';
+    }
+}
+class A2AStreamIdleTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`A2A stream made no progress for ${timeoutMs}ms`);
+        this.name = 'A2AStreamIdleTimeoutError';
+    }
+}
+function withStreamIdleTimeout(response, timeoutMs) {
+    if (!response.body || !Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return response;
+    const body = idleTimeoutBody(response.body, timeoutMs);
+    return new Response(body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers
+    });
+}
+function isEventStream(response) {
+    return response.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase() ===
+        'text/event-stream';
+}
+function responseDeadlineBody(body, timeoutError, cleanup) {
+    const reader = body.getReader();
+    let controllerRef;
+    let closed = false;
+    let timedOut = false;
+    const abort = () => {
+        if (closed || timedOut)
+            return;
+        timedOut = true;
+        void reader.cancel(timeoutError).catch(() => undefined);
+        controllerRef?.error(timeoutError);
+    };
+    const stream = new ReadableStream({
+        start(controller) {
+            controllerRef = controller;
+        },
+        async pull(controller) {
+            if (closed || timedOut)
+                return;
+            try {
+                const result = await reader.read();
+                if (timedOut)
+                    return;
+                if (result.done) {
+                    closed = true;
+                    cleanup();
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(result.value);
+            }
+            catch (error) {
+                if (timedOut)
+                    return;
+                closed = true;
+                cleanup();
+                controller.error(error);
+            }
+        },
+        async cancel(reason) {
+            closed = true;
+            cleanup();
+            await reader.cancel(reason);
+        }
+    });
+    return { stream, abort };
+}
+function idleTimeoutBody(body, timeoutMs) {
+    const reader = body.getReader();
+    let controllerRef;
+    let timer;
+    let closed = false;
+    let timedOut = false;
+    const clearIdleTimer = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = undefined;
     };
+    const armIdleTimer = () => {
+        clearIdleTimer();
+        timer = setTimeout(() => {
+            if (closed || timedOut)
+                return;
+            timedOut = true;
+            const error = new A2AStreamIdleTimeoutError(timeoutMs);
+            void reader.cancel(error).catch(() => undefined);
+            controllerRef?.error(error);
+        }, timeoutMs);
+        timer.unref?.();
+    };
+    return new ReadableStream({
+        start(controller) {
+            controllerRef = controller;
+            armIdleTimer();
+        },
+        async pull(controller) {
+            if (closed || timedOut)
+                return;
+            try {
+                const result = await reader.read();
+                if (timedOut)
+                    return;
+                if (result.done) {
+                    closed = true;
+                    clearIdleTimer();
+                    controller.close();
+                    return;
+                }
+                armIdleTimer();
+                controller.enqueue(result.value);
+            }
+            catch (error) {
+                if (timedOut)
+                    return;
+                closed = true;
+                clearIdleTimer();
+                controller.error(error);
+            }
+        },
+        async cancel(reason) {
+            closed = true;
+            clearIdleTimer();
+            await reader.cancel(reason);
+        }
+    });
+}
+function positiveTimeout(value, fallback) {
+    return Number.isFinite(value) && value > 0 ? Math.trunc(value) : fallback;
 }
 function artifactFromA2A(artifact) {
     const text = textParts(artifact.parts).join('') || undefined;

package/dist/acp/runtime.js

@@ -186,11 +186,19 @@ export class AcpProcessRuntime {
             this.finishPermission({ outcome: { outcome: 'cancelled' } });
             return;
         }
-        if (response.action === 'accept') {
-            const option = options.find((item) => item.kind?.startsWith('allow')) ||
-                options.find((item) => !(item.kind?.startsWith('reject') ?? false));
+        // Protocol IDs are opaque: never interpret a numeric ID as an index or
+        // fold its case into a different (possibly permanent) permission.
+        if (response.optionId !== undefined) {
+            const option = options.find((item) => item.id === response.optionId);
+            if (!option)
+                throw new Error('Permission optionId does not match an offered option');
+            this.finishPermission({ outcome: { outcome: 'selected', optionId: option.id } });
+            return;
+        }
+        if (response.action === 'accept' && !response.optionId) {
+            const option = options.find((item) => item.kind === 'allow_once');
             if (!option) {
-                throw new Error('Permission request does not provide an allow option');
+                throw new Error('Permission request requires an explicit optionId; no allow_once option is available');
             }
             this.finishPermission({
                 outcome: { outcome: 'selected', optionId: option.id }
@@ -298,8 +306,7 @@ 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'));
+            const allow = params.options.find((option) => option.kind.toLowerCase() === 'allow_once');
             return allow
                 ? {
                     outcome: {