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

package/extensions/board/format.ts

@@ -12,18 +12,85 @@
  */
 
 import { type Card, cardRef, DEFAULT_PRIORITY, dependsOf, priorityOf } from "../../lib/board/card.ts";
-import type { BoardIndex } from "../../lib/board/links.ts";
+import { type BoardIndex, lanesText, openDependentsOf } from "../../lib/board/links.ts";
+import type { Skip } from "../../lib/board/store.ts";
+import { formatAge } from "../../lib/format.ts";
 import { plural } from "../../lib/board/round-text.ts";
 
 /** One card: the headline, then the state a reader needs in order to act on it. */
-export function formatCard(card: Card, board?: BoardIndex): string {
-	return [`${cardRef(card.id)} ${card.status} · ${card.title}`, ...detailLines(card, board)].join("\n");
+export function formatCard(card: Card, board?: BoardIndex, now?: number): string {
+	return [`${cardRef(card.id)} ${card.status} · ${card.title}`, ...detailLines(card, board, now)].join("\n");
 }
 
-/** A board, in lane order. */
-export function formatCards(cards: readonly Card[]): string {
-	if (cards.length === 0) return "The board is empty.";
-	return cards.map((card) => listLine(card)).join("\n");
+/**
+ * What a listing cannot show, and therefore has to say.
+ *
+ * A footnote is the difference between a listing and the board: an omission nobody
+ * accounted for reads as a smaller board — or as history that was deleted.
+ */
+export interface ListingNotes {
+	/** Finished cards the board holds that a lane-less listing left out. */
+	hiddenDone: number;
+	/** Cards set aside in the archive, which no board read opens. */
+	archived: number;
+	/** Card files this build could not read. */
+	skipped: readonly Skip[];
+}
+
+/**
+ * A board's listing: the cards, then the footnotes a reader cannot see.
+ *
+ * One body, because the footnotes belong to the listing: a card file this build cannot
+ * read, the finished cards a plain listing left out, and the cards an `archive` set aside.
+ */
+export function formatBoard(shown: readonly Card[], notes: ListingNotes): string {
+	const lines =
+		shown.length === 0 ? [notes.hiddenDone === 0 ? "The board is empty." : "No open cards."] : shown.map(listLine);
+	// A finished card is history rather than work, so a listing that names no lane leaves
+	// them out; the count is what keeps the omission from reading as a smaller board.
+	if (notes.hiddenDone > 0) {
+		const them = notes.hiddenDone === 1 ? "it" : "them";
+		lines.push(`${plural(notes.hiddenDone, "done card")} hidden; pass status: "done" to read ${them}.`);
+	}
+	for (const note of [archiveNote(notes.archived), formatSkipped(notes.skipped)]) {
+		if (note !== "") lines.push(note);
+	}
+	return lines.join("\n");
+}
+
+/**
+ * The archive's listing: what is set aside, and the files there this build refused.
+ *
+ * The archive is read on request only, so this has no lane footnote of its own — every
+ * card in the pile is finished, and a `done` lane would be a second way to say it.
+ */
+export function formatArchive(shown: readonly Card[], skipped: readonly Skip[]): string {
+	const lines = shown.length === 0 ? ["The archive is empty."] : shown.map(listLine);
+	const unreadable = formatSkipped(skipped);
+	if (unreadable !== "") lines.push(unreadable);
+	return lines.join("\n");
+}
+
+/**
+ * The one sentence a board listing adds so its archive is not mistaken for deleted history.
+ *
+ * Empty when nothing is set aside, so the ordinary board says nothing new.
+ */
+export function archiveNote(count: number): string {
+	if (count === 0) return "";
+	return `${plural(count, "card")} ${count === 1 ? "is" : "are"} set aside in the archive; pass archived: true to read ${count === 1 ? "it" : "them"}.`;
+}
+
+/**
+ * The files the board could not read, or nothing when it read everything.
+ *
+ * A skipped file is not an absent one: a board written by a newer build would
+ * otherwise read as "nobody has planned anything" while the work sits on disk.
+ */
+export function formatSkipped(skipped: readonly Skip[]): string {
+	if (skipped.length === 0) return "";
+	const files = skipped.map((entry) => `${entry.file} (${entry.why})`).join(", ");
+	return `${plural(skipped.length, "file")} this build cannot read: ${files}`;
 }
 
 /** The dropped id, which is the only thing left of the card. */
@@ -31,22 +98,53 @@ export function formatDropped(id: string): string {
 	return `${cardRef(id)} dropped, with its notes.`;
 }
 
+/**
+ * The ids an archive set aside, and how to read them again.
+ *
+ * A move has to name the way back or it reads like a deletion: the card is out of the
+ * board and its notes, plan, and landed commit are still in its file.
+ */
+export function formatArchived(ids: readonly string[]): string {
+	const theirs = ids.length === 1 ? "its" : "their";
+	return `${plural(ids.length, "card")} archived: ${ids.map(cardRef).join(", ")} — out of the board, ${theirs} notes and plan still readable with archived: true.`;
+}
+
 /** A one-line listing: the id, the lane, the title, and who holds it. */
 function listLine(card: Card): string {
 	const holder = card.owner === undefined ? "unassigned" : card.owner.label;
 	const urgency = priorityOf(card) === DEFAULT_PRIORITY ? "" : ` · ${priorityOf(card)}`;
 	const waits = dependsOf(card).length === 0 ? "" : ` · waits on ${dependsOf(card).map(cardRef).join(", ")}`;
-	return `${cardRef(card.id)} ${card.status} · ${card.title} · ${holder}${urgency}${waits}`;
+	// The two lanes that carry a fact of their own say it here: what a block waits on, and
+	// what closed a finished card. Both are one short phrase, so a listing stays one line.
+	const blocked = card.blockedBy === undefined ? "" : ` · blocked: ${card.blockedBy}`;
+	const landed = card.landed === undefined ? "" : ` · landed ${card.landed.commit}`;
+	return `${cardRef(card.id)} ${card.status} · ${card.title} · ${holder}${urgency}${waits}${blocked}${landed}`;
 }
 
 /** The state lines under a card's headline. */
-function detailLines(card: Card, board?: BoardIndex): string[] {
+function detailLines(card: Card, board?: BoardIndex, now?: number): string[] {
 	const lines: string[] = [];
 	if (card.owner !== undefined) lines.push(`  owner: ${card.owner.label}`);
+	// An offer's age is the fact a reader acts on, which is the one place an age belongs in
+	// this text: the value is whether anybody has had time to answer.
+	if (card.offeredAt !== undefined && now !== undefined) {
+		lines.push(`  offered: ${formatAge(now, card.offeredAt)} ago, and nobody took it`);
+	}
+	if (card.blockedBy !== undefined) lines.push(`  blocked: ${card.blockedBy}`);
+	if (card.landed !== undefined) lines.push(`  landed: ${card.landed.commit}`);
 	if (priorityOf(card) !== DEFAULT_PRIORITY) lines.push(`  priority: ${priorityOf(card)}`);
 	if (card.plan !== undefined) lines.push(`  plan: ${card.plan}`);
 	if (card.paths.length > 0) lines.push(`  paths: ${card.paths.join(", ")}`);
 	if (dependsOf(card).length > 0) lines.push(`  waits on: ${waitingOf(card, board)}`);
+	// The mirror question, for the same board: what leaving this card undone holds up. Only
+	// a card with the board in hand can answer it, which is why a bare card read omits it.
+	if (board !== undefined) {
+		const dependents = openDependentsOf(card.id, board);
+		if (dependents.length > 0) {
+			const which = dependents.length === 1 ? "card" : "cards";
+			lines.push(`  waited on by ${dependents.length} ${which}: ${lanesText(dependents)}`);
+		}
+	}
 	if (card.notes.length > 0) {
 		const last = card.notes.at(-1);
 		if (last) lines.push(`  last note (${last.by}): ${last.text}`);

package/extensions/board/index.ts

@@ -15,6 +15,7 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { isExtensionEnabled } from "../../lib/env.ts";
+import { requestMount } from "../../lib/http/index.ts";
 import { registerCommands } from "./commands.ts";
 import { type BoardPage, createBoardPage } from "./page.ts";
 import { type BoardSession, openBoardSession } from "../../lib/board/session.ts";
@@ -30,9 +31,20 @@ export interface BoardDeps {
 export default function board(pi: ExtensionAPI, deps: BoardDeps = {}): void {
 	if (!isExtensionEnabled("board")) return;
 	const session = deps.session ?? openBoardSession(pi);
-	const page = deps.page ?? createBoardPage(session);
+	/** The session the page serves as; the mount lands on this session's one server. */
+	let sessionId = "";
+	const page =
+		deps.page ??
+		createBoardPage(session, {
+			mount: (spec) => requestMount(pi, spec),
+			session: () => sessionId,
+		});
 	registerTools(pi, session);
-	registerCommands(pi, page);
+	registerCommands(pi, session, page);
+
+	pi.on("session_start", async (_event, ctx) => {
+		sessionId = ctx.sessionManager.getSessionId();
+	});
 
 	pi.on("session_shutdown", async () => {
 		await page.closeAll();

package/extensions/board/join.ts

@@ -2,30 +2,51 @@
  * Board's side of the team: the one call that puts this session on it.
  *
  * The user's surface is `/board` and `team`; the session bus is the transport under
- * them. So the board joins on the user's behalf — when the page opens, and again the
- * first time a card is worked — and never asks anybody to run a bus action.
+ * them. So the board joins on the user's behalf — when the page opens, and the first
+ * time this session claims a card — and never asks anybody to run a bus action.
+ *
+ * The label it asks for is the session's own team name (`BoardSession.who`), so the
+ * card, the bus record, and the roster say one word, and joining never renames the
+ * session: the footer keeps the name the user gave it.
  *
  * The seam exists for the same reason `team`'s dispatch does: a board suite drives a
  * recording join instead of a bus, and the shipped implementation is one in-process
  * request through `lib/session-tool.ts` (a command context cannot call a tool).
  */
 
-import type { JoinResult } from "../../lib/session-tool.ts";
-import { DEFAULT_SEAT } from "./seat.ts";
+import { messageOf } from "../../lib/errors.ts";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { JoinResult, TeamJoin } from "../../lib/session-tool.ts";
+import type { TeamStanding } from "../../lib/board/session.ts";
 
 /**
  * The join itself is `lib/session-tool.ts`'s, because `team` asks for it too; this
- * module only holds what is the board's — the label it lands on, and how the outcome
- * reads on a `/board` line.
+ * module only holds what is the board's — when it asks, and how the outcome reads on a
+ * `/board` line.
  */
 export type { TeamJoin } from "../../lib/session-tool.ts";
 
 /**
- * The label `/board` lands on: the page's seat when this session serves it, and
- * nothing when it watches somebody else's page, so a viewer keeps its own name.
+ * Put this session on the team, once: the first card it claims.
+ *
+ * Asked only while the standing does not say this session is on the team, so a card
+ * write costs one request for the session rather than one per card. A failure is
+ * recorded and asked again by the next claim; a bus that is not loaded answers with a
+ * sentence, which is a result and not an exception — and a join that did throw still
+ * must not undo the card that was already written, so it is swallowed here.
  */
-export function joinLabel(served: boolean): string | undefined {
-	return served ? DEFAULT_SEAT : undefined;
+export async function joinOnClaim(
+	standing: TeamStanding,
+	team: TeamJoin,
+	ctx: ExtensionContext,
+	label: string,
+): Promise<void> {
+	if (standing.last()?.ok === true) return;
+	try {
+		standing.record(await team.join(ctx, { label }));
+	} catch (error) {
+		standing.record({ ok: false, error: messageOf(error) });
+	}
 }
 
 /**