one-code-extension 0.1.3 → 0.3.0

package/extensions/tool-search/index.ts

@@ -28,17 +28,51 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import {
 	DEFER_CHANNEL,
-	deferredRegistry,
+	deferredAddendumText,
+	deferredMissReminderText,
+	DeferredRegistry,
 	deferredReminderText,
 	type DeferRequest,
+	resultText,
 	searchTools,
 	selectedNames,
+	supportsToolReferences,
+	toolNotFoundName,
+	withDeferredToolDefinitions,
 } from "../lib/deferred.ts";
+import { looksLikeAnthropicRequest } from "../lib/anthropic-payload.ts";
+import { MCP_TOOLS_CHANNEL, type McpToolsPayload } from "../lib/mcp-share.ts";
 import { CONTEXT_ORDER, REMINDER_CHANNEL } from "../lib/reminders.ts";
+import { sessionAlive } from "../lib/session-lifecycle.ts";
 import { ccToolRenderers } from "../lib/tui-render.ts";
+import { normalizeToolName } from "../permissions/matcher.ts";
+import { applyAnnouncement, planAnnouncement } from "./announce.ts";
+
+/** Coalesces the burst of per-tool defers one server emits into one listing update. */
+const ANNOUNCE_DEBOUNCE_MS = 100;
 
 export default function toolSearchExtension(pi: ExtensionAPI) {
+	// Owned here (see lib/deferred.ts): the only instance, fed over DEFER_CHANNEL.
+	const deferredRegistry = new DeferredRegistry();
 	let sessionStarted = false;
+	// The deferred-tools listing is a first-prepend reminder on message 1, part of
+	// the cached prefix of every later request. Before the first request nothing
+	// is cached, so the listing is (re)written freely; after it the listing is
+	// FROZEN and later arrivals ride a one-shot addendum where the model reads
+	// next (./announce.ts — a rewrite re-cached 16.7k tokens of history on
+	// request 2 of every run whose MCP tools registered inside the debounce,
+	// measured 2026-09-04). While the initial MCP connect is still settling the
+	// addendum waits for settle, so one burst of per-tool defers is one notice.
+	let requestSent = false;
+	let mcpSettled = false;
+	let announcePending = false;
+	let announceTimer: NodeJS.Timeout | undefined;
+	// After session_shutdown every pi.* call throws (the runner is invalidated,
+	// findings §8); a debounced announce landing in a timer callback then would
+	// be an uncaught exception and take pi down (LIFECYCLE-REVIEW L1).
+	const alive = sessionAlive(pi);
+	/** Names the model has been told about: the frozen listing plus every addendum. */
+	const announced = new Set<string>();
 
 	const searchableTools = () =>
 		pi
@@ -50,18 +84,74 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 				keywords: deferredRegistry.keywordsFor(tool.name),
 			}));
 
-	const announceDeferred = () => {
+	const announce = () => {
+		if (!alive()) return;
 		const available = searchableTools();
-		if (available.length === 0) return;
-		pi.events.emit(REMINDER_CHANNEL, {
-			scope: "every-turn",
-			key: "deferred-tools",
-			text: deferredReminderText(available),
-			placement: "first-prepend",
-			order: CONTEXT_ORDER.deferredTools,
-		});
+		const plan = planAnnouncement({ requestSent, announced, available: available.map((t) => t.name) });
+		if (plan.kind === "rewrite") {
+			pi.events.emit(REMINDER_CHANNEL, {
+				scope: "every-turn",
+				key: "deferred-tools",
+				text: deferredReminderText(available),
+				placement: "first-prepend",
+				order: CONTEXT_ORDER.deferredTools,
+			});
+		} else if (plan.kind === "addendum") {
+			// Unkeyed on purpose: a keyed next-turn reminder replaces its
+			// predecessor, and an addendum replaced before delivery would lose names.
+			pi.events.emit(REMINDER_CHANNEL, { text: deferredAddendumText(plan.added) });
+		}
+		applyAnnouncement(announced, plan);
+	};
+
+	const clearAnnounce = () => {
+		if (announceTimer) clearTimeout(announceTimer);
+		announceTimer = undefined;
+	};
+	const scheduleAnnounce = () => {
+		clearAnnounce();
+		if (!alive()) return;
+		announceTimer = setTimeout(() => {
+			announceTimer = undefined;
+			// Decided at fire time, not schedule time: a request may have gone out
+			// during the debounce (the -p race).
+			if (requestSent && !mcpSettled) {
+				announcePending = true;
+				return;
+			}
+			announce();
+		}, ANNOUNCE_DEBOUNCE_MS);
+		announceTimer.unref?.();
 	};
 
+	pi.events.on(MCP_TOOLS_CHANNEL, (data) => {
+		if (!(data as McpToolsPayload | undefined)?.settled) return;
+		mcpSettled = true;
+		if (announcePending) {
+			announcePending = false;
+			announce();
+		}
+	});
+
+	pi.on("context", () => {
+		requestSent = true;
+	});
+
+	// On models that take client-side tool references (first-party Claude >= 4.5,
+	// not Haiku) every deferred tool rides every Anthropic request as a
+	// `defer_loading: true` definition from request 1, so `tools` never changes
+	// when tool_search loads one. Anthropic keeps deferred definitions out of the
+	// cached prefix, but adding one mid-session still re-cached the whole message
+	// history (lib/deferred.ts withDeferredToolDefinitions has the measurement);
+	// unloaded deferred definitions cost no input tokens, so this is free.
+	pi.on("before_provider_request", (event, ctx) => {
+		if (!supportsToolReferences(ctx.model as { provider?: string; id?: string } | undefined)) return undefined;
+		if (!looksLikeAnthropicRequest(event.payload)) return undefined;
+		return withDeferredToolDefinitions(event.payload as Record<string, unknown>, pi.getAllTools(), (name) =>
+			deferredRegistry.has(name),
+		);
+	});
+
 	/** Deactivate every deferred-registry tool and announce the loadable set. */
 	const deferAll = () => {
 		const deferred = new Set(deferredRegistry.names);
@@ -69,7 +159,7 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 		const active = pi.getActiveTools();
 		const next = active.filter((name) => !deferred.has(name));
 		if (next.length !== active.length) pi.setActiveTools(next);
-		announceDeferred();
+		announce();
 	};
 
 	pi.events.on(DEFER_CHANNEL, (data) => {
@@ -84,21 +174,54 @@ export default function toolSearchExtension(pi: ExtensionAPI) {
 			if (active.includes(request.name)) {
 				pi.setActiveTools(active.filter((name) => name !== request.name));
 			}
-			announceDeferred();
+			// The tool is searchable (keyword search reads the registry) from now;
+			// only the standing listing waits.
+			scheduleAnnounce();
 		}
 	});
 
 	pi.on("session_start", () => {
 		sessionStarted = true;
+		// A pending debounce belongs to the previous session's listing (RPC's
+		// new_session emits session_start twice, findings §3); deferAll below
+		// announces the fresh one.
+		clearAnnounce();
+		// A new session (/clear, or a resume in a new process) has no cached prefix
+		// yet: its first request gets a freshly written listing.
+		requestSent = false;
+		announced.clear();
 		deferAll();
 	});
 
+	pi.on("session_shutdown", clearAnnounce);
+
+	// The every-turn deferred-tools list tells the model to load via tool_search,
+	// but if it calls a deferred tool directly anyway, pi's core dispatcher fails
+	// the call with a bare "Tool <name> not found" — which fires here as an error
+	// tool_execution_end. (This path skips beforeToolCall/afterToolCall, so the
+	// tool_call/tool_result hooks never see it.) The call can't be salvaged
+	// mid-turn, but we steer the model straight back to tool_search on its next
+	// step with a one-shot reminder, far more pointed than the standing list.
+	pi.on("tool_execution_end", (event) => {
+		if (!event.isError) return;
+		const raw = toolNotFoundName(resultText(event.result));
+		// Map a Claude Code spelling (a direct `NotebookEdit` call) to our name so
+		// the miss is recognised and the steer names the loadable tool (M1).
+		const name = raw ? normalizeToolName(raw) : undefined;
+		if (!name || !deferredRegistry.has(name)) return;
+		pi.events.emit(REMINDER_CHANNEL, {
+			scope: "next-turn",
+			key: `deferred-miss-${name}`,
+			text: deferredMissReminderText(name),
+		});
+	});
+
 	pi.registerTool({
 		name: "tool_search",
 		label: "Tool Search",
 		...ccToolRenderers("Tool Search"),
 		description:
-			"Load the schemas of tools that are available but not yet callable. Query forms: `select:<name>[,<name>]` to load exact tools by name, `+<term> <words>` to require a term in the tool name, or plain keywords to search. Returns the tools that are now callable.",
+			"Fetches full schema definitions for deferred tools so they can be called.\n\nDeferred tools appear by name in <system-reminder> messages. Until fetched, only the name is known — there is no parameter schema, so the tool cannot be invoked. This tool takes a query, matches it against the deferred tool list, and loads the matched tools' full schemas so they become callable exactly like any tool defined at the top of the prompt.\n\nQuery forms:\n- `select:web_fetch,notebook_edit` — fetch these exact tools by name\n- `notebook jupyter` — keyword search, up to max_results best matches\n- `+slack send` — require \"slack\" in the name, rank by remaining terms",
 		promptSnippet: "Load additional tool schemas on demand",
 		parameters: Type.Object({
 			query: Type.String({ description: "Tool names (`select:a,b`) or keywords describing the capability needed" }),

package/extensions/turn-duration/index.ts

@@ -0,0 +1,60 @@
+/**
+ * turn-duration extension — Claude Code's "✻ Cooked for 5m 12s" line shown in
+ * the transcript after each response.
+ *
+ * The turn's wall-clock is measured across agent_start→agent_settled by span.ts
+ * (one turn can hold several runs — `lib/interrupt.ts`) and emitted as a
+ * display-only session entry (`appendEntry` — not part of the LLM context, so
+ * the model never sees its own timing line), rendered dim and led by the ✻ mark
+ * to match CC's TurnDurationMessage. CC shows it after every response with no
+ * threshold and defaults it on; CC_TURN_DURATION=0 opts out. The completion verb
+ * is sampled once per turn from CC's 8-verb list.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { trackShellTasks } from "../lib/shell-tasks.ts";
+import { dimMarkedLine } from "../lib/tui-render.ts";
+import { TURN_MARK, turnDurationText } from "./line.ts";
+import { TurnSpan } from "./span.ts";
+import { pickCompletionVerb } from "./verbs.ts";
+
+const ENTRY_TYPE = "one-code:turn-duration";
+
+interface TurnDurationData {
+	verb: string;
+	durationMs: number;
+	/** Background shells still running when the turn ended (CC's `· 2 shells still running`). */
+	runningShells?: number;
+}
+
+export default function turnDurationExtension(pi: ExtensionAPI) {
+	const shellTasks = trackShellTasks(pi);
+
+	pi.registerEntryRenderer<TurnDurationData>(ENTRY_TYPE, (entry, _options, theme) => {
+		const data = entry.data;
+		if (!data) return undefined;
+		return dimMarkedLine(theme, TURN_MARK, turnDurationText(data.verb, data.durationMs, data.runningShells ?? 0));
+	});
+
+	const span = new TurnSpan();
+
+	pi.on("agent_start", () => {
+		span.runStarted(Date.now());
+	});
+
+	pi.on("agent_end", (event, ctx) => {
+		span.runEnded(event.messages, ctx.signal?.aborted);
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		const durationMs = span.settle(Date.now());
+		if (durationMs === undefined) return;
+		if (process.env.CC_TURN_DURATION === "0") return;
+		if (!ctx.hasUI) return;
+		pi.appendEntry<TurnDurationData>(ENTRY_TYPE, {
+			verb: pickCompletionVerb(),
+			durationMs,
+			runningShells: shellTasks.running().length,
+		});
+	});
+}

package/extensions/turn-duration/line.ts

@@ -0,0 +1,22 @@
+/**
+ * Pure pieces of Claude Code's turn-duration line ("✻ Cooked for 5m 12s"),
+ * matched to CC's SystemTextMessage/TurnDurationMessage render
+ * (`${verb} for ${duration}`, dim, led by the ✻ teardrop asterisk). CC shows
+ * it after every response with no minimum-duration threshold; the optional
+ * token-budget suffix is CC's separate /budget feature and is not replicated.
+ */
+
+import { countNoun, formatDuration } from "../lib/tui-render.ts";
+
+/** CC's TEARDROP_ASTERISK (figures.ts), the mark leading the duration line. */
+export const TURN_MARK = "✻";
+
+/**
+ * `<Verb> for <duration>` — duration formatted like the spinner's elapsed
+ * clock — plus Claude Code's background-shell tail (`· 2 shells still
+ * running`) when shells outlive the turn.
+ */
+export function turnDurationText(verb: string, durationMs: number, runningShells = 0): string {
+	const shells = runningShells > 0 ? ` · ${countNoun(runningShells, "shell")} still running` : "";
+	return `${verb} for ${formatDuration(0, durationMs)}${shells}`;
+}

package/extensions/turn-duration/span.ts

@@ -0,0 +1,41 @@
+/**
+ * The wall-clock span of one user-visible turn.
+ *
+ * A turn can hold several agent runs (see `lib/interrupt.ts` for why), so the
+ * span opens on the FIRST run and closes at settle: a retried run keeps the
+ * original start, which is what makes the rendered duration the time the user
+ * actually waited rather than the time the last attempt took.
+ *
+ * A turn that ends aborted or errored renders nothing: the interrupted
+ * extension prints its own note for an abort, and pi prints its own retry
+ * failure for an error. Claude Code gates its turn line the same way.
+ */
+
+import { type RunMessage, RunOutcomeLatch } from "../lib/interrupt.ts";
+
+export class TurnSpan {
+	/** Undefined rather than 0 for "no span open", so a start of 0 is still a start. */
+	private startedAt: number | undefined;
+	private readonly outcome = new RunOutcomeLatch();
+
+	/** `agent_start`: opens the span; a retry/continuation is a no-op, keeping the first start. */
+	runStarted(now: number): void {
+		this.startedAt ??= now;
+	}
+
+	/** `agent_end`: remembers how that run ended (with the run's `signal.aborted`), for settle to read. */
+	runEnded(messages: ReadonlyArray<RunMessage> | undefined, signalAborted = false): void {
+		this.outcome.record(messages, signalAborted);
+	}
+
+	/**
+	 * `agent_settled`: closes the span and returns the duration to render, or
+	 * undefined when this turn should show no line at all.
+	 */
+	settle(now: number): number | undefined {
+		const startedAt = this.startedAt;
+		this.startedAt = undefined;
+		if (this.outcome.take() !== "ok" || startedAt === undefined) return undefined;
+		return Math.max(0, now - startedAt);
+	}
+}

package/extensions/turn-duration/verbs.ts

@@ -0,0 +1,24 @@
+/**
+ * Claude Code's turn-completion verbs, verbatim from the reconstructed source
+ * (src/constants/turnCompletionVerbs.ts) — the past-tense verb shown after a
+ * response finishes ("✻ Cooked for 5m 12s"). One is picked at random per turn.
+ * These read naturally with "for <duration>", so the gerund spinner list
+ * (spinner/verbs.ts) is deliberately not reused.
+ */
+
+export const TURN_COMPLETION_VERBS: readonly string[] = [
+	"Baked",
+	"Brewed",
+	"Churned",
+	"Cogitated",
+	"Cooked",
+	"Crunched",
+	"Sautéed",
+	"Worked",
+];
+
+/** Random completion verb for one turn; `random` is injectable for tests. */
+export function pickCompletionVerb(random: () => number = Math.random): string {
+	const index = Math.min(TURN_COMPLETION_VERBS.length - 1, Math.floor(random() * TURN_COMPLETION_VERBS.length));
+	return TURN_COMPLETION_VERBS[index];
+}