Refactor ledger module with factory pattern, stale guards, and named constants

Author: ofriw

ledger/store.ts

@@ -28,16 +28,21 @@ export function getEntryNames(state: AgenticodingState): string[] {
 	return Array.from(state.ledger.keys()).sort();
 }
 
+const PREVIEW_MAX_CHARS = 80;
+const ELLIPSIS_LENGTH = 3;
+
 export function formatEntryList(state: AgenticodingState): string {
 	const names = getEntryNames(state);
-	if (names.length === 0) return "(empty)";
+	if (names.length === 0) return "";
 
 	return names
 		.map((name) => {
 			const content = state.ledger.get(name)!;
 			const firstLine = content.split("\n")[0] ?? "";
 			const preview =
-				firstLine.length > 80 ? firstLine.slice(0, 77) + "..." : firstLine;
+				firstLine.length > PREVIEW_MAX_CHARS
+					? firstLine.slice(0, PREVIEW_MAX_CHARS - ELLIPSIS_LENGTH) + "..."
+					: firstLine;
 			return `  ${name}: ${preview}`;
 		})
 		.join("\n");
@@ -48,9 +53,11 @@ export async function saveLedgerEntry(
 	state: AgenticodingState,
 	name: string,
 	content: string,
+	assertWritable?: () => void,
 ): Promise<string[]> {
 	const release = await acquireWriteLock();
 	try {
+		assertWritable?.();
 		const truncated = truncateHead(content, {
 			maxLines: DEFAULT_MAX_LINES,
 			maxBytes: DEFAULT_MAX_BYTES,

ledger/tools.ts

@@ -6,86 +6,94 @@
  * list of entry names in both result text and details.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { AgenticodingState } from "../state.js";
 import { formatEntryList, getEntryNames, saveLedgerEntry } from "./store.js";
 
-// ── Registration ──────────────────────────────────────────────────────
+// ── Factory ───────────────────────────────────────────────────────────
 
-export function registerLedgerTools(
+/**
+ * Creates ledger tool definitions (ledger_add, ledger_get, ledger_list).
+ *
+ * Shared by parent registration (withPromptHints=true) and child spawn
+ * sessions (withPromptHints=false). The prompt hints (snippet, guidelines)
+ * are only included for the parent — child agents don't need them.
+ */
+export function createLedgerToolDefinitions(
 	pi: ExtensionAPI,
 	state: AgenticodingState,
-): void {
-	// ── ledger_add ──────────────────────────────────────────────────
-	pi.registerTool({
+	options?: { withPromptHints?: boolean; isStale?: () => boolean },
+): ToolDefinition[] {
+	const withHints = options?.withPromptHints ?? false;
+	const assertFresh = () => {
+		if (options?.isStale?.()) {
+			throw new Error("Spawn invalidated by reset.");
+		}
+	};
+
+	const ledgerAdd: ToolDefinition = {
 		name: "ledger_add",
 		label: "Ledger Add",
 		description:
 			"Save or refine a compact continuity entry. " +
 			"Same name overwrites the previous entry (refinement). " +
 			"Writes are serialized via a process-local lock; same-name writes overwrite in completion order. " +
 			"Always returns the current list of up to date entries.",
-
-		promptSnippet: "Save or refine a compact continuity entry",
-		promptGuidelines: [
-			"Continuously maintain the ledger while you work. After meaningful reads, research, analysis, decisions, or milestones, either refine an existing entry, create a compact reusable entry, or consciously skip because nothing reusable was learned.",
-			"Prefer refining existing entries over creating many tiny ones. Do not try to make the ledger complete.",
-		],
-
+		...(withHints
+			? {
+					promptSnippet: "Save or refine a compact continuity entry",
+					promptGuidelines: [
+						"Continuously maintain the ledger while you work. After meaningful reads, research, analysis, decisions, or milestones, either refine an existing entry, create a compact reusable entry, or consciously skip because nothing reusable was learned.",
+						"Prefer refining existing entries over creating many tiny ones. Do not try to make the ledger complete.",
+					],
+				}
+			: {}),
 		executionMode: "sequential",
-
 		parameters: Type.Object({
 			name: Type.String({
 				description:
 					"Kebab-case entry identifier. Using an existing name overwrites that entry (refinement).",
 			}),
 			content: Type.String({
 				description:
-					"Compact markdown. Prefer one reusable item per bullet. " +
-					"Capture only stable facts, decisions, constraints, progress, and expensive discoveries " +
-					"that future work should build on. Truncated at 50KB / 2000 lines.",
+					"Compact markdown. Capture only reusable facts, decisions, " +
+					"constraints, progress, and expensive discoveries. " +
+					"Truncated at 50KB / 2000 lines.",
 			}),
 		}),
-
-		async execute(
-			_toolCallId,
-			params,
-			_signal,
-			_onUpdate,
-			_ctx,
-		) {
-			const names = await saveLedgerEntry(pi, state, params.name, params.content);
-
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			assertFresh();
+			const names = await saveLedgerEntry(pi, state, params.name, params.content, assertFresh);
 			return {
 				content: [
 					{
 						type: "text",
 						text: `Saved ledger entry "${params.name}".` +
-							`\n\nEntries:\n${formatEntryList(state)}`,
+							`\n\nEntries:\n${formatEntryList(state) || "(empty)"}`,
 					},
 				],
 				details: { entries: names },
 			};
 		},
-	});
+	};
 
-	// ── ledger_get ──────────────────────────────────────────────────
-	pi.registerTool({
+	const ledgerGet: ToolDefinition = {
 		name: "ledger_get",
 		label: "Ledger Get",
 		description:
 			"Retrieve a ledger entry's full body by name. " +
 			"Always returns the current list of entry names.",
-
-		promptSnippet: "Fetch a ledger entry by name",
+		...(withHints
+			? { promptSnippet: "Fetch a ledger entry by name" }
+			: {}),
 		parameters: Type.Object({
 			name: Type.String({
 				description: "Entry name to retrieve.",
 			}),
 		}),
-
 		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			assertFresh();
 			const content = state.ledger.get(params.name);
 			const names = getEntryNames(state);
 
@@ -96,7 +104,7 @@ export function registerLedgerTools(
 							type: "text",
 							text:
 								`Entry "${params.name}" not found.` +
-								`\n\nEntries:\n${formatEntryList(state)}`,
+								`\n\nEntries:\n${formatEntryList(state) || "(empty)"}`,
 						},
 					],
 					details: { entries: names, found: false },
@@ -109,37 +117,50 @@ export function registerLedgerTools(
 						type: "text",
 						text:
 							`--- ${params.name} ---\n${content}\n` +
-							`---\nEntries:\n${formatEntryList(state)}`,
+							`---\nEntries:\n${formatEntryList(state) || "(empty)"}`,
 					},
 				],
 				details: { entries: names, found: true },
 			};
 		},
-	});
+	};
 
-	// ── ledger_list ─────────────────────────────────────────────────
-	pi.registerTool({
+	const ledgerList: ToolDefinition = {
 		name: "ledger_list",
 		label: "Ledger List",
 		description:
 			"List all ledger entries as name + first-line preview. " +
 			"Always returns the current list of entry names.",
-
-		promptSnippet: "List all ledger entries",
+		...(withHints
+			? { promptSnippet: "List all ledger entries" }
+			: {}),
 		parameters: Type.Object({}),
-
 		async execute() {
+			assertFresh();
 			const names = getEntryNames(state);
-
 			return {
 				content: [
 					{
 						type: "text",
-						text: `Entries:\n${formatEntryList(state)}`,
+						text: `Entries:\n${formatEntryList(state) || "(empty)"}`,
 					},
 				],
 				details: { entries: names },
 			};
 		},
-	});
+	};
+
+	return [ledgerAdd, ledgerGet, ledgerList];
+}
+
+// ── Registration ──────────────────────────────────────────────────────
+
+export function registerLedgerTools(
+	pi: ExtensionAPI,
+	state: AgenticodingState,
+): void {
+	const tools = createLedgerToolDefinitions(pi, state, { withPromptHints: true });
+	for (const tool of tools) {
+		pi.registerTool(tool);
+	}
 }