pi-straw-boss 0.8.0 → 0.9.1

package/README.md

@@ -14,7 +14,7 @@ Run a few agents on the same project and they start stepping on each other: two
 
 - **Everyone joins.** Each pi in Herdr joins its tab's net at start as a member; nothing to ask or remember.
 - **A main agent per tab, by promotion.** An agent whose work grows calls `boss_promote`, or is promoted when it first dispatches a subagent. A tab has one main, and nobody takes it over except you with `/boss`.
-- **A tower per workspace.** It opens with the workspace's first main in its own tab, pinned first, and coordinates the main agents and the other towers. You don't need to talk to it.
+- **A tower per workspace.** It opens with the workspace's first main in its own tab, pinned first, and coordinates the main agents and the other towers, and opens a tab with a main agent for work no session owns. You don't need to talk to it.
 - **A live dashboard** in the tower: who joined, and what they and their subagents are doing.
 - **A browser view** of the whole net, `/boss gui`: every workspace as a base with its tower, agents, and subagents, animated and read-only. Click a base to zoom in, click a unit to read its chat as a live comms log; units that wait on you queue up as alerts.
 - **Broadcast** to a tab, a workspace, every tower, or every session.
@@ -46,6 +46,7 @@ The tower only routes and coordinates, so it can run a lighter model: set `tower
 | `boss_promote` | Become this tab's main agent (refused while it has one). |
 | `boss_status` | Main agents, this workspace's tower, and the other towers. |
 | `call_tower` | Message this workspace's tower, or another workspace's. |
+| `boss_open_main` | Tower only: open a tab with a new main agent for a request no session owns. |
 | `boss_broadcast` | Message a tab, a workspace, all towers, or every session. |
 | `/boss` | Take over as this tab's main agent. |
 | `/boss status`, `/boss tower` | Show the status; open and focus the tower. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-straw-boss",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Straw Boss coordination for pi in Herdr: sessions join a tab's net by choice, the first joiner is its main agent, a workspace tower opens on demand with a live monitoring dashboard, and boss_broadcast reaches the rest",
   "type": "module",
   "license": "MIT",

package/prompts/tower.md

@@ -2,7 +2,7 @@ You are the tower of Herdr workspace {{workspace}}; agents talk to you, the boss
 
 Agents and towers message you through intercom; answer with intercom send.
 
-- Route each request to the main agent that owns it; when its tab has no main, to the member session doing that work; when no session owns it, back to the sender. Relay with boss_status, call_tower, and boss_broadcast; towers coordinate through the head tower, the tower of workspace {{head}}.
+- Route each request to the main agent that owns it; when its tab has no main, to the member session doing that work; when no session owns it, open a main with boss_open_main without asking the boss, once, passing the request and the boss's decisions verbatim and the sender, and tell the sender if it fails. Other workspaces' work goes to their towers. Relay with boss_status, call_tower, and boss_broadcast; towers coordinate through the head tower, the tower of workspace {{head}}.
 - Friction reports: find the owner and the broken relationship (registration, endpoint, dependency, shared resource, cleanup); have the owner repair it. Return a Straw Boss defect as a finding with evidence.
 - Never ask the boss (no ask_user, robot_hand, focus changes); boss decisions go to the owning main agent.
 - Do no work yourself: no commands, process signals, or edits; even a one-step fix goes to its owner.

package/src/herdr.ts

@@ -125,6 +125,25 @@ export async function waitFor<T>(sleep: Sleep, check: () => T | Promise<T>, ms:
 	}
 }
 
+/** A new tab in `dir` that does not take focus, with `env` (NAME=value) in its panes. */
+export async function createTab(run: HerdrRun, workspace: string, dir: string, env: string[], label?: string) {
+	const created = await result(run, ["tab", "create", "--workspace", workspace, ...(label ? ["--label", label] : []), "--cwd", dir, "--no-focus", ...env.flatMap((e) => ["--env", e])]);
+	return { tabId: created.tab.tab_id as string, paneId: created.root_pane.pane_id as string };
+}
+
+/** Starts pi in the pane under a Herdr agent name. A new tab's shell may not be at its prompt yet: herdr answers agent_pane_busy until it is, and any other failure is final. */
+export async function startPi(run: HerdrRun, sleep: Sleep, name: string, paneId: string, piArgs: string[]) {
+	const start = ["agent", "start", name, "--kind", "pi", "--pane", paneId, "--timeout", String(START_MS), "--", ...piArgs];
+	for (let attempt = 1; ; attempt++) {
+		try {
+			return await run(start, START_MS + 5000);
+		} catch (error) {
+			if (attempt === START_ATTEMPTS || !(error as Error).message.includes("agent_pane_busy")) throw error;
+			await sleep(500);
+		}
+	}
+}
+
 /** The live tower of a workspace, opening its `tower` tab when there is none. One opening at a time per workspace. */
 export function ensureTower(env: TowerEnv, workspace: Workspace, cwd: string) {
 	const existing = opening.get(workspace.workspace_id);
@@ -145,35 +164,39 @@ async function open({ run, sleep, live, moveFirst, model }: TowerEnv, workspace:
 
 	// A leftover tower tab is reused: a pane already running pi only needs its token awaited, a shell prompt gets pi started.
 	// The tab is told apart by the `sb_role=tower` pane token that only Straw Boss writes; a tab merely labelled "tower"
-	// (a pi-herdr-agents subagent can be named so) is someone else's.
+	// (a pi-herdr-agents subagent can be named so) is someone else's. A tab whose token was cleared (its tower quit) is still ours when it has
+	// exactly the tower label (the glyph), one pane, and no agent in it.
 	let paneId: string;
 	let running = false;
-	const marked = (await panes(run, ws)).find((p) => p.tokens?.sb_role === "tower");
-	if (marked) {
-		paneId = marked.pane_id;
-		running = marked.agent === "pi";
-		await moveFirst(marked.tab_id);
+	const here = await panes(run, ws);
+	const marked = here.find((p) => p.tokens?.sb_role === "tower");
+	const bare = marked ? [] : (await tabs(run, ws)).filter((t) => t.label === TOWER_LABEL).flatMap((t) => {
+		const inside = here.filter((p) => p.tab_id === t.tab_id);
+		return inside.length === 1 && !inside[0]!.agent && !inside[0]!.tokens?.sb_role ? [inside[0]!] : [];
+	});
+	const reused = marked ?? bare[0];
+	if (reused) {
+		paneId = reused.pane_id;
+		running = reused.agent === "pi";
+		if (!marked) await report(run, "pane", paneId, { sb_role: "tower" });
+		await moveFirst(reused.tab_id);
+		// Other shell-only leftovers are closed; failing to close one leaves a harmless tab, so it does not stop the tower.
+		for (const extra of bare.slice(1)) await run(["tab", "close", extra.tab_id]).catch(() => {});
 	} else {
 		const dir = workspace.worktree?.checkout_path ?? cwd;
-		const created = await result(run, ["tab", "create", "--workspace", ws, "--label", TOWER_LABEL, "--cwd", dir, "--no-focus", "--env", "STRAW_BOSS_ROLE=tower"]);
-		paneId = created.root_pane.pane_id;
+		const created = await createTab(run, ws, dir, ["STRAW_BOSS_ROLE=tower"], TOWER_LABEL);
+		paneId = created.paneId;
 		// Marked at once, so a tab left without pi is recognised (while the marker lasts) and the label stays display only.
 		await report(run, "pane", paneId, { sb_role: "tower" });
-		await moveFirst(created.tab.tab_id);
+		await moveFirst(created.tabId);
 	}
 	if (!running) {
 		// Herdr agent names are unique across workspaces and lowercase only, so the name carries the lowercased workspace id.
-		const start = ["agent", "start", `tower-${ws.toLowerCase()}`, "--kind", "pi", "--pane", paneId, "--timeout", String(START_MS), "--", "--name", `tower · ${workspace.label}`, ...(model ? ["--model", model] : [])];
-		// A new tab's shell may not be at its prompt yet: herdr answers agent_pane_busy until it is, and any other failure is final.
-		for (let attempt = 1; ; attempt++) {
-			try {
-				await run(start, START_MS + 5000);
-				break;
-			} catch (error) {
-				if (attempt === START_ATTEMPTS || !(error as Error).message.includes("agent_pane_busy")) throw error;
-				await sleep(500);
-			}
-		}
+		// An adopted shell that turns out busy (the user runs something there) gives the token back, so the next open does not count it as the tower.
+		await startPi(run, sleep, `tower-${ws.toLowerCase()}`, paneId, ["--name", `tower · ${workspace.label}`, ...(model ? ["--model", model] : [])]).catch(async (error: unknown) => {
+			if (reused && !marked) await report(run, "pane", paneId, { sb_role: null }).catch(() => {});
+			throw error;
+		});
 	}
 	const id = await waitFor(sleep, held, TOWER_WAIT_MS, 1000);
 	if (!id) throw new Error(`The tower of ${workspace.label} did not publish its token within ${TOWER_WAIT_MS / 1000} s (pane ${paneId})`);

package/src/index.ts

@@ -11,6 +11,7 @@ import { createHub, type Hub } from "./dialogs.ts";
 import { answers, type Gui, openBrowser, readRecord, sharedGui, startGui, urlOf } from "./gui.ts";
 import { netSource } from "./net.ts";
 import { clearOrder, markKids, netTokens } from "./order.ts";
+import { opener } from "./opener.ts";
 import { orphans } from "./orphan.ts";
 import { copyText, pairingKeys, showLines } from "./pairing.ts";
 import { type Run, switchRemote, tailscale } from "./remote.ts";
@@ -64,6 +65,8 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 		const bridge = startBridge(pi, { env, dir: guiDir, local: () => (hub?.running ? hub : undefined) });
 		if (env.PI_SUBAGENT_ID) return;
 		let isTower = env.STRAW_BOSS_ROLE === "tower";
+		// A tab the tower opened for a request starts its pi with this role: it promotes itself as soon as it has joined (opener.ts).
+		const opensAsMain = env.STRAW_BOSS_ROLE === "main";
 		let joined = false, isMain = false, holdsTower = false, requests = 0;
 		const nonce = randomUUID().slice(0, 8);
 		// The tab's live main agent as of the last refresh, and the main this session pinned as owner before the broker echoes it back.
@@ -75,7 +78,7 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 		let c!: Channel, at!: Place, ui: ExtensionContext["ui"] | undefined, timer: ReturnType<typeof setInterval> | undefined;
 		let queue: Promise<void> = Promise.resolve();
 		// This session's intercom name, which the subagents it launched show as their launcher, and the subagent panes it has marked.
-		let ownName = "", kids = new Set<string>();
+		let ownName = "", openedBy: string | undefined, kids = new Set<string>();
 		// Watches for subagents this session launched whose result can no longer reach it (orphan.ts).
 		let nudges: ReturnType<typeof orphans> | undefined, nudgeTimer: ReturnType<typeof setInterval> | undefined;
 		const me = () => env.PI_INTERCOM_SESSION_ID ?? "";
@@ -116,7 +119,7 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 				ownName = nameOf((known ?? (await c.listSessions().catch(() => []))).find((s) => s.id === me())) || ownName;
 				// A failed read of Herdr leaves the subagents' tokens as they are; their TTL still runs.
 				const net = await netTokens(run, at, sbRole, ownName || me().slice(0, 8)).catch(() => undefined);
-				await report(run, "pane", at.paneId, { sb_role: sbRole, ...net?.own }).catch(() => {});
+				await report(run, "pane", at.paneId, { sb_role: sbRole, ...net?.own, ...(openedBy ? { sb_opened_by: openedBy } : {}) }).catch(() => {});
 				if (net) kids = await markKids(run, net.kids, kids, net.joined);
 			}
 			if (holdsTower && !stopped) await report(run, "workspace", at.workspaceId, { tower: me() }).catch(() => {});
@@ -318,6 +321,21 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 				return { text, details: { role: role() } };
 			});
 		}
+		// Tower only. The tower runs no commands: this is its one way to start work, in a new tab of its own workspace.
+		function addOpenMain() {
+			const open = opener({ run, sleep, workspaceId: at.workspaceId, cwd: process.cwd(), sessions: () => c.listSessions(), send });
+			tool("boss_open_main", "Open a new tab in this workspace with a new pi as its main agent and hand it a request that no session owns. Does not ask the boss and does not take focus. Opens at most one main per request; when it fails, tell the sender.",
+				Type.Object({
+					request: Type.String({ description: "The sender's request exactly as it reached you, with every boss decision it quotes kept verbatim." }),
+					sender: Type.String({ description: "The intercom name or session id of the session that made the request; the new main reports back to it." }),
+					label: Type.Optional(Type.String({ description: "A short label for the new tab." })),
+				}),
+				async (input) => {
+					const opened = await open(input);
+					const text = opened.repeated ? `A main was already opened for this request (tab ${opened.tab}); nothing new opened.` : `Opened tab ${opened.tab} with a main agent (session ${opened.main}) and handed it the request. It reports to ${opened.sender}.`;
+					return { text, details: opened };
+				});
+		}
 		const startTower = async () => {
 			at = await place(run);
 			connect(false);
@@ -339,6 +357,7 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 			holdsTower = true;
 			info = { workspace: ws?.label ?? at.workspaceId, head: headOf(all)?.label ?? "" };
 			addNetTools();
+			addOpenMain();
 			keepFresh();
 			await publish();
 			// The dashboard lives exactly as long as this session holds the tower role.
@@ -357,6 +376,17 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 			}
 		};
 
+		// STRAW_BOSS_ROLE=main stays in the new tab's shell, so a later pi started there would self-promote. The tower's one-time pane token is what
+		// authorises it: this pi consumes the token and keeps the opener's marker (sb_opened_by) fresh, which the tower counts to enforce its limits.
+		const claimOpened = async () => {
+			if (!opensAsMain) return false;
+			const mine = (await panes(run, at.workspaceId).catch(() => [])).find((p) => p.pane_id === at.paneId);
+			if (mine?.tokens?.sb_open_main !== "1") return false;
+			openedBy = mine.tokens.sb_opened_by;
+			await report(run, "pane", at.paneId, { sb_open_main: null }).catch(() => {});
+			return true;
+		};
+
 		pi.on("session_start", async (_event, ctx) => {
 			stopped = false;
 			ui = ctx.ui;
@@ -379,7 +409,10 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 				if (bar) {
 					tell(bar.text, bar.level);
 				} else {
-					starting = joinNet();
+					starting = joinNet().then(async () => {
+						const taken = (await claimOpened()) && (await promote(false));
+						if (taken && !taken.promoted) tell(taken.text, "warning");
+					});
 				}
 			}
 			starting?.catch((error: Error) => tell(`Straw Boss: ${error.message}`, "error"));
@@ -408,7 +441,7 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 			if (["subagent", "subagent_resume"].includes(event.toolName) && !isTower && !barred && role()) for (const ms of KID_MARK_MS) setTimeout(() => void publish(), ms).unref();
 		});
 
-		pi.on("session_shutdown", async () => {
+		pi.on("session_shutdown", async (event) => {
 			if (gui) await switchRemote(gui, false, guiDir, ts).catch(() => {});
 			await gui?.stop();
 			gui = undefined;
@@ -423,9 +456,15 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 			const held = holdsTower;
 			holdsTower = false;
 			if (!role() || !at) return;
-			await report(run, "pane", at.paneId, { sb_role: null, sb_order: null, sb_mark: null, sb_indent: null, sb_tab: null }).catch(() => {});
+			await report(run, "pane", at.paneId, { sb_role: null, sb_opened_by: null, sb_order: null, sb_mark: null, sb_indent: null, sb_tab: null }).catch(() => {});
 			await clearOrder(run, [...kids]);
 			if (held) await report(run, "workspace", at.workspaceId, { tower: null }).catch(() => {});
+			// A tower that quits leaves its tab as a plain shell: close the tab, but only when this pane is all it holds. A reload, /new, resume or fork keeps the tab.
+			if (isTower && event.reason === "quit") {
+				const all = await panes(run, at.workspaceId).catch(() => []);
+				const tab = all.find((p) => p.pane_id === at.paneId)?.tab_id;
+				if (tab && all.every((p) => p.tab_id !== tab || p.pane_id === at.paneId)) await run(["tab", "close", tab]).catch(() => {});
+			}
 		});
 
 		// /boss gui is a read-only viewer: any session may open it, and it joins nothing and writes no token. A session outside the net

package/src/opener.ts

@@ -0,0 +1,90 @@
+import { createHash, randomUUID } from "node:crypto";
+import { createTab, report, panes, startPi, type HerdrRun, type Session, type Sleep, waitFor, workspaces } from "./herdr.ts";
+
+// The one thing a tower does besides routing: when no session owns a request, it opens a main for it (docs/how-it-works.md, "Opening a main").
+// It is narrow on purpose: one new tab in the tower's own workspace, started without focus, in which Straw Boss starts pi. It types into no pane
+// that already exists, and `STRAW_BOSS_ROLE=main` makes that pi promote itself once it has joined (index.ts).
+
+const MAIN_WAIT_MS = 60_000;
+/** At most this many mains opened by towers are alive in one workspace, and at most one per sender. */
+const MAX_OPENED_MAINS = 2;
+
+/** A limit was hit: nothing opened, and the same request may be tried again once an opened main has finished. */
+class OpenLimitError extends Error {}
+
+export interface OpenerEnv {
+	run: HerdrRun;
+	sleep: Sleep;
+	/** The tower's own workspace: a request for another workspace goes to that workspace's tower. */
+	workspaceId: string;
+	/** Where the new pi runs when the workspace has no checkout path of its own. */
+	cwd: string;
+	sessions(): Promise<Session[]>;
+	send(to: string, message: string): Promise<{ status: string; code?: string; detail?: string }>;
+}
+export interface OpenRequest { request: string; sender: string; label?: string }
+export interface Opened { tab: string; pane: string; main: string; sender: string; repeated?: true }
+
+/** The text the new main starts from: who asked, and what, with nothing summarised. */
+export const handoff = (workspace: string, sender: Session, request: string) =>
+	[
+		`Straw Boss: the tower of workspace ${workspace} opened this tab for you because no session owned the request below, and you are its main agent.`,
+		"Do the work, dispatching workers as your main agent prompt describes, and report the outcome to the sender with intercom send.",
+		`Sender: ${sender.name ?? sender.id} (session id ${sender.id})`,
+		"Request, verbatim:",
+		request,
+	].join("\n");
+
+/**
+ * Opens a main for a request, once, within the limits above. The same sender and request never open a second main, whether the first attempt is still running, succeeded,
+ * or failed (a failed attempt closes the tab it created and is not retried: the sender hears of it instead).
+ */
+export function opener(env: OpenerEnv) {
+	const seen = new Map<string, Promise<Opened>>();
+	const open = async ({ request, sender: asked, label }: OpenRequest): Promise<Opened> => {
+		const { run, sleep } = env;
+		const sessions = await env.sessions();
+		const matches = sessions.filter((s) => s.id === asked || s.name === asked);
+		if (matches.length !== 1) throw new Error(`${matches.length ? "Several sessions are named" : "No live session is named or has the id"} "${asked}", so the new main could not report back to it`);
+		const sender = matches[0]!;
+		const workspace = (await workspaces(run)).find((w) => w.workspace_id === env.workspaceId);
+		if (!workspace) throw new Error(`Workspace ${env.workspaceId} is not open any more`);
+		// Limits come from live Herdr panes carrying the marker below, so they hold across a tower restart: a closed tab takes its marker with it, and
+		// a main that died leaves one that expires with its token TTL. Opens are serialised, so the count and the marker cannot race.
+		const marked = (await panes(run, workspace.workspace_id)).filter((p) => p.tokens?.sb_opened_by);
+		const ofSender = marked.filter((p) => p.tokens!.sb_opened_by === sender.id).length;
+		if (ofSender) throw new OpenLimitError(`Sender ${sender.name ?? sender.id} already has ${ofSender === 1 ? "an opened main" : `${ofSender} opened mains`} running in workspace ${workspace.label}; a sender gets one at a time. Wait for it to finish, or send the request to it.`);
+		if (marked.length >= MAX_OPENED_MAINS) throw new OpenLimitError(`Workspace ${workspace.label} already has ${marked.length} mains opened by its tower (the limit is ${MAX_OPENED_MAINS}); try again when one has finished.`);
+		const { tabId, paneId } = await createTab(run, workspace.workspace_id, workspace.worktree?.checkout_path ?? env.cwd, ["STRAW_BOSS_ROLE=main"], label);
+		try {
+			// The marker counts toward the limits at once; sb_open_main authorises exactly one pi in this shell to promote itself (it consumes the token).
+			await report(run, "pane", paneId, { sb_opened_by: sender.id, sb_open_main: "1" });
+			// Herdr agent names are unique across workspaces and lowercase only.
+			await startPi(run, sleep, `main-${randomUUID().slice(0, 8)}`, paneId, ["--name", `main · ${label ?? workspace.label}`]);
+			// The pi is the tab's main once it has published its role; only then does it get the request, so its first prompt is the main agent's.
+			const main = await waitFor(sleep, async () => {
+				const role = (await panes(run, workspace.workspace_id)).find((p) => p.pane_id === paneId)?.tokens?.sb_role;
+				return role === "main" ? (await env.sessions()).find((s) => s.herdrLocation?.paneId === paneId) : undefined;
+			}, MAIN_WAIT_MS, 500);
+			if (!main) throw new Error(`The pi in pane ${paneId} did not become the main agent of its tab within ${MAIN_WAIT_MS / 1000} s`);
+			const sent = await env.send(main.id, handoff(workspace.label, sender, request));
+			if (sent.status !== "sent") throw new Error(`The new main ${main.name ?? main.id} did not take the request: ${sent.status} ${sent.code ?? ""} ${sent.detail ?? ""}`.trim());
+			return { tab: tabId, pane: paneId, main: main.id, sender: sender.id };
+		} catch (error) {
+			// Nothing was handed over, so no work is lost with the tab.
+			await run(["tab", "close", tabId]).catch(() => {});
+			throw error;
+		}
+	};
+	let queue: Promise<unknown> = Promise.resolve();
+	return (input: OpenRequest): Promise<Opened> => {
+		const key = createHash("sha256").update(JSON.stringify([input.sender, input.request])).digest("hex");
+		const prior = seen.get(key);
+		if (prior) return prior.then((opened) => ({ ...opened, repeated: true as const }), (error: Error) => Promise.reject(new Error(`A main was already tried for this request and is not opened again: ${error.message}`)));
+		const pending = queue.then(() => open(input), () => open(input));
+		queue = pending.catch(() => {});
+		seen.set(key, pending);
+		pending.catch((error) => error instanceof OpenLimitError && seen.get(key) === pending && seen.delete(key));
+		return pending;
+	};
+}