@tshu-w/pi-agents 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.4.1] - 2026-11-04
+
+### Added
+
+- `pd main --name <name>` opens a main Agent per name, so that each channel can have its own.
+
+### Changed
+
+- Inputs answered by the same turn share one notification.
+
 ## [0.4.0] - 2026-11-04
 
 ### Added

package/bin/pd.mjs

@@ -155,20 +155,24 @@ function headlessMode() {
   if (!interactive || parsed.print) return 'text';
 }
 
-/** Opens the main Agent that `main.json` names, from any directory, or starts one in `~` if there is none. */
+/** Opens the main Agent of the entry `--name` picks (default `main`), from any directory, or starts one in `~` if there is none. */
 async function openMain() {
-  const options = args.slice(1);
+  const name = parseArgs(args.slice(1)).name ?? 'main';
+  // `--name` picks the entry, so it does not rename the Session.
+  const options = argGroups(parseArgs, args.slice(1)).filter(([option]) => !['--name', '-n'].includes(option)).flat();
   let file;
-  try { file = JSON.parse(readFileSync(paths.mainSession, 'utf8')).sessionFile; }
-  catch (failure) { if (failure.code !== 'ENOENT') throw failure; }
+  // `main.json` maps entry names to Session files; an old one holds `{ sessionFile }` for `main`.
+  try {
+    const entries = JSON.parse(readFileSync(paths.mainSession, 'utf8'));
+    file = typeof entries.sessionFile === 'string' ? { main: entries.sessionFile }[name] : entries[name];
+  } catch (failure) { if (failure.code !== 'ENOENT') throw failure; }
   // A main Agent without messages has no file yet, but its host may be running.
   const holds = host => hostSessionFile(host) === file;
   if (file && (existsSync(file) || (await settledHosts(paths, holds)).some(holds))) args = ['--session', file, ...options];
   else {
     process.chdir(homedir());
-    // These go first, as messages may follow `--`, and `--main` before a message would take it as its value.
-    // A `--name` among the options comes later and wins.
-    args = ['--main', '--name', 'main', ...options];
+    // These go first, as messages may follow `--`; with `=`, `--main` takes no other argument as its value.
+    args = [`--main=${name}`, '--name', name, ...options];
   }
   parsed = parseArgs(args);
 }

package/docs/HOSTS.md

@@ -16,7 +16,7 @@ Files live in `${XDG_STATE_HOME:-~/.local/state}/pi/agents/`:
 
 - `workbench.json`: seen marks and which Sessions are listed.
 - `host.log`, `daemon.log`: logs.
-- `main.json`: which Session is the main Agent.
+- `main.json`: which Session is the main Agent of each entry name.
 
 Sockets and Session locks go in `$XDG_RUNTIME_DIR/pi-agents/`. macOS has no `XDG_RUNTIME_DIR`, so there they go in `runtime/` under the state directory.
 
@@ -36,7 +36,7 @@ pi install "$(npm root -g)/@tshu-w/pi-agents"
 - `pd [pi options]` starts Pi interactively in a new host and attaches the terminal. If the Session is already running in a host, `pd` attaches to it instead, sending it the messages as follow-ups and ignoring other options.
 - `pd agents` opens the workbench.
 - `pd attach <session>` attaches to a Session, starting it first if it is not running.
-- `pd main [pi options]` opens the main Agent, which hands work to other Agents, from any directory; `/new` in it starts a new one.
+- `pd main [--name <name>] [pi options]` opens the main Agent for `<name>` (default `main`), which hands work to other Agents, from any directory; `/new` in it starts a new one.
 - Non-interactive starts (`-p`, `--mode json`, `--mode rpc`, piped stdin) work as in Pi, on the Session in a host, so several of them and an attached terminal can use one Session at once. Their commands act on that Session, as `abort` stops whichever turn is running. Unlike Pi:
   - Dialogs are not sent to them. A dialog waits while a terminal is attached and is cancelled otherwise.
   - Extensions see interactive mode, so what an extension writes to stdout does not reach them; `/program` prints as with `pi -p`.

package/docs/SPEC.md

@@ -38,7 +38,7 @@ When the user of a root Agent clears its queued messages, messages from other Ag
 
 ### 2.3 wait
 
-`wait` waits until owned Agents have answered the inputs sent to them. It can target specific Agents and take a timeout.
+`wait` waits until owned Agents have finished the inputs sent to them. It can target specific Agents and take a timeout.
 
 ### 2.4 list
 
@@ -52,11 +52,11 @@ When the user of a root Agent clears its queued messages, messages from other Ag
 
 An Agent is `running` while a turn is in progress, `waiting` while its turn waits in `wait` (§4), `queued` while its next turn waits for a slot (§4), and `idle` otherwise. An Agent goes offline when its runtime unloads it; it stays `idle`.
 
-`send` returns once the recipient's runtime accepts the message, waking it if needed. Acceptance does not mean the recipient has handled it; a message not yet handled is lost if the recipient exits.
+`send` returns once the recipient's runtime accepts the message, waking it if needed. Acceptance does not mean the recipient has handled it (§10).
 
 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 unfinished inputs end as `aborted`. They return as `idle` when their owner is loaded again.
+Owned Agents run independently of their owner's turns and go offline with it (§10). They return as `idle` when their owner is loaded again.
 
 On abort or when going offline, work that has not stopped within a timeout is abandoned: it no longer counts as live work and may keep running until the process exits; the timeout is reported.
 
@@ -76,7 +76,7 @@ An input is outstanding from acceptance until its turn ends or it is withdrawn.
 
 An input sent to an owned Agent ends as `completed` when its turn answers it, `failed` when its turn fails, or `aborted` when it is aborted or withdrawn. Its result is the answer or the error. Only inputs from the owner have results; the recipient replies to other senders with `send`.
 
-When an input ends, its owner receives a notification carrying the result, unless the owner aborted it or is going offline. The notification is an input delivered as `steer` (a write after the owner's turn is stopped, §2.2).
+When an input ends, its owner receives a notification carrying the result, unless the owner aborted it or is going offline. Inputs that a turn ends with the same outcome and result share one notification. The notification is an input delivered as `steer` (a write after the owner's turn is stopped, §2.2).
 
 `wait` ends when the Agents it waits for have no pending inputs, when its timeout expires, or when a steer input arrives; a write does not end it. Their notifications are held until it ends, then delivered as one.
 
@@ -362,3 +362,10 @@ Invalid settings produce a startup warning, and the defaults are used.
 Each Agent is a persistent Pi Session. A root Agent is an ordinary Session. An owned Agent is a child Session that records its owner and root, and runs 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 (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 startup, Pi reports it and exits.
+
+## 10. Limitations
+
+In this version:
+
+- A message accepted but not yet handled is lost if the recipient exits.
+- When an owner goes offline, its owned Agents go offline too, from the bottom of the tree up, and their unfinished inputs end as `aborted`, as do inputs unfinished when a process exits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tshu-w/pi-agents",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Multi-agent runtime for Pi: persistent async agents, dynamic workflows, and inter-agent messaging",
   "license": "AGPL-3.0-only",
   "repository": {

package/src/agents/agents.ts

@@ -549,7 +549,7 @@ export class Agents {
 		const turn = agent.turn;
 		if (!turn && agent.queue.length === 0) return false;
 		if (silent) for (const input of [...agent.queue, ...(turn?.inputs ?? [])]) input.silent = true;
-		for (const input of agent.queue.splice(0)) this.end(agent, input, "aborted", "");
+		this.end(agent, agent.queue.splice(0), "aborted", "");
 		this.changed();
 		if (turn) await this.stop(agent, turn, deadline);
 		return true;
@@ -560,7 +560,7 @@ export class Agents {
 		const index = agent.queue.indexOf(input);
 		if (index !== -1) {
 			agent.queue.splice(index, 1);
-			this.end(agent, input, "aborted", "");
+			this.end(agent, [input], "aborted", "");
 			this.changed();
 		} else if (agent.turn?.inputs.includes(input)) {
 			await this.stop(agent, agent.turn, Date.now() + SHUTDOWN_TIMEOUT_MS);
@@ -736,31 +736,40 @@ export class Agents {
 		turn.finished = true;
 		if (turn.slot) scheduler.release(this.self.rootId, agent.record.id);
 		if (agent.turn === turn) agent.turn = undefined;
-		for (const input of turn.inputs) this.end(agent, input, answer.outcome, answer.result);
+		this.end(agent, turn.inputs, answer.outcome, answer.result);
 		turn.done.resolve();
 		this.changed();
 		this.pump(agent);
 	}
 
-	private end(agent: Owned, input: Input, outcome: Outcome, result: string): void {
-		if (input.permit) scheduler.releaseOutstanding(this.self.rootId, input.permit);
-		input.permit = undefined;
-		const record = input.record;
-		if (!record || ended(record)) return;
-		if (input.schema !== undefined && outcome !== "aborted") {
-			if (input.submitted) {
-				outcome = "completed";
-				record.value = input.submitted.value;
-			} else if (outcome === "completed") {
-				outcome = "failed";
-				result = `The turn ended without calling ${SUBMIT_RESULT_TOOL_NAME}.`;
+	/** Ends inputs together; those that end with the same state and result share one notification. */
+	private end(agent: Owned, inputs: Input[], outcome: Outcome, result: string): void {
+		const answers = new Map<string, InputRecord>();
+		let changed = false;
+		for (const input of inputs) {
+			if (input.permit) scheduler.releaseOutstanding(this.self.rootId, input.permit);
+			input.permit = undefined;
+			const record = input.record;
+			if (!record || ended(record)) continue;
+			changed = true;
+			record.state = outcome;
+			record.result = result;
+			if (input.schema !== undefined && outcome !== "aborted") {
+				if (input.submitted) {
+					record.state = "completed";
+					record.value = input.submitted.value;
+				} else if (outcome === "completed") {
+					record.state = "failed";
+					record.result = `The turn ended without calling ${SUBMIT_RESULT_TOOL_NAME}.`;
+				}
 			}
+			input.done?.resolve();
+			if (input.silent) continue;
+			const key = JSON.stringify([record.state, record.result]);
+			if (!answers.has(key)) answers.set(key, record);
 		}
-		record.state = outcome;
-		record.result = result;
-		this.persist(agent);
-		input.done?.resolve();
-		if (!input.silent) this.notifyLater(agent, record);
+		if (changed) this.persist(agent);
+		for (const record of answers.values()) this.notifyLater(agent, record);
 	}
 
 	private notifyLater(agent: Owned, record: InputRecord): void {

package/src/main-agent.ts

@@ -7,21 +7,22 @@ import { statePaths } from "./roots/paths.mjs";
 export const MAIN_FLAG = "main";
 const instructions = readFileSync(new URL("./main-agent.md", import.meta.url), "utf8").trim();
 
-/** The main Agent's Session file, as `main.json` names it. */
-function mainSessionFile(): string | undefined {
+/** The main Agents' Session files by entry name, as `main.json` maps them; an old `{ sessionFile }` is the entry `main`. */
+function mainEntries(): Record<string, string> {
 	try {
-		return (JSON.parse(readFileSync(statePaths().mainSession, "utf8")) as { sessionFile?: string }).sessionFile;
+		const entries = JSON.parse(readFileSync(statePaths().mainSession, "utf8")) as Record<string, string>;
+		return typeof entries.sessionFile === "string" ? { main: entries.sessionFile } : entries;
 	} catch {
-		return undefined;
+		return {};
 	}
 }
 
 /**
- * The main Agent is the Session `main.json` names: `pd main` starts one with `--main`, and `/new` in it starts the
- * next. It gets the main Agent's instructions.
+ * A main Agent is a Session an entry of `main.json` names: `pd main --name <entry>` starts one with `--main=<entry>`,
+ * and `/new` in it starts the next for the same entry. It gets the main Agent's instructions.
  */
 export function registerMainAgent(pi: ExtensionAPI): void {
-	pi.registerFlag(MAIN_FLAG, { type: "boolean", description: "Start the main Agent (used by pd main)" });
+	pi.registerFlag(MAIN_FLAG, { type: "string", description: "Start the main Agent of this entry (used by pd main)" });
 	let main = false;
 	pi.on("session_start", (event, ctx) => {
 		main = false;
@@ -29,17 +30,22 @@ export function registerMainAgent(pi: ExtensionAPI): void {
 		// Absolute, as `pd main` compares it from other directories; a session directory may be relative.
 		const current = ctx.sessionManager.getSessionFile();
 		const file = current && path.resolve(current);
-		const started = event.reason === "startup" && pi.getFlag(MAIN_FLAG) === true;
-		const renewed = event.reason === "new" && event.previousSessionFile !== undefined && path.resolve(event.previousSessionFile) === mainSessionFile();
-		if (file && (started || renewed)) {
+		const mains = mainEntries();
+		const flag = pi.getFlag(MAIN_FLAG);
+		const previous = event.reason === "new" && event.previousSessionFile !== undefined ? path.resolve(event.previousSessionFile) : undefined;
+		const names = event.reason === "startup" && typeof flag === "string"
+			? [flag]
+			: Object.keys(mains).filter((name) => previous !== undefined && mains[name] === previous);
+		if (file && names.length > 0) {
+			for (const name of names) mains[name] = file;
 			const record = statePaths().mainSession;
 			mkdirSync(path.dirname(record), { recursive: true, mode: 0o700 });
 			// Replaced at once, so that a reader never sees it half written.
 			const temporary = `${record}.${process.pid}`;
-			writeFileSync(temporary, JSON.stringify({ sessionFile: file }));
+			writeFileSync(temporary, JSON.stringify(mains), { mode: 0o600 });
 			renameSync(temporary, record);
 		}
-		main = file !== undefined && file === mainSessionFile();
+		main = file !== undefined && Object.values(mains).includes(file);
 	});
 	pi.on("before_agent_start", (event) => {
 		if (main) event.systemPromptOptions.sections["main-agent"] = instructions;