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

package/lib/board/page-pointer.ts

@@ -0,0 +1,310 @@
+/**
+ * The page pointer: how a second session finds the page a repository already serves.
+ *
+ * A page is one loopback server owned by one session's process, so nothing about it is
+ * discoverable without a note left where the repository's state already lives. That note
+ * is `<board>/page.json`: the port, the seat serving it, and the token the page reads by.
+ * The page cannot change a card, so the note carries nothing a reader could misuse.
+ *
+ * Two rules make the file safe to trust:
+ *
+ * - **Created exclusively**, by hard-linking a temp file onto the name, so two sessions
+ *   starting at the same instant cannot both believe they are the page: the loser reads
+ *   the winner's pointer and attaches.
+ * - **Believed only while it answers.** A crash leaves the file behind, and the file says
+ *   nothing about whether the process is alive, so a caller probes the page before it
+ *   attaches or takes the seat over. `probePage` is that question, with the network as a
+ *   seam so a test drives it.
+ *
+ * Pure I/O, no state: one call answers one caller, and the caller owns the path it hands in.
+ */
+
+import { access, link, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { hasErrorCode } from "../errors.ts";
+import { abortableSleep } from "../timer.ts";
+
+/** The file, beside the board's `cards/` directory. */
+export const PAGE_FILE = "page.json";
+
+/**
+ * How long a probe waits before it calls the page gone.
+ *
+ * Long enough for a page that is busy answering a browser: the probe shares the event
+ * loop with the snapshot route, and a page declared dead while it is merely slow is taken
+ * over — two servers, one note.
+ */
+export const PROBE_MS = 1_500;
+
+/** The port, the seat, and the credential the page reads by. */
+export interface PagePointer {
+	port: number;
+	/** The page's one token: every read, and nothing else to authorise. */
+	token: string;
+	/** The seat the page writes as. */
+	seat: { id?: string; label: string };
+	/** When the page started, so a reader can tell a fresh note from a stale one. */
+	startedAt: number;
+}
+
+/** The fetch a probe uses: the global one in production, a stub in a test. */
+export type ProbeFetch = (url: string, init: { signal: AbortSignal }) => Promise<{ ok: boolean; status?: number }>;
+
+/** The URL for this page, wherever it is opened from. */
+export function urlOf(pointer: PagePointer): string {
+	return `http://127.0.0.1:${pointer.port}/?token=${pointer.token}`;
+}
+
+/**
+ * Whether a note is there at all, readable or not.
+ *
+ * `readPointer` answers nothing for two very different states — no page has ever written a
+ * note here, and a note this build cannot read — and a caller that has just failed to
+ * create one has to tell them apart: the first is a race with a page that cleared its note
+ * and is worth another attempt, the second is a file only its owner can explain.
+ */
+export async function noteExists(dir: string): Promise<boolean> {
+	try {
+		await access(join(dir, PAGE_FILE));
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/** The pointer written for one board directory, or nothing when there is none to trust. */
+export async function readPointer(dir: string): Promise<PagePointer | undefined> {
+	return readPointerAt(join(dir, PAGE_FILE));
+}
+
+/** The pointer a file holds, by path: the same read, for a note that has been moved aside. */
+async function readPointerAt(path: string): Promise<PagePointer | undefined> {
+	let text: string;
+	try {
+		text = await readFile(path, "utf-8");
+	} catch {
+		return undefined;
+	}
+	try {
+		return asPointer(JSON.parse(text));
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Write a pointer for a page this caller has just started.
+ *
+ * Returns whether it became the file: `false` means another session got there first, and
+ * the caller should read that one and attach rather than serve a second page.
+ */
+export async function createPointer(dir: string, pointer: PagePointer): Promise<boolean> {
+	const target = join(dir, PAGE_FILE);
+	const temp = `${target}.tmp-${process.pid}-${Math.random().toString(16).slice(2, 10)}`;
+	try {
+		await writeFile(temp, `${JSON.stringify(pointer, null, "\t")}\n`, { mode: 0o600 });
+		try {
+			await link(temp, target);
+			return true;
+		} catch (error) {
+			// The name is taken: another session is serving this repository, and this one
+			// becomes a viewer of it. Any other failure is the caller's to hear about.
+			if (hasErrorCode(error, "EEXIST")) return false;
+			throw error;
+		}
+	} finally {
+		await rm(temp, { force: true });
+	}
+}
+
+/**
+ * Remove the pointer for a page that has stopped.
+ *
+ * Only a caller that has proved the note is not a live page may clear it: the page that
+ * wrote it, on its own way out, or a session that just found it answering nobody. The
+ * token is what decides — a restart of the same seat has the same seat and a new token,
+ * so a note that no longer names a live page never takes the live one's place away.
+ * Returns whether the file was the one named.
+ *
+ * The note is moved aside before it is removed, and the token is checked again on what was
+ * moved. A read followed by an unlink is two instants, and a session that judged the old
+ * note dead acts on the first one: if it removed the name, it could delete the note a
+ * faster session had written in between, and both would serve a page, only one of them
+ * findable. The move is atomic, so the file this call holds is the file that was there;
+ * a note that is not the one proved dead goes back where it came from.
+ */
+export async function clearPointer(dir: string, token: string): Promise<boolean> {
+	const pointer = await readPointer(dir);
+	if (pointer === undefined || pointer.token !== token) return false;
+	const target = join(dir, PAGE_FILE);
+	const held = `${target}.gone-${process.pid}-${Math.random().toString(16).slice(2, 10)}`;
+	try {
+		await rename(target, held);
+	} catch {
+		// It left while this call was looking, which is somebody else having cleared it.
+		return false;
+	}
+	const moved = await readPointerAt(held);
+	if (moved === undefined || moved.token !== token) {
+		await putBack(held, target);
+		return false;
+	}
+	await rm(held, { force: true });
+	return true;
+}
+
+/**
+ * Put a note this call moved aside but did not earn the right to remove back in place.
+ *
+ * A newer note may have taken the name in the same instant; that one stays, and this one
+ * was already superseded by it.
+ */
+async function putBack(held: string, target: string): Promise<void> {
+	try {
+		await link(held, target);
+	} catch {
+		// The name is taken again: whatever holds it now is newer than what this call moved.
+	}
+	await rm(held, { force: true });
+}
+
+/** How many times a caller tries to own the note before it gives up for good. */
+export const NOTE_ATTEMPTS = 3;
+
+/** How long a page that has written its note but does not answer yet is given, in steps. */
+export const YOUNG_POLLS = 8;
+const YOUNG_POLL_MS = 75;
+
+/** How many times a caller looks again at a name that is momentarily free. */
+const EMPTY_LOOKS = 20;
+const EMPTY_LOOK_MS = 25;
+
+/** What one `/board` found where the note should be. */
+export type PointerOutcome =
+	| { kind: "written"; took?: PagePointer }
+	| { kind: "attached"; pointer: PagePointer }
+	/** The name is taken by a file this build cannot read: nothing to attach to, nothing to take. */
+	| { kind: "unreadable" }
+	/** Every attempt lost, and the note there still answers nobody. */
+	| { kind: "stale"; pointer: PagePointer }
+	/** Every attempt lost to a page that came and went, so there is no note to name. */
+	| { kind: "busy" };
+
+/**
+ * Become the repository's page, or find the one that already is.
+ *
+ * The note is written exclusively, so the loser of a simultaneous start attaches to the
+ * winner rather than serving a second page nobody can find. A note that answers nobody is
+ * a page that died between its note and its server — and while it sits there no later
+ * `/board` can serve either, so it is taken over once it has been proved dead.
+ *
+ * More than one attempt, because two sessions reach this point in the same instant and
+ * the loser of a *takeover* has to end up a viewer of the page that won: it re-reads and
+ * probes again rather than reporting a page it never asked about. A failure here names
+ * the file, because "another session is serving" is a thing this function can see and
+ * therefore must not guess.
+ */
+export async function settlePointer(dir: string, note: PagePointer, probe?: ProbeFetch): Promise<PointerOutcome> {
+	let took: PagePointer | undefined;
+	let attempts = 0;
+	let looks = 0;
+	while (attempts < NOTE_ATTEMPTS) {
+		// A retry writes a fresh `startedAt`, so a reader can tell it from the first attempt.
+		const candidate = attempts === 0 ? note : { ...note, startedAt: note.startedAt + attempts };
+		if (await createPointer(dir, candidate))
+			return took === undefined ? { kind: "written" } : { kind: "written", took };
+		const winner = await readPointer(dir);
+		if (winner === undefined) {
+			// No note at all means a page is between clearing its note and writing the next one.
+			// That is a few microseconds of somebody else's work, not a takeover attempt of this
+			// caller's, so the name is chased without spending one; a file that stays, and cannot
+			// be read, is the caller's dead end.
+			if (await noteExists(dir)) return { kind: "unreadable" };
+			if (looks >= EMPTY_LOOKS) return { kind: "busy" };
+			looks += 1;
+			await abortableSleep(EMPTY_LOOK_MS);
+			continue;
+		}
+		attempts += 1;
+		if (await answerOrWait(winner, probe)) return { kind: "attached", pointer: winner };
+		// Only that exact note: a note a newer page wrote is not this caller's to take. A
+		// refused clear means somebody else got there first, so the next attempt re-reads.
+		if (await clearPointer(dir, winner.token)) took = winner;
+	}
+	const last = await readPointer(dir);
+	if (last !== undefined) return { kind: "stale", pointer: last };
+	return (await noteExists(dir)) ? { kind: "unreadable" } : { kind: "busy" };
+}
+
+/**
+ * Whether the winner answers, giving a page that is still coming up its full probe window.
+ *
+ * A note is written before its server can accept a connection, so the loser of a simultaneous
+ * start reads a note whose page is a few milliseconds behind it. One refused connection is
+ * therefore not proof of death: stealing that note serves a second page, and calling it stale
+ * reports a page that exists as one that did not start. The poll is bounded at the same
+ * 600 ms a probe itself may spend, so a note whose page is really gone is still taken over.
+ */
+async function answerOrWait(pointer: PagePointer, probe?: ProbeFetch): Promise<boolean> {
+	for (let attempt = 0; attempt < YOUNG_POLLS; attempt++) {
+		if (await probePage(pointer, probe)) return true;
+		await abortableSleep(YOUNG_POLL_MS);
+	}
+	return false;
+}
+
+/**
+ * Whether the page a pointer names is answering.
+ *
+ * The question goes to the cheap liveness route, not to the snapshot: a probe runs while
+ * another session may be serving a browser, and asking for the snapshot would make a busy
+ * page look like a dead one — the very race that costs a takeover and leaves two servers.
+ * A page from a build without that route answers 404 there and is asked for its snapshot
+ * once, so an upgrade mid-session attaches instead of stealing the seat.
+ *
+ * A page that answers with anything but a 200 is not one to attach to: a port reused by
+ * another program, a server shutting down, and a page that refuses the token all read the
+ * same, and all mean "serve your own".
+ */
+export async function probePage(
+	pointer: PagePointer,
+	fetchLike: ProbeFetch = (url, init) => fetch(url, init),
+	timeoutMs: number = PROBE_MS,
+): Promise<boolean> {
+	const ask = (path: string): Promise<{ ok: boolean; status?: number }> =>
+		fetchLike(`http://127.0.0.1:${pointer.port}${path}?token=${pointer.token}`, {
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+	try {
+		const ping = await ask("/api/ping");
+		if (ping.ok) return true;
+		// A page this build started always answers the ping; a 404 is one started by an
+		// older build, whose only liveness answer is its snapshot.
+		if (ping.status !== 404) return false;
+		return (await ask("/api/board")).ok;
+	} catch {
+		return false;
+	}
+}
+
+/** A parsed file as a pointer, or undefined when it is not one this build can trust. */
+function asPointer(value: unknown): PagePointer | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	const { port, seat, startedAt } = value as Record<string, unknown>;
+	// A note written by the build with two tokens carries `viewToken`; it is this page's
+	// only credential now, so an upgrade reads it instead of refusing to serve its own note.
+	const { token = (value as { viewToken?: unknown }).viewToken } = value as { token?: unknown };
+	if (typeof port !== "number" || !Number.isInteger(port) || port <= 0 || port > 65_535) return undefined;
+	if (typeof token !== "string" || token === "") return undefined;
+	if (typeof startedAt !== "number") return undefined;
+	if (typeof seat !== "object" || seat === null) return undefined;
+	const { id, label } = seat as Record<string, unknown>;
+	if (typeof label !== "string" || label === "") return undefined;
+	if (id !== undefined && typeof id !== "string") return undefined;
+	return {
+		port,
+		token,
+		seat: id === undefined ? { label } : { id, label },
+		startedAt,
+	};
+}

package/lib/board/round-text.ts

@@ -0,0 +1,81 @@
+/**
+ * The lead's rollup, as the lines a reader gets.
+ *
+ * Two surfaces want the same sentences: `board`'s tool returns them, because the model's
+ * next decision is taken from the counts and the ids, and `team`'s `/team` prints them,
+ * because a lead in a terminal should not have to open a browser to see what needs a
+ * decision. One text, so the two cannot describe one board differently.
+ *
+ * It reads the cards and the round and nothing else — no clock, no roster, no store — so
+ * `plural` and the group lines are pure and a caller supplies what it already read.
+ */
+
+import { type Card, cardRef } from "./card.ts";
+import type { RoundSummary } from "./round.ts";
+
+/**
+ * The rollup: a headline of what a lead decides on, then one line per group.
+ *
+ * Groups name their cards by id and state, because the ids are what the next action
+ * takes, and an empty group is left out rather than drawn empty.
+ */
+export function formatRound(cards: readonly Card[], round: RoundSummary): string {
+	const owners = round.owners.length;
+	const headline = [
+		plural(owners, "owner"),
+		plural(cards.length, "feature"),
+		`${round.unassigned.length} unassigned`,
+		`${round.unplanned.length} unplanned`,
+		`${round.blocked.length} blocked`,
+		`${round.idle.length} idle`,
+		`${round.done.length} done`,
+	].join(" · ");
+	const lines = [headline];
+	for (const group of round.owners) {
+		// An owner who finished everything is still listed, with what it finished: the
+		// count says which kind of work is left, and an empty list is a legitimate answer.
+		const counts =
+			group.done.length > 0 ? `${group.cards.length} live, ${group.done.length} done` : `${group.cards.length}`;
+		const listed = group.cards.map((card) => brief(card)).join(", ");
+		lines.push(listed === "" ? `${group.label} (${counts})` : `${group.label} (${counts}): ${listed}`);
+	}
+	lines.push(...group("unassigned", round.unassigned));
+	lines.push(...group("unplanned", round.unplanned));
+	lines.push(...group("blocked", round.blocked, true));
+	lines.push(...group("idle", round.idle));
+	lines.push(...group("done", round.done));
+	return lines.join("\n");
+}
+
+/**
+ * `1 owner`, `2 owners`.
+ *
+ * Written as concatenation rather than a template, because the page's bundle carries
+ * this function's *source*: a backtick or an interpolation in it would end the string it
+ * is spliced into. `round-text.test.ts` pins both, and `PLURAL_JS` is how it crosses.
+ */
+export function plural(count: number, noun: string): string {
+	return count + " " + noun + (count === 1 ? "" : "s");
+}
+
+/** The same body, as the browser receives it: one wording for `1 card`, not two. */
+export const PLURAL_JS = String(plural);
+
+/** `#4 doing planned`, the brief a rollup group needs. */
+function brief(card: Card): string {
+	const planned = card.status === "doing" ? (card.plan === undefined ? " unplanned" : " planned") : "";
+	return `${cardRef(card.id)} ${card.status}${planned}`;
+}
+
+/** One rollup group, or nothing when it is empty. */
+function group(label: string, cards: readonly Card[], withReason = false): string[] {
+	if (cards.length === 0) return [];
+	const items = cards.map((card) => (withReason ? blockedBrief(card) : brief(card)));
+	return [`${label} (${cards.length}): ${items.join(", ")}`];
+}
+
+/** A blocked card names the note that explains it, if there is one. */
+function blockedBrief(card: Card): string {
+	const last = card.notes.at(-1);
+	return `${brief(card)}${last === undefined ? "" : ` — ${last.text}`}`;
+}

package/lib/board/round.ts

@@ -0,0 +1,94 @@
+/**
+ * The rollup: the lead's view of a board, computed from the cards alone.
+ *
+ * This is what `board list --round` returns and what the page's Team tab draws, so
+ * the two cannot disagree about who holds what. It deliberately reads nothing but
+ * the cards: a session's liveness is `session status`'s answer, and the board has
+ * to work when `session-bus` is not loaded. `idle` therefore means what a card can
+ * know — nobody has touched it in half an hour — not that its owner's process is
+ * gone.
+ *
+ * The groups overlap on purpose. A `doing` card with no plan and no touch for half
+ * an hour is both `unplanned` and `idle`, and hiding it in one of the two would lose
+ * half the reason a lead should look at it.
+ *
+ * Pure: no I/O and no clock of its own.
+ */
+
+import type { Card } from "./card.ts";
+
+/** How long a `doing` card may go untouched before the rollup calls it idle. */
+export const IDLE_MS = 30 * 60 * 1_000;
+
+/**
+ * One owner, the live cards it holds, and the ones it finished.
+ *
+ * `T` is what the caller handed in: the rollup never builds a card, so a snapshot whose
+ * cards carry derived facts hands them back on the same terms it received them.
+ */
+export interface RoundGroup<T extends Card = Card> {
+	label: string;
+	cards: T[];
+	/** This owner's finished cards: history, kept so a teammate who is done is not erased. */
+	done: T[];
+}
+
+/** The lead's rollup of one board. */
+export interface RoundSummary<T extends Card = Card> {
+	/** Every owner with at least one unfinished card, ordered by label. */
+	owners: RoundGroup<T>[];
+	/** `todo` cards: nobody has taken them yet. */
+	unassigned: T[];
+	/** `doing` cards with no plan recorded: work started before it was planned. */
+	unplanned: T[];
+	/** `blocked` cards, and the note that says why. */
+	blocked: T[];
+	/** `doing` cards untouched for {@link IDLE_MS}: possibly a dead owner. */
+	idle: T[];
+	/** Finished cards, oldest first, kept as history. */
+	done: T[];
+}
+
+/**
+ * The rollup of `cards` at `now`.
+ *
+ * `cards` holds the unfinished cards only: a finished one is also in `done` and
+ * counting it twice would make the tallies disagree with the lanes. A finished card
+ * still names its owner, in the group's `done`, because an owner whose last card is
+ * done has not left the board — dropping the group erased a teammate the round had
+ * just finished. Two owners
+ * whose labels differ only by case are one owner — a name is case-insensitive when
+ * it is a send target, so it is here too — and the first spelling seen is kept.
+ */
+export function buildRound<T extends Card = Card>(cards: readonly T[], now: number): RoundSummary<T> {
+	const groups = new Map<string, RoundGroup<T>>();
+	const unassigned: T[] = [];
+	const unplanned: T[] = [];
+	const blocked: T[] = [];
+	const idle: T[] = [];
+	const done: T[] = [];
+
+	for (const card of cards) {
+		if (card.status === "todo") unassigned.push(card);
+		if (card.status === "done") done.push(card);
+		if (card.status === "blocked") blocked.push(card);
+		if (card.status === "doing" && card.plan === undefined) unplanned.push(card);
+		if (card.status === "doing" && now - card.updatedAt >= IDLE_MS) idle.push(card);
+
+		if (card.owner === undefined) continue;
+		const key = card.owner.label.toLowerCase();
+		const group = groups.get(key) ?? { label: card.owner.label, cards: [], done: [] };
+		if (card.status === "done") group.done.push(card);
+		else group.cards.push(card);
+		groups.set(key, group);
+	}
+
+	return {
+		owners: [...groups.values()].sort((a, b) => a.label.localeCompare(b.label)),
+		unassigned,
+		unplanned,
+		blocked,
+		idle,
+		done,
+	};
+}