pi-straw-boss 0.6.3 → 0.6.5

package/README.md

@@ -19,6 +19,7 @@ Run a few agents on the same project and they start stepping on each other: two
 - **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.
 - **Tidy tabs.** When a pi starts in a tab or quits out of it, the tab's panes are made equal again, so workers split off one by one don't leave a chain of halves.
+- **A net view in Herdr's sidebar.** An optional plugin turns the Agents list into the net, towers first and each subagent under its launcher, on one key.
 
 ## Install
 
@@ -50,6 +51,32 @@ You need pi running inside Herdr 0.9.4 or newer, and [pi-intercom](https://www.n
 
 Subagents and sessions in Herdr worktree workspaces never join: the session that launched them speaks for them. Outside Herdr the extension does nothing.
 
+## Net view in the sidebar
+
+An optional Herdr plugin in [`herdr-plugin/`](herdr-plugin) turns the sidebar's Agents list into a net view.
+It lists the head tower's workspace first, in each workspace the tower, then each tab's main agent and members, and every subagent right under the session that launched it, even in a worktree workspace.
+One key switches to it, and the same key switches back to Herdr's own view.
+pi-straw-boss writes the sort key (`sb_order`) and a role label (`sb_mark`) the view and your sidebar rows can use.
+It needs Herdr 0.9.3 or newer and node.
+
+Link it from a checkout, then bind a key in Herdr's `config.toml`:
+
+```bash
+herdr plugin link /path/to/pi-straw-boss/herdr-plugin
+```
+
+```toml
+[[keys.command]]
+key = "prefix+alt+n"
+type = "plugin_action"
+command = "wayne930242.straw-boss.net"
+description = "toggle the straw net view"
+```
+
+Run `herdr server reload-config` to load the key, and `herdr plugin unlink wayne930242.straw-boss` to remove the plugin.
+`herdr plugin install wayne930242/pi-straw-boss/herdr-plugin` installs it from GitHub instead of a checkout.
+[How it works](docs/how-it-works.md#sidebar-net-view) has the tokens and a sidebar rows snippet that shows each member's role in Herdr's own view too.
+
 ## Learn more
 
 [How it works](docs/how-it-works.md) covers roles, the tower, the dashboard, the browser view, what the extension writes, and how Claude Code or Codex agents can find a tower.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-straw-boss",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "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/src/dashboard.ts

@@ -78,8 +78,8 @@ function readJson(path: string): Record<string, unknown> {
 	}
 }
 
-/** The subagents a pi session launched: live ones, plus those that finished in the last 10 minutes. */
-export function subagents(parent: Pane | undefined, all: Pane[], now: number): Row[] {
+/** The subagents a pi session launched: live ones, plus those that finished in the last 10 minutes. The dashboard shows the first `limit`. */
+export function subagents(parent: Pane | undefined, all: Pane[], now: number, limit = MAX_CHILDREN): Row[] {
 	const file = parent?.agent_session?.value;
 	if (!file) return [];
 	const dir = join(dirname(file), "artifacts", basename(file, ".jsonl").split("_").pop()!);
@@ -109,7 +109,7 @@ export function subagents(parent: Pane | undefined, all: Pane[], now: number): R
 			return { group: "net" as const, depth: 2, mark, text: name, kind: "subagent", workspace: pane?.workspace_id, id, file, pane: pane?.agent === "pi" ? pane.pane_id : undefined, note: { working: doing, waiting: "waiting on a question", done: "finished" }[mark as "working"] };
 		})
 		.sort((a, b) => Number(a.mark === "done") - Number(b.mark === "done") || a.text.localeCompare(b.text))
-		.slice(0, MAX_CHILDREN);
+		.slice(0, limit);
 }
 
 /**

package/src/herdr.ts

@@ -20,6 +20,7 @@ export type Sleep = (ms: number) => Promise<void>;
 export interface Place { paneId: string; tabId: string; workspaceId: string }
 export interface Workspace { workspace_id: string; label: string; agent_status?: string; tokens?: Record<string, string>; worktree?: { checkout_path?: string; is_linked_worktree?: boolean; repo_key?: string } }
 export interface Pane { pane_id: string; tab_id: string; workspace_id?: string; agent?: string; agent_status?: string; agent_session?: { value: string }; label?: string; tokens?: Record<string, string> }
+export interface HerdrTab { tab_id: string; workspace_id: string; label?: string }
 export interface Location { status: string; workspace?: { id: string; label: string }; tab?: { id: string; label: string }; paneId?: string }
 /** A live pi-intercom session; `status` is idle, thinking, or tool:<name>. */
 export interface Session { id: string; name?: string; status?: string; herdrLocation?: Location }
@@ -49,8 +50,8 @@ async function result(run: HerdrRun, args: string[], timeoutMs?: number) {
 	}
 }
 
-// The tower tab is labelled with the Nerd Font lighthouse glyph (md-lighthouse, U+F09FF) alone.
-export const TOWER_LABEL = "\u{f09ff}";
+// The tower tab is labelled with the Nerd Font radio tower glyph (md-radio_tower, U+F043B) alone.
+export const TOWER_LABEL = "\u{f043b}";
 
 export async function place(run: HerdrRun): Promise<Place> {
 	const pane = (await result(run, ["pane", "current"])).pane;
@@ -65,6 +66,9 @@ export const headOf = (all: Workspace[]) => all.find((w) => !isSub(w));
 
 export const workspaces = async (run: HerdrRun): Promise<Workspace[]> => (await result(run, ["workspace", "list"])).workspaces;
 
+/** The tabs of one workspace in Herdr's tab order. */
+export const tabs = async (run: HerdrRun, workspace: string): Promise<HerdrTab[]> => (await result(run, ["tab", "list", "--workspace", workspace])).tabs;
+
 export async function panes(run: HerdrRun, workspace?: string): Promise<Pane[]> {
 	return (await result(run, ["pane", "list", ...(workspace ? ["--workspace", workspace] : [])])).panes;
 }

package/src/index.ts

@@ -9,6 +9,7 @@ import { collect, startDashboard } from "./dashboard.ts";
 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 { copyText, pairingKeys, showLines } from "./pairing.ts";
 import { type Run, switchRemote, tailscale } from "./remote.ts";
 import { ensureTower, headOf, herdrApi, type HerdrApi, herdrCall, type HerdrCall, herdrRun, type HerdrRun, isSub, type Pane, panes, parentOf, place, type Place, report, type Session, type Sleep, waitFor, workspaces, type Workspace } from "./herdr.ts";
@@ -68,6 +69,8 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 		let gui: Gui | undefined, viewer: Channel | undefined, opening: Promise<string> | undefined;
 		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>();
 		const me = () => env.PI_INTERCOM_SESSION_ID ?? "";
 		const role = (): Role | undefined => {
 			if (isTower) return "tower";
@@ -98,11 +101,20 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 		};
 
 		// Tokens are display and discovery only: a failed write waits for the next refresh, liveness comes from intercom.
-		const publish = async () => {
-			const sbRole = role();
-			if (sbRole) await report(run, "pane", at.paneId, { sb_role: sbRole }).catch(() => {});
-			if (holdsTower) await report(run, "workspace", at.workspaceId, { tower: me() }).catch(() => {});
+		// One publish at a time, and shutdown waits for the one in flight: a write that lands after the clear would leave tokens behind.
+		let publishing: Promise<void> = Promise.resolve(), stopped = false;
+		const publishOnce = async (known?: Session[]) => {
+			const sbRole = stopped ? undefined : role();
+			if (sbRole) {
+				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(() => {});
+				if (net) kids = await markKids(run, net.kids, kids, net.joined);
+			}
+			if (holdsTower && !stopped) await report(run, "workspace", at.workspaceId, { tower: me() }).catch(() => {});
 		};
+		const publish = (known?: Session[]) => (publishing = publishing.then(() => publishOnce(known)).catch(() => {}));
 		const keepFresh = () => {
 			timer ??= setInterval(() => void publish(), REFRESH_MS);
 			timer.unref();
@@ -157,7 +169,7 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 				const wasMain = isMain;
 				isMain = mainId === me();
 				if (isMain !== wasMain) tell(`This session is ${isMain ? "now" : "no longer"} the main agent of ${info.tab}`);
-				await publish();
+				await publish(sessions);
 				// The workspace's first main opens the tower at once; later mains find it open.
 				if (isMain && !wasMain && autoTower) void openTower().catch((error: Error) => tell(`Straw Boss: could not open the tower: ${error.message}`, "warning"));
 			} catch (error) {
@@ -338,6 +350,7 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 		};
 
 		pi.on("session_start", async (_event, ctx) => {
+			stopped = false;
 			ui = ctx.ui;
 			hasUI = ctx.hasUI;
 			prompts = Object.fromEntries(PROMPTS.map((name) => [name, readFileSync(join(promptDir, `${name}.md`), "utf8").trim()]));
@@ -385,10 +398,13 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), call = herdr
 			dashboard = undefined;
 			clearInterval(timer);
 			timer = undefined;
+			stopped = true; // a refresh still in flight must not write tokens after they are cleared
+			await publishing;
 			const held = holdsTower;
 			holdsTower = false;
 			if (!role() || !at) return;
-			await report(run, "pane", at.paneId, { sb_role: null }).catch(() => {});
+			await report(run, "pane", at.paneId, { sb_role: null, sb_order: null, sb_mark: null }).catch(() => {});
+			await clearOrder(run, [...kids]);
 			if (held) await report(run, "workspace", at.workspaceId, { tower: null }).catch(() => {});
 		});
 

package/src/order.ts

@@ -0,0 +1,75 @@
+import { subagents } from "./dashboard.ts";
+import { type HerdrRun, type HerdrTab, isSub, type Pane, panes, type Place, report, tabs, workspaces, type Workspace } from "./herdr.ts";
+
+// Two display tokens for the sidebar plugin and for Herdr's own Agents rows, written next to `sb_role`:
+//  - `sb_order`: a sort key that lays the net out as the head tower's workspace first, then the other workspaces in Herdr's order, in each the tower
+//    and then the tabs in tab order, in each tab the main agent and then the members, and every subagent right after the session that launched it,
+//    its own subagents after it in turn. Segments are fixed-width and `.`-separated, so plain string order is the numeric order of every segment,
+//    and a subagent's key is its parent's key plus one more segment, which sorts after the parent and before the parent's next sibling.
+//  - `sb_mark`: a short label that says what a net member is, a star for a main agent, a dot for a member, and an arrow and the launcher's name for a subagent.
+//    A tower has none: its tab already carries the radio tower glyph.
+// A session writes them for itself and for the subagents it launched, which never join and write nothing, on the same 4 minute refresh as `sb_role`.
+
+/** The glyphs sit in Hack Nerd Font and MesloLGS NF: Font Awesome's star (U+F005), the middle dot, and the down-right arrow. */
+export const MARK = { main: "\uf005 main", member: "\u00b7 member" } as const;
+export const ARROW = "\u21b3";
+// The dashboard shows eight subagents per session, but every live one is keyed: one left out would sort outside its launcher's span. Three digits count them.
+const MAX_KIDS = 999;
+const NAME_MAX = 24;
+const part = (n: number, width = 3) => String(n).padStart(width, "0");
+const short = (name: string) => (name.length > NAME_MAX ? `${name.slice(0, NAME_MAX - 1)}…` : name);
+
+/**
+ * The key of a session that is in the net, or undefined when Herdr cannot place it. Workspaces count among the base ones (a sub workspace is a
+ * linked worktree whose sessions hang under their launcher), the head tower's workspace being the first of them; a pane's slot is its place among
+ * its tab's panes, so every member has a key of its own.
+ */
+export function orderKey(role: "tower" | "main" | "member", pane: Pane, ps: Pane[], all: Workspace[], tabList: HerdrTab[]): string | undefined {
+	const base = all.filter((w) => !isSub(w)).findIndex((w) => w.workspace_id === pane.workspace_id);
+	if (base < 0) return undefined;
+	if (role === "tower") return `${part(base)}.0`;
+	const tab = tabList.findIndex((t) => t.tab_id === pane.tab_id), slot = ps.filter((p) => p.tab_id === pane.tab_id).findIndex((p) => p.pane_id === pane.pane_id);
+	return tab < 0 || slot < 0 ? undefined : `${part(base)}.1.${part(tab)}.${role === "main" ? 0 : 1}.${part(slot)}`;
+}
+
+/**
+ * The tokens of the live subagents below a session, each keyed after its launcher, at any depth. Subagents that finished have no pane to mark;
+ * a pane already marked on the way down (a cycle in the launch records) is not marked again, which also ends the descent.
+ */
+export function descendants(parent: Pane | undefined, key: string, name: string, ps: Pane[], now: number, seen = new Set<string>(parent ? [parent.pane_id] : [])): Kid[] {
+	if (!parent) return [];
+	return subagents(parent, ps, now, MAX_KIDS).flatMap((row, i) => {
+		if (!row.pane || seen.has(row.pane)) return [];
+		seen.add(row.pane);
+		const order = `${key}.${part(i)}`;
+		return [{ pane: row.pane, order, mark: `${ARROW} ${short(name)}` }, ...descendants(ps.find((p) => p.pane_id === row.pane), order, row.text, ps, now, seen)];
+	});
+}
+
+/** The subagent panes a session marks: each gets `sb_order` and `sb_mark`. */
+export interface Kid { pane: string; order: string; mark: string }
+
+/**
+ * What a session publishes besides its role: its own two tokens (null clears them when Herdr cannot place the session, and a tower has no
+ * mark) and those of the subagents it launched. Reads Herdr only.
+ */
+export async function netTokens(run: HerdrRun, place: Place, role: "tower" | "main" | "member", name: string, now = Date.now()): Promise<{ own: Record<string, string | null>; kids: Kid[]; joined: Set<string> }> {
+	const [ps, all, tabList] = [await panes(run), await workspaces(run), await tabs(run, place.workspaceId)];
+	const pane = ps.find((p) => p.pane_id === place.paneId), key = pane && orderKey(role, pane, ps, all, tabList);
+	const joined = new Set(ps.filter((p) => p.tokens?.sb_role).map((p) => p.pane_id));
+	return { own: { sb_order: key ?? null, sb_mark: role === "tower" ? null : MARK[role] }, kids: key ? descendants(pane, key, name, ps, now) : [], joined };
+}
+
+/**
+ * Writes the subagents' tokens and clears those of subagent panes marked before and gone now, except a pane that has joined the net since
+ * (a shell where a subagent ran can start a pi that writes its own). Returns the panes now marked. A failed write waits for the next refresh.
+ */
+export async function markKids(run: HerdrRun, kids: Kid[], before: Set<string>, joined = new Set<string>()): Promise<Set<string>> {
+	for (const kid of kids) await report(run, "pane", kid.pane, { sb_order: kid.order, sb_mark: kid.mark }).catch(() => {});
+	const marked = new Set(kids.map((k) => k.pane));
+	await clearOrder(run, [...before].filter((id) => !marked.has(id) && !joined.has(id)));
+	return marked;
+}
+
+/** Removes both tokens from panes, ignoring a pane that has already closed. */
+export const clearOrder = (run: HerdrRun, paneIds: string[]) => Promise.all(paneIds.map((id) => report(run, "pane", id, { sb_order: null, sb_mark: null }).catch(() => {})));