@maxiaochao/pi-toolkit 0.12.2 → 0.13.0

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2026-10-20 - v0.13.0
+
+- background-tasks v0.1.0: bundle background shell tasks with runtime limits, bounded logs, completion notifications and /bg controls
+- Bundle and enable `@maxiaochao/pi-background-tasks` by default: managed shell jobs, Bash-aligned bounded output, completion followUps, `/bg` controls and an above-editor status widget. Keep the standalone package available as an alternative installation. The toolkit now requires Pi 1.3.0 or later.
+
 ## 2026-10-20 - v0.12.2
 
 - herdr-subagents v0.7.1: clarify Persona responsibilities and dispatch guidance

package/README.md

@@ -4,15 +4,15 @@ Personal Pi distribution that bundles focused extensions, agent skills, the Nigh
 
 ## Install
 
-Install the complete toolkit:
+Requires Pi **1.3.0 or later**. Install the complete toolkit:
 
 ```bash
 pi install npm:@maxiaochao/pi-toolkit
 ```
 
-That one install enables five child packages by default, because their source is embedded in the toolkit tarball: `pi-cache-export`, `pi-codex-edit`, `pi-herdr-subagents`, `pi-scheduler`, and `pi-worktree`.
+That one install enables six child packages by default, because their source is embedded in the toolkit tarball: `pi-cache-export`, `pi-codex-edit`, `pi-herdr-subagents`, `pi-scheduler`, `pi-background-tasks`, and `pi-worktree`.
 
-`pi-openai-account-pool` is not enabled and stays a separate install:
+`pi-openai-account-pool` is optional and stays a separate install:
 
 ```bash
 pi install npm:@maxiaochao/pi-openai-account-pool
@@ -34,6 +34,7 @@ Restart Pi after updating. `pi update --extensions` has the same effect when upd
 | [pi-codex-edit](packages/codex-edit/README.md) | Codex-harness `apply_patch` routing for selected GPT models | Yes | `pi install npm:@maxiaochao/pi-codex-edit` | `pi update npm:@maxiaochao/pi-codex-edit` | The core lies in the fact that the Codex model is naturally good at apply_patch, and the model is trained on this during training. However, hash-based in-context patch schemes have high token costs and complexity |
 | [pi-herdr-subagents](packages/herdr-subagents/README.md) | Visible Herdr Pi Agents coordinated by a small task state machine | Yes | `pi install npm:@maxiaochao/pi-herdr-subagents` | `pi update npm:@maxiaochao/pi-herdr-subagents` | I wanted simple serial or bounded-parallel dispatch while each task stays a real interactive Pi session in its own Herdr pane, and the main conversation only receives short summaries instead of every child's full transcript |
 | [pi-openai-account-pool](packages/openai-account-pool/README.md) | Several ChatGPT Plus/Pro logins behind `openai-codex`, switching accounts on a proven quota limit | No | `pi install npm:@maxiaochao/pi-openai-account-pool` | `pi update npm:@maxiaochao/pi-openai-account-pool` | One `/login openai-codex` credential overwrites the previous one, so hitting the subscription limit meant logging in again by hand mid-task; this keeps the accounts I authorized side by side and continues the same request on the next usable one |
+| [pi-background-tasks](packages/background-tasks/README.md) | Background shell jobs, bounded logs, completion notifications and a fixed status widget | Yes | `pi install npm:@maxiaochao/pi-background-tasks` | `pi update npm:@maxiaochao/pi-background-tasks` | Long builds and delayed log checks should keep running while the main agent does other work; these are local processes, not subagents |
 | [pi-scheduler](packages/scheduler/README.md) | Session-scoped interval prompts with Agent and `/schedule` controls | Yes | `pi install npm:@maxiaochao/pi-scheduler` | `pi update npm:@maxiaochao/pi-scheduler` | I don't recommend this, it's just that it sends messages to the main session at loop intervals |
 | [pi-worktree](packages/worktree/README.md) | Worktree CLI, current-session switching Extension, and agent skill | Yes | `pi install npm:@maxiaochao/pi-worktree` | `pi update npm:@maxiaochao/pi-worktree` | In addition to the basic worktree CLI + skill, what can be achieved is to directly switch to the worktree path in the main conversation to continue the task conversation after communicating the requirements in the main conversation |
 
@@ -41,7 +42,7 @@ Each child README owns its feature description, motivation or upstream alignment
 
 Herdr Subagents tasks require an explicit `agent` Persona; no default `worker` is selected. Choose `reviewer` for independent reviews of proposals, designs, documents, implementations, or analysis; `explorer` for codebase investigation; `worker` for file-changing work; and `analyst` for charter-defined agent-team roles. See [built-in Personas](packages/herdr-subagents/README.md#built-in-personas) for selection guidance and the distinction between parent-facing descriptions and child instructions. Personas can opt into local extension files or npm/git Pi packages through `extensions`. Set top-level `defaultExtensions` in `~/.pi/agent/herdr-subagents.json` (or project `.pi/herdr-subagents.json`) to share a fallback list; Persona-specific lists take precedence, and `[]` clears inherited sources. This uses native Pi package semantics: package-provided skills, prompt templates, and themes may also load, and `--no-skills` does not exclude explicitly selected package skills. See the [extension-source contract](packages/herdr-subagents/README.md#explicit-extension-sources-and-pi-packages) for precedence, isolation, and examples. The [real Herdr smoke test](packages/herdr-subagents/TESTING.md) preserves the configured analyst model and explicit authentication extensions while isolating unrelated settings.
 
-Multiple standalone children may be installed together. `pi-openai-account-pool` may also be installed alongside the complete toolkit because the toolkit does not embed it. Every other child in the table above is embedded, so a second install exposes the same resource twice.
+Multiple standalone children may be installed together. `pi-openai-account-pool` may also be installed alongside the complete toolkit because the toolkit does not embed it. Every other child in the table above, including `pi-background-tasks`, is embedded, so a second install exposes the same resource twice.
 
 Use `--local` with install or remove when the package declaration belongs to a project's `.pi/settings.json` rather than personal settings.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.12.2",
-  "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
+  "version": "0.13.0",
+  "description": "Personal pi coding agent toolkit: background tasks, scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
     "packages/*"
@@ -17,6 +17,7 @@
     "packages/codex-edit",
     "packages/herdr-subagents",
     "packages/scheduler",
+    "packages/background-tasks",
     "packages/worktree",
     "themes",
     "README.md",
@@ -36,6 +37,7 @@
       "./packages/codex-edit/extensions/codex-edit.ts",
       "./packages/herdr-subagents/extensions/herdr-subagents.ts",
       "./packages/scheduler/extensions/scheduler.ts",
+      "./packages/background-tasks/extensions/background-tasks.ts",
       "./packages/worktree/extensions/worktree.ts"
     ],
     "skills": [
@@ -51,7 +53,7 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": ">=1.3.0",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
   },
@@ -59,9 +61,9 @@
     "ws": "^8.19.0"
   },
   "scripts": {
-    "test": "node tests/package-layout.mjs && node tests/release-check.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/herdr-subagents test && npm --prefix packages/openai-account-pool test && npm --prefix packages/scheduler test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
+    "test": "node tests/package-layout.mjs && node tests/release-check.mjs && npm --prefix packages/todo test && npm --prefix packages/cache-export test && npm --prefix packages/codex-edit test && npm --prefix packages/herdr-subagents test && npm --prefix packages/openai-account-pool test && npm --prefix packages/scheduler test && npm --prefix packages/background-tasks test && npm --prefix packages/worktree test && node --experimental-strip-types extensions/btw/tests/history.mjs",
     "test:root": "node tests/package-layout.mjs && node tests/release-check.mjs && node --experimental-strip-types extensions/btw/tests/history.mjs",
-    "load-test": "pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/herdr-subagents/extensions/herdr-subagents.ts && pi -ne -e ./packages/scheduler/extensions/scheduler.ts && pi -ne -e ./packages/worktree/extensions/worktree.ts",
+    "load-test": "pi -ne -e ./packages/cache-export/extensions/cache-export.ts && pi -ne -e ./extensions/btw/index.ts && pi -ne -e ./packages/codex-edit/extensions/codex-edit.ts && pi -ne -e ./packages/herdr-subagents/extensions/herdr-subagents.ts && pi -ne -e ./packages/scheduler/extensions/scheduler.ts && pi -ne -e ./packages/background-tasks/extensions/background-tasks.ts && pi -ne -e ./packages/worktree/extensions/worktree.ts && npm --prefix packages/background-tasks run load-test -- --toolkit",
     "load-test:root": "pi -ne -e ./extensions/btw/index.ts",
     "eval:agents": "node evaluations/agents-md/run.mjs",
     "eval:agents:test": "node evaluations/agents-md/tests/run-tests.mjs",

package/packages/background-tasks/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 2026-10-20 - v0.1.0
+
+- bundle background shell tasks with runtime limits, bounded logs, completion notifications and /bg controls
+- Bundle and enable this package in the complete toolkit by default while retaining standalone installation as an alternative.
+
+- Add session-scoped background shell tasks with two concurrent slots, finite runtime limits, private bounded logs, Bash-aligned output views, and explicit cancellation.
+- Add completion followUps, `/bg` controls, and an above-editor widget with five-second finished rows. Reuse Pi's native shell backend without subagents or extra system-prompt rules.

package/packages/background-tasks/README.md

@@ -0,0 +1,114 @@
+# Pi Background Tasks
+
+Run shell commands in the background, then notify the main agent when they finish. These are local processes, not subagents.
+
+![Two real background jobs beside Scheduler](docs/screenshot.png)
+
+![Real Pi: start, cancel, completion and output](docs/demo.gif)
+
+## Why
+
+A command such as `sleep 60; python3 ...` can spend most of its time waiting to check a build log. A normal Bash call keeps waiting for that command. This package returns a task ID immediately so the main agent can do other work.
+
+It uses Pi's public `createLocalBashOperations()` backend for shell execution and process-group cancellation. It adds session ownership, bounded logs, status, and completion messages. It neither replaces Bash nor starts another model or Herdr pane.
+
+## Install and update
+
+Requires Pi **1.3.0 or later**.
+
+```bash
+pi install npm:@maxiaochao/pi-background-tasks
+pi update npm:@maxiaochao/pi-background-tasks
+```
+
+The complete `@maxiaochao/pi-toolkit` package **bundles and enables Background Tasks by default**. Choose either the toolkit or this standalone package; do not install both, because the tool and `/bg` command would be registered twice.
+
+## Agent tool
+
+```text
+background_task({ action: "start", command: "sleep 10; printf 'checks complete\\n'", description: "Delayed check", timeout: 120 })
+background_task({ action: "list" })
+background_task({ action: "output", id: "<returned-task-id>" })
+background_task({ action: "cancel", id: "<returned-task-id>" })
+```
+
+Start returns a running task's ID, log path and runtime limit, not the command's final output. An invalid start is rejected before execution. A later execution error becomes a failed task.
+
+- `command`: unchanged multi-line shell script; only for start.
+- `description`: optional display label, shortened to 200 characters.
+- `cwd`: optional directory, resolved relative to the current session directory.
+- `timeout`: integer seconds, **1800 by default**, from 1 through 7200. Zero and unlimited mode are rejected.
+- `id`: required for output and cancel. IDs belong only to their originating session.
+
+At most **two** tasks run at once. A third request fails immediately; it is not queued. Cancelling waits for process cleanup. Cancelling an already-ended task returns its status without another completion notification.
+
+List shows running tasks and the latest 20 finished tasks, with total and omitted counts. Older logs remain queryable by their IDs until the session closes.
+
+## User controls and status
+
+```text
+/bg
+/bg list
+/bg output <returned-task-id>
+/bg cancel <returned-task-id>
+```
+
+The commands inspect the same jobs without asking a model to perform the operation. Start a command through the agent tool; there is no second shell parser in `/bg`.
+
+A fixed widget **above the editor** shows each task's ID, status, elapsed time, runtime limit and description. It coexists with Scheduler, Todo, and Herdr widgets. Finished rows remain for five seconds; hiding a row does not delete its record. RPC gets a compact active count; non-interactive tools work without the widget.
+
+Completion, failure, cancellation, timeout and output-limit termination each send one `followUp` message to the main agent. It waits for the current turn, rather than interrupting it. Notifications contain metadata and a log path, **not the output body**. The agent can call output when it needs the details.
+
+## Output and safety limits
+
+| View | Limit |
+| --- | --- |
+| Model-visible output | Last 2000 lines or 50 KiB, whichever is reached first, like Bash |
+| Codemode's `structuredContent.output` | Up to 1 MiB of raw log bytes; larger logs keep their first and last 512 KiB with an omission marker |
+| Disk capture | 32 MiB per task, 256 MiB total per session |
+
+Display/program-view truncation does **not** stop the command. Disk limits **do** stop the overflowing task with `output_limit`; a full session budget rejects new starts. Nothing silently evicts old logs.
+
+Output includes a log path for further reads. `truncated` describes the program view, not disk capture. `task.capture_complete` is false while running or when log data was lost. The states are `running`, `succeeded`, `failed`, `cancelled`, `timed_out` and `output_limit`.
+
+Output streams to private temporary logs (directory 0700, files 0600 on Unix), with bounded memory and range-limited reads. Log errors stop the task and are reported. Stdout and stderr are merged; strict ordering across the two streams is not promised. Logs and command arguments can contain secrets: choose commands accordingly.
+
+## Codemode and Bash
+
+Use Bash when you need a command's result before proceeding. Codemode composes tool calls and filters their results; it does not itself own background jobs.
+
+Codemode can start a managed job and finish immediately:
+
+```javascript
+const started = await tools.background_task({
+  action: "start",
+  command: "sleep 10; printf 'done\\n'",
+  timeout: 120,
+});
+text(started.task);
+```
+
+Later scripts can list, read, or cancel the job. This does not hold a Codemode worker open. Merely starting an unawaited Bash call is different: Codemode cancels unfinished nested calls when its script ends.
+
+The tool description is compact. This package adds no `promptGuidelines` or extra global system-prompt rules.
+
+## Lifetime and scope
+
+- Exit, new/resumed/forked sessions and reload terminate active tasks, remove the widget and timers, and delete this package's captured logs. Commands' own files are left alone. History is not restored.
+- Aborting the main agent's current turn does not cancel an accepted job. Use cancel or `/bg cancel`.
+- Cancellation and runtime limits stop the native shell process group. Scripts must wait for their own work. Daemonized/detached commands (`nohup`, `setsid`, self-backgrounding processes), existing PID adoption, PTYs and interactive stdin are not supported.
+- This is a distinct **local execution** tool. A third-party sandbox or remote backend installed only for Bash does not automatically cover it. Enable it only where direct local shell execution is permitted.
+- It is not an OS sandbox: CPU/memory quotas, cleanup after SIGKILL/power loss, automatic retries, deadline renewal and persistence are out of scope. Native signal delivery and timers are best-effort.
+- A completion message already queued in Pi cannot be selectively withdrawn. Shutdown prevents new messages from old jobs; it cannot retract one already delivered to the host.
+
+## Remove
+
+For a standalone installation:
+
+```bash
+pi remove npm:@maxiaochao/pi-background-tasks
+```
+
+With the toolkit, disable its Background Tasks extension through `pi config` instead of removing a separate package.
+
+For deterministic, real-process, real-TUI and media checks, see [TESTING.md](TESTING.md).

package/packages/background-tasks/TESTING.md

@@ -0,0 +1,56 @@
+# Testing Pi Background Tasks
+
+Run from the repository root, with Node 22.19+ and Pi 1.3.0+ on PATH:
+
+```bash
+npm --prefix packages/background-tasks test
+npm --prefix packages/background-tasks run load-test
+npm pack ./packages/background-tasks --dry-run
+```
+
+Tests use Node's built-in test runner. They resolve host peers from the installed Pi rather than installing another copy. npm's workspace `node_modules/.bin` directories are excluded from this lookup because they can contain an older development Pi. Set `PI_TEST_BINARY=/absolute/path/to/pi` to choose a specific host.
+
+- `tasks.mjs`: fake execution and clock at the task-manager interface; immediate return, two slots, validation, timeout/cancel races, final failure, disk budgets, write errors, bounded history and shutdown.
+- `output.mjs`: compares both output views with the real host Bash tool. Covers line/byte limits, long lines, empty output, missing final newline, UTF-8 split across chunks, invalid UTF-8 and logs larger than 1 MiB.
+- `processes.mjs`: the native backend, a multi-line Python log check, non-blocking concurrency, PID-observed process-tree cleanup, silent busy-loop timeout and the default 32 MiB disk limit.
+- `extension.mjs`: real extension registration with fake execution/clock; schema errors, command parity, parent-signal independence, followUp, no output in notifications, above-editor placement, five-second retention, narrow/CJK rendering, coexistence and non-TUI modes.
+
+Load-test uses an isolated temporary agent directory, the production extension and an offline fixture provider. It does not access real provider credentials or alter the user's installed packages. From the workspace, `npm --prefix packages/background-tasks run load-test -- --toolkit` loads the complete toolkit directory through its manifest and verifies exactly one background-task tool; the root load-test runs this check too.
+
+## Real Pi TUI
+
+Requires Python 3 with the existing `pexpect` module; process fixtures use Bash, Python and `ps`. The current native-process/TUI suite is verified on Linux.
+
+```bash
+python3 packages/background-tasks/tests/tui-smoke.py .cache/verification/background-tui
+```
+
+This starts a real Pi in a PTY with the production extension, Scheduler, the built-in Codemode tool and a deterministic fixture provider. It checks two jobs, rejection of a third, Codemode completion while jobs remain alive, explicit output, cancellation, automatic main-agent followUp, reload/new/quit cleanup and log removal. No network model calls occur. Mocked UI tests separately verify the exact five-second boundary.
+
+Results and the actual ANSI stream are stored under the chosen evidence directory. Real screenshots require an isolated X11 terminal window, `gnome-terminal.real`, `xwininfo` and ImageMagick `import`:
+
+```bash
+gnome-terminal.real --wait --window --title='Pi Background Tasks Smoke' --geometry=140x42 -- \
+  env BG_SMOKE_RENDER=1 BG_SMOKE_CAPTURE=1 python3 \
+  "$PWD/packages/background-tasks/tests/tui-smoke.py" "$PWD/.cache/verification/background-tui-live"
+```
+
+It relays the real PTY output, captures only the test window, then closes it. Inspect the running, completed and history screenshots; check the widget has disappeared in the last one. Provider decisions are fixtures; tool execution, shell jobs, queues, TUI and cleanup are real.
+
+For the original delayed-check scenario, also run one 60-second sleep + Python heredoc check against temporary build log/exit files. The normal regression uses a one-second delay to keep the suite short.
+
+## Media and workspace checks
+
+```bash
+node scripts/capture-package-media.mjs background-tasks
+node tests/package-layout.mjs
+node tests/release-check.mjs
+npm test
+npm run load-test
+npm pack --dry-run
+git diff --check
+```
+
+The media command requires the real-TUI screenshot prerequisites above, plus Pillow. It reruns the real TUI and renders PNG/GIF from captured running/completed/history frames, not invented output. Inspect and click both links in `docs/package-media-gallery.html` with Chrome. The root tarball must include `packages/background-tasks/`, and the root default loadout must enable its extension exactly once. The standalone tarball remains independently loadable.
+
+Record actual checks and any missing prerequisites in `docs/verification.md`. A missing GUI, skipped browser check or unavailable Pi does not count as a successful end-to-end verification.

package/packages/background-tasks/extensions/background-tasks.ts

@@ -0,0 +1,200 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { createLocalBashOperations, type BashOperations, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { stripVTControlCharacters } from "node:util";
+import { Type } from "typebox";
+import { BackgroundTasks, errorText, summary, systemClock, type Clock, type TaskSnapshot } from "../src/background-tasks.ts";
+import { BackgroundWidget, FINISHED_VISIBLE_MS, WIDGET_KEY, duration, visibleTasks } from "../src/widget.ts";
+
+const actions = ["start", "list", "output", "cancel"] as const;
+type Action = typeof actions[number];
+interface Params {
+	action: Action;
+	command?: string;
+	description?: string;
+	cwd?: string;
+	timeout?: number;
+	id?: string;
+}
+const Parameters = Type.Object({
+	action: StringEnum(actions, { description: "start returns a task ID immediately; list checks tasks; output reads a bash-limited snapshot; cancel stops one task" }),
+	command: Type.Optional(Type.String({ description: "Shell command for start; may be multi-line. Runs locally, with stdin closed." })),
+	description: Type.Optional(Type.String({ description: "Short display label for start" })),
+	cwd: Type.Optional(Type.String({ description: "Working directory for start; defaults to the session directory. Relative paths resolve from it." })),
+	timeout: Type.Optional(Type.Integer({ minimum: 1, maximum: 7200, description: "Runtime limit for start, in seconds: default 1800 (30 minutes), maximum 7200 (2 hours); no unlimited mode" })),
+	id: Type.Optional(Type.String({ description: "Task ID for output or cancel; output shows the last 2000 lines or 50 KiB. Codemode receives up to 1 MiB, keeping head/tail if larger, plus a log path." })),
+}, { additionalProperties: false });
+const TaskSchema = Type.Object({
+	id: Type.String(), status: StringEnum(["running", "succeeded", "failed", "cancelled", "timed_out", "output_limit"] as const),
+	description: Type.String(), cwd: Type.String(), started_at: Type.Number(), ended_at: Type.Optional(Type.Number()),
+	timeout: Type.Number(), elapsed_seconds: Type.Number(), log_path: Type.String(), bytes: Type.Number(),
+	capture_complete: Type.Boolean(), exit_code: Type.Optional(Type.Number()), reason: Type.Optional(Type.String()),
+});
+const OutputSchema = Type.Object({
+	action: Type.Optional(StringEnum(actions)), task: Type.Optional(TaskSchema), tasks: Type.Optional(Type.Array(TaskSchema)),
+	running: Type.Optional(Type.Number()), total: Type.Optional(Type.Number()), omitted: Type.Optional(Type.Number()),
+	output: Type.Optional(Type.String()), truncated: Type.Optional(Type.Boolean()), full_output_path: Type.Optional(Type.String()),
+	error: Type.Optional(Type.String()),
+});
+
+function validate(params: Params): void {
+	if (!actions.includes(params.action)) throw new Error("action must be start, list, output, or cancel");
+	const allowed = params.action === "start" ? ["action", "command", "description", "cwd", "timeout"]
+		: params.action === "list" ? ["action"] : ["action", "id"];
+	if (Object.keys(params).some((key) => !allowed.includes(key))) throw new Error(`Unexpected parameter for ${params.action}`);
+	if (params.action === "start" && typeof params.command !== "string") throw new Error("start requires command");
+	if ((params.action === "output" || params.action === "cancel") && (typeof params.id !== "string" || !params.id)) throw new Error(`${params.action} requires id`);
+}
+
+function formatTask(task: TaskSnapshot): string {
+	return `${task.id} · ${task.status} · ${duration(task.elapsed_seconds)} / ${duration(task.timeout)}${task.exit_code === undefined ? "" : ` · exit ${task.exit_code}`} · ${JSON.stringify(task.description)}`;
+}
+function parseCommand(input: string): Params {
+	const parts = input.trim().split(/\s+/).filter(Boolean);
+	if (parts.length === 0 || (parts.length === 1 && parts[0] === "list")) return { action: "list" };
+	if (parts.length === 2 && (parts[0] === "output" || parts[0] === "cancel")) return { action: parts[0], id: parts[1] };
+	throw new Error("usage: /bg [list | output <id> | cancel <id>]");
+}
+
+export default function (pi: ExtensionAPI, dependencies: { operations?: BashOperations; clock?: Clock; logRoot?: string } = {}) {
+	const clock = dependencies.clock ?? systemClock;
+	let manager: BackgroundTasks | undefined;
+	let context: ExtensionContext | undefined;
+	let generation = 0;
+	let timer: unknown;
+	let mounted: { widget: BackgroundWidget; tui: { requestRender(): void } } | undefined;
+
+	const clearTimer = () => {
+		if (timer !== undefined) clock.clearTimeout(timer);
+		timer = undefined;
+	};
+	const refresh = () => {
+		if (!context?.hasUI || !manager) return;
+		const list = manager.list();
+		if (context.mode !== "tui") {
+			context.ui.setStatus(WIDGET_KEY, list.running ? `Background tasks ${list.running}/2` : undefined);
+			return;
+		}
+		const visible = visibleTasks(list.tasks, clock.now());
+		if (visible.length === 0) {
+			clearTimer();
+			if (mounted) {
+				context.ui.setWidget(WIDGET_KEY, undefined);
+				mounted.tui.requestRender();
+				mounted = undefined;
+			}
+			return;
+		}
+		if (mounted) {
+			mounted.widget.invalidate();
+			mounted.tui.requestRender();
+		} else {
+			context.ui.setWidget(WIDGET_KEY, (tui, theme) => {
+				const widget = new BackgroundWidget(() => manager?.list().tasks ?? [], clock, theme);
+				mounted = { widget, tui };
+				return widget;
+			}, { placement: "aboveEditor" });
+		}
+		if (timer === undefined) {
+			const delay = Math.min(1000, ...visible.filter((task) => task.ended_at !== undefined).map((task) => task.ended_at! + FINISHED_VISIBLE_MS - clock.now()));
+			timer = clock.setTimeout(() => { timer = undefined; refresh(); }, Math.max(1, delay));
+		}
+	};
+	const dispose = async () => {
+		generation++;
+		const previous = manager;
+		const previousContext = context;
+		manager = undefined;
+		context = undefined;
+		clearTimer();
+		try {
+			if (previousContext?.hasUI) {
+				previousContext.ui.setStatus(WIDGET_KEY, undefined);
+				if (previousContext.mode === "tui") previousContext.ui.setWidget(WIDGET_KEY, undefined);
+			}
+			mounted = undefined;
+		} finally { await previous?.shutdown(); }
+	};
+	pi.on("session_start", async (_event, ctx) => {
+		await dispose();
+		context = ctx;
+		const epoch = generation;
+		manager = new BackgroundTasks({
+			operations: dependencies.operations ?? createLocalBashOperations(), clock, logRoot: dependencies.logRoot,
+			onChange() { if (generation === epoch) refresh(); },
+			onComplete(task) {
+				if (generation !== epoch || !context) return;
+				pi.sendMessage({
+					customType: "background-task-finished", display: true, details: { task },
+					content: `[Background task finished]\n${formatTask(task)}${task.reason ? `\nReason: ${task.reason}` : ""}\nCaptured log: ${task.log_path}${task.capture_complete ? "" : "\nOutput capture is incomplete."}`,
+				}, { triggerTurn: true, deliverAs: "followUp" });
+			},
+		});
+	});
+	pi.on("session_shutdown", dispose);
+
+	const perform = async (params: Params, cwd: string) => {
+		validate(params);
+		if (!manager) throw new Error("Background tasks session is not ready");
+		if (params.action === "start") {
+			const task = manager.start({ command: params.command!, description: params.description, cwd: params.cwd, timeout: params.timeout }, cwd);
+			return {
+				text: `Started ${formatTask(task)}\nLog: ${task.log_path}\nAt most 2 tasks run at once. Tasks stop on session changes, reload, or exit; captured logs are then removed.`,
+				data: { action: params.action, task }, details: { action: params.action, task }, isError: false,
+			};
+		}
+		if (params.action === "list") {
+			const list = manager.list();
+			return {
+				text: list.total ? `${list.running}/2 running; ${list.total} total${list.omitted ? `; ${list.omitted} older tasks omitted` : ""}\n${list.tasks.map(formatTask).join("\n")}` : "No background tasks in this session.",
+				data: { action: params.action, ...list }, details: { action: params.action, ...list }, isError: false,
+			};
+		}
+		if (params.action === "cancel") {
+			const task = await manager.cancel(params.id!);
+			return { text: formatTask(task), data: { action: params.action, task }, details: { action: params.action, task }, isError: false };
+		}
+		const { text, output, truncated, truncation, ...task } = manager.output(params.id!);
+		const capturedText = task.capture_complete ? text : text.replace("Full output:", "Captured output:");
+		return {
+			text: `${formatTask(task)}\n[Untrusted shell output${task.status === "running" ? "; running snapshot" : ""}]\n${capturedText}\nCaptured log: ${task.log_path}${task.capture_complete ? "" : "\nCapture incomplete (task still running or output was lost)."}`,
+			data: { action: params.action, task, output, truncated, full_output_path: task.log_path },
+			details: { action: params.action, task, truncation },
+			isError: ["failed", "timed_out", "output_limit"].includes(task.status),
+		};
+	};
+
+	pi.registerTool({
+		name: "background_task", label: "Background task",
+		description: "Start shell commands as background tasks and return task IDs immediately. Supports status, output, and cancellation; notifies the main agent on completion.",
+		parameters: Parameters, outputSchema: OutputSchema,
+		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			try {
+				if (signal?.aborted) throw new Error("Tool call aborted before task acceptance");
+				const result = await perform(params, ctx?.cwd ?? context?.cwd ?? process.cwd());
+				return { content: [{ type: "text" as const, text: result.text }], structuredContent: result.data, details: result.details, isError: result.isError };
+			} catch (error) {
+				const message = errorText(error);
+				return { content: [{ type: "text" as const, text: `Error: ${message}` }], structuredContent: { error: message }, details: { error: message }, isError: true };
+			}
+		},
+		renderCall(args, theme) {
+			return new Text(`${theme.fg("toolTitle", theme.bold("background_task "))}${theme.fg("muted", summary(String(args.action ?? "")))}`, 0, 0);
+		},
+		renderResult(result, _options, theme) {
+			const block = result.content[0];
+			const text = block?.type === "text" ? stripVTControlCharacters(block.text).replace(/[\x00-\x08\x0b-\x1f\x7f\uFFF9-\uFFFB]/g, "") : "";
+			return new Text(theme.fg(result.isError ? "error" : "muted", text), 0, 0);
+		},
+	});
+	pi.registerCommand("bg", {
+		description: "List background shell tasks, read output, or cancel a task",
+		handler: async (args, ctx) => {
+			try {
+				const result = await perform(parseCommand(args), ctx.cwd);
+				pi.sendMessage({ customType: "background-task-inspect", content: result.text, display: true, details: result.details }, { triggerTurn: false });
+			} catch (error) { ctx.ui.notify(errorText(error), "error"); }
+		},
+	});
+}

package/packages/background-tasks/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@maxiaochao/pi-background-tasks",
+  "version": "0.1.0",
+  "description": "Session-scoped background shell tasks with completion notifications for Pi.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "background-tasks"
+  ],
+  "files": [
+    "extensions",
+    "src",
+    "tests",
+    "docs",
+    "README.md",
+    "TESTING.md",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
+    "directory": "packages/background-tasks"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/background-tasks.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": ">=1.3.0",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --import ./tests/runtime.mjs --test tests/tasks.mjs tests/output.mjs tests/processes.mjs tests/extension.mjs",
+    "load-test": "node --experimental-strip-types tests/load.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}