pi-multi-agent-skill 0.0.0-stage → 0.2.0

package/skills/multi-agent/references/lifecycle.md

@@ -0,0 +1,92 @@
+# Job lifecycle
+
+A job is a named agent and its conversation. `run` creates the job and starts
+its first run; each `resume` starts another run in the same conversation. A
+job has at most one run at a time, and its status describes the latest run.
+
+## Statuses
+
+| Status | Meaning | Result text |
+|---|---|---|
+| `running` | The agent is working. | — |
+| `done` | The agent finished its turn. | Its final message. |
+| `failed` | The run could not finish; see below. | The agent's last message, if any, then an `error:` line. |
+| `aborted` | `abort` stopped the agent, or something else aborted its turn. | Its last message. |
+| `timeout` | The run reached its `--timeout`. | Its last message. |
+| `killed` | `kill`, a signal to the job's runner, or the end of a foreground command stopped the run. | Its last message. |
+| `died` | The job's runner ended without recording a result, for example after a SIGKILL. | None; the result reads `(no output)`. |
+
+A run ends as `failed` when the model returns an error after pi's own retries,
+pi rejects the prompt, pi cannot start, or pi exits during the run. In the
+last case the result holds the end of pi's stderr. A model or tool name that
+pi rejects is a common cause.
+
+"Last message" is the text of the agent's latest message in this run. It is
+empty when that message had only tool calls, or when the run stopped before
+the agent wrote anything; the result then reads `(no output)`. A message cut
+short by an abort keeps the text written before it.
+
+A prompt that pi handles by itself without starting the agent, such as an
+extension command, ends the run at once as `done` with no output.
+
+## How a run stops
+
+- **The agent finishes.** The status is `done`, or `failed` if its last
+  message was an error.
+- **`abort`.** Steering messages that the agent has not read are discarded and
+  pi is asked to abort the current turn. The agent gets 30 seconds to wind
+  down; after that the run is stopped anyway. The status is `aborted`.
+- **Timeout.** The limit counts from the start of the run. When it is
+  reached, the run is aborted as above and ends as `timeout`.
+- **`kill`, a signal, or the end of a foreground command.** The run stops at
+  once without the 30-second wind-down. The status is `killed`.
+
+In every case pi is shut down cleanly: it gets 10 seconds to exit, then
+SIGTERM, then SIGKILL 5 seconds later. A run that hits its timeout can
+therefore take up to 45 seconds to end. `steer` and `abort` fail with `job is
+not running; use resume` as soon as the run has started to end.
+
+## Foreground and background runs
+
+Every run is driven by its own runner process, detached from the caller's
+terminal and process group.
+
+- A foreground run is tied to the command that started it. Whatever ends that
+  command, SIGKILL included, stops the agent and the commands it was running.
+  On SIGINT, SIGTERM or SIGHUP the command waits for the run to stop and
+  prints its result; a second signal ends it at once. A foreground run started
+  by another agent is tied to that agent's command in the same way, so a chain
+  of foreground runs stops together.
+- A background run keeps going after its caller ends, until it finishes,
+  reaches its timeout, or is stopped with `kill`.
+- If a runner is killed with SIGKILL, its job's status becomes `died` at once.
+  The agent's pi process usually exits within a second, but commands the agent
+  was running may keep running.
+
+## Timeouts
+
+A timeout applies to one run. `run` and `resume` default to 3600 seconds in
+the background and to no limit in the foreground; `--timeout 0` removes the
+limit, and fractional seconds are allowed. A timeout does not carry over to
+the next run.
+
+## Dialogs and approvals
+
+No person watches an agent. When an extension inside the agent opens a dialog
+(select, confirm, input or editor), it is cancelled at once and logged in the
+progress log as `denied:`. Extensions that have a non-interactive mode run in
+it (see `state.md`), so tool calls that need a person fail without opening a
+dialog. The agent is told not to retry them and to report what it could not
+do in its final message.
+
+## Nesting
+
+An agent can start agents of its own. `PI_MULTI_AGENT_DEPTH` counts the depth:
+0 or unset for the user's agent, 1 for an agent it started, and so on. `run` and
+`resume` refuse to start when the caller's depth is at least
+`PI_MULTI_AGENT_MAX_DEPTH` (default 2), so by default the user's agent and its
+agents can delegate, and their agents cannot. Agents inherit
+`PI_MULTI_AGENT_MAX_DEPTH` from the environment of the user's agent.
+
+`PI_MULTI_AGENT_JOB` holds the job directory of the agent that is running.
+`status` and `list` use it to show the job that started each job.

package/skills/multi-agent/references/profiles.md

@@ -0,0 +1,79 @@
+# Profiles
+
+A profile sets an agent's system prompt, model, thinking level and tools. It
+is a Markdown file with frontmatter; the body after the frontmatter is the
+profile's prompt.
+
+```markdown
+---
+description: Reviews a diff for correctness bugs.
+model: anthropic/claude-sonnet-5
+thinking: high
+tools: read, grep, find, ls, bash
+---
+
+You review code changes. Report each bug with its file, line and a failing
+scenario.
+```
+
+## Where profiles come from
+
+Profiles are looked up in three directories, from highest to lowest priority:
+
+1. `<cwd>/.pi/agents/*.md` (project), where `<cwd>` is the agent's working
+   directory
+2. `$PI_CODING_AGENT_DIR/agents/*.md`, default `~/.pi/agent/agents/` (user)
+3. `profiles/*.md` in this skill's directory (built-in)
+
+Names are matched case-insensitively. When several directories define the
+same name, the file from the highest directory is used as a whole; fields are
+never merged across files. To change one field of a built-in profile, copy the
+whole file and edit the copy. A profile with `enabled: false` hides its name,
+including lower profiles of that name.
+
+A job keeps the settings it was created with. Editing a profile affects new
+jobs only, not `resume` of an existing one.
+
+## Fields
+
+| Field | Default | Effect |
+|---|---|---|
+| `name` | file name without `.md` | Profile name. |
+| `description` | `name` | Shown by `profiles`. |
+| `model` | the caller's model | Passed to `pi --model`. |
+| `thinking` | the caller's thinking level | Passed to `pi --thinking`. |
+| `tools` | pi's default tool selection | Passed to `pi --tools`. |
+| `disallowed_tools` | none | Passed to `pi --exclude-tools`. |
+| `prompt_mode` | `append` | `append` or `replace`; see below. |
+| `enabled` | `true` | `false` hides the profile. |
+
+Unknown fields are ignored. The parser reads `key: value` lines, quoted
+strings, `true`/`false` and `[a, b]` lists, and skips comments and indented
+lines; it does not support nested YAML.
+
+## Model and thinking level
+
+For each of the two, the first value found wins: the `run` option, the profile
+field, the caller's current setting, then pi's configured default. The
+caller's settings come from the `PI_PROVIDER`, `PI_MODEL` and
+`PI_REASONING_LEVEL` variables that pi sets for the commands it runs.
+
+## Tools
+
+`tools` and `disallowed_tools` accept a comma-separated list or `[a, b]`. The
+entries are passed to pi verbatim as `--tools` and `--exclude-tools`; see pi's
+documentation of those options for the patterns they accept and which tools
+they keep.
+
+## System prompt
+
+With `prompt_mode: append`, the profile's body is passed to pi with
+`--append-system-prompt`, so it is added to the system prompt pi builds as
+usual. With `prompt_mode: replace`, the body is passed with `--system-prompt`
+and pi also gets `--no-context-files`. Any other value makes `run` fail.
+
+Every agent also receives a short block that tells it its job name, that only
+its final message is read, and that no person can approve blocked tool calls.
+This block is passed with `--append-system-prompt` in both modes, so pi does
+not load `APPEND_SYSTEM.md` files for agents; put text that agents need in a
+profile's body.

package/skills/multi-agent/references/state.md

@@ -0,0 +1,57 @@
+# State
+
+## Locations
+
+Job directories are in
+`$XDG_STATE_HOME/pi-multi-agent/<project>/jobs/<name>/` (default
+`~/.local/state`). `<project>` is the project's directory with every character
+other than a letter or digit replaced by `-` and the leading `-` removed, so
+`/home/me/app` becomes `home-me-app`.
+
+A running job's runner listens on a Unix socket in
+`$XDG_STATE_HOME/pi-multi-agent/sockets/`, which `steer`, `abort` and `kill`
+connect to. Conversations are pi session files in
+`$PI_CODING_AGENT_DIR/multi-agent-sessions/<project>/` (default
+`~/.pi/agent/`), so they stay out of pi's `/resume` list.
+
+## Job files
+
+| File | Content |
+|---|---|
+| `job.json` | Launch settings: profile, pi arguments, cwd, parent job, depth, run mode, timeout. |
+| `prompt.txt` | Prompt of the latest run. |
+| `system-prompt.md` | The profile's prompt, when it replaces pi's system prompt. |
+| `append-prompt.md` | Text added to pi's system prompt: the profile's prompt in append mode, then the multi-agent block. |
+| `status` | Status of the latest run; final once `exit_code` exists. |
+| `lock` | Held by the job's runner for as long as it runs. The job is running exactly while this lock is held. |
+| `started_at`, `ended_at` | UTC timestamps of the latest run. |
+| `runs` | Number of runs. |
+| `exit_code` | Exit code of the latest run, written last. A run without it that is no longer running has `died`. |
+| `output.txt` | Result text of the latest run; empty if that run produced none. |
+| `model` | Model that wrote the latest message. |
+| `stderr.txt` | pi's stderr for the latest run. |
+| `progress.log` | The lines `peek` prints, across runs. |
+| `usage.json` | Token and cost totals across runs. |
+| `runner.log` | Traceback when the runner itself fails. |
+
+Starting a run clears the previous run's result, end time and model, so these
+files always describe the latest run.
+
+## Reading a conversation
+
+To read a finished job's whole conversation in interactive pi, run the
+`session_cmd` that `status` prints. Do not open it while the job is running,
+because two processes would then write the same session file.
+
+## The agent's environment
+
+The script starts the program in `PI_MULTI_AGENT_PI_BIN` (default `pi`). An
+agent inherits the environment of the command that started it, plus:
+
+| Variable | Value |
+|---|---|
+| `PI_MULTI_AGENT_JOB` | The agent's job directory. |
+| `PI_MULTI_AGENT_DEPTH` | The agent's nesting depth; see `lifecycle.md`. |
+| `PI_MINIMAL_PERMISSION_SYSTEM_NONINTERACTIVE` | `1`, so that extension never waits for an approval. |
+| `PI_REQUEST_USER_INPUT_NONINTERACTIVE` | `1`, so that extension never asks the user a question. |
+| `PWD` | The agent's working directory. |

package/skills/multi-agent/references/troubleshooting.md

@@ -0,0 +1,59 @@
+# Troubleshooting
+
+## Job status
+
+- **Status `failed` with `pi exited before the run finished`.** pi stopped
+  during start-up or the run. The output holds the end of pi's stderr; the
+  whole log is in the job's `stderr.txt`. A model or tool name that pi rejects
+  causes this.
+- **Status `failed` with `the runner failed`.** The script itself hit an
+  error. The traceback is in the job's `runner.log`.
+- **Status `died`.** The runner was killed without a chance to record a
+  result. The agent's pi process exits by itself, usually within a second,
+  but commands it started can survive; look for them with `ps` if the agent
+  was running a long command. `peek` shows how far it got; `resume`
+  continues the conversation. Wait a few seconds before you `resume` a job
+  that has just died, so its old pi has exited and does not write the
+  conversation at the same time as the new one.
+- **An agent reports that a tool call needs approval.** Agents cannot ask a
+  person. Run that step yourself, or tell the user what was blocked.
+- **A job lingers after its caller is gone.** Background jobs outlive their
+  caller by design. Stop them with `kill NAME`, or `kill --all` when the user
+  asks.
+
+## Command errors
+
+- **`job is not running; use resume`.** The run has ended or is ending.
+  `resume` the job with a new prompt instead of steering it.
+- **`job NAME already exists in this project`.** Pick another `--name`.
+  The error shows the existing job's status and age. Use `resume` or `rm`
+  only for a job you started or the user asked about.
+- **`job NAME is running` from `resume` or `rm`.** The job's runner is
+  still alive, or another command was starting the job at the same moment.
+  `wait` for it, or `kill` it first.
+- **`unknown profile: P (available: ...)`.** No enabled profile has that name
+  in the agent's working directory; the message lists the ones that exist.
+- **`--fork needs PI_SESSION_FILE`.** The command does not run inside pi, so
+  there is no conversation to copy. Drop `--fork` and write a self-contained
+  prompt.
+- **`cannot start an agent: ... PI_MULTI_AGENT_MAX_DEPTH`.** The caller is too
+  deep in a chain of agents. Do the work directly.
+- **`the runner of job NAME is not responding`.** The runner did not answer
+  `kill` within 10 seconds, or did not exit within 20 seconds after it
+  answered. The message ends with a `pkill` command that stops that runner;
+  run it, then wait a few seconds before you `resume` the job (see `died`).
+- **`the job's working directory no longer exists`.** `resume` runs the
+  agent in the directory the job was started in. Start a new job instead.
+- **`job NAME exists in several projects`.** Run the command from the
+  directory where the job was started.
+
+## Environment
+
+- **`cannot find the pi program`.** Set `PI_MULTI_AGENT_PI_BIN` to the command
+  that starts pi, such as `pi-bolt`, or ask the user which one they use.
+- **`flock does not work on ...`.** The state directory is on a file system
+  without working file locks, such as some NFS or SMB mounts. Set
+  `XDG_STATE_HOME` to a directory on a local file system.
+- **`the socket path for this job is too long`.** The socket path under
+  `XDG_STATE_HOME` exceeds the system's limit for Unix sockets (about 100
+  bytes). Set `XDG_STATE_HOME` to a shorter path.