@gavin-hu/my-pi-agent 0.13.1 → 0.15.0

package/extensions/subagent/README.md

@@ -2,7 +2,9 @@
 
 A `subagent` tool that hands a task to a specialized agent running in its own
 `pi --mode json` process. The subagent gets a fresh context window, so broad
-exploration or parallel work does not fill the main conversation.
+exploration or parallel work does not fill the main conversation. A single run
+can also start in the background and be inspected, collected, or cancelled with
+`/agents`.
 
 ```bash
 pi --extension ./extensions/subagent    # load just this extension
@@ -16,6 +18,10 @@ How the `subagent` call and its result look in the transcript — the call line
 
 <img src="../../assets/tools/subagent.png" alt="The subagent tool's call and result: the call line and an indented body with the two tasks, each agent's section rule, its summary, and the usage total" width="100%">
 
+## Screens
+
+<img src="../../assets/agents.png" alt="The /agents screen: running and finished background helpers with status, task, elapsed time, and usage" width="100%">
+
 ## What it does
 
 - **Isolated context.** Each subagent is a separate `pi` process with its own
@@ -25,10 +31,17 @@ How the `subagent` call and its result look in the transcript — the call line
 - **External agents.** Optionally load markdown agents from `~/.pi/agents`
   (user) and the nearest `.pi/agents` (project). They are opt-in per scope and
   never replace the built-ins silently.
-- **Three modes.** One agent, a parallel batch, or a sequential chain.
+- **Three modes, plus background.** One agent, a parallel batch, or a sequential
+  chain; a single run can also continue after the tool returns and be collected
+  from `/agents`. A running helper adds a `↳ N` footer chip, and a finish notice
+  points back at `/agents`.
 - **Streaming.** Tool calls and progress update live in the transcript while the
   subagent runs; the `app.tools.expand` key (`ctrl+o` by default) expands the
   full task, tool calls, Markdown output, and usage.
+- **Bounded runs.** A per-run deadline kills a child that hangs, and reports it
+  as a failed run instead of rejecting the whole call.
+- **Optional transcripts.** Opt-in per-run stream under `.pi/subagents/`,
+  written by the parent and pruned by age and count.
 - **Inherited model.** Subagents use the dispatching session's model and thinking
   level unless an agent overrides them (none do).
 
@@ -40,6 +53,7 @@ How the `subagent` call and its result look in the transcript — the call line
 | Field | Value |
 |---|---|
 | `agent` + `task` | Single mode: one built-in/external agent and its task. |
+| `background` | Single mode only: start the run and return immediately; manage it with `/agents`. |
 | `tasks[]` | Parallel mode: independent `{agent, task, cwd?}` entries, max 8. |
 | `chain[]` | Chain mode: ordered `{agent, task, cwd?}` steps, max 8; `{previous}` is replaced by the prior step's final output. |
 | `cwd` | Optional working directory for the spawned process (single mode; per-step for the others). A relative path resolves against the active root. |
@@ -56,6 +70,21 @@ How the `subagent` call and its result look in the transcript — the call line
 { "agent": "explorer", "task": "Find every place the HTTP client is retried", "cwd": "." }
 ```
 
+### Background
+
+```json
+{ "agent": "explorer", "task": "Map the auth module", "background": true }
+```
+
+The tool returns immediately with a run id such as `a2`. `/agents` lists every
+run with its status, elapsed time, and usage; `Enter` opens the run, `c` collects
+a finished result into the conversation, and `x` cancels a running one. While a
+run is active, its detail pane follows a bounded preview of the latest output,
+and a `↳ N` chip in the footer counts running helpers. A finish notice points
+back at `/agents`; the finalized result replaces the preview when the run
+finishes. A background run is session-owned and is bounded by the same timeout
+and transcript settings as a foreground run.
+
 ### Parallel
 
 Runs up to 8 tasks, at most 4 at once. Independent tasks only.
@@ -88,6 +117,55 @@ at most 8 steps (like the parallel task cap).
 }
 ```
 
+## Command
+
+| Command | What it does |
+|---|---|
+| `/agents` | Open the background-run board: inspect, collect, or cancel. |
+
+The board is TUI-only for actions; RPC, print, and JSON print the run list.
+Collecting sends the result as a user message, which starts the next turn.
+
+## Configuration
+
+Read from the shared `bytefly.json` section `subagent` (global then project),
+once per session. Keys and bounds live in the
+[configuration page](../../docs/configuration.md#subagent--delegated-runs);
+the behaviour is here.
+
+- **`timeoutMs`** (default ten minutes, `0` disables) bounds one child run. The
+  limit is per run, not per call, so a chain is bounded step by step and a
+  parallel batch bounds each task separately. On expiry the child gets the same
+  `SIGTERM`, then `SIGKILL` after 5 s, as a user abort — but the run fails
+  instead of throwing: a chain stops at that step, a parallel call counts a
+  failure, and the model sees `Timed out after 10m00s`.
+- **`transcripts`** (`off`, `failed`, or `all`; default `off`) keeps finished
+  runs on disk, all of them or only the failed ones.
+- **`retentionDays`** (default 14) and **`maxRuns`** (default 100) bound the
+  store. It is pruned at `session_start`, and only while transcripts are on.
+- **`backgroundMax`** (default 4, `1`–`8`) bounds concurrently running
+  background children. Finished runs do not consume a slot. A run that is still
+  running when the session ends is interrupted; the next `/agents` shows the
+  start entry without a finish.
+
+### Transcripts
+
+```
+.pi/subagents/20261015-143012-a1b2c3/
+  meta.json     agent, task, cwd, model, timings, exit, status, usage
+  events.jsonl  the child's raw stdout lines, verbatim
+  stderr.log    only when the child wrote any
+```
+
+The store is resolved against the **session** cwd, so inside a worktree it lands
+in the main checkout's `.pi/` and outlives that worktree — the anchoring the
+`job` registry uses. Outside a repository it falls back to
+`<agent-dir>/subagents`. The parent writes it and the child never learns it
+exists, so `readOnly`, the `--tools` allowlist, and the project-agent trust gate
+are unchanged. Writing is best-effort: an unwritable checkout records the failure
+in the result and never fails a run. The stream is buffered in the parent up to
+32 MiB, then truncated with a marker rather than silently dropped.
+
 ## Security
 
 A subagent is a real `pi` process and shares Pi's OS permissions. The built-in
@@ -206,7 +284,10 @@ Markdown, and per-step/per-task usage with a total.
 
 A failed or aborted result always shows its `errorMessage`, falling back to the
 subprocess `stderr`, in both the collapsed and expanded views, in every mode. A
-failure with neither falls back to `Error: Subprocess exited with code N.` and an
+run that exceeded its deadline reports `Timed out after …` the same way, and the
+expanded view adds the transcript path, the truncation marker, or why the
+transcript could not be written. A failure with neither falls back to
+`Error: Subprocess exited with code N.` and an
 `[exit N]` bracket, so a non-zero exit is never silent. A child terminated by a
 signal (an OOM kill, a crash) has no exit code, so it is recorded as
 `Terminated by <signal>` and reported as a failure. Parallel and chain
@@ -232,8 +313,10 @@ step's `Output`.
   does not reimplement tool execution or model streaming.
 - **No pinned models.** Built-in agents set no `model`, so a subprocess inherits
   the dispatching session's provider/model and thinking level.
-- **No persistence.** Subagent transcripts live only in the tool result details;
-  they are not written to the parent session.
+- **No persistence by default.** A run's transcript lives in the tool result
+  details; keeping it on disk is opt-in, parent-written, and bounded by age and
+  count. It is an audit and handoff record, not a resume point: replaying a run
+  whose writes already landed is not attempted.
 - **No cost attribution to the parent session.** A subagent's tokens and cost are
   captured in the tool result and shown in the transcript, but they belong to a
   separate process and are not added to the dispatching session's totals. Instead,
@@ -244,6 +327,19 @@ step's `Output`.
   starts from zero, and a run that never produced an assistant message publishes
   nothing.
 
+## Limitations
+
+- Background runs are single-mode only. Parallel and chain calls wait as before.
+- A background run is session-owned: `/tree` does not move it, and a process
+  restart cannot resume it. A start entry without a finish is shown as
+  `interrupted`.
+- The collected output is capped at 50 KiB; the optional transcript keeps the
+  full stream. The `/agents` detail keeps only a bounded live preview, and a
+  finished run keeps its bounded output in the session record rather than the
+  child's full result.
+- A finish notice appears in the TUI, but there is no OS notification; the run
+  remains listed in `/agents`.
+
 ## Pi integration
 
 | Aspect | Detail |
@@ -253,8 +349,8 @@ step's `Output`.
 | Annotations | `readOnlyHint: false`, `openWorldHint: true` |
 | Output schema | none; the full result lives in tool-result `details` |
 | Execution | spawns `pi --mode json` subprocesses; external agents discovered from `<agent-dir>/agents` and `.pi/agents` |
-| State storage | tool-result `details` only (no session persistence) |
-| Lifecycle | none; the tool is stateless and spawns per call |
+| State storage | tool-result `details`; optional per-run transcripts under `.pi/subagents/`; background start/finish entries (`subagent-background`) on the session branch |
+| Lifecycle | `session_start` loads the config, prunes expired transcripts, and attaches the footer chip; `session_shutdown` aborts every live background child and clears the chip |
 
 ## Design notes
 
@@ -284,6 +380,14 @@ step's `Output`.
   results arrive as `message_end` (messages, usage, model, stop reason) and
   failures as `tool_execution_end`. A tool error does not by itself fail the run,
   because the agent may recover.
+- **A deadline reuses the abort kill path but not its outcome.** One kill
+  closure serves both triggers, so the SIGTERM → 5 s SIGKILL escalation is
+  identical; only the reporting differs, because a deadline must leave the
+  finished steps in `details` while a user abort rejects the call.
+- **The transcript is the parent's.** Teeing the child's stdout and stderr in
+  `spawnAndCollect` and flushing in `runSingleAgent`'s `finally` means the
+  artifact exists even on the abort path, and the child needs no tool, no prompt
+  line, and no writable store.
 - **Bounded parallel output.** Parallel mode runs at most 4 of up to 8 tasks at
   once and caps each model-facing section at 50 KiB, appending an omission notice
   pointing at the tool details. The full results stay in `details` for rendering.
@@ -318,7 +422,13 @@ step's `Output`.
 | `schema.ts` | TypeBox params, limits, and `resolveMode`. |
 | `invocation.ts` | `pi` subprocess invocation and argument construction. |
 | `stream.ts` | JSON-event parsing, usage accounting, output helpers (pure). |
-| `run.ts` | Runs one subagent process and captures its result. |
+| `transcripts.ts` | Per-run transcript buffer, run ids, the store directory, and pruning. |
+| `config.ts` | The `subagent` section of `bytefly.json`: deadline, transcripts, retention. |
+| `run.ts` | Runs one subagent process and captures its result (including the background abort-as-result path). |
+| `background.ts` | Background run entries, replay, capacity, cancel, collect, and shutdown. |
+| `background-tui.ts` | The `/agents` board: a `DockListScreen` with a live output pane and width-aware facts. |
+| `commands.ts` | The `/agents` command. |
+| `ui.ts` | The running-count footer chip and finish notices. |
 | `format.ts` | Token/usage/tool-call formatting (pure). |
 | `render.ts` | `renderCall` / `renderResult` transcript rendering. |
 | `types.ts` | Shared result and process types. |

package/extensions/subagent/background-tui.ts

@@ -0,0 +1,208 @@
+/**
+ * The `/agents` board: background runs, live status, and a per-run detail.
+ *
+ * The board reads runs from a getter on every render, so a finish or cancel is
+ * reflected without rebuilding the component. The frame, the id-anchored cursor,
+ * the navigation and wheel keys, and the pane lifecycle come from the shared
+ * `DockListScreen`, so this module owns only the run vocabulary: the row, the
+ * status view, the key/value facts, the hints, and what `c` and `x` do.
+ *
+ * Two of that base's optional members are why the board can be one: the pane is
+ * live (`liveDetail`), because a running child's output arrives between frames
+ * and nothing polls it, and the facts are a `facts` hook, because the key/value
+ * rows are built from the current width.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { sanitizeLine, stripControlChars } from "../../lib/format.ts";
+import type { ScreenHint, ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { DockListScreen, type DetailContents } from "../../lib/tui/dock-screen.ts";
+import { GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
+import { keyValueRow, statusRow } from "../../lib/tui/rows.ts";
+import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
+import type { BackgroundRun, BackgroundStatus } from "./background.ts";
+import { canCollect } from "./background.ts";
+import { formatBackgroundDuration, formatUsageStats } from "./format.ts";
+
+/** One status's glyph, role, and readable label. */
+function statusView(status: BackgroundStatus): { glyph: string; role: TuiRole; label: string } {
+	switch (status) {
+		case "running":
+			return { glyph: GLYPHS.jobsRunning, role: "warn", label: "running" };
+		case "finished":
+			return { glyph: GLYPHS.check, role: "ok", label: "finished" };
+		case "failed":
+			return { glyph: GLYPHS.jobsFailure, role: "bad", label: "failed" };
+		case "cancelled":
+			return { glyph: GLYPHS.stopped, role: "warn", label: "cancelled" };
+		case "timedout":
+			return { glyph: GLYPHS.warn, role: "bad", label: "timed out" };
+		case "interrupted":
+			return { glyph: GLYPHS.unknown, role: "faint", label: "interrupted" };
+	}
+}
+
+/** A short task label for a list row. */
+function taskLabel(run: BackgroundRun): string {
+	return sanitizeLine(run.task).split("\n")[0] ?? "";
+}
+
+/** The output rows for the detail pane. */
+function outputLines(run: BackgroundRun): string[] {
+	const text =
+		run.output?.trim() ||
+		(run.status === "running"
+			? "Still running…"
+			: run.status === "interrupted"
+				? "Interrupted before it finished."
+				: "(no output recorded)");
+	return text.split("\n").map((line) => stripControlChars(line).replaceAll("\t", "    ").slice(0, 2_000));
+}
+
+/** The detail key/value rows. */
+function detailRows(run: BackgroundRun, now: number, theme: Theme, width: number): string[] {
+	const usage = run.usage ? formatUsageStats(run.usage) : "(not reported)";
+	const rows = [
+		keyValueRow(theme, width, { label: "Task", value: taskLabel(run), labelWidth: 12 }),
+		keyValueRow(theme, width, { label: "Cwd", value: sanitizeLine(run.cwd), labelWidth: 12 }),
+		keyValueRow(theme, width, { label: "Status", value: statusView(run.status).label, labelWidth: 12 }),
+		keyValueRow(theme, width, { label: "Duration", value: formatBackgroundDuration(run, now), labelWidth: 12 }),
+		keyValueRow(theme, width, { label: "Usage", value: usage, labelWidth: 12 }),
+	];
+	if (run.errorMessage) {
+		rows.push(keyValueRow(theme, width, { label: "Error", value: sanitizeLine(run.errorMessage), labelWidth: 12 }));
+	}
+	if (run.artifactPath) {
+		rows.push(
+			keyValueRow(theme, width, { label: "Transcript", value: sanitizeLine(run.artifactPath), labelWidth: 12 }),
+		);
+	}
+	return rows;
+}
+
+export interface AgentsBoardOptions {
+	runs: () => readonly BackgroundRun[];
+	theme: Theme;
+	now?: () => number;
+	/** Collect a finished run; the command closes the board and sends it. */
+	onCollect: (runId: string) => void;
+	/** Cancel a running run; the board stays open. */
+	onCancel: (runId: string) => void;
+	onClose: () => void;
+	requestRender: () => void;
+	viewportRows?: ViewportRowsSource;
+}
+
+/** The list/detail board for background subagent runs. */
+export class AgentsBoardComponent extends DockListScreen<BackgroundRun> {
+	constructor(private readonly board: AgentsBoardOptions) {
+		super({
+			theme: board.theme,
+			title: "Agents",
+			detailTitle: "Run",
+			emptyList: "No background subagents yet.",
+			emptyDetail: "(no output recorded)",
+			requestRender: board.requestRender,
+			onClose: board.onClose,
+			viewportRowsSource: board.viewportRows,
+		});
+	}
+
+	private get now(): number {
+		return (this.board.now ?? Date.now)();
+	}
+
+	/** `c` collects a finished run and `x` cancels a running one, in either mode. */
+	private act(key: string, run: BackgroundRun | undefined): boolean {
+		if (!run) return false;
+		if (key === "c" && canCollect(run)) {
+			this.board.onCollect(run.id);
+			return true;
+		}
+		if (key === "x" && run.status === "running") {
+			this.board.onCancel(run.id);
+			return true;
+		}
+		return false;
+	}
+
+	protected rows(): readonly BackgroundRun[] {
+		return this.board.runs();
+	}
+
+	protected idOf(run: BackgroundRun): string {
+		return run.id;
+	}
+
+	protected rowLine(run: BackgroundRun, width: number, selected: boolean): string {
+		const view = statusView(run.status);
+		const usage = run.usage ? formatUsageStats(run.usage) : "";
+		const trailing = [view.label, formatBackgroundDuration(run, this.now), usage].filter(Boolean).join(SEPARATORS.item);
+		return statusRow(this.theme, width, {
+			selected,
+			glyph: view.glyph,
+			glyphRole: view.role,
+			label: `${run.id} ${sanitizeLine(run.agent)}  ${taskLabel(run)}`,
+			labelRole: selected ? "accent" : "label",
+			trailing,
+		});
+	}
+
+	/** The board has never carried a focus block: the detail pane states the facts. */
+	protected detailBlock(): string[] {
+		return [];
+	}
+
+	protected summaryCells(rows: readonly BackgroundRun[]): string[] {
+		const running = rows.filter((run) => run.status === "running").length;
+		const cells = [paint(this.theme, "meta", `${rows.length} run${rows.length === 1 ? "" : "s"}`)];
+		if (running > 0) cells.push(paint(this.theme, "meta", `${running} running`));
+		return cells;
+	}
+
+	protected listHints(): ScreenHint[] {
+		const focused = this.focused;
+		const hints: ScreenHint[] = ["Esc close", { text: "Enter detail", color: "accent" }];
+		if (focused && canCollect(focused)) hints.push({ text: "c collect", color: "accent" });
+		if (focused?.status === "running") hints.push({ text: "x cancel", color: "warning" });
+		hints.push("↑/↓ select");
+		return hints;
+	}
+
+	protected detailHints(run: BackgroundRun | undefined): ScreenHint[] {
+		const hints: ScreenHint[] = ["Esc back"];
+		if (run && canCollect(run)) hints.push({ text: "c collect", color: "accent" });
+		if (run?.status === "running") hints.push({ text: "x cancel", color: "warning" });
+		hints.push("j/k scroll");
+		return hints;
+	}
+
+	protected detailFor(run: BackgroundRun): DetailContents {
+		return {
+			title: `${run.id} ${sanitizeLine(run.agent)}`,
+			subtitle: `${statusView(run.status).label}${SEPARATORS.item}${formatBackgroundDuration(run, this.now)}`,
+			// The key/value rows need the current width, so they are rebuilt per frame.
+			facts: (width) => detailRows(run, this.now, this.theme, width),
+			lines: outputLines(run),
+		};
+	}
+
+	/** The output a live run keeps producing; a removed run has none, which closes the pane. */
+	protected detailById(id: string): { lines: string[] } | undefined {
+		const run = this.rows().find((entry) => entry.id === id);
+		return run ? { lines: outputLines(run) } : undefined;
+	}
+
+	/** Re-read the pane on every frame: a child's output arrives without a poll. */
+	protected liveDetail(): boolean {
+		return true;
+	}
+
+	protected handleVerb(key: string, focused: BackgroundRun | undefined): void {
+		this.act(key, focused);
+	}
+
+	protected handleDetailVerb(key: string, run: BackgroundRun): boolean {
+		return this.act(key, run);
+	}
+}