@tshu-w/pi-agents 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+## [0.4.1] - 2026-11-04
+
+### Added
+
+- `pd main --name <name>` opens a main Agent per name, so that each channel can have its own.
+
+### Changed
+
+- Inputs answered by the same turn share one notification.
+
+## [0.4.0] - 2026-11-04
+
+### Added
+
+- `spawn` takes `disown`: a root Agent starts another root Agent it does not own, which replies with `send`.
+- A Program's notification carries the result's images.
+
+### Changed
+
+- **Breaking:** `wait` only waits, for Agents and background Programs, and returns how it ended; results always arrive as notifications, also while waiting. The `history` parameter is removed.
+- The notifications of what a `wait` waits for arrive together when it ends.
+- `pd main` opens the main Agent from any directory, and starts one in `~` if there is none; `/new` in it starts a new main Agent.
+
+## [0.3.0] - 2026-11-02
+
+### Added
+
+- `pd main` opens the main Agent: one Session you talk to, which hands your work to other Agents and reports back.
+
+### Changed
+
+- The task panel and `/tasks` show the same tree, including the Agents that Programs start.
+- `/tasks` lists only the running background Programs of other Agents.
+- The task panel shows a task's cost only once there is any.
+
+### Fixed
+
+- Under Pi 1.4.0, a Program starts at once even while background Programs wait on Agents.
+- The task viewer scrolls, and renders only what changed.
+- Terminal input that arrives just before detaching no longer leaks into the shell.
+- The workbench preview labels custom messages by their type.
+
+## [0.2.0] - 2026-10-15
+
+### Added
+
+- `pd -p`, `--mode json`, and `--mode rpc` run on the Session in its host, so several clients and an attached terminal can use one Session at once.
+- `/program <file>` runs a saved Program; `/tasks` opens background Programs.
+- `agent().send()` in Programs accepts a `timeout`.
+- Program results list Agents' `send()` calls and name the calls still running when the script returned.
+- `list` shows each Agent's latest request.
+- The panel shows how long each task has run and what its replies cost.
+- Agent messages queued in a Session are shown and kept; queued writes are labeled apart from steers.
+
+### Changed
+
+- `pd` and `pd --session-id` attach to a Session already running in a host and send it their messages.
+- After a turn is stopped, messages from other Agents are held as writes until the next input from its user or owner.
+- `wait` ends early when a steer arrives.
+- Stopping a Program no longer notifies its caller.
+- A detached Session exits after 10 idle minutes instead of 5.
+- The workbench has clearer session groups, better preview scrolling and layout, and a configurable detach key.
+
+### Fixed
+
+- Compatibility with Pi 1.2, including `program` reaching MCP tools without the `codemode` extension.
+- Hosted `pd -p` prints `/program` results and exits with 1 on a failed `/program` or a truncated reply, as Pi does.
+- Shutdown no longer waits indefinitely for Agents still loading, and Program cleanup waits for tool calls left running.
+- Messages to a Program's Agents go through their owner.
+- Timers, connections, and signal handlers no longer leak in the viewer and the host extension.
+- `pd` waits for a starting or exiting Pi instead of reporting the Session in use.
+
+## [0.1.1] - 2026-10-10
+
+### Fixed
+
+- Removing an idle Session that runs in a detached host quits it instead of refusing.
+- Previewing a Session in the workbench marks its latest turn as seen.
+
+## [0.1.0] - 2026-10-10
+
+Initial release.
+
+### Added
+
+- `agent` tool: start, message, wait for, list, and abort Agents that run in parallel in the background and notify their owner when done.
+- `program` tool: run JavaScript that composes tool calls and Agents, in the foreground or in the background.
+- Messaging between Agents, including root Agents in other Pi instances.
+- Task panel showing each Agent's and Program's live work; `/tasks` hides or shows it.
+- `/agents` opens an Agent in the tree to watch and talk to it.
+- `pd`: start Pi in a host that keeps the Session running after the terminal detaches (`Ctrl+Z`, `/detach`); `pd attach <session>` attaches again.
+- `pd agents` opens the workbench, which lists all Sessions with previews.

package/bin/pd.mjs

@@ -2,15 +2,16 @@
 // The `pd` command: runs Pi in a host, attaching this terminal to interactive Pi and connecting
 // non-interactive Pi to the hosted Session; `--no-session` and package commands run Pi directly.
 import { spawn } from 'node:child_process';
-import { accessSync, constants, readlinkSync, symlinkSync, unlinkSync } from 'node:fs';
+import { accessSync, constants, existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { pathToFileURL } from 'node:url';
 import { styleText } from 'node:util';
 import { attach, hostSessionFile, settledHosts, startHost } from '../src/host/client.mjs';
 import { detachKey, detachMatcher } from '../src/host/keys.mjs';
 import { discoverRoots, findRoot } from '../src/roots/discovery.mjs';
-import { defaultSessionDir, prepareDirectory, resolvePath, sessionDir, statePaths } from '../src/roots/paths.mjs';
+import { defaultSessionDir, resolvePath, sessionDir, statePaths } from '../src/roots/paths.mjs';
 import { piPackage } from '../src/pi.mjs';
 import { markedFiles } from '../src/daemon/sessions.mjs';
 import { argGroups } from '../src/host/rpc-client.mjs';
@@ -154,37 +155,26 @@ function headlessMode() {
   if (!interactive || parsed.print) return 'text';
 }
 
-/** Prepares the main Agent's directory, whose `AGENTS.md` links to the main Agent's instructions, and continues its Session there. */
+/** Opens the main Agent of the entry `--name` picks (default `main`), from any directory, or starts one in `~` if there is none. */
 async function openMain() {
-  await prepareDirectory(paths.main);
-  const link = join(paths.main, 'AGENTS.md');
-  const instructions = fileURLToPath(new URL('../src/main-agent.md', import.meta.url));
-  let target;
-  try { target = readlinkSync(link); }
-  catch (failure) {
-    // A file put in place of the link stays.
-    if (failure.code !== 'ENOENT' && failure.code !== 'EINVAL') throw failure;
-    target = failure.code === 'EINVAL' ? instructions : undefined;
+  const name = parseArgs(args.slice(1)).name ?? 'main';
+  // `--name` picks the entry, so it does not rename the Session.
+  const options = argGroups(parseArgs, args.slice(1)).filter(([option]) => !['--name', '-n'].includes(option)).flat();
+  let file;
+  // `main.json` maps entry names to Session files; an old one holds `{ sessionFile }` for `main`.
+  try {
+    const entries = JSON.parse(readFileSync(paths.mainSession, 'utf8'));
+    file = typeof entries.sessionFile === 'string' ? { main: entries.sessionFile }[name] : entries[name];
+  } catch (failure) { if (failure.code !== 'ENOENT') throw failure; }
+  // A main Agent without messages has no file yet, but its host may be running.
+  const holds = host => hostSessionFile(host) === file;
+  if (file && (existsSync(file) || (await settledHosts(paths, holds)).some(holds))) args = ['--session', file, ...options];
+  else {
+    process.chdir(homedir());
+    // These go first, as messages may follow `--`; with `=`, `--main` takes no other argument as its value.
+    args = [`--main=${name}`, '--name', name, ...options];
   }
-  // The link follows this copy of pi-agents; another `pd main` may be making it at the same time.
-  if (target !== instructions) {
-    try { if (target !== undefined) unlinkSync(link); }
-    catch (failure) { if (failure.code !== 'ENOENT') throw failure; }
-    try { symlinkSync(instructions, link); }
-    catch (failure) { if (failure.code !== 'EEXIST') throw failure; }
-  }
-  process.chdir(paths.main);
-  const options = args.slice(1);
-  // A running main Agent may have no file yet for `-c` to find.
-  const here = host => host.session?.cwd === process.cwd();
-  const running = (await settledHosts(paths, here)).filter(here);
-  args = running.length === 1 ? ['--session', hostSessionFile(running[0]), ...options] : ['-c', ...options];
   parsed = parseArgs(args);
-  // A new main Agent is named, so other Agents can address it; options go first, as messages may follow `--`.
-  if (!running.length && parsed.name === undefined && !(await recentSession())) {
-    args.unshift('--name', 'main');
-    parsed = parseArgs(args);
-  }
 }
 
 if (args[0] === 'main') await openMain();

package/docs/HOSTS.md

@@ -16,7 +16,7 @@ Files live in `${XDG_STATE_HOME:-~/.local/state}/pi/agents/`:
 
 - `workbench.json`: seen marks and which Sessions are listed.
 - `host.log`, `daemon.log`: logs.
-- `main/`: the main Agent's working directory. Its `AGENTS.md` links to the main Agent's instructions in pi-agents.
+- `main.json`: which Session is the main Agent of each entry name.
 
 Sockets and Session locks go in `$XDG_RUNTIME_DIR/pi-agents/`. macOS has no `XDG_RUNTIME_DIR`, so there they go in `runtime/` under the state directory.
 
@@ -36,7 +36,7 @@ pi install "$(npm root -g)/@tshu-w/pi-agents"
 - `pd [pi options]` starts Pi interactively in a new host and attaches the terminal. If the Session is already running in a host, `pd` attaches to it instead, sending it the messages as follow-ups and ignoring other options.
 - `pd agents` opens the workbench.
 - `pd attach <session>` attaches to a Session, starting it first if it is not running.
-- `pd main [pi options]` opens the main Agent, which hands work to other Agents: it runs `pd -c [pi options]` in `main/`, named `main`.
+- `pd main [--name <name>] [pi options]` opens the main Agent for `<name>` (default `main`), which hands work to other Agents, from any directory; `/new` in it starts a new one.
 - Non-interactive starts (`-p`, `--mode json`, `--mode rpc`, piped stdin) work as in Pi, on the Session in a host, so several of them and an attached terminal can use one Session at once. Their commands act on that Session, as `abort` stops whichever turn is running. Unlike Pi:
   - Dialogs are not sent to them. A dialog waits while a terminal is attached and is cancelled otherwise.
   - Extensions see interactive mode, so what an extension writes to stdout does not reach them; `/program` prints as with `pi -p`.

package/docs/PROGRAM.md

@@ -8,7 +8,7 @@ The `program` tool replaces Pi's `codemode` tool and keeps its script API, tool
 
 An Agent runs a **Program** with the `program` tool. That Agent is the Program's **caller**. The Program can call the caller's tools and create Agents.
 
-A Program runs in the **foreground** or the **background**. In the foreground, the tool call returns the Program's result. In the background, the tool call returns the Program's ID, and the caller gets the result with `wait`.
+A Program runs in the **foreground** or the **background**. In the foreground, the tool call returns the Program's result. In the background, the tool call returns the Program's ID, and the caller gets the result in a notification.
 
 A Program is shown by its short ID: the shortest prefix of its ID, at least 8 characters, that none of the caller's other Programs' IDs starts with. A target is an ID or a unique ID prefix.
 
@@ -23,11 +23,11 @@ A Program is `running` until it ends in one of three ways:
 ## 2. Operations
 
 - `run` runs a Program in the foreground or background, with an optional timeout.
-- `wait` waits for background Programs and returns their results.
+- `wait` waits for background Programs to end.
 - `list` lists the caller's background Programs.
 - `stop` stops a running Program.
 
-When a background Program ends and its caller is not waiting for it, the caller gets a notification, as in SPEC §5. A steer input ends `wait` early, as in SPEC §5.
+When a background Program ends, the caller gets a notification with the result, unless it stopped the Program. `wait` ends as in SPEC §5.
 
 ## 3. Program API
 
@@ -47,7 +47,7 @@ With `timeout`, an input that has not ended within that many seconds of `send()`
 
 When a Program ends, it cancels its unfinished tool calls and aborts its Agents' unfinished inputs, and waits for its Agents to go offline. It returns its result after cleanup. Work not stopped within the cleanup timeout is abandoned and may keep running; the Program's result and `stop` report it as an error, and the Program's state is unchanged.
 
-When the caller goes offline, its running Programs stop. Their results remain available when the caller is loaded again.
+When the caller goes offline, its running Programs stop, as if it stopped them.
 
 ## 5. Limits
 
@@ -61,7 +61,7 @@ An owned caller gives up its slot while a foreground Program runs or while it wa
 
 description:
 
-Run JavaScript that composes tool calls and Agents; only its output and return value reach the caller. `run` runs a Program in the foreground, or in the background with `background`; `wait` waits for background Programs and returns their results; `list` lists background Programs; `stop` stops a running Program. When a background Program ends while its caller is not waiting for it, the caller receives a notification; `wait` returns the result.
+Run JavaScript that composes tool calls and Agents; only its output and return value reach the caller. `run` runs a Program in the foreground, or in the background with `background`; `wait` waits for background Programs to end; `list` lists background Programs; `stop` stops a running Program. When a background Program ends, the caller receives a notification with the result.
 
 Program code is the body of an async function. It calls the caller's tools through `tools.*`, which excludes `program`, and creates Agents through `agent()`. These Agents belong to the Program, are isolated from other Agents, and go offline when it ends.
 
@@ -117,7 +117,7 @@ promptGuidelines:
 
 - Use `program(action='run', code=...)` to call tools or Agents several times without a model turn between the calls, for example to read many files, filter large tool output, fan out Agents, or loop until a condition holds.
 - Use `Promise.allSettled` for independent calls. Return only what the caller needs; use `text()` for progress worth reading.
-- Use `background=true` for long Programs, and `program(action='wait', ...)` when the next step depends on their results.
+- Use `background=true` for long Programs, and `program(action='wait', ...)` when your next step or answer depends on their results.
 
 parameters:
 
@@ -125,7 +125,7 @@ parameters:
 - `code`: JavaScript async-function body for `run`.
 - `background`: Whether `run` returns the Program ID at once (default: false).
 - `timeout`: Maximum seconds. For `run` (default: none), expiry stops the Program. For `wait` (default: 30, min: 10, max: 3600), expiry does not stop Programs.
-- `target`: Program ID or unique ID prefix for `wait` or `stop`. `wait` also accepts an array. When omitted for `wait`, selects running Programs and ended Programs whose result has not been returned.
+- `target`: Program ID or unique ID prefix for `wait` or `stop`. `wait` also accepts an array. When omitted for `wait`, selects running Programs.
 - `limit`: Maximum Programs returned by `list` (default: 20, max: 200).
 - `offset`: Number of Programs to skip for `list` (default: 0).
 
@@ -141,22 +141,13 @@ In these formats, `<id>` is the Program's short ID.
 Program <id> started.
 ```
 
-`wait` returns one block per result, followed by running Programs on timeout:
+`wait` returns as `agent` `wait` does (SPEC §6), naming the Programs still running:
 
 ```text
-<program-result id="<id>" status="<outcome>">
-<result>
-</program-result>
-
-Still running: <id>, ...
-```
-
-When a steer input ended the wait, the line of SPEC §6 follows.
-
-A single completed result, with nothing running, is returned alone. When there are no results or running Programs:
-
-```text
-No results.
+Wait completed.
+Wait timed out. Still running: <id>, ...
+Wait interrupted by a new message. Still running: <id>, ...
+Nothing to wait for.
 ```
 
 `list` returns one entry per background Program, newest first:
@@ -210,18 +201,16 @@ No Program matches "<target>". Use list to find Programs.
 
 truncation:
 
-`wait` text beyond Pi's output limits is truncated as in SPEC §6. `wait` adds results in order; the result that crosses the limit is truncated but keeps its closing tag, and later results are omitted. A truncated result counts as returned. Omitted results stay unreturned, and the text ends with:
-
-```text
-[Results omitted: <id>, ... Use wait with fewer targets.]
-```
+A notification's result beyond Pi's output limits is truncated as in SPEC §6 and keeps its closing tag.
 
 messages:
 
-A notification to the caller:
+A notification to the caller, followed by the result's images:
 
 ```text
-Program <id> <outcome>.
+<program-result id="<id>" status="<outcome>">
+<result>
+</program-result>
 ```
 
 ## 7. Human interface

package/docs/SPEC.md

@@ -6,7 +6,7 @@ Terms follow Pi's [Pi Durable specification](https://github.com/earendil-works/p
 
 ## 1. Semantic model
 
-An **Agent** is an addressable conversation with a stable identity. The Agent that spawns another Agent is its **owner**. A root Agent has no owner and is usually opened by a user. Ownership forms trees.
+An **Agent** is an addressable conversation with a stable identity. The Agent that spawns another Agent is its **owner**, unless it disowns it (§2.1). A root Agent has no owner. Ownership forms trees.
 
 An Agent is shown by its name and **short ID**: the shortest prefix of its ID, at least 8 characters, that no other Agent visible to the reader has. An address is an ID, a name, or a unique ID prefix, tried in that order.
 
@@ -24,6 +24,8 @@ An owner can **wait** for answers to the inputs it sends to its owned Agents.
 
 `spawn` creates a named, owned Agent and sends it a first input. It accepts an optional working directory, model, thinking level, and forked context, and returns the Agent's ID. Names are unique among siblings.
 
+With `disown`, a root Agent's `spawn` starts a root Agent instead, detached in a host (HOSTS §4).
+
 ### 2.2 send
 
 `send` sends a message to a visible Agent by address. An ambiguous or unknown address is rejected.
@@ -36,7 +38,7 @@ When the user of a root Agent clears its queued messages, messages from other Ag
 
 ### 2.3 wait
 
-`wait` returns results of inputs sent to owned Agents. It can target specific Agents and take a timeout.
+`wait` waits until owned Agents have finished the inputs sent to them. It can target specific Agents and take a timeout.
 
 ### 2.4 list
 
@@ -50,11 +52,11 @@ When the user of a root Agent clears its queued messages, messages from other Ag
 
 An Agent is `running` while a turn is in progress, `waiting` while its turn waits in `wait` (§4), `queued` while its next turn waits for a slot (§4), and `idle` otherwise. An Agent goes offline when its runtime unloads it; it stays `idle`.
 
-`send` returns once the recipient's runtime accepts the message, waking it if needed. Acceptance does not mean the recipient has handled it; a message not yet handled is lost if the recipient exits.
+`send` returns once the recipient's runtime accepts the message, waking it if needed. Acceptance does not mean the recipient has handled it (§10).
 
 An input to an offline Agent wakes it; a write to one is rejected.
 
-Owned Agents run independently of their owner's turns. When their owner goes offline, they go offline too, from the bottom of the tree up, and their unfinished inputs end as `aborted`. They return as `idle` when their owner is loaded again.
+Owned Agents run independently of their owner's turns and go offline with it (§10). They return as `idle` when their owner is loaded again.
 
 On abort or when going offline, work that has not stopped within a timeout is abandoned: it no longer counts as live work and may keep running until the process exits; the timeout is reported.
 
@@ -74,9 +76,9 @@ An input is outstanding from acceptance until its turn ends or it is withdrawn.
 
 An input sent to an owned Agent ends as `completed` when its turn answers it, `failed` when its turn fails, or `aborted` when it is aborted or withdrawn. Its result is the answer or the error. Only inputs from the owner have results; the recipient replies to other senders with `send`.
 
-`wait` returns unread results in order and marks them read. On timeout, it returns the results so far and names the Agents still pending. A steer input to the waiting Agent, from any sender, ends `wait` the same way; a write does not. It can also return read results again.
+When an input ends, its owner receives a notification carrying the result, unless the owner aborted it or is going offline. Inputs that a turn ends with the same outcome and result share one notification. The notification is an input delivered as `steer` (a write after the owner's turn is stopped, §2.2).
 
-When an input ends and its owner is not waiting for that Agent, the owner receives a notification, unless the owner aborted it. The notification is an input delivered as `steer` (a write after the owner's turn is stopped, §2.2), and it names the Agent and how the input ended. It does not include the result; the owner reads the result with `wait`.
+`wait` ends when the Agents it waits for have no pending inputs, when its timeout expires, or when a steer input arrives; a write does not end it. Their notifications are held until it ends, then delivered as one.
 
 A recipient sees each message with its sender's name and ID.
 
@@ -86,7 +88,7 @@ A recipient sees each message with its sender's name and ID.
 
 description:
 
-Create, message, and coordinate Agents. `spawn` creates an owned Agent and sends its first input; `send` sends an input or a write to a visible Agent; `wait` waits for owned Agents and returns unread results; `list` finds visible Agents; `abort` stops an owned Agent's current turn and queued inputs while keeping it available. When an owned Agent finishes an input while its owner is not waiting for it, the owner receives a notification naming the Agent and outcome; `wait` returns the result. Owned Agents under the same root share `${maxConcurrent}` execution slots and a limit of `${maxOutstanding}` inputs that have not ended. Inputs that start a new turn queue when all slots are busy; new inputs are rejected at the input limit.
+Create, message, and coordinate Agents. `spawn` creates an Agent and sends its first input; `send` sends an input or a write to a visible Agent; `wait` waits for owned Agents to finish; `list` finds visible Agents; `abort` stops an owned Agent's current turn and queued inputs while keeping it available. When an owned Agent finishes an input, its owner receives a notification with the result. Owned Agents under the same root share `${maxConcurrent}` execution slots and a limit of `${maxOutstanding}` inputs that have not ended. Inputs that start a new turn queue when all slots are busy; new inputs are rejected at the input limit.
 
 promptSnippet:
 
@@ -96,20 +98,20 @@ promptGuidelines:
 
 - Use `agent(action='spawn', name=..., message=...)` for concrete, bounded work with a clear expected result. Keep the first message self-contained; use `context='fork'` only when the Agent needs the caller's conversation.
 - For independent work, start the Agents before waiting and partition tasks into non-overlapping responsibilities.
-- Use `agent(action='wait', ...)` when the next step depends on Agent results. Prefer one longer wait over repeated short polling.
+- Use `agent(action='wait', ...)` when your next step or answer depends on Agent results. Prefer one longer wait over repeated short polling.
 
 parameters:
 
-- `action`: Operation and applicable parameters: `spawn(name, message, cwd?, context?, model?, thinkingLevel?)`, `send(target, message, deliverAs?)`, `wait(target?, history?, timeout?)`, `list(query?, state?, limit?, offset?)`, or `abort(target)`.
+- `action`: Operation and applicable parameters: `spawn(name, message, cwd?, context?, model?, thinkingLevel?, disown?)`, `send(target, message, deliverAs?)`, `wait(target?, timeout?)`, `list(query?, state?, limit?, offset?)`, or `abort(target)`.
 - `name`: Name of the new Agent for `spawn`; unique among the caller's Agents.
 - `message`: Non-empty text for `spawn` or `send`.
 - `cwd`: Working directory for `spawn` (default: the caller's current working directory).
 - `context`: Context for `spawn` (default: fresh). fresh starts without the caller's conversation; fork snapshots it.
 - `model`: Model for `spawn` as provider/modelId (default: the caller's model).
 - `thinkingLevel`: Thinking level for `spawn`: off, minimal, low, medium, high, xhigh, or max (default: the caller's level).
-- `target`: Agent ID, name, or unique ID prefix for `send`, `wait`, or `abort`. `wait` and `send` with `deliverAs='write'` also accept an array. When omitted for `wait`, selects all owned Agents with pending or unread results.
-- `deliverAs`: Delivery for `send` (default: followUp). followUp waits until the recipient's current turn ends; steer delivers after its current tool calls, before the next model call; write delivers like steer but never starts a turn and has no result.
-- `history`: Number of most recent read results to return again per selected Agent for `wait` (default: 0).
+- `disown`: For `spawn`, start a root Agent the caller does not own; it replies with send instead of returning a result (default: false).
+- `target`: Agent ID, name, or unique ID prefix for `send`, `wait`, or `abort`. `wait` and `send` with `deliverAs='write'` also accept an array. When omitted for `wait`, selects all owned Agents with pending inputs.
+- `deliverAs`: Delivery for `send` (default: followUp). followUp waits until the recipient's current turn ends; steer delivers after its current tool calls, before the next model call; write delivers like steer but does not wake an idle recipient and has no result.
 - `timeout`: Maximum seconds for `wait` (default: 30, min: 10, max: 3600). Timeout does not abort Agents.
 - `query`: Search query for `list`, matching ID, name, cwd, summaries, and user messages. Case-insensitive; spaces mean AND; `|` means OR.
 - `state`: State for `list`: running, waiting, queued, or idle.
@@ -148,37 +150,26 @@ followUp / steer: { id, queued }
 write:           { ids }
 ```
 
-`wait` returns one block per result, followed by pending Agents on timeout:
+`wait` returns how it ended; results arrive as notifications:
 
 ```text
-<agent-result name="<name>" id="<id>" status="<outcome>">
-<answer or error>
-</agent-result>
-
-Still pending: <name> (<id>), ...
+Wait completed.
+Wait timed out. Still pending: <name> (<id>), ...
+Wait interrupted by a new message. Still pending: <name> (<id>), ...
 ```
 
-When a steer input ended the wait, a line follows:
+When none of the selected Agents has pending inputs:
 
 ```text
-Still pending: <name> (<id>), ...
-Stopped waiting for a new message. Wait again to keep waiting.
-```
-
-A result returned again through `history` adds `history="true"`. A single unread completed result, with nothing pending, is returned as the answer alone. When there are no results or pending inputs:
-
-```text
-No results.
+Nothing to wait for.
 ```
 
 Details:
 
 ```text
-{ results: [{ id, name, state, history, result? }], pending: [{ id, name }], interrupted? }
+{ pending: [{ id, name }], timedOut?, interrupted? }
 ```
 
-`state` is the input outcome (§5); `history` marks a previously read result; `interrupted` is `true` when a steer input ended the wait.
-
 `list` returns one entry per Agent, followed by its latest request, if any, and its time. With a query, entries are ordered by their most recent match, and a matching summary or user message shows its latest excerpt instead:
 
 ```text
@@ -257,22 +248,20 @@ Agent <name> (<id>) did not stop within the timeout and may still be running.
 
 truncation:
 
-Text beyond Pi's output limits is truncated with Pi's native notice, and the full text is saved to a file whose path appears in the notice. `wait` adds results in order; the result that crosses the limit is truncated but keeps its closing tag, and later results are omitted. A truncated result counts as read. Omitted results stay unread, and the text ends with:
-
-```text
-[Results omitted: <name> (<id>), ... Use wait with fewer targets.]
-```
-
-Details retain metadata, `truncation`, and `fullOutputPath`. `wait.results[].result` contains only retained text and is absent for omitted results.
+Text beyond Pi's output limits is truncated with Pi's native notice, and the full text is saved to a file whose path appears in the notice. A notification's result is truncated the same way and keeps its closing tag. Details retain metadata, `truncation`, and `fullOutputPath`.
 
 messages:
 
 A notification to the owner:
 
 ```text
-Agent <name> (<id>) <outcome>.
+<agent-result name="<name>" id="<id>" status="<outcome>">
+<answer or error>
+</agent-result>
 ```
 
+A notification that a `wait` held holds one such block per result, separated by blank lines.
+
 A recipient sees each message in an `agent-message` element naming the sender. An input from a sender other than the owner also carries a note asking for a reply:
 
 ```text
@@ -326,7 +315,7 @@ A message from another Agent shows its sender after the label:
 <body>
 ```
 
-The user's input from the task viewer shows as a user message. `wait` shows each result with the first lines of its body; a Program's body starts at its output:
+The user's input from the task viewer shows as a user message. Notifications show each result with the first lines of its body; a Program's body starts at its output:
 
 ```text
 <name> (<id>)  <state>
@@ -373,3 +362,10 @@ Invalid settings produce a startup warning, and the defaults are used.
 Each Agent is a persistent Pi Session. A root Agent is an ordinary Session. An owned Agent is a child Session that records its owner and root, and runs in its owner's process.
 
 A delivered message enters the recipient's current branch. An offline root Agent is started in a host, detached, with its saved working directory and model and the current configuration (HOSTS §4). If a root process cannot finish cleanup within a grace period on exit, it is forcibly terminated. Before shutting down an idle Session, another extension can emit `busy:query` on `pi.events` with `{ busy: false }`; it is set to `true` while the tree has live work. One runtime uses a Session at a time. If a Session is occupied at startup, Pi reports it and exits.
+
+## 10. Limitations
+
+In this version:
+
+- A message accepted but not yet handled is lost if the recipient exits.
+- When an owner goes offline, its owned Agents go offline too, from the bottom of the tree up, and their unfinished inputs end as `aborted`, as do inputs unfinished when a process exits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tshu-w/pi-agents",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Multi-agent runtime for Pi: persistent async agents, dynamic workflows, and inter-agent messaging",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -16,7 +16,8 @@
   "files": [
     "bin",
     "src",
-    "docs"
+    "docs",
+    "CHANGELOG.md"
   ],
   "keywords": [
     "pi",