one-code-extension 0.1.4 → 0.3.0

package/extensions/recap/index.ts

@@ -0,0 +1,215 @@
+/**
+ * recap extension — Claude Code's "while you were away" summary (the ※ line).
+ *
+ * CC fires it when the terminal has been blurred for 5 minutes; pi exposes no
+ * terminal focus/blur event, so the closest faithful trigger is an idle timer:
+ * armed when a turn ends, reset on any keystroke (onTerminalInput) and cleared
+ * while a turn runs, it fires after CC's 5-minute lull with no interaction. At
+ * most one recap per user turn (firedSinceTurn), matching CC's
+ * hasSummarySinceLastUserTurn guard.
+ *
+ * Generation mirrors CC's awaySummary.ts: a cheap same-containment model
+ * (pickEconomicalContainedModel — the getSmallFastModel analog), CC's verbatim
+ * prompt, and only the last 30 messages. It deliberately does NOT reuse the
+ * session prompt cache the way compaction does — CC makes a small standalone
+ * call here (skipCacheWrite). The result is a display-only entry (appendEntry,
+ * not in LLM context). Best-effort throughout: any failure just shows nothing.
+ *
+ * Deviations from CC, logged in docs/decisions: the session-memory block is
+ * omitted (decoupling), and name-only stubs of the active tools are sent
+ * rather than an empty tool list — some providers reject a history carrying
+ * tool_use blocks with no tools declared, and the small-token instruction keeps
+ * the model answering in text rather than calling one. A failed recap does not
+ * retry until the next turn (one attempt per turn, success or not). CC_RECAP=0
+ * opts out; CC_RECAP_IDLE_MS overrides the 5-minute delay.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { Api, Model, Tool } from "@earendil-works/pi-ai";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import { convertToLlm, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { withReasoningFallback } from "../lib/model-policy.ts";
+import { recordUsage } from "../lib/usage-bus.ts";
+import { pickEconomicalContainedModel } from "../lib/model-tier.ts";
+import { dimMarkedLine } from "../lib/tui-render.ts";
+import { RECAP_PROMPT, recapLine, recentForRecap, REFERENCE_MARK } from "./prompt.ts";
+import { RecapScheduler } from "./scheduler.ts";
+
+const ENTRY_TYPE = "one-code:recap";
+const DEFAULT_IDLE_MS = 5 * 60_000; // CC's BLUR_DELAY_MS
+const RECAP_MAX_TOKENS = 256; // 1-3 short sentences
+const RECAP_TIMEOUT_MS = 30_000;
+
+/** The idle delay before a recap, overridable via CC_RECAP_IDLE_MS (floor 1s). */
+function idleMs(): number {
+	const raw = Number(process.env.CC_RECAP_IDLE_MS);
+	return Number.isFinite(raw) && raw >= 1000 ? raw : DEFAULT_IDLE_MS;
+}
+
+interface RecapData {
+	content: string;
+}
+
+/**
+ * Name-only tool declarations: enough for a provider to accept the tool_use
+ * blocks already in the history, without the descriptions and schemas (the
+ * recap never calls a tool, and its prompt asks for text).
+ */
+export function toolStubs(names: readonly string[]): Tool[] {
+	return names.map(
+		(name) =>
+			({
+				name,
+				description: "Unavailable during this summary; answer in text.",
+				parameters: { type: "object", properties: {} },
+			}) as unknown as Tool,
+	);
+}
+
+export default function recapExtension(pi: ExtensionAPI) {
+	pi.registerEntryRenderer<RecapData>(ENTRY_TYPE, (entry, _options, theme) => {
+		const content = entry.data?.content;
+		if (!content) return undefined;
+		return dimMarkedLine(theme, REFERENCE_MARK, recapLine(content));
+	});
+
+	// The exact request messages the session last sent (after every extension's
+	// mutations), captured like the compaction extension does.
+	let capturedMessages: AgentMessage[] | undefined;
+	pi.on("context", (event) => {
+		capturedMessages = event.messages;
+	});
+
+	let lastCtx: ExtensionContext | undefined;
+	let inFlight: AbortController | undefined;
+	let inputHookRegistered = false;
+
+	const abortInFlight = () => {
+		inFlight?.abort();
+		inFlight = undefined;
+	};
+
+	const scheduler = new RecapScheduler(
+		{
+			set: (cb, ms) => {
+				const handle = setTimeout(cb, ms);
+				handle.unref?.();
+				return handle;
+			},
+			clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+		},
+		idleMs,
+		() => process.env.CC_RECAP !== "0",
+		() => void generate(),
+	);
+
+	async function generate() {
+		const ctx = lastCtx;
+		const messages = capturedMessages;
+		if (!ctx?.hasUI || !messages?.length || scheduler.hasFiredSinceTurn) return;
+		abortInFlight();
+		const controller = new AbortController();
+		inFlight = controller;
+		try {
+			const model = ctx.model;
+			if (!model) return;
+			const choice = pickEconomicalContainedModel(ctx.modelRegistry.getAvailable(), model);
+			if (!choice) return;
+			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(choice.model);
+			if (!auth.ok) return;
+			const baseUrl = (auth as { baseUrl?: string }).baseUrl;
+
+			// Name-only stubs of the active tools, so a history carrying tool_use
+			// blocks stays valid on strict providers (see the header note) without
+			// shipping every full schema (~6k tokens) to a call that must answer
+			// in text.
+			const tools = toolStubs(pi.getActiveTools());
+
+			const recent = recentForRecap(messages);
+			const recapMessages = [...convertToLlm(recent), { role: "user" as const, content: RECAP_PROMPT, timestamp: Date.now() }];
+			// Thinking off unless the model cannot disable it; withReasoningFallback
+			// sends a level up front for catalog-marked models and retries on the 400
+			// for the rest. Fires on a 5-min idle timer, so no cross-call memo.
+			const result = await withReasoningFallback(choice.model, (reasoning) => {
+				const timeout = AbortSignal.timeout(RECAP_TIMEOUT_MS);
+				return completeSimple(
+					baseUrl ? ({ ...choice.model, baseUrl } as Model<Api>) : choice.model,
+					{ systemPrompt: "", messages: recapMessages, tools },
+					{
+						apiKey: auth.apiKey,
+						headers: auth.headers,
+						env: auth.env,
+						signal: AbortSignal.any([controller.signal, timeout]),
+						maxTokens: RECAP_MAX_TOKENS,
+						...(reasoning ? { reasoning } : {}),
+					},
+				);
+			}, undefined, (usage) => recordUsage(pi, "recap", usage));
+			if (controller.signal.aborted) return;
+			const content = result.content
+				.filter((block): block is { type: "text"; text: string } => block.type === "text")
+				.map((block) => block.text)
+				.join("\n")
+				.trim();
+			if (!content) return;
+			scheduler.markFired();
+			pi.appendEntry<RecapData>(ENTRY_TYPE, { content });
+		} catch {
+			// Best-effort: a failed recap shows nothing — and does not retry. Without
+			// this the failure re-arms on every keystroke (interacted() → arm()),
+			// hammering the provider once per idle period until a turn resets it.
+			// An abort means a new turn or session already reset the scheduler; a
+			// late markFired there would suppress that turn's own recap.
+			if (!controller.signal.aborted) scheduler.markFired();
+		} finally {
+			if (inFlight === controller) inFlight = undefined;
+		}
+	}
+
+	pi.on("session_start", (_event, ctx) => {
+		lastCtx = ctx;
+		// A new session (including after /clear): drop any timer armed by the
+		// previous session and its captured messages, so a stale recap can never
+		// surface against the fresh conversation.
+		scheduler.reset();
+		abortInFlight();
+		capturedMessages = undefined;
+		if (!ctx.hasUI) return;
+		// Reset the idle clock on any keystroke — the closest signal to CC's
+		// terminal-blur trigger pi exposes. Registered ONCE (session_start fires
+		// again on every /clear and session switch, so an unguarded registration
+		// would leak a growing stack of listeners); the handler drives the
+		// scheduler, which reads only its own state.
+		if (inputHookRegistered) return;
+		inputHookRegistered = true;
+		ctx.ui.onTerminalInput(() => {
+			scheduler.interacted();
+			return undefined; // observe only; never consume the keystroke
+		});
+	});
+
+	pi.on("agent_start", (_event, ctx) => {
+		lastCtx = ctx;
+		scheduler.turnStarted();
+		abortInFlight();
+	});
+
+	// Settle, not agent_end: `agent_end` fires per run, and arming the idle
+	// timer there could fire a recap during a retry backoff longer than the
+	// configured idle (CC_RECAP_IDLE_MS floors at 1s), burning the
+	// one-per-turn budget mid-turn.
+	pi.on("agent_settled", (_event, ctx) => {
+		lastCtx = ctx;
+		// Unconditional: turnEnded() both clears turn state and arms the idle
+		// timer, so gating it on hasUI could leave turnRunning stuck true (and
+		// block all future re-arming) if a turn ever ends without UI. Arming
+		// without UI is harmless — generate() bails on !hasUI and the timer is
+		// unref'd, so a one-shot -p process exits before it can fire.
+		scheduler.turnEnded();
+	});
+
+	pi.on("session_shutdown", () => {
+		scheduler.reset();
+		abortInFlight();
+	});
+}

package/extensions/recap/prompt.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure pieces of Claude Code's "while you were away" recap (the ※ line CC shows
+ * when you come back after stepping away). Prompt text is verbatim from CC's
+ * services/awaySummary.ts; the display format matches CC's away_summary render
+ * (dim, led by the ※ reference mark). The session-memory block CC optionally
+ * prepends is omitted here (kept decoupled from One Code's memory extension).
+ */
+
+/** CC's REFERENCE_MARK (figures.ts) — the away-summary/recap marker. */
+export const REFERENCE_MARK = "※";
+
+/**
+ * Recap only needs recent context; CC truncates to the last 30 messages to
+ * avoid "prompt too long" on large sessions (≈15 exchanges — plenty for
+ * "where we left off").
+ */
+export const RECENT_MESSAGE_WINDOW = 30;
+
+/** The away-summary instruction, verbatim from CC's buildAwaySummaryPrompt (no memory block). */
+export const RECAP_PROMPT =
+	"The user stepped away and is coming back. Write exactly 1-3 short sentences. Start by stating the high-level task — what they are building or debugging, not implementation details. Next: the concrete next step. Skip status reports and commit recaps.";
+
+/** The transcript text after the ※ mark, matching CC's shipped "recap: …" line. */
+export function recapLine(content: string): string {
+	return `recap: ${content.trim()}`;
+}
+
+/**
+ * The recent-message window for the recap: the last `window` messages, trimmed
+ * forward to the first clean turn boundary — a `user` prompt or an `assistant`
+ * reply. A raw slice can begin mid-exchange with a leading tool-result message
+ * whose matching assistant tool_use fell outside the window; convertToLlm would
+ * then emit an orphan tool_result block that strict providers (e.g. Anthropic)
+ * reject, silently failing the recap. An assistant start is safe — its own tool
+ * results follow within the window. When the window holds no user/assistant
+ * message at all (e.g. one long tool-only stretch), nothing is safe to send, so
+ * it returns empty and the recap runs on the instruction alone. Generic over
+ * `{ role }` so it is testable with plain objects.
+ */
+export function recentForRecap<T extends { role: string }>(messages: readonly T[], window = RECENT_MESSAGE_WINDOW): T[] {
+	const tail = messages.slice(-window);
+	const start = tail.findIndex((message) => message.role === "user" || message.role === "assistant");
+	return start === -1 ? [] : tail.slice(start);
+}

package/extensions/recap/scheduler.ts

@@ -0,0 +1,87 @@
+/**
+ * Pure idle-timer state machine for the recap (no pi imports, so it is
+ * unit-tested directly; index.ts is thin wiring).
+ *
+ * The recap fires after a lull with no interaction following a turn — the
+ * closest faithful substitute for Claude Code's 5-minute terminal-blur trigger,
+ * which pi exposes no event for. The rules:
+ *   - armed when a turn ends, re-armed on any keystroke, cleared while a turn runs;
+ *   - at most one recap per user turn (CC's hasSummarySinceLastUserTurn guard);
+ *   - `reset()` drops a pending fire and all turn state, so a timer armed by a
+ *     previous session can never fire against a new one (after /clear).
+ *
+ * The clock is injected (`TimerOps`) so tests drive it deterministically; the
+ * async model call it triggers stays in the extension.
+ */
+
+export interface TimerOps {
+	/** Schedule `cb` after `ms`; return a handle for `clear`. */
+	set(cb: () => void, ms: number): unknown;
+	clear(handle: unknown): void;
+}
+
+export class RecapScheduler {
+	private turnRunning = false;
+	private firedSinceTurn = false;
+	private handle: unknown;
+
+	constructor(
+		private readonly timer: TimerOps,
+		/** The idle delay in ms, read at arm time. */
+		private readonly idleMs: () => number,
+		/** Whether the recap is enabled (e.g. CC_RECAP !== "0"). */
+		private readonly enabled: () => boolean,
+		/** Called when the idle timer elapses. */
+		private readonly onFire: () => void,
+	) {}
+
+	private clear(): void {
+		if (this.handle !== undefined) {
+			this.timer.clear(this.handle);
+			this.handle = undefined;
+		}
+	}
+
+	private arm(): void {
+		this.clear();
+		if (this.turnRunning || this.firedSinceTurn || !this.enabled()) return;
+		this.handle = this.timer.set(() => {
+			this.handle = undefined;
+			this.onFire();
+		}, this.idleMs());
+	}
+
+	/** A turn began: cancel any pending recap and allow a fresh one after it. */
+	turnStarted(): void {
+		this.turnRunning = true;
+		this.firedSinceTurn = false;
+		this.clear();
+	}
+
+	/** A turn ended: start the idle countdown. */
+	turnEnded(): void {
+		this.turnRunning = false;
+		this.arm();
+	}
+
+	/** Any interaction between turns resets the idle clock. */
+	interacted(): void {
+		if (!this.turnRunning) this.arm();
+	}
+
+	/** New session or shutdown: drop the pending fire and all turn state. */
+	reset(): void {
+		this.turnRunning = false;
+		this.firedSinceTurn = false;
+		this.clear();
+	}
+
+	/** A recap was emitted; suppress another until the next turn. */
+	markFired(): void {
+		this.firedSinceTurn = true;
+	}
+
+	get hasFiredSinceTurn(): boolean {
+		return this.firedSinceTurn;
+	}
+}

package/extensions/search-tools/tools.ts

@@ -9,13 +9,15 @@ import type { PromptTier } from "../lib/model-tier.ts";
 export const SEARCH_TOOLS = ["grep", "find", "ls"] as const;
 
 /**
- * Returns the active-tool list adjusted for the tier: mid/low gain the search
- * tools (deduped, appended in a stable order), frontier loses them (Claude
- * Code's frontier surface has no dedicated search tools). Order of the
- * existing names is preserved so the rebuilt system prompt stays byte-stable.
+ * Returns the active-tool list adjusted for the tier: only `tiny` gains the
+ * search tools (deduped, appended in a stable order); frontier/workhorse/cheap
+ * lose them. Claude Code ships no dedicated search tools on any tier (Haiku
+ * included — bash covers search), so `cheap` matches CC exactly; the grep/find/ls
+ * crutch is reserved for the sub-Haiku `tiny` models CC never serves. Order of
+ * the existing names is preserved so the rebuilt system prompt stays byte-stable.
  */
 export function withSearchTools(active: string[], tier: PromptTier): string[] {
-	if (tier === "frontier") {
+	if (tier !== "tiny") {
 		const drop = new Set<string>(SEARCH_TOOLS);
 		return active.filter((name) => !drop.has(name));
 	}