agentus 0.12.2 → 0.13.0

package/bin/cli.mjs

@@ -4,7 +4,7 @@
  * cross-session `send`. Dispatched by `bin/agentus.mjs`, which is also what the cockpit hands agents
  * as `AGENTUS_COCKPIT_BIN`, so there is exactly one command and one spelling everywhere.
  *
- * SHAPE: noun, then verb — `agentus session list|show|messages|plan|send`
+ * SHAPE: noun, then verb — `agentus session list|show|messages|plan|send|wake|create|stop`
  * The five things an agent needs are all about ONE object (a session), so the noun is not decoration:
  * it keeps `list` from meaning "list what?" and leaves the top level free for the two commands that
  * are NOT about a session — `capabilities` (this CLI's contract) and `skill` (its manual). The
@@ -54,10 +54,16 @@ another one
   agentus session messages <id> [--tail N]
                                       the last N messages, each cut to the documented size
   agentus session plan <id>           the plan object the operator's card renders
-  agentus session send <id> <text…> [--wake]
+  agentus session send <id> <text…> [--wake] [--interrupt] [--reply-on-done]
                                        deliver a message into another session (stdin if no text);
-                                       --wake also starts the target when it is cold
+                                       --wake also starts the target when it is cold;
+                                       --interrupt cancels the turn it is running first (explicit)
   agentus session wake <id>            start a cold session's process (same switch as send)
+  agentus session create <cwd> [--backend <id>] [--title <text>]
+                                       open a NEW session in that directory and answer with its row
+                                       (same switch as send — it costs one agent process)
+  agentus session stop <id> [--close]  interrupt the turn it is running; --close stops the PROCESS
+                                       (the slot goes cold, the transcript stays)
 
   agentus capabilities                the contract: commands, fields, truncation, scope, send state
   agentus skill [--path]              this CLI's manual, as shipped in the package
@@ -295,7 +301,15 @@ if (cmd === "capabilities") {
     // The text is the plain words after the id — an agent writing a sentence should not have to
     // build JSON to say it. With no words, stdin is accepted: either a JSON `{"message": "…"}` (what
     // older callers sent) or the raw text.
-    let message = args.slice(1).filter((a) => a !== "--wake").join(" ").trim();
+    const wantWake = args.includes("--wake");
+    const wantInterrupt = args.includes("--interrupt");
+    // #59：`--reply-on-done` 不是"抢话头"，是"别让我在这儿等它跑完" —— 调用立即返回，目标回合
+    // 自然结束时服务端往本会话投一条【完成回推】。派活给一个要跑十分钟的会话时才用得上。
+    const wantReply = args.includes("--reply-on-done");
+    const FLAGS = new Set(["--wake", "--interrupt", "--reply-on-done"]);
+    const straySend = args.slice(1).filter((a) => a.startsWith("--") && !FLAGS.has(a));
+    if (straySend.length) fail("bad_request", `unknown flag ${straySend[0]} (usage: agentus session send <id> <text…> [--wake] [--interrupt] [--reply-on-done])`);
+    let message = args.slice(1).filter((a) => !FLAGS.has(a)).join(" ").trim();
     if (!message) {
       const raw = await readStdin();
       if (raw) {
@@ -313,7 +327,7 @@ if (cmd === "capabilities") {
       res = await fetch(`${EP}/api/cockpit/send`, {
         method: "POST",
         headers: headers(true),
-        body: JSON.stringify({ to: id, message, ...(args.includes("--wake") ? { wake: true } : {}) }),
+        body: JSON.stringify({ to: id, message, ...(wantWake ? { wake: true } : {}), ...(wantInterrupt ? { interrupt: true } : {}), ...(wantReply ? { replyOnDone: true } : {}) }),
       });
     } catch (e) {
       fail("unreachable", `the cockpit did not answer: ${e?.message ?? e}`);
@@ -333,9 +347,17 @@ if (cmd === "capabilities") {
       data: body,
       meta: {
         schema_version: 1,
-        note: body?.delivered_after_wake
-          ? "the target was COLD: this call woke it (a process now exists) and then delivered. delivered means it received the message and started a turn — not that it read or agreed."
-          : "delivered means the target agent received it and started a turn — it does NOT mean it read or agreed. Only the operator sees the reply.",
+        note: [
+          body?.delivered_after_wake
+            ? "the target was COLD: this call woke it (a process now exists) and then delivered."
+            : null,
+          body?.interrupted
+            ? "the target was BUSY: its turn was interrupted (cancelled, then the session was waited to really stop) before yours started — the words it had already produced stay in its transcript."
+            : null,
+          body?.reply_on_done
+            ? "reply-on-done: this call returned as soon as the target's turn STARTED. When that turn ends, the cockpit posts a 【完成回推】 notice into this session and wakes you; read the actual result with `session messages <target>`."
+            : "delivered means the target agent received it and started a turn — it does NOT mean it read or agreed. Only the operator sees the reply.",
+        ].filter(Boolean).join(" "),
       },
     });
   } else if (verb === "wake") {
@@ -364,6 +386,84 @@ if (cmd === "capabilities") {
           : "the target was already live: nothing was started.",
       },
     });
+  } else if (verb === "create") {
+    // The FIRST positional is the directory, not an id: this is the one verb that makes an object
+    // instead of acting on one. `~` is expanded HERE as well as server-side so the error a caller
+    // reads names the path it actually meant.
+    // Walk argv once, skipping each flag's VALUE — otherwise `create --backend hermes /tmp/x`
+    // reads "hermes" as the directory and then rejects the real path as an extra argument.
+    const VALUE_FLAGS = new Set(["--backend", "--title", "--profile", "--model"]);
+    let cwdArg;
+    for (let i = 0; i < args.length; i++) {
+      const a = args[i];
+      if (a.startsWith("--")) { if (VALUE_FLAGS.has(a)) i++; continue; }
+      cwdArg = a;
+      break;
+    }
+    if (!cwdArg) fail("bad_request", "usage: agentus session create <cwd> [--backend <id>] [--title <text>]");
+    const flags = { backend: undefined, title: undefined };
+    for (let i = 0; i < args.length; i++) {
+      const a = args[i];
+      if (a === cwdArg) continue;
+      if (a === "--backend" || a === "--title") {
+        const v = args[++i];
+        if (v === undefined) fail("bad_request", `${a} needs a value`);
+        flags[a.slice(2)] = v;
+      } else fail("bad_request", `unexpected argument "${a}" (usage: agentus session create <cwd> [--backend <id>] [--title <text>])`);
+    }
+    let res;
+    try {
+      res = await fetch(`${EP}/api/cockpit/create`, {
+        method: "POST",
+        headers: headers(true),
+        body: JSON.stringify({ cwd: cwdArg, ...flags }),
+      });
+    } catch (e) {
+      fail("unreachable", `the cockpit did not answer: ${e?.message ?? e}`);
+    }
+    const body = await res.json().catch(() => null);
+    if (!res.ok) {
+      // An unknown backend is only actionable if the caller is told WHICH ones exist — the same reason
+      // `target_cold` names `--wake` instead of being a bare prohibition.
+      fail(String(body?.error ?? `http_${res.status}`),
+        String(body?.message ?? body?.error ?? `the cockpit answered HTTP ${res.status}`),
+        Array.isArray(body?.backends) ? { details: { backends: body.backends } } : {});
+    }
+    out({
+      success: true,
+      data: body,
+      meta: {
+        schema_version: 1,
+        note: "the session exists and is starting. Read its id from data.session and send into it at once; a slot with no process yet answers cold_target unless you pass --wake.",
+      },
+    });
+  } else if (verb === "stop") {
+    if (!id) fail("bad_request", "usage: agentus session stop <id> [--close]");
+    const close = args.includes("--close");
+    const leftovers = args.slice(1).filter((a) => a !== "--close");
+    if (leftovers.length) fail("bad_request", `unexpected argument "${leftovers[0]}" (usage: agentus session stop <id> [--close])`);
+    let res;
+    try {
+      res = await fetch(`${EP}/api/cockpit/stop`, {
+        method: "POST",
+        headers: headers(true),
+        body: JSON.stringify(close ? { id, close: true } : { id }),
+      });
+    } catch (e) {
+      fail("unreachable", `the cockpit did not answer: ${e?.message ?? e}`);
+    }
+    const body = await res.json().catch(() => null);
+    if (!res.ok) fail(String(body?.error ?? `http_${res.status}`), String(body?.message ?? body?.error ?? `the cockpit answered HTTP ${res.status}`));
+    out({
+      success: true,
+      data: body,
+      meta: {
+        schema_version: 1,
+        note: close
+          ? (body?.closed ? "its agent process is stopped and the slot is cold; the transcript is untouched." : "nothing was running: the slot was already cold.")
+          : (body?.stopped ? "the turn was cancelled; the words it had already produced stay in the transcript." : "no turn was running — nothing was interrupted."),
+      },
+    });
   } else {
     process.stderr.write(USAGE);
     fail("bad_request", `unknown session command: ${verb ?? "(none)"}`);

package/docs/dev/04-recover.md

@@ -99,9 +99,11 @@ cp -p packages/server/.data/agentus.sqlite \
 ```
 
 The one migration path in the project that rewrites rows in place — the legacy transcript
-fold — takes its own backup first with `VACUUM INTO <db>.pre-fold.bak` and gates itself on
-`pragma user_version`, so it runs once and is idempotent. If you see a `*.pre-fold.bak`
-beside the store, that fold ran; the original is inside it.
+fold — takes its own backup first with `VACUUM INTO <db>.pre-fold-v<ver>-<timestamp>.bak` and
+records itself in the `repairs` table, so it runs once per version and is idempotent. Each pass
+version gets its own file and the newest three per pass version are kept (older ones are pruned), so
+"a `.pre-fold.bak` exists" no longer means anything: read `repairs` for what ran, and pick the
+backup by timestamp.
 
 Two cautions that come from real incidents:
 

package/docs/transcript-folding.md

@@ -112,9 +112,19 @@ accepted rather than guessed away.
 2. **The row is the truth on reads; `delta` exists only so a live turn does not re-send the whole text
    every frame.** Anything that reads the transcript (`hotwords.ts` context, the phone's notifications)
    reads rows, so it sees accumulated text for free — it used to see 40 chunks of 3.8 characters.
+2b. **Two frames are one stream only if they are close in time.** The rule is: the gap from the
+   previous frame is at most 2 s, the turn id (when both rows carry one) agrees, and a sentence end
+   only counts as a boundary when that gap is over 750 ms. The accepted cost is written down rather
+   than hidden: two id-less messages written less than 750 ms apart, the first ending in a full stop,
+   are indistinguishable from one stream and get merged — but only when both are short fragments (≤24
+   characters) carrying no `messageId` and no `block_key`, which is the only shape this rule applies to;
+   a longer second message stays its own row even at a 40 ms gap. Time is the only witness a store without
+   message ids has, and the alternative — the rule that shipped in v3 — cut every reply at its first
+   full stop.
 3. **Never fold on a guess.** Same id, or whitespace-insensitive equality, or ≥60% coverage. Everything
    else stays as it is, and the migration is logged (`[store] 历史分片已折叠：3804 行 → …`) with a
-   one-time `VACUUM INTO` backup beside the DB (`agentus.sqlite.pre-fold.bak`).
+   one-time `VACUUM INTO` backup beside the DB (`agentus.sqlite.pre-fold-v<ver>-<timestamp>.bak`,
+   newest three kept per pass version; what actually ran is in the `repairs` table).
 4. **A page boundary must not be able to cut a message.** Page sizes are row- and byte-bounded, and the
    store guarantees a message is one row; if either changes, re-run the checks below.
 
@@ -137,3 +147,13 @@ curl -s -H "Authorization: Bearer $(cat "${AGENTUS_DATA:-$HOME/.agentus}/auth.to
 Result for `hello`: **3804 rows → 70** (10 agent messages, 15 thought blocks, 37 tool cards, 8 prompts),
 `hasOlder=false`, both markdown tables reported complete (the 2623-character reply holds its 8-row table
 in one block), and one duplicate left — the 12-character re-send described above.
+
+## Splitting rows an older build glued together
+
+A re-walk cannot undo a merge: the second half's row is gone, so there is nothing to fold back out.
+`scripts/repair-glued-rows.py <db> <older-backup.bak>` finds the pairs that can be **proved** glued —
+both halves must appear, in that order, as message texts in an older copy of the same database, and
+both must be ≤24 characters — and prints them; `--apply` rewrites them. It is a dry run unless you
+pass `--apply`, and it puts the second half 5 s after the first so the corrected rule never joins
+them again.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentus",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "Multi-session web cockpit for ACP-speaking coding agents (Qoder CLI / Hermes). UI has no intelligence — the agent lives in spawned CLI subprocesses.",
   "license": "Apache-2.0",
   "repository": {
@@ -75,6 +75,7 @@
     "apk": "bash scripts/build-apk.sh",
     "transcript-fold": "tsx scripts/qa/transcript-fold.mts",
     "store-fold": "tsx scripts/qa/store-fold.mts",
+    "context-window": "tsx scripts/qa/context-window.mts",
     "live-stream": "tsx scripts/qa/live-stream.mts",
     "open-target": "tsx scripts/qa/open-target.mts",
     "rail-recent": "tsx scripts/qa/rail-recent.mts",
@@ -86,7 +87,12 @@
     "replay-window": "node scripts/qa/replay-window.mjs",
     "think-cadence": "node scripts/qa/think-cadence.mjs",
     "vad": "tsx scripts/qa/vad.mts",
-    "vad-silero": "tsx scripts/qa/vad-silero.mts"
+    "vad-silero": "tsx scripts/qa/vad-silero.mts",
+    "tus-mood": "tsx scripts/qa/tus-mood.mts",
+    "tus-mode-sweep": "node scripts/qa/tus-mode-sweep.mjs",
+    "usage-row-sweep": "node scripts/qa/usage-row-sweep.mjs",
+    "call-brief-sweep": "node scripts/qa/call-brief-sweep.mjs",
+    "reply-on-done": "node scripts/qa/reply-on-done.mjs"
   },
   "engines": {
     "node": ">=22.5"

package/packages/server/mock/agent.mjs

@@ -643,9 +643,13 @@ const agent = () => ({
     // A turn that does real work: N tool calls with a reasoning burst before each — the
     // transcript-flood case (ten calls + ten bursts). `[tools:10]` drives it with no permission
     // prompts: the point is the SHAPE of the transcript, not the approval.
-    const many = /\[tools:(\d+)\]/.exec(text);
+    // `[tools:N]` (25 ms in-progress window, the real shape) or `[tools:N:ms]` for QA: a 25 ms
+    // window is honest but a page that misses the re-render inside it can only be blamed on the
+    // machine's load, so a test that needs to OBSERVE the running state widens it explicitly.
+    const many = /\[tools:(\d+)(?::(\d+))?\]/.exec(text);
     if (many) {
       const n = Math.min(20, Math.max(1, Number(many[1]) || 1));
+      const windowMs = Math.min(3000, Math.max(10, Number(many[2]) || 25));
       for (let i = 1; i <= n; i++) {
         const burst = (`step ${i}: reading the file, checking the surrounding code, then writing `
           + "the change back. This sentence is deliberately long so the reasoning block is taller "
@@ -669,7 +673,7 @@ const agent = () => ({
           status: "in_progress",
           rawInput: { step: i },
         });
-        await sleep(25);
+        await sleep(windowMs);
         await send(agent._conn, sessionId, {
           sessionUpdate: "tool_call_update",
           toolCallId: id,
@@ -846,6 +850,23 @@ const agent = () => ({
     // One id per logical message, exactly like the real backend: the cockpit (and the store) fold the
     // chunks of a message by this id, so a mock that omits it would test a path nobody runs.
     const messageId = randomUUID();
+    // 表情通道的探针（糯米模式）：提示里带 `[emo-probe]`（只有 QA sweep 会发）**并且**同一轮
+    // 真的收到了 `[emo:x]` 提示句，才在回复开头吐一个标签。于是「服务端那段提示词到底有没有
+    // 到达 agent」变成一个能观测的事实，而不是靠读服务端代码相信；别的 sweep 不发这个探针，
+    // 行为零变化（也不需要给子进程多开一个 env 白名单出口）。
+    // 提示句是**另一个内容块**（ACP resource），不在 `text` 里 —— 只看 text 会得出「服务端没注入」
+    // 的错误结论（这次就是这么踩的）。所以探针看的是整条 prompt 的所有块。
+    const allBlocks = prompt.map((p) => p.text || p.resource?.text || "").join(" ");
+    const probe = allBlocks.match(/\[emo-probe(?::([a-z]+))?\]/i);
+    if (probe && /\[emo:[a-z]+\]/.test(allBlocks)) {
+      // 带后缀可指定要回哪张脸（[emo-probe:calm]）；不带后缀保持 happy，老 sweep 不用改。
+      const mood = (probe[1] || "happy").toLowerCase();
+      await send(agent._conn, sessionId, {
+        sessionUpdate: "agent_message_chunk",
+        messageId,
+        content: { type: "text", text: `[emo:${mood}] ` },
+      });
+    }
     const words = `Mock echo (${effort} effort) to: "${text}". `.repeat(2).split(" ");
     for (const w of words) {
       if (s.cancelled) return { stopReason: "cancelled" };
@@ -865,6 +886,22 @@ const agent = () => ({
       messageId,
       content: { type: "text", text: MOCK_MARKDOWN },
     });
+    // `[think-late:N]` — 回答已经开始之后才到的思考块。真实后端会这样交错（思考 → 回答 →
+    // 又一段思考），而这正是「耳朵里在念回答、转录里还写着思考中」的来源。QA only：
+    // 没有这个探针的轮次行为零变化。
+    const lateThink = /\[think-late(?::(\d+))?\]/.exec(text);
+    if (lateThink) {
+      const thinkId = `th-${sessionId}-late`;
+      const n = Math.min(Math.max(Number(lateThink[1] ?? 2) || 2, 1), 12);
+      for (let i = 0; i < n; i++) {
+        await send(agent._conn, sessionId, {
+          sessionUpdate: "agent_thought_chunk",
+          messageId: thinkId,
+          content: { type: "text", text: `after the answer started, thought ${i + 1}. ` },
+        });
+        await sleep(SLOW);
+      }
+    }
     // Context gauge data, shaped like a real agent's usage_update (AionUi F-DISPLAY-07).
     // `/compress` is the agent's own command for this: honour it by actually lowering the
     // reported context, so "the button did something" is a measurable claim.

package/packages/server/src/acp/backends.ts

@@ -24,6 +24,28 @@ export interface HomeIsolation {
   homeDefault: string;
 }
 
+/**
+ * Hand a backend its declared context window as argv, when that is the only way it can hear it.
+ *
+ * Qoder reports no `usage_update` and advertises no context option over ACP (issue #57), but its CLI
+ * takes a global `--context-window <n>`; its own log line (`context_window.restore_skipped
+ * reason=cli_context_window_override`) says the flag wins over the window restored from a resumed
+ * session. Every other backend keeps the ACP route (Hermes has `context_budget`), so this does
+ * nothing for them — and an arg the operator already put in the row is never duplicated.
+ */
+export function applyContextWindow(
+  id: string,
+  spec: { kind?: string },
+  args: string[],
+  contextLimit?: number | null,
+): string[] {
+  const declared = typeof contextLimit === "number" && contextLimit > 0 ? Math.round(contextLimit) : null;
+  if (!declared) return args;
+  if (id !== "qoder" && spec.kind !== "qoder") return args;
+  if (args.some((a) => a === "--context-window" || a.startsWith("--context-window="))) return args;
+  return [...args, "--context-window", String(declared)];
+}
+
 export interface BackendSpec {
   /** registry row id (M6); the builtin seeds carry theirs, spawn does not need it */
   id?: string;