@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/interactive/editor-submit.ts

@@ -1,9 +1,11 @@
-import { runBashCommand } from "../core/bash-exec.js";
+import { combineBashOutput, runBashCommand } from "../core/bash-exec.js";
+import type { PendingSkillRequest } from "../core/skill-activation.js";
+import { ToolNames } from "../core/tool-names.js";
 import type { DispatchContract } from "../domains/dispatch/contract.js";
 import type { SessionContract, SessionEntry } from "../domains/session/index.js";
+import { toolPresentationPolicy } from "../tools/presentation.js";
 import type { ChatLoop } from "./chat-loop.js";
 import type { ChatPanel } from "./chat-panel.js";
-import { renderBashExecutionEntry } from "./chat-renderer.js";
 import { bashExecutionEntryInput, parseEditorBashCommand } from "./editor-bash.js";
 import {
 	formatSteerCandidates,
@@ -12,7 +14,15 @@ import {
 	resolveSteerTarget,
 } from "./editor-steer.js";
 import { type ExternalEditResult, editTextExternally, resolveExternalEditor } from "./external-editor.js";
-import { parseSlashCommand, type RunIo, type SlashCommand } from "./slash-commands.js";
+import { type BashTranscriptExecution, renderBashTranscriptExecution } from "./renderers/tool-execution.js";
+import { parseSlashCommand, type RunIo, type SlashCommand, type SlashCommandDispatchResult } from "./slash-commands.js";
+import {
+	type FoldOverride,
+	policyRunningToolFold,
+	policyToolFold,
+	resolveFold,
+	type TranscriptDetailPolicy,
+} from "./transcript-detail.js";
 
 const EDITOR_BASH_TIMEOUT_MS = 300_000;
 
@@ -26,13 +36,8 @@ const EDITOR_BASH_TIMEOUT_MS = 300_000;
  * operator can see which flag the usage line is complaining about and fix that
  * one token.
  *
- * `unknown-command` used to be restored on the same reasoning and it does not
- * hold. The token matched no command at all, so there is nothing to correct
- * against, and the restored text has no cursor placement of its own: the next
- * keystrokes land in front of the leftover `/token`, which no longer parses as
- * a command, so the whole concatenation goes to the model as a chat message the
- * operator never wrote. An empty line after "is not a command" costs a retype
- * and says exactly what happened.
+ * `unknown-command` cannot be decided here: a prompt template can still claim
+ * it during dispatch. Its post-dispatch verdict is handled at the call site.
  *
  * A command that ran and failed has done work, and chat text belongs to the
  * transcript, so both also leave the line empty.
@@ -44,6 +49,10 @@ function isRejectedCommand(command: SlashCommand): boolean {
 export interface EditorSubmitExpansion {
 	text: string;
 	images: ReadonlyArray<unknown>;
+	/** Paths the draft referenced inline; the idle path hands them to the chat loop for rule scoping. */
+	workingContextPaths?: ReadonlyArray<string>;
+	/** Skill requests parsed out of the draft; the idle path hands them to the chat loop as the pending-skill policy. */
+	pendingSkillRequests?: ReadonlyArray<PendingSkillRequest>;
 }
 
 export interface EditorSubmitEditor {
@@ -58,13 +67,18 @@ export interface EditorSubmitUi {
 	requestRender(force?: boolean): void;
 }
 
-type EditorSubmitChat = Pick<ChatLoop, "clearQueuedFollowUps" | "isStreaming" | "queueFollowUp">;
+type EditorSubmitChat = Pick<
+	ChatLoop,
+	"clearQueuedFollowUps" | "interruptRefusal" | "isStreaming" | "queueFollowUp" | "submit" | "whenSettled"
+>;
 type EditorSubmitDispatch = Pick<DispatchContract, "snapshot" | "steer">;
 type EditorSubmitSession = Pick<SessionContract, "appendEntry" | "current" | "tree">;
 
 export interface EditorSubmitSessionTranscript {
 	ensureSessionForLocalEntry(): void;
 	refreshChatContextFromSession(leafTurnId: string | null): void;
+	/** Count a prompt the operator submitted; the idle path does this through the slash runtime. */
+	recordSubmittedTurn(): void;
 }
 
 export interface EditorSubmitDeps {
@@ -76,7 +90,10 @@ export interface EditorSubmitDeps {
 	session?: EditorSubmitSession;
 	sessionTranscript: EditorSubmitSessionTranscript;
 	chatPanel: Pick<ChatPanel, "appendReplayBlock">;
-	dispatchCommand: (text: string) => void;
+	beforeSemanticBoundary?: (reason: string) => void;
+	settleVisibleFrame?: (reason: string) => Promise<void>;
+	dispatchCommand: (text: string) => SlashCommandDispatchResult;
+	dispatchCommandAsync?: (text: string, signal?: AbortSignal) => Promise<void>;
 	/** Idempotently collapses a fresh-session launchpad before any handler can append output. */
 	collapseLaunchpadBeforeSubmit?: () => void;
 	expandSubmit: (text: string) => Promise<EditorSubmitExpansion>;
@@ -93,15 +110,27 @@ export interface EditorSubmitController {
 	openExternalEditorForInput(): void;
 	handleEditorSteerMention(mention: { target: string; text: string }): boolean;
 	submitEditorText(text: string): void;
+	/** Admit an immutable boot record without reading or mutating the live draft. */
+	admitCapturedText(text: string, signal?: AbortSignal): Promise<void>;
 	queueFollowUpFromEditor(): void;
+	/**
+	 * Interrupt mode: cancel the active run and deliver the draft now. Idle, it
+	 * is a plain send. The chat loop owns cancel → settle → submit and the two
+	 * refusals (attached dispatch, parked permission ask), which degrade the
+	 * message to next-slot delivery with a notice.
+	 */
+	interruptFromEditor(): void;
 	restoreQueuedFollowUpsToEditor(): void;
 	hasActiveEditorBash(): boolean;
 	cancelActiveEditorBash(): boolean;
 }
 
+type EditorSteerSubmission = "unhandled" | "accepted" | "rejected";
+
 /** Owns editor submission and the one local bash process attached to it. */
 export function createEditorSubmitController(deps: EditorSubmitDeps): EditorSubmitController {
 	let activeEditorBash: AbortController | null = null;
+	let activeEditorBashSettlement: Promise<void> | null = null;
 
 	const runEditorBash = (text: string): boolean => {
 		const parsed = parseEditorBashCommand(text);
@@ -126,13 +155,55 @@ export function createEditorSubmitController(deps: EditorSubmitDeps): EditorSubm
 			activeEditorBash = null;
 			return true;
 		}
+		const startedAt = performance.now();
+		const execution: BashTranscriptExecution = {
+			command: parsed.command,
+			output: "",
+			running: true,
+			totalBytes: 0,
+			excludeFromContext: parsed.excludeFromContext,
+		};
+		// The operator's bash row follows the same rule as a model bash call: the
+		// transcript detail policy (through bash's presentation once settled)
+		// unless the operator overrode this one block with the expand key.
+		let fold: FoldOverride;
+		const bashPresentation = toolPresentationPolicy(ToolNames.Bash, undefined);
+		const policyFold = (detail: TranscriptDetailPolicy) =>
+			execution.running ? policyRunningToolFold(detail) : policyToolFold(detail, bashPresentation);
+		deps.chatPanel.appendReplayBlock(
+			(width, detail) =>
+				renderBashTranscriptExecution(
+					{
+						...execution,
+						folded: resolveFold(fold, policyFold(detail)) === "folded",
+						...(execution.running ? { elapsedMs: Math.max(0, performance.now() - startedAt) } : {}),
+					},
+					width,
+				),
+			() => execution.running,
+			{
+				policyFold,
+				fold: () => fold,
+				setFold: (next: FoldOverride) => {
+					fold = next;
+					deps.ui.requestRender();
+				},
+			},
+		);
+		deps.ui.requestRender();
 
-		void (async () => {
+		let settlement!: Promise<void>;
+		settlement = (async () => {
 			try {
 				const result = await (deps.runBash ?? runBashCommand)(parsed.command, {
 					cwd: deps.getCwd?.() ?? process.cwd(),
 					timeoutMs: EDITOR_BASH_TIMEOUT_MS,
 					signal: abort.signal,
+					onUpdate: (progress) => {
+						execution.output = combineBashOutput(progress);
+						execution.totalBytes = progress.outputBytes;
+						deps.ui.requestRender();
+					},
 				});
 				const input = bashExecutionEntryInput({
 					command: parsed.command,
@@ -149,17 +220,34 @@ export function createEditorSubmitController(deps: EditorSubmitDeps): EditorSubm
 							timestamp: deps.nowIso?.() ?? new Date().toISOString(),
 						} as SessionEntry);
 				if (entry.kind === "bashExecution") {
-					deps.chatPanel.appendReplayBlock((width) => renderBashExecutionEntry(entry, width));
+					execution.output = entry.output;
+					execution.running = false;
+					execution.exitCode = entry.exitCode;
+					execution.cancelled = entry.cancelled;
+					execution.truncated = entry.truncated;
+					execution.fullOutputPath = entry.fullOutputPath;
+					execution.totalBytes = Math.max(execution.totalBytes ?? 0, Buffer.byteLength(combineBashOutput(result), "utf8"));
 				}
-				deps.sessionTranscript.refreshChatContextFromSession(parentTurnId);
+				// `parentTurnId` was the leaf when the command started and stays the
+				// entry's anchor. The chat leaf is a different question: a prompt
+				// may have landed while the command ran, so restore the leaf the
+				// session has now, not the one captured then. Restoring the stale
+				// one wedged every later submit on a parent that was no longer
+				// the leaf.
+				deps.sessionTranscript.refreshChatContextFromSession(deps.session?.tree().leafId ?? parentTurnId);
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
+				execution.running = false;
+				execution.error = msg;
 				deps.io.stderr(`[bash] ${msg}\n`);
 			} finally {
 				if (activeEditorBash === abort) activeEditorBash = null;
+				if (activeEditorBashSettlement === settlement) activeEditorBashSettlement = null;
 				deps.ui.requestRender();
 			}
 		})();
+		activeEditorBashSettlement = settlement;
+		void settlement;
 		return true;
 	};
 
@@ -186,14 +274,14 @@ export function createEditorSubmitController(deps: EditorSubmitDeps): EditorSubm
 		deps.ui.requestRender(true);
 	};
 
-	const handleEditorSteerMention = (mention: { target: string; text: string }): boolean => {
+	const submitEditorSteerMention = (mention: { target: string; text: string }): EditorSteerSubmission => {
 		let running: RunningDispatchRef[] = [];
 		try {
 			running = deps.dispatch.snapshot().running.map((run) => ({ runId: run.runId, agentId: run.agentId }));
 		} catch {
 			running = [];
 		}
-		if (running.length === 0) return false;
+		if (running.length === 0) return "unhandled";
 		const resolution = resolveSteerTarget(mention.target, running);
 		if (resolution.kind === "match") {
 			try {
@@ -203,11 +291,12 @@ export function createEditorSubmitController(deps: EditorSubmitDeps): EditorSubm
 					`steer queued for ${resolution.run.agentId} (${resolution.run.runId}); awaiting worker acknowledgement`,
 					`steer:${resolution.run.runId}`,
 				);
+				return "accepted";
 			} catch (err) {
 				const msg = err instanceof Error ? err.message : String(err);
 				deps.notify("error", `steer to @${mention.target} failed: ${msg}`, `steer:${mention.target}`);
+				return "rejected";
 			}
-			return true;
 		}
 		if (resolution.kind === "ambiguous") {
 			deps.notify(
@@ -215,34 +304,127 @@ export function createEditorSubmitController(deps: EditorSubmitDeps): EditorSubm
 				`@${mention.target} matches ${resolution.candidates.length} runs: ${formatSteerCandidates(resolution.candidates)}; use a runId prefix`,
 				`steer:${mention.target}`,
 			);
-			return true;
+			return "rejected";
 		}
 		deps.notify(
 			"warning",
 			`no running dispatch matches @${mention.target}; running: ${formatSteerCandidates(running)}`,
 			`steer:${mention.target}`,
 		);
-		return true;
+		return "rejected";
 	};
 
+	const handleEditorSteerMention = (mention: { target: string; text: string }): boolean =>
+		submitEditorSteerMention(mention) !== "unhandled";
+
 	const submitEditorText = (text: string): void => {
 		const trimmed = text.trim();
 		if (trimmed.length === 0) return;
 		deps.collapseLaunchpadBeforeSubmit?.();
 		if (parseEditorBashCommand(text)) {
-			if (!deps.chat.isStreaming() && !activeEditorBash) deps.editor.setText("");
+			if (!deps.chat.isStreaming() && !activeEditorBash) {
+				deps.editor.addToHistory(text);
+				deps.editor.setText("");
+			} else {
+				// Pi Editor clears the buffer before invoking onSubmit. A command
+				// refused by either admission guard is still a draft, so put it back
+				// for the operator instead of silently discarding it.
+				deps.editor.setText(text);
+			}
 			if (runEditorBash(text)) deps.ui.requestRender();
 			return;
 		}
 		const steerMention = parseEditorSteerMention(trimmed);
-		if (steerMention && handleEditorSteerMention(steerMention)) {
+		if (steerMention) {
+			const submission = submitEditorSteerMention(steerMention);
+			if (submission !== "unhandled") {
+				if (submission === "accepted") {
+					deps.editor.addToHistory(text);
+					deps.editor.setText("");
+				} else {
+					// Resolution and dispatch failures are correctable rejections. Pi
+					// has already cleared the editor, so explicitly restore the draft.
+					deps.editor.setText(text);
+				}
+				deps.ui.requestRender();
+				return;
+			}
+		}
+		const command = parseSlashCommand(trimmed);
+		if (isRejectedCommand(command)) {
+			deps.editor.setText(text);
+			deps.dispatchCommand(trimmed);
+		} else if (command.kind === "unknown-command") {
+			const result = deps.dispatchCommand(trimmed);
+			if (result === "rejected") {
+				deps.editor.setText(text);
+			} else {
+				deps.editor.addToHistory(text);
+				deps.editor.setText("");
+			}
+		} else {
 			deps.editor.addToHistory(text);
 			deps.editor.setText("");
+			deps.dispatchCommand(trimmed);
+		}
+		deps.ui.requestRender();
+	};
+
+	const awaitWithAbort = async (promise: Promise<void>, signal?: AbortSignal): Promise<void> => {
+		if (!signal) return await promise;
+		signal.throwIfAborted();
+		let abort: (() => void) | null = null;
+		try {
+			await Promise.race([
+				promise,
+				new Promise<never>((_resolve, reject) => {
+					abort = () => reject(signal.reason ?? new DOMException("aborted", "AbortError"));
+					signal.addEventListener("abort", abort, { once: true });
+				}),
+			]);
+		} finally {
+			if (abort) signal.removeEventListener("abort", abort);
+		}
+	};
+
+	const admitCapturedText = async (text: string, signal?: AbortSignal): Promise<void> => {
+		const trimmed = text.trim();
+		if (trimmed.length === 0) return;
+		signal?.throwIfAborted();
+		deps.collapseLaunchpadBeforeSubmit?.();
+		if (parseEditorBashCommand(text)) {
+			while (deps.chat.isStreaming()) await awaitWithAbort(deps.chat.whenSettled(), signal);
+			while (activeEditorBashSettlement) await awaitWithAbort(activeEditorBashSettlement, signal);
+			signal?.throwIfAborted();
+			deps.editor.addToHistory(text);
+			runEditorBash(text);
 			deps.ui.requestRender();
 			return;
 		}
-		deps.editor.setText(isRejectedCommand(parseSlashCommand(trimmed)) ? text : "");
-		deps.dispatchCommand(trimmed);
+		const steerMention = parseEditorSteerMention(trimmed);
+		if (steerMention) {
+			const submission = submitEditorSteerMention(steerMention);
+			if (submission !== "unhandled") {
+				if (submission === "rejected") {
+					throw new Error("queued boot steer was not admitted; preserving it for recovery");
+				}
+				deps.editor.addToHistory(text);
+				deps.ui.requestRender();
+				return;
+			}
+		}
+		const command = parseSlashCommand(trimmed);
+		if (isRejectedCommand(command)) {
+			signal?.throwIfAborted();
+			if (deps.dispatchCommandAsync) await deps.dispatchCommandAsync(trimmed, signal);
+			else deps.dispatchCommand(trimmed);
+			deps.ui.requestRender();
+			throw new Error("queued boot command needs correction; preserving it for recovery");
+		}
+		deps.editor.addToHistory(text);
+		signal?.throwIfAborted();
+		if (deps.dispatchCommandAsync) await deps.dispatchCommandAsync(trimmed, signal);
+		else deps.dispatchCommand(trimmed);
 		deps.ui.requestRender();
 	};
 
@@ -261,6 +443,7 @@ export function createEditorSubmitController(deps: EditorSubmitDeps): EditorSubm
 				deps.io.stderr("[follow-up] image references cannot be queued while a response is streaming\n");
 				return;
 			}
+			deps.beforeSemanticBoundary?.("follow-up-submit");
 			if (!deps.chat.queueFollowUp(submitted.text)) {
 				deps.io.stderr("[follow-up] no active response to queue against\n");
 				return;
@@ -274,6 +457,50 @@ export function createEditorSubmitController(deps: EditorSubmitDeps): EditorSubm
 		});
 	};
 
+	const interruptFromEditor = (): void => {
+		const text = deps.editor.getText().trim();
+		if (text.length === 0) return;
+		if (!deps.chat.isStreaming()) {
+			deps.editor.setText("");
+			submitEditorText(text);
+			deps.ui.requestRender();
+			return;
+		}
+		void (async () => {
+			const submitted = await deps.expandSubmit(text);
+			if (submitted.images.length > 0) {
+				deps.io.stderr("[interrupt] image references cannot be sent while a response is streaming\n");
+				return;
+			}
+			deps.editor.addToHistory(text);
+			// Same restore Esc performs: when the interrupt will really cancel the
+			// run, the queued steers and follow-ups come back to the editor rather
+			// than vanishing with the cancelled run. A refused interrupt cancels
+			// nothing, so the queue stays put.
+			const restored = deps.chat.interruptRefusal() === null ? deps.chat.clearQueuedFollowUps() : [];
+			deps.editor.setText(restored.join("\n\n"));
+			deps.ui.requestRender();
+			// An interrupt is a fresh prompt, so it carries what the idle path
+			// carries: the launchpad collapse, the submitted-turn count, and the
+			// expansion's working-context paths and pending skill requests. Only
+			// images stay behind, rejected above, as they are for a follow-up.
+			deps.collapseLaunchpadBeforeSubmit?.();
+			deps.sessionTranscript.recordSubmittedTurn();
+			const paths = submitted.workingContextPaths ?? [];
+			const skillRequests = submitted.pendingSkillRequests ?? [];
+			deps.beforeSemanticBoundary?.("interrupt-submit");
+			await deps.chat.submit(submitted.text, {
+				steering: "interrupt",
+				...(paths.length > 0 ? { workingContextPaths: paths } : {}),
+				...(skillRequests.length > 0 ? { pendingSkillRequests: skillRequests } : {}),
+			});
+			await deps.settleVisibleFrame?.("interrupt-submit-return");
+		})().catch((err) => {
+			const msg = err instanceof Error ? err.message : String(err);
+			deps.io.stderr(`[interrupt] ${msg}\n`);
+		});
+	};
+
 	const restoreQueuedFollowUpsToEditor = (): void => {
 		const restored = deps.chat.clearQueuedFollowUps();
 		if (restored.length === 0) {
@@ -291,7 +518,9 @@ export function createEditorSubmitController(deps: EditorSubmitDeps): EditorSubm
 		openExternalEditorForInput,
 		handleEditorSteerMention,
 		submitEditorText,
+		admitCapturedText,
 		queueFollowUpFromEditor,
+		interruptFromEditor,
 		restoreQueuedFollowUpsToEditor,
 		hasActiveEditorBash: () => activeEditorBash !== null,
 		cancelActiveEditorBash: () => {

package/src/interactive/export-html/ansi-to-html.ts

@@ -0,0 +1,161 @@
+/**
+ * Terminal ANSI to HTML conversion adapted from pi-coding-agent 0.84.0's
+ * `dist/core/export-html/ansi-to-html.js`.
+ *
+ * Clio's transcript also contains OSC 133 shell-integration markers and may
+ * contain other non-SGR terminal controls. Those controls are discarded here;
+ * only SGR presentation survives as inline HTML styles.
+ */
+
+const ANSI_COLORS = [
+	"rgb(0,0,0)",
+	"rgb(128,0,0)",
+	"rgb(0,128,0)",
+	"rgb(128,128,0)",
+	"rgb(0,0,128)",
+	"rgb(128,0,128)",
+	"rgb(0,128,128)",
+	"rgb(192,192,192)",
+	"rgb(128,128,128)",
+	"rgb(255,0,0)",
+	"rgb(0,255,0)",
+	"rgb(255,255,0)",
+	"rgb(0,0,255)",
+	"rgb(255,0,255)",
+	"rgb(0,255,255)",
+	"rgb(255,255,255)",
+] as const;
+
+interface TextStyle {
+	fg: string | null;
+	bg: string | null;
+	bold: boolean;
+	dim: boolean;
+	italic: boolean;
+	underline: boolean;
+}
+
+function color256ToHex(index: number): string {
+	const bounded = Math.max(0, Math.min(255, index));
+	if (bounded < 16) return ANSI_COLORS[bounded] ?? ANSI_COLORS[0];
+	if (bounded < 232) {
+		const cubeIndex = bounded - 16;
+		const component = (value: number): number => (value === 0 ? 0 : 55 + value * 40);
+		return `rgb(${component(Math.floor(cubeIndex / 36))},${component(Math.floor((cubeIndex % 36) / 6))},${component(cubeIndex % 6)})`;
+	}
+	const gray = 8 + (bounded - 232) * 10;
+	return `rgb(${gray},${gray},${gray})`;
+}
+
+export function escapeHtml(text: string): string {
+	return text
+		.replace(/&/gu, "&amp;")
+		.replace(/</gu, "&lt;")
+		.replace(/>/gu, "&gt;")
+		.replace(/"/gu, "&quot;")
+		.replace(/'/gu, "&#039;");
+}
+
+function createEmptyStyle(): TextStyle {
+	return { fg: null, bg: null, bold: false, dim: false, italic: false, underline: false };
+}
+
+function styleToInlineCss(style: TextStyle): string {
+	const parts: string[] = [];
+	if (style.fg) parts.push(`color:${style.fg}`);
+	if (style.bg) parts.push(`background-color:${style.bg}`);
+	if (style.bold) parts.push("font-weight:bold");
+	if (style.dim) parts.push("opacity:0.6");
+	if (style.italic) parts.push("font-style:italic");
+	if (style.underline) parts.push("text-decoration:underline");
+	return parts.join(";");
+}
+
+function hasStyle(style: TextStyle): boolean {
+	return style.fg !== null || style.bg !== null || style.bold || style.dim || style.italic || style.underline;
+}
+
+function applySgrCode(params: number[], style: TextStyle): void {
+	let index = 0;
+	while (index < params.length) {
+		const code = params[index] ?? 0;
+		if (code === 0) Object.assign(style, createEmptyStyle());
+		else if (code === 1) style.bold = true;
+		else if (code === 2) style.dim = true;
+		else if (code === 3) style.italic = true;
+		else if (code === 4) style.underline = true;
+		else if (code === 22) {
+			style.bold = false;
+			style.dim = false;
+		} else if (code === 23) style.italic = false;
+		else if (code === 24) style.underline = false;
+		else if (code >= 30 && code <= 37) style.fg = ANSI_COLORS[code - 30] ?? null;
+		else if (code === 38) {
+			if (params[index + 1] === 5 && params[index + 2] !== undefined) {
+				style.fg = color256ToHex(params[index + 2] ?? 0);
+				index += 2;
+			} else if (params[index + 1] === 2 && params[index + 4] !== undefined) {
+				style.fg = `rgb(${params[index + 2]},${params[index + 3]},${params[index + 4]})`;
+				index += 4;
+			}
+		} else if (code === 39) style.fg = null;
+		else if (code >= 40 && code <= 47) style.bg = ANSI_COLORS[code - 40] ?? null;
+		else if (code === 48) {
+			if (params[index + 1] === 5 && params[index + 2] !== undefined) {
+				style.bg = color256ToHex(params[index + 2] ?? 0);
+				index += 2;
+			} else if (params[index + 1] === 2 && params[index + 4] !== undefined) {
+				style.bg = `rgb(${params[index + 2]},${params[index + 3]},${params[index + 4]})`;
+				index += 4;
+			}
+		} else if (code === 49) style.bg = null;
+		else if (code >= 90 && code <= 97) style.fg = ANSI_COLORS[code - 90 + 8] ?? null;
+		else if (code >= 100 && code <= 107) style.bg = ANSI_COLORS[code - 100 + 8] ?? null;
+		index += 1;
+	}
+}
+
+// CSI, OSC, DCS/SOS/PM/APC, and single-character ESC sequences. SGR CSI
+// sequences are interpreted; every other terminal control is removed.
+const ESC = String.fromCharCode(27);
+const BEL = String.fromCharCode(7);
+const TERMINAL_SEQUENCE = new RegExp(
+	`${ESC}(?:\\[([0-?]*[ -/]*)([@-~])|\\][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)|[PX^_][\\s\\S]*?${ESC}\\\\|[@-_])`,
+	"gu",
+);
+
+export function ansiToHtml(text: string): string {
+	const style = createEmptyStyle();
+	let result = "";
+	let lastIndex = 0;
+	let spanOpen = false;
+	TERMINAL_SEQUENCE.lastIndex = 0;
+	let match = TERMINAL_SEQUENCE.exec(text);
+	while (match !== null) {
+		result += escapeHtml(text.slice(lastIndex, match.index));
+		if (match[2] === "m") {
+			if (spanOpen) result += "</span>";
+			const raw = match[1] ?? "";
+			const params = raw.length > 0 ? raw.split(";").map((part) => Number.parseInt(part, 10) || 0) : [0];
+			applySgrCode(params, style);
+			spanOpen = hasStyle(style);
+			if (spanOpen) result += `<span style="${styleToInlineCss(style)}">`;
+		}
+		lastIndex = match.index + match[0].length;
+		match = TERMINAL_SEQUENCE.exec(text);
+	}
+	result += escapeHtml(text.slice(lastIndex));
+	if (spanOpen) result += "</span>";
+	// A raw C0 control is never meaningful inside the exported document. Tabs
+	// remain useful in preformatted tool output and are safe in HTML text.
+	return Array.from(result)
+		.filter((character) => {
+			const code = character.charCodeAt(0);
+			return code === 9 || (code >= 32 && code !== 127);
+		})
+		.join("");
+}
+
+export function ansiLinesToHtml(lines: ReadonlyArray<string>): string {
+	return lines.map((line) => `<div class="ansi-line">${ansiToHtml(line) || "&nbsp;"}</div>`).join("\n");
+}

package/src/interactive/export-html/index.ts

@@ -0,0 +1,51 @@
+import { htmlTemplate } from "./template.js";
+import { renderTranscriptHtml } from "./tool-renderer.js";
+
+export const MAX_HTML_EXPORT_BYTES = 2 * 1024 * 1024;
+const TEMPLATE_RESERVE_BYTES = 8 * 1024;
+
+export interface HtmlSessionExportInput {
+	sessionId: string;
+	exportedAt: string;
+	ansiLines: ReadonlyArray<string>;
+	maxBytes?: number;
+}
+
+/**
+ * Build the bounded, self-contained HTML document used by `/export`.
+ * Whole rendered rows are admitted until the byte budget is full, so the
+ * result never cuts an ANSI sequence, Unicode scalar, span, or tool section.
+ */
+export function renderSessionHtml(input: HtmlSessionExportInput): string {
+	const maxBytes = input.maxBytes ?? MAX_HTML_EXPORT_BYTES;
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < TEMPLATE_RESERVE_BYTES * 2) {
+		throw new Error(`HTML export size limit must be at least ${TEMPLATE_RESERVE_BYTES * 2} bytes`);
+	}
+	const lineBudget = maxBytes - TEMPLATE_RESERVE_BYTES;
+	const selected: string[] = [];
+	let renderedBytes = 0;
+	let truncated = false;
+	for (const line of input.ansiLines) {
+		const rendered = renderTranscriptHtml([line]);
+		const bytes = Buffer.byteLength(rendered, "utf8") + 1;
+		if (renderedBytes + bytes > lineBudget) {
+			truncated = true;
+			break;
+		}
+		selected.push(line);
+		renderedBytes += bytes;
+	}
+	const html = htmlTemplate({
+		sessionId: input.sessionId,
+		exportedAt: input.exportedAt,
+		transcriptHtml: renderTranscriptHtml(selected),
+		truncated,
+	});
+	if (Buffer.byteLength(html, "utf8") > maxBytes) {
+		throw new Error(`HTML export exceeded its ${maxBytes}-byte size limit`);
+	}
+	return html;
+}
+
+export { ansiLinesToHtml, ansiToHtml } from "./ansi-to-html.js";
+export { renderTranscriptHtml } from "./tool-renderer.js";