@tshu-w/pi-agents 0.0.0-stage → 0.1.0

package/docs/SPEC.md

@@ -0,0 +1,427 @@
+# Pi Agents Specification
+
+Pi Agents lets Agents in Pi discover, message, and wait for each other.
+Programs built on these operations are specified in PROGRAM.md.
+
+Terms follow Pi's
+[Pico5 specification](https://github.com/earendil-works/pi/blob/main/packages/durable/docs/pico-v5.md).
+
+## 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 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.
+
+A **message** carries text from one Agent to another. An **input** asks the
+recipient to act. A **write** only adds to the recipient's conversation.
+
+A **turn** is one continuous run of an Agent's model and tools. Its final
+assistant message is the **answer** to the inputs it handled.
+
+An owner can **wait** for answers to the inputs it sends to its owned Agents.
+
+**Visibility** determines which Agents an Agent can discover and message.
+
+## 2. Operations
+
+### 2.1 spawn
+
+`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.
+
+### 2.2 send
+
+`send` sends a message to a visible Agent by address. An ambiguous or
+unknown address is rejected.
+
+An input to an Agent with a turn in progress is either answered by the current turn
+(`steer`) or by a new turn after it (`followUp`, the default).
+
+A write is added at the recipient's next tool boundary, or at once if it is
+idle. A write can go to several Agents at once.
+
+### 2.3 wait
+
+`wait` returns results of inputs sent to owned Agents. It can target
+specific Agents and take a timeout.
+
+### 2.4 list
+
+`list` returns visible Agents with their ID, name, working directory, and
+state.
+
+### 2.5 abort
+
+`abort` stops an owned Agent's current turn and withdraws its queued
+inputs. The Agent stays available.
+
+## 3. Lifecycle
+
+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.
+
+An input to an offline Agent wakes it. A write never wakes an Agent.
+
+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.
+
+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.
+
+A root Agent is `running` while it has a turn in progress or pending messages,
+or while its tree has live work (§7 Task panel); otherwise it is `idle`.
+
+## 4. Visibility and limits
+
+An Agent sees every Agent in its own tree. A root Agent also sees other root
+Agents.
+
+Limits apply to owned Agents in each tree.
+
+An owned Agent needs a slot to run a turn. `maxConcurrent` (default 3) is
+the number of slots. An input that would start a turn waits for a free
+slot, and `spawn` or `send` reports that it is queued. A `steer` input to
+an Agent with a turn in progress joins it and needs no new slot. An Agent gives
+up its slot while it waits in `wait`, and takes one again before
+continuing, ahead of inputs that have not started.
+
+An input is outstanding from acceptance until its turn ends or it is
+withdrawn. `maxOutstanding` (default 8) limits outstanding inputs; an input
+beyond it is rejected. `maxConcurrent` cannot exceed `maxOutstanding`.
+
+## 5. Results and notifications
+
+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. It can also
+return read results again.
+
+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`,
+and it names the Agent and how the input ended. It does not include the
+result; the owner reads the result with `wait`.
+
+A recipient sees each message with its sender's name and ID.
+
+## 6. Model-facing tool
+
+### `agent`
+
+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.
+
+promptSnippet:
+
+Create, message, and coordinate Agents
+
+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.
+
+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)`.
+- `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, or xhigh (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).
+- `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.
+- `limit`: Maximum Agents returned by `list` (default: 20, max: 200).
+- `offset`: Number of Agents to skip for `list` (default: 0).
+
+results:
+
+In these formats, `<id>` is the Agent's short ID. Details use full IDs;
+arrays remain present when empty.
+
+`spawn`:
+
+```text
+Agent <name> (<id>) started.
+Agent <name> (<id>) queued: all <N> slots are busy.
+```
+
+Details:
+
+```text
+{ id, name, queued }
+```
+
+`send` returns acceptance, not completion:
+
+```text
+Input accepted by <name> (<id>).
+Input accepted by <name> (<id>), queued: all <N> slots are busy.
+Write accepted by <name> (<id>), ...
+```
+
+Details:
+
+```text
+followUp / steer: { id, queued }
+write:           { ids }
+```
+
+`wait` returns one block per result, followed by pending Agents on timeout:
+
+```text
+<agent-result name="<name>" id="<id>" status="<outcome>">
+<answer or error>
+</agent-result>
+
+Still pending: <name> (<id>), ...
+```
+
+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.
+```
+
+Details:
+
+```text
+{ results: [{ id, name, state, history, result? }], pending: [id] }
+```
+
+`state` is the input outcome (§5); `history` marks a previously read result.
+
+`list` returns one entry per Agent. With a query, entries are ordered by
+their most recent match. When a summary or user message matches, the entry
+shows the latest matching excerpt and its time:
+
+```text
+<name> (<id>)  <state>  <cwd>
+  YYYY-MM-DD HH:MM  …<matching excerpt>…
+```
+
+When more entries remain:
+
+```text
+[N more results. Use offset=X to continue.]
+```
+
+When no Agents match:
+
+```text
+No matching Agents.
+```
+
+Details:
+
+```text
+{ total, agents: [{ id, name?, ownerId?, state }] }
+```
+
+`agents` is the current page; `total` counts all matches. `state` is the
+Agent's current state (§3).
+
+`abort`:
+
+```text
+Agent <name> (<id>) aborted.
+Agent <name> (<id>) has no turn or queued inputs.
+```
+
+Details:
+
+```text
+{ id, aborted }
+```
+
+For unnamed root Agents, show the ID without a name or parentheses.
+
+errors:
+
+Invalid calls fail with an error. Errors that need a follow-up say what to
+do:
+
+```text
+No visible Agent matches "<target>". Use list to find Agents.
+```
+
+```text
+"<target>" matches several Agents:
+<name> (<id>)  <state>  <cwd>
+...
+
+Retry with a longer ID prefix.
+```
+
+```text
+Name "<name>" is already used by <id>.
+```
+
+```text
+Input rejected: <N> inputs have not ended. Wait for results or abort an Agent.
+```
+
+```text
+<name> (<id>) is not owned by the caller.
+```
+
+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.
+
+messages:
+
+A notification to the owner:
+
+```text
+Agent <name> (<id>) <outcome>.
+```
+
+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
+<agent-message from="<name>" id="<id>">
+<body>
+</agent-message>
+```
+
+```text
+<agent-message from="<name>" id="<id>" note="Reply with send">
+<body>
+</agent-message>
+```
+
+## 7. Human interface
+
+### Task panel
+
+A panel above the editor shows the current Agent's live work:
+
+    Tasks (<N> live, /tasks to hide)
+      Agent <name> (<id>)  <state>  <N> pending
+        Agent <name> (<id>)  <state>
+      Program <id>  running
+        Agent <name> (<id>)  <state>
+      +<N> more
+
+The live work is the owned Agents that are not `idle`, and the running
+background Programs with their Agents that are not `idle`. The rows list
+them as a tree in the order they started, each
+under its owner and each Program under its caller, with the owners needed to
+keep the tree. Rows that do not fit are counted in the last row.
+
+The panel updates as states change and is shown while it has a row.
+`/tasks` hides or shows it.
+
+### Agent viewer
+
+`/agents` lists the Agents in the current Agent's tree, including Programs'
+Agents, those not `idle` first and newest first within each group, with their state
+and latest activity, and opens the selected one in a viewer. An Agent not owned
+by the current Agent is named with its owners up to it, as
+`<name> ‹ <owner> ‹ …`, where a Program is `Program <id>`. The viewer shows the
+Agent's conversation and updates while it works; the current Session keeps
+running behind it.
+
+Text entered in the viewer is the user's input to that Agent and is sent as
+in Pi's editor.
+
+`app.interrupt` stops the Agent's current turn, as `abort` does.
+`app.clear` clears the input, and closes the viewer when the input is empty.
+
+### Workbench
+
+`pd agents` opens the workbench, which lists every root Session on this
+machine and lets the user open and message them. Interactive Sessions keep
+running after their terminal closes. See [WORKBENCH.md](WORKBENCH.md).
+
+## 8. Configuration
+
+Settings live under `"pi-agents"` in the global `settings.json`:
+
+```json
+{
+  "pi-agents": {
+    "maxConcurrent": 3,
+    "maxOutstanding": 8,
+    "extensions": []
+  }
+}
+```
+
+- `maxConcurrent`, `maxOutstanding`: limits from §4. Both are positive
+  integers with `maxConcurrent <= maxOutstanding`.
+- `extensions`: extension paths loaded by owned Agents, relative to Pi's
+  agent directory. An owned Agent can use only tools its owner can use.
+
+Invalid settings produce a startup warning, and the defaults are used.
+
+## 9. Runtime
+
+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 (WORKBENCH §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 interactive
+startup, its lock error stays visible until the user dismisses it, then Pi exits.

package/docs/WORKBENCH.md

@@ -0,0 +1,165 @@
+# Pi Agents Workbench
+
+## 1. Overview
+
+The workbench 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. Sessions
+started with `pd` keep running after their terminal closes.
+
+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.
+- **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 30 seconds after its
+last connection closes.
+
+Files live in `${XDG_STATE_HOME:-~/.local/state}/pi/agents/`:
+
+- `workbench.json`: seen marks and which Sessions are listed. The file is
+  versioned.
+- `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.
+
+## 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:
+
+    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.
+
+## 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.
+- `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`, piped stdin) and package commands
+  (`pd install`, `pd update`, ...) run Pi directly.
+
+A host inherits the environment of the process that asked for it, because Pi
+reads terminal features from the environment once, 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.
+
+On attach, the host restores the screen and the terminal modes Pi has set
+(keyboard protocols, bracketed paste, mouse, title, program status). Images
+come back when the host then has Pi redraw.
+
+A host started from a terminal waits for that terminal to attach before it
+starts Pi, so Pi detects the terminal's colors and keyboard protocol just as it
+would without a host. A host started in the background passes the queries Pi
+sent at startup to the first terminal that attaches, and Pi finishes detecting
+then.
+
+Closing the window, pressing `Ctrl+Z` (the `pi-agents.detach` keybinding), or
+running `/detach` detaches. The Session keeps running, and the terminal prints:
+
+    Pi keeps running. To reattach, run pd attach <session>
+
+A host disables suspend, since a suspended Pi would stay stopped; `Ctrl+Z`
+detaches in its place.
+
+A detached Session exits once its tree has had no live work for 5 minutes. 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`.
+
+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 input**: 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.
+
+A turn counts as seen once it has been shown in an attached terminal. 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 (`?`); the
+daemon checks it again every second until that changes.
+
+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.
+  - The page keys of fullscreen mode (`tui.altScreen.pageUp`/`pageDown`)
+    scroll; with no message typed, `↑`/`↓` scroll too.
+  - `Esc` clears a typed message; with none typed, it closes the preview.
+- `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. A running Session must quit first.
+- `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.
+
+## 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.
+
+## 7. Platform
+
+macOS and Linux. Every dependency is pure JavaScript or prebuilt: hosts use
+`@lydell/node-pty`, and a Session lock is a file that records the process
+holding it.
+
+## 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.

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@tshu-w/pi-agents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Multi-agent runtime for Pi: async agents, programmatic delegation, and inter-agent messaging",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tshu-w/pi-agents.git"
+  },
+  "homepage": "https://github.com/tshu-w/pi-agents#readme",
+  "type": "module",
+  "bin": {
+    "pd": "bin/pd.mjs",
+    "pi-agents": "bin/pd.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "agents",
+    "multi-agent"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test --test-timeout=30000 tests/",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@lydell/node-pty": "^1.2.0-beta.15",
+    "@xterm/addon-serialize": "^0.14.0",
+    "@xterm/headless": "^6.0.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "5.9.3"
+  }
+}