@semanaut/zpi-peer 0.1.0 → 0.1.1

package/README.md

@@ -1,19 +1,38 @@
 # @semanaut/zpi-peer
 
-Equal, durable peers in tmux windows plus a letter channel between any pi sessions, for [pi](https://github.com/earendil-works/pi).
+Equal, durable pi peers plus a letter channel between any pi sessions, for [pi](https://github.com/earendil-works/pi).
 
-A session is alive exactly while a live pane carries its `@pi_sid` label. Peers can be spawned, listed, mailed, and revived.
+Peers are equal instances, not subordinates: each runs in its own tmux pane, with its own context, its own token budget, and its own mistakes. tmux is the single source of truth for who is alive — every peer pane carries an `@pi_sid` label, and a session is considered alive exactly while a live pane still holds its label. When the pane dies, the session id goes dark but its history stays durable on disk, so the peer can always be brought back.
 
-## Install
+## Management via tmux
 
-```bash
-pi install npm:@semanaut/zpi-peer
-```
+- **Spawn**: a peer is launched in a new tmux pane with a pre-assigned sessionId. `peer_spawn` returns only once the peer is verifiably up — it waits until the pane carries the `@pi_sid` label, and reports a failure instead of a sid that never booted.
+- **Liveness**: `@pi_sid` pane labels are the liveness signal. Killing the pane (or the whole window) ends the peer; the session file remains on disk.
+- **Revive**: a dark session is restarted with `pi --session <sid>` in a fresh pane, restoring its full history. The sid becomes disk-durable once the peer submits its first message; a peer killed before that cannot be resumed.
+- **Normal tmux workflow works**: switch panes/windows, watch a peer work live in its pane, kill it with tmux when done.
 
-## Requires
+## The three tools
 
-tmux.
+- **`peer_spawn`** — launch an equal peer in a tmux pane; optional role-prompt file and fork/handoff context.
+- **`peer_list`** — list sessions and their liveness, filterable by creator ("self" = your own peers).
+- **`peer_send_mail`** — deliver a letter to any pi session's mailbox, peers and human-started alike.
+
+## Automatic revival
+
+Mailing a dead recipient revives it automatically: the letter is delivered by first relaunching the session via `pi --session <sid>` in a new tmux pane, waiting (up to ~25s) until the pane is verifiably up, then injecting the notice — a running session gets it within ~1.5s (steer while running, followUp when idle). If the revive fails, the letter stays queued and is read at the next start. The mechanism never bypasses pi's own resume logic: no label within the budget (pi exited, or waits at an interactive prompt) counts as a failure.
+
+## Bundled role prompts
+
+Three standard role prompts ship with the package. Pass one as `peer_spawn`'s `prompt` parameter to give a peer a persistent role:
+
+- **scout** — fast reconnaissance. Maps unknown territory: key directories, entry points, one-line file descriptions. It locates, it does not analyze deeply, and it states its interpretation when the task is ambiguous.
+- **researcher** — directed research. Produces a sourced findings brief on a question that cannot be answered from the code alone; every conclusion cites a file path or URL.
+- **critic** — independent review. An unpolluted second opinion on a plan, diff, or conclusion: answers VERDICT (agree / agree-with-changes / object) plus numbered findings by severity, each with quoted evidence and a concrete suggestion. It never rubber-stamps.
+
+All three are read-only by intent: peers launch with the full toolset, and discipline comes from the role file and the task text, not from restrictions. A peer can always mail back.
+
+On every start the extension mirrors the role files into the peer data directory (`<agent dir>/peer/roles`); an edited or older copy is preserved as `<name>.backup` before the bundled version is written, so local edits survive and upgrades still land. Any other file path works for a custom role.
 
 ## Bundled skill
 
-Installs the `peer-orchestrator` skill (policy for spawning and steering equal pi peers) alongside the extension.
+Installs the `peer-orchestrator` skill alongside the extension: the policy for when to spawn peers (only for genuinely parallel, independent work), how to write a self-contained first task, how to choose a peer's starting context, and how to batch follow-up letters.

package/extensions/zpi-peer.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
 import { getAgentDir, SessionManager, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
@@ -165,6 +166,29 @@ async function waitForBoot(
 
 const registryDir = () => path.join(getAgentDir(), "peer", "registry");
 
+const peerRolesDir = () => path.join(getAgentDir(), "peer", "roles");
+const BUNDLED_ROLES = ["AGENTS.scout.md", "AGENTS.researcher.md", "AGENTS.critic.md"];
+const bundledRolesDir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "roles");
+
+/** Mirror the bundled role files into the peer data directory. An edited or older copy is kept as
+ * `<name>.backup` before the bundled version is written, so every start reconciles the roles. */
+function syncRoles(): void {
+	try {
+		const dir = peerRolesDir();
+		fs.mkdirSync(dir, { recursive: true });
+		for (const name of BUNDLED_ROLES) {
+			const src = path.join(bundledRolesDir, name);
+			const dst = path.join(dir, name);
+			const bundled = fs.readFileSync(src);
+			if (fs.existsSync(dst)) {
+				if (fs.readFileSync(dst).equals(bundled)) continue;
+				fs.renameSync(dst, `${dst}.backup`);
+			}
+			fs.copyFileSync(src, dst);
+		}
+	} catch {}
+}
+
 /** Expand a leading ~/ — fs.* and pi's prompt resolution do not. */
 function expandPath(p: string): string {
 	if (p === "~") return os.homedir();
@@ -392,6 +416,10 @@ async function revivePeer(pi: ExtensionAPI, sid: string, cwd: string, signal?: A
 }
 
 export default function piPeer(pi: ExtensionAPI) {
+	syncRoles();
+	const roleDir = peerRolesDir();
+	const ROLE_HINT = `Standard roles live in ${roleDir}: AGENTS.scout.md (fast reconnaissance), AGENTS.researcher.md (directed research), AGENTS.critic.md (independent review).`;
+
 	// On a revive the role must be resolved before any pending letter can start a turn —
 	// session_start does both, in that order.
 
@@ -451,7 +479,7 @@ export default function piPeer(pi: ExtensionAPI) {
 		name: "peer_spawn",
 		label: "Spawn peer",
 		description:
-			`Spawn an equal pi peer in a tmux pane with a pre-assigned sessionId. ${SKILL_GATE} It returns only once the peer is verifiably up — it blocks up to ~${SPAWN_BOOT_TIMEOUT_MS / 1000}s until the peer labels the pane it was given, and reports a failure instead of handing back a sid that never booted. The returned sid becomes disk-durable a few seconds after return, when the peer submits its first message (pi persists the session file then, not at boot); a peer killed before that leaves no session — its sid goes dark (mail queues, resume reports not found). The task is delivered at launch as the peer's first user message. Use peer_send_mail for follow-up letters. prompt: path to a role file that stays with the peer across every start — standard role files: ~/.pi/agent/AGENTS.critic.md, ~/.pi/agent/AGENTS.researcher.md, ~/.pi/agent/AGENTS.scout.md (the peer-orchestrator skill describes what each role does). context: omit = empty | fork:<sessionId> = fork that session's full history, and the forked peer also inherits its role unless prompt overrides it | handoff:<text> = custom context text (prepended to the first message).`,
+			`Spawn an equal pi peer in a tmux pane with a pre-assigned sessionId. ${SKILL_GATE} It returns only once the peer is verifiably up — it blocks up to ~${SPAWN_BOOT_TIMEOUT_MS / 1000}s until the peer labels the pane it was given, and reports a failure instead of handing back a sid that never booted. The returned sid becomes disk-durable a few seconds after return, when the peer submits its first message (pi persists the session file then, not at boot); a peer killed before that leaves no session — its sid goes dark (mail queues, resume reports not found). The task is delivered at launch as the peer's first user message. Use peer_send_mail for follow-up letters. prompt: path to a role file that stays with the peer across every start — ${ROLE_HINT} The peer-orchestrator skill describes what each role does; any other file path works for a custom role. context: omit = empty | fork:<sessionId> = fork that session's full history, and the forked peer also inherits its role unless prompt overrides it | handoff:<text> = custom context text (prepended to the first message).`,
 		promptGuidelines: [
 			"Use peer_spawn only when the user asked for parallel/independent work or a task clearly warrants a separate context; every letter sent via peer_send_mail costs the recipient one LLM turn.",
 		],
@@ -461,7 +489,7 @@ export default function piPeer(pi: ExtensionAPI) {
 			prompt: Type.Optional(
 				Type.String({
 					description:
-						"Path to a role-prompt file (errors if it does not exist). The role stays with the peer across every start — spawn, mail revive, or a user-run /resume — and the file is re-read per turn, so editing it takes effect without respawning. Identity follows the session: /new inside a peer's pane starts a plain session, while a fork inherits the role of the session it branched from unless this overrides it. Standard roles: ~/.pi/agent/AGENTS.critic.md, ~/.pi/agent/AGENTS.researcher.md, ~/.pi/agent/AGENTS.scout.md; omit for a plain peer.",
+						"Path to a role-prompt file (errors if it does not exist). The role stays with the peer across every start — spawn, mail revive, or a user-run /resume — and the file is re-read per turn, so editing it takes effect without respawning. Identity follows the session: /new inside a peer's pane starts a plain session, while a fork inherits the role of the session it branched from unless this overrides it. ${ROLE_HINT} Any other file path works for a custom role; omit for a plain peer.",
 				}),
 			),
 			context: Type.Optional(

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@semanaut/zpi-peer",
-  "version": "0.1.0",
-  "description": "pi extension: equal, durable peers in tmux windows plus a letter channel between any pi sessions",
+  "version": "0.1.1",
+  "description": "pi extension: equal, durable pi peers managed through tmux panes plus a letter channel between any pi sessions. Tools: peer_spawn (launch a peer in a tmux pane), peer_list (list peers, alive or exited), peer_send_mail (deliver a letter, reviving dead recipients). Ships scout / researcher / critic role prompts",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -9,6 +9,7 @@
   "license": "MIT",
   "files": [
     "extensions",
+    "roles",
     "skills"
   ],
   "pi": {

package/roles/AGENTS.critic.md

@@ -0,0 +1,9 @@
+You are an independent critic peer in a flat network of equal pi instances.
+
+Rules:
+1. Read-only. Your value is an unpolluted second opinion, not execution.
+2. Judge against evidence: quote the exact file/line or message you object to.
+3. Structure verdicts as: VERDICT (agree / agree-with-changes / object), then numbered
+   findings ordered by severity, each with evidence and a concrete suggestion.
+4. Send your verdict to the requester's inbox with peer_send_mail; sign with name, role, sessionId.
+5. Do not rubber-stamp. If you find nothing wrong, say what you checked and why it holds.

package/roles/AGENTS.researcher.md

@@ -0,0 +1,10 @@
+You are a read-only research peer in a flat network of equal pi instances.
+
+Rules:
+1. Do not modify files or run commands with side effects.
+2. Every conclusion must cite its source (file path or URL).
+3. When done, send your findings brief to the requester's inbox with peer_send_mail:
+   sign the letter with your name, role and sessionId, and state that it is a result report.
+4. If you are missing information, ask by letter: state clearly that the letter is a question,
+   ask exactly one question, and give the sessionId your reply should be sent to.
+5. You are an equal peer, not a subordinate: push back with evidence if the task looks wrong.

package/roles/AGENTS.scout.md

@@ -0,0 +1,9 @@
+You are a scout peer in a flat network of equal pi instances.
+
+Rules:
+1. Read-only and fast: locate, don't analyze in depth.
+2. Produce a map: key directories, entry points, relevant files with one-line descriptions,
+   and where the answers to the task's questions live.
+3. Every pointer must be a real path you verified exists.
+4. Send the map to the requester's inbox with peer_send_mail; sign with name, role, sessionId.
+5. If the task is ambiguous, make the most useful reasonable interpretation and state it.

package/skills/peer-orchestrator/SKILL.md

@@ -71,12 +71,16 @@ peer when a new one is needed.
 All three are read-only by intent. Peers launch with the full toolset; discipline comes from the
 role file and your task text, not from restrictions. A peer can always mail you back.
 
-- `~/.pi/agent/AGENTS.scout.md` — fast reconnaissance. Use it to map unknown territory: key
+Pass the path of the role file you want to `peer_spawn`'s prompt parameter; the exact paths of
+the three standard roles are given in the peer_spawn tool description. For a custom role, pass
+the path of any other role file instead.
+
+- scout — fast reconnaissance. Use it to map unknown territory: key
   directories, entry points, one-line file descriptions. It locates, it does not analyze deeply,
   and it states its interpretation when your task is ambiguous.
-- `~/.pi/agent/AGENTS.researcher.md` — directed research. Use it for a sourced findings brief on a
+- researcher — directed research. Use it for a sourced findings brief on a
   question you could not answer from the code alone; every conclusion cites a file path or URL.
-- `~/.pi/agent/AGENTS.critic.md` — independent review. Use it for an unpolluted second opinion on a
+- critic — independent review. Use it for an unpolluted second opinion on a
   plan, diff, or conclusion of yours; it answers VERDICT (agree / agree-with-changes / object)
   plus numbered findings by severity, each with quoted evidence and a concrete suggestion. It
   never rubber-stamps — give it the artifact, not your defense of it.