@xcanwin/manyoyo 8.6.6 → 8.6.7

package/lib/web/AGENTS.md

@@ -12,9 +12,13 @@
 - **`/agent/stream` 的 NDJSON 事件协议是跨前后端的契约**，改一处必须同步另一处：服务端 `lib/web/server.js`、前端 `frontend/src/lib/api.ts` 的 `StreamEvent` + `workspace-panel.tsx` 的事件分支
   - `content_chunk`：token 级增量，前端**追加**；`reset: true` 表示换了一条 assistant 消息、从空白重新开始。只发新增片段，不要改成重发累计全文（几千个增量就是 O(n²) 流量）。
   - `content_delta`：每条 assistant 消息落地时下发一次的权威全文，前端**整体覆盖**。
+  - `queue_next`（新增）：这一轮结束后服务端接着发排队的下一条，前端收到后结束这条流、改走恢复轮询（见下面“追加提示词”）。
   - `trace`：**不保证带结构化 `traceEvent`**。stderr 行（`emitStderrTraceLine`）和解析不出 JSON 的 stdout 行只有 `text` + `stream`，前端靠 `toTraceEvent()` 兜底成 `kind="output"` 的事件展示。新增只认 `traceEvent` 的分支等于把自定义 CLI、CLI 报错的输出全吞掉。
   - `ping`：保活心跳，前端忽略。`DEFAULT_AGENT_STREAM_HEARTBEAT_MS` 必须明显小于反向代理的空闲读超时（nginx `proxy_read_timeout` 默认 60s），否则 agent 静默期间流会被 RST，浏览器侧表现为输入框上方冒出 `network error`。
   - token 级增量**不写**事件日志、历史落盘按 `AGENT_STREAM_PARTIAL_PERSIST_INTERVAL_MS` 节流；新增逐事件的落盘/日志动作前先想清楚它会不会被每个 token 触发一次。
+- **追加提示词（排队）**：任务进行中用户可以追加提示词，队列存在 `agentSession.queue`（`lib/web/agent-queue.js`，最多 10 条，`when` 为 `now` / `step` / `turn`；`normalizeWebAgentSession` 的字段白名单里要有它，否则落盘后丢失）。接口 `POST /api/sessions/:name/agent/queue`（clientMessageId 幂等；容器被别的会话占着返回 409）、`DELETE .../agent/queue/:id`、`POST .../agent/queue/continue`；`/messages` 带 `queue`。一轮对话的完整流程抽成 `runWebAgentStreamTurn(..., res)`：前端不在线时传 `createHeadlessResponse()` 顶替 `res`，事件照常落盘。每一轮结束（完成 / 失败 / 被追加打断，**用户点停止除外**，由 `stopWebAgentRun` 置 `runState.userStopped`，并把 `agentSession.queuePaused` **落盘**——只记在内存里的话，serve 重启或用户下一次正常发送、那一轮结束后，停止前的排队会被自动发出去；暂停只有 `POST .../agent/queue/continue` 能解除，队列清空时自动解除，`/messages` 带 `queuePaused`）后若队列可以自动发（`agentQueue.shouldAutoDispatch`），先给连着的流发一个 `queue_next` 事件（前端据此结束这条流、改走恢复轮询），再 `setImmediate` 调 `dispatchNextQueued`（同步取出队首并占锁，开不起来就放回队首）。`now` 立即走进程树信号；`step` 在 `isStepBoundary`（一次工具 / 子 Agent / 说明完成）处打断，`agentStepFallbackMs`（默认 120 秒）等不到就退化成 `now`。serve 重启后 `startContainerServices` 末尾调 `resumeQueuedAgentTurns`，把留在队列里（暂停的除外）又没有任务在跑的内容当作 `turn` 发出；发之前用 `buildLiveRunsCommand`（只读，校验规则同停止脚本）看容器里还有没有活着的 Agent 进程，有就不发、排队留给用户——那可能是上一个 serve 的孤儿任务，也可能是同一 HOME 下另一个 serve 实例正在跑的任务，所以只检测不杀。
+- **停止 / 打断必须进到容器里发信号**（`lib/web/agent-run-control.js`）：只杀宿主机上的 `docker exec` 客户端，容器里的 Agent 进程会继续跑（实测）。命令被包成 `echo $$ > /tmp/manyoyo-run-<id>.pid; <命令>; exit $?`，**末尾的 `exit $?` 不能省**——命令是最后一条简单命令时 bash 会 exec 替换自己，`/proc/<pid>/cmdline` 里的 `manyoyo-run-<id>.pid` 标记就没了，停止时会因“认不出进程”而不杀（真实容器测出来的，单测里用 `sleep 61; true` 测不到）。PID 文件容器里可写，按不可信输入处理（纯数字、普通文件、命令行带标记才发信号），再按子孙进程树逐级 INT → TERM → KILL。真实的 claude 收到 SIGINT 会正常收尾、**退出码为 0**，所以 `interrupted` 看“发过信号”（`runState.signaled`）而不只是退出码。已验证 Claude 打断后 `-r <id>` 能接上上下文；Codex / Gemini / OpenCode 没有环境验证，拿不到引擎会话 id 时走既有的历史注入降级。
+- **子 Agent**：Claude 的 `Agent`（旧名 `Task`）工具生成 `kind: "subagent"` 事件，子 Agent 里的事件带 `parentToolId`（取自 `parent_tool_use_id`）；带 `parent_tool_use_id` 的 assistant 文本不当作主 Agent 的回复。`--forward-subagent-text` 只在 `claude --help` 里有该参数时才加（命令里就地探测，约 50ms，不缓存）。样本 fixture：`test/fixtures/claude-subagent.ndjson`。
 - **历史读写在 `lib/web/history-store.js`**：进程内缓存 + 原子写（`writeConfigFileSecure`，0600）+ 合并写盘。读靠 `stat` 的 `ino + mtimeMs + size` 判断缓存是否还有效（别的进程原子替换也能识别）；`loadWebSessionHistory` 返回的是**缓存里的同一个对象**，改了必须 `saveWebSessionHistory`，只读路由不要改它（`getWebAgentSession(..., { create: true })` 会在缓存里留一个未保存的空 agent，只在马上要写的路径里用）。流式过程中的 trace patch 和控制事件走 `{ defer: true }`（只改内存，最迟 `AGENT_STREAM_PARTIAL_PERSIST_INTERVAL_MS` 后落盘）；`process.exit` / serve 关闭会 flush；`result` / `error` 类事件（`WEB_STREAM_FLUSH_EVENT_TYPES`）和所有非 defer 写入立即写盘并带上攒着的内容。`kill -9` 最多丢约 1 秒的 trace。文件解析失败会留一份 `.corrupt-<时间>` 备份再按空历史处理，不要绕过它。磁盘格式只有 `agents.<id>.messages`（不再有顶层 `messages`，紧凑 JSON），老版本（含 `update --rollback`）读取时优先用 `agents`，能读新文件。
 - `GET /api/sessions` 以前是同步 IO 大户（逐容器读 + 解析整份历史），现在命中缓存基本是 0 次解析，但新增的同步操作仍要先实测；`buildSessionSummary()` 支持传入调用方加载好的 history，不要重复读。（`docker ps -a` + 批量 `inspect` 实测仅约 90ms，不是瓶颈）
 - **`/messages` 是分页 + 增量**（`lib/web/messages-view.js`）：`?limit=`（1～200，默认 60，起点往前对齐到 user 消息）/ `?after=<id>&epoch=<e>`（tail，锚点之后的消息；epoch 不符、锚点不存在或超过 120 条时返回最近一页并标 `mode: "reset"`）/ `?before=<id>`（更早一页）；`GET /messages/<id>/trace` 取完整执行过程。查询参数全部白名单校验，非法返回 400。**稳定前缀约定**：第一条 pending 消息之前的消息不再被修改——违反约定的写操作（删除非 pending 消息、克隆）必须给该 agent 换新的 `epoch`（`removeWebSessionMessage` 与 clone 已处理；新增修改历史消息的写操作要自己判断）。500 条上限从头裁掉**不换** epoch（tail 响应带 `firstId`，前端据此裁掉本地被丢弃的开头）。列表里的 trace 消息会被精简（长字符串截成 200 字符，带 `traceTruncated`），`/audit` 与 trace 接口输出完整内容。

package/lib/web/agent-queue.js

@@ -0,0 +1,150 @@
+'use strict';
+
+// 任务进行中追加的提示词队列：存在 agentSession.queue 里，随历史落盘。
+// 只放纯函数，调用方负责 saveWebSessionHistory。
+
+const crypto = require('crypto');
+
+const QUEUE_MAX = 10;
+const QUEUE_WHEN = ['now', 'step', 'turn'];
+const STEP_FALLBACK_MS = 120 * 1000;
+// 这些 kind 完成不代表“一步”结束（会话 / 回合 / 错误）
+const NON_STEP_KINDS = new Set(['thread', 'turn', 'error']);
+
+function normalizeWhen(value) {
+    return QUEUE_WHEN.includes(value) ? value : null;
+}
+
+function getQueue(agentSession) {
+    if (!agentSession) {
+        return [];
+    }
+    if (!Array.isArray(agentSession.queue)) {
+        agentSession.queue = [];
+    }
+    return agentSession.queue;
+}
+
+function publicQueue(agentSession) {
+    const queue = agentSession && Array.isArray(agentSession.queue) ? agentSession.queue : [];
+    return queue.map(item => ({
+        id: item.id,
+        clientMessageId: item.clientMessageId,
+        text: item.text,
+        when: item.when,
+        createdAt: item.createdAt
+    }));
+}
+
+// now / step 排在所有 turn 之前（它们之间保持先来先到）；turn 排到队尾
+function enqueue(agentSession, { clientMessageId, text, when }) {
+    const queue = getQueue(agentSession);
+    if (clientMessageId) {
+        const existing = queue.find(item => item.clientMessageId === clientMessageId);
+        if (existing) {
+            return { ok: true, duplicate: true, item: existing };
+        }
+    }
+    if (queue.length >= QUEUE_MAX) {
+        return { ok: false, full: true };
+    }
+    const item = {
+        id: `q-${crypto.randomBytes(6).toString('hex')}`,
+        clientMessageId: clientMessageId || '',
+        text,
+        when,
+        createdAt: new Date().toISOString()
+    };
+    if (when === 'turn') {
+        queue.push(item);
+    } else {
+        const firstTurn = queue.findIndex(entry => entry.when === 'turn');
+        queue.splice(firstTurn === -1 ? queue.length : firstTurn, 0, item);
+    }
+    return { ok: true, duplicate: false, item };
+}
+
+// 用户点停止时暂停：落盘在 agentSession.queuePaused，serve 重启、下一轮结束后都不自动发，
+// 只有“继续发送”才恢复。队列清空时暂停一并解除（之后新排的提示词照常自动发）
+function isPaused(agentSession) {
+    return Boolean(agentSession && agentSession.queuePaused === true && getQueue(agentSession).length);
+}
+
+function pauseQueue(agentSession) {
+    if (agentSession && getQueue(agentSession).length) agentSession.queuePaused = true;
+}
+
+function resumeQueue(agentSession) {
+    if (agentSession) agentSession.queuePaused = false;
+}
+
+function shouldAutoDispatch(agentSession) {
+    return getQueue(agentSession).length > 0 && !isPaused(agentSession);
+}
+
+function clearPauseIfEmpty(agentSession) {
+    if (agentSession && !getQueue(agentSession).length) agentSession.queuePaused = false;
+}
+
+function removeFromQueue(agentSession, id) {
+    const queue = getQueue(agentSession);
+    const index = queue.findIndex(item => item.id === id);
+    if (index === -1) {
+        return null;
+    }
+    const removed = queue.splice(index, 1)[0];
+    clearPauseIfEmpty(agentSession);
+    return removed;
+}
+
+function takeNext(agentSession) {
+    const queue = getQueue(agentSession);
+    const item = queue.length ? queue.shift() : null;
+    clearPauseIfEmpty(agentSession);
+    return item;
+}
+
+// 一次工具调用 / 子 Agent 结束，或一条 assistant 消息完整落地
+function isStepBoundary(event) {
+    const traceEvent = event && event.type === 'trace' ? event.traceEvent : null;
+    return Boolean(traceEvent)
+        && typeof traceEvent.kind === 'string'
+        && !NON_STEP_KINDS.has(traceEvent.kind)
+        && traceEvent.phase === 'completed';
+}
+
+// 从磁盘读回时的白名单：只留结构合法的条目
+function normalizeStoredQueue(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .filter(item => item && typeof item === 'object' && typeof item.id === 'string' && typeof item.text === 'string'
+            && item.text.trim() && QUEUE_WHEN.includes(item.when))
+        .slice(0, QUEUE_MAX)
+        .map(item => ({
+            id: item.id,
+            clientMessageId: typeof item.clientMessageId === 'string' ? item.clientMessageId : '',
+            text: item.text,
+            when: item.when,
+            createdAt: typeof item.createdAt === 'string' ? item.createdAt : new Date().toISOString()
+        }));
+}
+
+module.exports = {
+    normalizeStoredQueue,
+    QUEUE_MAX,
+    QUEUE_WHEN,
+    STEP_FALLBACK_MS,
+    normalizeWhen,
+    getQueue,
+    publicQueue,
+    enqueue,
+    removeFromQueue,
+    takeNext,
+    isStepBoundary,
+    isPaused,
+    pauseQueue,
+    resumeQueue,
+    shouldAutoDispatch
+};

package/lib/web/agent-run-control.js

@@ -0,0 +1,124 @@
+'use strict';
+
+// 停止 / 打断容器里的 Agent 进程。
+// 宿主机上的 `docker exec` 客户端被杀后，容器里的进程常常还活着（实测：kill 客户端后 `sleep 600` 仍在），
+// 所以要进到容器里，按进程组发信号：INT（让这一轮干净结束）→ TERM → KILL，最后才收宿主机上的客户端。
+//
+// 约定：命令前面加一句把自己的 PID 写进容器里的 /tmp/manyoyo-run-<id>.pid（wrapAgentCommand），再运行真正的命令；
+// 这条命令行本身就带着 `manyoyo-run-<id>.pid`，所以 /proc/<pid>/cmdline 就是“这个进程属于这次运行”的标记。
+// PID 文件在容器里、容器内进程可写，按不可信输入处理：内容必须是纯数字，并且该进程的环境里
+// 命令行里必须有本次运行的标记，才会发信号（见 RUN_KILL_SCRIPT）。
+
+const crypto = require('crypto');
+
+const RUN_ID_PATTERN = /^[A-Za-z0-9-]{8,64}$/;
+const KILL_SIGNALS = new Set(['INT', 'TERM', 'KILL']);
+const DEFAULT_GRACE_MS = 3000;
+
+function isValidRunId(value) {
+    return typeof value === 'string' && RUN_ID_PATTERN.test(value);
+}
+
+function createRunId() {
+    return crypto.randomUUID();
+}
+
+function pidFilePath(runId) {
+    return `/tmp/manyoyo-run-${runId}.pid`;
+}
+
+// 仍然是 `/bin/bash -lc <命令>` 的单个字符串参数（原命令原样保留，不套引号）。
+// 容器里的 exec 进程不是进程组长（实测 PGID/SID 都是 0），所以停的时候走子孙进程树，不依赖进程组
+function wrapAgentCommand(command, runId) {
+    if (!isValidRunId(runId)) throw new Error(`runId 非法: ${runId}`);
+    // 末尾的 `exit $?` 不能省：命令是最后一条简单命令时 bash 会 exec 替换自己，命令行里的标记随之消失，停止时就认不出这个进程
+    return `echo $$ > ${pidFilePath(runId)}; ${command}; exit $?`;
+}
+
+
+// 在容器里执行（参数：$1 = runId，$2 = 信号）。只认纯数字 PID、普通文件（不跟符号链接）、
+// 且进程命令行里带本次的 manyoyo-run-<id>.pid 标记；先发给整个进程组，失败再发给进程本身
+const RUN_KILL_SCRIPT = [
+    'f="/tmp/manyoyo-run-$1.pid"',
+    '[ -f "$f" ] && [ ! -L "$f" ] || exit 0',
+    'pid="$(head -c 16 "$f" 2>/dev/null | tr -d "\\n")"',
+    'case "$pid" in ""|*[!0-9]*) exit 3;; esac',
+    '[ "$pid" -gt 1 ] || exit 3',
+    'tr "\\0" " " < "/proc/$pid/cmdline" 2>/dev/null | grep -qF "manyoyo-run-$1.pid" || exit 4',
+    // 本进程和它的全部子孙（agent 派生的子进程）；先收集再发信号
+    'descendants() { for c in $(ps -eo pid=,ppid= | awk -v p="$1" \'$2 == p { print $1 }\'); do echo "$c"; descendants "$c"; done; }',
+    'all="$pid $(descendants "$pid")"',
+    'for p in $all; do kill -"$2" "$p" 2>/dev/null; done',
+    'exit 0'
+].join('\n');
+
+function buildRunKillCommand(runId, signal) {
+    if (!isValidRunId(runId)) throw new Error(`runId 非法: ${runId}`);
+    if (!KILL_SIGNALS.has(signal)) throw new Error(`信号不允许: ${signal}`);
+    return ['/bin/sh', '-c', RUN_KILL_SCRIPT, 'sh', runId, signal];
+}
+
+// 列出容器里还活着的运行 id（每行一个）。和 RUN_KILL_SCRIPT 同样的校验：文件名里的 id 合法、普通文件、
+// PID 是纯数字且大于 1、进程命令行里带这次运行的标记。只读，不发任何信号：
+// 同一个 HOME 可能有另一个 serve 实例在用这个容器，重启后的自动处理不能去杀别人的任务
+const LIVE_RUNS_SCRIPT = [
+    'for f in /tmp/manyoyo-run-*.pid; do',
+    '  [ -f "$f" ] && [ ! -L "$f" ] || continue',
+    '  id="${f#/tmp/manyoyo-run-}"; id="${id%.pid}"',
+    '  case "$id" in ""|*[!A-Za-z0-9-]*) continue;; esac',
+    '  pid="$(head -c 16 "$f" 2>/dev/null | tr -d "\\n")"',
+    '  case "$pid" in ""|*[!0-9]*) continue;; esac',
+    '  [ "$pid" -gt 1 ] || continue',
+    '  tr "\\0" " " < "/proc/$pid/cmdline" 2>/dev/null | grep -qF "manyoyo-run-$id.pid" || continue',
+    '  echo "$id"',
+    'done',
+    'exit 0'
+].join('\n');
+
+function buildLiveRunsCommand() {
+    return ['/bin/sh', '-c', LIVE_RUNS_SCRIPT];
+}
+
+/**
+ * INT → TERM → KILL 逐级升级，每级等 graceMs，进程退出就停；最后兜底收宿主机上的客户端。
+ * @param {{ runState: object, killInContainer: (runId: string, signal: string) => Promise<void>|void, sleep?: Function, graceMs?: number }} options
+ *   runState.closed 是 Promise（进程 close 时 resolve），runState.process 是宿主机上的客户端子进程
+ */
+async function terminateRun({ runState, killInContainer, graceMs = DEFAULT_GRACE_MS, signals = ['INT', 'TERM', 'KILL'] }) {
+    const exited = () => Promise.race([
+        runState.closed.then(() => true),
+        new Promise(resolve => {
+            const timer = setTimeout(() => resolve(false), graceMs);
+            if (typeof timer.unref === 'function') timer.unref();
+        })
+    ]);
+    if (isValidRunId(runState.runId)) {
+        for (const signal of signals) {
+            try {
+                await killInContainer(runState.runId, signal);
+            } catch (error) {
+                // 容器可能已经没了：继续往下收客户端
+            }
+            if (await exited()) return 'exited';
+        }
+    }
+    try {
+        if (runState.process) runState.process.kill('SIGKILL');
+    } catch (error) {
+        // 进程可能已退出
+    }
+    return 'client-killed';
+}
+
+module.exports = {
+    RUN_ID_PATTERN,
+    RUN_KILL_SCRIPT,
+    DEFAULT_GRACE_MS,
+    isValidRunId,
+    createRunId,
+    wrapAgentCommand,
+    buildRunKillCommand,
+    buildLiveRunsCommand,
+    pidFilePath,
+    terminateRun
+};