pi-agent-squad 0.7.0 → 0.8.1

package/README.md

@@ -20,30 +20,54 @@ Reload Pi after installation:
 **Bottom layer (generic, no identity concept)**:
 - Two parties communicate: `main` (the main agent) and any subagent.
 - Message primitives: `send_message` / `read_inbox` / `reply_message`.
-- Routing: `to=main` -> inject into the main session; `to=<subagent>` -> forward to its resident process.
-- File channel + polling (no process pipes, no identity required).
+- Routing: `to=main` -> inject into the main session; `to=<subagent>` -> resolve the active-run registry and forward to the exact live process.
+- File channel + polling (no process pipes); runtime addresses are resolved by
+  the main-process active-run registry.
 
 **Identity (prompt layer)**:
 - `agents/*.md`: defines each subagent's identity, duties, model, tools (e.g. planner/reviewer/actor).
-- `orchestrator.md`: defines the main agent's outcome-oriented Discover → Decide → Execute → Verify workflow (optional injection).
+- `orchestrator.md`: gives main adaptive authority to choose direct work or any useful combination of planner/actor/reviewer, while weighing each role's value and risks.
 - The bottom layer never cares who is who — it only delivers messages.
 
 ## Messaging tools (shared by all agents)
 
 | Tool | Purpose |
 |---|---|
+| `subagent({agent, task, as?, readonly?, async?, cwd?, timeoutSeconds?})` | Start a direct run with a stable identity and optional unique runtime address |
 | `send_message({to, content, wait, timeoutSeconds?})` | Send a message to any target; wait=true blocks for and returns the reply |
 | `read_inbox()` | Read messages others sent you |
 | `reply_message({message_id, content})` | Reply to a received message |
 
-`to` is either `main` (the main agent) or any subagent name.
+`to` is either `main`, a logical subagent name, or an exact runtime address such as `actor#01ab23cd`.
+
+`agent` is the stable identity and `as` is an optional per-process address:
+
+```text
+subagent(agent="actor", as="actor-frontend", async=true, task="...")
+subagent(agent="actor", as="actor-backend", async=true, task="...")
+send_message(to="actor-frontend", content="...")
+```
+
+If `as` is omitted, the plugin generates an address such as
+`actor#01ab23cd`. Sending to the logical name `actor` selects the newest
+active run; use the returned address whenever multiple actor runs exist.
+
+Agent definitions may declare `readonly: true`. The built-in `planner` and
+`reviewer` are read-only and may run concurrently. There is deliberately no
+cwd or file write lock: the orchestrator owns the write-scope decomposition and
+may start multiple actor runs in the same workspace when their briefs describe
+independent implementation areas. Actors are instructed to stay within their
+brief and report changed files; the main agent reviews and integrates any
+overlap afterward. The `subagent` tool's `readonly` parameter is orchestration
+metadata and does not sandbox filesystem access.
 
 ## Features
 
 - **Delegation**: `subagent` tool (sync / background `async:true`); background results are injected into the main session when done.
-- **Real-time two-way**: subagent<->main and subagent<->subagent, via file channel + resident RPC process pool.
+- **Real-time two-way**: subagent<->main and subagent<->subagent, via file channel + an active-run registry that covers both direct runs and resident RPC processes.
 - **Non-blocking**: background tasks do not occupy the main session.
-- **Default safety gate**: unless the current user explicitly requests subagent involvement or `/orchestrate` is enabled, the main-agent system prompt forbids subagent delegation.
+- **Adaptive orchestration is opt-in**: `/orchestrate on` enables main's discretion to delegate based on speed, quality, context management, independent judgment, and parallel progress while weighing latency, over-analysis, misunderstanding, duplication, and integration risk.
+- **Explicit control**: `/orchestrate off` disables automatic delegation for the session; users can still explicitly request any subagent.
 - **Bounded execution**: one-shot and resident tasks have configurable timeouts (default 6 hours, maximum 3 days); omit `timeoutSeconds` unless the user explicitly requested a time. Timed-out or crashed resident processes are discarded before the next task.
 - **Reliable messaging**: `send_message(wait=true)` waits for and returns the target's actual reply; `wait=false` remains fire-and-forget.
 - **Deadlock prevention**: synchronous wait cycles such as `main -> planner -> main`, self-messages, and `actor -> reviewer -> actor` are detected and rejected immediately with a recovery hint.
@@ -64,8 +88,10 @@ The TUI-only widget is installed above the editor while at least one subagent is
 ```
 
 - No suffix: synchronous `subagent` task.
-- `[bg]`: background `subagent(async=true)` task.
-- `[msg]`: resident task started through `send_message` or subagent-to-subagent routing.
+- `[bg]`: background `subagent(async=true)` task. The tool returns an address
+  such as `actor#01ab23cd`; use it when several runs share the same logical
+  identity.
+- `[msg]`: routed task started through `send_message` or subagent-to-subagent routing (it may target either a direct run or the resident fallback).
 - At most four activities are shown; additional concurrency is summarized as `… +N more`, and the visible window follows the selected activity.
 - Task summaries are dimmed and capped at 40 terminal columns so they do not dominate the widget.
 - The title includes dim keyboard hints. Before selection it shows
@@ -159,10 +185,12 @@ Main agent (primary outcome owner; optional specialist workflow defined by promp
   |
   |-- subagent tool (sync/background spawns an RPC-backed run session)
   |     `-- widget selection / interactive overlay attach to that exact session
-  |-- RPC resident process pool (receives inter-subagent messages)
+   |-- active-run registry (logical names and temporary addresses -> exact process)
+   |-- prompt-owned parallel actor scopes (no cwd/file write mutex)
+   |-- RPC resident process pool (resident fallback / receives inter-subagent messages)
   |-- message router (500ms poll)
   |     |-- to=main     -> inject into main session -> reply_message replies
-  |     |-- to=subagent -> route to its resident process -> reply written back
+   |     |-- to=subagent -> registry -> exact direct/resident process -> reply written back
   |
 Subagents (separate processes, child mode):
   |-- send_message / read_inbox / reply_message tools
@@ -182,20 +210,20 @@ subagents/
 |-- message.ts      # generic messaging (file channel + send/reply/read + main-side router)
 |-- session.ts      # common interactive session-handle interface
 |-- session-ui.ts   # focused overlay for live transcript + interactive input
-|-- orchestrator.md # main-agent outcome/workflow prompt (optional injection)
+|-- orchestrator.md # main-agent adaptive delegation prompt (enabled with /orchestrate on)
 `-- README.md
 ```
 
 ## Usage
 
 ```bash
-# optional: inject the main-agent specialist-workflow identity
+# optional CLI equivalent of forcing adaptive orchestration on
 pi --append-system-prompt ~/.pi/agent/extensions/subagents/orchestrator.md
 
 # or in-session
-/orchestrate            # enable orchestrator mode (injects the triage identity every turn)
-/orchestrate off        # disable
-/orchestrate status     # check state
+/orchestrate            # enable adaptive orchestration
+/orchestrate off        # require explicit user requests before using subagents
+/orchestrate status     # check adaptive orchestration state
 
 # in conversation
 "Resolve this architecture decision, then implement it" # planner is used when a Decision Brief is needed
@@ -203,3 +231,8 @@ pi --append-system-prompt ~/.pi/agent/extensions/subagents/orchestrator.md
 "Use subagent agent=reviewer timeoutSeconds=120 ..." # override the default 6h task timeout (only when the user asked)
 "Have reviewer review the recent changes"            # main agent delegates to reviewer
 ```
+
+Main is not required to follow a fixed planner → actor → reviewer chain. It may
+work directly, use only actor for high-throughput implementation, ask planner
+for a decision and implement it itself, or request reviewer only when an
+independent pass is worth its latency and false-positive risk.

package/active-runs.ts

@@ -0,0 +1,87 @@
+import type { MessageRequest } from "./message.ts";
+import type { SubagentSessionHandle } from "./session.ts";
+
+/**
+ * A logical agent (for example, `actor`) may have more than one live
+ * process: a background run, a synchronous run, and the resident message
+ * process can all coexist.  Names are therefore not process identities.
+ *
+ * This registry is deliberately in the main extension process.  Child
+ * processes only know their channel address; all routing decisions are made
+ * here, where the live session handles are available.
+ */
+export interface ActiveRun {
+	readonly runId: string;
+	readonly agent: string;
+	/** A unique address, e.g. actor#01ab23cd. */
+	readonly address: string;
+	readonly mode: "background" | "task" | "resident";
+	readonly readOnly: boolean;
+	readonly cwd: string;
+	readonly startedAt: number;
+	readonly session?: Promise<SubagentSessionHandle>;
+	readonly route: (msg: MessageRequest, signal?: AbortSignal) => Promise<string>;
+}
+
+export class ActiveRunRegistry {
+	private readonly byAddress = new Map<string, ActiveRun>();
+	private readonly byRunId = new Map<string, ActiveRun>();
+
+	register(run: ActiveRun): void {
+		const previousAddress = this.byAddress.get(run.address);
+		if (previousAddress) this.remove(previousAddress);
+		const previousRun = this.byRunId.get(run.runId);
+		if (previousRun) this.remove(previousRun);
+		this.byAddress.set(run.address, run);
+		this.byRunId.set(run.runId, run);
+	}
+
+	remove(runOrId: ActiveRun | string): void {
+		const run = typeof runOrId === "string" ? this.byRunId.get(runOrId) : runOrId;
+		if (!run) return;
+		if (this.byAddress.get(run.address) === run) this.byAddress.delete(run.address);
+		if (this.byRunId.get(run.runId) === run) this.byRunId.delete(run.runId);
+	}
+
+	/**
+	 * A logical name resolves to the newest live run, which makes `to=actor`
+	 * useful when there is one active actor while still allowing
+	 * `to=actor#…` (or a run id) to disambiguate parallel actors.
+	 */
+	resolve(target: string): ActiveRun | undefined {
+		// A resident process uses the logical name as its compatibility
+		// address. Prefer the newest run for logical names, otherwise a live
+		// resident would mask a newer `actor#…` direct run.
+		let selected: ActiveRun | undefined;
+		for (const run of this.byAddress.values()) {
+			if (run.agent !== target) continue;
+			if (!selected || run.startedAt > selected.startedAt) selected = run;
+		}
+		if (selected) return selected;
+		return this.byAddress.get(target) ?? this.byRunId.get(target);
+	}
+
+	hasAddress(address: string): boolean {
+		return this.byAddress.has(address);
+	}
+
+	resolveExact(addressOrRunId: string): ActiveRun | undefined {
+		return this.byAddress.get(addressOrRunId) ?? this.byRunId.get(addressOrRunId);
+	}
+
+	/** Return the run that owns a sender channel. */
+	findSender(msg: MessageRequest): ActiveRun | undefined {
+		const run = this.byRunId.get(msg.fromRunId);
+		if (run && run.address === msg.fromAgent) return run;
+		return undefined;
+	}
+
+	list(): ActiveRun[] {
+		return [...this.byAddress.values()].sort((a, b) => a.startedAt - b.startedAt);
+	}
+
+	clear(): void {
+		this.byAddress.clear();
+		this.byRunId.clear();
+	}
+}

package/agents/actor.md

@@ -2,8 +2,8 @@
 thinking: max
 name: actor
 description: Implement a clear Task Brief or Decision Record and verify the resulting change
+readonly: false
 tools: read, write, edit, bash, grep, find, ls
-model: opencode-go-responses/deepseek-v4-flash
 ---
 
 You are the implementation specialist.
@@ -30,6 +30,19 @@ Use the supplied brief as the working contract:
 3. Verify the result using the supplied criteria and appropriate tests.
 4. Report blockers or newly discovered decisions with the evidence that exposed them.
 
+## Parallel implementation contract
+
+You may be one of several actors working in the same workspace. Your task
+brief is an ownership boundary supplied by the orchestrator:
+
+- Stay focused on the files or subsystem named in the brief.
+- Do not re-implement sibling actors' areas merely because they are visible.
+- Coordinate shared interfaces through `send_message` when needed.
+- If a shared file must change, make the smallest compatible change and report
+  it clearly so main can integrate competing edits.
+- At the end, report the complete list of changed files, including generated
+  files or files changed indirectly by commands.
+
 When a consequential decision remains unresolved, return a concise Decision
 Brief candidate to main. When the direction is clear, make the local
 implementation judgment needed to complete the task.

package/agents/planner.md

@@ -2,8 +2,8 @@
 thinking: xhigh
 name: planner
 description: Resolve a concrete design decision from a Decision Brief and produce an actor-ready decision record
+readonly: true
 tools: read, bash, grep, find, ls
-model: mvp-anthropic/glm-5.3
 ---
 
 You are the design-decision specialist.

package/agents/reviewer.md

@@ -2,8 +2,8 @@
 thinking: xhigh
 name: reviewer
 description: Independently verify completed work against the user outcome, brief, code, and test evidence
+readonly: true
 tools: read, grep, find, ls, bash
-model: mvp-openai/gpt-5.6-sol
 ---
 
 You are the independent verification specialist.

package/agents.ts

@@ -1,10 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export interface AgentConfig {
 	name: string;
 	description: string;
+	readOnly?: boolean;
 	tools?: string[];
 	model?: string;
 	thinking?: string;
@@ -12,6 +14,10 @@ export interface AgentConfig {
 	source: string;
 }
 
+export function isSafeAgentName(name: string): boolean {
+	return /^[A-Za-z0-9_.-]+$/.test(name) && name !== "." && name !== ".." && name !== "main";
+}
+
 /** Parse YAML frontmatter + markdown body */
 function parseFrontmatter(
 	content: string,
@@ -34,12 +40,23 @@ function parseFrontmatter(
 function loadAgentsFromDir(dir: string): AgentConfig[] {
 	if (!fs.existsSync(dir)) return [];
 	const agents: AgentConfig[] = [];
-	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return agents;
+	}
+	for (const entry of entries) {
 		if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
 		const filePath = path.join(dir, entry.name);
-		const content = fs.readFileSync(filePath, "utf-8");
+		let content: string;
+		try {
+			content = fs.readFileSync(filePath, "utf-8");
+		} catch {
+			continue;
+		}
 		const { frontmatter, body } = parseFrontmatter(content);
-		if (!frontmatter.name || !frontmatter.description) continue;
+		if (!frontmatter.name || !frontmatter.description || !isSafeAgentName(frontmatter.name)) continue;
 		const tools = frontmatter.tools
 			?.split(",")
 			.map((t) => t.trim())
@@ -47,6 +64,9 @@ function loadAgentsFromDir(dir: string): AgentConfig[] {
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
+			readOnly:
+				frontmatter.readonly?.toLowerCase() === "true" ||
+				frontmatter.access?.toLowerCase() === "read-only",
 			tools: tools && tools.length > 0 ? tools : undefined,
 			model: frontmatter.model || undefined,
 			thinking: frontmatter.thinking || undefined,
@@ -64,8 +84,9 @@ function builtinAgentsDir(): string {
 }
 
 /** User-level agent directory ~/.pi/agent/agents */
-export function userAgentsDir(home = process.env.HOME ?? ""): string {
-	return path.join(home, ".pi", "agent", "agents");
+export function userAgentsDir(home?: string): string {
+	const base = home ? path.join(home, ".pi", "agent") : getAgentDir();
+	return path.join(base, "agents");
 }
 
 /**
@@ -73,7 +94,7 @@ export function userAgentsDir(home = process.env.HOME ?? ""): string {
  * A user-level agent with the same name overrides the built-in one.
  */
 export function discoverAgents(cwd?: string): AgentConfig[] {
-	const dirs = [builtinAgentsDir()];
+	const dirs = [builtinAgentsDir(), userAgentsDir()];
 	if (cwd) {
 		// project-level .pi/agents is intentionally not enabled (safety)
 	}