pi-agenticoding 0.1.0

package/spawn/shared.ts

@@ -0,0 +1,34 @@
+export type ThinkingValue = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+export type SpawnOutcome = "running" | "success" | "aborted" | "error";
+
+export type SpawnResultDetails = {
+	depth: number;
+	model: string;
+	thinking: ThinkingValue;
+	truncated: boolean;
+	outcome: SpawnOutcome;
+	stats?: Record<string, number>;
+	statsUnavailable?: boolean;
+};
+
+type AssistantMessageLike = {
+	role: string;
+	content?: { type: string; text?: string }[];
+};
+
+/**
+ * Returns all text blocks from the last assistant message, joined by newlines.
+ */
+export function getLastAssistantText(messages: AssistantMessageLike[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role !== "assistant") continue;
+		const text = (msg.content ?? [])
+			.filter((block) => block.type === "text" && typeof block.text === "string")
+			.map((block) => block.text ?? "")
+			.join("\n")
+			.trim();
+		if (text) return text;
+	}
+	return "";
+}

package/state.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared mutable state for the agenticoding extension.
+ *
+ * Single source of truth that all modules read/write through.
+ * Mutable by design — this is session-scoped imperative state.
+ */
+
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+
+export interface AgenticodingState {
+	/** Compact ledger entries keyed by kebab-case name */
+	ledger: Map<string, string>;
+
+	/** Monotonically increasing epoch, set on first ledger_add */
+	epoch: number;
+
+	/** Last context usage percent from getContextUsage() */
+	lastContextPercent: number | null;
+
+	/** Handoff task queued by the tool until the compaction hook consumes it. */
+	pendingHandoff: { task: string; source: "tool" } | null;
+
+	/** User-requested handoff that must result in a real tool-driven compaction. */
+	pendingRequestedHandoff: {
+		direction: string;
+		enforcementAttempts: number;
+		toolCalled: boolean;
+	} | null;
+
+	/**
+	 * Published child agent sessions keyed by toolCallId.
+	 * Lifecycle: executeSpawn publishes → renderSpawnResult claims via get+delete.
+	 * This is only the render handoff queue, not the full live-session registry.
+	 */
+	childSessions: Map<string, AgentSession>;
+
+	/**
+	 * All live child agent sessions keyed by toolCallId, including claimed ones.
+	 * Reset/teardown aborts this registry so claimed children cannot outlive /new or UI disposal.
+	 *
+	 * INVARIANT: This Map is never replaced — only cleared via .clear().
+	 * NestedAgentSessionComponent holds a direct reference and depends on it
+	 * staying valid. If you change this, update attachSession in spawn/renderer.ts.
+	 */
+	liveChildSessions: Map<string, AgentSession>;
+
+	/**
+	 * Generation counter for child-session ownership.
+	 * Increment on /new so stale child updates/results cannot touch fresh state.
+	 */
+	childSessionEpoch: number;
+}
+
+/** Create a fresh state instance. Call reset() on /new. */
+export function createState(): AgenticodingState {
+	const childSessions = new Map<string, AgentSession>();
+	const liveChildSessions = new Map<string, AgentSession>();
+	const state: AgenticodingState = {
+		ledger: new Map(),
+		epoch: 0,
+		lastContextPercent: null,
+		pendingHandoff: null,
+		pendingRequestedHandoff: null,
+		childSessions,
+		liveChildSessions,
+		childSessionEpoch: 0,
+	};
+	// Prevent replacement — NestedAgentSessionComponent holds direct references
+	// to both maps and depends on reference stability. Only .clear() and .delete()
+	// are valid — assigning a new Map would silently break session lifecycle.
+	Object.defineProperty(state, 'childSessions', {
+		get: () => childSessions,
+		set: () => { throw new Error('childSessions cannot be replaced — use .clear() instead'); },
+		enumerable: true,
+		configurable: false,
+	});
+	Object.defineProperty(state, 'liveChildSessions', {
+		get: () => liveChildSessions,
+		set: () => { throw new Error('liveChildSessions cannot be replaced — use .clear() instead'); },
+		enumerable: true,
+		configurable: false,
+	});
+	return state;
+}
+
+/** Reset all state. Used on /new or session reset. */
+export function resetState(state: AgenticodingState): void {
+	state.childSessionEpoch++;
+	state.ledger.clear();
+	state.epoch = 0;
+	state.lastContextPercent = null;
+	state.pendingHandoff = null;
+	state.pendingRequestedHandoff = null;
+	abortAndClearChildSessions(state);
+}
+
+/** Abort all active child sessions and clear both registries. Called on /new (session reset). */
+export function abortAndClearChildSessions(state: AgenticodingState): void {
+	const seen = new Map<any, string>(); // session → first id (for logging)
+	for (const [id, session] of [...state.childSessions.entries(), ...state.liveChildSessions.entries()]) {
+		if (!seen.has(session)) seen.set(session, id);
+	}
+	state.childSessions.clear();
+	state.liveChildSessions.clear();
+	for (const [session, id] of seen) {
+		session.abort().catch(e => console.warn("[spawn] abort failed:", id, e));
+	}
+}

package/system-prompt.ts

@@ -0,0 +1,59 @@
+/**
+ * Context management system prompt primer.
+ *
+ * Injected via before_agent_start into the system prompt.
+ * Teaches the LLM about spawn, ledger, and handoff primitives.
+ */
+
+export const CONTEXT_PRIMER = `
+## Context management
+
+One context, one job. Research is one job. Planning is one job. Execution
+is one job. When the job changes, call the handoff tool.
+
+### The primacy-zone heuristic
+You use long context unevenly. Performance can degrade as context grows —
+even far from the window limit. Treat the first ~30% as a practical heuristic
+for keeping the current job near the front of attention. The system tells you
+exact context usage after each turn, and watchdog reminders may be injected
+before LLM calls when context is past the heuristic. Watchdog reminders are
+advisory only.
+
+### Spawn — isolate noise
+Delegate isolated work to child agents. They are trusted extensions of you,
+with their own context and the same authority. You receive only condensed
+results. Parent context stays at orchestration level. Siblings run in parallel.
+
+### Ledger — sparse continuity cache
+Continuously maintain the ledger while you work. After meaningful reads,
+research, analysis, decisions, or milestones, either update/refine a ledger
+entry now or consciously skip because nothing reusable was learned. Prefer
+refining existing entries over creating many tiny ones. The current ledger
+listing is available above. Reference entries by name; fetch via ledger_get on
+demand. Never pre-load bodies.
+
+### Handoff — complete the picture, then continue cleanly
+When the job changes, or when context is noisy past the ~30% heuristic, use
+handoff to finish extracting what matters from the current context before the
+cut. Save reusable state to the ledger when useful, then draft a handoff brief
+that preserves the important knowledge still missing from the ledger.
+Handoff compacts the active session around that brief so the next turn starts
+in a clean context with the right picture already in view. Full history remains
+in the session file for the user.
+
+Use any structure that keeps the next work unambiguous. Include the current
+state, important findings, unresolved questions, failed paths worth avoiding,
+next steps, refs, constraints, and spawn ideas when useful. The handoff should
+help the next context start well without re-deriving what you already learned.
+
+### Rules
+- Maintain the ledger as a constant working process; do not wait for handoff
+- Cache reusable state in the ledger; handoff should also capture the missing context that has not been recorded yet
+- Prefer refining existing entries over creating many tiny ones
+- After meaningful work, either update/refine the ledger or intentionally skip
+- Reference ledger entries by name when useful; fetch bodies on demand
+- Use spawn to delegate isolated subtasks when it helps; parent orchestrates and merges results
+- Call handoff at job boundaries: research→execution, planning→execution
+- Past ~30%, consider handoff when the phase is done or context noise is hurting focus
+- After handoff, ledger_get entries as needed — not all at once
+`.trim();

package/test-loader.mjs

@@ -0,0 +1,32 @@
+import { access } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import path from "node:path";
+
+const PACKAGE_ROOT = "/Users/ofri/.nvm/versions/node/v24.14.1/lib/node_modules/@earendil-works/pi-coding-agent";
+const PACKAGE_ALIASES = {
+	"@earendil-works/pi-coding-agent": `${PACKAGE_ROOT}/dist/index.js`,
+	"@earendil-works/pi-ai": `${PACKAGE_ROOT}/node_modules/@earendil-works/pi-ai/dist/index.js`,
+	"@earendil-works/pi-tui": `${PACKAGE_ROOT}/node_modules/@earendil-works/pi-tui/dist/index.js`,
+	"@earendil-works/pi-agent-core": `${PACKAGE_ROOT}/node_modules/@earendil-works/pi-agent-core/dist/index.js`,
+	typebox: `${PACKAGE_ROOT}/node_modules/typebox/build/index.mjs`,
+};
+
+export async function resolve(specifier, context, defaultResolve) {
+	const packagePath = PACKAGE_ALIASES[specifier];
+	if (packagePath) {
+		return defaultResolve(pathToFileURL(packagePath).href, context, defaultResolve);
+	}
+
+	if ((specifier.startsWith("./") || specifier.startsWith("../")) && specifier.endsWith(".js") && context.parentURL) {
+		const parentPath = fileURLToPath(context.parentURL);
+		const tsPath = path.resolve(path.dirname(parentPath), specifier.slice(0, -3) + ".ts");
+		try {
+			await access(tsPath);
+			return defaultResolve(pathToFileURL(tsPath).href, context, defaultResolve);
+		} catch {
+			// fall through
+		}
+	}
+
+	return defaultResolve(specifier, context, defaultResolve);
+}

package/watchdog.ts

@@ -0,0 +1,65 @@
+/**
+ * Watchdog: advisory primacy-zone reminder.
+ *
+ * Exposes nudge text generation and records the latest context usage at
+ * `agent_end` for UI/state purposes. Actual reminder injection happens in the
+ * `context` hook so it can appear before every LLM call in the same agent run.
+ *
+ * Never force-disengages — the watchdog is advisory only.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgenticodingState } from "./state.js";
+
+/** Build a nudge string with the exact percent interpolated. */
+export function buildNudge(percent: number): string {
+	const pct = Math.round(percent);
+
+	if (pct >= 70) {
+		return `Context at ${pct}% — deep in the degraded zone. Compaction may trigger soon
+(emergency summarization at ~90%). Prefer a deliberate handoff now: save
+reusable state to the ledger, draft a clear next-task brief, and call handoff.`;
+	}
+
+	if (pct >= 50) {
+		return `Context at ${pct}% — well past the primacy-zone heuristic. If the current job is
+done or the context is noisy, consider a handoff soon. Save reusable state to
+the ledger and draft a concise but sufficiently detailed brief for what comes
+next.`;
+	}
+
+	// 30-50%
+	return `Context at ${pct}% — past the primacy-zone heuristic. One context, one job.
+If you're mid-job and still clear, continue. If the current phase is complete
+or the context is noisy, consider a handoff and draft a clear brief for what
+comes next.`;
+}
+
+/**
+ * Register the watchdog's `agent_end` handler.
+ *
+ * Must be called from the extension factory in index.ts after state creation.
+ */
+export function registerWatchdog(pi: ExtensionAPI, state: AgenticodingState): void {
+	pi.on("agent_end", async (_event: unknown, ctx: ExtensionContext) => {
+		const requestedHandoff = state.pendingRequestedHandoff;
+		if (requestedHandoff) {
+			requestedHandoff.enforcementAttempts += 1;
+			if (!requestedHandoff.toolCalled) {
+				state.pendingRequestedHandoff = null;
+			}
+		}
+
+		// ── Primacy-zone nudge ──────────────────────────────────────
+		const usage = ctx.getContextUsage();
+
+		// Null usage / null percent — right after compaction, before next LLM response.
+		if (!usage || usage.percent === null) {
+			state.lastContextPercent = null;
+			return;
+		}
+
+		state.lastContextPercent = usage.percent;
+
+	});
+}