@gavin-hu/my-pi-agent 0.17.0 → 0.18.0

package/extensions/session-bus/tui.ts

@@ -0,0 +1,394 @@
+/**
+ * The `/sessions` board: a docked list over the bus, with three scopes.
+ *
+ * `Tab` cycles Sessions → Inbox → Claims. Sessions and claims come from the bus
+ * snapshot, mail from a read-only peek, so the board announces nothing and
+ * consumes nothing. The rows, summaries, and focus blocks are in `rows.ts`; this
+ * module owns the screen, the scope it shows, and the two verbs that change this
+ * session's own state.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { matchesKey, Key } from "@earendil-works/pi-tui";
+import { messageOf } from "../../lib/errors.ts";
+import { formatDuration, sanitizeLine } from "../../lib/format.ts";
+import type { ScreenHint, ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { type DetailContents, DockListScreen } from "../../lib/tui/dock-screen.ts";
+import { SEPARATORS } from "../../lib/tui/glyphs.ts";
+import { keyValueRow } from "../../lib/tui/rows.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import { shortId } from "./format.ts";
+import {
+	type SessionRow,
+	claimRowLine,
+	count,
+	messageRowLine,
+	sessionDetailBlock,
+	sessionRowLine,
+	sessionRows,
+	summaryCells,
+} from "./rows.ts";
+import type { BoardSnapshot, BusMessage, ClaimRecord } from "./types.ts";
+
+/** The scopes `Tab` cycles through. */
+export type BoardScope = "sessions" | "inbox" | "claims";
+
+/** One row of the board, whichever scope is showing. */
+type BoardRow =
+	| { kind: "session"; row: SessionRow }
+	| { kind: "message"; message: BusMessage }
+	| { kind: "claim"; claim: ClaimRecord };
+
+const SCOPE_ORDER: readonly BoardScope[] = ["sessions", "inbox", "claims"];
+
+const SCOPE_TITLE: Readonly<Record<BoardScope, string>> = {
+	sessions: "Sessions",
+	inbox: "Inbox",
+	claims: "Claims",
+};
+
+const SCOPE_EMPTY: Readonly<Record<BoardScope, string>> = {
+	sessions: "No sessions on this bus.",
+	inbox: "No unread mail.",
+	claims: "No claims.",
+};
+
+/** A relative age for a message or a claim, e.g. `2.0s ago`, `5m00s ago`. */
+function ago(at: number, now: number): string {
+	return `${formatDuration(Math.max(0, now - at))} ago`;
+}
+
+/** A message body as prose: one paragraph per source line, control characters gone. */
+function messageProse(message: BusMessage): string {
+	return message.text
+		.split("\n")
+		.map((line) => sanitizeLine(line))
+		.join("\n");
+}
+
+/** The paths a message mentions, or an empty string. */
+function messagePaths(message: BusMessage): string {
+	return message.paths?.length ? message.paths.map((path) => sanitizeLine(path)).join(", ") : "";
+}
+
+/** The pane's width-dependent facts: identity, above the claim body. */
+function paneFacts(theme: Theme, row: SessionRow, now: number, width: number): string[] {
+	const labelWidth = 10;
+	return [
+		keyValueRow(theme, width, { label: "mode", labelWidth, value: sanitizeLine(row.session.mode) }),
+		keyValueRow(theme, width, { label: "id", labelWidth, value: shortId(row.session.id) }),
+		keyValueRow(theme, width, {
+			label: "last seen",
+			labelWidth,
+			value: ago(row.session.lastSeen, now),
+		}),
+	];
+}
+
+/** The pane body: every claim this session holds, in path order. */
+function paneLines(row: SessionRow, now: number): string[] {
+	return row.claims.map((claim) => `${sanitizeLine(claim.path)}${SEPARATORS.item}held ${ago(claim.at, now)}`);
+}
+
+/** A cheap signature of what the board draws, so a poll repaints only on a change. */
+function boardKey(board: BoardSnapshot | undefined): string {
+	if (!board) return "";
+	return [
+		...board.status.sessions.map(
+			(session) =>
+				`${session.id}:${session.label}:${session.unread}:${session.lastSeen}:${session.mode}:${session.cwd}`,
+		),
+		...board.status.claims.map((claim) => `${claim.path}:${claim.owner}:${claim.ownerLabel}:${claim.at}`),
+		board.status.watching ? `${board.status.watching.armed}:${board.status.watching.wake}` : "",
+		...board.messages.map((message) => `${message.id}:${message.at}`),
+	].join("|");
+}
+
+export interface SessionListCallbacks {
+	/** Arm (or disarm) this session's inbox watch, returning the line to show. */
+	toggleWatch(armed: boolean): Promise<string>;
+	/** Release one of this session's claims, returning the line to show. */
+	releaseClaim(path: string): Promise<string>;
+}
+
+interface SessionListOptions {
+	/** The latest board, or undefined before the first read. */
+	latest(): BoardSnapshot | undefined;
+	theme: Theme;
+	callbacks: SessionListCallbacks;
+	onClose(): void;
+	requestRender(): void;
+	now?: () => number;
+	viewportRowsSource?: ViewportRowsSource;
+}
+
+/**
+ * The `/sessions` board.
+ *
+ * The rows are derived from a board the command's poll supplies, so the screen
+ * never reads the bus itself; `liveDetail` keeps an open pane in step with that
+ * board, so a peer that expires or a message that is consumed closes its own pane.
+ * The focus is anchored by a scope-prefixed id, so switching scopes lands on the
+ * first row of the new list instead of a row that is no longer there.
+ */
+export class SessionListComponent extends DockListScreen<BoardRow> {
+	private board: BoardSnapshot | undefined;
+	private scope: BoardScope = "sessions";
+	private readonly callbacks: SessionListCallbacks;
+	private readonly now: () => number;
+
+	constructor(options: SessionListOptions) {
+		super({
+			theme: options.theme,
+			title: "Sessions",
+			detailTitle: "Details",
+			emptyList: "No sessions on this bus.",
+			emptyDetail: "Nothing to show.",
+			requestRender: options.requestRender,
+			onClose: options.onClose,
+			viewportRowsSource: options.viewportRowsSource,
+		});
+		this.callbacks = options.callbacks;
+		this.now = options.now ?? Date.now;
+		this.board = options.latest();
+	}
+
+	/** Replace the board; a poll that changed nothing does not repaint. */
+	setBoard(board: BoardSnapshot | undefined): void {
+		const before = boardKey(this.board);
+		this.board = board;
+		if (boardKey(board) !== before) this.options.requestRender();
+	}
+
+	/** The scope currently listed, for a test or a caller that wants to label it. */
+	get currentScope(): BoardScope {
+		return this.scope;
+	}
+
+	protected headerLabel(): string {
+		return SCOPE_TITLE[this.scope];
+	}
+
+	protected emptyLabel(): string {
+		return SCOPE_EMPTY[this.scope];
+	}
+
+	protected rows(): readonly BoardRow[] {
+		switch (this.scope) {
+			case "sessions":
+				return sessionRows(this.board?.status).map((row) => ({ kind: "session", row }));
+			case "inbox":
+				return (this.board?.messages ?? []).map((message) => ({ kind: "message", message }));
+			case "claims":
+				return (this.board?.status.claims ?? []).map((claim) => ({ kind: "claim", claim }));
+		}
+	}
+
+	protected idOf(row: BoardRow): string {
+		switch (row.kind) {
+			case "session":
+				return `s:${row.row.session.id}`;
+			case "message":
+				return `m:${row.message.id}`;
+			case "claim":
+				return `c:${row.claim.path}`;
+		}
+	}
+
+	protected rowLine(row: BoardRow, width: number, selected: boolean): string {
+		switch (row.kind) {
+			case "session":
+				return sessionRowLine(row.row, this.theme, width, { selected });
+			case "message":
+				return messageRowLine(row.message, this.theme, width, { selected });
+			case "claim":
+				return claimRowLine(row.claim, this.theme, width, {
+					selected,
+					self: row.claim.owner === this.me(),
+				});
+		}
+	}
+
+	protected detailBlock(row: BoardRow): string[] {
+		switch (row.kind) {
+			case "session":
+				return sessionDetailBlock(row.row, this.now());
+			case "message": {
+				const lines = [`received: ${ago(row.message.at, this.now())}`];
+				const paths = messagePaths(row.message);
+				if (paths) lines.push(`paths: ${paths}`);
+				return lines;
+			}
+			case "claim":
+				return [`held ${ago(row.claim.at, this.now())}`];
+		}
+	}
+
+	protected summaryCells(rows: readonly BoardRow[]): string[] {
+		const watching = this.board?.status.watching;
+		switch (this.scope) {
+			case "sessions": {
+				const sessions = rows.flatMap((row) => (row.kind === "session" ? [row.row] : []));
+				return summaryCells(this.theme, sessions, watching);
+			}
+			case "inbox": {
+				const cells = [paint(this.theme, "meta", count(rows.length, "unread message"))];
+				if (watching) cells.push(this.watchCell(watching));
+				return cells;
+			}
+			case "claims": {
+				const own = rows.flatMap((row) => (row.kind === "claim" && row.claim.owner === this.me() ? [row] : []));
+				const cells = [paint(this.theme, "meta", count(rows.length, "claim"))];
+				if (own.length > 0) cells.push(paint(this.theme, "label", `${own.length} yours`));
+				return cells;
+			}
+		}
+	}
+
+	protected listHints(): ScreenHint[] {
+		const tab = (scope: BoardScope): ScreenHint => ({ text: `Tab ${SCOPE_TITLE[scope].toLowerCase()}` });
+		const enter = (verb: string): ScreenHint => ({ text: `Enter ${verb}`, color: "accent" });
+		const hints: ScreenHint[] = ["Esc", tab(this.nextScope())];
+		switch (this.scope) {
+			case "sessions":
+				hints.push(enter("open"), this.watchHint(), "↑/↓", "PgUp/PgDn");
+				break;
+			case "inbox":
+				hints.push(enter("read"), this.watchHint(), "↑/↓", "PgUp/PgDn");
+				break;
+			case "claims":
+				hints.push(enter("open"), { text: "x release", color: "warning" }, "↑/↓", "PgUp/PgDn");
+				break;
+		}
+		return hints;
+	}
+
+	protected detailHints(row: BoardRow | undefined): ScreenHint[] {
+		if (row?.kind === "claim" && row.claim.owner === this.me()) {
+			return ["Esc back", { text: "x release", color: "warning" }, "↑/↓ scroll", "g/G ends"];
+		}
+		return ["Esc back", "↑/↓ scroll", "g/G ends", "PgUp/PgDn"];
+	}
+
+	protected detailFor(row: BoardRow): DetailContents {
+		switch (row.kind) {
+			case "session":
+				return {
+					title: `${sanitizeLine(row.row.session.label)}${row.row.self ? " · you" : ""}`,
+					subtitle: sanitizeLine(row.row.session.cwd),
+					lines: paneLines(row.row, this.now()),
+					tail: false,
+					facts: (width) => paneFacts(this.theme, row.row, this.now(), width),
+				};
+			case "message": {
+				const paths = messagePaths(row.message);
+				return {
+					title: `${sanitizeLine(row.message.fromLabel)}${SEPARATORS.item}${sanitizeLine(row.message.kind)}`,
+					subtitle: `${ago(row.message.at, this.now())}${paths ? `${SEPARATORS.item}paths: ${paths}` : ""}`,
+					text: messageProse(row.message),
+					tail: false,
+				};
+			}
+			case "claim": {
+				// A claim's pane is the session that holds it: identity plus everything it holds.
+				const owner = this.ownerRow(row.claim.owner);
+				return {
+					title: sanitizeLine(row.claim.ownerLabel),
+					subtitle: `holds ${sanitizeLine(row.claim.path)}${SEPARATORS.item}held ${ago(row.claim.at, this.now())}`,
+					lines: owner ? paneLines(owner, this.now()) : [],
+					tail: false,
+					...(owner ? { facts: (width: number) => paneFacts(this.theme, owner, this.now(), width) } : {}),
+				};
+			}
+		}
+	}
+
+	protected detailById(id: string): { lines: string[] } | undefined {
+		const row = this.rows().find((candidate) => this.idOf(candidate) === id);
+		if (!row) return undefined;
+		switch (row.kind) {
+			case "session":
+				return { lines: paneLines(row.row, this.now()) };
+			case "claim": {
+				const owner = this.ownerRow(row.claim.owner);
+				return { lines: owner ? paneLines(owner, this.now()) : [] };
+			}
+			case "message":
+				// The pane's body is prose, which the base owns; its presence is all this answers.
+				return { lines: [] };
+		}
+	}
+
+	protected liveDetail(): boolean {
+		return true;
+	}
+
+	protected handleVerb(key: string, focused: BoardRow | undefined): void {
+		if (matchesKey(key, Key.tab)) {
+			this.cycleScope();
+			return;
+		}
+		if (key === "w") {
+			this.toggleWatch();
+			return;
+		}
+		if (key === "x" && focused?.kind === "claim") this.release(focused.claim);
+	}
+
+	protected handleDetailVerb(key: string, row: BoardRow): boolean {
+		if (key !== "x" || row.kind !== "claim") return false;
+		this.release(row.claim);
+		return true;
+	}
+
+	private me(): string {
+		return this.board?.status.me.id ?? "";
+	}
+
+	/** The row for the session with `id`, when it is still on the board. */
+	private ownerRow(id: string): SessionRow | undefined {
+		return sessionRows(this.board?.status).find((row) => row.session.id === id);
+	}
+
+	private nextScope(): BoardScope {
+		const index = SCOPE_ORDER.indexOf(this.scope);
+		return SCOPE_ORDER[(index + 1) % SCOPE_ORDER.length] ?? "sessions";
+	}
+
+	private cycleScope(): void {
+		this.scope = this.nextScope();
+		this.options.requestRender();
+	}
+
+	private watchCell(watching: { armed: boolean; wake: boolean }): string {
+		return paint(this.theme, "ok", watching.wake ? "watch wake" : "watch on");
+	}
+
+	private watchHint(): ScreenHint {
+		return this.board?.status.watching
+			? { text: "w watch off", color: "warning" }
+			: { text: "w watch on", color: "accent" };
+	}
+
+	private toggleWatch(): void {
+		const armed = this.board?.status.watching !== undefined;
+		void this.callbacks
+			.toggleWatch(armed)
+			.then((line) => this.notify(line))
+			.catch((error) => this.notify(messageOf(error)));
+	}
+
+	private release(claim: ClaimRecord): void {
+		const path = sanitizeLine(claim.path);
+		if (claim.owner !== this.me()) {
+			this.notify(`${path} is ${sanitizeLine(claim.ownerLabel)}'s claim; not released.`);
+			return;
+		}
+		this.confirm(`Release ${path}? y/N`, () => {
+			void this.callbacks
+				.releaseClaim(claim.path)
+				.then((line) => this.notify(line))
+				.catch((error) => this.notify(messageOf(error)));
+		});
+	}
+}

package/extensions/session-bus/types.ts

@@ -0,0 +1,98 @@
+/**
+ * Shared shapes for the session bus.
+ *
+ * These describe the files and the tool result only; the file I/O lives in
+ * `store.ts` and the lifecycle in `runtime.ts`.
+ */
+
+import type { MessageKind, SessionMode } from "./protocol.ts";
+
+/** One registered Pi session. */
+export interface SessionRecord {
+	id: string;
+	label: string;
+	pid: number;
+	/** Working directory of the session; the worktree root when there is one. */
+	cwd: string;
+	/** Repository root the session belongs to, for relative claims. */
+	repoRoot: string;
+	/** The mode the session was started in. */
+	mode: SessionMode;
+	startedAt: number;
+	lastSeen: number;
+}
+
+/** One message waiting in a recipient's inbox. */
+export interface BusMessage {
+	id: string;
+	from: string;
+	fromLabel: string;
+	/** Recipient session id. */
+	to: string;
+	toLabel: string;
+	kind: MessageKind;
+	text: string;
+	paths?: string[];
+	at: number;
+}
+
+/** One repository-relative claim. */
+export interface ClaimRecord {
+	path: string;
+	owner: string;
+	ownerLabel: string;
+	at: number;
+}
+
+/** What `session status` returns. */
+export interface SessionStatus {
+	me: { id: string; label: string };
+	sessions: Array<SessionRecord & { unread: number }>;
+	claims: ClaimRecord[];
+	/** The newest split in this repository, and who holds each unit, on an explicit status call. */
+	units?: {
+		team: string;
+		joined: number;
+		total: number;
+		rows: Array<{ unit: string; lead?: boolean; holder?: string }>;
+	};
+	/** Present only when this session armed its inbox watch. */
+	watching?: { armed: boolean; wake: boolean };
+}
+
+/** A conflict returned by `session claim`. */
+export interface ClaimConflict {
+	path: string;
+	owner: string;
+	ownerLabel: string;
+}
+
+/**
+ * What the board reads in one poll: the bus as it stands, and this session's
+ * unread mail. Peeking never consumes, so the notice and `inbox` are unaffected.
+ */
+export interface BoardSnapshot {
+	status: SessionStatus;
+	messages: BusMessage[];
+}
+
+/** Structured result carried in the `session` tool's details. */
+export interface SessionDetails {
+	action: "status" | "send" | "inbox" | "claim" | "release" | "join" | "leave" | "watch" | "name";
+	/** With join/leave: the split and the unit, so a resumed transcript still says which. */
+	team?: string;
+	unit?: string;
+	status?: SessionStatus;
+	delivered?: string[];
+	messageId?: string;
+	messages?: BusMessage[];
+	claimed?: string[];
+	conflicts?: ClaimConflict[];
+	released?: string[];
+	notOwned?: string[];
+	/** Whether the inbox watch is on, and whether it raises a turn. */
+	watching?: { armed: boolean; wake: boolean };
+	/** With name: the label the bus settled on, which is what this session is called. */
+	label?: string;
+	error?: string;
+}

package/extensions/subagent/README.md

@@ -210,7 +210,7 @@ for another agent (typically `worker`) to execute, and it works headlessly. It
 returns the plan as text and writes nothing. For **interactive** planning where
 the user reviews and approves a saved plan, use the plan-mode extension instead
 (`enter_plan_mode` / `write_plan` / `exit_plan_mode`), which operates on the
-main session and persists to `.pi/plans`. Plan mode keeps `subagent` available
+main session and persists to the agent directory. Plan mode keeps `subagent` available
 for exploration but forces it read-only, so delegated recon is safe mid-plan.
 
 ## External agents

package/extensions/watch/README.md

@@ -3,7 +3,8 @@
 Tail a file or a command's merged output, match each new line against a regular
 expression, and keep the matching lines. Matches are sanitized and alerted in
 the TUI, reported to the model at the next turn, or — when a watcher opts into
-`wake` — raise one triggered turn immediately.
+`wake` — raise one triggered turn as soon as the agent is idle, including right
+after a running turn settles.
 
 ```
 pi --extension ./extensions/watch    # load just this extension
@@ -29,7 +30,9 @@ How the `watch` call and its result look in the transcript — the call line as
 - Shows a `⊚ N` running-watcher chip and a `! N` unreported-match chip, raises a
   `ctx.ui.notify` alert once per unreported burst, and offers a `/watch` screen.
 - Reports pending matches to the model at the start of the next turn, or wakes a
-  turn for a watcher added with `wake: true`. A wake also leaves the terminal: the
+  turn for a watcher added with `wake: true` as soon as the agent is idle. A wake
+  that arrives mid-turn is raised once that run settles. A wake also leaves the
+  terminal: the
   match is announced on `my-pi-agent/watch-match`, which bytefly's
   [notify](../bytefly/README.md#notifications) capability turns into a desktop
   notification when `notify.enabled` and `notify.matchFound` are on.
@@ -172,8 +175,8 @@ other.
 - Matching is per line; a pattern cannot span a newline.
 - Only a **wake** match raises an OS notification, and only when bytefly's
   `notify.enabled` and `notify.matchFound` are on. A match collected while the
-  agent was busy is reported at the next turn without a notification, and `watch`
-  itself never sends one — it announces the match and bytefly owns delivery.
+  agent was busy notifies once that run settles, and `watch` itself never sends
+  one — it announces the match and bytefly owns delivery.
 
 ## Non-goals
 
@@ -213,7 +216,8 @@ UTF-8 sequence split across a read boundary is never mangled. State is
 session-only by design: a watcher is a live process or file position, not
 transcript state, so it cannot be faithfully rebuilt from a `/tree` fork. Match
 delivery mirrors `job` — reported at the next turn, with `wake` triggering one
-turn — so a match is never dropped when the wake window is busy. Stopping a
+turn as soon as the agent is idle — so a match is never dropped when the wake
+window is busy; a mid-turn wake is raised once that run settles. Stopping a
 command sends SIGTERM to its process group and escalates to SIGKILL after a 2 s
 grace; shutdown waits the same grace, so a command that ignores SIGTERM cannot
 outlive the session.

package/extensions/watch/index.ts

@@ -4,8 +4,9 @@
  * Registers the `watch` tool and `/watch` command. Watchers read a file or a
  * command's merged output, match each new line against a regular expression,
  * and alert the user; matching lines are reported to the model — and shown as a
- * bytefly notice — at the next turn, or wake a turn immediately when the
- * watcher opted into `wake`. Watchers are session-only and stopped on shutdown.
+ * bytefly notice — at the next turn, or wake a turn as soon as the agent is idle
+ * when the watcher opted into `wake`, including right after a running turn
+ * settles. Watchers are session-only and stopped on shutdown.
  *
  * Load with:  pi --extension ./extensions/watch
  */
@@ -14,7 +15,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
 import { WATCH_MATCH_CHANNEL, type WatchMatchEvent } from "../../lib/events.ts";
 import { sanitizeLine } from "../../lib/format.ts";
-import { noticeMessage, type NoticeMessage } from "../../lib/notice.ts";
+import { burstText, noticeMessage, type NoticeMessage } from "../../lib/notice.ts";
 import { createPendingReporter, registerPendingChannel } from "../../lib/report.ts";
 import { registerCommands } from "./commands.ts";
 import { clipLabel } from "../../lib/tui/columns.ts";
@@ -32,10 +33,14 @@ const MAX_CONTEXT_MATCHES = 20;
 /** Build the model-facing text for the pending-match notice. */
 export function buildWatchContext(matches: PendingMatch[]): string {
 	const shown = matches.slice(0, MAX_CONTEXT_MATCHES);
-	const lines = shown.map(formatPendingMatch);
 	const more = matches.length - shown.length;
-	const suffix = more > 0 ? `\n… ${more} more match${more === 1 ? "" : "es"}` : "";
-	return `${WATCH_CONTEXT_MARKER}\n${matches.length} watched line${matches.length === 1 ? "" : "s"} matched:\n${lines.join("\n")}${suffix}\nRead more with \`watch matches <id>\`.`;
+	return burstText({
+		marker: WATCH_CONTEXT_MARKER,
+		headline: `${matches.length} watched line${matches.length === 1 ? "" : "s"} matched`,
+		lines: shown.map((match) => formatPendingMatch(match)),
+		...(more > 0 ? { more: `… ${more} more match${more === 1 ? "" : "es"}` } : {}),
+		hint: "Read more with `watch matches <id>`.",
+	});
 }
 
 /** The shared notice for pending matches: model text plus renderer details. */
@@ -64,15 +69,16 @@ export default function watch(pi: ExtensionAPI, deps: WatchDeps = {}): void {
 	if (!isExtensionEnabled("watch")) return;
 	const runtime = deps.runtime ?? createWatchRuntime();
 
-	// Opt-in wake: a `wake` watcher matched while the agent is idle. The reporter
-	// reports *all* pending matches, not just the waking one, so a non-wake match
-	// is not silently dropped.
+	// Opt-in wake: a `wake` watcher matched. The reporter reports *all* pending
+	// matches, not just the waking one, so a non-wake match is not silently
+	// dropped, and it retries a burst that arrived mid-turn once the run settles.
 	const reporter = createPendingReporter<PendingMatch>({
 		wake: (notice) => pi.sendMessage(notice, { triggerTurn: true }),
 		pending: () => runtime.pendingMatches(),
 		markReported: (matches) => runtime.markReported(matches),
 		buildNotice: watchNotice,
 		source: "watch",
+		wakeRequested: () => runtime.pendingMatches().some((match) => runtime.get(match.watcherId)?.wake === true),
 		// A wake means the user is away from the terminal, so the alert also leaves
 		// the process. bytefly's notify capability owns delivery; this publishes the
 		// fact and never learns how it is sent. The newest match is the one an alert