pi-ptc-subagents 0.1.2 → 1.0.0

package/CHANGELOG.md

@@ -5,6 +5,62 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] - 2026-09-24
+
+### Added
+
+- **Background dispatch: PTC programs can fan out to long-lived children.**
+  `pi.dispatch(...)` gains an opt-in `{ background: true }` path: instead of
+  awaiting the child, the binding returns a `DispatchHandle`
+  (`{ taskId, label, status: "running" }`) immediately, and a detached pump
+  drives a session-level `TaskRecord` through
+  `running / stopping / succeeded / failed / canceled / lost`, past the end of
+  the program and of the turn. The handle is a frozen spawn-time projection;
+  live state comes from three model-facing tools that stay on when PTC mode is
+  off (`/ptc off` only blocks new spawns):
+  - **`ptc_task_list`** — list this session's tasks (`status?`, `limit?`,
+    default 100, newest first);
+  - **`ptc_task_output`** — read a task's captured output (`taskId`,
+    `sinceBytes?`), tail-truncated to pi's 50 KB / 2000-line contract
+    (ADR-0015) with the full text written to a temp file;
+  - **`ptc_task_stop`** — ask a running task to stop (`taskId`, `reason?`,
+    default `"model stop"`), moving it `running -> stopping -> canceled`.
+
+  Lifecycle changes arrive as user-role `<bg-task-notification>` events under a
+  `<bg-task-notifications>` batch, cursor-delivered per subscriber with a
+  2048-byte inline-preview ceiling. Background tasks count against the existing
+  `dispatchConcurrency` (8) for their whole lifetime and share the
+  `maxDispatchDepth` (3) recursion bound. Existing foreground `pi.dispatch`
+  keeps its `DispatchResult` shape unchanged. ADR-0022.
+
+## [0.1.3] - 2026-09-23
+
+### Added
+
+- **PTC rows show what the program is doing while it runs.** Two partial-state
+  visuals on the `ptc_run_code` / `ptc_workflow` row, both absent until now:
+  - a **shimmer** on the call row — same text, one character at a time bright,
+    the highlight sweeping at 150ms — so a running row is distinguishable from a
+    settled one in a column (ADR-0020);
+  - a **sub-call tree** under it: one row per binding call the program made,
+    live from the moment the call is made, with its own five-state status
+    (`running` / `ok` / `error` / `cancelled` / `rejected`) and duration,
+    visible without expanding the row and capped at 32 with a `+N more` tail
+    (ADR-0021). A failed run shows the failure text but no sub-call tree: the
+    tool throws (pi's convention), and pi builds that error result with an empty
+    `details`, so the tracked calls are dropped with it.
+
+### Changed
+
+- **Build pipeline: minify + source-map exclusion.** `pnpm run build`
+  (`vp pack`) now produces minified `dist/*.js` (rolldown's built-in oxc
+  minifier; no new dependency). The npm tarball excludes `dist/**/*.map`
+  via the `package.json#files` whitelist — sourcemaps stay on disk for
+  local stack traces, but no longer ship. Tarball shrinks from 168.7 kB
+  packed / 548.6 kB unpacked (v0.1.2 baseline) to 40.5 kB / 113.6 kB
+  (−76% / −79%); `dist/*.js` total shrinks from 161,303 B to 53,959 B
+  (−66.5%). All 39 public exports retain their original names. ADR-0019.
+
 ## [0.1.2] - 2026-09-23
 
 ### Fixed

package/README.md

@@ -32,6 +32,9 @@ required — install it and the extension is on for the next pi startup.
 - `ptc_workflow` — structured variant with `meta` + plain-JSON `args`, plus the
   workflow helpers (`log`, `phase`, `parallel`, `pipeline`). There is no
   `agent()` helper on either surface.
+- `ptc_task_list` / `ptc_task_output` / `ptc_task_stop` — manage background
+  dispatches (see [Background dispatch](#background-dispatch)). They stay
+  available when PTC mode is off.
 
 Long output follows pi's own truncation contract ([ADR-0015](./docs/adr/0015-pi-truncation-contract.md)):
 
@@ -43,9 +46,11 @@ the next program can `tools.read`; the collapsed row then shows `truncated` in i
 
 PTC programs can spawn a fresh `pi` subprocess per call via the **`pi.dispatch(...)`** binding ([ADR-0016](./docs/adr/0016-ptc-dispatch-binding.md)). Use it to fan out to a specialist agent — the child subprocess loads the named agent's markdown from `~/.pi/agent/agents/<name>.md` (or `.pi/agents/<name>.md` for project-scope agents), runs that agent's tool set and system prompt in isolation, and returns a structured result.
 
+Bindings are reached through the one `tools` table — there is no `pi` global in the worker — so the binding named `pi.dispatch` is called as `tools["pi.dispatch"]({ … })` with a single object argument.
+
 ```ts
 // inside a ptc_run_code program
-const result = await pi.dispatch({
+const result = await tools["pi.dispatch"]({
   agent: "scout",
   task: "find all auth code in src/",
   cwd: process.cwd(),
@@ -62,8 +67,8 @@ const result = await pi.dispatch({
 ```ts
 const [read, scoutA, scoutB] = await Promise.all([
   tools.read({ path: "package.json" }),
-  pi.dispatch({ agent: "scout", task: "review auth" }),
-  pi.dispatch({ agent: "scout", task: "review db" }),
+  tools["pi.dispatch"]({ agent: "scout", task: "review auth" }),
+  tools["pi.dispatch"]({ agent: "scout", task: "review db" }),
 ]);
 ```
 
@@ -78,11 +83,36 @@ const [read, scoutA, scoutB] = await Promise.all([
 ```ts
 // in a hypothetical runner that wants to keep reads-only:
 createBuiltinBindings({ cwd: "/abs/path", names: ["read", "grep"] });
-// `pi.dispatch` is NOT in the resulting table.
+// `pi.dispatch` is NOT in the resulting `tools` table.
 ```
 
 **Not a subagent.** The term _subagent_ is overloaded in this field (DSH's `subagent` is a different thing; pi's `examples/extensions/subagent/` extension is also a different thing). pi-ptc uses _parallel binding_ and _concurrent tool call_ throughout; see `CONTEXT.md` for the canonical terms.
 
+### Background dispatch
+
+Foreground `pi.dispatch` blocks the program until the child exits. Pass `background: true` to spawn the child and return immediately with a `DispatchHandle` ([ADR-0022](./docs/adr/0022-background-dispatch.md)); the child outlives both the program and the turn:
+
+```ts
+// inside a ptc_run_code program — bindings are reached as tools["<name>"]
+const handle = await tools["pi.dispatch"]({
+  agent: "scout",
+  task: "audit the auth code",
+  background: true,
+  label: "auth audit", // defaults to task.slice(0, 64)
+});
+// handle: { taskId: "01J…", label: "auth audit", status: "running" }
+```
+
+(The binding's name is `pi.dispatch`; a program reaches it as `tools["pi.dispatch"]`.)
+
+A detached pump drives the task's lifecycle (`running` -> `succeeded` / `failed` / `canceled` / `lost`), and the model observes it with three always-on tools — they are not part of the PTC-mode loadout, so `/ptc off` (which only blocks new spawns) does not remove them:
+
+- `ptc_task_list({ status?, limit? })` — list this session's tasks, newest first (default limit 100).
+- `ptc_task_output({ taskId, sinceBytes? })` — read a task's captured output, tail-truncated to pi's 50 KB / 2000-line contract (ADR-0015).
+- `ptc_task_stop({ taskId, reason? })` — ask a running task to stop.
+
+Background tasks count against the same `dispatchConcurrency` (default 8) for their whole lifetime and share the `maxDispatchDepth` (default 3) recursion bound. A pre-spawn refusal (depth or concurrency cap, unknown agent) still comes back as the familiar `DispatchResult` with `status: "rejected"`. Full guide: [`docs/usage/bgdispatch.md`](./docs/usage/bgdispatch.md).
+
 ## TUI rendering
 
 Both tools register custom `renderCall` / `renderResult` hooks, so a PTC run reads as a program