@tshu-w/pi-agents 0.1.0 → 0.2.0

package/docs/PROGRAM.md

@@ -25,7 +25,7 @@ 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 `/tasks` and `/agents`,
+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.
@@ -45,7 +45,8 @@ A Program is `running` until it ends in one of three ways:
 - `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.
+caller gets a notification, as in SPEC §5. A steer input ends `wait` early,
+as in SPEC §5.
 
 ## 3. Program API
 
@@ -54,39 +55,23 @@ 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 Agents with `agent()`:
-
-```ts
-agent(options?: {
-  name?: string;
-  cwd?: string;
-  context?: "fresh" | "fork";
-  model?: string;
-  thinkingLevel?: string;
-}): AgentHandle
-
-interface AgentHandle {
-  readonly id: string;
-  readonly name: string;
-  send(message: string, options?: {
-    deliverAs?: "followUp" | "steer" | "write";
-    schema?: JsonSchema;
-  }): Promise<unknown>;
-  abort(): Promise<void>;
-}
-```
-
-`agent()` creates an idle Agent. 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`.
-It 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.
 
 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. `send()` throws if `schema` is used without `followUp`.
+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.
+
+`send()` throws if `schema` or `timeout` is used without `followUp`.
 
 ## 4. Lifecycle
 
@@ -94,8 +79,7 @@ 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.
-Stopping a Program does not undo completed tool calls.
+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.
@@ -153,11 +137,13 @@ interface SendOptions {
   deliverAs?: "followUp" | "steer" | "write";
   /** `followUp` only. The Agent must submit a value matching it. */
   schema?: JsonSchema;
+  /** `followUp` only. Seconds before the input is aborted. Default: none. */
+  timeout?: number;
 }
 interface AgentHandle {
   readonly id: string;
   readonly name: string;
-  /** Resolves with the answer, or with the submitted value when `schema` is set; a write resolves with undefined once accepted. Throws if the input fails or is aborted. */
+  /** Resolves with the answer, or with the submitted value when `schema` is set; a write resolves with undefined once accepted. Throws if the input fails, is aborted, or times out. */
   send(message: string, options?: SendOptions): Promise<unknown>;
   /** Aborts the Agent's current turn and queued inputs; the Agent stays usable. */
   abort(): Promise<void>;
@@ -202,6 +188,8 @@ 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 background:
 
@@ -220,6 +208,8 @@ timeout:
 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:
 
@@ -253,7 +243,7 @@ Program <id> has already ended.
 ```
 
 When some of the Program's work does not stop within the timeout, `stop`
-fails with:
+fails with the following; only restarting Pi stops it.
 
 ```text
 Program <id> did not stop within the timeout and may still be running.
@@ -300,10 +290,17 @@ 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).
+
+`/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.
 
 ## 8. Configuration
 
-`program` is inactive by default, like `codemode`; enable it with `"defaultTools": ["+program"]` or `--tools`.
+`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`.

package/docs/SPEC.md

@@ -4,7 +4,7 @@ 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).
+[Pi Durable specification](https://github.com/earendil-works/pi/blob/main/packages/durable/docs/spec.md).
 
 ## 1. Semantic model
 
@@ -45,6 +45,11 @@ An input to an Agent with a turn in progress is either answered by the current t
 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.
 
+When the user of a root Agent clears its queued messages, messages from other
+Agents stay queued. After an Agent's turn is stopped, messages from other
+Agents, notifications included, become writes until its next input from its
+user or owner.
+
 ### 2.3 wait
 
 `wait` returns results of inputs sent to owned Agents. It can target
@@ -52,8 +57,8 @@ specific Agents and take a timeout.
 
 ### 2.4 list
 
-`list` returns visible Agents with their ID, name, working directory, and
-state.
+`list` returns visible Agents with their ID, name, working directory,
+state, and latest request: the last user message or input it received.
 
 ### 2.5 abort
 
@@ -71,7 +76,7 @@ stays `idle`.
 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.
+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
@@ -101,7 +106,7 @@ 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`.
+beyond it is rejected. Notifications (§5) do not count.
 
 ## 5. Results and notifications
 
@@ -111,11 +116,12 @@ 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.
+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 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`,
+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`.
 
@@ -214,6 +220,13 @@ write:           { ids }
 Still pending: <name> (<id>), ...
 ```
 
+When a steer input ended the wait, a line follows:
+
+```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:
@@ -225,18 +238,19 @@ No results.
 Details:
 
 ```text
-{ results: [{ id, name, state, history, result? }], pending: [id] }
+{ results: [{ id, name, state, history, result? }], pending: [id], interrupted? }
 ```
 
-`state` is the input outcome (§5); `history` marks a previously read result.
+`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. 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:
+`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
 <name> (<id>)  <state>  <cwd>
-  YYYY-MM-DD HH:MM  …<matching excerpt>…
+  YYYY-MM-DD HH:MM  <latest request or matching excerpt>
 ```
 
 When more entries remain:
@@ -304,6 +318,13 @@ Input rejected: <N> inputs have not ended. Wait for results or abort an Agent.
 <name> (<id>) is not owned by the caller.
 ```
 
+When an aborted turn does not stop within the timeout (§3), `abort` fails
+with the following; only restarting Pi stops it.
+
+```text
+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
@@ -350,43 +371,59 @@ asking for a reply:
 
 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>
+    Tasks (<N> live, /tasks to view)
+      Agent <name> (<id>)  <state>  <time>  <cost>  <N> pending
+        Agent <name> (<id>)  <state>  <time>  <cost>
+      Program <id>  running  <time>  <cost>
+        Agent <name> (<id>)  <state>  <time>  <cost>
       +<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.
+keep the tree. Rows that do not fit are counted in the last row. The time is
+how long the Agent's current turn or the Program has run, and the cost what the
+replies in that turn have cost, or for a Program, those of all the Agents under
+it. When a reply has no price, the cost is the input and output tokens instead,
+like `7.3M tok`.
+
+The panel updates as states change, and its times each second. It is shown
+while it has a row.
+`/tasks panel` hides or shows it.
+
+### Queued messages
+
+Messages from other Agents that wait in the Session's queue, as during a turn,
+are listed above the editor, below the user's queued messages, until the
+Session takes them in:
 
-The panel updates as states change and is shown while it has a row.
-`/tasks` hides or shows it.
+    Steering: [<sender>] <body>
+    Write: [<sender>] <body>
+    Follow-up: [<sender>] <body>
 
-### Agent viewer
+### Task 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.
+`/tasks` lists the Agents in the current Agent's tree, including its Programs'
+Agents, and its background Programs, live ones first and newest first, 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, as
+`<name> ‹ <owner> ‹ …`, where a Program is `Program <id>`. The viewer follows
+an Agent's conversation, or a Program as it shows in the foreground, while the
+current Session keeps running.
 
-Text entered in the viewer is the user's input to that Agent and is sent as
-in Pi's editor.
+Text entered in an Agent's viewer is the user's input to it, sent as in Pi's
+editor; a Program takes no input.
 
-`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.
+`app.interrupt` stops an Agent's current turn, as `abort` does, or a Program,
+as `stop` 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).
+machine and lets the user open and message them. Sessions started with `pd`
+keep running after their terminal closes. See [HOSTS.md](HOSTS.md).
 
 ## 8. Configuration
 
@@ -417,11 +454,11 @@ 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).
+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 interactive
-startup, its lock error stays visible until the user dismisses it, then Pi exits.
+One runtime uses a Session at a time. If a Session is occupied at startup, Pi
+reports it and exits.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tshu-w/pi-agents",
-  "version": "0.1.0",
-  "description": "Multi-agent runtime for Pi: async agents, programmatic delegation, and inter-agent messaging",
+  "version": "0.2.0",
+  "description": "Multi-agent runtime for Pi: persistent async agents, dynamic workflows, and inter-agent messaging",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
@@ -19,10 +19,14 @@
     "docs"
   ],
   "keywords": [
-    "pi-package",
+    "pi",
+    "pi-coding-agent",
     "pi-extension",
-    "agents",
-    "multi-agent"
+    "pi-package",
+    "multi-agent",
+    "async-agents",
+    "dynamic-workflows",
+    "rlm"
   ],
   "pi": {
     "extensions": [
@@ -30,7 +34,7 @@
     ]
   },
   "scripts": {
-    "test": "node --test --test-timeout=30000 tests/",
+    "test": "node --test --test-timeout=30000 \"tests/*.test.mjs\"",
     "typecheck": "tsc -p tsconfig.json"
   },
   "dependencies": {