pi-multi-agent-skill 0.1.0 → 0.2.0

package/README.md

@@ -5,35 +5,10 @@ needs no extension and adds no tools. Your agent starts other agents, runs
 them in parallel or in the background, and waits for, steers, stops or
 resumes them. Any harness or agent that has a shell can use it.
 
-## Features
-
-- **Small token cost.** A subagent extension adds its tool definitions to
-  every request, whether or not your agent delegates anything. With this
-  skill, your agent's context holds only the skill's description, a few
-  dozen tokens, until it decides to delegate. Then it loads SKILL.md, which
-  is about 1.2K tokens and is all it needs for a fully working multi-agent
-  setup. The details of each command stay in separate references that it
-  reads only when needed.
-- **Everything a subagent tool does, without the tool.** Your agent gets the
-  same controls a dedicated extension would give it: start agents, wait for
-  them, `steer` one with a correction, `abort` it and keep what it has so
-  far, `resume` a finished job with a follow-up task, and see what each job
-  is doing. You can run the same commands yourself from a terminal.
-- **Parallel and background agents.** Run a quick question in the
-  foreground, or start several jobs at once and collect their results later.
-- **Stops when you stop.** A foreground agent ends when the command that
-  started it ends: press Esc, cancel the tool call or close the session, and
-  the agent and the commands it was running stop with it, at every level of
-  nesting. Background jobs keep running until they finish or time out.
-- **Your full pi setup.** Each agent loads the same extensions, MCP servers,
-  skills and settings as an interactive pi, and uses your model unless its
-  profile picks another.
-- **Profiles.** They work as in other subagent tools: each one sets an
-  agent's system prompt, model, thinking level and tools.
-- **Fork your conversation.** `--fork` hands the agent everything you have
-  discussed so far, for tasks that need that context.
-- **Works outside pi.** Claude Code, Codex or any other agent with a shell
-  can run the same commands to delegate work to pi agents.
+It aims to be minimal while keeping subagents as useful as an extension and
+tool based approach. A subagent extension adds its tool definitions to every
+request, while this skill adds only a few dozen tokens of description to your
+agent's context until it decides to delegate.
 
 ## Install
 
@@ -64,6 +39,65 @@ ln -s "$PWD/skills/multi-agent" ~/.pi/agent/skills/multi-agent
 
 Requirements: pi and Python 3.9 or later. Nothing else to install.
 
+Agents run `pi` by default. To run another build of pi, such as pi-bolt, set
+`PI_MULTI_AGENT_PI_BIN` in the environment that starts it. Your agent's shell
+inherits the variable, and so do the agents it starts:
+
+```bash
+alias pi-bolt='PI_MULTI_AGENT_PI_BIN=pi-bolt pi-bolt'
+```
+
+## Features
+
+- **Small token cost.** A subagent extension adds its tool definitions to
+  every request, whether or not your agent delegates anything. With this
+  skill, your agent's context holds only the skill's description, a few
+  dozen tokens, until it decides to delegate. Then it loads SKILL.md, which
+  is about 1.2K tokens and is all it needs for a fully working multi-agent
+  setup. The details of each command stay in separate references that it
+  reads only when needed.
+- **Everything a subagent tool does, without the tool.** Your agent gets the
+  same controls a dedicated extension would give it: start agents, wait for
+  them, `steer` one with a correction, `abort` it and keep what it has so
+  far, `resume` a finished job with a follow-up task, and see what each job
+  is doing. You can run the same commands yourself from a terminal.
+- **Foreground agents.** Run a quick question and wait for the answer. A
+  foreground agent is tied to the command that started it: press Esc, cancel
+  the tool call or close the session, and the agent and the commands it was
+  running stop with it, at every level of nesting.
+- **Parallel and background agents.** Start several jobs at once and collect
+  their results later. A background job is independent of your session: it
+  keeps running after the session that started it ends, until it finishes
+  or times out, and you can collect its result from a later session.
+- **Your full pi setup.** Each agent loads the same extensions, MCP servers,
+  skills and settings as an interactive pi, and uses your model unless its
+  profile picks another.
+- **Profiles.** They work as in other subagent tools: each one sets an
+  agent's system prompt, model, thinking level and tools.
+- **Fork your conversation.** `--fork` hands the agent everything you have
+  discussed so far, for tasks that need that context.
+- **Works outside pi.** Claude Code, Codex or any other agent with a shell
+  can run the same commands to delegate work to pi agents.
+
+## Non-goals
+
+These are deliberate non-goals, to keep the skill small and free of bloat.
+Each is better as a separate extension or skill that you pick to match your
+own workflow. This follows the minimalism of pi itself and the Unix
+philosophy: do one thing well and compose.
+
+- **Memory.** Agents do not share or keep memory between jobs. Use a memory
+  extension, or have agents write handoff notes.
+- **Scheduling.** There are no cron-style or recurring agents. Use cron,
+  `systemd` timers or a scheduler extension to run the commands.
+- **Worktrees.** Agents are not isolated in git worktrees. Just prompt the
+  agent to use a worktree.
+- **Dynamic workflows.** There is no scripting layer for orchestration such
+  as pipelines, parallel fan-out with gates, or phases. Your agent can
+  already start, wait for and chain jobs with plain commands. For
+  deterministic scripts, use an extension such as
+  [pi-dynamic-workflow](https://github.com/milanglacier/pi-dynamic-workflow).
+
 ## Usage
 
 Your agent drives the skill on its own, but the commands also work by hand:
@@ -81,21 +115,33 @@ See [`skills/multi-agent/references/`](skills/multi-agent/references/) for
 every command and option, how jobs start and stop, the profile format, where
 state is kept and troubleshooting.
 
-## Tests
+## Profiles
 
-```bash
-python3 -m unittest discover tests
-```
-
-The tests use an offline stand-in for pi, so they call no model.
+A profile is a Markdown file with frontmatter that sets an agent's system
+prompt, model, thinking level and tools. `--profile NAME` selects one;
+`multi_agent.py profiles` lists the available ones.
 
-## Releases
+```markdown
+---
+model: anthropic/claude-sonnet-5
+thinking: high
+tools: read, grep, find
+---
+You review code changes and report bugs.
+```
 
-Set the version in `package.json`, commit it, and push a matching tag such
-as `v0.1.1`. The GitHub workflow runs the tests and publishes to npm.
-Prerelease versions use the `next` npm tag; stable versions use `latest`.
-The npm trusted publisher is `milanglacier/pi-multi-agent-skill` with the
-workflow filename `publish.yml` and permission to publish directly.
+Profiles are looked up in `<cwd>/.pi/agents/*.md`, then
+`$PI_CODING_AGENT_DIR/agents/*.md` (`~/.pi/agent/agents/` by default); when
+names collide, the local profile wins. Two profiles are built in:
+`general-purpose` (the default) and `Explore`, a read-only search agent.
+Supported fields are `name`, `description`, `model`, `thinking`, `tools`,
+`disallowed_tools`, `prompt_mode` and `enabled`. Fields do not merge across
+files, so a local profile replaces the profile it overrides as a whole and
+must supply the entire profile; `enabled: false` is the exception and hides
+the name on its own. Unknown fields are ignored, and nested YAML is not
+supported. See
+[`references/profiles.md`](skills/multi-agent/references/profiles.md) for the
+field details.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-multi-agent-skill",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A minimal multi-agent skill+cli for pi. It adds no extension or tools, so it uses only a few dozen tokens of the context window until the main agent delegates, yet it gives the same controls as a subagent extension. Background agents keep running after the session closes, and any later session can collect their results.",
   "license": "MIT",
   "author": "Milan Glacier",
@@ -27,6 +27,8 @@
     "LICENSE"
   ],
   "pi": {
-    "skills": ["./skills"]
+    "skills": [
+      "./skills"
+    ]
   }
 }

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

@@ -17,12 +17,12 @@ An empty prompt or message is a usage error. `--help` prints a usage summary.
 | `peek NAME [-n N]` | Print the last N lines (default 20) of the job's progress log. |
 | `list [--all]` | List the jobs of the current project. |
 | `profiles` | List the available profiles. |
-| `rm NAME` | Delete a job that is not running, with its conversation. |
+| `rm NAME` / `rm --all` | Delete one job that is not running, or every such job of the current project, with their conversations. |
 
 ## Projects and job names
 
 A job belongs to the project of the directory where `run` was called. `run`,
-`list` and `kill --all` work on the current directory's project only.
+`list`, `kill --all` and `rm --all` work on the current directory's project only.
 
 The other commands look for NAME in the current project first. If the project
 has no job of that name, they search every project and use the job when
@@ -45,8 +45,9 @@ run it from the job's project.
 
 A job name contains letters, digits, `.`, `_` and `-`, starts and ends with a
 letter or digit, and has at most 64 characters. `run` refuses a name that
-already exists in the project; `resume` that job, pick another name, or `rm`
-the old job first.
+already exists in the project and reports its status and age. Pick another
+`--name`. Use `resume` or `rm` only for a job you started or the user asked
+about.
 
 `--cwd` changes where the agent works and where project profiles are looked
 up (`DIR/.pi/agents/`). The job still belongs to the current directory's
@@ -197,10 +198,13 @@ It looks up project profiles in the current directory.
 
 ## rm
 
-`rm` deletes a job that is not running: its state directory and its
+`rm NAME` deletes a job that is not running: its state directory and its
 conversation file. It prints `removed: NAME` and fails with `job NAME is
 running; kill it first` while the job runs.
 
+`rm --all` deletes every job of the current project that is not running,
+with its conversation, and leaves running jobs alone.
+
 ## Exit codes
 
 | Code | Meaning |

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

@@ -74,19 +74,19 @@ the next run.
 
 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:`. The pi-minimal-permission-system extension, if
-installed, runs in its non-interactive mode, so tool calls that need approval
-are blocked. The agent is told not to retry them and to report what it could not do in its final
-message.
+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. `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
+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
-`MULTI_AGENT_MAX_DEPTH` (default 2), so by default the user's agent and its
+`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
-`MULTI_AGENT_MAX_DEPTH` from the environment of the user's agent.
+`PI_MULTI_AGENT_MAX_DEPTH` from the environment of the user's agent.
 
-`MULTI_AGENT_JOB` holds the job directory of the agent that is running.
+`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/state.md

@@ -45,11 +45,13 @@ because two processes would then write the same session file.
 
 ## The agent's environment
 
-An agent inherits the environment of the command that started it, plus:
+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 |
 |---|---|
-| `MULTI_AGENT_JOB` | The agent's job directory. |
-| `MULTI_AGENT_DEPTH` | The agent's nesting depth; see `lifecycle.md`. |
+| `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

@@ -25,8 +25,9 @@
 
 - **`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`.** `run` needs a new name.
-  `resume` the job, pick another `--name`, or `rm` the old job first.
+- **`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.
@@ -35,7 +36,7 @@
 - **`--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: ... MULTI_AGENT_MAX_DEPTH`.** The caller is too
+- **`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
@@ -48,6 +49,8 @@
 
 ## 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.

package/skills/multi-agent/scripts/multi_agent.py

@@ -53,14 +53,14 @@ NOT_RUNNING = "job is not running; use resume"
 
 def time_scale():
     """The factor for the timing constants below; tests set it to make them short."""
-    value = os.environ.get("MULTI_AGENT_TIME_SCALE") or "1"
+    value = os.environ.get("PI_MULTI_AGENT_TIME_SCALE") or "1"
     try:
         scale = float(value)
     except ValueError:
         scale = 0.0
     if not 0 < scale < float("inf"):
         raise SystemExit(
-            f"multi-agent: error: MULTI_AGENT_TIME_SCALE needs a positive number, got: {value}"
+            f"multi-agent: error: PI_MULTI_AGENT_TIME_SCALE needs a positive number, got: {value}"
         )
     return scale
 
@@ -94,8 +94,8 @@ MULTI_AGENT_BLOCK = """<multi-agent>
 You are an agent named {name}, started by another agent to work on one
 task. Whoever reads your result sees only your final message, so make it a
 complete, self-contained answer to the task. No person is available to
-answer questions. If a tool call is blocked because it needs approval, do
-not retry it; say in your final message what you could not do and why.
+answer questions. If a tool call fails because it needs a person, do not
+retry it; say in your final message what you could not do and why.
 </multi-agent>
 """
 
@@ -112,7 +112,7 @@ Usage:
   multi_agent.py peek     NAME [-n N]
   multi_agent.py list     [--all]
   multi_agent.py profiles
-  multi_agent.py rm       NAME
+  multi_agent.py rm       (NAME | --all)
 
 Options for run:
   --profile P     Profile name, matched case-insensitively (default general-purpose)
@@ -273,7 +273,15 @@ def sessions_dir(project):
 
 
 def pi_bin():
-    return os.environ.get("MULTI_AGENT_PI_BIN") or "pi"
+    return os.environ.get("PI_MULTI_AGENT_PI_BIN") or "pi"
+
+
+def check_pi_bin():
+    if not shutil.which(pi_bin()):
+        raise CommandError(
+            f'cannot find the pi program "{pi_bin()}"; '
+            "set PI_MULTI_AGENT_PI_BIN to the command that starts pi"
+        )
 
 
 def find_session_file(session_dir, name):
@@ -583,6 +591,15 @@ def job_state(job_dir):
             os.close(fd)
 
 
+def job_since(job_dir, status):
+    """Return the time used for the job's age, or None when it is missing."""
+    started = parse_utc(read_text(job_path(job_dir, "started_at"), "") or "")
+    if status == "running":
+        return started
+    ended = parse_utc(read_text(job_path(job_dir, "ended_at"), "") or "")
+    return ended or started
+
+
 def socket_path(job_dir):
     """The path of the job's control socket.
 
@@ -719,9 +736,10 @@ def child_env(job_dir, job):
     env = dict(os.environ)
     for key in REMOVED_ENV:
         env.pop(key, None)
-    env["MULTI_AGENT_JOB"] = job_dir
-    env["MULTI_AGENT_DEPTH"] = str(job["depth"])
+    env["PI_MULTI_AGENT_JOB"] = job_dir
+    env["PI_MULTI_AGENT_DEPTH"] = str(job["depth"])
     env["PI_MINIMAL_PERMISSION_SYSTEM_NONINTERACTIVE"] = "1"
+    env["PI_REQUEST_USER_INPUT_NONINTERACTIVE"] = "1"
     env["PWD"] = job["cwd"]
     return env
 
@@ -1309,7 +1327,7 @@ def run_runner(job_dir, lock_fd, server, caller_fd=None):
 
 def caller_depth():
     try:
-        return int(os.environ.get("MULTI_AGENT_DEPTH") or 0)
+        return int(os.environ.get("PI_MULTI_AGENT_DEPTH") or 0)
     except ValueError:
         return 0
 
@@ -1317,12 +1335,12 @@ def caller_depth():
 def check_depth():
     depth = caller_depth()
     try:
-        limit = int(os.environ.get("MULTI_AGENT_MAX_DEPTH") or DEFAULT_MAX_DEPTH)
+        limit = int(os.environ.get("PI_MULTI_AGENT_MAX_DEPTH") or DEFAULT_MAX_DEPTH)
     except ValueError:
         limit = DEFAULT_MAX_DEPTH
     if depth >= limit:
         raise CommandError(
-            f"cannot start an agent: this caller is at depth {depth} and MULTI_AGENT_MAX_DEPTH is {limit}"
+            f"cannot start an agent: this caller is at depth {depth} and PI_MULTI_AGENT_MAX_DEPTH is {limit}"
         )
     return depth + 1
 
@@ -1564,6 +1582,7 @@ def cmd_run(argv):
         if not os.path.isfile(fork):
             raise CommandError(f"--fork: PI_SESSION_FILE does not exist: {fork}")
     depth = check_depth()
+    check_pi_bin()
     profile = find_profile(cwd, args.values.get("--profile") or DEFAULT_PROFILE)
 
     root = jobs_dir(project)
@@ -1576,9 +1595,16 @@ def cmd_run(argv):
         try:
             os.mkdir(os.path.join(root, name))
         except FileExistsError:
+            job_dir = os.path.join(root, name)
+            status = job_state(job_dir)
+            since = job_since(job_dir, status)
+            detail = status
+            if since is not None:
+                event = "started" if status == "running" else "ended"
+                detail += f", {event} {format_age(time.time() - since)} ago"
             raise CommandError(
-                f"job {name} already exists in this project; use `resume {name}` to continue it, pick"
-                f" another --name, or `rm {name}` first"
+                f"job {name} already exists in this project ({detail}); pick another --name. "
+                f"Run `resume {name}` or `rm {name}` only for a job you started or the user asked about."
             )
     else:
         for _attempt in range(100):
@@ -1613,7 +1639,7 @@ def cmd_run(argv):
             "cwd": cwd,
             "project": project,
             "session_dir": session_dir,
-            "parent": os.environ.get("MULTI_AGENT_JOB") or None,
+            "parent": os.environ.get("PI_MULTI_AGENT_JOB") or None,
             "depth": depth,
             "model": model,
             "thinking": thinking,
@@ -1640,6 +1666,7 @@ def cmd_resume(argv):
     prompt = read_message(args, "prompt")
     job_dir = find_job(name)
     check_depth()
+    check_pi_bin()
     # A runner holds the lock while the job runs, so taking it proves that
     # nothing runs, and keeps it so until the new runner holds it.
     lock_fd = job_lock(
@@ -1903,8 +1930,9 @@ def cmd_status(argv):
         ("session_file", sessions[-1] if sessions else "-"),
         (
             "session_cmd",
-            "cd {} && pi --session-dir {} --session-id {}".format(
+            "cd {} && {} --session-dir {} --session-id {}".format(
                 shlex.quote(job.get("cwd", ".")),
+                shlex.quote(pi_bin()),
                 shlex.quote(session_dir),
                 shlex.quote(name),
             ),
@@ -1938,8 +1966,7 @@ def cmd_list(argv):
         job = read_json(job_path(job_dir, "job.json"), {})
         status = job_state(job_dir)
         started = parse_utc(read_text(job_path(job_dir, "started_at"), "") or "")
-        ended = parse_utc(read_text(job_path(job_dir, "ended_at"), "") or "")
-        since = started if status == "running" else (ended or started)
+        since = job_since(job_dir, status)
         if (
             "--all" not in args.flags
             and status != "running"
@@ -1989,8 +2016,7 @@ def cmd_profiles(argv):
     return EXIT_OK
 
 
-def cmd_rm(argv):
-    job_dir = find_job(one_name(Args(argv, (), ()), "rm"))
+def remove_job(job_dir):
     name = os.path.basename(job_dir)
     lock_fd = job_lock(job_dir, f"job {name} is running; kill it first")
     try:
@@ -2002,6 +2028,26 @@ def cmd_rm(argv):
     finally:
         os.close(lock_fd)
     sys.stdout.write(f"removed: {name}\n")
+
+
+def cmd_rm(argv):
+    args = Args(argv, (), ("--all",))
+    if "--all" in args.flags:
+        if args.positional:
+            raise usage_error("rm takes a job name or --all, not both")
+        finished = [d for d in project_jobs(logical_cwd()) if job_state(d) != "running"]
+        if not finished:
+            sys.stdout.write("no jobs to remove in this project\n")
+            return EXIT_OK
+        code = EXIT_OK
+        for job_dir in finished:
+            try:
+                remove_job(job_dir)
+            except CommandError as exc:
+                sys.stdout.write(f"error: {exc}\n")
+                code = EXIT_FAIL
+        return code
+    remove_job(find_job(one_name(args, "rm")))
     return EXIT_OK