one-code-extension 0.3.1 → 0.4.0

package/extensions/lib/deferred.ts

@@ -10,6 +10,8 @@
  * `{ name, keywords? }` while extensions are loading (before session_start).
  */
 
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import { toolResultsOnBranch } from "./branch-restore.ts";
 import { parseClaudeVersion } from "./model-tier.ts";
 import { normalizeToolName } from "../permissions/matcher.ts";
 
@@ -106,51 +108,189 @@ export interface DeferrableToolInfo {
 	parameters?: { properties?: unknown; required?: unknown };
 }
 
+/** The `tool_search` calls that loaded tools: each call's id → the names it loaded. */
+export type ToolSearchLoads = ReadonlyMap<string, readonly string[]>;
+
+/**
+ * Every load recorded on a session branch: a `tool_search` result whose
+ * persisted `details.added` names the tools it activated. Read once at
+ * session start (a resumed session's earlier loads); loads made during the
+ * session are captured at the call itself.
+ */
+export function toolSearchLoads(branch: readonly SessionEntry[]): Map<string, string[]> {
+	const loads = new Map<string, string[]>();
+	for (const message of toolResultsOnBranch(branch, TOOL_SEARCH_NAMES)) {
+		const added = (message.details as { added?: unknown } | undefined)?.added;
+		if (!Array.isArray(added)) continue;
+		const names = added.filter((n): n is string => typeof n === "string");
+		if (names.length > 0) loads.set(message.toolCallId, names);
+	}
+	return loads;
+}
+const TOOL_SEARCH_NAMES: ReadonlySet<string> = new Set(["tool_search"]);
+
+type WireTool = Record<string, unknown> & { name: string };
+type WireBlock = Record<string, unknown> & { type?: unknown };
+type WireMessage = { role?: unknown; content?: unknown };
+
+/** A deferred definition in pi's own `convertTools` shape (findings §7). */
+function deferredDefinition(tool: DeferrableToolInfo): WireTool {
+	return {
+		name: tool.name,
+		description: tool.description ?? "",
+		input_schema: {
+			type: "object",
+			properties: tool.parameters?.properties ?? {},
+			required: tool.parameters?.required ?? [],
+		},
+		defer_loading: true,
+	};
+}
+
+/** The list with pi's cache breakpoint on its last item (a no-op without one). */
+function withBreakpointOnLast<T extends Record<string, unknown>>(items: T[], cache_control: unknown): T[] {
+	if (cache_control === undefined || items.length === 0) return items;
+	return [...items.slice(0, -1), { ...items[items.length - 1], cache_control }];
+}
+
 /**
- * An Anthropic request with every deferred tool that pi left out appended as a
- * `defer_loading: true` definition, sorted by name (pi's own entries stay first
- * and untouched). Anthropic keeps deferred definitions out of the cached prefix,
- * but ADDING one to `tools` mid-session still re-caches the message history —
- * measured 2026-09-04 on Sonnet 5: the request after a `tool_search` load read
- * only tools + system (8.7k of 25k tokens); with the full deferred set present
- * from request 1 it read all 25k. Unloaded deferred definitions cost no input
- * tokens, so sending them always is free and keeps `tools` byte-stable.
+ * An Anthropic request whose `tools` array is byte-identical to request 1's,
+ * whatever `tool_search` has loaded since — the client side of Anthropic's
+ * deferred-tool contract, which pi 0.86 no longer supplies for One Code
+ * (rationale and measurements: docs/decisions/caching.md "Loaded deferred
+ * tools stay deferred on the wire", findings §7).
+ *
+ * - Every registry tool `isDeferred` that is not eager on the wire is appended
+ *   as a `defer_loading: true` definition, sorted by name; pi's own rendering
+ *   of a later-deferred registry tool is replaced by ours.
+ * - A loaded tool pi promoted to eager is demoted back to deferred, the tools
+ *   cache breakpoint moves to the last remaining eager tool, and the
+ *   `tool_search` result that loaded it (`loads`) is rewritten to
+ *   `tool_reference` blocks, its own content moving to trailing sibling blocks
+ *   that take the result's breakpoint (Anthropic rejects references mixed with
+ *   ordinary result content). Demotion happens only when that result is on the
+ *   wire and precedes every `tool_use` of the tool; otherwise the tool stays
+ *   eager (one accepted cache miss, never a request Anthropic rejects).
+ * - pi's own deferred entries that are not registry tools (its
+ *   `__pi_deferred_placeholder__`) stay in place.
  *
- * Returns undefined (leave the payload alone) when there is nothing to add, the
- * request carries no tools, or the tool names on the wire are not the registry's
- * (pi's OAuth "stealth" mode renames them to Claude Code casing, and a name that
- * cannot be matched must not be duplicated). Schemas follow pi's own
- * `convertTools` shape. Never mutates its input.
+ * Returns undefined (leave the payload alone) when the request carries no
+ * tools or the wire names are not the registry's (pi's OAuth "stealth" mode
+ * renames them to Claude Code casing, and an unmatched name must not be
+ * duplicated). Never mutates its input.
  */
-export function withDeferredToolDefinitions(
+export function stabilizeDeferredTools(
 	payload: Record<string, unknown>,
 	tools: readonly DeferrableToolInfo[],
 	isDeferred: (name: string) => boolean,
+	loads: ToolSearchLoads = new Map(),
 ): Record<string, unknown> | undefined {
 	const existing = payload.tools;
 	if (!Array.isArray(existing) || existing.length === 0) return undefined;
 	const registry = new Set(tools.map((t) => t.name));
-	const present = new Set<string>();
-	for (const tool of existing) {
-		const name = (tool as { name?: unknown } | null)?.name;
-		if (typeof name !== "string" || !registry.has(name)) return undefined;
-		present.add(name);
+
+	const eager: WireTool[] = [];
+	const anchors: WireTool[] = [];
+	for (const raw of existing) {
+		const tool = raw as WireTool | null;
+		if (typeof tool?.name !== "string") return undefined;
+		if (!registry.has(tool.name)) {
+			if (tool.defer_loading === true) anchors.push(tool);
+			else return undefined;
+			continue;
+		}
+		if (tool.defer_loading !== true) eager.push(tool);
+	}
+
+	const messages: WireMessage[] = Array.isArray(payload.messages) ? (payload.messages as WireMessage[]) : [];
+	const referencesAt = new Map<string, string[]>();
+	const demoted = new Set<string>();
+	if (loads.size > 0 && eager.some((tool) => isDeferred(tool.name))) {
+		// Message index of each tool's first use and of each tool result: a
+		// reference is valid only ahead of every use of the tool.
+		const firstUse = new Map<string, number>();
+		const resultAt = new Map<string, number>();
+		messages.forEach((message, index) => {
+			if (!Array.isArray(message?.content)) return;
+			for (const block of message.content as WireBlock[]) {
+				if (block?.type === "tool_use" && typeof block.name === "string" && !firstUse.has(block.name)) {
+					firstUse.set(block.name, index);
+				} else if (block?.type === "tool_result" && typeof block.tool_use_id === "string") {
+					resultAt.set(block.tool_use_id, index);
+				}
+			}
+		});
+		// The earliest on-wire load of each tool.
+		const loaderOf = new Map<string, { callId: string; at: number }>();
+		for (const [callId, names] of loads) {
+			const at = resultAt.get(callId);
+			if (at === undefined) continue;
+			for (const name of names) {
+				const current = loaderOf.get(name);
+				if (current === undefined || at < current.at) loaderOf.set(name, { callId, at });
+			}
+		}
+		for (const tool of eager) {
+			if (!isDeferred(tool.name)) continue;
+			const loader = loaderOf.get(tool.name);
+			if (loader === undefined) continue;
+			const use = firstUse.get(tool.name);
+			if (use !== undefined && use < loader.at) continue;
+			demoted.add(tool.name);
+			referencesAt.set(loader.callId, [...(referencesAt.get(loader.callId) ?? []), tool.name]);
+		}
 	}
-	const extra = tools
-		.filter((t) => isDeferred(t.name) && !present.has(t.name))
+
+	// pi puts the tools breakpoint on the last eager tool; if that one is demoted
+	// the breakpoint moves to the new last one, otherwise nothing moves.
+	const last = eager.at(-1);
+	const keptEager = withBreakpointOnLast(
+		eager.filter((tool) => !demoted.has(tool.name)),
+		last !== undefined && demoted.has(last.name) ? last.cache_control : undefined,
+	);
+	if (keptEager.length === 0) return undefined;
+	const eagerNames = new Set(keptEager.map((tool) => tool.name));
+	const deferred = tools
+		.filter((t) => isDeferred(t.name) && !eagerNames.has(t.name))
 		.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
-		.map((t) => ({
-			name: t.name,
-			description: t.description ?? "",
-			input_schema: {
-				type: "object",
-				properties: t.parameters?.properties ?? {},
-				required: t.parameters?.required ?? [],
-			},
-			defer_loading: true,
-		}));
-	if (extra.length === 0) return undefined;
-	return { ...payload, tools: [...existing, ...extra] };
+		.map(deferredDefinition);
+	return {
+		...payload,
+		tools: [...keptEager, ...anchors, ...deferred],
+		messages: referencesAt.size === 0 ? payload.messages : messages.map((m) => withToolReferences(m, referencesAt)),
+	};
+}
+
+/**
+ * The user message with each loading `tool_result` rewritten to carry its
+ * `tool_reference` blocks and its original content moved to trailing sibling
+ * blocks; a breakpoint on the rewritten result moves to the new last block so
+ * the whole message stays inside the cached prefix.
+ */
+function withToolReferences(message: WireMessage, referencesAt: ReadonlyMap<string, readonly string[]>): WireMessage {
+	if (message?.role !== "user" || !Array.isArray(message.content)) return message;
+	const content = message.content as WireBlock[];
+	if (!content.some((block) => block?.type === "tool_result" && referencesAt.has(block.tool_use_id as string))) return message;
+
+	const blocks: WireBlock[] = [];
+	const siblings: WireBlock[] = [];
+	let movedBreakpoint: unknown;
+	for (const block of content) {
+		const names = block?.type === "tool_result" ? referencesAt.get(block.tool_use_id as string) : undefined;
+		if (!names) {
+			blocks.push(block);
+			continue;
+		}
+		const { content: original, cache_control, ...rest } = block;
+		if (cache_control !== undefined) movedBreakpoint = cache_control;
+		blocks.push({ ...rest, content: names.map((name) => ({ type: "tool_reference", tool_name: name })) });
+		if (typeof original === "string") {
+			if (original.trim().length > 0) siblings.push({ type: "text", text: original });
+		} else if (Array.isArray(original)) {
+			siblings.push(...(original as WireBlock[]));
+		}
+	}
+	return { ...message, content: withBreakpointOnLast([...blocks, ...siblings], movedBreakpoint) };
 }
 
 /**

package/extensions/lib/git.ts

@@ -1,8 +1,24 @@
 /** Shared git helpers — pure functions only (safe to import across extensions). */
 
+import { execFile } from "node:child_process";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 
+/**
+ * Whether the checkout at `cwd` has no uncommitted or untracked changes, or
+ * undefined when git could not say (not a repo, git missing). One short
+ * `git status --porcelain`, asynchronous so the tool_call hook it runs from
+ * does not stall the event loop; used for the classifier transcript's
+ * ground-truth line after a `git status` call (permissions/index.ts).
+ */
+export function gitStatusClean(cwd: string): Promise<boolean | undefined> {
+	return new Promise((resolvePromise) => {
+		execFile("git", ["status", "--porcelain"], { cwd, encoding: "utf8", timeout: 5_000, windowsHide: true }, (error, stdout) => {
+			resolvePromise(error ? undefined : stdout.trim().length === 0);
+		});
+	});
+}
+
 /**
  * The nearest checkout root at or above `startDir`: the directory holding a
  * `.git` entry (a directory for a main checkout, a file for a linked worktree

package/extensions/lib/keys.ts

@@ -0,0 +1,38 @@
+/**
+ * Keys that depend on the platform.
+ *
+ * pi rebinds a handful of its own shortcuts on Windows and WSL, where
+ * alt+enter and ctrl+shift+letter do not reach the process reliably: queue
+ * follow-up moves from alt+enter to ctrl+q, fork from ctrl+shift+f to ctrl+f,
+ * paste to alt+v, model select to alt+p (pi-coding-agent core/keybindings.js,
+ * `useWindowsKeybindings`, which pi does not export — the rule is copied
+ * here). So the ctrl+q that cycles permission modes everywhere else collides
+ * there: pi skips a `registerShortcut` on a built-in key with a startup
+ * warning, and mode cycling had no key at all on Windows (seen on the Vultr
+ * VM, 2026-09-19). No ctrl+letter is free on Windows once pi's app and editor
+ * bindings are counted, and pi itself reaches for alt there, so mode cycling
+ * is alt+m on Windows and WSL — docs/decisions/windows.md.
+ */
+
+/** pi's rule for its Windows key table: native Windows, or a WSL distro. */
+export function useWindowsKeybindings(platform: string = process.platform, env: NodeJS.ProcessEnv = process.env): boolean {
+	return platform === "win32" || (platform === "linux" && Boolean(env.WSL_DISTRO_NAME || env.WSL_INTEROP));
+}
+
+/** The key that cycles permission modes: ctrl+q, or alt+m where pi owns ctrl+q. */
+export function modeCycleKey(platform: string = process.platform, env: NodeJS.ProcessEnv = process.env): "ctrl+q" | "alt+m" {
+	return useWindowsKeybindings(platform, env) ? "alt+m" : "ctrl+q";
+}
+
+/**
+ * The footer badge's pause icon. Claude Code's is U+23F8 (⏸); Windows Terminal
+ * draws that code point with its emoji font, two cells wide and coloured,
+ * while pi measures one cell, so the icon overlapped the mode name — and the
+ * text-presentation selector (U+FE0E) is ignored there (verified on the Vultr
+ * VM, 2026-09-19: rows A and B of the width test). U+2016 (‖) is a plain
+ * single-cell glyph in Windows Terminal, so it stands in on Windows and WSL,
+ * where the terminal is Windows Terminal either way.
+ */
+export function pauseGlyph(platform: string = process.platform, env: NodeJS.ProcessEnv = process.env): "⏸" | "‖" {
+	return useWindowsKeybindings(platform, env) ? "‖" : "⏸";
+}

package/extensions/lib/local-command.ts

@@ -0,0 +1,112 @@
+/**
+ * Local-command breadcrumbs — what Claude Code shows the model when the user
+ * runs a slash command that the harness handles locally (`/clear`, `/model`, a
+ * panel command). Captured from CC 2.1.278 (`captures/sonnet.json`, and this
+ * repo's own sessions after a `/clear`; findings §14, 2026-09-19): three
+ * synthetic user messages that reach the model as consecutive bare text blocks
+ * of the next user message, after the reminder stack and before the user's own
+ * text —
+ *
+ *   <local-command-caveat>Caveat: …</local-command-caveat>\n
+ *   <command-name>/model</command-name>\n
+ *               <command-message>model</command-message>\n
+ *               <command-args></command-args>\n
+ *   <local-command-stdout>Set model to `Sonnet 5` …</local-command-stdout>\n
+ *
+ * (twelve-space indent on the second and third command lines, verbatim from
+ * CC's `formatCommandInputTags`; stdout XML-escaped like CC's `escapeXml`, `&
+ * < >` only). `/clear` carries an EMPTY stdout block and opens the new
+ * conversation. The caveat tells the model not to act on any of it.
+ *
+ * One Code emits these through the reminder queue's `user-prepend` placement
+ * (`lib/reminders.ts`): pi dispatches an extension command BEFORE its `input`
+ * event fires and handles its own built-ins (`/model`, `/name`, …) before
+ * either, so there is no single interception point — every One Code local
+ * command is registered through `registerLocalCommand`, which announces before
+ * the handler runs, and `/model` is announced from the `model_select` event by
+ * the extension that persists the choice. pi built-ins we cannot see
+ * (`/compact`, `/settings`, …) stay silent. The blocks are pinned in process
+ * memory, not written to the session file as CC does — a `--resume` drops them.
+ */
+
+import { REMINDER_CHANNEL, type ReminderPayload } from "./reminders.ts";
+
+/** The slice of pi's ExtensionAPI the announcer needs (its event bus). */
+export interface ReminderEmitter {
+	events: { emit(channel: string, data: unknown): unknown };
+}
+
+/**
+ * How each breadcrumb block begins — what a first message that is NOT the
+ * user's topic starts with (the session-title extension skips these, as CC's
+ * REPL does before naming a session).
+ */
+export const LOCAL_COMMAND_TAG_PREFIXES = ["<local-command-caveat>", "<command-name>", "<command-message>", "<local-command-stdout>"] as const;
+
+export const LOCAL_COMMAND_CAVEAT =
+	"<local-command-caveat>Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.</local-command-caveat>\n";
+
+/** CC's `escapeXml` (utils/xml.ts): `& < >` only. */
+export function escapeXml(s: string): string {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export interface LocalCommand {
+	/** Command name without the slash (`clear`, `model`). */
+	name: string;
+	/** The argument text the user typed after the name; "" when none. */
+	args?: string;
+	/** The command's printed result; "" (the default) is what `/clear` shows. */
+	stdout?: string;
+}
+
+/** CC's `formatCommandInputTags` — the command breadcrumb, indentation included. */
+export function commandInputBlock(name: string, args = ""): string {
+	return `<command-name>/${name}</command-name>\n            <command-message>${name}</command-message>\n            <command-args>${args}</command-args>\n`;
+}
+
+/** CC's `<local-command-stdout>` message; the content is XML-escaped. */
+export function commandStdoutBlock(stdout = ""): string {
+	return `<local-command-stdout>${escapeXml(stdout)}</local-command-stdout>\n`;
+}
+
+/** The three bare text blocks a local command leaves for the model, in CC's order. */
+export function localCommandBlocks(command: LocalCommand): string[] {
+	return [LOCAL_COMMAND_CAVEAT, commandInputBlock(command.name, (command.args ?? "").trim()), commandStdoutBlock(command.stdout ?? "")];
+}
+
+/**
+ * Tell the model a local command ran. Call it from the command's handler
+ * (before a `/clear` resets the session — the queue survives `newSession()`,
+ * so the breadcrumb opens the new conversation exactly as in CC).
+ */
+export function announceLocalCommand(pi: ReminderEmitter, command: LocalCommand): void {
+	localCommandBlocks(command).forEach((text, index) => {
+		// The caveat heads a RUN of commands: a second command before the next
+		// prompt joins the first caveat instead of repeating it.
+		const payload: ReminderPayload = { text, placement: "user-prepend", raw: true, ...(index === 0 ? { once: true } : {}) };
+		pi.events.emit(REMINDER_CHANNEL, payload);
+	});
+}
+
+type CommandOptions = { handler: (args: string, ctx: any) => Promise<void> | void } & Record<string, unknown>;
+
+/**
+ * `pi.registerCommand` for a One Code local command: the breadcrumb is
+ * announced before the handler runs, so no command can forget it. `/clear`
+ * is the one exception — it announces from the NEW session's `session_start`
+ * (see clear/index.ts) and registers plainly.
+ */
+export function registerLocalCommand<O extends CommandOptions>(
+	pi: ReminderEmitter & { registerCommand(name: string, options: O): void },
+	name: string,
+	options: O,
+): void {
+	pi.registerCommand(name, {
+		...options,
+		handler: (args: string, ctx: unknown) => {
+			announceLocalCommand(pi, { name, args });
+			return options.handler(args, ctx);
+		},
+	});
+}