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

package/extensions/board/transport/server.ts

@@ -1,54 +1,61 @@
 /**
- * The board page's server: one loopback listener, the snapshot pushed to every
- * attached tab, and the idle grace that closes the page when the last one leaves.
+ * The board page's mount: the prefix it holds on the session's one server, the snapshot
+ * pushed to every attached tab, and the idle grace that gives the prefix back when the
+ * last one leaves.
  *
- * `lib/http` owns the socket — binding, the body cap, the SSE head, and the
- * idempotent close — so this module owns only the board's own decisions: when a
- * frame is pushed (only when a card's revision moved), who receives it, and what
- * stops the ticker.
+ * `lib/http` owns the socket and `serve` owns the session's port, so this module owns only
+ * the board's own decisions: where it answers (`BOARD_BASE`), when a frame is pushed (only
+ * when a card's revision moved), who receives it, and what stops the ticker.
  */
 
+import { BOARD_BASE } from "../../../lib/board/page-pointer.ts";
+import type { BoardView } from "../../../lib/board/view.ts";
 import {
 	type EventSink,
+	type HttpMount,
 	LOOPBACK_HOSTS,
-	type LoopbackServer,
+	type MountSource,
+	type MountSpec,
 	mintToken,
-	serveLoopback,
 	tokenMatches,
 } from "../../../lib/http/index.ts";
+import type { IdleReason } from "../../../lib/http/sink.ts";
 import { defaultInterval, type RepeatTimer } from "../../../lib/timer.ts";
-import type { BoardView } from "../../../lib/board/view.ts";
 import type { PageView } from "../view/page.ts";
-import {
-	type Authority,
-	type BoardRouterContext,
-	handleBoardRequest,
-	type PageResult,
-	type PageWrite,
-} from "./router.ts";
+import { type BoardRouterContext, handleBoardRequest } from "./router.ts";
 
 /** How often the page is offered a frame; a frame is sent only when the signature moved. */
-export const PUSH_MS = 1_000;
+const PUSH_MS = 1_000;
 
 /** Largest request body the page accepts: a card and a note are small. */
-export const MAX_BODY_BYTES = 64 * 1_024;
+const MAX_BODY_BYTES = 64 * 1_024;
 
 /** What the page is built from. The lifecycle (`page.ts`) supplies all of it. */
 export interface BoardServerOptions {
-	/** Ports tried in order: the session's remembered port, then an OS-chosen one. */
-	ports: readonly number[];
-	/** The credential that may change a card; minted here when the caller has none. */
+	/** Where the prefix comes from: the session's server, or a suite's own. */
+	mount: MountSource;
+	/** The Pi session asking, so the prefix lands on this session's socket. */
+	session: string;
+	/** The page's token; minted here when the caller has none, so the note carries one. */
 	token?: string;
-	/** The credential a viewer carries: every read, and no write. */
-	viewToken?: string;
-	page: (view: PageView, authority: Authority) => Promise<string>;
+	page: (view: PageView) => Promise<string>;
 	script: string;
 	view: () => Promise<BoardView>;
-	write: (request: PageWrite) => Promise<PageResult>;
-	/** Called when the last tab has been gone for the grace period. */
-	onIdle?: () => void;
+	/** Called when the page went idle: no tab ever opened, or the last one left. */
+	onIdle?: (reason: IdleReason) => void;
 	/** Grace after the last stream leaves; 0 or absent waits for `close()`. */
 	idleMs?: number;
+	/** Grace for a page no tab ever attached to; absent leaves the mount open. */
+	firstIdleMs?: number;
+	/**
+	 * A read that failed while building a frame.
+	 *
+	 * A snapshot can fail for reasons the page does not control — the board directory removed
+	 * or made unreadable under a running page — and a ticker nobody awaits must not turn that
+	 * into an unhandled rejection in the session. The frame is dropped, the next tick tries
+	 * again, and this is the one place the failure is said. Absent, the page stays quiet.
+	 */
+	onError?: (error: unknown) => void;
 	/** The interval seam, so a test drives the ticker instead of waiting. */
 	interval?: RepeatTimer;
 }
@@ -56,10 +63,8 @@ export interface BoardServerOptions {
 /** A running page. */
 export interface BoardServer {
 	port: number;
-	/** The URL the lead opens: the page, with the credential that may change it. */
+	/** The URL for this page: one address, because there is one thing a page may do. */
 	url: string;
-	/** The URL a teammate opens: the same page, read-only. */
-	viewUrl: string;
 	/** How many tabs are attached, which is what `/board status` reports. */
 	watchers: () => number;
 	/** The signature of the last frame pushed, so a caller can tell it is live. */
@@ -67,26 +72,23 @@ export interface BoardServer {
 	close: () => Promise<void>;
 }
 
-export async function createBoardServer(options: BoardServerOptions): Promise<BoardServer> {
+/** The page, or the reason the session's server has no prefix for it. */
+export type BoardServerResult = { kind: "served"; server: BoardServer } | { kind: "refused"; reason: string };
+
+export async function createBoardServer(options: BoardServerOptions): Promise<BoardServerResult> {
 	const token = options.token ?? mintToken();
-	const viewToken = options.viewToken ?? mintToken();
 	const clients = new Set<EventSink>();
 	const interval = options.interval ?? defaultInterval;
+	/** A frame that could not be built is not sent; the next tick tries again. */
+	const report = (error: unknown): void => options.onError?.(error);
 	let pushed = "";
 
 	const ctx: BoardRouterContext = {
-		// Two credentials, one page: the lead's may change a card, a teammate's may only
-		// read it. Which of the two a request carries is the whole authorisation story.
-		authority: (given) => {
-			const value = given ?? "";
-			if (tokenMatches(token, value)) return "write";
-			return tokenMatches(viewToken, value) ? "view" : undefined;
-		},
+		read: (given) => tokenMatches(token, given ?? ""),
 		hosts: () => LOOPBACK_HOSTS,
 		page: options.page,
 		script: options.script,
 		view: options.view,
-		write: options.write,
 	};
 
 	const push = async (): Promise<void> => {
@@ -100,14 +102,25 @@ export async function createBoardServer(options: BoardServerOptions): Promise<Bo
 		for (const sink of clients) sink.write(frame);
 	};
 
-	const server: LoopbackServer = await serveLoopback({
-		ports: options.ports,
+	/** The prefix this page asks for: the session's server holds it, not this module. */
+	const spec: Omit<MountSpec, "handler"> = {
+		session: options.session,
+		prefix: BOARD_BASE,
 		maxBodyBytes: MAX_BODY_BYTES,
 		...(options.idleMs === undefined || options.onIdle === undefined
 			? {}
-			: { idle: { ms: options.idleMs, onIdle: options.onIdle } }),
+			: {
+					idle: {
+						ms: options.idleMs,
+						...(options.firstIdleMs === undefined ? {} : { firstMs: options.firstIdleMs }),
+						onIdle: options.onIdle,
+					},
+				}),
+	};
+	const outcome = await options.mount({
+		...spec,
 		async handler(request) {
-			const result = await handleBoardRequest(ctx, request.method, request.url, request.headers, request.body);
+			const result = await handleBoardRequest(ctx, request.method, request.url, request.headers);
 			if (!result.stream) return { result };
 			return {
 				result,
@@ -115,10 +128,13 @@ export async function createBoardServer(options: BoardServerOptions): Promise<Bo
 					clients.add(sink);
 					// A tab that just attached gets the current frame without waiting for a
 					// card to change — otherwise a quiet board looks like a dead page.
-					void options.view().then((view) => {
-						pushed = view.sig;
-						sink.write(`data: ${JSON.stringify(view)}\n\n`);
-					});
+					void options
+						.view()
+						.then((view) => {
+							pushed = view.sig;
+							sink.write(`data: ${JSON.stringify(view)}\n\n`);
+						})
+						.catch(report);
 					return () => {
 						clients.delete(sink);
 					};
@@ -126,8 +142,10 @@ export async function createBoardServer(options: BoardServerOptions): Promise<Bo
 			};
 		},
 	});
+	if (outcome.kind === "refused") return { kind: "refused", reason: outcome.reason };
+	const mount: HttpMount = outcome.mount;
 
-	const stopTicker = interval(PUSH_MS, () => void push());
+	const stopTicker = interval(PUSH_MS, () => void push().catch(report));
 	let closed = false;
 	const close = async (): Promise<void> => {
 		if (closed) return;
@@ -135,15 +153,17 @@ export async function createBoardServer(options: BoardServerOptions): Promise<Bo
 		stopTicker();
 		for (const sink of clients) sink.end();
 		clients.clear();
-		await server.close();
+		await mount.release();
 	};
 
 	return {
-		port: server.port,
-		url: `http://127.0.0.1:${server.port}/?token=${token}`,
-		viewUrl: `http://127.0.0.1:${server.port}/?token=${viewToken}`,
-		watchers: () => clients.size,
-		pushed: () => pushed,
-		close,
+		kind: "served",
+		server: {
+			port: mount.port,
+			url: `${mount.origin}${mount.base}/?token=${token}`,
+			watchers: () => clients.size,
+			pushed: () => pushed,
+			close,
+		},
 	};
 }

package/extensions/board/types.ts

@@ -25,12 +25,65 @@ export const BOARD_ACTIONS = [
 	"note",
 	"plan",
 	"edit",
+	"archive",
 	"drop",
 ] as const;
 
 /** One action. */
 export type BoardAction = (typeof BOARD_ACTIONS)[number];
 
+/**
+ * What each verb does, in one sentence.
+ *
+ * The tool description is built from this table and the parameter's `action`
+ * description points at that sentence, so the verbs are stated once. A new action is
+ * a row here and an entry in {@link BOARD_ACTIONS}; `test` holds the two together.
+ */
+export const BOARD_ACTION_DOCS: Record<BoardAction, string> = {
+	list:
+		"shows the board — `status` filters one lane, `mine` only what this session holds, " +
+		"`query` matches a title, a holder, a path hint, the plan, or a note's text, `card` reads that one card " +
+		"instead of the board, and `round` adds the lead's rollup of owners, unassigned, unplanned, blocked, and " +
+		"idle, which always covers the whole board — and a listing that names no lane leaves out the `done` cards, " +
+		"saying how many it left out",
+	add: "creates a `todo` card",
+	claim: "takes one for this session",
+	release: "gives it back",
+	reclaim: "takes it from whoever holds it",
+	move: "changes lane",
+	note: "appends to its history",
+	plan: "records the plan file being executed",
+	edit: "fixes what the card says — title, path hints, priority, and what it waits for",
+	archive:
+		"sets a finished card aside, out of the board and still readable, or every finished card when no `card` is named",
+	drop: "deletes a `todo`, a `done`, or one you hold",
+};
+
+/**
+ * The fields each action acts on: the behaviour, where {@link BOARD_ACTION_DOCS} is prose.
+ *
+ * The parameters are one flat object, so a field is published to every action at once;
+ * that is only harmless while each action reads its own. A call carrying a field its
+ * action never reads is refused against this table, because the alternative is what
+ * `add` did with `dependsOn`: accepted, ignored, and reported as recorded.
+ *
+ * `test` holds the other direction — every parameter but `action` is claimed here — so
+ * a new field cannot be published without an action that acts on it.
+ */
+export const ACTION_FIELDS: Record<BoardAction, readonly string[]> = {
+	list: ["card", "status", "mine", "query", "round", "archived"],
+	add: ["title", "paths", "priority", "note"],
+	claim: ["card"],
+	release: ["card"],
+	reclaim: ["card"],
+	move: ["card", "status", "blockedBy"],
+	note: ["card", "text"],
+	plan: ["card", "path"],
+	edit: ["card", "title", "paths", "priority", "dependsOn"],
+	archive: ["card"],
+	drop: ["card"],
+};
+
 /** A result the transcript renders and the page's routes mirror. */
 export interface BoardDetails {
 	action: BoardAction;
@@ -44,6 +97,10 @@ export interface BoardDetails {
 	round?: RoundSummary;
 	/** The id a `drop` removed. */
 	dropped?: string;
+	/** The ids an `archive` set aside, in the order it moved them. */
+	archived?: string[];
+	/** Cards an `archive` sweep could not set aside, and why: a move that changed underneath it. */
+	failed?: Array<{ card: string; error: string }>;
 	/** A refusal's reason, which the renderer draws instead of the details. */
 	error?: string;
 }

package/extensions/board/view/client.ts

@@ -1,35 +1,46 @@
 /**
- * The client bundle: the five modules that paint, round up, write, bind keys, and
- * follow the frame stream, plus the kit's own theme toggle and one `dialogScript`
- * per modal, and the one entry point that starts them.
+ * The client bundle: the modules that paint, round up, open a card, bind keys, and
+ * follow the frame stream, plus the kit's own theme toggle and the two dialog scripts,
+ * and the one entry point that starts them.
  *
  * Served as one string, because a page that opens six requests before it can paint
  * is a page that looks broken for a moment. Nothing here is typed — no compiler sees
  * a template string — so the split is by job and the class-contract test reads the
- * result: `render.ts` paints, `team.ts` draws the round, `actions.ts` posts and owns
- * the two dialogs, `keys.ts` binds, and `live.ts` owns the tabs and the stream.
+ * result: `render.ts` paints, `team.ts` draws the round, `dialog.ts` opens one card,
+ * `keys.ts` binds, and `live.ts` owns the tabs and the stream.
  *
  * Load order is a dependency: `team` takes helpers from `render`, and `live` starts
  * last, after every `board.*` handler it wires exists.
  */
 
-import { THEME_TOGGLE_JS, dialogScript, keysDialogScript } from "../../../lib/web/index.ts";
-import { BOARD_ACTIONS_JS } from "./actions.ts";
+import { MATCHES_QUERY_JS } from "../../../lib/board/card.ts";
+import { CLIENT_BASE_JS, CLIENT_RUNTIME_JS } from "../../../lib/web/index.ts";
+import { PLURAL_JS } from "../../../lib/board/round-text.ts";
+import { FORMAT_AGE_JS } from "../../../lib/format.ts";
+import { namesScript, TAB_TITLE_JS, THEME_TOGGLE_JS, dialogScript, keysDialogScript } from "../../../lib/web/index.ts";
+import { BOARD_CLASS } from "./names.ts";
+import { BOARD_DIALOG_JS } from "./dialog.ts";
 import { BOARD_KEYS_JS } from "./keys.ts";
 import { BOARD_LIVE_JS } from "./live.ts";
-import { BOARD_RENDER_JS } from "./render.ts";
+import { renderJs } from "./render.ts";
 import { BOARD_TEAM_JS } from "./team.ts";
 
-/** The whole client, in load order: paint, round, write, keys, wiring, then start. */
-export const BOARD_CLIENT_JS = `${BOARD_RENDER_JS}
+/**
+ * The whole client, in load order: paint, round, the card dialog, keys, wiring, start.
+ *
+ * Four rules cross the boundary as source — the count's wording, the tab title's
+ * shape, what a `query` matches, and how an age reads: the browser has no import graph,
+ * and a second copy of any of them is exactly what this bundle is not allowed to hold.
+ */
+export const BOARD_CLIENT_JS = `${CLIENT_BASE_JS}
+${namesScript(BOARD_CLASS)}
+${renderJs({ plural: PLURAL_JS, tabTitle: TAB_TITLE_JS, matches: MATCHES_QUERY_JS, age: FORMAT_AGE_JS, runtime: CLIENT_RUNTIME_JS })}
 ${BOARD_TEAM_JS}
-${BOARD_ACTIONS_JS}
+${BOARD_DIALOG_JS}
 ${BOARD_KEYS_JS}
 ${BOARD_LIVE_JS}
 ${THEME_TOGGLE_JS}
-${dialogScript({ dialogId: "board-new-dialog", globalName: "bfNew" })}
 ${dialogScript({ dialogId: "board-card-dialog", closeId: "card-dialog-close", globalName: "bfCard" })}
-${dialogScript({ dialogId: "board-confirm", globalName: "bfConfirm" })}
 ${keysDialogScript("keys-open")}
 (function () {
   "use strict";

package/extensions/board/view/dialog.ts

@@ -0,0 +1,43 @@
+/**
+ * The card dialog: one card, whole, as a read view.
+ *
+ * Opening, closing, and forgetting which card is open is the whole of it. The page
+ * cannot change a card, so this module has no request, no confirmation, no banner and
+ * no footer actions — the dialogs it used to fill are gone from the document, and the
+ * only way a card changes is a tool.
+ *
+ * The one thing it must not do is leave a stale panel behind: a dialog the kit closed —
+ * `Esc`, a backdrop click, its own close button — forgets `openId`, so the next frame
+ * stops filling something nobody can see.
+ */
+
+export const BOARD_DIALOG_JS = String.raw`(function () {
+  "use strict";
+  var board = window.bfBoard || (window.bfBoard = {});
+
+  /** Fill and open the card dialog. */
+  board.openCard = function (id) {
+    var view = board.view;
+    if (!view) return;
+    var card = board.findCard(view, id);
+    if (!card || !window.bfCard) return;
+    board.openId = id;
+    board.fillDialog(card, view);
+    window.bfCard.open();
+  };
+
+  board.closeCard = function () {
+    if (window.bfCard) window.bfCard.close();
+  };
+
+  board.dialogOpen = function () {
+    return window.bfCard ? window.bfCard.isOpen() : false;
+  };
+
+  var cardDialog = document.getElementById("board-card-dialog");
+  if (cardDialog) {
+    new MutationObserver(function () {
+      if (cardDialog.hidden) board.openId = undefined;
+    }).observe(cardDialog, { attributes: true, attributeFilter: ["hidden"] });
+  }
+})();`;

package/extensions/board/view/keys.ts

@@ -7,16 +7,15 @@
  * module exists to prevent, since no type checker sees the bundle.
  *
  * The vocabulary is the TUI's where it means the same thing (`j`/`k`, `?`, `Esc`);
- * `n`, `/` and `t` are this page's own.
+ * `/` and `t` are this page's own. There is no key that changes a card: the page reads.
  */
 
 import type { KeyHint } from "../../../lib/web/index.ts";
 
 /** One binding: the key or keys, and what pressing it does. */
 export const BOARD_KEYS: readonly KeyHint[] = [
-	{ keys: "n", label: "New card — open the dialog and focus the title field" },
 	{ keys: "/", label: "Filter the cards" },
-	{ keys: ["j", "k"], label: "Next or previous card" },
+	{ keys: ["j", "k"], label: "Next or previous card, or the next card in an open dialog" },
 	{ keys: "Enter", label: "Open the focused card" },
 	{ keys: "t", label: "Switch Board and Team" },
 	{ keys: "Esc", label: "Close a dialog, or clear the filter" },
@@ -35,23 +34,35 @@ export const BOARD_KEYS_JS = String.raw`(function () {
   "use strict";
   var board = window.bfBoard || (window.bfBoard = {});
 
-  /** Whether the event landed in a field, where every key is text. */
-  function typing(target) {
-    if (!target || !target.tagName) return false;
-    var tag = target.tagName.toLowerCase();
-    return tag === "input" || tag === "textarea" || tag === "select" || target.isContentEditable === true;
-  }
+  /** The render bundle's runtime: one typing test for the whole page. */
+  var typing = board.typing;
 
   /** The card nodes in reading order, so j/k walk the board as it is drawn. */
   function cards() {
-    var seen = [];
-    var nodes = document.querySelectorAll(".board-card");
-    for (var i = 0; i < nodes.length; i++) if (!nodes[i].hidden) seen.push(nodes[i]);
-    return seen;
+    return board.drawnCards();
+  }
+
+  /** Move the open dialog to the next or previous card; false when no dialog is open. */
+  function walk(delta) {
+    if (!board.dialogOpen || !board.dialogOpen()) return false;
+    var drawn = cards();
+    if (drawn.length === 0) return true;
+    // The open card is the one marked open, not the focused node: focus sits on the
+    // dialog's own panel, which is not one of the cards.
+    var at = -1;
+    for (var i = 0; i < drawn.length; i++) {
+      if (drawn[i].getAttribute("data-card") === String(board.openId)) at = i;
+    }
+    var next = at < 0 ? (delta > 0 ? 0 : drawn.length - 1) : (at + delta + drawn.length) % drawn.length;
+    board.openCard(drawn[next].getAttribute("data-card"));
+    return true;
   }
 
   /** Move focus to the next or previous drawn card, and say so for a screen reader. */
   function step(delta) {
+    // An open dialog walks instead of moving focus: the record stays whole, and Esc
+    // still returns to the board where it was.
+    if (walk(delta)) return;
     var drawn = cards();
     if (drawn.length === 0) return;
     var at = drawn.indexOf(document.activeElement);
@@ -78,9 +89,9 @@ export const BOARD_KEYS_JS = String.raw`(function () {
           board.closeCard();
           return;
         }
-        // The composer is a kit dialog, so the kit's own Esc closed it in the capture
-        // phase already; a filter with text is what Escape is for here. An empty one
-        // gives the keyboard back to the page by leaving the field.
+        // What is left for Escape is the filter: a field with text loses it, and the field
+        // itself then gives the keyboard back to the page. The keys sheet and the card
+        // dialog are above this, in the order a reader is likely to be inside them.
         if (board.hasFilter()) {
           board.clearFilter();
           if (typing(target)) target.blur();
@@ -93,17 +104,10 @@ export const BOARD_KEYS_JS = String.raw`(function () {
         return;
       }
       if (typing(target)) {
-        if (event.key === "Enter" && target.id === "card-dialog-note") board.addNote();
         if (event.key === "Enter" && target.id === "board-filter") board.applyFilter();
         return;
       }
-      if (event.key === "n") {
-        // Two modals over one board is a trap whose edge the reader cannot see, and a
-        // viewer's page has no composer to open at all.
-        if (!board.canWrite() || board.dialogOpen() || board.composerOpen()) return;
-        event.preventDefault();
-        board.focusComposer();
-      } else if (event.key === "/") {
+      if (event.key === "/") {
         event.preventDefault();
         board.focusFilter();
       } else if (event.key === "j") {