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

package/lib/board/page-pointer.ts

@@ -0,0 +1,256 @@
+/**
+ * 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 a *view* token — never the
+ * write token, which stays in the URL the lead's own browser was opened at.
+ *
+ * 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";
+
+/** 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. */
+export const PROBE_MS = 600;
+
+/** The port, the seat, and the credential a viewer may hold. */
+export interface PagePointer {
+	port: number;
+	/** A token that satisfies every read and no write. */
+	viewToken: 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 }>;
+
+/** The URL a viewer opens: the page, with the credential that may only read it. */
+export function viewUrlOf(pointer: PagePointer): string {
+	return `http://127.0.0.1:${pointer.port}/?token=${pointer.viewToken}`;
+}
+
+/**
+ * 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, viewToken: string): Promise<boolean> {
+	const pointer = await readPointer(dir);
+	if (pointer === undefined || pointer.viewToken !== viewToken) 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.viewToken !== viewToken) {
+		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;
+
+/** 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;
+	for (let attempt = 0; attempt < NOTE_ATTEMPTS; attempt++) {
+		// A retry writes a fresh `startedAt`, so a reader can tell it from the first attempt.
+		const candidate = attempt === 0 ? note : { ...note, startedAt: note.startedAt + attempt };
+		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 the page that had it cleared it in this instant: try again
+			// rather than reporting a file that is not there. Only a file that stays, and
+			// cannot be read, is the caller's dead end.
+			if (!(await noteExists(dir))) continue;
+			return { kind: "unreadable" };
+		}
+		if (await probePage(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.viewToken)) 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 page a pointer names is answering.
+ *
+ * A page that answers with anything but a 200 to the snapshot request 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> {
+	try {
+		const response = await fetchLike(`http://127.0.0.1:${pointer.port}/api/board?token=${pointer.viewToken}`, {
+			signal: AbortSignal.timeout(timeoutMs),
+		});
+		return response.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, viewToken, seat, startedAt } = value as Record<string, unknown>;
+	if (typeof port !== "number" || !Number.isInteger(port) || port <= 0 || port > 65_535) return undefined;
+	if (typeof viewToken !== "string" || viewToken === "") 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,
+		viewToken,
+		seat: id === undefined ? { label } : { id, label },
+		startedAt,
+	};
+}

package/lib/board/round-text.ts

@@ -0,0 +1,72 @@
+/**
+ * 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`. */
+export function plural(count: number, noun: string): string {
+	return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+/** `#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,89 @@
+/**
+ * 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 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. */
+export interface RoundGroup {
+	label: string;
+	cards: Card[];
+	/** This owner's finished cards: history, kept so a teammate who is done is not erased. */
+	done: Card[];
+}
+
+/** The lead's rollup of one board. */
+export interface RoundSummary {
+	/** Every owner with at least one unfinished card, ordered by label. */
+	owners: RoundGroup[];
+	/** `todo` cards: nobody has taken them yet. */
+	unassigned: Card[];
+	/** `doing` cards with no plan recorded: work started before it was planned. */
+	unplanned: Card[];
+	/** `blocked` cards, and the note that says why. */
+	blocked: Card[];
+	/** `doing` cards untouched for {@link IDLE_MS}: possibly a dead owner. */
+	idle: Card[];
+	/** Finished cards, oldest first, kept as history. */
+	done: Card[];
+}
+
+/**
+ * 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(cards: readonly Card[], now: number): RoundSummary {
+	const groups = new Map<string, RoundGroup>();
+	const unassigned: Card[] = [];
+	const unplanned: Card[] = [];
+	const blocked: Card[] = [];
+	const idle: Card[] = [];
+	const done: Card[] = [];
+
+	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,
+	};
+}