@comchatx/cx-subagents 0.1.0 → 0.2.0

package/README.md

@@ -1,43 +1,56 @@
-When a task will take long, such as a research across several data sources or a look through many listings, cx hands it to a helper that runs in the background, tells you it has, and keeps answering you. The helper's result comes back into the conversation by itself.
+When cx hands work to the background, a card for it appears under To do on the board. It holds what cx asked for. When the work is done, the same card shows its result. If it is not done after 30 minutes, the card says 超时 and shows what was done so far.
 
-## When the result comes back
+It needs [`pi-subagents`](https://www.npmjs.com/package/pi-subagents), which runs the work in the background, and [`@comchatx/cx-board`](https://www.npmjs.com/package/@comchatx/cx-board), the board. The Plugins page installs both with it. With pi-subagents alone, cx still works in the background, and no card is written.
 
-A helper runs for at most 30 minutes. When it is done, cx tells you what it found in the conversation; if it is still at work after 30 minutes, cx says it ran out. On cx's computer, at most two helpers run in the background at a time in one conversation: that is ComChatX's setting on the computer, not this package's, and a computer without that setting sets no cap.
-
-## What it costs
+## When cx's computer stops
 
-A helper uses the same model as cx and is paid from the same balance. cx's computer stays on while a helper runs, and that time is billed.
+If cx's computer stops before the work is done, its card stays as it was when the work started.
 
-## When cx's computer stops
+## What it costs
 
-If cx's computer stops before a result is handed back, that result is lost and the work has to run again.
+The work in the background uses the same model as cx and is paid from the same balance. cx's computer stays on while it runs, and that time is billed.
 
 ## How it is built
 
-- **pi-subagents, unchanged.** The helper is [`pi-subagents`](https://www.npmjs.com/package/pi-subagents) and its `subagent` tool. This package names it in its `comchatx` field's `builds`, so the Plugins page installs it with this one; it does not carry it. Its tests run against `pi-subagents` 0.83.0 on pi 1.3.0.
-- **One skill, `cx-subagents`.** It says when cx hands a task to the background (a long research across several sources; a look through many listings), that cx then hands the conversation back and says so, and that the result returns by itself. pi-subagents' own tool asks for an instruction before it delegates; in a ComChatX box this skill is that instruction. Its description says what it needs: pi installs nothing for a package.
-- **pi-subagents' config, carried by the box.** pi-subagents reads `extensions/subagent/config.json` in pi's agent directory once, when it loads, and the Plugins page installs it before this package, so a box's image carries the file instead of this package writing it:
-
-  ```json
-  {
-    "asyncByDefault": true,
-    "toolActivation": "eager",
-    "maxActiveAsyncRunsPerSession": 2
-  }
-  ```
+- **One extension, `extensions/board-cards.ts`.** pi loads it as TypeScript; there is no build. It ships no skill. When cx hands work to the background is cx's own judgement with pi-subagents' `subagent` tool.
+- **What it listens to.** pi-subagents emits `subagent:async-started` and `subagent:async-complete` on the session's event bus. The start carries the run id and the `subagent` call's id, and redacts the task. The extension takes the task from pi's own `tool_call` event for that call. The end carries the result.
+- **The card.** It goes in `board/<person>/todo/` under the session's directory, which in cx's computer is `/tenant`. The person is the one directory under `board/`; a board with none, or with more than one, gets no card. This is the board's shape as `cx-board` describes it. The extension imports nothing from `cx-board` and calls nothing of the board's.
+  - The name is `<YYYYMMDD-HHMMSS>-subagent-<run id>.md`, the start's time in UTC.
+  - The front matter is `kind: finding`, a `title` and an `at`. The title is the task's first line, at most 200 characters. `at` is the start.
+  - The words are the task as given. They are cut where the whole file would pass the 32 KiB the board reads.
+- **At the end** the same file in `todo/` is rewritten, its name, title and `at` kept. The words become:
+  - a single run's own output;
+  - each run's output under its agent's name, for several;
+  - at the deadline, 超时, then what the run had written. pi-subagents' own note on the stop, its "Recovery summary", is left out.
 
-  A run goes to the background unless a call says otherwise; the `subagent` tool is offered from a session's first request; and two background runs at a time in one session, where pi-subagents' own default has no cap. The 30-minute limit is pi-subagents' own default.
-- **What the box does for it.** A background run is a detached Node process of the model's user, so the box counts it as work and stays awake while it runs. Its state lives under `/tmp`, which a stop clears. The box drops the widget pi-subagents sets once a second while a run is in the background, since the page draws none. The notice that wakes cx when a run ends is not drawn; cx's own answer after it is.
+  Nothing is moved. A card the seller has already marked read stays in `done/`, and the result is a card again in `todo/` under the same name. A second start of the same run id overwrites its card. A run that ends after cx's computer stopped leaves its card as it started.
+- **pi-subagents' config is carried by the box,** not this package. `asyncByDefault` sends a run to the background. `toolActivation: "eager"` offers the `subagent` tool from the first request. `maxActiveAsyncRunsPerSession: 2` caps the runs in one conversation at two. The 30 minutes is pi-subagents' own default for a background run.
 
 ## Tests
 
-- `test/package.test.ts`: the pinned pi lists `cx-subagents` beside `pi-subagents`' own skill, with what it needs in its description; the `comchatx` field names the same skills pi lists from this package, with their words, for the Plugins page; the package ships the skill alone and names `pi-subagents` for the page.
-- `test/background.test.ts`, on the pinned pi in RPC mode with a scripted model on loopback, as a box starts pi:
-  - the `subagent` call comes back at once with the run detached;
-  - a second message is answered while the helper is still at work;
-  - the helper's result arrives as pi-subagents' notice, not displayed, and starts the turn in which cx relays it;
-  - with the box's config the session holds `0/2` background runs, and without it `0/unlimited`.
+The tests run against `pi-subagents` 0.85.0 on pi 1.4.0, the versions cx's computer runs.
+
+- **`test/board.test.ts`**, on the pinned pi in RPC mode with a scripted model on loopback, as a box starts pi. Each card is read by the board's own reader, copied into `test/fixtures/board-reader.ts` with its source lines named.
+  - A `subagent` call writes a started card whose title is the task's first line. The result rewrites the same file.
+  - A run stopped at its deadline writes 超时 with what it had.
+  - Two runs write two files.
+  - The same run id started again overwrites its card.
+- **`test/board-cards.test.ts`**, the extension on a bus of its own:
+  - the name and the front matter;
+  - a card found again after a reload;
+  - nothing moved;
+  - the task of a chain or a parallel run;
+  - no card where the board is not one person's;
+  - the 32 KiB cut;
+  - the end's words.
+- **`test/package.test.ts`:**
+  - pi lists no skill from the package and loads its one extension;
+  - the package ships the extension alone;
+  - the package names `pi-subagents` and `@comchatx/cx-board` in `comchatx.builds`.
+- **`test/background.test.ts`:**
+  - a run goes to the background and its result comes back into the conversation;
+  - the box's config caps the runs at two.
 
 ## Release
 
-A maintainer publishes the first version by hand, `npm publish --access public` from a checkout of the merged tag. Each later version is published by `.github/workflows/release.yml` on a `v<version>` tag, once this repository is the package's trusted publisher on npm.
+`.github/workflows/release.yml` publishes each version on a `v<version>` tag, once this repository is the package's trusted publisher on npm. Until then a maintainer publishes by hand, `npm publish --access public` from a checkout of the merged tag.

package/extensions/board-cards.ts

@@ -0,0 +1,162 @@
+import { mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/** pi-subagents' events for a background run, on the session's bus (`pi-subagents` `src/shared/types.js`). */
+export const STARTED = "subagent:async-started";
+export const COMPLETE = "subagent:async-complete";
+export const TIMED_OUT_WORDS = "超时";
+
+/** The board's shape (`parts/cx-board.md` §1): one directory per person under `board/`, cards waiting in its `todo/`. */
+const BOARD = "board";
+const TODO = "todo";
+const DONE = "done";
+const PERSON = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+/** The most of one file the board reads; a larger one is drawn as its name alone. */
+export const CARD_MAX_BYTES = 32 * 1024;
+const TITLE_MAX = 200;
+/** The `subagent` calls whose words are kept, the latest, for a start that names its call after the call's own result. */
+const ASKED_KEPT = 64;
+
+type Card = { readonly name: string; readonly title: string; readonly at: number };
+type Options = { readonly now?: () => number };
+
+const text = (value: unknown): string | undefined => (typeof value === "string" ? value : undefined);
+const record = (value: unknown): Record<string, unknown> => (typeof value === "object" && value !== null ? (value as Record<string, unknown>) : {});
+
+/** What a `subagent` call asked: its task, or each step's of a chain or a parallel run, as given. */
+function taskOf(input: Record<string, unknown>): string {
+  const own = text(input["task"]);
+  if (own !== undefined && own.trim() !== "") return own;
+  const steps = [input["tasks"], input["chain"]].flatMap((list) => (Array.isArray(list) ? list : [])).map((step) => text(record(step)["task"]) ?? "").filter((one) => one.trim() !== "");
+  return steps.join("\n\n");
+}
+
+const firstLine = (task: string): string => {
+  const line = (task.split(/\r?\n/).find((one) => one.trim() !== "") ?? "").replace(/\s+/g, " ").trim();
+  return line.length > TITLE_MAX ? `${line.slice(0, TITLE_MAX - 1)}…` : line;
+};
+
+const stamp = (ms: number): string => new Date(ms).toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15);
+const idPart = (id: string): string => id.replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 80);
+const suffix = (id: string): string => `-subagent-${idPart(id)}.md`;
+
+/** A card as the board reads it: front matter with its kind, title and time, then the words, cut to what the board reads whole. */
+export function cardText(card: Card, words: string): string {
+  const head = `---\nkind: finding\ntitle: ${JSON.stringify(card.title)}\nat: ${new Date(card.at).toISOString()}\n---\n\n`;
+  const room = CARD_MAX_BYTES - Buffer.byteLength(head) - 1;
+  const body = Buffer.byteLength(words) <= room ? words : `${Buffer.from(words).subarray(0, room - 3).toString().replace(/�+$/, "")}…`;
+  return `${head}${body}\n`;
+}
+
+/** The one person's board under the session's directory, or none when there is not exactly one. */
+function personDir(cwd: string): string | undefined {
+  let people: string[];
+  try {
+    people = readdirSync(join(cwd, BOARD), { withFileTypes: true }).filter((one) => one.isDirectory()).map((one) => one.name);
+  } catch {
+    return undefined;
+  }
+  return people.length === 1 && PERSON.test(people[0]!) ? join(cwd, BOARD, people[0]!) : undefined;
+}
+
+/** A run's card already on the board, by its run id: in `todo/`, else where the seller moved it, with its title and time read back. */
+function found(person: string, id: string, now: number): Card | undefined {
+  for (const place of [TODO, DONE]) {
+    let names: string[];
+    try { names = readdirSync(join(person, place)); } catch { continue; }
+    const name = names.filter((one) => one.endsWith(suffix(id)) && !one.startsWith(".")).sort().at(-1);
+    if (name === undefined) continue;
+    let lines: string[] = [];
+    try { lines = readFileSync(join(person, place, name), "utf8").split(/\r?\n/); } catch { /* the name alone */ }
+    const field = (key: string): string | undefined => lines.find((line) => line.startsWith(`${key}: `))?.slice(key.length + 2);
+    let title = field("title") ?? "";
+    try { title = JSON.parse(title) as string; } catch { /* as it stands */ }
+    const at = Date.parse(field("at") ?? "");
+    return { name, title, at: Number.isFinite(at) ? at : now };
+  }
+  return undefined;
+}
+
+/** Writes a card into `todo/` whole, so the board never reads half of one. */
+function write(person: string, card: Card, words: string): void {
+  const dir = join(person, TODO);
+  mkdirSync(dir, { recursive: true });
+  const temp = join(dir, `.${card.name}.${process.pid}.tmp`);
+  writeFileSync(temp, cardText(card, words));
+  renameSync(temp, join(dir, card.name));
+}
+
+/** Where pi-subagents' own note on a stopped run begins, after what the helper had written: paths and checks, not the helper's words. */
+const RECOVERY = "\n\nRecovery summary:";
+const ownWords = (result: Record<string, unknown>): string => {
+  const output = text(result["output"]) ?? "";
+  const cut = output.indexOf(RECOVERY);
+  return (cut < 0 ? output : output.slice(0, cut)).trim();
+};
+
+/**
+ * A run's end as its card's words: a single helper's own output, or each helper's of several under its agent's name; at the deadline,
+ * 「超时」 and what the run had when pi-subagents stopped it.
+ */
+export function endWords(event: Record<string, unknown>): string {
+  const timedOut = event["timedOut"] === true;
+  const results = Array.isArray(event["results"]) ? event["results"].map(record) : [];
+  const each = results.map((result) => ({ agent: text(result["agent"]) ?? "", words: ownWords(result) || (timedOut ? "" : (text(result["error"]) ?? "").trim()) }));
+  const words = each.length === 1 ? each[0]!.words : each.filter((one) => one.words !== "").map((one) => `${one.agent}:\n${one.words}`).join("\n\n");
+  if (timedOut) return words === "" ? TIMED_OUT_WORDS : `${TIMED_OUT_WORDS}\n\n${words}`;
+  return words !== "" ? words : (text(event["summary"]) ?? text(event["error"]) ?? "").trim();
+}
+
+/**
+ * Each background run of pi-subagents is a card on the board: at its start, the task's first line as the title, the start as its time and
+ * the task as its words; at its end, the same file in `todo/` with the result as its words. Nothing is moved; a card the seller already
+ * moved to `done/` stays there, and the result is a card again in `todo/` under the same name.
+ */
+export function boardCards(pi: ExtensionAPI, options: Options = {}): void {
+  const now = options.now ?? Date.now;
+  const asked = new Map<string, string>();
+  const running = new Set<string>();
+  const cards = new Map<string, Card>();
+  let cwd = process.cwd();
+
+  pi.on("session_start", (_event, ctx) => { cwd = ctx.cwd; });
+  pi.on("tool_call", (event, ctx) => {
+    cwd = ctx.cwd;
+    if (event.toolName !== "subagent") return;
+    asked.set(event.toolCallId, taskOf(record(event.input)));
+    running.add(event.toolCallId);
+    for (const old of asked.keys()) if (asked.size > ASKED_KEPT) asked.delete(old);
+  });
+  pi.on("tool_result", (event) => { running.delete(event.toolCallId); });
+
+  pi.events.on(STARTED, (data) => {
+    const event = record(data);
+    const id = text(event["id"]);
+    const person = personDir(cwd);
+    if (id === undefined || person === undefined) return;
+    const toolCallId = text(event["toolCallId"]);
+    const own = toolCallId === undefined ? undefined : asked.get(toolCallId);
+    const task = own ?? (running.size === 1 ? asked.get([...running][0]!) : undefined) ?? "";
+    const at = now();
+    const before = cards.get(id) ?? found(person, id, at);
+    const card = { name: before?.name ?? `${stamp(at)}${suffix(id)}`, title: firstLine(task) || (text(event["agent"]) ?? "subagent"), at };
+    cards.set(id, card);
+    write(person, card, task);
+  });
+
+  pi.events.on(COMPLETE, (data) => {
+    const event = record(data);
+    const id = text(event["id"]) ?? text(event["runId"]);
+    const person = personDir(cwd);
+    if (id === undefined || person === undefined) return;
+    const at = now();
+    const card = cards.get(id) ?? found(person, id, at) ?? { name: `${stamp(at)}${suffix(id)}`, title: "", at };
+    cards.delete(id);
+    write(person, { ...card, title: card.title || (text(event["agent"]) ?? "subagent") }, endWords(event));
+  });
+}
+
+export default function (pi: ExtensionAPI): void {
+  boardCards(pi);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comchatx/cx-subagents",
-  "version": "0.1.0",
-  "description": "Lets cx hand a long task to a helper in the background and keep answering you; the result comes back into the conversation by itself.",
+  "version": "0.2.0",
+  "description": "Puts what cx does in the background on the board.",
   "license": "MIT",
   "author": "ComChatX",
   "homepage": "https://github.com/comchatx/cx-subagents#readme",
@@ -15,40 +15,34 @@
   ],
   "type": "module",
   "pi": {
-    "skills": [
-      "./skills"
+    "extensions": [
+      "./extensions/board-cards.ts"
     ]
   },
   "files": [
-    "skills"
+    "extensions"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "comchatx": {
-    "about": "让 cx 把耗时的任务交给后台助手，自己继续回答你。",
-    "description": "任务要花很长时间时，比如跨几个数据源做调研、逐个查看大量 listing，cx 会把它交给一个在后台运行的助手，告诉你它这样做了，然后继续回答你。助手的结果会自己回到对话里。\n\n## 结果什么时候回来\n\n助手最多运行 30 分钟。做完时，cx 会在对话里告诉你结果；到 30 分钟还没做完，cx 会说它超时了。在 cx 的电脑上，同一个对话里最多同时有两个助手在后台运行：这是 ComChatX 在电脑上的设置，不是这个插件的；没有这项设置的电脑不限个数。\n\n## 费用\n\n助手和 cx 用同一个模型，由同一份余额付费。助手运行时，cx 的电脑保持开机，开机时长也要付费。\n\n## 电脑关机时\n\n如果 cx 的电脑在结果交回之前关机，这个结果就丢了，需要重新运行。",
+    "about": "把 cx 在后台做的事放到看板上。",
+    "description": "cx 在后台做一件事时，看板的待处理里会出现一张卡片，写着 cx 交代的内容。做完后，卡片换成结果；30 分钟还没做完，卡片显示「超时」和已做到的部分。\n\n## 费用\n\n后台的工作和 cx 用同一个模型，由同一份余额付费。后台有工作时，cx 的电脑保持开机，开机时长也要付费。",
     "mark": {
       "line": "rocket"
     },
     "section": "extensions",
     "builds": [
-      "pi-subagents"
-    ],
-    "skills": {
-      "cx-subagents": {
-        "about": {
-          "en": "Lets cx hand a long task to a helper in the background and keep answering; the result comes back into the conversation.",
-          "zh": "让 cx 把耗时的任务交给后台助手并继续回答；结果会回到对话里。"
-        }
-      }
-    }
+      "pi-subagents",
+      "@comchatx/cx-board"
+    ]
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
     "@types/node": "26.2.0",
-    "pi-subagents": "0.83.0",
+    "@vitest/coverage-v8": "4.1.11",
+    "pi-subagents": "0.85.0",
     "typescript": "7.0.2",
     "vitest": "4.1.11"
   }

package/skills/cx-subagents/SKILL.md

@@ -1,23 +0,0 @@
----
-name: cx-subagents
-description: "When a task will take long - a research across several data sources, a look through many listings - cx hands it to a helper in the background with pi-subagents' `subagent` tool, tells the seller it has, and keeps answering; the helper's result comes back into the conversation on its own. Needs pi-subagents; if no pi-subagents skill is listed, it is not installed, and the seller installs it in Plugins."
----
-
-## When a task goes to the background
-
-- A research across several data sources, or a look through many listings: work that would hold the conversation for minutes.
-- The seller asked for the work. In this box that is the instruction to hand a long piece of it to a helper; ask nothing more first.
-- Not for a quick answer, a single read, or a step whose result the next answer needs at once: do those in the conversation.
-
-## How
-
-- Call `subagent` with one agent and the whole task in your own words: what to look at, what to bring back. Leave `async` out: a run goes to the background here.
-- Then hand the conversation back: tell the seller in one sentence that the work runs in the background and that its result will come here, and answer whatever they ask next.
-- On cx's computer at most two helpers run at a time in one conversation, by ComChatX's setting on the computer, and a third is refused until one ends; a computer without that setting sets no cap.
-
-## When it comes back
-
-- The result arrives by itself, as a message that starts a turn of yours. Tell the seller what the helper found, in your words, as the answer to what they asked for.
-- A helper stops at 30 minutes, and its message says so: tell the seller it ran out, and offer to split the work.
-- If cx's computer stops before a result is handed back, that result is lost. If the seller asks after a stop, say so and offer to run it again.
-- A helper uses the same model as you, paid from the same balance, and cx's computer stays on while it runs.