pi-agenticoding 0.1.0

package/ledger/tools.ts

@@ -0,0 +1,166 @@
+/**
+ * Ledger tool definitions for the agenticoding extension.
+ *
+ * Three tools: ledger_add (sequential, serialized write), ledger_get, ledger_list.
+ * All read from the in-memory state.ledger Map and always return the current
+ * list of entry names in both result text and details.
+ */
+
+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";
+
+// ── Factory ───────────────────────────────────────────────────────────
+
+/**
+ * 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,
+	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.",
+		...(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. Capture only reusable facts, decisions, " +
+					"constraints, progress, and expensive discoveries. " +
+					"Truncated at 50KB / 2000 lines.",
+			}),
+		}),
+		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) || "(empty)"}`,
+					},
+				],
+				details: { entries: names },
+			};
+		},
+	};
+
+	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.",
+		...(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);
+
+			if (content === undefined) {
+				return {
+					content: [
+						{
+							type: "text",
+							text:
+								`Entry "${params.name}" not found.` +
+								`\n\nEntries:\n${formatEntryList(state) || "(empty)"}`,
+						},
+					],
+					details: { entries: names, found: false },
+				};
+			}
+
+			return {
+				content: [
+					{
+						type: "text",
+						text:
+							`--- ${params.name} ---\n${content}\n` +
+							`---\nEntries:\n${formatEntryList(state) || "(empty)"}`,
+					},
+				],
+				details: { entries: names, found: true },
+			};
+		},
+	};
+
+	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.",
+		...(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) || "(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);
+	}
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "pi-agenticoding",
+  "version": "0.1.0",
+  "description": "Context management primitives for the pi coding agent — spawn, ledger, handoff",
+  "license": "MIT",
+  "keywords": ["pi-package"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/earendil-works/pi-agenticoding.git"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  }
+}

package/spawn/index.ts

@@ -0,0 +1,487 @@
+/**
+ * Spawn tool for the agenticoding extension.
+ *
+ * Creates an isolated in-memory child AgentSession for focused subtask execution.
+ * Children inherit the parent's model, thinking level, cwd, and ledger access.
+ * Max nesting depth: 1 edge (parent → child only).
+ *
+ * Spawn is context isolation, not a security boundary. Child agents are trusted
+ * extensions of the parent and inherit parent authority by design.
+ */
+
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ToolDefinition,
+	ToolInfo,
+} from "@earendil-works/pi-coding-agent";
+import {
+	AuthStorage,
+	createAgentSession,
+	ModelRegistry,
+	SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import type { AgenticodingState } from "../state.js";
+import { formatEntryList } from "../ledger/store.js";
+import { createLedgerToolDefinitions } from "../ledger/tools.js";
+import {
+	renderSpawnCall,
+	renderSpawnResult,
+} from "./renderer.js";
+import {
+	getLastAssistantText,
+	type SpawnOutcome,
+	type SpawnResultDetails,
+	type ThinkingValue,
+} from "./shared.js";
+
+// ── Constants ─────────────────────────────────────────────────────────
+
+const MAX_SPAWN_DEPTH = 1;
+const CHILD_MAX_LINES = 2000;
+const CHILD_MAX_BYTES = 50 * 1024;
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+type AssistantMessageLike = {
+	role: string;
+	content?: { type: string; text?: string }[];
+	stopReason?: unknown;
+};
+
+function getLastAssistantMessage(messages: AssistantMessageLike[]): AssistantMessageLike | undefined {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "assistant") return msg;
+	}
+	return undefined;
+}
+
+function getLastAssistantOutcome(messages: AssistantMessageLike[]): SpawnOutcome {
+	const stopReason = getLastAssistantMessage(messages)?.stopReason;
+	if (stopReason === "aborted") return "aborted";
+	if (stopReason === "error") return "error";
+	return "success";
+}
+
+/**
+ * Truncates text to stay within maxLines/maxBytes.
+ * Line-count limit is applied first, then byte limit.
+ * May end mid-line if the byte limit is the tighter constraint.
+ */
+function truncateText(text: string, maxLines: number, maxBytes: number): string {
+	const lines = text.split("\n");
+	let truncated = lines.slice(0, maxLines).join("\n");
+	if (new TextEncoder().encode(truncated).length > maxBytes) {
+		truncated = new TextDecoder().decode(
+			new TextEncoder().encode(truncated).slice(0, maxBytes),
+		);
+	}
+	return truncated;
+}
+
+/**
+ * Truncates child agent output to CHILD_MAX_LINES lines / CHILD_MAX_BYTES bytes.
+ * Appends a "[Result truncated...]" advisory when truncation occurs.
+ * Returns { text, truncated }.
+ */
+function truncateResult(text: string): { text: string; truncated: boolean } {
+	const lines = text.split("\n");
+	const bytes = new TextEncoder().encode(text).length;
+
+	if (lines.length <= CHILD_MAX_LINES && bytes <= CHILD_MAX_BYTES) {
+		return { text, truncated: false };
+	}
+
+	const truncated = truncateText(text, CHILD_MAX_LINES, CHILD_MAX_BYTES);
+	return {
+		text:
+			truncated +
+			`\n\n[Result truncated to ${CHILD_MAX_LINES} lines / ${(CHILD_MAX_BYTES / 1024).toFixed(0)}KB. ` +
+			`Ask the child to summarize further if needed.]`,
+		truncated: true,
+	};
+}
+
+
+/**
+ * Build the final list of tool names for a child session.
+ *
+ * Child sessions inherit the parent's active built-in tools plus the local
+ * child custom tools defined here. Parent-only custom tools are intentionally
+ * excluded so the child never advertises a tool it cannot execute.
+ *
+ * handoff never carries into children, and spawn is only re-added from
+ * childTools when the current depth still allows nesting.
+ */
+function getInheritableParentToolNames(parentToolNames: string[], availableTools: Pick<ToolInfo, "name" | "sourceInfo">[]): string[] {
+	const activeToolNames = new Set(parentToolNames);
+	return availableTools
+		.filter((tool) => activeToolNames.has(tool.name) && tool.sourceInfo?.source === "builtin")
+		.map((tool) => tool.name);
+}
+
+export function buildChildToolNames(
+	parentToolNames: string[],
+	childTools: ToolDefinition[],
+	availableTools?: Pick<ToolInfo, "name" | "sourceInfo">[],
+): string[] {
+	const inheritableParentToolNames = availableTools
+		? getInheritableParentToolNames(parentToolNames, availableTools)
+		: parentToolNames;
+	const inheritedTools = inheritableParentToolNames.filter((name) => name !== "spawn" && name !== "handoff");
+	return [...new Set([...inheritedTools, ...childTools.map((tool) => tool.name)])];
+}
+
+// ── Shared spawn tool metadata (used by both parent and child tool definitions) ──
+
+const SPAWN_DESCRIPTION =
+	"Spawn an isolated child agent for a focused subtask. " +
+	"Child inherits parent model, thinking level, cwd, supported built-in tools, and shared ledger tools; spawn is only exposed when depth allows. " +
+	"Reference ledger entries by name — child will ledger_get them on demand.";
+
+const SPAWN_PROMPT_SNIPPET = "Spawn a focused subtask agent";
+
+const SPAWN_PROMPT_GUIDELINES = [
+	"Use spawn to delegate isolated work to child agents. They are trusted extensions of you with their own context and the same authority. Only condensed results are returned.",
+];
+
+const SPAWN_PARAMETERS = Type.Object({
+	prompt: Type.String({
+		description:
+			"Self-contained task description. Reference ledger entries by name — " +
+			"child will ledger_get them on demand.",
+	}),
+	thinking: StringEnum(
+		["off", "minimal", "low", "medium", "high", "xhigh"] as const,
+		{
+			description:
+				"Override child thinking level. Inherits parent by default.",
+		},
+	),
+});
+
+
+
+/**
+ * Build the custom tool set for child agent sessions.
+ *
+ * Produces ledger tools (add/get/list) and conditionally includes the spawn
+ * tool when currentDepth is below MAX_SPAWN_DEPTH. The spawn tool is omitted
+ * at max depth to prevent the LLM from attempting illegal recursion.
+ *
+ * All tools read/write the shared parent state so ledger entries are visible
+ * across parent and child contexts.
+ *
+ * @param sessionFactory - Test seam for dependency-injecting createAgentSession.
+ */
+export function createChildTools(
+	pi: ExtensionAPI,
+	state: AgenticodingState,
+	defaultThinking: ThinkingValue,
+	currentDepth: number,
+	sessionFactory: typeof createAgentSession = createAgentSession,
+	options?: { isStale?: () => boolean },
+): ToolDefinition[] {
+	// Child sessions inherit only executable parent tools via
+	// buildChildToolNames(). Only built-in parent tools are carried through.
+	// handoff never carries into children, and spawn is only re-added here
+	// while depth allows it.
+
+	const childSpawnTool: ToolDefinition = {
+		name: "spawn",
+		label: "Spawn",
+		description: SPAWN_DESCRIPTION,
+		promptSnippet: SPAWN_PROMPT_SNIPPET,
+		promptGuidelines: SPAWN_PROMPT_GUIDELINES,
+		parameters: SPAWN_PARAMETERS,
+		async execute(
+			toolCallId: string,
+			params: { prompt: string; thinking?: ThinkingValue },
+			signal: AbortSignal | undefined,
+			onUpdate:
+				| ((result: {
+						content: { type: string; text: string }[];
+						details?: unknown;
+				  }) => void)
+				| undefined,
+			ctx: ExtensionContext,
+		) {
+			return executeSpawn(toolCallId, pi, ctx, state, params, signal, onUpdate, defaultThinking, currentDepth, sessionFactory);
+		},
+		renderCall: renderSpawnCall,
+		renderResult(result, { expanded }, theme, context) {
+			return renderSpawnResult(result, expanded, theme, context, state);
+		},
+	};
+
+	const childLedgerTools = createLedgerToolDefinitions(pi, state, { isStale: options?.isStale });
+
+	return [
+		...(currentDepth < MAX_SPAWN_DEPTH ? [childSpawnTool] : []),
+		...childLedgerTools,
+	];
+}
+
+
+
+// ── Shared spawn execution logic ──────────────────────────────────────
+// Used by both the parent-registered spawn tool and child custom spawn tools.
+
+/**
+ * Creates an isolated child agent session, runs the given prompt, and returns
+ * the result with usage stats.
+ *
+ * Errors (all thrown, not returned):
+ *   - "Max spawn depth reached"          → currentDepth >= MAX_SPAWN_DEPTH
+ *   - "No model configured..."           → ctx.model is undefined
+ *   - "Child agent produced no output."  → no assistant text after prompt
+ *
+ * Side effects on state:
+ *   - state.childSessions.set(toolCallId, session) on creation
+ *   - state.liveChildSessions.set(toolCallId, session) on creation
+ *   - both registries delete(toolCallId) on error and completion paths
+ *
+ * @param onUpdate - Callback that fires once after session creation with
+ *   empty content + initial details (depth, model, thinking). Pi uses this
+ *   to render the component before the child produces output.
+ * @param sessionFactory - Test seam for mocking createAgentSession.
+ */
+export async function executeSpawn(
+	toolCallId: string,
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	state: AgenticodingState,
+	params: { prompt: string; thinking?: ThinkingValue },
+	signal: AbortSignal | undefined,
+	onUpdate:
+		| ((result: {
+				content: { type: string; text: string }[];
+				details?: unknown;
+		  }) => void)
+		| undefined,
+	defaultThinking: ThinkingValue,
+	currentDepth: number,
+	sessionFactory: typeof createAgentSession = createAgentSession,
+) {
+	if (currentDepth >= MAX_SPAWN_DEPTH) {
+		throw new Error(`Max spawn depth (${MAX_SPAWN_DEPTH}) reached. Cannot spawn further children.`);
+	}
+
+	const childModel = ctx.model;
+	if (!childModel) {
+		throw new Error("No model configured. Cannot spawn child agent.");
+	}
+
+	const childThinking: ThinkingValue = params.thinking ?? defaultThinking;
+	const depth = currentDepth + 1;
+
+	const listing = formatEntryList(state);
+	const ledgerListing = listing
+		? "Available ledger entries:\n" + listing
+		: "No ledger entries.";
+	const fullPrompt =
+		`You are a focused child agent spawned by a parent agent. ` +
+		`You have the same authority as the parent. ` +
+		`You inherit the parent's supported built-in tools plus shared ledger tools, and spawn is only exposed when depth allows it. ` +
+		`Your result will be read by the parent, so be concise and complete.\n\n` +
+		`${ledgerListing}\n\n` +
+		`## Task\n\n${params.prompt}\n\n` +
+		`When complete, provide a concise summary of findings. ` +
+		`Keep the result under ${CHILD_MAX_LINES} lines / ${(CHILD_MAX_BYTES / 1024).toFixed(0)}KB.`;
+
+	const authStorage = AuthStorage.create();
+	const modelRegistry = ModelRegistry.create(authStorage);
+	const childSessionEpoch = state.childSessionEpoch;
+	const isStale = () => state.childSessionEpoch !== childSessionEpoch;
+	const childTools = createChildTools(pi, state, childThinking, depth, sessionFactory, { isStale });
+	const parentToolNames = pi.getActiveTools();
+	const childToolNames = buildChildToolNames(parentToolNames, childTools, pi.getAllTools());
+
+	const { session } = await sessionFactory({
+		sessionManager: SessionManager.inMemory(),
+		model: childModel,
+		thinkingLevel: childThinking,
+		cwd: ctx.cwd,
+		tools: childToolNames,
+		customTools: childTools,
+		authStorage,
+		modelRegistry,
+	});
+
+	const invalidatedError = new Error("Spawn invalidated by reset.");
+	let wasAborted = false;
+	const abortChild = () => {
+		wasAborted = true;
+		session.abort().catch(e => console.error("[spawn] abort failed:", toolCallId, e));
+	};
+	const clearChildSession = () => {
+		if (state.childSessions.get(toolCallId) === session) {
+			state.childSessions.delete(toolCallId);
+		}
+		if (state.liveChildSessions.get(toolCallId) === session) {
+			state.liveChildSessions.delete(toolCallId);
+		}
+	};
+	const abortAndInvalidate = async () => {
+		clearChildSession();
+		await session.abort().catch(e => console.error("[spawn] abort failed:", toolCallId, e));
+		throw invalidatedError;
+	};
+
+	if (isStale()) {
+		await abortAndInvalidate();
+	}
+
+	// liveChildSessions must be set first — renderSpawnResult checks it to decide
+	// whether to pass the live registry to attachSession for stale detection.
+	state.liveChildSessions.set(toolCallId, session);
+	state.childSessions.set(toolCallId, session);
+
+	try {
+		if (signal?.aborted) {
+			wasAborted = true;
+			await session.abort();
+			throw signal.reason instanceof Error
+				? signal.reason
+				: new Error("Spawn aborted before child session started.");
+		}
+
+		if (isStale()) {
+			await abortAndInvalidate();
+		}
+
+		onUpdate?.({
+			content: [],
+			details: {
+				depth,
+				model: childModel.id,
+				thinking: childThinking,
+				truncated: false,
+				outcome: "running",
+			} satisfies SpawnResultDetails,
+		});
+
+		signal?.addEventListener("abort", abortChild, { once: true });
+		await session.prompt(fullPrompt);
+	} catch (error) {
+		clearChildSession();
+		if (isStale()) {
+			throw invalidatedError;
+		}
+		throw error;
+	} finally {
+		signal?.removeEventListener("abort", abortChild);
+	}
+
+	if (isStale()) {
+		clearChildSession();
+		throw invalidatedError;
+	}
+
+	const resultText = getLastAssistantText(session.messages);
+	if (!resultText) {
+		clearChildSession();
+		throw new Error("Child agent produced no output.");
+	}
+	const outcome = wasAborted ? "aborted" : getLastAssistantOutcome(session.messages);
+	const { text: finalText, truncated } = truncateResult(resultText);
+
+	// Execution should not retain live children after completion. If the TUI
+	// already rendered the child, it still owns the session object itself.
+	// Clearing here intentionally makes the component's dispose() a no-op for
+	// liveChildSessions — the child already completed so there's nothing to abort.
+	clearChildSession();
+
+	let stats: Record<string, number> | undefined;
+	let statsUnavailable = false;
+	try {
+		const sessionStats = session.getSessionStats();
+		if (sessionStats) {
+			stats = {
+				inputTokens: sessionStats.tokens?.input ?? 0,
+				outputTokens: sessionStats.tokens?.output ?? 0,
+				cacheReadTokens: sessionStats.tokens?.cacheRead ?? 0,
+				cacheWriteTokens: sessionStats.tokens?.cacheWrite ?? 0,
+				totalTokens: sessionStats.tokens?.total ?? 0,
+				cost: sessionStats.cost ?? 0,
+				turns: sessionStats.assistantMessages ?? 0,
+			};
+		}
+	} catch (error: unknown) {
+		statsUnavailable = true;
+		console.warn("[spawn] Failed to collect child session stats:", error, toolCallId);
+	}
+
+	if (isStale()) {
+		throw invalidatedError;
+	}
+
+	const details: SpawnResultDetails = {
+		depth,
+		model: childModel.id,
+		thinking: childThinking,
+		truncated,
+		outcome,
+	};
+	if (stats) {
+		details.stats = stats;
+	} else if (statsUnavailable) {
+		details.statsUnavailable = true;
+	}
+
+	return {
+		content: [{ type: "text" as const, text: finalText }],
+		details,
+	};
+}
+
+/**
+ * Register the spawn tool with pi's tool system.
+ *
+ * Creates a ToolDefinition that spawns an isolated child AgentSession
+ * for focused subtasks. Children inherit the parent model, thinking
+ * level, cwd, and ledger access.
+ *
+ * @param pi - Extension API instance for tool registration
+ * @param state - Shared session state (child sessions, epoch, ledger)
+ * @param sessionFactory - Optional test seam for mocking createAgentSession
+ */
+export function registerSpawnTool(
+	pi: ExtensionAPI,
+	state: AgenticodingState,
+	sessionFactory: typeof createAgentSession = createAgentSession,
+): void {
+	pi.registerTool({
+		name: "spawn",
+		label: "Spawn",
+		description: SPAWN_DESCRIPTION,
+		promptSnippet: SPAWN_PROMPT_SNIPPET,
+		promptGuidelines: SPAWN_PROMPT_GUIDELINES,
+		parameters: SPAWN_PARAMETERS,
+
+		async execute(
+			_toolCallId: string,
+			params: { prompt: string; thinking?: ThinkingValue },
+			signal: AbortSignal | undefined,
+			onUpdate:
+				| ((result: {
+						content: { type: string; text: string }[];
+						details?: unknown;
+				  }) => void)
+				| undefined,
+			ctx: ExtensionContext,
+		) {
+			const parentThinking: ThinkingValue = pi.getThinkingLevel();
+			return executeSpawn(_toolCallId, pi, ctx, state, params, signal, onUpdate, parentThinking, 0, sessionFactory);
+		},
+
+		renderCall: renderSpawnCall,
+
+		renderResult(result, { expanded }, theme, context) {
+			return renderSpawnResult(result, expanded, theme, context, state);
+		},
+	});
+}