pi-agenticoding 0.1.0

package/handoff/command.ts

@@ -0,0 +1,36 @@
+/**
+ * /handoff command for the agenticoding extension.
+ *
+ * Collects a user direction, asks the LLM to complete the picture in a
+ * handoff brief, and lets the handoff tool perform the actual compaction.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgenticodingState } from "../state.js";
+
+export function registerHandoffCommand(pi: ExtensionAPI, state: AgenticodingState): void {
+	pi.registerCommand("handoff", {
+		description:
+			"Ask the LLM to draft a handoff brief that completes the picture from " +
+			"your direction, then perform the handoff automatically.",
+
+		handler: async (args, ctx) => {
+			const direction = args.trim();
+			if (!direction) {
+				if (ctx.hasUI) ctx.ui.notify("Usage: /handoff <direction>", "error");
+				return;
+			}
+
+			state.pendingRequestedHandoff = {
+				direction,
+				enforcementAttempts: 0,
+				toolCalled: false,
+			};
+
+			pi.sendUserMessage(
+				`Handoff direction: ${direction}\n\nPrepare a real handoff in the current session and current context. Before calling the handoff tool, capture any reusable state in the ledger if needed. Then complete the picture in a concise but sufficiently detailed handoff brief and call the handoff tool in this turn. Preserve the important knowledge that is still only present in the current context so the next clean context can start well without re-deriving it. Use any structure that makes the next work unambiguous. Include findings, current state, unresolved questions, failed paths worth avoiding, next steps, refs, constraints, and spawn ideas when useful. Reference ledger entries by name when relevant.`,
+				ctx.isIdle() ? undefined : { deliverAs: "followUp" },
+			);
+		},
+	});
+}

package/handoff/compact.ts

@@ -0,0 +1,35 @@
+/**
+ * session_before_compact hook for deliberate handoff compactions.
+ *
+ * Replaces the active context with the queued handoff task and keeps no
+ * pre-handoff messages in LLM context.
+ */
+
+import type { ExtensionAPI, SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { AgenticodingState } from "../state.js";
+
+function getImpossibleKeptId(branchEntries: SessionEntry[]): string {
+	const leaf = branchEntries[branchEntries.length - 1];
+	return `${leaf?.id ?? "handoff"}-handoff-cut`;
+}
+
+export function registerHandoffCompaction(pi: ExtensionAPI, state: AgenticodingState): void {
+	pi.on("session_before_compact", async (event) => {
+		const pending = state.pendingHandoff;
+		if (!pending) {
+			return;
+		}
+
+		state.pendingHandoff = null;
+		state.pendingRequestedHandoff = null;
+
+		return {
+			compaction: {
+				summary: pending.task,
+				firstKeptEntryId: getImpossibleKeptId(event.branchEntries),
+				tokensBefore: event.preparation.tokensBefore,
+				details: { handoff: true, task: pending.task },
+			},
+		};
+	});
+}

package/handoff/tool.ts

@@ -0,0 +1,151 @@
+/**
+ * Handoff tool for the agenticoding extension.
+ *
+ * Tools can trigger compaction directly, so handoff is implemented as a
+ * deliberate compaction that replaces noisy context with a clean restart brief.
+ *
+ * The brief should complete the picture: preserve the important knowledge that
+ * is still only present in the current context, while referenced ledger entry
+ * bodies seed the post-handoff context immediately.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { AgenticodingState } from "../state.js";
+
+const MAX_INLINE_ENTRIES = 3;
+const MAX_INLINE_CHARS = 4000;
+
+/**
+ * Extract names of existing ledger entries referenced in the task text.
+ * Returns up to MAX_INLINE_ENTRIES entries with their full bodies,
+ * capped at MAX_INLINE_CHARS total.
+ */
+function extractReferencedLedgerEntries(
+	task: string,
+	state: AgenticodingState,
+): { name: string; body: string }[] {
+	const entryNames = Array.from(state.ledger.keys()).sort();
+	const matched: { name: string; body: string }[] = [];
+	const seen = new Set<string>();
+	let totalChars = 0;
+
+	for (const name of entryNames) {
+		if (task.includes(name) && !seen.has(name)) {
+			const body = state.ledger.get(name);
+			if (body) {
+				const chars = body.length;
+				if (totalChars + chars <= MAX_INLINE_CHARS && matched.length < MAX_INLINE_ENTRIES) {
+					matched.push({ name, body });
+					seen.add(name);
+					totalChars += chars;
+				}
+			}
+		}
+	}
+
+	return matched;
+}
+
+/**
+ * Build the enriched task that becomes the compaction summary.
+ *
+ * Shape: handoff primer + inlined ledger bodies + original task.
+ */
+function buildEnrichedTask(
+	task: string,
+	state: AgenticodingState,
+): string {
+	const refs = extractReferencedLedgerEntries(task, state);
+
+	const parts: string[] = [
+		"## Handoff — Continue Previous Work",
+		"",
+		"You are continuing a previous agent's work in a clean context. Available knowledge:",
+		"- Use `ledger_get` to retrieve detailed entries by name on demand",
+		"- Use `spawn` to delegate isolated subtasks to child agents",
+		"- Build on ledger knowledge and the handoff brief rather than reconstructing old context",
+		"- Treat the handoff brief as the missing picture that survived the cut",
+	];
+
+	if (refs.length > 0) {
+		parts.push("", "### Inlined Ledger Context");
+		for (const { name, body } of refs) {
+			parts.push("", `Ledger: \`${name}\``, body, "---");
+		}
+	}
+
+	parts.push("", "## Task", "", task);
+
+	return parts.join("\n");
+}
+
+export function registerHandoffTool(
+	pi: ExtensionAPI,
+	state: AgenticodingState,
+): void {
+	pi.registerTool({
+		name: "handoff",
+		label: "Handoff",
+		description:
+			"Replace the active context with a compact handoff task at the end of " +
+			"the current turn while keeping full history in the session file.\n\n" +
+			"WHEN TO USE:\n" +
+			"  1. Context past ~30% and the current job is no longer cleanly " +
+			"represented near the front of attention.\n" +
+			"  2. Context is filled with mechanics irrelevant to what comes " +
+			"next (research traces, planning deliberation, dead ends).\n" +
+			"  3. The current job is complete and a new distinct task starts.\n\n" +
+			"Rule: one context, one job. When the job changes, call handoff.\n\n" +
+			"AFTER HANDOFF the LLM sees:\n" +
+			"  • System prompt + context primer\n" +
+			"  • The handoff task — as a compaction summary at the top of context\n" +
+			"  • All ledger entries — accessible via ledger_get / ledger_list",
+
+		promptSnippet: "Pivot to a new job via deliberate handoff compaction",
+		promptGuidelines: [
+			"Call handoff when the job changes, or when context is past ~30% and noisy. " +
+				"Capture reusable state in the ledger if needed, then draft a concise but " +
+				"sufficiently detailed brief that completes the picture for the next clean context.",
+		],
+
+		executionMode: "sequential",
+
+		parameters: Type.Object({
+			task: Type.String({
+				description:
+					"What to do next. A concise but sufficiently detailed handoff brief. " +
+					"This becomes the FIRST thing the LLM sees after handoff. Complete the " +
+					"picture by preserving the important knowledge still missing from the ledger, " +
+					"then make the next work unambiguous using any structure you want.",
+			}),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const enrichedTask = buildEnrichedTask(params.task, state);
+			state.pendingHandoff = { task: enrichedTask, source: "tool" };
+			if (state.pendingRequestedHandoff) {
+				state.pendingRequestedHandoff.toolCalled = true;
+			}
+			ctx.compact({
+				onComplete: () => {
+					pi.sendUserMessage("Proceed.");
+				},
+				onError: () => {
+					state.pendingHandoff = null;
+					// Safe: pendingRequestedHandoff may already be cleaned up by watchdog
+					if (state.pendingRequestedHandoff) {
+						state.pendingRequestedHandoff.toolCalled = false;
+					}
+				},
+			});
+
+			return {
+				content: [{ type: "text", text: "Handoff started." }],
+				details: {},
+				terminate: true,
+			};
+		},
+
+	});
+}

package/index.ts

@@ -0,0 +1,149 @@
+/**
+ * Agenticoding v2 — Extension factory.
+ *
+ * Wires together the three primitives:
+ *   spawn     — delegate isolated work to child contexts
+ *   ledger    — sparse continuity cache
+ *   handoff   — deliberate task pivot via compaction
+ *
+ * Also registers:
+ *   - watchdog (advisory primacy-zone reminder after each turn)
+ *   - system prompt injection (CONTEXT_PRIMER, nudge, ledger listing)
+ *   - state reset on /new
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createState, resetState, type AgenticodingState } from "./state.js";
+import { CONTEXT_PRIMER } from "./system-prompt.js";
+import { buildNudge, registerWatchdog } from "./watchdog.js";
+import { registerLedgerTools } from "./ledger/tools.js";
+import { registerLedgerRehydration } from "./ledger/rehydration.js";
+import { registerHandoffTool } from "./handoff/tool.js";
+import { registerHandoffCommand } from "./handoff/command.js";
+import { registerHandoffCompaction } from "./handoff/compact.js";
+import { registerSpawnTool } from "./spawn/index.js";
+
+/** Build a status bar preview from ledger entries. */
+function formatLedgerPreview(state: AgenticodingState): string {
+	const names = Array.from(state.ledger.keys()).sort();
+	if (names.length === 0) return "(empty)";
+	return names
+		.map((name) => {
+			const content = state.ledger.get(name)!;
+			const firstLine = (content.split("\n")[0] ?? "").slice(0, 60);
+			return `${name}: ${firstLine}`;
+		})
+		.join("\n");
+}
+
+/** Update TUI indicators: context usage + ledger count. */
+function updateIndicators(ctx: ExtensionContext, state: AgenticodingState): void {
+	if (!ctx.hasUI) return;
+
+	const theme = ctx.ui.theme;
+
+	// Context usage
+	const usage = ctx.getContextUsage();
+	if (usage && usage.percent !== null) {
+		const pct = Math.round(usage.percent);
+		const tone = pct >= 70 ? "error" : pct >= 50 ? "warning" : pct >= 30 ? "accent" : "dim";
+		ctx.ui.setStatus("agenticoding-ctx", theme.fg("dim", "ctx ") + theme.fg(tone, `${pct}%`));
+	} else {
+		ctx.ui.setStatus("agenticoding-ctx", theme.fg("dim", "ctx --%"));
+	}
+
+	// Ledger count
+	const count = state.ledger.size;
+	ctx.ui.setStatus("agenticoding-ledger", count > 0 ? `\u{1F4D2} ${count}` : "");
+}
+
+export default function (pi: ExtensionAPI): void {
+	const state: AgenticodingState = createState();
+
+	// ── Register all tools ──────────────────────────────────────────
+	registerLedgerTools(pi, state);
+	registerHandoffTool(pi, state);
+	registerSpawnTool(pi, state);
+
+	// ── Register event handlers ─────────────────────────────────────
+	registerWatchdog(pi, state);
+	registerLedgerRehydration(pi, state);
+	registerHandoffCompaction(pi, state);
+
+	// ── Register commands ───────────────────────────────────────────
+	registerHandoffCommand(pi, state);
+
+	// ── /ledger command — show entries in overlay ───────────────────
+	pi.registerCommand("ledger", {
+		description: "Show ledger entries with name, line count, and first-line preview",
+		handler: async (_args, ctx) => {
+			const preview = formatLedgerPreview(state);
+			ctx.ui.notify(`Ledger (${state.ledger.size} entries):\n${preview}`, "info");
+		},
+	});
+
+	// ── before_agent_start: inject context primer + ledger ─────────
+	pi.on("before_agent_start", async (event, ctx: ExtensionContext) => {
+		// Update TUI indicators before each user-prompt agent run
+		updateIndicators(ctx, state);
+
+		const parts: string[] = [event.systemPrompt];
+
+		// Inject context management primer at the end of the system prompt
+		parts.push("\n" + CONTEXT_PRIMER);
+
+		// Inject ledger listing so the LLM always knows what's available
+		const entryNames = Array.from(state.ledger.keys()).sort();
+		if (entryNames.length > 0) {
+			const listing = entryNames
+				.map((name) => {
+					const content = state.ledger.get(name)!;
+					const firstLine = (content.split("\n")[0] ?? "").slice(0, 80);
+					return `  ${name}: ${firstLine}`;
+				})
+				.join("\n");
+			parts.push(
+				`\n## Active Ledger Entries\n` +
+					`The following entries are available via ledger_get by name:\n${listing}\n` +
+					`Reference entries by name — never paste bodies into prompts.`,
+			);
+		}
+
+		return { systemPrompt: parts.join("\n\n") };
+	});
+
+	// ── context: inject primacy-zone nudge before each LLM call ────
+	pi.on("context", async (event, ctx: ExtensionContext) => {
+		const usage = ctx.getContextUsage();
+		if (!usage || usage.percent === null || usage.percent < 30) {
+			return;
+		}
+
+		state.lastContextPercent = usage.percent;
+		return {
+			messages: [
+				...event.messages,
+				{
+					role: "custom",
+					customType: "agenticoding-watchdog",
+					content: buildNudge(usage.percent),
+					display: false,
+					timestamp: Date.now(),
+				},
+			],
+		};
+	});
+
+	// ── session_start: reset state + update indicators ─────────────
+	pi.on("session_start", async (event, ctx: ExtensionContext) => {
+		if (event.reason === "new") {
+			resetState(state);
+		}
+		updateIndicators(ctx, state);
+	});
+
+	// ── update TUI indicators after each turn ───────────────────────
+	pi.on("turn_end", async (_event, ctx: ExtensionContext) => {
+		updateIndicators(ctx, state);
+	});
+}

package/ledger/rehydration.ts

@@ -0,0 +1,94 @@
+/**
+ * Ledger rehydration for the agenticoding extension.
+ *
+ * A session_start handler that scans the current branch newest-to-oldest for
+ * persisted ledger-entry custom entries, rebuilds the in-memory state.ledger
+ * Map (newest wins per name), and ensures ledger_get / ledger_list are active.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgenticodingState } from "../state.js";
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+interface LedgerEntryData {
+	version: number;
+	epoch: number;
+	name: string;
+	content: string;
+}
+
+interface LedgerCandidate {
+	epoch: number;
+	content: string;
+}
+
+// ── Registration ──────────────────────────────────────────────────────
+
+export function registerLedgerRehydration(
+	pi: ExtensionAPI,
+	state: AgenticodingState,
+): void {
+	pi.on("session_start", async (_event, ctx) => {
+		const branch = ctx.sessionManager.getBranch();
+
+		// Scan newest-to-oldest; first occurrence of each name wins (newest).
+		const candidates = new Map<string, LedgerCandidate>();
+
+		for (let i = branch.length - 1; i >= 0; i--) {
+			const entry = branch[i];
+
+			if (
+				entry.type !== "custom" ||
+				(entry as Record<string, unknown>).customType !== "ledger-entry"
+			) {
+				continue;
+			}
+
+			const data = (entry as Record<string, unknown>).data as LedgerEntryData | undefined;
+			if (!data?.name || typeof data.content !== "string") continue;
+
+			// Skip if we already have a newer version of this name
+			if (candidates.has(data.name)) continue;
+
+			candidates.set(data.name, {
+				epoch: data.epoch,
+				content: data.content,
+			});
+		}
+
+		if (candidates.size === 0) return;
+
+		// Determine the current epoch from candidates.
+		// If state.epoch is already set (e.g., from first add before rehydration),
+		// filter to entries matching that epoch. Otherwise adopt the max epoch found.
+		let currentEpoch = state.epoch;
+		if (currentEpoch === 0) {
+			for (const [, c] of candidates) {
+				if (c.epoch > currentEpoch) currentEpoch = c.epoch;
+			}
+			state.epoch = currentEpoch;
+		}
+
+		// Rebuild state.ledger, filtering by epoch
+		state.ledger.clear();
+		for (const [name, candidate] of candidates) {
+			if (candidate.epoch === currentEpoch) {
+				state.ledger.set(name, candidate.content);
+			}
+		}
+
+		// Ensure ledger_get and ledger_list are active so the LLM can fetch entries
+		const active = pi.getActiveTools();
+		let changed = false;
+		if (!active.includes("ledger_get")) {
+			active.push("ledger_get");
+			changed = true;
+		}
+		if (!active.includes("ledger_list")) {
+			active.push("ledger_list");
+			changed = true;
+		}
+		if (changed) pi.setActiveTools(active);
+	});
+}

package/ledger/store.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared ledger storage helpers.
+ *
+ * Keeps parent and spawned-child ledger writes on the same persistence path.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import type { AgenticodingState } from "../state.js";
+
+let writeLock: Promise<void> = Promise.resolve();
+
+async function acquireWriteLock(): Promise<() => void> {
+	let release: () => void;
+	const prev = writeLock;
+	writeLock = new Promise<void>((resolve) => {
+		release = resolve;
+	});
+	await prev;
+	return release!;
+}
+
+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 "";
+
+	return names
+		.map((name) => {
+			const content = state.ledger.get(name)!;
+			const firstLine = content.split("\n")[0] ?? "";
+			const preview =
+				firstLine.length > PREVIEW_MAX_CHARS
+					? firstLine.slice(0, PREVIEW_MAX_CHARS - ELLIPSIS_LENGTH) + "..."
+					: firstLine;
+			return `  ${name}: ${preview}`;
+		})
+		.join("\n");
+}
+
+export async function saveLedgerEntry(
+	pi: ExtensionAPI,
+	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,
+		});
+
+		if (state.epoch === 0) {
+			state.epoch = Date.now();
+		}
+
+		state.ledger.set(name, truncated.content);
+		pi.appendEntry("ledger-entry", {
+			version: 1,
+			epoch: state.epoch,
+			name,
+			content: truncated.content,
+		});
+
+		return getEntryNames(state);
+	} finally {
+		release();
+	}
+}