one-code-extension 0.4.0 → 0.5.0

package/extensions/btw/index.ts

@@ -8,100 +8,181 @@
  * focused overlay panel, not in the transcript — so the exchange never enters
  * the main agent's context and cannot steer its work.
  *
- * The call reuses recap's machinery: the exact messages the session last put on
- * the wire (captured from the `context` event), name-only tool stubs so a
- * history carrying tool_use blocks stays valid on strict providers, and
- * withReasoningFallback for models that cannot disable thinking. Unlike recap it
- * uses the SESSION model (not an economical one) — a side question deserves the
- * same quality as the main conversation — and sends the full captured history,
- * not just the recent window.
+ * The call is Claude Code's: the session's last provider request replayed
+ * unchanged (system, every tool, every message), the reply that answered it,
+ * the session's earlier side exchanges, then the reminder and question, so it
+ * reads the cache the session wrote (lib/request-replay.ts; the compaction
+ * extension publishes the capture). Without a capture for the session model,
+ * or on a provider API the replay does not cover, it falls back to a
+ * standalone call: the messages the session last sent (captured from the
+ * `context` event), the earlier side exchanges, an empty system prompt,
+ * name-only tool stubs so a history carrying tool_use blocks stays valid on
+ * strict providers, and withReasoningFallback for models that cannot disable
+ * thinking. Both run on the SESSION model: a side question deserves the same
+ * quality as the main conversation.
  *
- * Deviations from CC, logged in docs/decisions/btw.md: the exchange is stateless
- * (each `/btw` sees only the shared main context, never a prior `/btw` — CC
- * keeps a side-session; the "one-off, no follow-up" framing holds either way);
- * `f to fork` is omitted (pi's `ctx.fork` branches from a session entry, not
- * from an injected side exchange); and the call runs with an empty system prompt
- * (the `context` event carries no system prompt to reuse), relying on the shared
- * history plus the reminder.
+ * Like Claude Code, the session keeps a side history: each answered question
+ * is threaded into the next one and listed in the panel, where it can be
+ * browsed and cleared. `f` forks the current answer into a background fork
+ * subagent through the subagents extension (lib/btw-fork.ts).
  */
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { Api, Model } from "@earendil-works/pi-ai";
-import { completeSimple } from "@earendil-works/pi-ai/compat";
-import { convertToLlm, copyToClipboard, type ExtensionAPI, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { withReasoningFallback } from "../lib/model-policy.ts";
-import { answerText, stripImageBlocks, toolStubs, trimToTurnBoundary } from "../lib/side-call.ts";
-import { boundedDockHeight, truncateLine } from "../lib/tui-render.ts";
+import {
+	convertToLlm,
+	copyToClipboard,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	getAgentDir,
+	SettingsManager,
+	UserMessageComponent,
+} from "@earendil-works/pi-coding-agent";
+import { ARGUMENT_HINT_CHANNEL, type ArgumentHint } from "../lib/argument-hints.ts";
+import { btwForkedLine, type BtwForkResult, requestBtwFork } from "../lib/btw-fork.ts";
+import { canShowCustomUi, notifyOrPrint, printAnswer } from "../lib/headless-output.ts";
+import { announcePromptOptions } from "../lib/prompt-options.ts";
+import { followLastExchange, replaySideCall } from "../lib/replay-call.ts";
+import { answerText, stripImageBlocks, toolStubs, trimToTurnBoundary, withoutSystemMessages } from "../lib/side-call.ts";
+import { boundedDockHeight, linesComponent, safeThemePaint, truncateLine } from "../lib/tui-render.ts";
+import { CONVERSATION_CACHE_PLACEMENT } from "../lib/side-call-cache.ts";
+import { releaseSideCalls, runSideCall } from "../lib/side-call-run.ts";
 import { recordUsage } from "../lib/usage-bus.ts";
-import { applyBtwKey, type BtwBody, BTW_MAX_HEIGHT, decodeBtwKey, initialBtwState, renderBtwPanel } from "./panel.ts";
-import { sideQuestionMessage } from "./prompt.ts";
+import type { ProseRenderer } from "../subagents/panel-render.ts";
+import { createMarkdownProse } from "../subagents/prose.ts";
+import { applyBtwKey, type BtwBody, BTW_MAX_HEIGHT, copyAnswer, decodeBtwKey, initialBtwState, renderBtwPanel } from "./panel.ts";
+import { type BtwExchange, exchangeMessages, historyMessages, sideQuestionMessage } from "./prompt.ts";
+import { panelUi } from "../lib/panel-focus.ts";
 
 const BTW_MAX_TOKENS = 8192;
 const BTW_TIMEOUT_MS = 120_000;
 /** Description on the name-only tool stubs sent with the side question. */
 const STUB_REASON = "Unavailable during this side question; answer in text.";
+/**
+ * The transcript record of a started fork, Claude Code's `/btw <question>` row
+ * with `⎿  ⑂ forked <name> (<id>)` under it. A display-only session entry: it
+ * never reaches the model, which learns of the fork from a one-shot reminder.
+ */
+const FORK_ENTRY_TYPE = "one-code:btw-fork";
+
+interface BtwForkEntry {
+	question: string;
+	name: string;
+	taskId: string;
+}
 
 export default function btwExtension(pi: ExtensionAPI) {
+	// The fork entry's `/btw` row is drawn as pi draws a user prompt, with the
+	// padding pi read from settings at startup.
+	let outputPad = 1;
+	try {
+		outputPad = SettingsManager.create(process.cwd(), getAgentDir()).getOutputPad();
+	} catch {
+		// Unreadable settings: pi's default padding.
+	}
+	pi.registerEntryRenderer<BtwForkEntry>(FORK_ENTRY_TYPE, (entry, _options, theme) => {
+		const data = entry.data;
+		if (!data) return undefined;
+		const row = new UserMessageComponent(`/btw ${data.question}`, undefined, outputPad);
+		const paint = safeThemePaint(theme);
+		return linesComponent((width) => [...row.render(width), truncateLine(`  ⎿  ${paint("dim", btwForkedLine(data.name, data.taskId))}`, width)]);
+	});
+
 	// The exact request messages the session last sent (after every extension's
 	// mutations), captured like recap and the compaction extension do.
 	let capturedMessages: AgentMessage[] | undefined;
 	pi.on("context", (event) => {
 		capturedMessages = event.messages;
 	});
+	// The same request as it went on the wire, and the reply that answered it.
+	const exchange = followLastExchange(pi);
+
+	// The session's answered side questions, oldest first: sent before each new
+	// question and listed in the panel. `x` in the panel clears them.
+	let history: BtwExchange[] = [];
 
 	// The controller for an open panel's in-flight call. Aborted when the session
 	// is replaced or torn down, so a late resolve cannot repaint a disposed `tui`
 	// or record usage on a stale `pi` (the crash the subagents panel once hit —
-	// docs/decisions/tools.md lifecycle review).
+	// working-docs/decisions/tools.md lifecycle review).
 	let inFlight: AbortController | undefined;
+	// Bumped when the session is replaced or torn down, so a fork request that
+	// settles afterwards touches neither the closed panel nor a stale ctx.
+	let sessionEpoch = 0;
 
-	// A new session (including after /clear) shares no context with the old one,
-	// and any in-flight side question is abandoned.
+	// A new session (including after /clear) shares no context with the old one:
+	// its side history starts empty and any in-flight side question is abandoned.
 	pi.on("session_start", () => {
+		sessionEpoch++;
+		// Claude Code's `[question]` placeholder after a bare `/btw` in the prompt.
+		pi.events.emit(ARGUMENT_HINT_CHANNEL, { command: "btw", hint: "[question]" } satisfies ArgumentHint);
 		capturedMessages = undefined;
+		history = [];
 		inFlight?.abort();
 		inFlight = undefined;
 	});
-	pi.on("session_shutdown", () => {
+	pi.on("session_shutdown", (_event, ctx) => {
+		sessionEpoch++;
 		inFlight?.abort();
 		inFlight = undefined;
+		releaseSideCalls(ctx.sessionManager.getSessionId());
 	});
 
-	/** Run the side question against the session model; returns the answer text. */
-	async function ask(ctx: ExtensionCommandContext, question: string, signal: AbortSignal): Promise<string> {
-		const model = ctx.model;
+	// The answer renders as Markdown, like the transcript; plain wrapped text
+	// until the renderer loads, or if it cannot.
+	let prose: ProseRenderer | undefined;
+	let proseLoad: Promise<void> | undefined;
+	const loadProse = (): Promise<void> =>
+		(proseLoad ??= createMarkdownProse().then(
+			(renderer) => {
+				prose = renderer;
+			},
+			() => {},
+		));
+
+	/** Run the side question against the session model, after the earlier exchanges; returns the answer text. */
+	async function ask(ctx: ExtensionCommandContext, question: string, earlier: readonly BtwExchange[], signal: AbortSignal): Promise<string> {
+		const model = ctx.model as Model<Api> | undefined;
 		if (!model) throw new Error("No model is configured for this session.");
+		const before = historyMessages(earlier, model);
+		const replayed = await replaySideCall(ctx, model, exchange, sideQuestionMessage(question), {
+			signal,
+			timeoutMs: BTW_TIMEOUT_MS,
+			onUsage: (usage) => recordUsage(pi, "btw", usage),
+			history: before,
+		});
+		if (replayed !== undefined) return replayed;
+
+		// No replay for this model, or it failed: the standalone call.
 		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
 		if (!auth.ok) throw new Error("No API key is available for the current model.");
-		const baseUrl = (auth as { baseUrl?: string }).baseUrl;
-
 		const tools = toolStubs(pi.getActiveTools(), STUB_REASON);
-		const context = trimToTurnBoundary(capturedMessages ?? []);
+		const context = trimToTurnBoundary(withoutSystemMessages(capturedMessages ?? []));
 		// btw runs on a cheap, possibly text-only reader and answers a text question,
 		// so images the conversation carried are stripped before the call
-		// (docs/decisions/model-policy.md).
-		const messages = [...stripImageBlocks(convertToLlm(context)), { role: "user" as const, content: sideQuestionMessage(question), timestamp: Date.now() }];
-
-		const result = await withReasoningFallback(
-			model as Model<Api>,
-			(reasoning) => {
-				const timeout = AbortSignal.timeout(BTW_TIMEOUT_MS);
-				return completeSimple(
-					baseUrl ? ({ ...model, baseUrl } as Model<Api>) : (model as Model<Api>),
-					{ systemPrompt: "", messages, tools },
-					{
-						apiKey: auth.apiKey,
-						headers: auth.headers,
-						env: auth.env,
-						signal: AbortSignal.any([signal, timeout]),
-						maxTokens: BTW_MAX_TOKENS,
-						...(reasoning ? { reasoning } : {}),
-					},
-				);
-			},
-			undefined,
-			(usage) => recordUsage(pi, "btw", usage),
-		);
+		// (working-docs/decisions/model-policy.md).
+		const messages = [
+			...stripImageBlocks(convertToLlm(context)),
+			...before,
+			{ role: "user" as const, content: sideQuestionMessage(question), timestamp: Date.now() },
+		];
+		const result = await runSideCall({
+			kind: "btw",
+			model,
+			auth,
+			sessionId: ctx.sessionManager.getSessionId(),
+			context: { systemPrompt: "", messages, tools },
+			signal,
+			timeoutMs: BTW_TIMEOUT_MS,
+			maxTokens: BTW_MAX_TOKENS,
+			cache: CONVERSATION_CACHE_PLACEMENT,
+			onUsage: (usage) => recordUsage(pi, "btw", usage),
+		});
+		// completeSimple reports a failure (a network error, a timeout) in the
+		// reply instead of throwing; its empty text is not an answer.
+		if (signal.aborted) return "";
+		if (result.stopReason === "aborted") throw new Error(`No answer within ${BTW_TIMEOUT_MS / 1000} seconds.`);
+		if (result.stopReason === "error") throw new Error(result.errorMessage || "The model returned an error.");
 		return answerText(result.content);
 	}
 
@@ -113,15 +194,27 @@ export default function btwExtension(pi: ExtensionAPI) {
 				ctx.ui.notify("Ask a side question: /btw <question>", "info");
 				return;
 			}
+			// The panel can fork a background agent whose completion opens the
+			// session's first turn; this context carries the options that turn
+			// is built from (lib/prompt-options.ts).
+			announcePromptOptions(pi.events, ctx);
 
-			// Headless (-p / --mode json): no panel — answer and print it. The
-			// handler blocks to completion, so the process does not exit early.
-			if (!ctx.hasUI) {
+			// RPC has dialogs but no custom panel. Deliver its answer as a notice,
+			// never a main-conversation message; one-shot runs print it instead.
+			if (!canShowCustomUi(ctx)) {
+				inFlight?.abort();
+				const controller = new AbortController();
+				inFlight = controller;
 				try {
-					const answer = await ask(ctx, question, new AbortController().signal);
-					ctx.ui.notify(answer || "(no answer)", "info");
+					const answer = await ask(ctx, question, history, controller.signal);
+					if (controller.signal.aborted) return;
+					if (answer) history.push({ question, answer });
+					if (ctx.mode === "rpc") ctx.ui.notify(answer || "(no answer)", "info");
+					else printAnswer(ctx, answer || "(no answer)");
 				} catch (error) {
-					ctx.ui.notify(`Side question failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+					if (!controller.signal.aborted) notifyOrPrint(ctx, `Side question failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+				} finally {
+					if (inFlight === controller) inFlight = undefined;
 				}
 				return;
 			}
@@ -132,11 +225,22 @@ export default function btwExtension(pi: ExtensionAPI) {
 			inFlight?.abort();
 			const controller = new AbortController();
 			inFlight = controller;
-			const view: { answer?: string; error?: string } = {};
+			// The earlier exchanges this panel lists and browses; the current one
+			// joins `history` when it lands, so the next /btw lists it.
+			let earlier = [...history];
+			const view: { answer?: string; error?: string; forking?: boolean } = {};
 			const bodyState = (): BtwBody =>
 				view.error !== undefined ? { kind: "error", message: view.error } : view.answer !== undefined ? { kind: "answer", text: view.answer } : { kind: "loading" };
+			// Reported after the panel closes: a started fork joins the transcript as
+			// Claude Code's `⑂ forked` entry; a failure is an error notice.
+			let forkResult: BtwForkResult | undefined;
+			const reportFork = (result: BtwForkResult) => {
+				if ("error" in result) ctx.ui.notify(result.error, "error");
+				else pi.appendEntry<BtwForkEntry>(FORK_ENTRY_TYPE, { question, name: result.name, taskId: result.taskId });
+			};
+			let panelOpen = true;
 
-			await ctx.ui.custom<null>((tui, theme, _keybindings, done) => {
+			await panelUi(pi.events, ctx.ui).custom<null>((tui, theme, _keybindings, done) => {
 				const state = initialBtwState();
 				let cache: { width: number; lines: string[] } | undefined;
 				const repaint = () => {
@@ -147,13 +251,15 @@ export default function btwExtension(pi: ExtensionAPI) {
 						tui.requestRender();
 					} catch {}
 				};
+				if (!prose) void loadProse().then(() => prose && repaint());
 
 				// Kick off the model call once, at mount, so `repaint` is bound.
 				void (async () => {
 					try {
-						const answer = await ask(ctx, question, controller.signal);
+						const answer = await ask(ctx, question, earlier, controller.signal);
 						if (controller.signal.aborted) return;
 						view.answer = answer;
+						if (answer) history.push({ question, answer });
 					} catch (error) {
 						if (controller.signal.aborted) return;
 						view.error = error instanceof Error ? error.message : String(error);
@@ -161,6 +267,30 @@ export default function btwExtension(pi: ExtensionAPI) {
 					repaint();
 				})();
 
+				const fork = (answer: string) => {
+					const model = ctx.model as Model<Api> | undefined;
+					if (!model) return;
+					view.forking = true;
+					repaint();
+					const epoch = sessionEpoch;
+					// The fork sees what the answer was written from: the earlier exchanges
+					// still listed (none once cleared), then this one.
+					const messages = [...historyMessages(earlier, model), ...exchangeMessages({ question, answer }, model)];
+					void requestBtwFork(pi.events, { ctx, question, messages }).then((result) => {
+						if (epoch !== sessionEpoch) return;
+						if (panelOpen) {
+							view.forking = false;
+							forkResult = result;
+							done(null);
+							return;
+						}
+						// The user closed the panel while the fork was starting.
+						try {
+							reportFork(result);
+						} catch {}
+					});
+				};
+
 				return {
 					render: (width: number) => {
 						if (cache?.width === width) return cache.lines;
@@ -169,26 +299,52 @@ export default function btwExtension(pi: ExtensionAPI) {
 						// Belt-and-suspenders truncate on top of renderBtwPanel's own,
 						// matching every sibling dock panel: pi-tui crashes the app on
 						// a line wider than the terminal.
-						const lines = renderBtwPanel({ state, question, body: bodyState(), width, height }, theme).map((line) => truncateLine(line, width));
+						const lines = renderBtwPanel(
+							{
+								state,
+								history: earlier,
+								question,
+								body: bodyState(),
+								width,
+								height,
+								canFork: true,
+								forking: view.forking,
+								renderAnswer: prose ? (text, width, ref) => prose!(ref, text, width) : undefined,
+							},
+							theme,
+						).map((line) => truncateLine(line, width));
 						cache = { width, lines };
 						return lines;
 					},
 					handleInput: (data: string) => {
 						const key = decodeBtwKey(data);
 						if (!key) return;
-						const effect = applyBtwKey(state, key);
+						// While a fork starts only closing works; its notice follows.
+						if (view.forking) {
+							if (key.kind === "close") done(null);
+							return;
+						}
+						const effect = applyBtwKey(state, key, earlier.length);
+						const shown = state.selected === null ? view.answer : earlier[state.selected]?.answer;
 						switch (effect?.kind) {
 							case "close":
 								done(null);
 								return;
 							case "copy":
 								// Only offer copy once there is a non-empty answer.
-								if (view.answer) {
-									void copyToClipboard(view.answer).then(() => {
-										state.copied = true;
-										repaint();
-									});
-								}
+								if (shown) void copyAnswer(copyToClipboard, shown, state, repaint);
+								return;
+							case "fork":
+								// The current answer only, not one browsed from the history.
+								if (state.selected === null && view.answer) fork(view.answer);
+								return;
+							case "clear":
+								if (earlier.length === 0) return;
+								history = history.filter((entry) => !earlier.includes(entry));
+								earlier = [];
+								state.selected = null;
+								state.offset = 0;
+								repaint();
 								return;
 							default:
 								repaint();
@@ -200,8 +356,10 @@ export default function btwExtension(pi: ExtensionAPI) {
 				};
 			});
 
+			panelOpen = false;
 			controller.abort();
 			if (inFlight === controller) inFlight = undefined;
+			if (forkResult) reportFork(forkResult);
 		},
 	});
 }