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

package/extensions/board/tools.ts

@@ -0,0 +1,279 @@
+/**
+ * The `board` tool: the shared feature list for one repository.
+ *
+ * One action-shaped tool, because every action is work on the same record and a
+ * model that has read the board should not have to learn a second surface to change
+ * it. The tool owns nothing but the dispatch: the workspace comes from
+ * `lib/board/session.ts`, the transition from `lib/board/rules.ts`, the bytes from
+ * `lib/board/store.ts`, and the words from `format.ts` and `result.ts`.
+ *
+ * A refusal is a failed result that still carries the card, so the next call starts
+ * from the truth — and it is the same refusal the page shows, because both go
+ * through `applyOp`.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { Static } from "typebox";
+import { cardRef, matchesQuery, normalizeCardId } from "../../lib/board/card.ts";
+import { indexOf } from "../../lib/board/links.ts";
+import { type CardOp, holds } from "../../lib/board/rules.ts";
+import { buildRound } from "../../lib/board/round.ts";
+import type { BoardStore } from "../../lib/board/store.ts";
+import { messageOf } from "../../lib/errors.ts";
+import { failedResult, textResult } from "../../lib/tool-result.ts";
+import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { callLine, detailsOrLine } from "../../lib/tui/tool.ts";
+import { formatRound } from "../../lib/board/round-text.ts";
+import { formatCard, formatCards, formatDropped } from "./format.ts";
+import { createTeamJoin, type TeamJoin } from "../../lib/session-tool.ts";
+import { BoardResult, collapsedLine, resultInput } from "./result.ts";
+import { createInput } from "./input.ts";
+import type { BoardSession } from "../../lib/board/session.ts";
+import { BoardParams } from "./schema.ts";
+import { BOARD_ACTIONS, BOARD_TOOL, type BoardAction, type BoardDetails, normalizeBoardAction } from "./types.ts";
+
+/** The parameters as the schema validates them. */
+type BoardArgs = Static<typeof BoardParams>;
+
+/**
+ * The call line's subject: the verb and what it acts on.
+ *
+ * `add` shows the title because the title is the identity of the thing being
+ * created; every other action names the card it touches, which is what a reader
+ * scanning the transcript is looking for.
+ */
+function callSubject(action: BoardAction, args: Record<string, unknown>): string {
+	const card = typeof args.card === "string" && args.card.trim() !== "" ? cardRef(args.card.trim()) : "";
+	if (action === "add") {
+		const title = typeof args.title === "string" ? args.title.trim() : "";
+		return title === "" ? "add" : `add ${title}`;
+	}
+	if (action === "list") {
+		const parts = ["list"];
+		if (args.round === true) parts.push("round");
+		if (typeof args.status === "string") parts.push(args.status);
+		if (typeof args.query === "string" && args.query.trim() !== "") parts.push(`"${args.query.trim()}"`);
+		if (card !== "") parts.push(card);
+		return parts.join(" ");
+	}
+	if (card === "") return action;
+	const status = typeof args.status === "string" ? ` ${args.status}` : "";
+	return `${action} ${card}${status}`;
+}
+
+/** One refusal: the reason for the model, the state for the renderer. */
+function refusal(action: BoardAction, me: BoardDetails["me"], message: string, card?: BoardDetails["card"]) {
+	return failedResult(`Error: ${message}`, {
+		action,
+		me,
+		error: message,
+		...(card === undefined ? {} : { card }),
+	});
+}
+
+/** The actions that need this session to be a teammate: everything but a read. */
+const MUTATING_ACTIONS = new Set<BoardAction>(BOARD_ACTIONS.filter((action) => action !== "list"));
+
+export function registerTools(pi: ExtensionAPI, runtime: BoardSession, deps: { team?: TeamJoin } = {}): void {
+	const team = deps.team ?? createTeamJoin(pi);
+	pi.registerTool({
+		name: BOARD_TOOL,
+		label: "Board",
+		description:
+			"The shared feature list for this repository: one card per feature, which any session reads and writes. " +
+			"A card carries the feature's outcome, the session that holds it, path hints, the plan it is executing, " +
+			"its priority, what it waits for, and its notes. `list` shows the board (`status` filters one lane, " +
+			"`mine` shows only what this session holds, `query` matches a title, a path hint, or a holder, `card` shows one card, `round` adds the lead's rollup " +
+			"of owners, unassigned, unplanned, blocked, and idle - the rollup always covers the whole board). `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, paths, priority, and the cards it waits for); " +
+			"`drop` deletes a `todo`, a `done`, or one you hold. A card's steps do not belong on the board - they " +
+			"belong in the plan and in `todo`.",
+		promptSnippet:
+			"The shared feature list for this repository: list, add, claim, release, reclaim, move, note, plan, edit, drop.",
+		promptGuidelines: [
+			"Claim a card before working on it; release or finish it when you stop, and reclaim a card whose owner is gone.",
+			"Record the plan file with `board` action `plan` once the plan is approved, then execute it.",
+			"Note each phase of the work, and move the card to `done` or `blocked` when it changes state.",
+			"A card that waits on another is linked with `edit` and `dependsOn`, so the order is on the board instead of in a refusal.",
+			"A feature's steps belong in `todo`, not on the board: one card is one feature, whatever it takes.",
+			"A `handoff` in your inbox is work you now own: read it with `session inbox`, record the plan, and start it.",
+			"`paths` are hints for a reader, not claims; `session`'s path claims are what protect a file.",
+		],
+		parameters: BoardParams,
+		annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const args = params as BoardArgs;
+			const action = normalizeBoardAction(args.action);
+			if (!action) {
+				return refusal(
+					"list",
+					{ label: "board" },
+					`unknown action "${String(args.action)}"; use ${BOARD_ACTIONS.join(", ")}.`,
+				);
+			}
+			const me = runtime.who(ctx, ctx.cwd);
+			try {
+				// Working a card makes this session a teammate, once: the board is the user's
+				// surface for the team, so nobody has to know the bus exists. A failed join is
+				// not a failed card write — the board works with no bus at all — and it is not
+				// marked, so the next write asks again.
+				if (MUTATING_ACTIONS.has(action) && !runtime.joined()) {
+					if ((await team.join(ctx)).ok) runtime.markJoined();
+				}
+				const store = await runtime.store(ctx.cwd);
+				const now = runtime.now();
+				switch (action) {
+					case "list":
+						return await read(store, action, me, args, now);
+					case "add":
+						return await add(store, me, args, now);
+					case "claim":
+						return await mutate(store, action, me, now, args, { kind: "claim" });
+					case "release":
+						return await mutate(store, action, me, now, args, { kind: "release" });
+					case "reclaim":
+						return await mutate(store, action, me, now, args, { kind: "reclaim" });
+					case "move": {
+						if (args.card === undefined) return refusal(action, me, 'card is required: pass the id, e.g. "4".');
+						const status = args.status;
+						if (status === undefined || status === "todo") {
+							return refusal(
+								action,
+								me,
+								'move needs a target lane: "doing", "blocked", or "done". Use release to return a card to todo.',
+							);
+						}
+						return await mutate(store, action, me, now, args, { kind: "move", status });
+					}
+					case "note":
+						return await mutate(store, action, me, now, args, { kind: "note", text: args.text });
+					case "plan":
+						return await mutate(store, action, me, now, args, { kind: "plan", path: args.path });
+					case "edit": {
+						if (
+							args.title === undefined &&
+							args.paths === undefined &&
+							args.priority === undefined &&
+							args.dependsOn === undefined
+						) {
+							return refusal(action, me, "edit needs a title, paths, priority, or dependsOn.");
+						}
+						return await mutate(store, action, me, now, args, {
+							kind: "edit",
+							title: args.title,
+							paths: args.paths,
+							priority: args.priority,
+							dependsOn: args.dependsOn,
+						});
+					}
+					case "drop":
+						return await dropCard(store, me, args, now);
+				}
+			} catch (error) {
+				return refusal(action, me, messageOf(error));
+			}
+		},
+
+		renderCall(args, theme, context) {
+			const action = normalizeBoardAction(args.action) ?? "list";
+			return callLine(theme, context.lastComponent, BOARD_TOOL, callSubject(action, args as Record<string, unknown>));
+		},
+
+		renderResult(result, options, theme, context) {
+			const text = reuseText(context?.lastComponent);
+			const details = toolDetails<BoardDetails>(result.details);
+			const outcome = detailsOrLine(theme, result, options.expanded, details);
+			if ("line" in outcome) {
+				text.setText(outcome.line);
+				return text;
+			}
+			const input = resultInput(outcome.details);
+			if (!input) {
+				text.setText(collapsedLine(theme, outcome.details));
+				return text;
+			}
+			const view =
+				context?.lastComponent instanceof BoardResult ? context.lastComponent : new BoardResult(input, theme);
+			view.setInput(input, theme);
+			return view;
+		},
+	});
+}
+
+/** `list`: the board, one card, or the lead's rollup. */
+async function read(
+	store: BoardStore,
+	action: BoardAction,
+	me: BoardDetails["me"],
+	args: BoardArgs,
+	now: number,
+): Promise<ReturnType<typeof textResult<BoardDetails>>> {
+	const cards = await store.list();
+	if (args.card !== undefined) {
+		const id = normalizeCardId(args.card);
+		if (id === undefined) return refusal(action, me, `"${args.card}" is not a card id.`);
+		const card = cards.find((entry) => entry.id === id);
+		if (!card) return refusal(action, me, `${cardRef(id)} does not exist.`);
+		return textResult(formatCard(card, indexOf(cards)), { action, me, card });
+	}
+	const listed = cards.filter(
+		(card) =>
+			(args.status === undefined || card.status === args.status) &&
+			(args.query === undefined || matchesQuery(card, args.query)) &&
+			// The same rule a claim is checked against, so "mine" cannot list a card this
+			// session could not release.
+			(args.mine !== true || holds(card, me)),
+	);
+	if (args.round !== true) return textResult(formatCards(listed), { action, me, cards: listed });
+	const round = buildRound(cards, now);
+	return textResult(formatRound(cards, round), { action, me, cards: listed, round });
+}
+
+/** `add`: the only action that creates a card. */
+async function add(
+	store: BoardStore,
+	me: BoardDetails["me"],
+	args: BoardArgs,
+	now: number,
+): Promise<ReturnType<typeof textResult<BoardDetails>>> {
+	const parsed = createInput({ title: args.title, paths: args.paths, priority: args.priority, note: args.note });
+	if ("error" in parsed) return refusal("add", me, parsed.error);
+	const card = await store.create(parsed.input, me, now);
+	return textResult(formatCard(card), { action: "add", me, card });
+}
+
+/** The actions that change a card the caller names. */
+async function mutate(
+	store: BoardStore,
+	action: BoardAction,
+	me: BoardDetails["me"],
+	now: number,
+	args: BoardArgs,
+	op: CardOp,
+): Promise<ReturnType<typeof textResult<BoardDetails>>> {
+	if (args.card === undefined) return refusal(action, me, 'card is required: pass the id, e.g. "4".');
+	const id = normalizeCardId(args.card);
+	if (id === undefined) return refusal(action, me, `"${args.card}" is not a card id.`);
+	const result = await store.mutate(id, op, me, now);
+	if (!result.ok) return refusal(action, me, result.error, result.card);
+	return textResult(formatCard(result.card), { action, me, card: result.card });
+}
+
+/** `drop`: the card and its notes leave together, so the report is the id. */
+async function dropCard(
+	store: BoardStore,
+	me: BoardDetails["me"],
+	args: BoardArgs,
+	now: number,
+): Promise<ReturnType<typeof textResult<BoardDetails>>> {
+	if (args.card === undefined) return refusal("drop", me, 'card is required: pass the id, e.g. "4".');
+	const id = normalizeCardId(args.card);
+	if (id === undefined) return refusal("drop", me, `"${args.card}" is not a card id.`);
+	const result = await store.mutate(id, { kind: "drop" }, me, now);
+	if (!result.ok) return refusal("drop", me, result.error, result.card);
+	return textResult(formatDropped(id), { action: "drop", me, dropped: id });
+}

package/extensions/board/transport/router.ts

@@ -0,0 +1,172 @@
+/**
+ * The board page's router: one request in, one response out, and every policy the
+ * served surface obeys decided here.
+ *
+ * The page can read and it can write, so it is checked the way `plan`'s review page
+ * is: a token in the URL, the `Host` allowlist, an origin check on every
+ * state-changing method, and a JSON body. The guards themselves are `lib/http`'s —
+ * this module only decides the order and the sentences.
+ *
+ * Nothing here knows what a board is. The snapshot arrives as `view()`, a write as
+ * `write()`, and the document as `page()`, all supplied by `page.ts`, so this file
+ * can be tested with a fake store and no server.
+ */
+
+import {
+	envelopeRefusal,
+	eventHeaders,
+	jsonError,
+	jsonResponse,
+	pageHeaders,
+	PAGE_METHODS,
+	parseRequestUrl,
+	postOnly,
+	requireJsonBody,
+	scriptHeaders,
+	type ServeResponse,
+} from "../../../lib/http/index.ts";
+import type { BoardView } from "../../../lib/board/view.ts";
+import type { Card } from "../../../lib/board/card.ts";
+import { THEME_JS, THEME_JS_PATH } from "../../../lib/web/index.ts";
+import type { PageView } from "../view/page.ts";
+
+/** The methods this surface serves: reads, writes, and the one deletion. */
+const METHODS: readonly string[] = [...PAGE_METHODS, "DELETE"];
+
+/**
+ * What a credential may do on this page.
+ *
+ * A page can be opened by the session that serves it and by a teammate watching it, and
+ * the two carry different tokens: `write` may change a card, `view` may only read. The
+ * split is a value here and not a boolean threaded through the page, so a route asks one
+ * function instead of remembering which token it was given.
+ */
+export type Authority = "write" | "view";
+
+/** The verbs a card route accepts, in the order the page uses them. */
+const CARD_VERBS = ["claim", "release", "reclaim", "assign", "move", "note", "plan", "edit"] as const;
+
+/** One card verb. */
+export type CardVerb = (typeof CARD_VERBS)[number];
+
+/** One write the page asks for, already routed but not yet applied. */
+export type PageWrite =
+	| { kind: "add"; body: Record<string, unknown> }
+	| { kind: "drop"; id: string }
+	| { kind: CardVerb; id: string; body: Record<string, unknown> };
+
+/** What a write did, or why it was refused with the status the page shows. */
+export type PageResult = { ok: true; card: Card } | { ok: false; status: number; error: string; card?: Card };
+
+/** Everything the router needs from the running page. */
+export interface BoardRouterContext {
+	/** What the request's token may do here, or undefined when it is not a token of this page. */
+	authority: (given: string | null) => Authority | undefined;
+	/** The names this server answers to. */
+	hosts: () => readonly string[];
+	/** The document for one tab, as the authority that asked for it may see it. */
+	page: (view: PageView, authority: Authority) => Promise<string>;
+	/** The client script. */
+	script: string;
+	/** The snapshot the page renders, and the body of `/api/board`. */
+	view: () => Promise<BoardView>;
+	/** Apply one write as the serving session. */
+	write: (request: PageWrite) => Promise<PageResult>;
+}
+
+/**
+ * Handle one request. `method`, `rawUrl`, and `headers` are the raw HTTP values;
+ * `body` is the request body, which is only non-empty when the server caps it.
+ */
+export async function handleBoardRequest(
+	ctx: BoardRouterContext,
+	method: string,
+	rawUrl: string,
+	headers: Record<string, string | string[] | undefined> = {},
+	body = "",
+): Promise<ServeResponse> {
+	const envelope = envelopeRefusal({ method, headers, hosts: ctx.hosts(), allowed: METHODS });
+	if (envelope) return envelope;
+
+	const parsed = parseRequestUrl(rawUrl);
+	if (!parsed) return jsonError(400, "Malformed request URL.");
+	const { pathname, search } = parsed;
+
+	if (pathname === "/favicon.ico") return { status: 204, headers: { "Cache-Control": "no-store" } };
+	if (pathname === THEME_JS_PATH) return { status: 200, headers: scriptHeaders(), body: THEME_JS };
+	if (pathname === "/app.js") return { status: 200, headers: scriptHeaders(), body: ctx.script };
+
+	const authority = ctx.authority(search.get("token"));
+	if (authority === undefined) return jsonError(403, "Invalid or missing token.");
+
+	if (pathname === "/api/board") return jsonResponse(200, await ctx.view());
+	if (pathname === "/" || pathname === "/index.html") {
+		const view = viewOf(search.get("view"));
+		return { status: 200, headers: pageHeaders(), body: await ctx.page(view, authority) };
+	}
+	if (pathname === "/events") return { status: 200, headers: eventHeaders(), stream: true };
+
+	// Everything below changes a card, so a credential that may only read stops here.
+	const readOnly = writeGuard(authority);
+	if (readOnly) return readOnly;
+
+	if (pathname === "/api/cards") {
+		const methodRefusal = postOnly(method, "add a card");
+		if (methodRefusal) return methodRefusal;
+		const jsonRefusal = requireJsonBody(headers["content-type"]);
+		if (jsonRefusal) return jsonRefusal;
+		const parsedBody = parseBody(body);
+		if (!parsedBody) return jsonError(400, "The request body must be a JSON object.");
+		return writeAnswer(await ctx.write({ kind: "add", body: parsedBody }));
+	}
+
+	const route = /^\/api\/cards\/([^/]+)(?:\/([^/]+))?$/.exec(pathname);
+	if (!route) return jsonError(404, "That page does not exist.");
+	const id = decodeURIComponent(route[1] ?? "");
+	const verb = route[2];
+
+	if (verb === undefined) {
+		if (method.toUpperCase() !== "DELETE") return jsonError(405, "Use DELETE to drop a card.");
+		return writeAnswer(await ctx.write({ kind: "drop", id }));
+	}
+	if (!CARD_VERBS.includes(verb as CardVerb)) return jsonError(404, "That card action does not exist.");
+	const methodRefusal = postOnly(method, verb);
+	if (methodRefusal) return methodRefusal;
+	const jsonRefusal = requireJsonBody(headers["content-type"]);
+	if (jsonRefusal) return jsonRefusal;
+	const parsedBody = parseBody(body);
+	if (!parsedBody) return jsonError(400, "The request body must be a JSON object.");
+	return writeAnswer(await ctx.write({ kind: verb as CardVerb, id, body: parsedBody }));
+}
+
+/** The 403 for a credential that may read this page but not change it. */
+function writeGuard(authority: Authority): ServeResponse | undefined {
+	if (authority === "write") return undefined;
+	return jsonError(403, "This page is read-only for a viewer.");
+}
+
+/** The tab a `?view=` names; anything else is the board. */
+function viewOf(raw: string | null): PageView {
+	return raw === "team" ? "team" : "board";
+}
+
+/** A request body as an object, or undefined when it is not one. */
+function parseBody(body: string): Record<string, unknown> | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return undefined;
+	}
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+	return parsed as Record<string, unknown>;
+}
+
+/** A write's answer: the card, or the refusal and the card it left alone. */
+function writeAnswer(result: PageResult): ServeResponse {
+	if (result.ok) return jsonResponse(200, { card: result.card });
+	return jsonResponse(
+		result.status,
+		result.card === undefined ? { error: result.error } : { error: result.error, card: result.card },
+	);
+}

package/extensions/board/transport/server.ts

@@ -0,0 +1,149 @@
+/**
+ * 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.
+ *
+ * `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.
+ */
+
+import {
+	type EventSink,
+	LOOPBACK_HOSTS,
+	type LoopbackServer,
+	mintToken,
+	serveLoopback,
+	tokenMatches,
+} from "../../../lib/http/index.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";
+
+/** How often the page is offered a frame; a frame is sent only when the signature moved. */
+export 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;
+
+/** 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. */
+	token?: string;
+	/** The credential a viewer carries: every read, and no write. */
+	viewToken?: string;
+	page: (view: PageView, authority: Authority) => 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;
+	/** Grace after the last stream leaves; 0 or absent waits for `close()`. */
+	idleMs?: number;
+	/** The interval seam, so a test drives the ticker instead of waiting. */
+	interval?: RepeatTimer;
+}
+
+/** A running page. */
+export interface BoardServer {
+	port: number;
+	/** The URL the lead opens: the page, with the credential that may change it. */
+	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. */
+	pushed: () => string;
+	close: () => Promise<void>;
+}
+
+export async function createBoardServer(options: BoardServerOptions): Promise<BoardServer> {
+	const token = options.token ?? mintToken();
+	const viewToken = options.viewToken ?? mintToken();
+	const clients = new Set<EventSink>();
+	const interval = options.interval ?? defaultInterval;
+	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;
+		},
+		hosts: () => LOOPBACK_HOSTS,
+		page: options.page,
+		script: options.script,
+		view: options.view,
+		write: options.write,
+	};
+
+	const push = async (): Promise<void> => {
+		if (clients.size === 0) return;
+		const view = await options.view();
+		// A frame is a snapshot, so sending one that says nothing new costs the page a
+		// parse and every reader a flicker. The signature is what changes.
+		if (view.sig === pushed) return;
+		pushed = view.sig;
+		const frame = `data: ${JSON.stringify(view)}\n\n`;
+		for (const sink of clients) sink.write(frame);
+	};
+
+	const server: LoopbackServer = await serveLoopback({
+		ports: options.ports,
+		maxBodyBytes: MAX_BODY_BYTES,
+		...(options.idleMs === undefined || options.onIdle === undefined
+			? {}
+			: { idle: { ms: options.idleMs, onIdle: options.onIdle } }),
+		async handler(request) {
+			const result = await handleBoardRequest(ctx, request.method, request.url, request.headers, request.body);
+			if (!result.stream) return { result };
+			return {
+				result,
+				openSink(sink) {
+					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`);
+					});
+					return () => {
+						clients.delete(sink);
+					};
+				},
+			};
+		},
+	});
+
+	const stopTicker = interval(PUSH_MS, () => void push());
+	let closed = false;
+	const close = async (): Promise<void> => {
+		if (closed) return;
+		closed = true;
+		stopTicker();
+		for (const sink of clients) sink.end();
+		clients.clear();
+		await server.close();
+	};
+
+	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,
+	};
+}

package/extensions/board/types.ts

@@ -0,0 +1,54 @@
+/**
+ * The shapes the `board` tool registers and reports.
+ *
+ * `details` is the result's state: the card an action produced, the cards a list
+ * read, the rollup when it was asked for, and — on a refusal — the card as it was,
+ * so a retry starts from the truth rather than from what the model thought it
+ * knew. The renderer and the tool share these types, and nothing else.
+ */
+
+import type { Card } from "../../lib/board/card.ts";
+import type { Actor } from "../../lib/board/rules.ts";
+import type { RoundSummary } from "../../lib/board/round.ts";
+
+/** The tool's name. One extension registers it, so it stays here. */
+export const BOARD_TOOL = "board";
+
+/** The actions the tool accepts, in the order the description lists them. */
+export const BOARD_ACTIONS = [
+	"list",
+	"add",
+	"claim",
+	"release",
+	"reclaim",
+	"move",
+	"note",
+	"plan",
+	"edit",
+	"drop",
+] as const;
+
+/** One action. */
+export type BoardAction = (typeof BOARD_ACTIONS)[number];
+
+/** A result the transcript renders and the page's routes mirror. */
+export interface BoardDetails {
+	action: BoardAction;
+	/** The serving session: the id Pi knows, and the label a card records. */
+	me: Actor;
+	/** The board a `list` read, in lane order. */
+	cards?: Card[];
+	/** The card an action produced, or the one a refusal left untouched. */
+	card?: Card;
+	/** The lead's rollup, only for `list` with `round`. */
+	round?: RoundSummary;
+	/** The id a `drop` removed. */
+	dropped?: string;
+	/** A refusal's reason, which the renderer draws instead of the details. */
+	error?: string;
+}
+
+/** Whether a value is one of the actions, so an unknown one is a refusal and not a crash. */
+export function normalizeBoardAction(raw: unknown): BoardAction | undefined {
+	return typeof raw === "string" && BOARD_ACTIONS.includes(raw as BoardAction) ? (raw as BoardAction) : undefined;
+}