import path from "node:path"; import { defineTool, keyHint, type ToolDefinition, withFileMutationQueue, } from "@earendil-works/pi-coding-agent"; import { Text } from "@earendil-works/pi-tui"; import { Type } from "typebox"; import { BOARD_NOTE_LIMIT, BOARD_PATH } from "./board-constants.ts"; import type { BoardProposal } from "./board-state.ts"; import type { BoardExec, BookServer } from "./book-server.ts"; import { loadBoardState, loadBookServer, loadOpenBrowser, loadProjectIndex, loadSystemRenderer, } from "./loaders.js"; import { requireProjectRoot } from "./project-root.ts"; import { expandableFallback } from "./tool-rendering.ts"; const STATES = ["todo", "done", "open", "dropped"] as const; const proposalParameters = Type.Object({ items: Type.Array( Type.Object({ id: Type.String({ description: "Existing spec, plan, or issue ID." }), state: Type.Enum(STATES, { type: "string", description: "Proposed board state for the item type.", }), rationale: Type.String({ minLength: 1, maxLength: 1000, description: "Terse evidence supporting this proposed state.", }), }), { minItems: 0, maxItems: 100 }, ), }); const updateParameters = Type.Object({ items: Type.Array( Type.Object({ id: Type.String({ description: "Existing spec, plan, or issue ID." }), state: Type.Enum(STATES, { type: "string", description: "Board state for the item type.", }), note: Type.String({ minLength: 1, maxLength: BOARD_NOTE_LIMIT, description: "Terse verified evidence stored with the board entry.", }), }), { minItems: 0, maxItems: 100 }, ), }); interface CallTheme { fg(style: string, text: string): string; bold(text: string): string; } function renderBoardItems( name: string, args: { items?: unknown }, theme: CallTheme, context: { expanded: boolean; lastComponent?: unknown; keyHint?: typeof keyHint; }, ): Text { const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0); const items = Array.isArray(args.items) ? (args.items as Record[]) : []; const count = items.length; let output = `${theme.fg("toolTitle", theme.bold(name))} ${theme.fg("toolOutput", `${count} item${count === 1 ? "" : "s"}`)}`; if (!context.expanded && count > 0) { output += theme.fg( "dim", ` (${(context.keyHint ?? keyHint)("app.tools.expand", "to expand")})`, ); } else { for (const item of items) { output += `\n${theme.fg("accent", String(item["state"]).toUpperCase())} ${theme.fg("toolOutput", String(item["id"]))}`; const evidence = item["rationale"] ?? item["note"]; if (evidence) output += `\n${theme.fg("dim", String(evidence))}`; } } text.setText(output); return text; } const renderBoardToolResult = ( result: Readonly<{ content: Parameters[0]; details?: unknown; }>, expanded: boolean, theme: CallTheme, isError: boolean, lastComponent: unknown, messages: Readonly<{ empty: string; summary: (count: number) => string }>, hint?: typeof keyHint, ): Text => { const text = (lastComponent as Text | undefined) ?? new Text("", 0, 0); const items = (result.details as { items?: BoardProposal[] } | undefined) ?.items; if (!items) { text.setText( expandableFallback( result.content, expanded, theme, isError ? "error" : "muted", hint, ), ); return text; } text.setText( theme.fg( "success", items.length === 0 ? messages.empty : messages.summary(items.length), ), ); return text; }; export interface BoardRuntime { tool: ToolDefinition; updateTool: ToolDefinition; open(cwd: string, onExec?: BoardExec, page?: string): Promise; shutdown(): void; } export function createBoardRuntime(): BoardRuntime { const proposals = new Map>(); const servers = new Map>(); let generation = 0; const executors = new Map(); const loadBoard = async (cwd: string) => { const root = requireProjectRoot(cwd); const [projectIndex, boardState] = await Promise.all([ loadProjectIndex(), loadBoardState(), ]); const index = projectIndex.loadProjectIndex(root); const state = boardState.readBoardState(root, index.prefix); return { boardState, index, root, state }; }; const tool = defineTool({ name: "system_board_propose", annotations: { readOnlyHint: false }, exposure: "deferred", label: "system_board_propose", description: "Propose board state changes for review; no direct .system/board.json write.", promptSnippet: "Propose System board states for human review", promptGuidelines: [ "During /system assess, call system_board_propose exactly once with evidence-backed state changes; use an empty items list when no changes are justified.", ], parameters: proposalParameters, renderCall(args, theme, context) { return renderBoardItems("system_board_propose", args, theme, context); }, renderResult(result, { expanded }, theme, context) { return renderBoardToolResult( result, expanded, theme, Boolean(context.isError), context.lastComponent, { empty: "✓ no changes proposed", summary: (count) => `✓ ${count} change${count === 1 ? "" : "s"} proposed`, }, context.keyHint ?? keyHint, ); }, async execute(_toolCallId, params, signal, _onUpdate, ctx) { const root = requireProjectRoot(ctx.cwd); return withFileMutationQueue(path.resolve(root, BOARD_PATH), async () => { if (signal?.aborted) throw new Error("Board proposal cancelled"); const { boardState, index } = await loadBoard(root); if (signal?.aborted) throw new Error("Board proposal cancelled"); const byId = new Map( index.documents.map((document) => [document.metadata.id, document]), ); const proposed = new Map(); for (const raw of params.items) { const document = byId.get(raw.id); if (!document) throw new Error(`No System board item: ${raw.id}`); const valid = boardState.isValidBoardState( document.metadata.type, raw.state, ); if (!valid) throw new Error( `Invalid ${document.metadata.type} board state ${raw.state}: ${raw.id}`, ); proposed.set(raw.id, { id: raw.id, state: raw.state, rationale: raw.rationale.trim(), }); } const current = proposals.get(root) ?? new Map(); current.clear(); for (const [id, proposal] of proposed) current.set(id, proposal); proposals.set(root, current); const items = [...proposed.values()].sort((left, right) => left.id.localeCompare(right.id), ); return { content: [ { type: "text" as const, text: `${params.items.length} board state proposal(s) recorded for human review. Run /system board to inspect and apply them.`, }, ], details: { items }, }; }); }, }); const updateTool = defineTool({ name: "system_board_update", annotations: { readOnlyHint: false }, exposure: "deferred", label: "system_board_update", description: "Apply verified board states to .system/board.json as agent; reject invalid states.", promptSnippet: "Update System board states from verified work", promptGuidelines: [ "After fresh verification in /system exec, call system_board_update exactly once with the states your work proves; use an empty items list when no change is justified.", ], parameters: updateParameters, renderCall(args, theme, context) { return renderBoardItems("system_board_update", args, theme, context); }, renderResult(result, { expanded }, theme, context) { return renderBoardToolResult( result, expanded, theme, Boolean(context.isError), context.lastComponent, { empty: "✓ no board changes", summary: (count) => `✓ ${count} board change${count === 1 ? "" : "s"} applied`, }, context.keyHint ?? keyHint, ); }, async execute(_toolCallId, params, signal, _onUpdate, ctx) { const root = requireProjectRoot(ctx.cwd); return withFileMutationQueue(path.resolve(root, BOARD_PATH), async () => { signal?.throwIfAborted(); const loaded = await loadBoard(root); signal?.throwIfAborted(); let state = loaded.state; const updatedAt = new Date().toISOString(); const applied: BoardProposal[] = []; for (const raw of params.items) { state = loaded.boardState.updateBoardState( state, loaded.index.documents, raw.id, raw.state, "agent", updatedAt, raw.note, ); applied.push({ id: raw.id, state: raw.state, rationale: raw.note.trim(), }); } if (applied.length > 0) loaded.boardState.writeBoardState(loaded.root, state); const items = [...applied].sort((left, right) => left.id.localeCompare(right.id), ); return { content: [ { type: "text" as const, text: applied.length === 0 ? "No board states changed." : `${applied.length} board state(s) applied. Run /system board to review or override them.`, }, ], details: { items }, }; }); }, }); return { tool, updateTool, async open( cwd: string, onExec?: BoardExec, page = "/board.html", ): Promise { const ticket = generation; const { index } = await loadBoard(cwd); if (ticket !== generation) throw new Error("System book opening cancelled"); if (onExec) executors.set(index.root, onExec); let pending = servers.get(index.root); if (!pending) { pending = (async () => { const [{ renderSystemBookSite }, { startBookServer }] = await Promise.all([loadSystemRenderer(), loadBookServer()]); const current = proposals.get(index.root) ?? new Map(); proposals.set(index.root, current); return startBookServer( index.root, current, renderSystemBookSite, async (id) => { const execute = executors.get(index.root); if (!execute) throw new Error("System execution is unavailable"); await execute(id); }, ); })(); servers.set(index.root, pending); } let server: BookServer; try { server = await pending; } catch (error) { if (servers.get(index.root) === pending) servers.delete(index.root); throw error; } if (ticket !== generation) { server.close(); throw new Error("System book opening cancelled"); } const url = new URL(page, server.url); url.searchParams.set( "k", new URL(server.url).searchParams.get("k") ?? "", ); const { openUrl } = await loadOpenBrowser(); const opened = await openUrl(url.href); const label = page === "/board.html" ? "System board" : "System book"; return opened.ok ? `${label} opened: ${url.href}\nBrowser: ${opened.command}` : `${label} running: ${url.href}\nBrowser: ${opened.error}`; }, shutdown() { generation++; proposals.clear(); for (const server of servers.values()) void server.then( (value) => value.close(), () => {}, ); servers.clear(); executors.clear(); }, }; }