one-code-extension 0.4.1 → 0.6.0

package/extensions/lib/shell-tool.ts

@@ -13,24 +13,34 @@
 
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
-import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ExtensionToolContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { Static, TObject } from "typebox";
 import { generateTaskId, TASK_REGISTER_CHANNEL } from "../background/registry.ts";
 import { type BashFinishSummary, runBackgroundBashBlocking, startBackgroundBash, tailCap } from "../bash/background.ts";
 import { createTaskNotifier, oneShotNote, sessionOutlivesTurn, shellSummary, type TaskStatus, taskNotification } from "./notifications.ts";
 import { commandToEvaluate, trackOriginalCommands } from "./original-command.ts";
-import { persistIfLarge, sessionResultsDir } from "./persisted-output.ts";
+import { persistedFilePreview, persistIfLarge, sessionResultsDir } from "./persisted-output.ts";
+import { withClaudeCodeShellText } from "./shell-result.ts";
+import { bashParserReady } from "./bash-parser.ts";
 import type { ShellSpawn } from "./shell-spawn.ts";
+import { keepSpillReadable } from "./spill-file.ts";
 import { ccWrapBuiltinRenderers, linesComponent, resultLines } from "./tui-render.ts";
+import { registerVariantTool } from "./tool-variants.ts";
 
 // The completion notification carries status + exit code + where the output is,
 // plus only a short tail: a finished build used to push 30 KB (~8k tokens) into
 // context unasked (review T7). The full tail stays behind task_output / the log.
 export const NOTIFY_OUTPUT_CAP = 2_000;
-/** One-shot modes return the whole output in the result; past this it is persisted (file + preview), never cut. */
-export const ONE_SHOT_OUTPUT_CAP = 30_000;
+/** Claude Code's inline cap for a shell's output; past it the output is persisted (file + head preview), never cut. */
+export const INLINE_OUTPUT_CAP = 30_000;
 /** Claude Code's cap; the tools' `timeout` is milliseconds, as CC's is. */
 export const MAX_TIMEOUT_MS = 600_000;
+/**
+ * Claude Code's default for a command that names no `timeout`, which both
+ * tool descriptions promise. pi's executor has no default, so without this a
+ * foreground `npm run dev` ran until Esc, and forever in a `-p` run.
+ */
+export const DEFAULT_TIMEOUT_MS = 120_000;
 
 /** The parameter shape both shell tools share (descriptions differ per tool). */
 export interface ShellToolParams {
@@ -53,7 +63,7 @@ export interface ShellToolBase {
 
 /** pi's shell tool executor: `execute(toolCallId, { command, timeout: seconds }, signal, onUpdate, ctx)`. */
 export interface ShellToolExecutor {
-	execute: (toolCallId: string, params: { command: string; timeout?: number }, signal: AbortSignal | undefined, onUpdate: any, ctx: ExtensionContext) => Promise<any>;
+	execute: (toolCallId: string, params: { command: string; timeout?: number }, signal: AbortSignal | undefined, onUpdate: any, ctx: ExtensionToolContext) => Promise<any>;
 }
 
 /** What one shell tool's definition supplies; everything else is shared. */
@@ -98,10 +108,20 @@ export function finishLine(summary: BashFinishSummary, timeoutSeconds?: number):
 	return `failed (${detail ?? `exit code ${summary.exitCode}`})`;
 }
 
+/**
+ * Why a one-shot `run_in_background` call was stopped: a one-shot session
+ * cannot keep a command running past the run, so the call is held to the
+ * foreground deadline.
+ */
+export function oneShotDeadlineNote(timeoutMs: number, explicit: boolean): string {
+	const which = explicit ? `its ${timeoutMs} ms timeout` : `the default ${timeoutMs} ms timeout (no \`timeout\` was given)`;
+	return `It was stopped at ${which}: a one-shot session cannot keep a background command running after the run ends, so a server or watcher started this way stops at the deadline. Pass a longer \`timeout\` (max ${MAX_TIMEOUT_MS}) for a long build.`;
+}
+
 /** `<sessionDir>/bash/<taskId>/output.log` — one spool location for every shell tool (the shell panel reads it). */
 export function taskLogPath(ctx: ExtensionContext, taskId: string): string | undefined {
 	try {
-		const dir = join(ctx.sessionManager.getSessionDir(), "bash", taskId);
+		const dir = join(sessionResultsDir(ctx), "bash", taskId);
 		mkdirSync(dir, { recursive: true });
 		return join(dir, "output.log");
 	} catch {
@@ -109,7 +129,13 @@ export function taskLogPath(ctx: ExtensionContext, taskId: string): string | und
 	}
 }
 
-export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: ShellToolSpec<P>): void {
+/**
+ * Register the shell tool; the returned setter registers it again with a new
+ * description (a no-op when the text is unchanged), for a description that
+ * follows the session (lib/tool-variants.ts). Everything else — the notifier,
+ * the original-command tracker, execute — is built once.
+ */
+export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: ShellToolSpec<P>): (description: string) => void {
 	// A completion whose output task_output just returned is withdrawn (CC's
 	// delivered_as_tool_result) — the model already has it.
 	const notifyTask = createTaskNotifier(pi, { withdrawOnDelivery: true });
@@ -124,7 +150,7 @@ export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: She
 	// "Took Ns" that counted permission-prompt wait disappears.
 	const wrapped = ccWrapBuiltinRenderers<{ command?: string }>(spec.ccLabel, spec.base, { title: (a) => a?.command });
 
-	pi.registerTool({
+	const definition = {
 		name: spec.name,
 		label: spec.base.label,
 		description: spec.description,
@@ -162,14 +188,24 @@ export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: She
 			if (guardReason) return { content: [{ type: "text" as const, text: guardReason }], isError: true, details: {} };
 			// pi's executor takes seconds; the model-facing unit is milliseconds
 			// (Claude Code's), so a habitual `timeout: 120000` is 2 minutes, not
-			// 33 hours (review T11).
-			const timeoutSeconds =
-				params.timeout !== undefined && Number.isFinite(params.timeout) && params.timeout > 0
-					? Math.min(params.timeout, MAX_TIMEOUT_MS) / 1000
-					: undefined;
+			// 33 hours (review T11). A command that names none gets Claude Code's
+			// default, which is what the descriptions promise.
+			const explicitTimeout = params.timeout !== undefined && Number.isFinite(params.timeout) && params.timeout > 0;
+			const timeoutSeconds = (explicitTimeout ? Math.min(params.timeout!, MAX_TIMEOUT_MS) : DEFAULT_TIMEOUT_MS) / 1000;
 
 			if (!params.run_in_background) {
-				return spec.foreground(ctx.cwd).execute(toolCallId, { command: params.command, timeout: timeoutSeconds }, signal, onUpdate, ctx);
+				// pi spills a long output to os.tmpdir(), outside every readable root;
+				// move it where the model's read of it is a working-space read, and
+				// cut the output Claude Code's way (its head, not pi's tail). Then
+				// Claude Code's result text (`Exit code N` first, trimmed output).
+				const result = await keepSpillReadable(
+					() => spec.foreground(ctx.cwd).execute(toolCallId, { command: params.command, timeout: timeoutSeconds }, signal, onUpdate, ctx),
+					sessionResultsDir(ctx),
+					{ inlineMax: INLINE_OUTPUT_CAP, id: `${spec.name}-${toolCallId}` },
+				);
+				// The no-match check parses the command; only bash results need the grammar.
+				if (spec.name === "bash") await bashParserReady();
+				return withClaudeCodeShellText(result, spec.name, originalCommand);
 			}
 
 			const shell = spec.backgroundShell();
@@ -189,48 +225,61 @@ export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: She
 			// detached task would be orphaned, and its completion callback would
 			// call sendMessage on the disposed session and crash pi (measured,
 			// STEERING-REVIEW-2026-09-05 H3). Run blocking there — the same rule the
-			// Agent tool applies — and return the output in the result.
+			// Agent tool applies — and return the output in the result. The call
+			// holds the turn like a foreground command, so it gets the foreground
+			// deadline (the model's `timeout`, else the default): with none, a
+			// server started this way hung the run forever. A detached shell below
+			// keeps having no deadline (findings §31).
 			if (!sessionOutlivesTurn(ctx.mode)) {
 				const summary = await runBackgroundBashBlocking({ id, command, description, cwd: ctx.cwd, timeoutSeconds, logPath, shell }, signal);
-				const output = persistIfLarge(summary.output, { dir: sessionResultsDir(ctx), id: `${spec.name}-${id}`, maxBytes: ONE_SHOT_OUTPUT_CAP });
+				const spool = summary.logPath && Buffer.byteLength(summary.output, "utf8") > INLINE_OUTPUT_CAP
+					? persistedFilePreview(summary.logPath)
+					: undefined;
+				const output = spool ?? persistIfLarge(summary.output, { dir: sessionResultsDir(ctx), id: `${spec.name}-${id}`, maxBytes: INLINE_OUTPUT_CAP });
+				const deadline = summary.timedOut ? ` ${oneShotDeadlineNote(timeoutSeconds * 1000, explicitTimeout)}` : "";
 				return {
 					content: [
 						{
 							type: "text" as const,
-							text: `${spec.ccLabel} task ${id} (${description}) ${finishLine(summary, timeoutSeconds)}. ${oneShotNote("command")}${logPath ? ` Log: ${logPath}.` : ""}\n\n${output}`,
+							text: `${spec.ccLabel} task ${id} (${description}) ${finishLine(summary, timeoutSeconds)}. ${oneShotNote("command")}${deadline}${summary.logPath ? ` Log: ${summary.logPath}.` : ""}\n\n${output}`,
 						},
 					],
 					// No taskId: nothing was registered behind task_output/task_stop, and
 					// its presence is what renderResult reads as "running in the background".
-					details: { logPath },
-					isError: summary.exitCode !== 0 && !summary.stopped,
+					details: { logPath: summary.logPath },
+					isError: shellFinish(summary, timeoutSeconds).status === "failed",
 				};
 			}
 
+			// No timeout here: Claude Code clears a command's timeout the
+			// moment it goes to the background, so a detached shell has no
+			// deadline (findings §31). Models habitually send `timeout: 600000`
+			// next to `run_in_background`, which used to kill a dev server at
+			// exactly 10 minutes. The one-shot path above keeps the timeout
+			// because there the command holds the turn.
 			const task = startBackgroundBash({
 				id,
 				command,
 				description,
 				cwd: ctx.cwd,
-				timeoutSeconds,
 				logPath,
 				shell,
 				onFinished: (finishedTask, summary) => {
 					// Claude Code's shell completion names the output file and nothing
 					// else — the model reads it (or task_output) when it needs the text.
 					// Without a spool file the tail rides `<result>` so nothing is lost.
-					const { status, detail } = shellFinish(summary, timeoutSeconds);
+					const { status, detail } = shellFinish(summary);
 					notify(
 						taskNotification({
 							kind: "shell",
 							taskId: id,
 							toolUseId: toolCallId,
-							outputFile: logPath,
+							outputFile: finishedTask.logPath,
 							status,
 							summary: shellSummary(description, status, summary.exitCode, detail),
-							result: logPath ? undefined : tailCap(summary.output, NOTIFY_OUTPUT_CAP).trim() || undefined,
+							result: finishedTask.logPath ? undefined : tailCap(summary.output, NOTIFY_OUTPUT_CAP).trim() || undefined,
 						}),
-						{ taskId: id, status: finishedTask.status, exitCode: summary.exitCode, logPath },
+						{ taskId: id, status: finishedTask.status, exitCode: summary.exitCode, logPath: finishedTask.logPath },
 					);
 				},
 			});
@@ -248,5 +297,6 @@ export function registerShellTool<P extends TObject>(pi: ExtensionAPI, spec: She
 				details: { taskId: id, logPath },
 			};
 		},
-	} as ToolDefinition<P>);
+	} as ToolDefinition<P>;
+	return registerVariantTool(pi, spec.description, (description) => ({ ...definition, description }) as unknown as ToolDefinition);
 }

package/extensions/lib/side-call-cache.ts

@@ -0,0 +1,124 @@
+/**
+ * Anthropic cache placement for standalone side calls. pi-ai marks the final
+ * user question, which means every different question writes a fresh cache
+ * entry. Move that marker onto the preceding conversation message instead,
+ * without changing any message text. Call this from an `anthropic-messages`
+ * payload hook, or an `openai-completions` one: Chat Completions carries the
+ * same `cache_control` markers when the model takes Anthropic's format
+ * (OpenRouter's `anthropic/*`), and has none to move otherwise.
+ */
+
+/** The APIs whose standalone side-call payload this placement applies to. */
+export const SIDE_CALL_CACHE_APIS: ReadonlySet<string> = new Set(["anthropic-messages", "openai-completions"]);
+
+/** Anthropic permits at most four cache-control markers per request. */
+export const MAX_SIDE_CALL_CACHE_MARKERS = 4;
+
+type WireRecord = Record<string, unknown>;
+
+/**
+ * Move pi-ai's final-question cache marker to the last preceding message and
+ * remove the earliest markers past Anthropic's four-marker limit. Unsupported
+ * payload shapes are left unchanged rather than being normalised.
+ */
+export function cacheSideCallConversation(payload: unknown): void {
+	if (!isRecord(payload) || !Array.isArray(payload.messages)) return;
+	const messages = payload.messages;
+	const questionIndex = messages.length - 1;
+	const question = asMessage(messages[questionIndex]);
+	if (!question || question.role !== "user") return;
+	const questionBlocks = blocks(question.content);
+	const sourceIndex = questionBlocks.findLastIndex((block) => block.cache_control !== undefined);
+	if (sourceIndex === -1) return;
+
+	const target = precedingCacheableBlock(messages, questionIndex);
+	if (!target) return;
+	const marker = questionBlocks[sourceIndex].cache_control;
+	const nextQuestionBlocks = [...questionBlocks];
+	const { cache_control: _, ...unmarked } = questionBlocks[sourceIndex];
+	nextQuestionBlocks[sourceIndex] = unmarked;
+	const nextTargetBlocks = [...target.blocks];
+	nextTargetBlocks[target.blockIndex] = { ...target.blocks[target.blockIndex], cache_control: marker };
+	const nextMessages = [...messages];
+	nextMessages[questionIndex] = { ...question, content: nextQuestionBlocks };
+	nextMessages[target.messageIndex] = { ...target.message, content: nextTargetBlocks };
+	payload.messages = nextMessages;
+	capMarkers(payload);
+}
+
+interface Target {
+	messageIndex: number;
+	message: WireRecord;
+	blocks: WireRecord[];
+	blockIndex: number;
+}
+
+/** The last prior wire block Anthropic accepts as a message cache breakpoint. */
+function precedingCacheableBlock(messages: unknown[], questionIndex: number): Target | undefined {
+	for (let messageIndex = questionIndex - 1; messageIndex >= 0; messageIndex--) {
+		const message = asMessage(messages[messageIndex]);
+		if (!message) continue;
+		// pi-ai keeps earlier user text as a string, only converting the final
+		// marked message to blocks. Convert this target exactly as pi-ai does so
+		// the newest conversation turn, rather than an older block message, gets
+		// the cache boundary. The text itself remains byte-for-byte unchanged.
+		// Chat Completions also sends assistant and tool text as strings; an
+		// empty one (a tool-call-only reply) cannot carry a marker, as in pi-ai.
+		if (typeof message.content === "string") {
+			if (message.content.length === 0) continue;
+			return { messageIndex, message, blocks: [{ type: "text", text: message.content }], blockIndex: 0 };
+		}
+		const content = blocks(message.content);
+		const blockIndex = content.findLastIndex(isCacheableBlock);
+		if (blockIndex !== -1) return { messageIndex, message, blocks: content, blockIndex };
+	}
+	return undefined;
+}
+
+function asMessage(value: unknown): WireRecord | undefined {
+	return isRecord(value) && typeof value.role === "string" ? value : undefined;
+}
+
+function blocks(value: unknown): WireRecord[] {
+	return Array.isArray(value) && value.every(isRecord) ? value : [];
+}
+
+/** This is pi-ai's own list from its Anthropic message converter. */
+function isCacheableBlock(block: WireRecord): boolean {
+	return (
+		block.type === "text" ||
+		block.type === "image" ||
+		block.type === "tool_result" ||
+		block.type === "tool_addition" ||
+		block.type === "tool_removal"
+	);
+}
+
+/** Drop the earliest actual Anthropic markers in wire order: tools, system, messages. */
+function capMarkers(payload: WireRecord): void {
+	const markers = [
+		...topLevelMarkers(payload.tools),
+		...topLevelMarkers(payload.system),
+		...messageMarkers(payload.messages),
+	];
+	for (const marker of markers.slice(0, Math.max(0, markers.length - MAX_SIDE_CALL_CACHE_MARKERS))) delete marker.cache_control;
+}
+
+/** Tool definitions and top-level system blocks can each carry one marker. */
+function topLevelMarkers(value: unknown): WireRecord[] {
+	return Array.isArray(value) ? value.filter((entry): entry is WireRecord => isRecord(entry) && entry.cache_control !== undefined) : [];
+}
+
+/** Only a message content block is an Anthropic conversation marker. Never inspect block payloads. */
+function messageMarkers(value: unknown): WireRecord[] {
+	if (!Array.isArray(value)) return [];
+	return value.flatMap((message) => (isRecord(message) ? blocks(message.content).filter((block) => block.cache_control !== undefined) : []));
+}
+
+function isRecord(value: unknown): value is WireRecord {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+
+/** The conversation cache placement a side call passes to `runSideCall` (`side-call-run.ts`). */
+export const CONVERSATION_CACHE_PLACEMENT = { apis: SIDE_CALL_CACHE_APIS, place: cacheSideCallConversation } as const;

package/extensions/lib/side-call-run.ts

@@ -0,0 +1,96 @@
+/**
+ * One standalone side call: a single `completeSimple` request outside the main
+ * agent loop, shared by `/btw`, the recap and the web_fetch reader. The
+ * auto-mode classifier has its own transport and stays out of this.
+ *
+ * Every side call takes the same steps: splice the provider's base URL from the
+ * resolved auth into the model, combine the caller's abort signal with a
+ * per-attempt timeout, key the request to the session (`<session id>:<kind>`,
+ * stable across calls, so the provider's prompt cache is reused), apply the
+ * caller's cache placement on the APIs it covers, log the attempt
+ * (`CC_SIDE_CALL_LOG`), retry with thinking on when the model cannot disable
+ * it, and report usage for the footer cost. The request on the wire is exactly
+ * what each extension built inline before (`side-call-run-wire.test.ts`).
+ *
+ * Kept apart from `side-call.ts`, which stays free of runtime pi imports for
+ * the pure prompt modules that use it.
+ */
+
+import { type Api, type AssistantMessage, type Context, cleanupSessionResources, type Model, type SimpleStreamOptions, type ThinkingLevel } from "@earendil-works/pi-ai";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import { withReasoningFallback } from "./model-policy.ts";
+import { SIDE_CALL_KINDS, type SideCallLogContext, logSideCallUsage } from "./side-call-usage.ts";
+
+/** A payload hook that places cache breakpoints, and the APIs whose payload shape it handles. */
+export interface SideCallCachePlacement {
+	apis: ReadonlySet<string>;
+	place: (payload: unknown) => void;
+}
+
+export interface SideCallRun {
+	/** Names the call in the cache key and the side-call log. */
+	kind: SideCallLogContext["kind"];
+	model: Model<Api>;
+	/** The model registry's resolved auth for `model` (the caller handles a failed lookup). */
+	auth: { apiKey?: string; headers?: SimpleStreamOptions["headers"]; env?: Record<string, string>; baseUrl?: string };
+	/** The session's id; the call's cache key is `<sessionId>:<kind>`. */
+	sessionId: string;
+	context: Context;
+	signal?: AbortSignal;
+	/** Applies to each attempt on its own, so a reasoning retry gets a full timeout. */
+	timeoutMs: number;
+	maxTokens: number;
+	/** Cache placement for the payload; none leaves pi-ai's own markers. */
+	cache?: SideCallCachePlacement;
+	/** Per-session memo of a model's required thinking level (`withReasoningFallback`). */
+	learnedReasoning?: Map<string, ThinkingLevel>;
+	/** Each attempt's usage, for the footer's all-in cost. */
+	onUsage: (usage: unknown) => void;
+}
+
+type SideCallKind = SideCallLogContext["kind"];
+
+/** A side call's cache key, which pi-ai also takes as its `sessionId`. */
+function sideCallKey(sessionId: string, kind: SideCallKind): string {
+	return `${sessionId}:${kind}`;
+}
+
+/**
+ * Close what pi-ai holds open under a session's side-call keys, every kind's
+ * (a key never used costs nothing). On openai-codex it keeps one WebSocket per
+ * `sessionId` with a 5-minute idle timer holding the process, and pi's own
+ * dispose closes only the session's id, so a `pi -p` run waited out the timer
+ * after its answer (findings §59). Every extension that runs a side call calls
+ * it as the session ends, so a new kind is released with no further change.
+ */
+export function releaseSideCalls(sessionId: string): void {
+	for (const kind of SIDE_CALL_KINDS) cleanupSessionResources(sideCallKey(sessionId, kind));
+}
+
+/** Run the side call and return the final reply; a provider failure is in its `stopReason`, as with `completeSimple`. */
+export async function runSideCall(run: SideCallRun): Promise<AssistantMessage> {
+	const { kind, model, auth, context } = run;
+	const sessionId = sideCallKey(run.sessionId, kind);
+	const target = auth.baseUrl ? ({ ...model, baseUrl: auth.baseUrl } as Model<Api>) : model;
+	const onPayload = run.cache?.apis.has(model.api) ? run.cache.place : undefined;
+	return withReasoningFallback(
+		model,
+		async (reasoning) => {
+			const timeout = AbortSignal.timeout(run.timeoutMs);
+			const reply = await completeSimple(target, context, {
+				apiKey: auth.apiKey,
+				headers: auth.headers,
+				env: auth.env,
+				signal: run.signal ? AbortSignal.any([run.signal, timeout]) : timeout,
+				maxTokens: run.maxTokens,
+				sessionId,
+				...(onPayload ? { onPayload } : {}),
+				...(reasoning ? { reasoning } : {}),
+			});
+			logSideCallUsage({ kind, model, sessionId, system: context.systemPrompt ?? "", messages: context.messages }, reply);
+			return reply;
+		},
+		run.learnedReasoning,
+		run.onUsage,
+	);
+}

package/extensions/lib/side-call-usage.ts

@@ -0,0 +1,38 @@
+/** Opt-in side-call cache evidence, independent of the provider's transport. */
+import { appendFileSync } from "node:fs";
+
+/** Every side-call kind; releaseSideCalls closes each one's pi-ai key. */
+export const SIDE_CALL_KINDS = ["reader", "btw", "recap"] as const;
+
+export interface SideCallLogContext {
+	kind: (typeof SIDE_CALL_KINDS)[number];
+	model: { provider: string; id: string; api: string };
+	sessionId: string;
+	system: string;
+	messages: readonly unknown[];
+}
+
+/**
+ * CC_SIDE_CALL_LOG names a JSONL file containing prompt text and normalized
+ * usage, never credentials or response text. Like CC_AUTO_MODE_LOG, this is
+ * explicitly opt-in and never read back. Log every completed provider attempt,
+ * including reasoning retries; a probe must not mistake an error for a hit.
+ */
+export function logSideCallUsage(call: SideCallLogContext, reply: { usage?: unknown; stopReason: string }): void {
+	const path = process.env.CC_SIDE_CALL_LOG;
+	if (!path) return;
+	try {
+		appendFileSync(path, `${JSON.stringify({
+			kind: call.kind,
+			model: `${call.model.provider}/${call.model.id}`,
+			api: call.model.api,
+			sessionId: call.sessionId,
+			system: call.system,
+			messages: call.messages,
+			usage: reply.usage,
+			stopReason: reply.stopReason,
+		})}\n`);
+	} catch {
+		// A diagnostic log that cannot be written must not fail a side call.
+	}
+}

package/extensions/lib/side-call.ts

@@ -26,6 +26,17 @@ export function toolStubs(names: readonly string[], reason = "Unavailable for th
 	);
 }
 
+/**
+ * The messages the current branch holds, as pi builds a request from them
+ * (compaction-aware), read when the side call runs. A copy kept from the last
+ * `context` event goes stale at a `/tree` or a compaction, which fire no
+ * `context` event, and the fallback then answered from the abandoned branch or
+ * the whole pre-compaction history.
+ */
+export function branchMessages<M>(ctx: { sessionManager: { buildSessionProjection(): { messages: M[] } } }): M[] {
+	return ctx.sessionManager.buildSessionProjection().messages;
+}
+
 /**
  * Trim a message history forward to the first clean turn boundary — a `user`
  * prompt or an `assistant` reply. A raw history can begin mid-exchange with a
@@ -40,6 +51,18 @@ export function trimToTurnBoundary<T extends { role: string }>(messages: readonl
 	return start === -1 ? [] : messages.slice(start);
 }
 
+/**
+ * The conversation without pi's `system` transcript messages, for a capture of
+ * the `context` event. pi 0.86 hands `context` handlers a leading system message
+ * holding pi's own default prompt sections and every full tool schema; a side
+ * call that forwarded it had pi-ai replay those into its system prompt and tools
+ * (over the stubs), and it shifted every role-by-index comparison. pi 0.87 strips
+ * system messages before `context` handlers run, so there this is a no-op.
+ */
+export function withoutSystemMessages<T extends { role: string }>(messages: readonly T[]): T[] {
+	return messages.filter((message) => message.role !== "system");
+}
+
 /** The placeholder left in a message whose only content was an image we removed. */
 export const IMAGE_OMITTED_TEXT = "[image omitted]";
 
@@ -55,7 +78,7 @@ export const IMAGE_OMITTED_TEXT = "[image omitted]";
  * placeholder text block, so it stays a valid turn on strict providers. Purely
  * structural (any `{ role, content }` message) to stay free of runtime pi
  * imports; assistant messages carry no images and pass through untouched.
- * See `docs/decisions/model-policy.md`.
+ * See `working-docs/decisions/model-policy.md`.
  */
 export function stripImageBlocks<M extends { role: string; content: unknown }>(messages: readonly M[]): M[] {
 	return messages.map((message) => {

package/extensions/lib/single-flight.ts

@@ -0,0 +1,18 @@
+/**
+ * One in-flight run per key (pure): a call while a run for its key is pending
+ * shares that run's promise instead of starting another; once it settles, the
+ * next call starts fresh. Used where two overlapping callers would otherwise
+ * both pass an "is it there yet?" check across an await and duplicate work
+ * that must happen once (a language server spawn, a consent dialog).
+ */
+export function singleFlight<T>(): (key: string, run: () => Promise<T>) => Promise<T> {
+	const pending = new Map<string, Promise<T>>();
+	return (key, run) => {
+		let current = pending.get(key);
+		if (!current) {
+			current = run().finally(() => pending.delete(key));
+			pending.set(key, current);
+		}
+		return current;
+	};
+}

package/extensions/lib/skill-body.ts

@@ -0,0 +1,42 @@
+/**
+ * Skills whose body is generated, not read from their SKILL.md: Claude Code's
+ * `/loop` builds a different prompt per argument shape (findings §21). The
+ * skill extension emits a `SkillBodyQuery` on SKILL_BODY_CHANNEL before it
+ * delivers a skill; the extension that owns the skill fills `body`
+ * synchronously, and the SKILL.md body is the fallback.
+ *
+ * A fired scheduled prompt that is a slash command (`/loop check the deploy`,
+ * `/babysit-prs`) runs the way Claude Code runs it, as if typed: the
+ * background extension emits a `SlashExpandQuery` on SLASH_EXPAND_CHANNEL
+ * and the skill extension fills `expanded` with the skill's block.
+ *
+ * Pure: no pi imports.
+ */
+
+export const SKILL_BODY_CHANNEL = "one-code:skill-body";
+export const SLASH_EXPAND_CHANNEL = "one-code:slash-expand";
+
+export interface SkillBodyQuery {
+	/** The skill's name. */
+	skill: string;
+	/** Its SKILL.md, so a provider answers only for its own file. */
+	path: string;
+	args: string;
+	cwd: string;
+	/** Set by the provider; the arguments are then part of it. */
+	body?: string;
+}
+
+export interface SlashExpandQuery {
+	/** The fired prompt, starting with `/`. */
+	text: string;
+	cwd: string;
+	/** Set by the skill extension when the command is a skill. */
+	expanded?: string;
+}
+
+/** `/name rest` split, or undefined when `text` is not a slash command. */
+export function parseSlashCommand(text: string): { name: string; args: string } | undefined {
+	const match = /^\/([^\s/][^\s]*)(?:\s+([\s\S]*))?$/.exec(text.trim());
+	return match ? { name: match[1], args: (match[2] ?? "").trim() } : undefined;
+}