pi-straw-boss 0.3.2 → 0.4.1

package/src/history.ts

@@ -0,0 +1,226 @@
+import { type FSWatcher, watch } from "node:fs";
+import { type FileHandle, open, stat } from "node:fs/promises";
+import { FULL_LIMIT, type Item, type Json, parse, toItem } from "./items.ts";
+
+// The session reader: a pi session file in, pages of displayable items out, plus a live tail. Only an index stays in memory
+// (type, id, parent, role, offset, length per entry); item content is read from the file by offset for the page being sent.
+//
+// Index: 1 MB chunks, yielding to the event loop between them. Per line only its first bytes (type, id, parentId, role come first
+// in most entries) and its last bytes (custom entries end with id, parentId, timestamp) are kept and matched, so a 58 MB file costs
+// tens of milliseconds. A line neither matches is read and parsed once. The leaf is the last entry in file order (pi's own load
+// rule) and the view is the path from the leaf up through parentId, oldest first. A rewritten file (smaller, new inode, new header)
+// is re-indexed from scratch; a new entry whose parent is not the current leaf is a branch move. Both reset the page.
+// All index work and every read run one at a time, in order (`serial`): the first index ends before any append starts, and a page or
+// entry is never read while the index is being rebuilt under it.
+
+const CHUNK = 1 << 20, HEAD = 512, TAIL = 400, BIG = 16_384;
+export const PAGE = 150;
+const HIDDEN = new Set(["session", "custom", "label", "usage", "context_edit"]);
+
+export interface Change { reset: boolean; items: Item[]; before?: string }
+export interface Reader {
+	ready: Promise<void>;
+	header(): { id?: string; cwd?: string } | undefined;
+	unreadable(): number;
+	page(before?: string, limit?: number): Promise<{ items: Item[]; before?: string }>;
+	entry(id: string): Promise<Item | undefined>;
+	subscribe(fn: (change: Change) => void): () => void;
+	start(): void;
+	stop(): void;
+}
+interface Ent { type: string; role?: string; id: string; parent: string | null; off: number; len: number }
+
+export function openReader(file: string, pollMs = 1000): Reader {
+	let ents: Ent[] = [], byId = new Map<string, number>(), path: number[] = [], bad = 0, size = 0, ino = -1, headText = "", head: Json | undefined;
+	let cur = { start: 0, len: 0, head: Buffer.alloc(0), tail: Buffer.alloc(0) };
+	const listeners = new Set<(c: Change) => void>();
+	let watcher: FSWatcher | undefined, timer: ReturnType<typeof setInterval> | undefined, chain: Promise<unknown> = Promise.resolve(), queued = false;
+	const serial = <T>(task: () => Promise<T>): Promise<T> => {
+		const run = chain.then(task);
+		chain = run.catch(() => {});
+		return run;
+	};
+
+	const grab = async (fh: FileHandle, off: number, len: number) => {
+		const buf = Buffer.allocUnsafe(len);
+		return buf.subarray(0, (await fh.read(buf, 0, len, off)).bytesRead);
+	};
+	/** A finished line: its entry, from the bytes at either end, else from the whole line read once. */
+	async function line(fh: FileHandle, start: number, len: number, h: string, t: string) {
+		const a = h.match(/^\{"type":"(\w+)","id":"([^"]+)","parentId":(null|"[^"]*")/) ?? t.match(/^()[^]*"id":"([^"]+)","parentId":(null|"[^"]*"),"timestamp":"[^"]*"\}$/) ?? undefined;
+		let type = a?.[1] || h.match(/^\{"type":"(\w+)"/)?.[1], id = a?.[2], parent = a?.[3];
+		if (type === "session") return void (headText ||= h);
+		if (!a || !type) {
+			const d = parse((await grab(fh, start, len)).toString("utf8"));
+			if (!d?.id) return void bad++;
+			[type, id, parent] = [d.type, d.id, d.parentId === null ? "null" : `"${d.parentId}"`];
+		}
+		const role = type === "message" ? h.match(/"message":\{"role":"(\w+)"/)?.[1] : undefined;
+		byId.set(id!, ents.push({ type: type!, role, id: id!, parent: parent === "null" ? null : parent!.slice(1, -1), off: start, len }) - 1);
+	}
+	/** Feeds file bytes starting at `at`; a line cut by the end of the data stays in `cur` until its newline arrives. */
+	async function feed(fh: FileHandle, chunk: Buffer, at: number) {
+		for (let i = 0; i < chunk.length; ) {
+			const nl = chunk.indexOf(10, i), seg = chunk.subarray(i, nl < 0 ? chunk.length : nl);
+			if (cur.head.length < HEAD) cur.head = Buffer.concat([cur.head, seg.subarray(0, HEAD - cur.head.length)]);
+			cur.tail = seg.length >= TAIL ? Buffer.from(seg.subarray(-TAIL)) : Buffer.concat([cur.tail, seg]).subarray(-TAIL);
+			cur.len += seg.length;
+			if (nl < 0) break;
+			if (cur.len) await line(fh, cur.start, cur.len, cur.head.toString("latin1"), cur.tail.toString("latin1"));
+			cur = { start: at + nl + 1, len: 0, head: Buffer.alloc(0), tail: Buffer.alloc(0) };
+			i = nl + 1;
+		}
+	}
+	const pathTo = (leaf: number) => {
+		const out: number[] = [];
+		for (let i: number | undefined = leaf; i !== undefined && out.length <= ents.length; i = ents[i]!.parent === null ? undefined : byId.get(ents[i]!.parent!)) out.push(i);
+		return out.reverse();
+	};
+	async function scan(fh: FileHandle, to: number) {
+		for (let at = size; at < to; at += CHUNK) {
+			await feed(fh, await grab(fh, at, Math.min(CHUNK, to - at)), at);
+			await new Promise((resolve) => setImmediate(resolve));
+		}
+		size = to;
+	}
+	/** The items of the entries at these indexes, in order; hidden kinds are skipped without reading. */
+	async function load(idx: number[], max = Infinity) {
+		const items: Item[] = [];
+		if (!idx.length) return items;
+		const fh = await open(file, "r");
+		try {
+			for (const i of idx.toReversed()) {
+				const e = ents[i]!;
+				if (items.length >= max) break;
+				if (HIDDEN.has(e.type) || e.role === "system") continue;
+				const big = e.role === "toolResult" && e.len > BIG * 2;
+				const text = (await grab(fh, e.off, big ? BIG : e.len)).toString("utf8");
+				const d = big ? { type: "message", id: e.id, message: { role: "toolResult", toolCallId: text.match(/"toolCallId":"([^"]+)"/)?.[1], toolName: text.match(/"toolName":"([^"]+)"/)?.[1], content: [{ type: "text", text: parse(`"${(text.match(/"text":"((?:[^"\\]|\\.)*)/)?.[1] ?? "").replace(/\\(?:u[0-9a-fA-F]{0,3})?$/, "")}"`) ?? "" }], isError: (await grab(fh, e.off + e.len - 300, 300)).toString("utf8").includes('"isError":true') } } : parse(text);
+				const item = d && toItem(d, e.len);
+				if (item) items.unshift(item);
+			}
+		} finally {
+			await fh.close();
+		}
+		return items;
+	}
+	async function page(before?: string, limit = PAGE) {
+		const end = before === undefined ? path.length : path.findIndex((i) => ents[i]!.id === before);
+		const idx = path.slice(0, Math.max(0, end)), items = await load(idx, limit);
+		const oldest = items[0] && path.findIndex((i) => ents[i]!.id === items[0]!.id);
+		return { items, before: oldest && oldest > 0 ? items[0]!.id : undefined };
+	}
+	async function reindex() {
+		[ents, byId, path, bad, size, headText] = [[], new Map(), [], 0, 0, ""];
+		cur = { start: 0, len: 0, head: Buffer.alloc(0), tail: Buffer.alloc(0) };
+		const fh = await open(file, "r");
+		try {
+			const s = await fh.stat();
+			ino = s.ino;
+			await scan(fh, s.size);
+			head = headText ? parse((await grab(fh, 0, Math.min(s.size, 4096))).toString("utf8").split("\n")[0]!) : undefined;
+		} finally {
+			await fh.close();
+		}
+		path = ents.length ? pathTo(ents.length - 1) : [];
+	}
+	const emit = (change: Change) => listeners.forEach((fn) => fn(change));
+	/** New bytes were appended: new entries extend the path, or move the branch (a new parent) and reset the page. */
+	async function append(to: number) {
+		const n = ents.length, fh = await open(file, "r");
+		try {
+			await scan(fh, to);
+		} finally {
+			await fh.close();
+		}
+		const added = ents.slice(n), leaf = path.at(-1), from = path.length;
+		if (!added.length) return;
+		if (added.every((e, k) => e.parent === (k ? added[k - 1]!.id : leaf === undefined ? null : ents[leaf]!.id))) {
+			path.push(...added.map((_, k) => n + k));
+			return emit({ reset: false, items: await load(path.slice(from)) });
+		}
+		path = pathTo(ents.length - 1);
+		emit({ reset: true, ...(await page()) });
+	}
+	const headChanged = async () => {
+		const fh = await open(file, "r");
+		try {
+			return headText !== "" && (await grab(fh, 0, headText.length)).toString("latin1") !== headText;
+		} finally {
+			await fh.close();
+		}
+	};
+	/** One look at the file: a rewrite re-indexes, new bytes are appended. Reads look first, so they never use an index of a replaced file. */
+	async function look() {
+		try {
+			const s = await stat(file).catch(() => undefined);
+			if (!s) return; // a new session has no file until its first message: keep waiting for it
+			if (s.ino !== ino || s.size < size || (s.size > size && (await headChanged()))) {
+				await reindex();
+				emit({ reset: true, ...(await page()) });
+			} else if (s.size > size) await append(s.size);
+		} catch {} // a read that fails (the file vanished mid-read) is retried by the next poll
+	}
+	/** A look queued behind the work already running; changes that arrive meanwhile queue one more. */
+	function refresh() {
+		if (queued) return;
+		queued = true;
+		void serial(() => ((queued = false), look()));
+	}
+	const ready: Promise<void> = serial(reindex).catch(() => undefined);
+	return {
+		ready,
+		header: () => head && { id: head.id, cwd: head.cwd },
+		unreadable: () => bad,
+		page: (before, limit) => serial(async () => (await look(), page(before, limit))),
+		entry: (id) => serial(async () => {
+			await look();
+			const i = byId.get(id), e = i === undefined ? undefined : ents[i];
+			if (!e) return undefined;
+			const fh = await open(file, "r");
+			try {
+				const d = parse((await grab(fh, e.off, Math.min(e.len, 2 * FULL_LIMIT))).toString("utf8"));
+				return d && toItem(d, e.len, true);
+			} finally {
+				await fh.close();
+			}
+		}),
+		subscribe: (fn) => (listeners.add(fn), () => void listeners.delete(fn)),
+		start() {
+			if (timer) return;
+			timer = setInterval(() => void refresh(), pollMs).unref();
+			try {
+				watcher = watch(file, refresh);
+				watcher.unref().on("error", () => {});
+			} catch {} // no file yet: the poll finds it
+			refresh();
+		},
+		stop() {
+			clearInterval(timer);
+			timer = undefined;
+			watcher?.close();
+			watcher = undefined;
+		},
+	};
+}
+
+/** Readers for the files pages watch: one per file while watched, the last eight kept (index only, not watching) afterwards. */
+export function readers(keep = 8, make = openReader) {
+	const all = new Map<string, { reader: Reader; users: number }>();
+	return {
+		acquire(file: string): Reader {
+			const held = all.get(file) ?? { reader: make(file), users: 0 };
+			held.users++;
+			all.delete(file);
+			all.set(file, held);
+			held.reader.start();
+			return held.reader;
+		},
+		release(file: string) {
+			const held = all.get(file);
+			if (!held || --held.users > 0) return;
+			held.reader.stop();
+			for (const [name, other] of all) if (all.size > keep && !other.users) all.delete(name);
+		},
+	};
+}

package/src/index.ts

@@ -6,7 +6,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Type, type Static, type TSchema } from "typebox";
 import { collect, startDashboard } from "./dashboard.ts";
 import { answers, type Gui, openBrowser, readRecord, sharedGui, startGui } from "./gui.ts";
-import { collectNet } from "./net.ts";
+import { netSource } from "./net.ts";
 import { ensureTower, headOf, herdrApi, type HerdrApi, herdrRun, type HerdrRun, isSub, type Pane, panes, parentOf, place, type Place, report, type Session, type Sleep, waitFor, workspaces, type Workspace } from "./herdr.ts";
 
 // pi-intercom's extension API as constants and minimal types: intercom is a runtime requirement, not an import.
@@ -15,7 +15,7 @@ const OUTBOX = "intercom:outbox-request";
 const OUTBOX_RESULT = "intercom:outbox-result";
 const NAMESPACE = /^[a-z0-9][a-z0-9._/-]{0,63}$/;
 const ENTRY = "straw-boss";
-const PROMPTS = ["main", "tower", "member", "reminder"];
+const PROMPTS = ["main", "tower", "member", "member-no-main"];
 const REFRESH_MS = 4 * 60_000;
 const CLAIM_MS = 5000;
 const CONNECT_MS = 15_000;
@@ -29,11 +29,11 @@ interface Channel {
 	listSessions(): Promise<Session[]>;
 }
 interface SendResult { requestId?: string; status: string; code?: string; detail?: string }
-interface Saved { asked?: boolean; joined?: boolean; tower?: boolean }
+interface Saved { tower?: boolean }
 type Role = "tower" | "main" | "member";
 type Scope = "tab" | "workspace" | "towers" | "all";
 type Member = ReturnType<typeof netMembers>[number];
-export interface Deps { run?: HerdrRun; api?: HerdrApi; env?: NodeJS.ProcessEnv; sleep?: Sleep; promptDir?: string; bundle?: string; openUrl?: (url: string) => Promise<void>; stateDir?: string }
+export interface Deps { run?: HerdrRun; api?: HerdrApi; env?: NodeJS.ProcessEnv; sleep?: Sleep; promptDir?: string; bundle?: string; openUrl?: (url: string) => Promise<void>; stateDir?: string; autoTower?: boolean }
 
 /** Live sessions whose pane carries an `sb_role` token: the sessions that joined the net, and towers. */
 function netMembers(sessions: Session[], ps: Pane[]) {
@@ -45,12 +45,14 @@ function netMembers(sessions: Session[], ps: Pane[]) {
 }
 const nameOf = (s?: Session) => (s ? (s.name ?? s.id) : "");
 
-export function createStrawBoss({ run = herdrRun, api = herdrApi(), env = process.env, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), promptDir = fileURLToPath(new URL("../prompts", import.meta.url)), bundle, openUrl = openBrowser, stateDir }: Deps = {}) {
+export function createStrawBoss({ run = herdrRun, api = herdrApi(), env = process.env, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), promptDir = fileURLToPath(new URL("../prompts", import.meta.url)), bundle, openUrl = openBrowser, stateDir, autoTower = true }: Deps = {}) {
 	return function strawBoss(pi: ExtensionAPI): void {
 		// Outside Herdr there is no tab to coordinate. A pi-herdr-agents worker never joins: its parent represents it.
 		if (!env.HERDR_PANE_ID || env.PI_SUBAGENT_ID) return;
 		let isTower = env.STRAW_BOSS_ROLE === "tower";
-		let asked = false, joined = false, isMain = false, holdsTower = false, requests = 0;
+		let joined = false, isMain = false, holdsTower = false, requests = 0;
+		// 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.
+		let mainId: string | undefined, pinned: string | undefined, joining: Promise<void> | undefined;
 		// Why this session cannot join: it sits in a sub workspace, or Herdr could not say whether it does.
 		let barred: string | undefined, dashboard: ReturnType<typeof startDashboard> | undefined, hasUI = false;
 		let prompts: Record<string, string> = {}, info: Record<string, string> = {}, saved: Saved = {};
@@ -75,6 +77,7 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), env = proces
 				},
 			});
 		const connect = (eligible: boolean) => {
+			if (c) return; // a join that failed after registering retries on the channel it has
 			const namespace = `straw-boss/tab/${Buffer.from(at.tabId).toString("hex")}`;
 			if (!NAMESPACE.test(namespace)) throw new Error(`Tab id ${at.tabId} is too long for an intercom namespace (limit 24 characters)`);
 			pi.events.emit(REGISTER, { namespace, ownerEligible: eligible, onReady: (channel: Channel) => (c = channel), onEvent });
@@ -92,33 +95,53 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), env = proces
 			timer.unref();
 		};
 
-		// The owner records who is main. The first joiner pins itself, so a later owner change never swaps the main agent.
-		const pin = (main?: string) => {
-			if (main && c.snapshot().owner?.sessionId === me()) c.commitState({ v: 1, main, since: Date.now() });
+		// The owner records who is main. Promotion is first come, first served, and the main stays until it leaves: a later owner change never swaps it.
+		const pin = (main: string) => {
+			if (c.snapshot().owner?.sessionId !== me()) return;
+			c.commitState({ v: 1, main, since: Date.now() });
+			pinned = main;
 		};
-		const onEvent = (event: { type: string; fromSessionId?: string; payload?: { type?: string } }) => {
-			if (event.type === "message" && event.payload?.type === "claim") pin(event.fromSessionId);
-			else if (["connection", "owner", "state", "session_left"].includes(event.type)) void sync();
+		// The owner decides a claim: a tab has one main, so a claim is dropped while a live main exists, unless the user forced it with /boss.
+		const claim = async (from: string, force: boolean) => {
+			try {
+				if (c.snapshot().owner?.sessionId !== me()) return;
+				const current = pinned ?? (c.snapshot().state?.payload as { main?: string } | undefined)?.main;
+				if (!force && current && current !== from && (await c.listSessions()).some((s) => s.id === current)) return;
+				pin(from);
+			} catch (error) {
+				tell(`Straw Boss: ${(error as Error).message}`, "warning");
+			}
+		};
+		const onEvent = (event: { type: string; fromSessionId?: string; owner?: { sessionId: string }; payload?: { type?: string; force?: boolean } }) => {
+			// Ownership moved away: what this session pinned as owner is no longer its to defend.
+			if (event.type === "owner" && event.owner?.sessionId !== me()) pinned = undefined;
+			// A join that failed at start (intercom not connected yet, no owner yet) is retried when the channel changes.
+			if (!joined && !barred && !isTower && c && ["connection", "owner"].includes(event.type)) void joinNet().catch(() => {});
+			if (event.type === "message" && event.payload?.type === "claim" && event.fromSessionId) {
+				const [from, force] = [event.fromSessionId, Boolean(event.payload.force)];
+				queue = queue.then(() => claim(from, force));
+			} else if (["connection", "owner", "state", "session_left"].includes(event.type)) void sync();
 			if (["presence_update", "session_joined", "session_left"].includes(event.type)) dashboard?.poke();
 		};
 		const refresh = async () => {
 			if (!joined) return;
 			try {
 				const snap = c.snapshot();
+				if (snap.owner?.sessionId !== me()) pinned = undefined;
 				const sessions = await c.listSessions();
-				let main = (snap.state?.payload as { main?: string } | undefined)?.main;
-				if (!sessions.some((s) => s.id === main)) {
-					// The pinned main is gone: the owner is main until it pins itself.
-					main = snap.owner?.sessionId;
-					pin(main);
-				}
+				// A main that has left leaves the tab without one until a member promotes.
+				const recorded = (snap.state?.payload as { main?: string } | undefined)?.main;
+				if (pinned === recorded) pinned = undefined; // the broker has echoed it
+				mainId = sessions.find((s) => s.id === (pinned ?? recorded))?.id;
 				const ws = (await workspaces(run)).find((w) => w.workspace_id === at.workspaceId);
 				const tab = sessions.find((s) => s.id === me())?.herdrLocation?.tab?.label ?? at.tabId;
-				info = { tab, workspace: ws?.label ?? at.workspaceId, main: nameOf(sessions.find((s) => s.id === main)), tower: nameOf(sessions.find((s) => s.id === ws?.tokens?.tower)) };
+				info = { tab, workspace: ws?.label ?? at.workspaceId, main: nameOf(sessions.find((s) => s.id === mainId)), tower: nameOf(sessions.find((s) => s.id === ws?.tokens?.tower)) };
 				const wasMain = isMain;
-				isMain = main === me();
+				isMain = mainId === me();
 				if (isMain !== wasMain) tell(`This session is ${isMain ? "now" : "no longer"} the main agent of ${info.tab}`);
 				await publish();
+				// 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) {
 				tell(`Straw Boss: ${(error as Error).message}`, "warning");
 			}
@@ -129,27 +152,40 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), env = proces
 			if (await waitFor(sleep, () => channel.snapshot().connected && channel.snapshot().supported, CONNECT_MS)) return;
 			throw new Error(channel.snapshot().connected ? "The intercom broker lacks extension-bus-v1" : "pi-intercom is not connected");
 		};
-		const joinNet = async (restored = false) => {
-			if (joined) return;
-			if (barred) throw new Error(barred);
-			at = await place(run);
-			connect(true);
-			await connected();
-			if (!(await waitFor(sleep, () => c.snapshot().owner, CLAIM_MS))) throw new Error("No intercom owner was elected for this tab");
-			joined = true;
-			if (!restored) pi.appendEntry(ENTRY, { asked: true, joined: true });
-			addNetTools();
-			keepFresh();
-			await sync();
-		};
-		const takeover = async () => {
+		// Every joinable session joins at start as a member (owner-eligible, so the tab channel always has an owner). One join at a time.
+		const joinNet = () =>
+			(joining ??= (async () => {
+				if (joined) return;
+				if (barred) throw new Error(barred);
+				at = await place(run);
+				connect(true);
+				await connected();
+				if (!(await waitFor(sleep, () => c.snapshot().owner, CLAIM_MS))) throw new Error("No intercom owner was elected for this tab");
+				joined = true;
+				addNetTools();
+				addPromote();
+				keepFresh();
+				await sync();
+			})().catch((error) => {
+				joining = undefined;
+				throw error;
+			}));
+		// Becoming the tab's main agent. Without `force` a tab that already has a live main refuses; /boss forces.
+		const promote = async (force: boolean): Promise<{ promoted: boolean; text: string }> => {
 			await joinNet();
-			if (!isMain) {
-				if (c.snapshot().owner?.sessionId === me()) pin(me());
-				else c.publish({ type: "claim" }, { audience: "owner" });
-				if (!(await waitFor(sleep, () => isMain, CLAIM_MS))) throw new Error("The owner did not confirm the takeover within 5 s");
+			await sync();
+			if (isMain) return { promoted: true, text: `You are already the main agent of tab ${info.tab}.` };
+			const refused = () => ({ promoted: false, text: `Tab ${info.tab} already has a main agent, ${info.main}. Stay a member: you may dispatch your own subagents, but tell ${info.main} through intercom first what you will do and which resources you will use.` });
+			if (!force && mainId) return refused();
+			if (c.snapshot().owner?.sessionId === me()) await (queue = queue.then(() => claim(me(), force)));
+			else c.publish({ type: "claim", force }, { audience: "owner" });
+			if (!(await waitFor(sleep, () => isMain, CLAIM_MS))) {
+				await sync();
+				if (isMain) return { promoted: true, text: `You are now the main agent of tab ${info.tab}.` };
+				if (!force && mainId && mainId !== me()) return refused();
+				throw new Error("The owner did not confirm the promotion within 5 s");
 			}
-			return `This session is the main agent of tab ${info.tab}`;
+			return { promoted: true, text: `You are now the main agent of tab ${info.tab}.` };
 		};
 		const send = (to: string, message: string) =>
 			new Promise<SendResult>((resolve) => {
@@ -237,6 +273,13 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), env = proces
 				}),
 				({ message, scope }) => broadcast(message, scope ?? "workspace"));
 		}
+		function addPromote() {
+			tool("boss_promote", "Become the main agent of this Herdr tab when your work grows: several steps, dispatching workers, or touching more than one app. Refused when the tab already has a main agent.", Type.Object({}), async () => {
+				const { promoted, text } = await promote(false);
+				if (!promoted) throw new Error(text);
+				return { text, details: { role: role() } };
+			});
+		}
 		const startTower = async () => {
 			at = await place(run);
 			connect(false);
@@ -281,7 +324,6 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), env = proces
 			hasUI = ctx.hasUI;
 			prompts = Object.fromEntries(PROMPTS.map((name) => [name, readFileSync(join(promptDir, `${name}.md`), "utf8").trim()]));
 			saved = Object.assign({}, ...ctx.sessionManager.getBranch().flatMap((e) => (e.type === "custom" && e.customType === ENTRY ? [e.data] : [])));
-			asked = Boolean(saved.asked);
 			isTower ||= Boolean(saved.tower);
 			// Starting runs in the background: pi awaits session_start handlers in turn, and pi-intercom connects in its own, after this one.
 			let starting: Promise<void> | undefined;
@@ -293,12 +335,7 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), env = proces
 				if (bar) {
 					tell(bar.text, bar.level);
 				} else {
-					tool("boss_join", "Join this Herdr workspace's Straw Boss net when your current work competes for resources with, or collaborates with, other work in the workspace. The first session of a tab to join becomes its main agent; later ones are members.", Type.Object({}), async () => {
-						await joinNet();
-						const text = isMain ? `Joined as the main agent of tab ${info.tab}.` : `Joined tab ${info.tab} as a member; its main agent is ${info.main}.`;
-						return { text, details: { role: role() } };
-					});
-					if (saved.joined) starting = joinNet(true);
+					starting = joinNet();
 				}
 			}
 			starting?.catch((error: Error) => tell(`Straw Boss: ${error.message}`, "error"));
@@ -306,19 +343,22 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), env = proces
 
 		pi.on("before_agent_start", (event) => {
 			const current = role();
-			// A session outside the net is asked once, at its first run, whether it should join.
-			const first = !current && !asked && !barred;
-			if (first) {
-				asked = true;
-				pi.appendEntry(ENTRY, { asked: true });
-			}
-			let text: string | undefined;
-			if (current) text = render(prompts[current]);
-			else if (first) text = render(prompts.reminder);
-			if (text) event.systemPromptOptions.sections[ENTRY] = text;
+			const name = current === "member" && !mainId ? "member-no-main" : current;
+			if (name) event.systemPromptOptions.sections[ENTRY] = render(prompts[name]);
 			else delete event.systemPromptOptions.sections[ENTRY];
 		});
 
+		// A member that dispatches a subagent without promoting is promoted here, before the subagent starts, unless the tab already has a main.
+		pi.on("tool_call", async (event) => {
+			if (event.toolName !== "subagent" || isTower || barred) return;
+			try {
+				await joinNet();
+				if (!isMain) await promote(false);
+			} catch (error) {
+				tell(`Straw Boss: ${(error as Error).message}`, "warning");
+			}
+		});
+
 		pi.on("session_shutdown", async () => {
 			await gui?.stop();
 			gui = undefined;
@@ -357,7 +397,7 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), env = proces
 			// in this session share one start.
 			opening ??= (async () => {
 				if (gui) return gui.url;
-				const shared = await sharedGui(guiDir, `${me() || "unknown"} (pane ${env.HERDR_PANE_ID})`, (prefer) => startGui({ read: () => collectNet({ run, sessions }), dir: bundle, ...prefer }), sleep);
+				const shared = await sharedGui(guiDir, `${me() || "unknown"} (pane ${env.HERDR_PANE_ID})`, (prefer) => { const net = netSource({ run, sessions }); return startGui({ read: net.read, net, dir: bundle, ...prefer }); }, sleep);
 				gui = shared.mine;
 				return shared.url;
 			})().finally(() => (opening = undefined));
@@ -367,14 +407,14 @@ export function createStrawBoss({ run = herdrRun, api = herdrApi(), env = proces
 		};
 
 		pi.registerCommand("boss", {
-			description: "Join this tab's Straw Boss net and become its main agent. /boss status shows the coordinators; /boss tower opens and focuses the workspace tower; /boss gui opens the net in the browser (/boss gui stop closes it).",
+			description: "Take over as this tab's main agent (every session already joins as a member). /boss status shows the coordinators; /boss tower opens and focuses the workspace tower; /boss gui opens the net in the browser (/boss gui stop closes it).",
 			handler: async (args, ctx) => {
 				ui = ctx.ui;
 				try {
 					if (/^gui( stop)?$/.test(args.trim())) return await guiCommand(args.trim() === "gui stop");
-					if (args.trim() === "status") return tell(joined || isTower ? JSON.stringify(await status(), null, 2) : "Not in the net. /boss joins it.");
+					if (args.trim() === "status") return tell(joined || isTower ? JSON.stringify(await status(), null, 2) : "Not in the net: still joining, or this session cannot join.");
 					if (isTower) throw new Error("This session is the tower, not a main agent");
-					if (args.trim() !== "tower") return tell(await takeover());
+					if (args.trim() !== "tower") return tell((await promote(true)).text);
 					await joinNet();
 					const tower = await openTower();
 					const where = (await c.listSessions()).find((s) => s.id === tower.id)?.herdrLocation;

package/src/items.ts

@@ -0,0 +1,93 @@
+import { type FileHandle, open } from "node:fs/promises";
+import { basename } from "node:path";
+
+// Session entries as displayable items: what the chat shows for each kind of entry, with previews capped so a page stays small.
+// `full` lifts the caps for the one-entry fetch (thinking text, whole tool result, images).
+
+const PREVIEW = 2048, FULL = 1 << 20, TEXT = 100_000, LAST_BYTES = 65_536;
+export const FULL_LIMIT = FULL;
+
+export interface Tool { id: string; name: string; summary: string; args?: string }
+export interface Item {
+	id: string; kind: "user" | "assistant" | "result" | "bash" | "notice" | "divider" | "meta"; at?: string; text?: string; more?: boolean; images?: number; pics?: string[];
+	thought?: number; thoughtText?: string; tools?: Tool[]; model?: string; stop?: string; error?: string; ctx?: number;
+	callId?: string; name?: string; isError?: boolean; bytes?: number; command?: string; exit?: number; type?: string; from?: string; link?: string; tokens?: number;
+}
+export interface Json { [key: string]: any } // eslint-disable-line @typescript-eslint/no-explicit-any -- session entries are untrusted JSON, read defensively
+
+const clip = (s: string, n: number) => (s.length > n ? s.slice(0, n) : s);
+const first = (v: unknown, n = 160) => clip(String(v ?? "").split("\n")[0] ?? "", n);
+const blocks = (c: unknown): Json[] => (Array.isArray(c) ? c : []);
+const textOf = (c: unknown) => (typeof c === "string" ? c : blocks(c).filter((b) => b?.type === "text").map((b) => String(b.text)).join("\n"));
+export const parse = (s: string): Json | undefined => {
+	try {
+		return JSON.parse(s);
+	} catch {
+		return undefined;
+	}
+};
+const pics = (c: unknown) => blocks(c).filter((b) => b?.type === "image" && /^image\/(png|jpe?g|gif|webp)$/.test(b.mimeType)).map((b) => `data:${b.mimeType};base64,${b.data}`);
+const idOf = (file: string) => basename(file, ".jsonl").split("_").pop()!;
+
+function toolLine(name: string, a: Json): string {
+	switch (name) {
+		case "bash": return first(a.command);
+		case "read": case "edit": case "write": return first(a.path ?? a.file_path);
+		case "subagent": case "subagent_resume": return [a.name, a.agent].filter(Boolean).join(" · ");
+		case "intercom": return [a.action, a.to, first(a.message, 80)].filter(Boolean).join(" ");
+		case "ask_user": return first(a.question ?? a.questions?.[0]?.question);
+		case "show_doc": return first([a.paths].flat().join(", "));
+		case "todo": return [a.action, first(a.subject ?? a.id, 80)].filter(Boolean).join(" ");
+		case "MonitorCreate": return first(a.description ?? a.command);
+		default: return `(${first(Object.values(a)[0], 100)})`;
+	}
+}
+
+/** One session entry as an item, or undefined for kinds the chat does not show. `full` lifts the preview caps (thinking text, whole tool result). */
+export function toItem(d: Json, len: number, full = false): Item | undefined {
+	const base = { id: String(d.id), at: d.timestamp as string | undefined };
+	const m: Json = d.message ?? {}, limit = full ? FULL : PREVIEW;
+	const preview = (s: string, kind: "result" | "bash") => ({ text: clip(s, limit), more: s.length > limit, ...(kind === "result" ? { bytes: len } : {}) });
+	switch (d.type === "message" ? m.role : d.type) {
+		case "user": return { ...base, kind: "user", text: clip(textOf(m.content), TEXT), images: blocks(m.content).filter((b) => b?.type === "image").length, ...(full ? { pics: pics(m.content) } : {}) };
+		case "assistant": {
+			const thinking = blocks(m.content).filter((b) => b?.type === "thinking");
+			const thought = thinking.reduce((n, b) => n + String(b.thinking ?? "").length, 0);
+			const tools = blocks(m.content).filter((b) => b?.type === "toolCall").map((b): Tool => ({ id: b.id, name: b.name, summary: toolLine(b.name, b.arguments ?? {}), args: clip(JSON.stringify(b.arguments ?? {}, null, 1), full ? FULL : 1500) }));
+			const stop = ["error", "aborted", "length"].includes(m.stopReason) ? m.stopReason : undefined;
+			return { ...base, kind: "assistant", text: clip(textOf(m.content), TEXT), thought: thought || (thinking.length ? -1 : undefined), ...(full ? { thoughtText: thinking.map((b) => b.thinking).join("\n\n") } : {}), tools, model: m.model, stop, error: m.errorMessage, ctx: m.usage?.totalTokens };
+		}
+		case "toolResult": return { ...base, kind: "result", callId: m.toolCallId, name: m.toolName, isError: Boolean(m.isError), images: blocks(m.content).filter((b) => b?.type === "image").length, ...(full ? { pics: pics(m.content) } : {}), ...preview(textOf(m.content), "result") };
+		case "bashExecution": return { ...base, kind: "bash", command: first(m.command, 400), exit: m.exitCode, ...preview(String(m.output ?? ""), "bash") };
+		case "custom_message": {
+			if (!d.display) return undefined;
+			const sessionFile = d.details?.sessionFile;
+			return { ...base, kind: "notice", type: d.customType, text: clip(textOf(d.content), full ? FULL : 600), from: d.details?.from?.name ?? d.details?.name, link: typeof sessionFile === "string" ? idOf(sessionFile) : undefined };
+		}
+		case "compaction": return { ...base, kind: "divider", type: "compaction", tokens: d.tokensBefore, text: clip(String(d.summary ?? ""), full ? FULL : 600) };
+		case "branch_summary": return { ...base, kind: "divider", type: "branch", text: clip(String(d.summary ?? ""), full ? FULL : 600) };
+		case "model_change": return { ...base, kind: "meta", text: `model ${d.provider}/${d.modelId}` };
+		case "thinking_level_change": return { ...base, kind: "meta", text: `thinking ${d.thinkingLevel}` };
+		case "session_info": return { ...base, kind: "meta", text: `session named ${d.name}` };
+		default: return undefined;
+	}
+}
+
+/** The last assistant text of a session file, from its last 64 KB: what a workspace card shows. */
+export async function lastLine(file: string): Promise<string> {
+	let fh: FileHandle | undefined;
+	try {
+		fh = await open(file, "r");
+		const { size } = await fh.stat(), start = Math.max(0, size - LAST_BYTES), buf = Buffer.alloc(size - start);
+		await fh.read(buf, 0, buf.length, start);
+		for (const line of buf.toString("utf8").split("\n").slice(start ? 1 : 0).reverse()) {
+			const text = textOf((line.includes('"role":"assistant"') ? parse(line) : undefined)?.message?.content).trim().split("\n").filter(Boolean).at(-1);
+			if (text) return clip(text, 240);
+		}
+	} catch {} // an unreadable or missing file simply has no last line
+	finally {
+		await fh?.close();
+	}
+	return "";
+}
+