@tshu-w/pi-agents 0.2.0 → 0.2.2

package/bin/pd.mjs

@@ -7,12 +7,13 @@ import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { styleText } from 'node:util';
-import { attach, settledHosts, startHost } from '../src/host/client.mjs';
+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 { agentDir, configuredSessionDir, defaultSessionDir, 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';
 
 const real = process.env.PATH.split(':').map(dir => join(dir, 'pi')).find(file => {
   try { accessSync(file, constants.X_OK); return true; } catch { return false; }
@@ -23,9 +24,13 @@ if (!real) {
 }
 const args = process.argv.slice(2);
 const paths = statePaths();
+const dist = file => import(pathToFileURL(join(piPackage(real), 'dist', file)).href);
+// Pi's own parsing, so that `pd` reads every argument as `pi` does.
+const { parseArgs } = await dist('cli/args.js');
+const { ENV_SESSION_DIR, getAgentDir } = await dist('config.js');
+const parsed = parseArgs(args);
 
 const COMMANDS = new Set(['install', 'remove', 'uninstall', 'update', 'list', 'config', 'auth', 'mcp']);
-const DIRECT_FLAGS = new Set(['-h', '--help', '-v', '--version', '--export', '--list-models', '--no-session']);
 
 function runDirectly() {
   const child = spawn(real, args, { stdio: 'inherit' });
@@ -44,20 +49,12 @@ function error(text) {
   return styleText('red', text, { stream: process.stderr });
 }
 
-function option(name, alias) {
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--') return;
-    if (args[i] === name || args[i] === alias) return args[i + 1] ?? '';
-    if (args[i].startsWith(`${name}=`)) return args[i].slice(name.length + 1);
-  }
-}
-
 
 /** Attaches the terminal to the host at `socket`; `send`, if given, sends messages once attached, and its error is reported once detached. */
 async function attachAndReport(socket, send) {
   const tui = await import(pathToFileURL(createRequire(join(piPackage(real), 'package.json')).resolve('@earendil-works/pi-tui')).href);
   let sent;
-  const result = await attach(socket, { isDetach: detachMatcher(tui, detachKey(agentDir())), onAttach: () => { sent = send?.(); } });
+  const result = await attach(socket, { isDetach: detachMatcher(tui, detachKey(getAgentDir())), onAttach: () => { sent = send?.(); } });
   const failure = await sent;
   if (failure) process.stderr.write(`${error(failure)}\n`);
   const id = result.session?.id;
@@ -74,31 +71,30 @@ async function attachAndReport(socket, send) {
 /** The running host already holding the Session that `--session`, `--session-id`, or `-c` would open. */
 async function runningTarget() {
   let running;
-  const session = option('--session');
-  const sessionId = option('--session-id');
+  const { session, sessionId } = parsed;
   if (session) {
     const file = resolve(session);
-    running = host => host.session && (host.session.id.startsWith(session) || host.session.file === file);
-  } else if (sessionId && option('--fork') === undefined) {
+    running = host => host.session && (host.session.id.startsWith(session) || hostSessionFile(host) === file);
+  } else if (sessionId && parsed.fork === undefined) {
     // With `--fork`, the ID names a new Session.
     const file = await sessionById(sessionId);
     // A Session without messages has no file yet; its host reports where it will be.
-    const directory = sessionDirOption() ?? defaultSessionDir(process.cwd());
+    const directory = await sessionDirOption() ?? defaultSessionDir(process.cwd(), getAgentDir());
     running = host => host.session && (file
-      ? host.session.file === file
-      : host.session.id === sessionId && dirname(host.session.file) === directory && host.session.cwd === process.cwd());
-  } else if (args.includes('-c') || args.includes('--continue')) {
+      ? hostSessionFile(host) === file
+      : host.session.id === sessionId && dirname(hostSessionFile(host)) === directory && host.session.cwd === process.cwd());
+  } else if (parsed.continue) {
     const file = await recentSession();
-    if (file) running = host => host.session?.file === file;
+    if (file) running = host => hostSessionFile(host) === file;
   }
   return running && (await settledHosts(paths, running)).find(running);
 }
 
 /** The Session `-c` continues, chosen by Pi's own `continueRecent` rules. */
 async function recentSession() {
-  const { findMostRecentSession } = await import(pathToFileURL(join(piPackage(real), 'dist/core/session-manager.js')).href);
-  const configured = sessionDirOption();
-  const fallback = defaultSessionDir(process.cwd());
+  const { findMostRecentSession } = await dist('core/session-manager.js');
+  const configured = await sessionDirOption();
+  const fallback = defaultSessionDir(process.cwd(), getAgentDir());
   const directory = configured ?? fallback;
   // A configured directory may hold other cwds' Sessions.
   return findMostRecentSession(directory, directory === fallback ? undefined : process.cwd()) ?? undefined;
@@ -106,13 +102,14 @@ async function recentSession() {
 
 /** The Session `--session-id` would open, found by Pi's own rules, if it exists. */
 async function sessionById(id) {
-  const { SessionManager } = await import(pathToFileURL(join(piPackage(real), 'dist/core/session-manager.js')).href);
-  return SessionManager.findById(process.cwd(), id, sessionDirOption());
+  const { SessionManager } = await dist('core/session-manager.js');
+  return SessionManager.findById(process.cwd(), id, await sessionDirOption());
 }
 
-function sessionDirOption() {
-  const flag = option('--session-dir');
-  return flag ? resolvePath(flag) : configuredSessionDir();
+/** The session directory configured for Pi in this cwd, as Pi resolves it: `--session-dir`, its environment variable, then its settings. */
+async function sessionDirOption() {
+  const configured = parsed.sessionDir || process.env[ENV_SESSION_DIR] || (await dist('core/settings-manager.js')).SettingsManager.create(process.cwd(), getAgentDir()).getSessionDir();
+  return configured ? resolvePath(configured) : undefined;
 }
 
 async function attachCommand(query) {
@@ -147,16 +144,14 @@ async function attachCommand(query) {
 
 /** Warns about the options a running Session does not apply. */
 function warnIgnored(options) {
-  const ignored = options.filter((arg, i) => !['--session', '--session-id', '--session-dir', '-c', '--continue'].includes(arg)
-    && !arg.startsWith('--session=') && !arg.startsWith('--session-id=') && !['--session', '--session-id', '--session-dir'].includes(options[i - 1]));
+  const ignored = argGroups(parseArgs, options).filter(([option]) => !['--session', '--session-id', '--session-dir', '-c', '--continue'].includes(option)).flat();
   if (ignored.length) process.stderr.write(`${styleText('yellow', `The Session is already running; using it without applying: ${ignored.join(' ')}`, { stream: process.stderr })}\n`);
 }
 
 /** Pi's mode for `args` when it is not interactive: 'text', 'json', or 'rpc'. */
 function headlessMode() {
-  const mode = option('--mode');
-  if (mode === 'json' || mode === 'rpc') return mode;
-  if (!interactive || args.includes('-p') || args.includes('--print')) return 'text';
+  if (parsed.mode === 'json' || parsed.mode === 'rpc') return parsed.mode;
+  if (!interactive || parsed.print) return 'text';
 }
 
 const interactive = process.stdin.isTTY && process.stdout.isTTY;
@@ -166,7 +161,9 @@ else if (args[0] === 'agents' && interactive) {
   await workbench({ pi: real, paths, sessionDir: sessionDir() });
   process.exit(0);
 }
-else if (COMMANDS.has(args[0]) || args.some(arg => DIRECT_FLAGS.has(arg.split('=')[0]))) runDirectly();
+else if (COMMANDS.has(args[0]) || parsed.help || parsed.version || parsed.export !== undefined || parsed.listModels !== undefined || parsed.noSession) {
+  runDirectly();
+}
 else if (headlessMode()) {
   const { runHeadless } = await import('../src/host/rpc-client.mjs');
   await runHeadless({ pi: real, paths, args, mode: headlessMode(), findRunning: runningTarget, warnIgnored });

package/docs/HOSTS.md

@@ -2,169 +2,105 @@
 
 ## 1. Overview
 
-`pd` runs each Pi Session in a host of its own, so the Session keeps running
-after its terminal closes, and terminals, scripts, and other programs can use
-it at once. The workbench, opened with `pd agents`, shows the user's root
-Sessions in one terminal view: from it the user opens a Session, reads its
-latest result, or sends it a message.
+`pd` runs each Pi Session in a host of its own, so the Session keeps running after its terminal closes, and terminals, scripts, and other programs can use it at once. The workbench, opened with `pd agents`, shows the user's root Sessions in one terminal view: from it the user opens a Session, reads its latest result, or sends it a message.
 
 Three kinds of process take part:
 
-- **Host**: one per Session. It runs Pi's full TUI in a pseudo-terminal and
-  relays it to whichever terminal is attached.
-- **Daemon**: one per user. It tracks Sessions, delivers messages, and starts
-  hosts.
+- **Host**: one per Session. It runs Pi's full TUI in a pseudo-terminal and relays it to whichever terminal is attached.
+- **Daemon**: one per user. It tracks Sessions, delivers messages, and starts hosts.
 - **Workbench**: the daemon's terminal view, opened with `pd agents`.
 
-Every running root Session reports its state to the daemon. The daemon starts
-when a Session or the workbench first needs it, and exits soon after its last
-connection closes.
+Every running root Session reports its state to the daemon. The daemon starts when a Session or the workbench first needs it, and exits soon after its last connection closes.
 
 Files live in `${XDG_STATE_HOME:-~/.local/state}/pi/agents/`:
 
 - `workbench.json`: seen marks and which Sessions are listed.
 - `host.log`, `daemon.log`: logs.
 
-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.
+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.
 
 ## 2. Setup
 
-Install with npm to get the `pd` command, also named `pi-agents`, then have Pi
-load the extension from the same copy, so the command and the extension are
-always the same version:
+Install with npm to get the `pd` command, also named `pi-agents`, then have Pi load the extension from the same copy, so the command and the extension are always the same version:
 
-    npm install -g @tshu-w/pi-agents
-    pi install "$(npm root -g)/@tshu-w/pi-agents"
+```sh
+npm install -g @tshu-w/pi-agents
+pi install "$(npm root -g)/@tshu-w/pi-agents"
+```
 
-`pd` runs whichever `pi` is on `PATH`. Sessions started with plain `pi` also
-load the extension, but run outside hosts and end with their terminal.
+`pd` runs whichever `pi` is on `PATH`. Sessions started with plain `pi` also load the extension, but run outside hosts and end with their terminal.
 
 ## 3. Commands
 
-- `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 [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.
-- 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`.
-  - `new_session`, `switch_session`, `fork`, and `clone` move only the caller
-    to the other Session.
-  - `-p` and `--mode json` wait until the Session is idle, then run their
-    messages back to back. Their output covers their own turns, including
-    input other clients add to them.
-  - `SIGINT`, `SIGTERM`, or `SIGHUP` (as from Ctrl+C, `kill`, or a closed
-    terminal) makes `-p` and `--mode json` withdraw their prompts that have
-    not started and stop their running turn, including input other clients
-    added to it. Killed with `SIGKILL`, they leave their turn running.
-  - An RPC client that ends leaves its turn running. One whose Session stops
-    opens it again; requests awaiting a response then fail.
-- `--no-session` starts and package commands (`pd install`, `pd update`, ...)
-  run Pi directly.
-
-A host keeps the options and environment of the process that started it, as
-Pi reads them only at startup.
-
-A Session running outside a host still appears in the workbench, but can be
-attached only after it exits.
+- `pd attach <session>` attaches to a Session, starting it first if it is not running.
+- 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`.
+  - `new_session`, `switch_session`, `fork`, and `clone` move only the caller to the other Session.
+  - `-p` and `--mode json` wait until the Session is idle, then run their messages back to back. Their output covers their own turns, including input other clients add to them.
+  - `SIGINT`, `SIGTERM`, or `SIGHUP` (as from Ctrl+C, `kill`, or a closed terminal) makes `-p` and `--mode json` withdraw their prompts that have not started and stop their running turn, including input other clients added to it. Killed with `SIGKILL`, they leave their turn running.
+  - An RPC client that ends leaves its turn running. One whose Session stops opens it again; requests awaiting a response then fail.
+- `--no-session` starts and package commands (`pd install`, `pd update`, ...) run Pi directly.
+
+A host keeps the options and environment of the process that started it, as Pi reads them only at startup.
+
+A Session running outside a host still appears in the workbench, but can be attached only after it exits.
 
 ## 4. Attach and detach
 
-Only one terminal is attached at a time. A new terminal takes over, and the
-previous one is told how to reattach.
+Only one terminal is attached at a time. A new terminal takes over, and the previous one is told how to reattach.
 
-On attach, the host restores Pi's screen and the terminal modes Pi has set.
-Pi detects the colors and keyboard protocol of the first terminal that
-attaches, as it would without a host.
+On attach, the host restores Pi's screen and the terminal modes Pi has set. Pi detects the colors and keyboard protocol of the first terminal that attaches, as it would without a host.
 
-Closing the window, pressing `Ctrl+Z` (the `pi-agents.detach` keybinding), or
-running `/detach` detaches. The Session keeps running, and the terminal prints:
+Closing the window, pressing `Ctrl+Z` (`pi-agents.detach`), or running `/detach` detaches. The Session keeps running, and the terminal prints:
 
-    Pi keeps running. To reattach: pd attach <session>
+```text
+Pi keeps running. To reattach: pd attach <session>
+```
 
 A host disables Pi's suspend.
 
-A detached Session exits after 10 minutes with no live work in its tree and no
-`pd --mode rpc` connected. A message to a Session that is not running starts it
-in a host, detached.
+A detached Session exits after 10 minutes with no live work in its tree and no `pd --mode rpc` connected. A message to a Session that is not running starts it in a host, detached.
 
 ## 5. Workbench
 
-The list shows running Sessions, Sessions that ran without a terminal (started
-here, woken by a message, or detached), Sessions opened here, and Sessions
-with an unseen turn. Older Sessions are reached with `/resume`.
+The list shows running Sessions, Sessions that ran without a terminal (started here, woken by a message, or detached), Sessions opened here, and Sessions with an unseen turn. Older Sessions are reached with `/resume`.
 
-Each row shows a root Session's name and what it did last. The name is the
-Session name, or else the first line of its first message. While the Session
-works, the row shows the running tool; otherwise, the start of its last reply.
-Running owned Agents and Programs are counted, as in `3 agents running`.
+Each row shows a root Session's name and what it did last. The name is the Session name, or else the first line of its first message. While the Session works, the row shows the running tool; otherwise, the start of its last reply. Running owned Agents and Programs are counted, as in `3 agents running`.
 
 Rows are grouped by state, newest first in each group:
 
-- **Needs attention**: a dialog waiting for the user, or a finished turn the user
-  has not seen. A turn that failed after Pi's retries, or a host that exited
-  abnormally, is marked failed.
+- **Needs attention**: a dialog waiting for the user, or a finished turn the user has not seen. A turn that failed after Pi's retries, or a host that exited abnormally, is marked failed.
 - **Working**: the Session or its tree has live work.
 - **Completed**: everything else.
 
-While a Session works, its icon spins. Otherwise the shape tells whether Pi is
-still running (`●`) or has exited (`○`), and the color marks a finished (green)
-or failed (red) turn, or a dialog waiting for the user (yellow). The header
-shows Pi's logo, the size of each group, and key hints.
+While a Session works, its icon spins. Otherwise the shape tells whether Pi is still running (`●`) or has exited (`○`), and the color marks a finished (green) or failed (red) turn, or a dialog waiting for the user (yellow). The header shows Pi's logo, the size of each group, and key hints.
 
-A turn counts as seen once it has been shown in an attached terminal or a
-preview. Sessions
-from before the workbench start out seen. A Session that holds its lock but is
-not reporting to the daemon, as while its Pi exits, shows as unknown (`?`).
+A turn counts as seen once it has been shown in an attached terminal or a preview. Sessions from before the workbench start out seen. A Session that holds its lock but is not reporting to the daemon, as while its Pi exits, shows as unknown (`?`).
 
 Keys:
 
-- `Enter` attaches; detaching returns here.
-- `Space` previews the selected Session below the list: the conversation
-  since the last compaction, with thinking left out and each run of tool
-  calls folded to one line, such as `... (6 tool calls: bash, read, edit)`.
-  The preview follows the Session as it works.
-  The input keeps `@<session>` at its start, so a message goes to the
-  previewed Session. In the preview:
-  - `Enter` sends a typed message; with none typed, it attaches.
-  - `Ctrl+O` (`app.tools.expand`) attaches.
-  - It scrolls as fullscreen mode does; with no message typed, `↑`/`↓`
-    scroll too.
-  - `Esc` clears a typed message; with none typed, it closes the preview.
-  - `Ctrl+Z` closes the preview.
+- `Enter` (`tui.select.confirm`) attaches; detaching returns here.
+- `Space` previews the selected Session below the list: the conversation since the last compaction, with thinking left out, and each run of tool calls, branch summary, and custom message folded to one line, such as `... (6 tool calls: bash, read, edit)`. The preview follows the Session as it works. The input keeps `@<session>` at its start, so a message goes to the previewed Session. In the preview:
+  - With no message typed, `Enter` attaches, as `Ctrl+O` (`app.tools.expand`) always does.
+  - It scrolls as fullscreen mode does; with no message typed, `↑`/`↓` (`tui.select.up`/`tui.select.down`) scroll too.
+  - `Esc` (`tui.select.cancel`) clears a typed message; with none typed, it or `Space` closes the preview, as `Ctrl+Z` always does.
 - `Ctrl+X` stops the current turn, as `app.interrupt` does.
-- `Ctrl+D` removes the selected Session from the list. Its file stays, and
-  `/resume` brings it back. An idle Session in a host that no terminal is
-  attached to quits first; any other running Session must quit itself.
-- `Ctrl+Z` (`pi-agents.detach`) exits the workbench, as detaching leaves a
-  Session; every Session keeps running.
+- `Ctrl+D` (`app.session.delete`) removes the selected Session from the list. Its file stays, and `/resume` brings it back. An idle Session in a host that no terminal is attached to quits first; any other running Session must quit itself.
+- `Ctrl+Z` (`pi-agents.detach`) exits the workbench, as detaching leaves a Session; every Session keeps running.
 
 The input at the bottom:
 
-- `@` on an empty input opens Pi's session picker. The chosen Session is
-  selected in the list, and the input starts with `@<session>`; the text after
-  it goes to that Session as a user message. After `/`, Tab completes a
-  command.
-- `/resume` opens Pi's session picker over all directories, newest first, and
-  attaches the chosen Session. `Ctrl+D` in the picker deletes a Session file.
-- `/quit` exits the workbench, as do `Esc` and `Ctrl+C` twice on an empty
-  input.
-- Any other text starts a new Session in the current directory with Pi's
-  default settings, detached.
+- `@` on an empty input opens Pi's session picker. The chosen Session is selected in the list, and the input starts with `@<session>`; the text after it goes to that Session as a user message.
+- `/resume` opens Pi's session picker over all directories, newest first, and attaches the chosen Session.
+- `/quit` exits the workbench, as do `Esc` and `Ctrl+C` (`app.clear`) twice on an empty input.
+- Any other text starts a new Session in the current directory with Pi's default settings, detached.
 
 ## 6. Upgrades
 
-A host keeps running the version it started with until its Session exits.
-When the daemon sees a newer pi-agents version, it restarts once idle, and
-Sessions reconnect to the new daemon.
+A host keeps running the version it started with until its Session exits. When the daemon sees a newer pi-agents version, it restarts once idle, and Sessions reconnect to the new daemon.
 
 ## 7. Platform
 
@@ -172,8 +108,4 @@ macOS and Linux.
 
 ## Not in this version
 
-Attaching several terminals to one Session, Sessions on other machines,
-model-written summaries, and a confirmation before quitting while work is
-running. Keeping Sessions alive across host crashes and reboots needs a
-durable runtime, which [Pi Durable](https://earendil.com/posts/pi-durable/)
-explores.
+Attaching several terminals to one Session, Sessions on other machines, model-written summaries, and a confirmation before quitting while work is running. Keeping Sessions alive across host crashes and reboots needs a durable runtime, which [Pi Durable](https://earendil.com/posts/pi-durable/) explores.

package/docs/PROGRAM.md

@@ -1,34 +1,18 @@
 # Pi Agents Program Specification
 
-A Program is JavaScript that calls tools and Agents. Agents are defined in
-SPEC.md.
+A Program is JavaScript that calls tools and Agents. Agents are defined in SPEC.md.
 
-The `program` tool replaces Pi's `codemode` tool and keeps its script API,
-tool list, result format, and truncation. This document describes what
-Programs add.
+The `program` tool replaces Pi's `codemode` tool and keeps its script API, tool list, result format, and truncation. This document describes what Programs add.
 
 ## 1. Semantic model
 
-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.
+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 with `wait`.
 
-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.
+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.
 
-Agents created with `agent()` belong to the Program: it gets their results
-from `send()`, without `wait` or notifications, and only it can abort
-them. Each of these Agents and the Agents under it see only one another,
-and no other Agent sees them. The user sees them in the task panel and `/tasks`,
-and can talk to them or interrupt them in the viewer; an interrupted input
-makes its `send()` throw. When the Program ends, their unfinished inputs end
-as `aborted`, and the Agents go offline for good, from the bottom up.
+Agents created with `agent()` belong to the Program: it gets their results from `send()`, without `wait` or notifications, and only it can abort them. Each of these Agents and the Agents under it see only one another, and no other Agent sees them. The user sees them in the task panel and `/tasks`, and can talk to them or interrupt them in the viewer; an interrupted input makes its `send()` throw. When the Program ends, their unfinished inputs end as `aborted`, and the Agents go offline for good, from the bottom up.
 
 A Program is `running` until it ends in one of three ways:
 
@@ -38,60 +22,38 @@ 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.
+- `run` runs a Program in the foreground or background, with an optional timeout.
 - `wait` waits for background Programs and returns their results.
 - `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 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.
 
 ## 3. Program API
 
-`tools` holds the caller's tools, except `program`; which tools the caller
-can use is checked at each call. If a Program fails or is stopped, the
-error or stop reason follows its output. Its `store()` writes are kept
-only if it completes.
+`tools` holds the caller's tools, except `program`; which tools the caller can use is checked at each call. If a Program fails or is stopped, the error or stop reason follows its output. Its `store()` writes are kept only if it completes.
 
-A Program also creates idle Agents with `agent()`, typed in the Agent API
-(§6). Options work like `agent` `spawn`; an omitted name is generated,
-unique within the Program. `send()` sends a message and returns its result.
-`abort()` works like `agent` `abort`. The Agent gets its tools as if the caller had spawned it.
+A Program also creates idle Agents with `agent()`, typed in the Agent API (§6). Options work like `agent` `spawn`; an omitted name is generated, unique within the Program. `send()` sends a message and returns its result. `abort()` works like `agent` `abort`. The Agent gets its tools as if the caller had spawned it.
 
-A result is the Agent's answer. If the input fails or is aborted, the
-result throws an Error. A write returns `undefined` once accepted.
+A result is the Agent's answer. If the input fails or is aborted, the result throws an Error. A write returns `undefined` once accepted.
 
-With `schema`, the Agent must call `submit_result` with a value that
-matches the schema, and the result is that value. If it does not, the
-input fails.
+With `schema`, the Agent must call `submit_result` with a value that matches the schema, and the result is that value. If it does not, the input fails.
 
-With `timeout`, an input that has not ended within that many seconds of
-`send()`, including time queued for a slot, is aborted; the Agent's queued
-inputs are unaffected. The result throws a timeout Error.
+With `timeout`, an input that has not ended within that many seconds of `send()`, including time queued for a slot, is aborted; the Agent's queued inputs are unaffected. The result throws a timeout Error.
 
 `send()` throws if `schema` or `timeout` is used without `followUp`.
 
 ## 4. Lifecycle
 
-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 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. Their results remain available when the caller is loaded again.
 
 ## 5. Limits
 
-A Program's Agents and the Agents under them count toward the caller's
-tree: they share its slots and `maxOutstanding` limit, as in SPEC §4. At
-`maxOutstanding`, `send()` throws.
+A Program's Agents and the Agents under them count toward the caller's tree: they share its slots and `maxOutstanding` limit, as in SPEC §4. At `maxOutstanding`, `send()` throws.
 
-An owned caller gives up its slot while a foreground Program runs or while
-it waits for background Programs, and takes one again before continuing.
+An owned caller gives up its slot while a foreground Program runs or while it waits for background Programs, and takes one again before continuing.
 
 ## 6. Model-facing tool
 
@@ -99,21 +61,11 @@ it waits for background Programs, and takes one again before continuing.
 
 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 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.
 
-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.
+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.
 
-`program` replaces the `codemode` tool; wherever `codemode` is mentioned,
-use `program`.
+`program` replaces the `codemode` tool; wherever `codemode` is mentioned, use `program`.
 
 [the script API of `codemode`, without its Model API]
 
@@ -163,14 +115,9 @@ Run JavaScript that composes tool calls and Agents
 
 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 `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.
 
 parameters:
 
@@ -186,10 +133,7 @@ results:
 
 In these formats, `<id>` is the Program's short ID.
 
-`run` in the foreground returns the Program result, as an error if the
-Program failed or was stopped.
-A Program result lists its `send()` calls with its tool calls, and names the
-calls still running when the script returned, which were cancelled.
+`run` in the foreground returns the Program result, as an error if the Program failed or was stopped. A Program result lists its `send()` calls with its tool calls, and names the calls still running when the script returned, which were cancelled.
 
 `run` in the background:
 
@@ -197,8 +141,7 @@ calls still running when the script returned, which were cancelled.
 Program <id> started.
 ```
 
-`wait` returns one block per result, followed by running Programs on
-timeout:
+`wait` returns one block per result, followed by running Programs on timeout:
 
 ```text
 <program-result id="<id>" status="<outcome>">
@@ -210,8 +153,7 @@ 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:
+A single completed result, with nothing running, is returned alone. When there are no results or running Programs:
 
 ```text
 No results.
@@ -242,8 +184,7 @@ Program <id> stopped.
 Program <id> has already ended.
 ```
 
-When some of the Program's work does not stop within the timeout, `stop`
-fails with the following; only restarting Pi stops it.
+When some of the Program's work does not stop within the timeout, `stop` fails with the following; only restarting Pi stops it.
 
 ```text
 Program <id> did not stop within the timeout and may still be running.
@@ -257,8 +198,7 @@ Cleanup error: some of the Program's work did not stop within the timeout and ma
 
 errors:
 
-Invalid calls fail with an error. Errors that need a follow-up say what to
-do:
+Invalid calls fail with an error. Errors that need a follow-up say what to do:
 
 ```text
 No Program matches "<target>". Use list to find Programs.
@@ -270,10 +210,7 @@ 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:
+`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.]
@@ -289,19 +226,10 @@ Program <id> <outcome>.
 
 ## 7. Human interface
 
-The task panel (SPEC §7) lists running background Programs.
-`/tasks` opens a background Program in the task viewer (SPEC §7).
+The task panel (SPEC §7) lists running background Programs. `/tasks` opens a background Program in the task viewer (SPEC §7).
 
-`/program <path> [args]` runs the script in a file as a foreground Program of
-the current Agent, with the text after the path as the global `args`. Esc
-stops it. Like a `!` command, it and its result join the context without
-starting a turn. With `pi -p`, the result is printed, and Pi exits with
-status 1 if the run fails.
+`/program <path> [args]` runs the script in a file as a foreground Program of the current Agent, with the text after the path as the global `args`. Like a `!` command, it and its result join the context without starting a turn. With `pi -p`, the result is printed, and Pi exits with status 1 if the run fails.
 
 ## 8. Configuration
 
-`program` is inactive by default, like `codemode`; enable it with `"defaultTools": ["+program"]` or `--tools`. `/program` does not need it.
-MCP treats `program` as `codemode`: it activates `program` when its servers need a script tool and neither is active, unless `autoEnableCodemode` is false, and a Program waits for the MCP servers its code names.
-When both `program` and `codemode` are active, Pi warns once per Session, since they do a similar job.
-`codemode.mode` decides how the tool list is presented, as for `codemode`.
-`--program-only` activates `program` and uses `only` for the process, including its owned Agents.
+`program` is inactive by default, like `codemode`; enable it with `"defaultTools": ["+program"]` or `--tools`. `/program` does not need it. MCP treats `program` as `codemode`: it activates `program` when its servers need a script tool and neither is active, unless `autoEnableCodemode` is false, and a Program waits for the MCP servers its code names. When both `program` and `codemode` are active, Pi warns once per Session, since they do a similar job. `codemode.mode` decides how the tool list is presented, as for `codemode`. `--program-only` activates `program` and uses `only` for the process, including its owned Agents.