Add files using upload-large-folder tool

packages/agent/src/harness/tools/write.ts

@@ -0,0 +1,44 @@
+import { type Static, Type } from "typebox";
+import type { AgentHarnessTool } from "../types.ts";
+import { getOrThrow } from "../types.ts";
+import { withFileMutationQueue } from "./file-mutation-queue.ts";
+import { resolveToolPath } from "./path-utils.ts";
+import type { ExecutionToolContext } from "./tool-context.ts";
+
+const writeSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to write (relative or absolute)" }),
+	content: Type.String({ description: "Content to write to the file" }),
+});
+
+export type WriteToolInput = Static<typeof writeSchema>;
+
+export function createWriteTool<TContext extends ExecutionToolContext = ExecutionToolContext>(): AgentHarnessTool<
+	TContext,
+	typeof writeSchema,
+	undefined
+> {
+	return {
+		name: "write",
+		label: "write",
+		description:
+			"Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+		parameters: writeSchema,
+		async execute(_toolCallId, { path, content }, _onUpdate, { env }, _invocation, context) {
+			const absolutePath = await resolveToolPath(env, path, context);
+			return withFileMutationQueue(
+				env,
+				absolutePath,
+				async () => {
+					if (context.abortSignal?.aborted) throw new Error("Operation aborted");
+					getOrThrow(await env.writeFile(absolutePath, content, context));
+					if (context.abortSignal?.aborted) throw new Error("Operation aborted");
+					return {
+						content: [{ type: "text", text: `Successfully wrote to ${path}` }],
+						details: undefined,
+					};
+				},
+				context,
+			);
+		},
+	};
+}

packages/coding-agent/docs/tui.md

@@ -0,0 +1,961 @@
+> pi can create TUI components. Ask it to build one for your use case.
+
+# TUI Components
+
+Extensions and custom tools can render custom TUI components for interactive user interfaces. This page covers the component system and available building blocks.
+
+**Source:** [`@earendil-works/pi-tui`](https://github.com/earendil-works/pi/tree/main/packages/tui)
+
+## Component Interface
+
+All components implement:
+
+```typescript
+interface Component {
+  render(width: number): string[];
+  handleInput?(data: string): void;
+  handleMouse?(event: TuiMouseEvent): TuiMouseEventResult | undefined;
+  wantsKeyRelease?: boolean;
+  invalidate(): void;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `render(width)` | Return array of strings (one per line). Each line **must not exceed `width`**. |
+| `handleInput?(data)` | Receive keyboard input when component has focus. |
+| `handleMouse?(event)` | Receive normalized pointer input in fullscreen mode. |
+| `wantsKeyRelease?` | If true, component receives key release events (Kitty protocol). Default: false. |
+| `invalidate()` | Clear cached render state. Called on theme changes. |
+
+The TUI appends a full SGR reset and OSC 8 reset at the end of each rendered line. Styles do not carry across lines. If you emit multi-line text with styling, reapply styles per line or use `wrapTextWithAnsi()` so styles are preserved for each wrapped line.
+
+## Focusable Interface (IME Support)
+
+Components that display a text cursor and need IME (Input Method Editor) support should implement the `Focusable` interface:
+
+```typescript
+import { CURSOR_MARKER, type Component, type Focusable } from "@earendil-works/pi-tui";
+
+class MyInput implements Component, Focusable {
+  focused: boolean = false;  // Set by TUI when focus changes
+  
+  render(width: number): string[] {
+    const marker = this.focused ? CURSOR_MARKER : "";
+    // Emit marker right before the fake cursor
+    return [`> ${beforeCursor}${marker}\x1b[7m${atCursor}\x1b[27m${afterCursor}`];
+  }
+}
+```
+
+When a `Focusable` component has focus, TUI:
+1. Sets `focused = true` on the component
+2. Scans rendered output for `CURSOR_MARKER` (a zero-width APC escape sequence)
+3. Positions the hardware terminal cursor at that location
+4. Shows the hardware cursor only when `showHardwareCursor` is enabled
+
+The cursor remains hidden by default. This keeps the fake cursor rendering, while still positioning the hardware cursor for terminals that track IME candidate windows with hidden cursors. Some terminals require a visible hardware cursor for IME positioning; enable it with the renderer's `showHardwareCursor` constructor argument or `setShowHardwareCursor(true)`. Pi also maps `PI_HARDWARE_CURSOR=1` to this setting before it creates its renderer. The `Editor` and `Input` built-in components already implement this interface.
+
+### Container Components with Embedded Inputs
+
+When a container component (dialog, selector, etc.) contains an `Input` or `Editor` child, the container must implement `Focusable` and propagate the focus state to the child. Otherwise, the hardware cursor won't be positioned correctly for IME input.
+
+```typescript
+import { Container, type Focusable, Input } from "@earendil-works/pi-tui";
+
+class SearchDialog extends Container implements Focusable {
+  private searchInput: Input;
+
+  // Focusable implementation - propagate to child input for IME cursor positioning
+  private _focused = false;
+  get focused(): boolean {
+    return this._focused;
+  }
+  set focused(value: boolean) {
+    this._focused = value;
+    this.searchInput.focused = value;
+  }
+
+  constructor() {
+    super();
+    this.searchInput = new Input();
+    this.addChild(this.searchInput);
+  }
+}
+```
+
+Without this propagation, typing with an IME (Chinese, Japanese, Korean, etc.) will show the candidate window in the wrong position on screen.
+
+## Using Components
+
+**In extensions** via `ctx.ui.custom()`:
+
+```typescript
+pi.on("session_start", async (_event, ctx) => {
+  const result = await ctx.ui.custom<string | null>((tui, theme, keybindings, done) =>
+    new MyComponent({
+      theme,
+      keybindings,
+      onChange: () => tui.requestRender(),
+      onSelect: (value) => done(value),
+      onCancel: () => done(null),
+    })
+  );
+});
+```
+
+**In custom tools** via `ctx.ui.custom()`:
+
+```typescript
+async execute(toolCallId, params, signal, onUpdate, ctx) {
+  const result = await ctx.ui.custom<string | null>((tui, theme, keybindings, done) =>
+    new MyComponent({
+      theme,
+      keybindings,
+      onChange: () => tui.requestRender(),
+      onSelect: (value) => done(value),
+      onCancel: () => done(null),
+    })
+  );
+  // Use result...
+}
+```
+
+## Overlays
+
+Overlays render components on top of existing content without clearing the screen. Pass `{ overlay: true }` to `ctx.ui.custom()`:
+
+```typescript
+const result = await ctx.ui.custom<string | null>(
+  (tui, theme, keybindings, done) => new MyDialog({ onClose: done }),
+  { overlay: true }
+);
+```
+
+For positioning and sizing, use `overlayOptions`:
+
+```typescript
+const result = await ctx.ui.custom<string | null>(
+  (tui, theme, keybindings, done) => new SidePanel({ onClose: done }),
+  {
+    overlay: true,
+    overlayOptions: {
+      // Size: number or percentage string
+      width: "50%",          // 50% of terminal width
+      minWidth: 40,          // minimum 40 columns
+      maxHeight: "80%",      // max 80% of terminal height
+
+      // Position: anchor-based (default: "center")
+      anchor: "right-center", // 9 positions: center, top-left, top-center, etc.
+      offsetX: -2,            // offset from anchor
+      offsetY: 0,
+
+      // Or percentage/absolute positioning
+      row: "25%",            // 25% from top
+      col: 10,               // column 10
+
+      // Margins
+      margin: 2,             // all sides, or { top, right, bottom, left }
+
+      // Responsive: hide on narrow terminals
+      visible: (termWidth, termHeight) => termWidth >= 80,
+    },
+    // Get handle for programmatic focus and visibility control
+    onHandle: (handle) => {
+      // handle.focus() - focus this overlay and bring it to the visual front
+      // handle.unfocus() - release input to normal fallback
+      // handle.unfocus({ target }) - release input to a specific component or null
+      // handle.setHidden(true/false) - toggle visibility
+      // handle.hide() - permanently remove
+    },
+  }
+);
+```
+
+### Overlay Focus
+
+A focused visible overlay keeps input ownership across temporary non-overlay UI. If an overlay opens another `ctx.ui.custom()` component without `{ overlay: true }`, that replacement UI receives input while it is active; when it closes, the focused overlay can reclaim input.
+
+Use `handle.unfocus()` when a visible overlay should stop owning input and let TUI fall back to another visible capturing overlay or the previous focus target. Use `handle.unfocus({ target })` when a specific component should receive input while the overlay stays visible. Passing `{ target: null }` intentionally leaves no focused component until focus is set again.
+
+### Overlay Lifecycle
+
+Overlay components are disposed when closed. Don't reuse references - create fresh instances:
+
+```typescript
+// Wrong - stale reference
+let menu: MenuComponent;
+await ctx.ui.custom((_, __, ___, done) => {
+  menu = new MenuComponent(done);
+  return menu;
+}, { overlay: true });
+setActiveComponent(menu);  // Disposed
+
+// Correct - re-call to re-show
+const showMenu = () => ctx.ui.custom((_, __, ___, done) => 
+  new MenuComponent(done), { overlay: true });
+
+await showMenu();  // First show
+await showMenu();  // "Back" = just call again
+```
+
+See [overlay-qa-tests.ts](../examples/extensions/overlay-qa-tests.ts) for comprehensive examples covering anchors, margins, stacking, responsive visibility, and animation.
+
+## Built-in Components
+
+Import from `@earendil-works/pi-tui`:
+
+```typescript
+import { Text, Box, Container, Spacer, Markdown } from "@earendil-works/pi-tui";
+```
+
+### Text
+
+Multi-line text with word wrapping.
+
+```typescript
+const text = new Text(
+  "Hello World",    // content
+  1,                // paddingX (default: 1)
+  1,                // paddingY (default: 1)
+  (s) => bgGray(s)  // optional background function
+);
+text.setText("Updated");
+```
+
+### Box
+
+Container with padding and background color.
+
+```typescript
+const box = new Box(
+  1,                // paddingX
+  1,                // paddingY
+  (s) => bgGray(s)  // background function
+);
+box.addChild(new Text("Content", 0, 0));
+box.setBgFn((s) => bgBlue(s));
+```
+
+### Container
+
+Groups child components vertically.
+
+```typescript
+const container = new Container();
+container.addChild(component1);
+container.addChild(component2);
+container.removeChild(component1);
+```
+
+### Spacer
+
+Empty vertical space.
+
+```typescript
+const spacer = new Spacer(2);  // 2 empty lines
+```
+
+### Markdown
+
+Renders markdown with syntax highlighting.
+
+```typescript
+const md = new Markdown(
+  "# Title\n\nSome **bold** text",
+  1,        // paddingX
+  1,        // paddingY
+  theme     // MarkdownTheme (see below)
+);
+md.setText("Updated markdown");
+```
+
+### Image
+
+Renders images in supported terminals (Kitty, iTerm2, Ghostty, WezTerm, Warp).
+
+```typescript
+const image = new Image(
+  base64Data,   // base64-encoded image
+  "image/png",  // MIME type
+  theme,        // ImageTheme
+  { maxWidthCells: 80, maxHeightCells: 24 }
+);
+```
+
+## Keyboard Input
+
+Use `matchesKey()` for key detection:
+
+```typescript
+import { matchesKey, Key } from "@earendil-works/pi-tui";
+
+handleInput(data: string) {
+  if (matchesKey(data, Key.up)) {
+    this.selectedIndex--;
+  } else if (matchesKey(data, Key.enter)) {
+    this.onSelect?.(this.selectedIndex);
+  } else if (matchesKey(data, Key.escape)) {
+    this.onCancel?.();
+  } else if (matchesKey(data, Key.ctrl("c"))) {
+    // Ctrl+C
+  }
+}
+```
+
+**Key identifiers** (use `Key.*` for autocomplete, or string literals):
+- Basic keys: `Key.enter`, `Key.escape`, `Key.tab`, `Key.space`, `Key.backspace`, `Key.delete`, `Key.home`, `Key.end`
+- Arrow keys: `Key.up`, `Key.down`, `Key.left`, `Key.right`
+- With modifiers: `Key.ctrl("c")`, `Key.shift("tab")`, `Key.alt("left")`, `Key.ctrlShift("p")`
+- String format also works: `"enter"`, `"ctrl+c"`, `"shift+tab"`, `"ctrl+shift+p"`
+
+## Mouse Input
+
+Fullscreen mode routes normalized press, release, click, move, drag, and wheel events to components and overlays. Return `{ handled: true }` to suppress default behavior, `capture: true` to retain drag/release ownership, `focus: true` to request keyboard focus, and `render: true` when a hover or release visibly changes the component. Press, click, drag, and wheel render by default; no-op move/release events do not.
+
+```typescript
+import { MouseRegion } from "@earendil-works/pi-tui";
+
+const clickable = new MouseRegion(content, (event) => {
+  if (event.type !== "click" || event.button !== "left") return undefined;
+  expanded = !expanded;
+  return { handled: true };
+});
+```
+
+Unhandled wheel input scrolls the nearest `ScrollView`; unhandled primary-button drags retain transcript selection. OSC 8 links take precedence over parent click regions. `Input`, `Editor`, `SelectList`, and `SettingsList` include fullscreen mouse behavior. Regular mode does not capture mouse input because the terminal owns its scrollback.
+
+## Line Width
+
+**Critical:** Each line from `render()` must not exceed the `width` parameter.
+
+```typescript
+import { visibleWidth, truncateToWidth } from "@earendil-works/pi-tui";
+
+render(width: number): string[] {
+  // Truncate long lines
+  return [truncateToWidth(this.text, width)];
+}
+```
+
+Utilities:
+- `visibleWidth(str)` - Get display width (ignores ANSI codes)
+- `truncateToWidth(str, width, ellipsis?)` - Truncate with optional ellipsis
+- `wrapTextWithAnsi(str, width)` - Word wrap preserving ANSI codes
+
+## Creating Custom Components
+
+Example: Interactive selector
+
+```typescript
+import {
+  matchesKey, Key,
+  truncateToWidth, visibleWidth
+} from "@earendil-works/pi-tui";
+
+class MySelector {
+  private items: string[];
+  private selected = 0;
+  private cachedWidth?: number;
+  private cachedLines?: string[];
+  
+  public onSelect?: (item: string) => void;
+  public onCancel?: () => void;
+
+  constructor(items: string[]) {
+    this.items = items;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.up) && this.selected > 0) {
+      this.selected--;
+      this.invalidate();
+    } else if (matchesKey(data, Key.down) && this.selected < this.items.length - 1) {
+      this.selected++;
+      this.invalidate();
+    } else if (matchesKey(data, Key.enter)) {
+      this.onSelect?.(this.items[this.selected]);
+    } else if (matchesKey(data, Key.escape)) {
+      this.onCancel?.();
+    }
+  }
+
+  render(width: number): string[] {
+    if (this.cachedLines && this.cachedWidth === width) {
+      return this.cachedLines;
+    }
+
+    this.cachedLines = this.items.map((item, i) => {
+      const prefix = i === this.selected ? "> " : "  ";
+      return truncateToWidth(prefix + item, width);
+    });
+    this.cachedWidth = width;
+    return this.cachedLines;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+}
+```
+
+Usage in an extension:
+
+```typescript
+pi.registerCommand("pick", {
+  description: "Pick an item",
+  handler: async (_args, ctx) => {
+    const items = ["Option A", "Option B", "Option C"];
+    const selected = await ctx.ui.custom<string | null>((tui, _theme, _keybindings, done) => {
+      const selector = new MySelector(items);
+      selector.onSelect = done;
+      selector.onCancel = () => done(null);
+
+      return {
+        render: (width) => selector.render(width),
+        handleInput: (data) => {
+          selector.handleInput(data);
+          tui.requestRender();
+        },
+        invalidate: () => selector.invalidate(),
+      };
+    });
+
+    if (selected !== null) {
+      ctx.ui.notify(`Selected: ${selected}`, "info");
+    }
+  }
+});
+```
+
+## Theming
+
+Components accept theme objects for styling.
+
+**In `renderCall`/`renderResult`**, use the `theme` parameter:
+
+```typescript
+renderResult(result, options, theme, context) {
+  // Use theme.fg() for foreground colors
+  return new Text(theme.fg("success", "Done!"), 0, 0);
+  
+  // Use theme.bg() for background colors
+  const styled = theme.bg("toolPendingBg", theme.fg("accent", "text"));
+}
+```
+
+**Foreground colors** (`theme.fg(color, text)`):
+
+| Category | Colors |
+|----------|--------|
+| General | `text`, `accent`, `muted`, `dim`, `searchMatchText` |
+| Status | `success`, `error`, `warning` |
+| Borders | `border`, `borderAccent`, `borderMuted` |
+| Messages | `userMessageText`, `customMessageText`, `customMessageLabel` |
+| Tools | `toolTitle`, `toolOutput` |
+| Diffs | `toolDiffAdded`, `toolDiffRemoved`, `toolDiffContext` |
+| Markdown | `mdHeading`, `mdLink`, `mdLinkUrl`, `mdCode`, `mdCodeBlock`, `mdCodeBlockBorder`, `mdQuote`, `mdQuoteBorder`, `mdHr`, `mdListBullet` |
+| Syntax | `syntaxComment`, `syntaxKeyword`, `syntaxFunction`, `syntaxVariable`, `syntaxString`, `syntaxNumber`, `syntaxType`, `syntaxOperator`, `syntaxPunctuation` |
+| Thinking | `thinkingOff`, `thinkingMinimal`, `thinkingLow`, `thinkingMedium`, `thinkingHigh`, `thinkingXhigh`, `thinkingMax` |
+| Modes | `bashMode` |
+
+**Background colors** (`theme.bg(color, text)`):
+
+`selectedBg`, `searchMatchBg`, `userMessageBg`, `customMessageBg`, `toolPendingBg`, `toolSuccessBg`, `toolErrorBg`
+
+**For Markdown**, use `getMarkdownTheme()`:
+
+```typescript
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Markdown } from "@earendil-works/pi-tui";
+
+renderResult(result, options, theme, context) {
+  const mdTheme = getMarkdownTheme();
+  return new Markdown(result.details.markdown, 0, 0, mdTheme);
+}
+```
+
+**For custom components**, define your own theme interface:
+
+```typescript
+interface MyTheme {
+  selected: (s: string) => string;
+  normal: (s: string) => string;
+}
+```
+
+## Debug logging
+
+Set `PI_TUI_WRITE_LOG` to capture the raw ANSI stream written to stdout.
+
+```bash
+PI_TUI_WRITE_LOG=/tmp/tui-ansi.log npx tsx packages/tui/test/chat-simple.ts
+```
+
+## Performance
+
+Cache rendered output when possible:
+
+```typescript
+class CachedComponent {
+  private cachedWidth?: number;
+  private cachedLines?: string[];
+
+  render(width: number): string[] {
+    if (this.cachedLines && this.cachedWidth === width) {
+      return this.cachedLines;
+    }
+    // ... compute lines ...
+    this.cachedWidth = width;
+    this.cachedLines = lines;
+    return lines;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+}
+```
+
+Call `invalidate()` when state changes, then use the injected `tui.requestRender()` to trigger re-render.
+
+## Invalidation and Theme Changes
+
+When the theme changes, the TUI calls `invalidate()` on all components to clear their caches. Components must properly implement `invalidate()` to ensure theme changes take effect.
+
+### The Problem
+
+If a component pre-bakes theme colors into strings (via `theme.fg()`, `theme.bg()`, etc.) and caches them, the cached strings contain ANSI escape codes from the old theme. Simply clearing the render cache isn't enough if the component stores the themed content separately.
+
+**Wrong approach** (theme colors won't update):
+
+```typescript
+class BadComponent extends Container {
+  private content: Text;
+
+  constructor(message: string, theme: Theme) {
+    super();
+    // Pre-baked theme colors stored in Text component
+    this.content = new Text(theme.fg("accent", message), 1, 0);
+    this.addChild(this.content);
+  }
+  // No invalidate override - parent's invalidate only clears
+  // child render caches, not the pre-baked content
+}
+```
+
+### The Solution
+
+Components that build content with theme colors must rebuild that content when `invalidate()` is called:
+
+```typescript
+class GoodComponent extends Container {
+  private message: string;
+  private content: Text;
+
+  constructor(message: string) {
+    super();
+    this.message = message;
+    this.content = new Text("", 1, 0);
+    this.addChild(this.content);
+    this.updateDisplay();
+  }
+
+  private updateDisplay(): void {
+    // Rebuild content with current theme
+    this.content.setText(theme.fg("accent", this.message));
+  }
+
+  override invalidate(): void {
+    super.invalidate();  // Clear child caches
+    this.updateDisplay(); // Rebuild with new theme
+  }
+}
+```
+
+### Pattern: Rebuild on Invalidate
+
+For components with complex content:
+
+```typescript
+class ComplexComponent extends Container {
+  private data: SomeData;
+
+  constructor(data: SomeData) {
+    super();
+    this.data = data;
+    this.rebuild();
+  }
+
+  private rebuild(): void {
+    this.clear();  // Remove all children
+
+    // Build UI with current theme
+    this.addChild(new Text(theme.fg("accent", theme.bold("Title")), 1, 0));
+    this.addChild(new Spacer(1));
+
+    for (const item of this.data.items) {
+      const color = item.active ? "success" : "muted";
+      this.addChild(new Text(theme.fg(color, item.label), 1, 0));
+    }
+  }
+
+  override invalidate(): void {
+    super.invalidate();
+    this.rebuild();
+  }
+}
+```
+
+### When This Matters
+
+This pattern is needed when:
+
+1. **Pre-baking theme colors** - Using `theme.fg()` or `theme.bg()` to create styled strings stored in child components
+2. **Syntax highlighting** - Using `highlightCode()` which applies theme-based syntax colors
+3. **Complex layouts** - Building child component trees that embed theme colors
+
+This pattern is NOT needed when:
+
+1. **Using theme callbacks** - Passing functions like `(text) => theme.fg("accent", text)` that are called during render
+2. **Simple containers** - Just grouping other components without adding themed content
+3. **Stateless render** - Computing themed output fresh in every `render()` call (no caching)
+
+## Common Patterns
+
+These patterns cover the most common UI needs in extensions. **Copy these patterns instead of building from scratch.**
+
+### Pattern 1: Selection Dialog (SelectList)
+
+For letting users pick from a list of options. Use `SelectList` from `@earendil-works/pi-tui` with `DynamicBorder` for framing.
+
+```typescript
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, type SelectItem, SelectList, Text } from "@earendil-works/pi-tui";
+
+pi.registerCommand("pick", {
+  handler: async (_args, ctx) => {
+    const items: SelectItem[] = [
+      { value: "opt1", label: "Option 1", description: "First option" },
+      { value: "opt2", label: "Option 2", description: "Second option" },
+      { value: "opt3", label: "Option 3" },  // description is optional
+    ];
+
+    const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+      const container = new Container();
+
+      // Top border
+      container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+      // Title
+      container.addChild(new Text(theme.fg("accent", theme.bold("Pick an Option")), 1, 0));
+
+      // SelectList with theme
+      const selectList = new SelectList(items, Math.min(items.length, 10), {
+        selectedPrefix: (t) => theme.fg("accent", t),
+        selectedText: (t) => theme.fg("accent", t),
+        description: (t) => theme.fg("muted", t),
+        scrollInfo: (t) => theme.fg("dim", t),
+        noMatch: (t) => theme.fg("warning", t),
+      });
+      selectList.onSelect = (item) => done(item.value);
+      selectList.onCancel = () => done(null);
+      container.addChild(selectList);
+
+      // Help text
+      container.addChild(new Text(theme.fg("dim", "↑↓ navigate • enter select • esc cancel"), 1, 0));
+
+      // Bottom border
+      container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+      return {
+        render: (w) => container.render(w),
+        invalidate: () => container.invalidate(),
+        handleInput: (data) => { selectList.handleInput(data); tui.requestRender(); },
+      };
+    });
+
+    if (result) {
+      ctx.ui.notify(`Selected: ${result}`, "info");
+    }
+  },
+});
+```
+
+**Examples:** [preset.ts](../examples/extensions/preset.ts), [tools.ts](../examples/extensions/tools.ts)
+
+### Pattern 2: Async Operation with Cancel (BorderedLoader)
+
+For operations that take time and should be cancellable. `BorderedLoader` shows a spinner and handles escape to cancel.
+
+```typescript
+import { BorderedLoader } from "@earendil-works/pi-coding-agent";
+
+pi.registerCommand("fetch", {
+  handler: async (_args, ctx) => {
+    const result = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+      const loader = new BorderedLoader(tui, theme, "Fetching data...");
+      loader.onAbort = () => done(null);
+
+      // Do async work
+      fetchData(loader.signal)
+        .then((data) => done(data))
+        .catch(() => done(null));
+
+      return loader;
+    });
+
+    if (result === null) {
+      ctx.ui.notify("Cancelled", "info");
+    } else {
+      ctx.ui.setEditorText(result);
+    }
+  },
+});
+```
+
+**Examples:** [qna.ts](../examples/extensions/qna.ts), [handoff.ts](../examples/extensions/handoff.ts)
+
+### Pattern 3: Settings/Toggles (SettingsList)
+
+For toggling multiple settings. Use `SettingsList` from `@earendil-works/pi-tui` with `getSettingsListTheme()`.
+
+```typescript
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import { Container, type SettingItem, SettingsList, Text } from "@earendil-works/pi-tui";
+
+pi.registerCommand("settings", {
+  handler: async (_args, ctx) => {
+    const items: SettingItem[] = [
+      { id: "verbose", label: "Verbose mode", currentValue: "off", values: ["on", "off"] },
+      { id: "color", label: "Color output", currentValue: "on", values: ["on", "off"] },
+    ];
+
+    await ctx.ui.custom((_tui, theme, _kb, done) => {
+      const container = new Container();
+      container.addChild(new Text(theme.fg("accent", theme.bold("Settings")), 1, 1));
+
+      const settingsList = new SettingsList(
+        items,
+        Math.min(items.length + 2, 15),
+        getSettingsListTheme(),
+        (id, newValue) => {
+          // Handle value change
+          ctx.ui.notify(`${id} = ${newValue}`, "info");
+        },
+        () => done(undefined),  // On close
+        { enableSearch: true }, // Optional: enable fuzzy search by label
+      );
+      container.addChild(settingsList);
+
+      return {
+        render: (w) => container.render(w),
+        invalidate: () => container.invalidate(),
+        handleInput: (data) => settingsList.handleInput?.(data),
+      };
+    });
+  },
+});
+```
+
+**Examples:** [tools.ts](../examples/extensions/tools.ts)
+
+### Pattern 4: Persistent Status Indicator
+
+Show status in the footer that persists across renders. Good for mode indicators.
+
+```typescript
+// Set status (shown in footer)
+ctx.ui.setStatus("my-ext", ctx.ui.theme.fg("accent", "● active"));
+
+// Clear status
+ctx.ui.setStatus("my-ext", undefined);
+```
+
+**Examples:** [status-line.ts](../examples/extensions/status-line.ts), [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts), [preset.ts](../examples/extensions/preset.ts)
+
+### Pattern 4b: Working Indicator Customization
+
+Customize the inline working indicator shown while pi is streaming a response.
+
+```typescript
+// Static indicator
+ctx.ui.setWorkingIndicator({ frames: [ctx.ui.theme.fg("accent", "●")] });
+
+// Custom animated indicator
+ctx.ui.setWorkingIndicator({
+  frames: [
+    ctx.ui.theme.fg("dim", "·"),
+    ctx.ui.theme.fg("muted", "•"),
+    ctx.ui.theme.fg("accent", "●"),
+    ctx.ui.theme.fg("muted", "•"),
+  ],
+  intervalMs: 120,
+});
+
+// Hide the indicator entirely
+ctx.ui.setWorkingIndicator({ frames: [] });
+
+// Restore pi's default spinner
+ctx.ui.setWorkingIndicator();
+```
+
+This only affects the normal streaming working indicator. Compaction and retry loaders keep their built-in styling. Custom frames are rendered verbatim, so extensions must add their own colors when needed.
+
+**Examples:** [working-indicator.ts](../examples/extensions/working-indicator.ts)
+
+### Pattern 5: Widgets Above/Below Editor
+
+Show persistent content above or below the input editor. Good for todo lists, progress.
+
+```typescript
+// Simple string array (above editor by default)
+ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"]);
+
+// Render below the editor
+ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"], { placement: "belowEditor" });
+
+// Or with theme
+ctx.ui.setWidget("my-widget", (_tui, theme) => {
+  const lines = items.map((item, i) =>
+    item.done
+      ? theme.fg("success", "✓ ") + theme.fg("muted", item.text)
+      : theme.fg("dim", "○ ") + item.text
+  );
+  return {
+    render: () => lines,
+    invalidate: () => {},
+  };
+});
+
+// Clear
+ctx.ui.setWidget("my-widget", undefined);
+```
+
+**Examples:** [plan-mode/index.ts](../examples/extensions/plan-mode/index.ts)
+
+### Pattern 6: Custom Footer
+
+Replace the footer. `footerData` exposes data not otherwise accessible to extensions.
+
+```typescript
+ctx.ui.setFooter((tui, theme, footerData) => ({
+  invalidate() {},
+  render(width: number): string[] {
+    // footerData.getGitBranch(): string | null
+    // footerData.getExtensionStatuses(): ReadonlyMap<string, string>
+    return [`${ctx.model?.id} (${footerData.getGitBranch() || "no git"})`];
+  },
+  dispose: footerData.onBranchChange(() => tui.requestRender()), // reactive
+}));
+
+ctx.ui.setFooter(undefined); // restore default
+```
+
+Token stats available via `ctx.sessionManager.getBranch()` and `ctx.model`.
+
+**Examples:** [custom-footer.ts](../examples/extensions/custom-footer.ts)
+
+### Pattern 7: Custom Editor (vim mode, etc.)
+
+Replace the main input editor with a custom implementation. Useful for modal editing (vim), different keybindings (emacs), or specialized input handling.
+
+```typescript
+import { CustomEditor, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
+
+type Mode = "normal" | "insert";
+
+class VimEditor extends CustomEditor {
+  private mode: Mode = "insert";
+
+  handleInput(data: string): void {
+    // Escape: switch to normal mode, or pass through for app handling
+    if (matchesKey(data, "escape")) {
+      if (this.mode === "insert") {
+        this.mode = "normal";
+        return;
+      }
+      // In normal mode, escape aborts agent (handled by CustomEditor)
+      super.handleInput(data);
+      return;
+    }
+
+    // Insert mode: pass everything to CustomEditor
+    if (this.mode === "insert") {
+      super.handleInput(data);
+      return;
+    }
+
+    // Normal mode: vim-style navigation
+    switch (data) {
+      case "i": this.mode = "insert"; return;
+      case "h": super.handleInput("\x1b[D"); return; // Left
+      case "j": super.handleInput("\x1b[B"); return; // Down
+      case "k": super.handleInput("\x1b[A"); return; // Up
+      case "l": super.handleInput("\x1b[C"); return; // Right
+    }
+    // Pass unhandled keys to super (ctrl+c, etc.), but filter printable chars
+    if (data.length === 1 && data.charCodeAt(0) >= 32) return;
+    super.handleInput(data);
+  }
+
+  render(width: number): string[] {
+    const lines = super.render(width);
+    // Add mode indicator to bottom border (use truncateToWidth for ANSI-safe truncation)
+    if (lines.length > 0) {
+      const label = this.mode === "normal" ? " NORMAL " : " INSERT ";
+      const lastLine = lines[lines.length - 1]!;
+      // Pass "" as ellipsis to avoid adding "..." when truncating
+      lines[lines.length - 1] = truncateToWidth(lastLine, width - label.length, "") + label;
+    }
+    return lines;
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", (_event, ctx) => {
+    // Factory receives the TUI, theme, and keybindings from the app
+    ctx.ui.setEditorComponent((tui, theme, keybindings) =>
+      new VimEditor(tui, theme, keybindings)
+    );
+  });
+}
+```
+
+**Key points:**
+
+- **Extend `CustomEditor`** (not base `Editor`) to get app keybindings (escape to abort, ctrl+d to exit, model switching, etc.)
+- **Call `super.handleInput(data)`** for keys you don't handle
+- **Status spinners**: custom editors keep standalone status rows by default. Pass `{ embedWorkingStatus: true }` as the fourth `CustomEditor` constructor argument to embed working, compaction, branch summarization, and retry spinners in the editor border instead.
+- **Factory pattern**: `setEditorComponent` receives a factory function that gets `tui`, `theme`, and `keybindings`
+- **Pass `undefined`** to restore the default editor: `ctx.ui.setEditorComponent(undefined)`
+
+**Examples:** [modal-editor.ts](../examples/extensions/modal-editor.ts)
+
+## Key Rules
+
+1. **Always use theme from callback** - Don't import theme directly. Use `theme` from the `ctx.ui.custom((tui, theme, keybindings, done) => ...)` callback.
+
+2. **Always type DynamicBorder color param** - Write `(s: string) => theme.fg("accent", s)`, not `(s) => theme.fg("accent", s)`.
+
+3. **Call tui.requestRender() after state changes** - In `handleInput`, call `tui.requestRender()` after updating state.
+
+4. **Return the three-method object** - Custom components need `{ render, invalidate, handleInput }`.
+
+5. **Use existing components** - `SelectList`, `SettingsList`, `BorderedLoader` cover 90% of cases. Don't rebuild them.
+
+## Examples
+
+- **Selection UI**: [examples/extensions/preset.ts](../examples/extensions/preset.ts) - SelectList with DynamicBorder framing
+- **Async with cancel**: [examples/extensions/qna.ts](../examples/extensions/qna.ts) - BorderedLoader for LLM calls
+- **Settings toggles**: [examples/extensions/tools.ts](../examples/extensions/tools.ts) - SettingsList for tool enable/disable
+- **Status indicators**: [examples/extensions/plan-mode/index.ts](../examples/extensions/plan-mode/index.ts) - setStatus and setWidget
+- **Working indicator**: [examples/extensions/working-indicator.ts](../examples/extensions/working-indicator.ts) - setWorkingIndicator
+- **Custom footer**: [examples/extensions/custom-footer.ts](../examples/extensions/custom-footer.ts) - setFooter with stats
+- **Custom editor**: [examples/extensions/modal-editor.ts](../examples/extensions/modal-editor.ts) - Vim-like modal editing
+- **Snake game**: [examples/extensions/snake.ts](../examples/extensions/snake.ts) - Full game with keyboard input, game loop
+- **Custom tool rendering**: [examples/extensions/todo.ts](../examples/extensions/todo.ts) - renderCall and renderResult

packages/coding-agent/install-lock/package-lock.json

@@ -0,0 +1,1917 @@
+{
+	"name": "@earendil-works/pi-coding-agent-install",
+	"version": "0.85.1",
+	"lockfileVersion": 3,
+	"requires": true,
+	"packages": {
+		"": {
+			"name": "@earendil-works/pi-coding-agent-install",
+			"version": "0.85.1",
+			"dependencies": {
+				"@earendil-works/pi-coding-agent": "0.85.1"
+			},
+			"engines": {
+				"node": ">=22.19.0"
+			}
+		},
+		"node_modules/@anthropic-ai/sdk": {
+			"version": "0.124.0",
+			"resolved": "https://registry.npmjs.org/@anthropic-ai/sdk/-/sdk-0.124.0.tgz",
+			"integrity": "sha512-cN5O8i9UVxHeOQAzj/XjshWXG8KiibJDw9OGpH2Z/eR3n/RBxdoLxDJOcfqAJWvjaMDFfHTBADU04hWRJVkDyA==",
+			"license": "MIT",
+			"dependencies": {
+				"json-schema-to-ts": "^3.1.1",
+				"standardwebhooks": "^1.0.0"
+			},
+			"peerDependencies": {
+				"zod": "^3.25.0 || ^4.0.0"
+			},
+			"peerDependenciesMeta": {
+				"zod": {
+					"optional": true
+				}
+			},
+			"bin": {
+				"anthropic-ai-sdk": "bin/cli"
+			}
+		},
+		"node_modules/@aws-sdk/client-bedrock-runtime": {
+			"version": "3.1127.0",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/client-bedrock-runtime/-/client-bedrock-runtime-3.1127.0.tgz",
+			"integrity": "sha512-IDl/lrPb90aH+pZFHGNDmgH9nAUQj5PlZH1sJ3w7RikctyjHSnY3oNjZhrLoaBoQn/rNK0zsP6OHEqEhj2tdLA==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/core": "^3.977.9",
+				"@aws-sdk/credential-provider-node": "^3.972.82",
+				"@aws-sdk/eventstream-handler-node": "^3.972.34",
+				"@aws-sdk/middleware-eventstream": "^3.972.29",
+				"@aws-sdk/middleware-websocket": "^3.972.52",
+				"@aws-sdk/token-providers": "3.1127.0",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/fetch-http-handler": "^5.7.2",
+				"@smithy/node-http-handler": "^4.11.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/core": {
+			"version": "3.977.9",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/core/-/core-3.977.9.tgz",
+			"integrity": "sha512-reqPFEQrZxDZpeGj4PFMepBeR5LGYHRqq/L0motTzgFkCRBA4rFdaVXDSLYyGHhxVz7sT2PDnPN9CluGSfgyJA==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/types": "^3.974.5",
+				"@aws-sdk/xml-builder": "^3.972.40",
+				"@aws/lambda-invoke-store": "^0.3.0",
+				"@smithy/core": "^3.33.3",
+				"@smithy/signature-v4": "^5.6.12",
+				"@smithy/types": "^4.17.2",
+				"bowser": "^2.11.0",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/credential-provider-env": {
+			"version": "3.972.70",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-env/-/credential-provider-env-3.972.70.tgz",
+			"integrity": "sha512-H404B7dJl2mCrBqahDEYsanB0xhdDp6tXnXcTUnXmmpy2Q3J0Ho0bUajZ2jr/RdwzCyS59Gi8xXIFwPLGBl6Uw==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/core": "^3.977.9",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/credential-provider-http": {
+			"version": "3.972.72",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-http/-/credential-provider-http-3.972.72.tgz",
+			"integrity": "sha512-X98zYOrVOeuosCX+6ktf29FC2N2GHPLia7qv6mzPzTc+RPAuHWCDS++Z6JK7eGYqb/v6uaW7bAXaOvDBfol+0w==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/core": "^3.977.9",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/fetch-http-handler": "^5.7.2",
+				"@smithy/node-http-handler": "^4.11.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/credential-provider-ini": {
+			"version": "3.973.15",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-ini/-/credential-provider-ini-3.973.15.tgz",
+			"integrity": "sha512-Rykg6s5ceBuynMOGWgoowO4N+27JfnqXAnVaSunZl0hOO1XodSrxGNz6sCEbnmS0lAfQZDKyb3fbr46gSuv6Sg==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/core": "^3.977.9",
+				"@aws-sdk/credential-provider-env": "^3.972.70",
+				"@aws-sdk/credential-provider-http": "^3.972.72",
+				"@aws-sdk/credential-provider-login": "^3.972.77",
+				"@aws-sdk/credential-provider-process": "^3.972.70",
+				"@aws-sdk/credential-provider-sso": "^3.973.14",
+				"@aws-sdk/credential-provider-web-identity": "^3.972.76",
+				"@aws-sdk/nested-clients": "^3.997.44",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/credential-provider-imds": "^4.4.16",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/credential-provider-login": {
+			"version": "3.972.77",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-login/-/credential-provider-login-3.972.77.tgz",
+			"integrity": "sha512-Jb59xfEISoN5mmbnA+HYqdtrSX3CgCtJoof+V5D8/TgUI56W63GEEd5Y58WijU3Ou6+WEgaLD1feVzaRXV5IDQ==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/core": "^3.977.9",
+				"@aws-sdk/nested-clients": "^3.997.44",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/credential-provider-node": {
+			"version": "3.972.82",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-node/-/credential-provider-node-3.972.82.tgz",
+			"integrity": "sha512-znDkEOGXB8W3kG1LJUKP3foBZY/9qLM0eil/DxWXSp37XsdsRLQHE/d/OaCGGVgKpA6znR38h/+INk8do1FjiA==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/credential-provider-env": "^3.972.70",
+				"@aws-sdk/credential-provider-http": "^3.972.72",
+				"@aws-sdk/credential-provider-ini": "^3.973.15",
+				"@aws-sdk/credential-provider-process": "^3.972.70",
+				"@aws-sdk/credential-provider-sso": "^3.973.14",
+				"@aws-sdk/credential-provider-web-identity": "^3.972.76",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/credential-provider-imds": "^4.4.16",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/credential-provider-process": {
+			"version": "3.972.70",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-process/-/credential-provider-process-3.972.70.tgz",
+			"integrity": "sha512-2ry03fGRJr4sV3jI+ocjj5JqALnFD6ymM5KiNCDZMvq8bX2GSbE0vji4aM43TVCl2nXqqLRZaUxdq/KeWRAY4Q==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/core": "^3.977.9",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/credential-provider-sso": {
+			"version": "3.973.14",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-sso/-/credential-provider-sso-3.973.14.tgz",
+			"integrity": "sha512-jkhg/8ocAAoc0RFyLMhCw+/zZh7gystQgd4F4hznNa8P4Cc501PQmxd+jGLiMHodPJ+7Zv/3znM62gZojyasmA==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/core": "^3.977.9",
+				"@aws-sdk/nested-clients": "^3.997.44",
+				"@aws-sdk/token-providers": "3.1116.0",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/credential-provider-sso/node_modules/@aws-sdk/token-providers": {
+			"version": "3.1116.0",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1116.0.tgz",
+			"integrity": "sha512-ygIivKqh8aHzNkucOCXHyIBgBpLPfrSI0mCqXF+vLBsPTUKqj0VSqAY0GFPe7lQl4HntjOcQ+KSyS7oUV2C54Q==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/core": "^3.977.9",
+				"@aws-sdk/nested-clients": "^3.997.44",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/credential-provider-web-identity": {
+			"version": "3.972.76",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/credential-provider-web-identity/-/credential-provider-web-identity-3.972.76.tgz",
+			"integrity": "sha512-d3AGyVu759PGr35mEB2s22xxlNEA5rpdxtSPJthfPFJvoQ8dt357iVPECqWfUxXp1toJAvKmbtcIYVGigaGsCA==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/core": "^3.977.9",
+				"@aws-sdk/nested-clients": "^3.997.44",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/eventstream-handler-node": {
+			"version": "3.972.34",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/eventstream-handler-node/-/eventstream-handler-node-3.972.34.tgz",
+			"integrity": "sha512-cTeVzpu1xEAkryTZBYhGwnQ6gOGyp8ZYZvmn0Sg/nI/ABmy/CRHHxPDJDUi9PxwxUtGGaatvfRUB3FCgT/rSWw==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/middleware-eventstream": {
+			"version": "3.972.29",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/middleware-eventstream/-/middleware-eventstream-3.972.29.tgz",
+			"integrity": "sha512-dlRzHCgyB8W6hLuDC5pcT5q+ziPt00n4QGgGBE17ucLVU4zMa6lsbuUdQ2Pm75Z5VA8GF+R/+SgrRcaTdIzSIQ==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/middleware-websocket": {
+			"version": "3.972.52",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/middleware-websocket/-/middleware-websocket-3.972.52.tgz",
+			"integrity": "sha512-vsPPM+nMbKJlUCFU+eoGZbdxdxDIAX9LbpjSXaR5Ufpmqgp8TdYQnoExhLu4T3umW/JIIPny1ydbhWidZZYokQ==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/core": "^3.977.9",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/fetch-http-handler": "^5.7.2",
+				"@smithy/signature-v4": "^5.6.12",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">= 14.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/nested-clients": {
+			"version": "3.997.44",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/nested-clients/-/nested-clients-3.997.44.tgz",
+			"integrity": "sha512-NhEgryjlBF9w38ZXqGymQV28IhkYa1mKhlbYnqIis57AYwWGVYfUPgg/qC2rLRqOUfblxx++irvju10kVTa8Vw==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/core": "^3.977.9",
+				"@aws-sdk/signature-v4-multi-region": "^3.996.46",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/fetch-http-handler": "^5.7.2",
+				"@smithy/node-http-handler": "^4.11.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/signature-v4-multi-region": {
+			"version": "3.996.46",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/signature-v4-multi-region/-/signature-v4-multi-region-3.996.46.tgz",
+			"integrity": "sha512-L+2xZTye/2T96f3lwCws0Zw6GG2JHZW9e8FpVgGBeeExSKyeoZ6CWRpBml/7DNiK/O26jrgPM9F+Ay8VkgzUWQ==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/signature-v4": "^5.6.12",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/token-providers": {
+			"version": "3.1127.0",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/token-providers/-/token-providers-3.1127.0.tgz",
+			"integrity": "sha512-Dv2TMWBshJ+tF6ahs2Sy5bh4Iabsd4GAQqVvE9XZmYmnoaVbpS2QKIKE/HRacc7bTtbjEEvP+laGzHvHlf1CiQ==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@aws-sdk/core": "^3.977.9",
+				"@aws-sdk/nested-clients": "^3.997.44",
+				"@aws-sdk/types": "^3.974.5",
+				"@smithy/core": "^3.33.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/types": {
+			"version": "3.974.5",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/types/-/types-3.974.5.tgz",
+			"integrity": "sha512-LkwLL2BLbC6wNNm4JaH9mbEqBMdOZCct6VAYqhdN4U1xrWM+fUJQEfbHwQgDypapOWTRtlk25akb5afM0P8CIQ==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws-sdk/xml-builder": {
+			"version": "3.972.40",
+			"resolved": "https://registry.npmjs.org/@aws-sdk/xml-builder/-/xml-builder-3.972.40.tgz",
+			"integrity": "sha512-wlFmCIGUlwF4zx/kncw+bmxTQh1HeSJq4mYV/V5cZUSJadDP3kXvGW8Rn21cimj/7y9ju+47oYWXi97vF7czaA==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			}
+		},
+		"node_modules/@aws/lambda-invoke-store": {
+			"version": "0.3.0",
+			"resolved": "https://registry.npmjs.org/@aws/lambda-invoke-store/-/lambda-invoke-store-0.3.0.tgz",
+			"integrity": "sha512-sl4Bm6yiMNYrZKkqqDFWN0UfnWhlS8ivKxrYl+6t0gCLrqr8y3B2IqZZbFRkfaVVp7C/baApyh71P+LeE1A2sQ==",
+			"license": "Apache-2.0",
+			"engines": {
+				"node": ">=18.0.0"
+			}
+		},
+		"node_modules/@babel/runtime": {
+			"version": "7.29.2",
+			"resolved": "https://registry.npmjs.org/@babel/runtime/-/runtime-7.29.2.tgz",
+			"integrity": "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=6.9.0"
+			}
+		},
+		"node_modules/@earendil-works/chord": {
+			"version": "0.85.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/chord/-/chord-0.85.1.tgz",
+			"license": "MIT",
+			"dependencies": {
+				"esbuild": "0.28.2"
+			},
+			"engines": {
+				"node": ">=22.19.0"
+			}
+		},
+		"node_modules/@earendil-works/pi-agent-core": {
+			"version": "0.85.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-agent-core/-/pi-agent-core-0.85.1.tgz",
+			"license": "MIT",
+			"dependencies": {
+				"@earendil-works/chord": "^0.85.1",
+				"@earendil-works/pi-ai": "^0.85.1",
+				"@earendil-works/pi-telemetry": "^0.85.1",
+				"diff": "8.0.4",
+				"ignore": "7.0.8",
+				"typebox": "1.3.27",
+				"yaml": "2.9.0"
+			},
+			"engines": {
+				"node": ">=22.19.0"
+			}
+		},
+		"node_modules/@earendil-works/pi-ai": {
+			"version": "0.85.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-ai/-/pi-ai-0.85.1.tgz",
+			"license": "MIT",
+			"dependencies": {
+				"@anthropic-ai/sdk": "0.124.0",
+				"@aws-sdk/client-bedrock-runtime": "3.1127.0",
+				"@earendil-works/pi-telemetry": "^0.85.1",
+				"@google/genai": "2.21.0",
+				"@smithy/node-http-handler": "4.12.1",
+				"http-proxy-agent": "9.1.0",
+				"https-proxy-agent": "9.1.0",
+				"openai": "6.40.0",
+				"partial-json": "0.1.7",
+				"typebox": "1.3.27"
+			},
+			"bin": {
+				"pi-ai": "dist/cli.js"
+			},
+			"engines": {
+				"node": ">=22.19.0"
+			}
+		},
+		"node_modules/@earendil-works/pi-ai/node_modules/agent-base": {
+			"version": "9.0.0",
+			"resolved": "https://registry.npmjs.org/agent-base/-/agent-base-9.0.0.tgz",
+			"integrity": "sha512-TQf59BsZnytt8GdJKLPfUZ54g/iaUL2OWDSFCCvMOhsHduDQxO8xC4PNeyIkVcA5KwL2phPSv0douC0fgWzmnA==",
+			"license": "MIT",
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/@earendil-works/pi-ai/node_modules/https-proxy-agent": {
+			"version": "9.1.0",
+			"resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-9.1.0.tgz",
+			"integrity": "sha512-ag87y7cJJ9/3+GxFr8Oy4O5faDsGRGnBGsJj/YjOSsSx/5eadKLYTMPlzuR6obgoCDDm0abAAZitXXQkMOPSpA==",
+			"license": "MIT",
+			"dependencies": {
+				"agent-base": "9.0.0",
+				"debug": "^4.3.4",
+				"proxy-agent-negotiate": "1.1.0"
+			},
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/@earendil-works/pi-coding-agent": {
+			"version": "0.85.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-coding-agent/-/pi-coding-agent-0.85.1.tgz",
+			"license": "MIT",
+			"dependencies": {
+				"@earendil-works/chord": "^0.85.1",
+				"@earendil-works/pi-agent-core": "^0.85.1",
+				"@earendil-works/pi-ai": "^0.85.1",
+				"@earendil-works/pi-tui": "^0.85.1",
+				"@silvia-odwyer/photon-node": "0.3.4",
+				"chalk": "6.0.0",
+				"cross-spawn": "7.0.6",
+				"diff": "8.0.4",
+				"grok-mermaid": "0.2.3",
+				"highlight.js": "10.7.3",
+				"hosted-git-info": "9.0.3",
+				"ignore": "7.0.8",
+				"jiti": "2.7.0",
+				"minimatch": "10.2.6",
+				"proper-lockfile": "4.1.2",
+				"semver": "7.8.5",
+				"typebox": "1.3.27",
+				"undici": "8.10.2",
+				"yaml": "2.9.0"
+			},
+			"bin": {
+				"pi": "dist/bundle/cli.js"
+			},
+			"engines": {
+				"node": ">=22.19.0"
+			}
+		},
+		"node_modules/@earendil-works/pi-telemetry": {
+			"version": "0.85.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-telemetry/-/pi-telemetry-0.85.1.tgz",
+			"license": "MIT",
+			"engines": {
+				"node": ">=22.19.0"
+			}
+		},
+		"node_modules/@earendil-works/pi-tui": {
+			"version": "0.85.1",
+			"resolved": "https://registry.npmjs.org/@earendil-works/pi-tui/-/pi-tui-0.85.1.tgz",
+			"license": "MIT",
+			"dependencies": {
+				"get-east-asian-width": "1.6.0",
+				"marked": "18.0.11"
+			},
+			"engines": {
+				"node": ">=22.19.0"
+			}
+		},
+		"node_modules/@esbuild/aix-ppc64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz",
+			"integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"aix"
+			],
+			"cpu": [
+				"ppc64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/android-arm": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz",
+			"integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"android"
+			],
+			"cpu": [
+				"arm"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/android-arm64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz",
+			"integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"android"
+			],
+			"cpu": [
+				"arm64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/android-x64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz",
+			"integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"android"
+			],
+			"cpu": [
+				"x64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/darwin-arm64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz",
+			"integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"darwin"
+			],
+			"cpu": [
+				"arm64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/darwin-x64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz",
+			"integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"darwin"
+			],
+			"cpu": [
+				"x64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/freebsd-arm64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz",
+			"integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"freebsd"
+			],
+			"cpu": [
+				"arm64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/freebsd-x64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz",
+			"integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"freebsd"
+			],
+			"cpu": [
+				"x64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/linux-arm": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz",
+			"integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"linux"
+			],
+			"cpu": [
+				"arm"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/linux-arm64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz",
+			"integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"linux"
+			],
+			"cpu": [
+				"arm64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/linux-ia32": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz",
+			"integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"linux"
+			],
+			"cpu": [
+				"ia32"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/linux-loong64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz",
+			"integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"linux"
+			],
+			"cpu": [
+				"loong64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/linux-mips64el": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz",
+			"integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"linux"
+			],
+			"cpu": [
+				"mips64el"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/linux-ppc64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz",
+			"integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"linux"
+			],
+			"cpu": [
+				"ppc64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/linux-riscv64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz",
+			"integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"linux"
+			],
+			"cpu": [
+				"riscv64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/linux-s390x": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz",
+			"integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"linux"
+			],
+			"cpu": [
+				"s390x"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/linux-x64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz",
+			"integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"linux"
+			],
+			"cpu": [
+				"x64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/netbsd-arm64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz",
+			"integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"netbsd"
+			],
+			"cpu": [
+				"arm64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/netbsd-x64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz",
+			"integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"netbsd"
+			],
+			"cpu": [
+				"x64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/openbsd-arm64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz",
+			"integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"openbsd"
+			],
+			"cpu": [
+				"arm64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/openbsd-x64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz",
+			"integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"openbsd"
+			],
+			"cpu": [
+				"x64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/openharmony-arm64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz",
+			"integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"openharmony"
+			],
+			"cpu": [
+				"arm64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/sunos-x64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz",
+			"integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"sunos"
+			],
+			"cpu": [
+				"x64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/win32-arm64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz",
+			"integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"win32"
+			],
+			"cpu": [
+				"arm64"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/win32-ia32": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz",
+			"integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"win32"
+			],
+			"cpu": [
+				"ia32"
+			],
+			"optional": true
+		},
+		"node_modules/@esbuild/win32-x64": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz",
+			"integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"os": [
+				"win32"
+			],
+			"cpu": [
+				"x64"
+			],
+			"optional": true
+		},
+		"node_modules/@google/genai": {
+			"version": "2.21.0",
+			"resolved": "https://registry.npmjs.org/@google/genai/-/genai-2.21.0.tgz",
+			"integrity": "sha512-+PDtco2/Z0ONdzCGekCoCT+O1VJS9xJQNN4XzQpXG/t3El/SWWMkCWlFRO1KmivOHPa4Q0VjUYu1HBKCZ/v33Q==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"google-auth-library": "^10.3.0",
+				"p-retry": "^4.6.2",
+				"protobufjs": "^7.5.4",
+				"ws": "^8.18.0"
+			},
+			"peerDependencies": {
+				"@modelcontextprotocol/sdk": "^1.25.2"
+			},
+			"peerDependenciesMeta": {
+				"@modelcontextprotocol/sdk": {
+					"optional": true
+				}
+			},
+			"engines": {
+				"node": ">=20.0.0"
+			},
+			"hasInstallScript": true
+		},
+		"node_modules/@protobufjs/aspromise": {
+			"version": "1.1.2",
+			"resolved": "https://registry.npmjs.org/@protobufjs/aspromise/-/aspromise-1.1.2.tgz",
+			"integrity": "sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==",
+			"license": "BSD-3-Clause"
+		},
+		"node_modules/@protobufjs/base64": {
+			"version": "1.1.2",
+			"resolved": "https://registry.npmjs.org/@protobufjs/base64/-/base64-1.1.2.tgz",
+			"integrity": "sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==",
+			"license": "BSD-3-Clause"
+		},
+		"node_modules/@protobufjs/codegen": {
+			"version": "2.0.5",
+			"resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz",
+			"integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==",
+			"license": "BSD-3-Clause"
+		},
+		"node_modules/@protobufjs/eventemitter": {
+			"version": "1.1.1",
+			"resolved": "https://registry.npmjs.org/@protobufjs/eventemitter/-/eventemitter-1.1.1.tgz",
+			"integrity": "sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==",
+			"license": "BSD-3-Clause"
+		},
+		"node_modules/@protobufjs/fetch": {
+			"version": "1.1.1",
+			"resolved": "https://registry.npmjs.org/@protobufjs/fetch/-/fetch-1.1.1.tgz",
+			"integrity": "sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==",
+			"license": "BSD-3-Clause",
+			"dependencies": {
+				"@protobufjs/aspromise": "^1.1.1"
+			}
+		},
+		"node_modules/@protobufjs/float": {
+			"version": "1.0.2",
+			"resolved": "https://registry.npmjs.org/@protobufjs/float/-/float-1.0.2.tgz",
+			"integrity": "sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==",
+			"license": "BSD-3-Clause"
+		},
+		"node_modules/@protobufjs/path": {
+			"version": "1.1.2",
+			"resolved": "https://registry.npmjs.org/@protobufjs/path/-/path-1.1.2.tgz",
+			"integrity": "sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==",
+			"license": "BSD-3-Clause"
+		},
+		"node_modules/@protobufjs/pool": {
+			"version": "1.1.0",
+			"resolved": "https://registry.npmjs.org/@protobufjs/pool/-/pool-1.1.0.tgz",
+			"integrity": "sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==",
+			"license": "BSD-3-Clause"
+		},
+		"node_modules/@protobufjs/utf8": {
+			"version": "1.1.1",
+			"resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.1.tgz",
+			"integrity": "sha512-oOAWABowe8EAbMyWKM0tYDKi8Yaox52D+HWZhAIJqQXbqe0xI/GV7FhLWqlEKreMkfDjshR5FKgi3mnle0h6Eg==",
+			"license": "BSD-3-Clause"
+		},
+		"node_modules/@silvia-odwyer/photon-node": {
+			"version": "0.3.4",
+			"resolved": "https://registry.npmjs.org/@silvia-odwyer/photon-node/-/photon-node-0.3.4.tgz",
+			"integrity": "sha512-bnly4BKB3KDTFxrUIcgCLbaeVVS8lrAkri1pEzskpmxu9MdfGQTy8b8EgcD83ywD3RPMsIulY8xJH5Awa+t9fA==",
+			"license": "Apache-2.0"
+		},
+		"node_modules/@smithy/core": {
+			"version": "3.33.3",
+			"resolved": "https://registry.npmjs.org/@smithy/core/-/core-3.33.3.tgz",
+			"integrity": "sha512-CsOeKq/9kA3y6VJHt+/+VTCtBaxJ4OTFpgrjIUhPpDIKxBci1k2bJaQASF2h/ELWrulGp+t97DZ0mevfAD8idg==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=18.0.0"
+			}
+		},
+		"node_modules/@smithy/credential-provider-imds": {
+			"version": "4.5.2",
+			"resolved": "https://registry.npmjs.org/@smithy/credential-provider-imds/-/credential-provider-imds-4.5.2.tgz",
+			"integrity": "sha512-A9uSdn72ozbRUSit0eib0TW7nXuNPlaeM0zcGkJ+nE6tFcSDbnmtwoxbTCFBukVQcszDAyvsd7+rTduPTXpygg==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@smithy/core": "^3.33.2",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=18.0.0"
+			}
+		},
+		"node_modules/@smithy/fetch-http-handler": {
+			"version": "5.8.0",
+			"resolved": "https://registry.npmjs.org/@smithy/fetch-http-handler/-/fetch-http-handler-5.8.0.tgz",
+			"integrity": "sha512-ycSJu3tFAQ4v04CBB0agqFMVsSQ1iG3yw+SpgxRqKfaURpQD4CZ8Wn0zPMmSnOuTpTh65Vz+EA0rMrw089wvkA==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@smithy/core": "^3.33.3",
+				"@smithy/types": "^4.18.0",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=18.0.0"
+			}
+		},
+		"node_modules/@smithy/node-http-handler": {
+			"version": "4.12.1",
+			"resolved": "https://registry.npmjs.org/@smithy/node-http-handler/-/node-http-handler-4.12.1.tgz",
+			"integrity": "sha512-ThMkboGeONWXAelq9FvGsuJC4rOi+qyC4/zhUF58xYpxUg5sQKx2VXZYJmtNjr4dSuBJ1HeJXETQILCz3wOHvw==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@smithy/core": "^3.33.3",
+				"@smithy/types": "^4.18.0",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=18.0.0"
+			}
+		},
+		"node_modules/@smithy/signature-v4": {
+			"version": "5.7.3",
+			"resolved": "https://registry.npmjs.org/@smithy/signature-v4/-/signature-v4-5.7.3.tgz",
+			"integrity": "sha512-7ImGm+FkHRLcBaRttIAMZ6bzJZWb2cJGoYjq46F2UjycujWzrL9GEN9h4w7eQyXJYnltrUhxbbieBAIRrdqpow==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"@smithy/core": "^3.33.3",
+				"@smithy/types": "^4.17.2",
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=18.0.0"
+			}
+		},
+		"node_modules/@smithy/types": {
+			"version": "4.18.0",
+			"resolved": "https://registry.npmjs.org/@smithy/types/-/types-4.18.0.tgz",
+			"integrity": "sha512-CgB6HHWer/vrKps24ulRIbpcpb7K4xAU7SkZ7YHzBPlwHsvsrCJFEXK421s+cJzX+ZrqtA/TuU5w1HzI7k9N8A==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"tslib": "^2.6.2"
+			},
+			"engines": {
+				"node": ">=18.0.0"
+			}
+		},
+		"node_modules/@stablelib/base64": {
+			"version": "1.0.1",
+			"resolved": "https://registry.npmjs.org/@stablelib/base64/-/base64-1.0.1.tgz",
+			"integrity": "sha512-1bnPQqSxSuc3Ii6MhBysoWCg58j97aUjuCSZrGSmDxNqtytIi0k8utUenAwTZN4V5mXXYGsVUI9zeBqy+jBOSQ==",
+			"license": "MIT"
+		},
+		"node_modules/@types/node": {
+			"version": "22.19.19",
+			"resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.19.tgz",
+			"integrity": "sha512-dyh/xO2Fh5bYrfWaaqGrRQQGkNdmYw6AmaAUvYeUMNTWQtvb796ikLdmTchRmOlOiIJ1TDXfWgVx1QkUlQ6Hew==",
+			"license": "MIT",
+			"dependencies": {
+				"undici-types": "~6.21.0"
+			}
+		},
+		"node_modules/agent-base": {
+			"version": "7.1.4",
+			"resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.4.tgz",
+			"integrity": "sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==",
+			"license": "MIT",
+			"engines": {
+				"node": ">= 14"
+			}
+		},
+		"node_modules/balanced-match": {
+			"version": "4.0.4",
+			"resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+			"integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+			"license": "MIT",
+			"engines": {
+				"node": "18 || 20 || >=22"
+			}
+		},
+		"node_modules/base64-js": {
+			"version": "1.5.1",
+			"resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
+			"integrity": "sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==",
+			"license": "MIT",
+			"funding": [
+				{
+					"type": "github",
+					"url": "https://github.com/sponsors/feross"
+				},
+				{
+					"type": "patreon",
+					"url": "https://www.patreon.com/feross"
+				},
+				{
+					"type": "consulting",
+					"url": "https://feross.org/support"
+				}
+			]
+		},
+		"node_modules/bignumber.js": {
+			"version": "9.3.1",
+			"resolved": "https://registry.npmjs.org/bignumber.js/-/bignumber.js-9.3.1.tgz",
+			"integrity": "sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==",
+			"license": "MIT",
+			"engines": {
+				"node": "*"
+			}
+		},
+		"node_modules/bowser": {
+			"version": "2.14.1",
+			"resolved": "https://registry.npmjs.org/bowser/-/bowser-2.14.1.tgz",
+			"integrity": "sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg==",
+			"license": "MIT"
+		},
+		"node_modules/brace-expansion": {
+			"version": "5.0.9",
+			"resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.9.tgz",
+			"integrity": "sha512-ScQ4IuvIEF1TMlP7Zt+vjJ//9zlPb2SDcxWxM3bk8s6t6GGdJ7KO1dCcTidOPJKePW30LE/2cT7wCyPho9/Wxg==",
+			"license": "MIT",
+			"dependencies": {
+				"balanced-match": "^4.0.2"
+			},
+			"engines": {
+				"node": "20 || >=22"
+			}
+		},
+		"node_modules/buffer-equal-constant-time": {
+			"version": "1.0.1",
+			"resolved": "https://registry.npmjs.org/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz",
+			"integrity": "sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==",
+			"license": "BSD-3-Clause"
+		},
+		"node_modules/chalk": {
+			"version": "6.0.0",
+			"resolved": "https://registry.npmjs.org/chalk/-/chalk-6.0.0.tgz",
+			"integrity": "sha512-2uNTXIuTTxk7ciZgAU1BQcgnchcG0xXnrs6jzkQfj9SsRa9M2s5zE8WT96hS6KmG4MzWHSrvH43DF1m4XRkrFg==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=22"
+			},
+			"funding": {
+				"url": "https://github.com/chalk/chalk?sponsor=1"
+			}
+		},
+		"node_modules/cross-spawn": {
+			"version": "7.0.6",
+			"resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+			"integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+			"license": "MIT",
+			"dependencies": {
+				"path-key": "^3.1.0",
+				"shebang-command": "^2.0.0",
+				"which": "^2.0.1"
+			},
+			"engines": {
+				"node": ">= 8"
+			}
+		},
+		"node_modules/data-uri-to-buffer": {
+			"version": "4.0.1",
+			"resolved": "https://registry.npmjs.org/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz",
+			"integrity": "sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==",
+			"license": "MIT",
+			"engines": {
+				"node": ">= 12"
+			}
+		},
+		"node_modules/debug": {
+			"version": "4.4.3",
+			"resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz",
+			"integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==",
+			"license": "MIT",
+			"dependencies": {
+				"ms": "^2.1.3"
+			},
+			"peerDependenciesMeta": {
+				"supports-color": {
+					"optional": true
+				}
+			},
+			"engines": {
+				"node": ">=6.0"
+			}
+		},
+		"node_modules/diff": {
+			"version": "8.0.4",
+			"resolved": "https://registry.npmjs.org/diff/-/diff-8.0.4.tgz",
+			"integrity": "sha512-DPi0FmjiSU5EvQV0++GFDOJ9ASQUVFh5kD+OzOnYdi7n3Wpm9hWWGfB/O2blfHcMVTL5WkQXSnRiK9makhrcnw==",
+			"license": "BSD-3-Clause",
+			"engines": {
+				"node": ">=0.3.1"
+			}
+		},
+		"node_modules/ecdsa-sig-formatter": {
+			"version": "1.0.11",
+			"resolved": "https://registry.npmjs.org/ecdsa-sig-formatter/-/ecdsa-sig-formatter-1.0.11.tgz",
+			"integrity": "sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"safe-buffer": "^5.0.1"
+			}
+		},
+		"node_modules/esbuild": {
+			"version": "0.28.2",
+			"resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz",
+			"integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==",
+			"license": "MIT",
+			"optionalDependencies": {
+				"@esbuild/aix-ppc64": "0.28.2",
+				"@esbuild/android-arm": "0.28.2",
+				"@esbuild/android-arm64": "0.28.2",
+				"@esbuild/android-x64": "0.28.2",
+				"@esbuild/darwin-arm64": "0.28.2",
+				"@esbuild/darwin-x64": "0.28.2",
+				"@esbuild/freebsd-arm64": "0.28.2",
+				"@esbuild/freebsd-x64": "0.28.2",
+				"@esbuild/linux-arm": "0.28.2",
+				"@esbuild/linux-arm64": "0.28.2",
+				"@esbuild/linux-ia32": "0.28.2",
+				"@esbuild/linux-loong64": "0.28.2",
+				"@esbuild/linux-mips64el": "0.28.2",
+				"@esbuild/linux-ppc64": "0.28.2",
+				"@esbuild/linux-riscv64": "0.28.2",
+				"@esbuild/linux-s390x": "0.28.2",
+				"@esbuild/linux-x64": "0.28.2",
+				"@esbuild/netbsd-arm64": "0.28.2",
+				"@esbuild/netbsd-x64": "0.28.2",
+				"@esbuild/openbsd-arm64": "0.28.2",
+				"@esbuild/openbsd-x64": "0.28.2",
+				"@esbuild/openharmony-arm64": "0.28.2",
+				"@esbuild/sunos-x64": "0.28.2",
+				"@esbuild/win32-arm64": "0.28.2",
+				"@esbuild/win32-ia32": "0.28.2",
+				"@esbuild/win32-x64": "0.28.2"
+			},
+			"bin": {
+				"esbuild": "bin/esbuild"
+			},
+			"engines": {
+				"node": ">=18"
+			},
+			"hasInstallScript": true
+		},
+		"node_modules/extend": {
+			"version": "3.0.2",
+			"resolved": "https://registry.npmjs.org/extend/-/extend-3.0.2.tgz",
+			"integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==",
+			"license": "MIT"
+		},
+		"node_modules/fast-sha256": {
+			"version": "1.3.0",
+			"resolved": "https://registry.npmjs.org/fast-sha256/-/fast-sha256-1.3.0.tgz",
+			"integrity": "sha512-n11RGP/lrWEFI/bWdygLxhI+pVeo1ZYIVwvvPkW7azl/rOy+F3HYRZ2K5zeE9mmkhQppyv9sQFx0JM9UabnpPQ==",
+			"license": "Unlicense"
+		},
+		"node_modules/fetch-blob": {
+			"version": "3.2.0",
+			"resolved": "https://registry.npmjs.org/fetch-blob/-/fetch-blob-3.2.0.tgz",
+			"integrity": "sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==",
+			"license": "MIT",
+			"dependencies": {
+				"node-domexception": "^1.0.0",
+				"web-streams-polyfill": "^3.0.3"
+			},
+			"engines": {
+				"node": "^12.20 || >= 14.13"
+			},
+			"funding": [
+				{
+					"type": "github",
+					"url": "https://github.com/sponsors/jimmywarting"
+				},
+				{
+					"type": "paypal",
+					"url": "https://paypal.me/jimmywarting"
+				}
+			]
+		},
+		"node_modules/formdata-polyfill": {
+			"version": "4.0.10",
+			"resolved": "https://registry.npmjs.org/formdata-polyfill/-/formdata-polyfill-4.0.10.tgz",
+			"integrity": "sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==",
+			"license": "MIT",
+			"dependencies": {
+				"fetch-blob": "^3.1.2"
+			},
+			"engines": {
+				"node": ">=12.20.0"
+			}
+		},
+		"node_modules/gaxios": {
+			"version": "7.1.4",
+			"resolved": "https://registry.npmjs.org/gaxios/-/gaxios-7.1.4.tgz",
+			"integrity": "sha512-bTIgTsM2bWn3XklZISBTQX7ZSddGW+IO3bMdGaemHZ3tbqExMENHLx6kKZ/KlejgrMtj8q7wBItt51yegqalrA==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"extend": "^3.0.2",
+				"https-proxy-agent": "^7.0.1",
+				"node-fetch": "^3.3.2"
+			},
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/gcp-metadata": {
+			"version": "8.1.2",
+			"resolved": "https://registry.npmjs.org/gcp-metadata/-/gcp-metadata-8.1.2.tgz",
+			"integrity": "sha512-zV/5HKTfCeKWnxG0Dmrw51hEWFGfcF2xiXqcA3+J90WDuP0SvoiSO5ORvcBsifmx/FoIjgQN3oNOGaQ5PhLFkg==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"gaxios": "^7.0.0",
+				"google-logging-utils": "^1.0.0",
+				"json-bigint": "^1.0.0"
+			},
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/get-east-asian-width": {
+			"version": "1.6.0",
+			"resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.6.0.tgz",
+			"integrity": "sha512-QRbvDIbx6YklUe6RxeTeleMR0yv3cYH6PsPZHcnVn7xv7zO1BHN8r0XETu8n6Ye3Q+ahtSarc3WgtNWmehIBfA==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/sindresorhus"
+			}
+		},
+		"node_modules/google-auth-library": {
+			"version": "10.6.2",
+			"resolved": "https://registry.npmjs.org/google-auth-library/-/google-auth-library-10.6.2.tgz",
+			"integrity": "sha512-e27Z6EThmVNNvtYASwQxose/G57rkRuaRbQyxM2bvYLLX/GqWZ5chWq2EBoUchJbCc57eC9ArzO5wMsEmWftCw==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"base64-js": "^1.3.0",
+				"ecdsa-sig-formatter": "^1.0.11",
+				"gaxios": "^7.1.4",
+				"gcp-metadata": "8.1.2",
+				"google-logging-utils": "1.1.3",
+				"jws": "^4.0.0"
+			},
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/google-logging-utils": {
+			"version": "1.1.3",
+			"resolved": "https://registry.npmjs.org/google-logging-utils/-/google-logging-utils-1.1.3.tgz",
+			"integrity": "sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA==",
+			"license": "Apache-2.0",
+			"engines": {
+				"node": ">=14"
+			}
+		},
+		"node_modules/graceful-fs": {
+			"version": "4.2.11",
+			"resolved": "https://registry.npmjs.org/graceful-fs/-/graceful-fs-4.2.11.tgz",
+			"integrity": "sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==",
+			"license": "ISC"
+		},
+		"node_modules/grok-mermaid": {
+			"version": "0.2.3",
+			"resolved": "https://registry.npmjs.org/grok-mermaid/-/grok-mermaid-0.2.3.tgz",
+			"integrity": "sha512-/4KopAbsjvuRP9MdPtlDjOHUmUVEohOX73JNcsWpzAtFxh+bq5+Dhb6gzvRieLDwIPQIR3/vy8V1NNTuz4Zsmg==",
+			"license": "Apache-2.0",
+			"engines": {
+				"node": ">=18"
+			}
+		},
+		"node_modules/highlight.js": {
+			"version": "10.7.3",
+			"resolved": "https://registry.npmjs.org/highlight.js/-/highlight.js-10.7.3.tgz",
+			"integrity": "sha512-tzcUFauisWKNHaRkN4Wjl/ZA07gENAjFl3J/c480dprkGTg5EQstgaNFqBfUqCq54kZRIEcreTsAgF/m2quD7A==",
+			"license": "BSD-3-Clause",
+			"engines": {
+				"node": "*"
+			}
+		},
+		"node_modules/hosted-git-info": {
+			"version": "9.0.3",
+			"resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-9.0.3.tgz",
+			"integrity": "sha512-Hc+ghLoSt6QaYZUv0WBiIvmMDZuZZ7oaDvdH8MbfOO4lOsxdXLEvuC6ePoGs9H1X9oCLyq6+NVN0MKqD+ydxyg==",
+			"license": "ISC",
+			"dependencies": {
+				"lru-cache": "^11.1.0"
+			},
+			"engines": {
+				"node": "^20.17.0 || >=22.9.0"
+			}
+		},
+		"node_modules/http-proxy-agent": {
+			"version": "9.1.0",
+			"resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-9.1.0.tgz",
+			"integrity": "sha512-2NxoveTT58mjYT4n3RPTEfCZGLMbidoO8XEieXfpSYxu+PQJ1qpx4ypwH6N+uF9twBPIvRRgvkvW5HUTYWENig==",
+			"license": "MIT",
+			"dependencies": {
+				"agent-base": "9.0.0",
+				"debug": "^4.3.4",
+				"proxy-agent-negotiate": "1.1.0"
+			},
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/http-proxy-agent/node_modules/agent-base": {
+			"version": "9.0.0",
+			"resolved": "https://registry.npmjs.org/agent-base/-/agent-base-9.0.0.tgz",
+			"integrity": "sha512-TQf59BsZnytt8GdJKLPfUZ54g/iaUL2OWDSFCCvMOhsHduDQxO8xC4PNeyIkVcA5KwL2phPSv0douC0fgWzmnA==",
+			"license": "MIT",
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/https-proxy-agent": {
+			"version": "7.0.6",
+			"resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.6.tgz",
+			"integrity": "sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==",
+			"license": "MIT",
+			"dependencies": {
+				"agent-base": "^7.1.2",
+				"debug": "4"
+			},
+			"engines": {
+				"node": ">= 14"
+			}
+		},
+		"node_modules/ignore": {
+			"version": "7.0.8",
+			"resolved": "https://registry.npmjs.org/ignore/-/ignore-7.0.8.tgz",
+			"integrity": "sha512-YYNsSlXBjMk92SKnkwvB5LOVSa6OznlFUGcsvrFgNJbJCd0M1XKeFVRc8ZByeCqz32FivYNHJVooLmdqrmvp/Q==",
+			"license": "MIT",
+			"engines": {
+				"node": ">= 4"
+			}
+		},
+		"node_modules/isexe": {
+			"version": "2.0.0",
+			"resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+			"integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+			"license": "ISC"
+		},
+		"node_modules/jiti": {
+			"version": "2.7.0",
+			"resolved": "https://registry.npmjs.org/jiti/-/jiti-2.7.0.tgz",
+			"integrity": "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==",
+			"license": "MIT",
+			"bin": {
+				"jiti": "lib/jiti-cli.mjs"
+			}
+		},
+		"node_modules/json-bigint": {
+			"version": "1.0.0",
+			"resolved": "https://registry.npmjs.org/json-bigint/-/json-bigint-1.0.0.tgz",
+			"integrity": "sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==",
+			"license": "MIT",
+			"dependencies": {
+				"bignumber.js": "^9.0.0"
+			}
+		},
+		"node_modules/json-schema-to-ts": {
+			"version": "3.1.1",
+			"resolved": "https://registry.npmjs.org/json-schema-to-ts/-/json-schema-to-ts-3.1.1.tgz",
+			"integrity": "sha512-+DWg8jCJG2TEnpy7kOm/7/AxaYoaRbjVB4LFZLySZlWn8exGs3A4OLJR966cVvU26N7X9TWxl+Jsw7dzAqKT6g==",
+			"license": "MIT",
+			"dependencies": {
+				"@babel/runtime": "^7.18.3",
+				"ts-algebra": "^2.0.0"
+			},
+			"engines": {
+				"node": ">=16"
+			}
+		},
+		"node_modules/jwa": {
+			"version": "2.0.1",
+			"resolved": "https://registry.npmjs.org/jwa/-/jwa-2.0.1.tgz",
+			"integrity": "sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==",
+			"license": "MIT",
+			"dependencies": {
+				"buffer-equal-constant-time": "^1.0.1",
+				"ecdsa-sig-formatter": "1.0.11",
+				"safe-buffer": "^5.0.1"
+			}
+		},
+		"node_modules/jws": {
+			"version": "4.0.1",
+			"resolved": "https://registry.npmjs.org/jws/-/jws-4.0.1.tgz",
+			"integrity": "sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==",
+			"license": "MIT",
+			"dependencies": {
+				"jwa": "^2.0.1",
+				"safe-buffer": "^5.0.1"
+			}
+		},
+		"node_modules/long": {
+			"version": "5.3.2",
+			"resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz",
+			"integrity": "sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==",
+			"license": "Apache-2.0"
+		},
+		"node_modules/lru-cache": {
+			"version": "11.4.0",
+			"resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.4.0.tgz",
+			"integrity": "sha512-W+R+kFL4HgVxONq2bhXPi3bGpzGe/yEhVOp233qw9wCRtgncJ15P3bC+e4zZMu4Cq7d+WAJjXGW0uUkifhcatA==",
+			"license": "BlueOak-1.0.0",
+			"engines": {
+				"node": "20 || >=22"
+			}
+		},
+		"node_modules/marked": {
+			"version": "18.0.11",
+			"resolved": "https://registry.npmjs.org/marked/-/marked-18.0.11.tgz",
+			"integrity": "sha512-HnslJfsZkRPBDJRHvVtAaWlZHEpSu7u8LgQuJCELjRKuWR+hpq4A7sLq3p8HaI9ypVoXDXxV34CsQJEe1+J5Aw==",
+			"license": "MIT",
+			"bin": {
+				"marked": "bin/marked.js"
+			},
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/minimatch": {
+			"version": "10.2.6",
+			"resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.6.tgz",
+			"integrity": "sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A==",
+			"license": "BlueOak-1.0.0",
+			"dependencies": {
+				"brace-expansion": "^5.0.8"
+			},
+			"engines": {
+				"node": "18 || 20 || >=22"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/isaacs"
+			}
+		},
+		"node_modules/ms": {
+			"version": "2.1.3",
+			"resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
+			"integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
+			"license": "MIT"
+		},
+		"node_modules/node-domexception": {
+			"version": "1.0.0",
+			"resolved": "https://registry.npmjs.org/node-domexception/-/node-domexception-1.0.0.tgz",
+			"integrity": "sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=10.5.0"
+			},
+			"deprecated": "Use your platform's native DOMException instead",
+			"funding": [
+				{
+					"type": "github",
+					"url": "https://github.com/sponsors/jimmywarting"
+				},
+				{
+					"type": "github",
+					"url": "https://paypal.me/jimmywarting"
+				}
+			]
+		},
+		"node_modules/node-fetch": {
+			"version": "3.3.2",
+			"resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-3.3.2.tgz",
+			"integrity": "sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==",
+			"license": "MIT",
+			"dependencies": {
+				"data-uri-to-buffer": "^4.0.0",
+				"fetch-blob": "^3.1.4",
+				"formdata-polyfill": "^4.0.10"
+			},
+			"engines": {
+				"node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+			},
+			"funding": {
+				"type": "opencollective",
+				"url": "https://opencollective.com/node-fetch"
+			}
+		},
+		"node_modules/openai": {
+			"version": "6.40.0",
+			"resolved": "https://registry.npmjs.org/openai/-/openai-6.40.0.tgz",
+			"integrity": "sha512-MWtTjd/gQt4jpbji61NTgFWJLoY/PdRJ6wG9/ZDRMYNMlBKrCrSlkLI+KgHP1vR1qT6LKSAyAqIxno6lcK9JiA==",
+			"license": "Apache-2.0",
+			"peerDependencies": {
+				"ws": "^8.18.0",
+				"zod": "^3.25 || ^4.0"
+			},
+			"peerDependenciesMeta": {
+				"ws": {
+					"optional": true
+				},
+				"zod": {
+					"optional": true
+				}
+			}
+		},
+		"node_modules/p-retry": {
+			"version": "4.6.2",
+			"resolved": "https://registry.npmjs.org/p-retry/-/p-retry-4.6.2.tgz",
+			"integrity": "sha512-312Id396EbJdvRONlngUx0NydfrIQ5lsYu0znKVUzVvArzEIt08V1qhtyESbGVd1FGX7UKtiFp5uwKZdM8wIuQ==",
+			"license": "MIT",
+			"dependencies": {
+				"@types/retry": "0.12.0",
+				"retry": "^0.13.1"
+			},
+			"engines": {
+				"node": ">=8"
+			}
+		},
+		"node_modules/p-retry/node_modules/@types/retry": {
+			"version": "0.12.0",
+			"resolved": "https://registry.npmjs.org/@types/retry/-/retry-0.12.0.tgz",
+			"integrity": "sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==",
+			"license": "MIT"
+		},
+		"node_modules/partial-json": {
+			"version": "0.1.7",
+			"resolved": "https://registry.npmjs.org/partial-json/-/partial-json-0.1.7.tgz",
+			"integrity": "sha512-Njv/59hHaokb/hRUjce3Hdv12wd60MtM9Z5Olmn+nehe0QDAsRtRbJPvJ0Z91TusF0SuZRIvnM+S4l6EIP8leA==",
+			"license": "MIT"
+		},
+		"node_modules/path-key": {
+			"version": "3.1.1",
+			"resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+			"integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=8"
+			}
+		},
+		"node_modules/proper-lockfile": {
+			"version": "4.1.2",
+			"resolved": "https://registry.npmjs.org/proper-lockfile/-/proper-lockfile-4.1.2.tgz",
+			"integrity": "sha512-TjNPblN4BwAWMXU8s9AEz4JmQxnD1NNL7bNOY/AKUzyamc379FWASUhc/K1pL2noVb+XmZKLL68cjzLsiOAMaA==",
+			"license": "MIT",
+			"dependencies": {
+				"graceful-fs": "^4.2.4",
+				"retry": "^0.12.0",
+				"signal-exit": "^3.0.2"
+			}
+		},
+		"node_modules/proper-lockfile/node_modules/retry": {
+			"version": "0.12.0",
+			"resolved": "https://registry.npmjs.org/retry/-/retry-0.12.0.tgz",
+			"integrity": "sha512-9LkiTwjUh6rT555DtE9rTX+BKByPfrMzEAtnlEtdEwr3Nkffwiihqe2bWADg+OQRjt9gl6ICdmB/ZFDCGAtSow==",
+			"license": "MIT",
+			"engines": {
+				"node": ">= 4"
+			}
+		},
+		"node_modules/protobufjs": {
+			"version": "7.6.6",
+			"resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.6.6.tgz",
+			"integrity": "sha512-dYDWdjSl5RNb7SgPxGQcRU+GtvP7s2fpkrY0r432PcOIaZ0/rBcxEZnQN67iJhFuQiVw754JDoPruPCNdGsbjg==",
+			"license": "BSD-3-Clause",
+			"dependencies": {
+				"@protobufjs/aspromise": "^1.1.2",
+				"@protobufjs/base64": "^1.1.2",
+				"@protobufjs/codegen": "^2.0.5",
+				"@protobufjs/eventemitter": "^1.1.1",
+				"@protobufjs/fetch": "^1.1.1",
+				"@protobufjs/float": "^1.0.2",
+				"@protobufjs/path": "^1.1.2",
+				"@protobufjs/pool": "^1.1.0",
+				"@protobufjs/utf8": "^1.1.1",
+				"@types/node": ">=13.7.0",
+				"long": "^5.3.2"
+			},
+			"engines": {
+				"node": ">=12.0.0"
+			},
+			"hasInstallScript": true
+		},
+		"node_modules/proxy-agent-negotiate": {
+			"version": "1.1.0",
+			"resolved": "https://registry.npmjs.org/proxy-agent-negotiate/-/proxy-agent-negotiate-1.1.0.tgz",
+			"integrity": "sha512-N8IBcM3UgCVzz2L2Lqv8DVntDnnC8/hiV4nEDUPkqq72TPUgYWjQc+bdZlBPZK9LzPAvOY//gAt0S0DApoOXWQ==",
+			"license": "MIT",
+			"peerDependencies": {
+				"kerberos": "^2.0.0"
+			},
+			"peerDependenciesMeta": {
+				"kerberos": {
+					"optional": true
+				}
+			},
+			"engines": {
+				"node": ">= 20"
+			}
+		},
+		"node_modules/retry": {
+			"version": "0.13.1",
+			"resolved": "https://registry.npmjs.org/retry/-/retry-0.13.1.tgz",
+			"integrity": "sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg==",
+			"license": "MIT",
+			"engines": {
+				"node": ">= 4"
+			}
+		},
+		"node_modules/safe-buffer": {
+			"version": "5.2.1",
+			"resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
+			"integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
+			"license": "MIT",
+			"funding": [
+				{
+					"type": "github",
+					"url": "https://github.com/sponsors/feross"
+				},
+				{
+					"type": "patreon",
+					"url": "https://www.patreon.com/feross"
+				},
+				{
+					"type": "consulting",
+					"url": "https://feross.org/support"
+				}
+			]
+		},
+		"node_modules/semver": {
+			"version": "7.8.5",
+			"resolved": "https://registry.npmjs.org/semver/-/semver-7.8.5.tgz",
+			"integrity": "sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==",
+			"license": "ISC",
+			"bin": {
+				"semver": "bin/semver.js"
+			},
+			"engines": {
+				"node": ">=10"
+			}
+		},
+		"node_modules/shebang-command": {
+			"version": "2.0.0",
+			"resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+			"integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+			"license": "MIT",
+			"dependencies": {
+				"shebang-regex": "^3.0.0"
+			},
+			"engines": {
+				"node": ">=8"
+			}
+		},
+		"node_modules/shebang-regex": {
+			"version": "3.0.0",
+			"resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+			"integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=8"
+			}
+		},
+		"node_modules/signal-exit": {
+			"version": "3.0.7",
+			"resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",
+			"integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
+			"license": "ISC"
+		},
+		"node_modules/standardwebhooks": {
+			"version": "1.1.1",
+			"resolved": "https://registry.npmjs.org/standardwebhooks/-/standardwebhooks-1.1.1.tgz",
+			"integrity": "sha512-bCbX9ZEyFkWPsRz7Bl3NuQUJohmwGSev/yhr7vhaGPlc4AfIrspIRa6cPTBuI1ItmrTDJ4d/S2hCsfe4+vQGnQ==",
+			"license": "MIT",
+			"dependencies": {
+				"@stablelib/base64": "^1.0.0",
+				"fast-sha256": "^1.3.0"
+			}
+		},
+		"node_modules/ts-algebra": {
+			"version": "2.0.0",
+			"resolved": "https://registry.npmjs.org/ts-algebra/-/ts-algebra-2.0.0.tgz",
+			"integrity": "sha512-FPAhNPFMrkwz76P7cdjdmiShwMynZYN6SgOujD1urY4oNm80Ou9oMdmbR45LotcKOXoy7wSmHkRFE6Mxbrhefw==",
+			"license": "MIT"
+		},
+		"node_modules/tslib": {
+			"version": "2.8.1",
+			"resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+			"integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+			"license": "0BSD"
+		},
+		"node_modules/typebox": {
+			"version": "1.3.27",
+			"resolved": "https://registry.npmjs.org/typebox/-/typebox-1.3.27.tgz",
+			"integrity": "sha512-zu+jc1pcy4UiNThxikUr36f0Rybk9PEeCg/NE6adeWr/SKsdNO4EzZHYRDlv2YCVAfj3Odq3dESSo/jNyoBXzA==",
+			"license": "MIT"
+		},
+		"node_modules/undici": {
+			"version": "8.10.2",
+			"resolved": "https://registry.npmjs.org/undici/-/undici-8.10.2.tgz",
+			"integrity": "sha512-/y4/bH9YNU5hi9NIrpOuvGXFcxrj3CMrV+/AYpowAYTpHn8gX/XPFjNy766FPoYY0miQhdW977JFWKGNhBdwyQ==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=22.19.0"
+			}
+		},
+		"node_modules/undici-types": {
+			"version": "6.21.0",
+			"resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz",
+			"integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
+			"license": "MIT"
+		},
+		"node_modules/web-streams-polyfill": {
+			"version": "3.3.3",
+			"resolved": "https://registry.npmjs.org/web-streams-polyfill/-/web-streams-polyfill-3.3.3.tgz",
+			"integrity": "sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==",
+			"license": "MIT",
+			"engines": {
+				"node": ">= 8"
+			}
+		},
+		"node_modules/which": {
+			"version": "2.0.2",
+			"resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+			"integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+			"license": "ISC",
+			"dependencies": {
+				"isexe": "^2.0.0"
+			},
+			"bin": {
+				"node-which": "bin/node-which"
+			},
+			"engines": {
+				"node": ">= 8"
+			}
+		},
+		"node_modules/ws": {
+			"version": "8.21.0",
+			"resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz",
+			"integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==",
+			"license": "MIT",
+			"peerDependencies": {
+				"bufferutil": "^4.0.1",
+				"utf-8-validate": ">=5.0.2"
+			},
+			"peerDependenciesMeta": {
+				"bufferutil": {
+					"optional": true
+				},
+				"utf-8-validate": {
+					"optional": true
+				}
+			},
+			"engines": {
+				"node": ">=10.0.0"
+			}
+		},
+		"node_modules/yaml": {
+			"version": "2.9.0",
+			"resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+			"integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
+			"license": "ISC",
+			"bin": {
+				"yaml": "bin.mjs"
+			},
+			"engines": {
+				"node": ">= 14.6"
+			},
+			"funding": {
+				"url": "https://github.com/sponsors/eemeli"
+			}
+		}
+	}
+}

packages/coding-agent/install-lock/package.json

@@ -0,0 +1,15 @@
+{
+	"name": "@earendil-works/pi-coding-agent-install",
+	"version": "0.85.1",
+	"private": true,
+	"description": "Lockfile root used by the Pi installer and updater.",
+	"dependencies": {
+		"@earendil-works/pi-coding-agent": "0.85.1"
+	},
+	"overrides": {
+		"protobufjs": "7.6.6"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	}
+}

packages/coding-agent/src/core/compaction/branch-summarization.ts

@@ -0,0 +1,382 @@
+/**
+ * Branch summarization for tree navigation.
+ *
+ * When navigating to a different point in the session tree, this generates
+ * a summary of the branch being left so context isn't lost.
+ */
+
+import type { AgentMessage, StreamFn } from "@earendil-works/pi-agent-core";
+import type { RetryCallbacks, RetryPolicy } from "@earendil-works/pi-ai";
+import { contentText } from "@earendil-works/pi-ai";
+import type { Model, SimpleStreamOptions, Usage } from "@earendil-works/pi-ai/compat";
+import {
+	convertToLlm,
+	createBranchSummaryMessage,
+	createCompactionSummaryMessage,
+	createCustomMessage,
+} from "../messages.ts";
+import type { ReadonlySessionManager, SessionEntry } from "../session-manager.ts";
+import { completeSummarization, estimateTokens, getSummarizationFailure } from "./compaction.ts";
+import {
+	computeFileLists,
+	createFileOps,
+	extractFileOpsFromMessage,
+	type FileOperations,
+	formatFileOperations,
+	SUMMARIZATION_SYSTEM_PROMPT,
+	serializeConversation,
+} from "./utils.ts";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface BranchSummaryResult {
+	summary?: string;
+	usage?: Usage;
+	readFiles?: string[];
+	modifiedFiles?: string[];
+	aborted?: boolean;
+	error?: string;
+}
+
+/** Details stored in BranchSummaryEntry.details for file tracking */
+export interface BranchSummaryDetails {
+	readFiles: string[];
+	modifiedFiles: string[];
+}
+
+export type { FileOperations } from "./utils.ts";
+
+export interface BranchPreparation {
+	/** Messages extracted for summarization, in chronological order */
+	messages: AgentMessage[];
+	/** File operations extracted from tool calls */
+	fileOps: FileOperations;
+	/** Total estimated tokens in messages */
+	totalTokens: number;
+}
+
+export interface CollectEntriesResult {
+	/** Entries to summarize, in chronological order */
+	entries: SessionEntry[];
+	/** Common ancestor between old and new position, if any */
+	commonAncestorId: string | null;
+}
+
+export interface GenerateBranchSummaryOptions {
+	/** Model to use for summarization */
+	model: Model<any>;
+	/** API key for the model */
+	apiKey?: string;
+	/** Request headers for the model */
+	headers?: Record<string, string>;
+	/** Provider-scoped environment values for the model */
+	env?: Record<string, string>;
+	/** Abort signal for cancellation */
+	signal: AbortSignal;
+	/** Optional custom instructions for summarization */
+	customInstructions?: string;
+	/** If true, customInstructions replaces the default prompt instead of being appended */
+	replaceInstructions?: boolean;
+	/** Tokens reserved when selecting branch history (default 16384) */
+	reserveTokens?: number;
+	/** Optional session stream function. Used to preserve SDK request behavior without mutating agent state. */
+	streamFn?: StreamFn;
+	/** Retry policy for transient summarization errors. Reuses coding-agent's `settings.retry`. */
+	retry?: RetryPolicy;
+	/** Optional callbacks for retry reporting (e.g. TUI retry indicators). */
+	callbacks?: RetryCallbacks;
+}
+
+// ============================================================================
+// Entry Collection
+// ============================================================================
+
+/**
+ * Collect entries that should be summarized when navigating from one position to another.
+ *
+ * Walks from oldLeafId back to the common ancestor with targetId, collecting entries
+ * along the way. Does NOT stop at compaction boundaries - those are included and their
+ * summaries become context.
+ *
+ * @param session - Session manager (read-only access)
+ * @param oldLeafId - Current position (where we're navigating from)
+ * @param targetId - Target position (where we're navigating to)
+ * @returns Entries to summarize and the common ancestor
+ */
+export function collectEntriesForBranchSummary(
+	session: ReadonlySessionManager,
+	oldLeafId: string | null,
+	targetId: string,
+): CollectEntriesResult {
+	// If no old position, nothing to summarize
+	if (!oldLeafId) {
+		return { entries: [], commonAncestorId: null };
+	}
+
+	// Find common ancestor (deepest node that's on both paths)
+	const oldPath = new Set(session.getBranch(oldLeafId).map((e) => e.id));
+	const targetPath = session.getBranch(targetId);
+
+	// targetPath is root-first, so iterate backwards to find deepest common ancestor
+	let commonAncestorId: string | null = null;
+	for (let i = targetPath.length - 1; i >= 0; i--) {
+		if (oldPath.has(targetPath[i].id)) {
+			commonAncestorId = targetPath[i].id;
+			break;
+		}
+	}
+
+	// Collect entries from old leaf back to common ancestor
+	const entries: SessionEntry[] = [];
+	let current: string | null = oldLeafId;
+
+	while (current && current !== commonAncestorId) {
+		const entry = session.getEntry(current);
+		if (!entry) break;
+		entries.push(entry);
+		current = entry.parentId;
+	}
+
+	// Reverse to get chronological order
+	entries.reverse();
+
+	return { entries, commonAncestorId };
+}
+
+// ============================================================================
+// Entry to Message Conversion
+// ============================================================================
+
+/**
+ * Extract AgentMessage from a session entry.
+ * Similar to getMessageFromEntry in compaction.ts but also handles compaction entries.
+ */
+function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined {
+	switch (entry.type) {
+		case "message":
+			// Skip tool results - context is in assistant's tool call
+			if (entry.message.role === "toolResult") return undefined;
+			return entry.message;
+
+		case "custom_message":
+			return createCustomMessage(entry.customType, entry.content, entry.display, entry.details, entry.timestamp);
+
+		case "branch_summary":
+			return createBranchSummaryMessage(entry.summary, entry.fromId, entry.timestamp);
+
+		case "compaction":
+			return createCompactionSummaryMessage(entry.summary, entry.tokensBefore, entry.timestamp);
+
+		// These don't contribute to conversation content
+		case "thinking_level_change":
+		case "model_change":
+		case "custom":
+		case "label":
+		case "session_info":
+			return undefined;
+	}
+}
+
+/**
+ * Prepare entries for summarization with token budget.
+ *
+ * Walks entries from NEWEST to OLDEST, adding messages until we hit the token budget.
+ * This ensures we keep the most recent context when the branch is too long.
+ *
+ * Also collects file operations from:
+ * - Tool calls in assistant messages
+ * - Existing branch_summary entries' details (for cumulative tracking)
+ *
+ * @param entries - Entries in chronological order
+ * @param tokenBudget - Maximum tokens to include (0 = no limit)
+ */
+export function prepareBranchEntries(entries: SessionEntry[], tokenBudget: number = 0): BranchPreparation {
+	const messages: AgentMessage[] = [];
+	const fileOps = createFileOps();
+	let totalTokens = 0;
+
+	// First pass: collect file ops from ALL entries (even if they don't fit in token budget)
+	// This ensures we capture cumulative file tracking from nested branch summaries
+	// Only extract from pi-generated summaries (fromHook !== true), not extension-generated ones
+	for (const entry of entries) {
+		if (entry.type === "branch_summary" && !entry.fromHook && entry.details) {
+			const details = entry.details as BranchSummaryDetails;
+			if (Array.isArray(details.readFiles)) {
+				for (const f of details.readFiles) fileOps.read.add(f);
+			}
+			if (Array.isArray(details.modifiedFiles)) {
+				// Modified files go into both edited and written for proper deduplication
+				for (const f of details.modifiedFiles) {
+					fileOps.edited.add(f);
+				}
+			}
+		}
+	}
+
+	// Second pass: walk from newest to oldest, adding messages until token budget
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		const message = getMessageFromEntry(entry);
+		if (!message) continue;
+
+		// Extract file ops from assistant messages (tool calls)
+		extractFileOpsFromMessage(message, fileOps);
+
+		const tokens = estimateTokens(message);
+
+		// Check budget before adding
+		if (tokenBudget > 0 && totalTokens + tokens > tokenBudget) {
+			// If this is a summary entry, try to fit it anyway as it's important context
+			if (entry.type === "compaction" || entry.type === "branch_summary") {
+				if (totalTokens < tokenBudget * 0.9) {
+					messages.unshift(message);
+					totalTokens += tokens;
+				}
+			}
+			// Stop - we've hit the budget
+			break;
+		}
+
+		messages.unshift(message);
+		totalTokens += tokens;
+	}
+
+	return { messages, fileOps, totalTokens };
+}
+
+// ============================================================================
+// Summary Generation
+// ============================================================================
+
+const BRANCH_SUMMARY_PREAMBLE = `The user explored a different conversation branch before returning here.
+Summary of that exploration:
+
+`;
+
+const BRANCH_SUMMARY_PROMPT = `Create a structured summary of this conversation branch for context when returning later.
+
+Use this EXACT format:
+
+## Goal
+[What was the user trying to accomplish in this branch?]
+
+## Constraints & Preferences
+- [Any constraints, preferences, or requirements mentioned]
+- [Or "(none)" if none were mentioned]
+
+## Progress
+### Done
+- [x] [Completed tasks/changes]
+
+### In Progress
+- [ ] [Work that was started but not finished]
+
+### Blocked
+- [Issues preventing progress, if any]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale]
+
+## Next Steps
+1. [What should happen next to continue this work]
+
+Keep each section concise. Preserve exact file paths, function names, and error messages.`;
+
+/**
+ * Generate a summary of abandoned branch entries.
+ *
+ * @param entries - Session entries to summarize (chronological order)
+ * @param options - Generation options
+ */
+export async function generateBranchSummary(
+	entries: SessionEntry[],
+	options: GenerateBranchSummaryOptions,
+): Promise<BranchSummaryResult> {
+	const {
+		model,
+		apiKey,
+		headers,
+		env,
+		signal,
+		customInstructions,
+		replaceInstructions,
+		reserveTokens = 16384,
+		streamFn,
+		retry,
+		callbacks,
+	} = options;
+
+	// Token budget = context window minus reserved space for prompt + response
+	const contextWindow = model.contextWindow || 128000;
+	const tokenBudget = contextWindow - reserveTokens;
+
+	const { messages, fileOps } = prepareBranchEntries(entries, tokenBudget);
+
+	if (messages.length === 0) {
+		return { summary: "No content to summarize" };
+	}
+
+	// Transform to LLM-compatible messages, then serialize to text
+	// Serialization prevents the model from treating it as a conversation to continue
+	const llmMessages = convertToLlm(messages);
+	const conversationText = serializeConversation(llmMessages);
+
+	// Build prompt
+	let instructions: string;
+	if (replaceInstructions && customInstructions) {
+		instructions = customInstructions;
+	} else if (customInstructions) {
+		instructions = `${BRANCH_SUMMARY_PROMPT}\n\nAdditional focus: ${customInstructions}`;
+	} else {
+		instructions = BRANCH_SUMMARY_PROMPT;
+	}
+	const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${instructions}`;
+
+	const summarizationMessages = [
+		{
+			role: "user" as const,
+			content: [{ type: "text" as const, text: promptText }],
+			timestamp: Date.now(),
+		},
+	];
+
+	const maxTokens = Math.min(4096, model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY);
+
+	// Call LLM for summarization. Prefer the session stream function so SDK
+	// request behavior (timeouts, retries, attribution headers) stays consistent
+	// without running through agent state/events. Retried via completeSummarization
+	// so transient stream drops reuse the configured retry policy.
+	const context = { systemPrompt: SUMMARIZATION_SYSTEM_PROMPT, messages: summarizationMessages };
+	const requestOptions: SimpleStreamOptions = { apiKey, headers, env, signal, maxTokens };
+	const response = await completeSummarization(model, context, requestOptions, streamFn, retry, callbacks);
+
+	// Check if aborted or errored
+	if (response.stopReason === "aborted") {
+		return { aborted: true };
+	}
+	const failure = getSummarizationFailure(response, "Branch summarization");
+	if (failure) {
+		return { error: failure };
+	}
+	if (response.content.some((block) => block.type === "toolCall")) {
+		return { error: "Branch summarization attempted to call a tool" };
+	}
+
+	let summary = contentText(response.content);
+
+	// Prepend preamble to provide context about the branch summary
+	summary = BRANCH_SUMMARY_PREAMBLE + summary;
+
+	// Compute file lists and append to summary
+	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
+	summary += formatFileOperations(readFiles, modifiedFiles);
+
+	return {
+		summary: summary || "No summary generated",
+		usage: response.usage,
+		readFiles,
+		modifiedFiles,
+	};
+}

packages/coding-agent/src/core/compaction/compaction.ts

@@ -0,0 +1,1012 @@
+/**
+ * Context compaction for long sessions.
+ *
+ * Pure functions for compaction logic. The session manager handles I/O,
+ * and after compaction the session is reloaded.
+ */
+
+import type { AgentMessage, StreamFn, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { contentText, type RetryCallbacks, type RetryPolicy, retryAssistantCall, uuidv7 } from "@earendil-works/pi-ai";
+import type { AssistantMessage, Context, Model, SimpleStreamOptions, Usage } from "@earendil-works/pi-ai/compat";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import { convertToLlm } from "../messages.ts";
+import {
+	buildSessionContext,
+	type CompactionEntry,
+	type SessionEntry,
+	sessionEntryToContextMessages,
+} from "../session-manager.ts";
+import {
+	computeFileLists,
+	createFileOps,
+	extractFileOpsFromMessage,
+	type FileOperations,
+	formatFileOperations,
+	SUMMARIZATION_SYSTEM_PROMPT,
+	serializeConversation,
+} from "./utils.ts";
+
+// ============================================================================
+// File Operation Tracking
+// ============================================================================
+
+/** Details stored in CompactionEntry.details for file tracking */
+export interface CompactionDetails {
+	readFiles: string[];
+	modifiedFiles: string[];
+}
+
+/**
+ * Extract file operations from messages and previous compaction entries.
+ */
+function extractFileOperations(
+	messages: AgentMessage[],
+	entries: SessionEntry[],
+	prevCompactionIndex: number,
+): FileOperations {
+	const fileOps = createFileOps();
+
+	// Collect from previous compaction's details (if pi-generated)
+	if (prevCompactionIndex >= 0) {
+		const prevCompaction = entries[prevCompactionIndex] as CompactionEntry;
+		if (!prevCompaction.fromHook && prevCompaction.details) {
+			// fromHook field kept for session file compatibility
+			const details = prevCompaction.details as CompactionDetails;
+			if (Array.isArray(details.readFiles)) {
+				for (const f of details.readFiles) fileOps.read.add(f);
+			}
+			if (Array.isArray(details.modifiedFiles)) {
+				for (const f of details.modifiedFiles) fileOps.edited.add(f);
+			}
+		}
+	}
+
+	// Extract from tool calls in messages
+	for (const msg of messages) {
+		extractFileOpsFromMessage(msg, fileOps);
+	}
+
+	return fileOps;
+}
+
+// ============================================================================
+// Message Extraction
+// ============================================================================
+
+/**
+ * Extract AgentMessage from an entry if it produces one.
+ * Returns undefined for entries that don't contribute to LLM context.
+ */
+function getMessageFromEntryForCompaction(entry: SessionEntry): AgentMessage | undefined {
+	if (entry.type === "compaction") {
+		return undefined;
+	}
+	return sessionEntryToContextMessages(entry)[0];
+}
+
+/** Result from compact() - SessionManager adds uuid/parentUuid when saving */
+export interface CompactionResult<T = unknown> {
+	summary: string;
+	firstKeptEntryId: string;
+	tokensBefore: number;
+	estimatedTokensAfter?: number;
+	/** Usage from the LLM call(s) that generated this summary, if available */
+	usage?: Usage;
+	/** Extension-specific data (e.g., ArtifactIndex, version markers for structured compaction) */
+	details?: T;
+}
+
+function combineUsage(first: Usage, second: Usage): Usage {
+	return {
+		input: first.input + second.input,
+		output: first.output + second.output,
+		cacheRead: first.cacheRead + second.cacheRead,
+		cacheWrite: first.cacheWrite + second.cacheWrite,
+		...(first.cacheWrite1h !== undefined || second.cacheWrite1h !== undefined
+			? { cacheWrite1h: (first.cacheWrite1h ?? 0) + (second.cacheWrite1h ?? 0) }
+			: {}),
+		...(first.reasoning !== undefined || second.reasoning !== undefined
+			? { reasoning: (first.reasoning ?? 0) + (second.reasoning ?? 0) }
+			: {}),
+		totalTokens: first.totalTokens + second.totalTokens,
+		cost: {
+			input: first.cost.input + second.cost.input,
+			output: first.cost.output + second.cost.output,
+			cacheRead: first.cost.cacheRead + second.cost.cacheRead,
+			cacheWrite: first.cost.cacheWrite + second.cost.cacheWrite,
+			total: first.cost.total + second.cost.total,
+		},
+	};
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CompactionSettings {
+	enabled: boolean;
+	reserveTokens: number;
+	keepRecentTokens: number;
+}
+
+export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {
+	enabled: true,
+	reserveTokens: 16384,
+	keepRecentTokens: 20000,
+};
+
+// ============================================================================
+// Token calculation
+// ============================================================================
+
+/**
+ * Calculate total context tokens from usage.
+ * Uses the native totalTokens field when available, falls back to computing from components.
+ */
+export function calculateContextTokens(usage: Usage): number {
+	return usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+}
+
+/**
+ * Get usage from an assistant message if available.
+ * Skips aborted, error, and all-zero usage messages as they don't have valid usage data.
+ */
+function getAssistantUsage(msg: AgentMessage): Usage | undefined {
+	if (msg.role === "assistant" && "usage" in msg) {
+		const assistantMsg = msg as AssistantMessage;
+		if (
+			assistantMsg.stopReason !== "aborted" &&
+			assistantMsg.stopReason !== "error" &&
+			assistantMsg.usage &&
+			calculateContextTokens(assistantMsg.usage) > 0
+		) {
+			return assistantMsg.usage;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Find the last valid assistant message usage from session entries.
+ */
+export function getLastAssistantUsage(entries: SessionEntry[]): Usage | undefined {
+	for (let i = entries.length - 1; i >= 0; i--) {
+		const entry = entries[i];
+		if (entry.type === "message") {
+			const usage = getAssistantUsage(entry.message);
+			if (usage) return usage;
+		}
+	}
+	return undefined;
+}
+
+export interface ContextUsageEstimate {
+	tokens: number;
+	usageTokens: number;
+	trailingTokens: number;
+	lastUsageIndex: number | null;
+}
+
+function getLastAssistantUsageInfo(messages: AgentMessage[]): { usage: Usage; index: number } | undefined {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const usage = getAssistantUsage(messages[i]);
+		if (usage) return { usage, index: i };
+	}
+	return undefined;
+}
+
+/**
+ * Estimate context tokens from messages, using the last assistant usage when available.
+ * If there are messages after the last usage, estimate their tokens with estimateTokens.
+ */
+export function estimateContextTokens(messages: AgentMessage[]): ContextUsageEstimate {
+	const usageInfo = getLastAssistantUsageInfo(messages);
+
+	if (!usageInfo) {
+		let estimated = 0;
+		for (const message of messages) {
+			estimated += estimateTokens(message);
+		}
+		return {
+			tokens: estimated,
+			usageTokens: 0,
+			trailingTokens: estimated,
+			lastUsageIndex: null,
+		};
+	}
+
+	const usageTokens = calculateContextTokens(usageInfo.usage);
+	let trailingTokens = 0;
+	for (let i = usageInfo.index + 1; i < messages.length; i++) {
+		trailingTokens += estimateTokens(messages[i]);
+	}
+
+	return {
+		tokens: usageTokens + trailingTokens,
+		usageTokens,
+		trailingTokens,
+		lastUsageIndex: usageInfo.index,
+	};
+}
+
+/**
+ * Check if compaction should trigger based on context usage.
+ */
+export function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean {
+	if (!settings.enabled) return false;
+	return contextTokens > contextWindow - settings.reserveTokens;
+}
+
+// ============================================================================
+// Cut point detection
+// ============================================================================
+
+const ESTIMATED_IMAGE_CHARS = 4800;
+
+function estimateTextAndImageContentChars(content: string | Array<{ type: string; text?: string }>): number {
+	if (typeof content === "string") {
+		return content.length;
+	}
+
+	let chars = 0;
+	for (const block of content) {
+		if (block.type === "text" && block.text) {
+			chars += block.text.length;
+		} else if (block.type === "image") {
+			chars += ESTIMATED_IMAGE_CHARS;
+		}
+	}
+	return chars;
+}
+
+/**
+ * Estimate token count for a message using chars/4 heuristic.
+ * This is conservative (overestimates tokens).
+ */
+export function estimateTokens(message: AgentMessage): number {
+	let chars = 0;
+
+	switch (message.role) {
+		case "user": {
+			chars = estimateTextAndImageContentChars(
+				(message as { content: string | Array<{ type: string; text?: string }> }).content,
+			);
+			return Math.ceil(chars / 4);
+		}
+		case "assistant": {
+			const assistant = message as AssistantMessage;
+			for (const block of assistant.content) {
+				if (block.type === "text") {
+					chars += block.text.length;
+				} else if (block.type === "thinking") {
+					chars += block.thinking.length;
+				} else if (block.type === "toolCall") {
+					chars += block.name.length + JSON.stringify(block.arguments).length;
+				}
+			}
+			return Math.ceil(chars / 4);
+		}
+		case "custom":
+		case "toolResult": {
+			chars = estimateTextAndImageContentChars(message.content);
+			return Math.ceil(chars / 4);
+		}
+		case "bashExecution": {
+			chars = message.command.length + message.output.length;
+			return Math.ceil(chars / 4);
+		}
+		case "branchSummary":
+		case "compactionSummary": {
+			chars = message.summary.length;
+			return Math.ceil(chars / 4);
+		}
+	}
+
+	return 0;
+}
+
+function isCutPointMessage(message: AgentMessage): boolean {
+	switch (message.role) {
+		case "user":
+		case "assistant":
+		case "bashExecution":
+		case "custom":
+		case "branchSummary":
+		case "compactionSummary":
+			return true;
+		case "toolResult":
+			return false;
+	}
+	return false;
+}
+
+function isTurnStartMessage(message: AgentMessage): boolean {
+	switch (message.role) {
+		case "user":
+		case "bashExecution":
+		case "custom":
+		case "branchSummary":
+		case "compactionSummary":
+			return true;
+		case "assistant":
+		case "toolResult":
+			return false;
+	}
+	return false;
+}
+
+function isTurnStartEntry(entry: SessionEntry): boolean {
+	if (entry.type === "compaction") {
+		return false;
+	}
+	return sessionEntryToContextMessages(entry).some(isTurnStartMessage);
+}
+
+/**
+ * Find valid cut points: indices of context-visible user-like or assistant messages.
+ * Never cut at tool results (they must follow their tool call).
+ * When we cut at an assistant message with tool calls, its tool results follow it
+ * and will be kept.
+ */
+function findValidCutPoints(entries: SessionEntry[], startIndex: number, endIndex: number): number[] {
+	const cutPoints: number[] = [];
+	for (let i = startIndex; i < endIndex; i++) {
+		const entry = entries[i];
+		if (entry.type === "compaction") {
+			continue;
+		}
+		if (sessionEntryToContextMessages(entry).some(isCutPointMessage)) {
+			cutPoints.push(i);
+		}
+	}
+	return cutPoints;
+}
+
+/**
+ * Find the context-visible user-role message that starts the turn containing the given entry index.
+ * Returns -1 if no turn start found before the index.
+ */
+export function findTurnStartIndex(entries: SessionEntry[], entryIndex: number, startIndex: number): number {
+	for (let i = entryIndex; i >= startIndex; i--) {
+		if (isTurnStartEntry(entries[i])) {
+			return i;
+		}
+	}
+	return -1;
+}
+
+export interface CutPointResult {
+	/** Index of first entry to keep */
+	firstKeptEntryIndex: number;
+	/** Index of user message that starts the turn being split, or -1 if not splitting */
+	turnStartIndex: number;
+	/** Whether this cut splits a turn (cut point is not a user message) */
+	isSplitTurn: boolean;
+}
+
+/**
+ * Find the cut point in session entries that keeps approximately `keepRecentTokens`.
+ *
+ * Algorithm: Walk backwards from newest, accumulating estimated message sizes.
+ * Stop when we've accumulated >= keepRecentTokens. Cut at that point.
+ *
+ * Can cut at user OR assistant messages (never tool results). When cutting at an
+ * assistant message with tool calls, its tool results come after and will be kept.
+ *
+ * Returns CutPointResult with:
+ * - firstKeptEntryIndex: the entry index to start keeping from
+ * - turnStartIndex: if cutting mid-turn, the user message that started that turn
+ * - isSplitTurn: whether we're cutting in the middle of a turn
+ *
+ * Only considers entries between `startIndex` and `endIndex` (exclusive).
+ */
+export function findCutPoint(
+	entries: SessionEntry[],
+	startIndex: number,
+	endIndex: number,
+	keepRecentTokens: number,
+): CutPointResult {
+	const cutPoints = findValidCutPoints(entries, startIndex, endIndex);
+
+	if (cutPoints.length === 0) {
+		return { firstKeptEntryIndex: startIndex, turnStartIndex: -1, isSplitTurn: false };
+	}
+
+	// Walk backwards from newest, accumulating estimated message sizes
+	let accumulatedTokens = 0;
+	let cutIndex = cutPoints[0]; // Default: keep from first message (not header)
+
+	for (let i = endIndex - 1; i >= startIndex; i--) {
+		const entry = entries[i];
+		const messageTokens = sessionEntryToContextMessages(entry).reduce(
+			(sum, message) => sum + estimateTokens(message),
+			0,
+		);
+		if (messageTokens === 0) continue;
+		accumulatedTokens += messageTokens;
+
+		// Check if we've exceeded the budget
+		if (accumulatedTokens >= keepRecentTokens) {
+			// Find the closest valid cut point at or after this entry
+			for (let c = 0; c < cutPoints.length; c++) {
+				if (cutPoints[c] >= i) {
+					cutIndex = cutPoints[c];
+					break;
+				}
+			}
+			break;
+		}
+	}
+
+	// Scan backwards from cutIndex to include adjacent metadata entries that do not affect context.
+	while (cutIndex > startIndex) {
+		const prevEntry = entries[cutIndex - 1];
+		// Stop at compaction boundaries or context-visible entries.
+		if (prevEntry.type === "compaction" || sessionEntryToContextMessages(prevEntry).length > 0) {
+			break;
+		}
+		cutIndex--;
+	}
+
+	// Determine if this is a split turn
+	const cutEntry = entries[cutIndex];
+	const startsTurn = isTurnStartEntry(cutEntry);
+	const turnStartIndex = startsTurn ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);
+
+	return {
+		firstKeptEntryIndex: cutIndex,
+		turnStartIndex,
+		isSplitTurn: !startsTurn && turnStartIndex !== -1,
+	};
+}
+
+// ============================================================================
+// Summarization
+// ============================================================================
+
+const SUMMARIZATION_PROMPT = `The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
+
+Use this EXACT format:
+
+## Goal
+[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
+
+## Constraints & Preferences
+- [Any constraints, preferences, or requirements mentioned by user]
+- [Or "(none)" if none were mentioned]
+
+## Progress
+### Done
+- [x] [Completed tasks/changes]
+
+### In Progress
+- [ ] [Current work]
+
+### Blocked
+- [Issues preventing progress, if any]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale]
+
+## Next Steps
+1. [Ordered list of what should happen next]
+
+## Critical Context
+- [Any data, examples, or references needed to continue]
+- [Or "(none)" if not applicable]
+
+Keep each section concise. Preserve exact file paths, function names, and error messages.`;
+
+const UPDATE_SUMMARIZATION_INSTRUCTIONS = `Update the existing structured summary with new information. RULES:
+- PRESERVE all existing information from the previous summary
+- ADD new progress, decisions, and context from the new messages
+- UPDATE the Progress section: move items from "In Progress" to "Done" when completed
+- UPDATE "Next Steps" based on what was accomplished
+- PRESERVE exact file paths, function names, and error messages
+- If something is no longer relevant, you may remove it
+
+Use this EXACT format:
+
+## Goal
+[Preserve existing goals, add new ones if the task expanded]
+
+## Constraints & Preferences
+- [Preserve existing, add new ones discovered]
+
+## Progress
+### Done
+- [x] [Include previously done items AND newly completed items]
+
+### In Progress
+- [ ] [Current work - update based on progress]
+
+### Blocked
+- [Current blockers - remove if resolved]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale] (preserve all previous, add new)
+
+## Next Steps
+1. [Update based on current state]
+
+## Critical Context
+- [Preserve important context, add new if needed]
+
+Keep each section concise. Preserve exact file paths, function names, and error messages.`;
+
+const UPDATE_SUMMARIZATION_PROMPT = `The messages above are NEW conversation messages to incorporate into the existing summary provided in <previous-summary> tags.
+
+${UPDATE_SUMMARIZATION_INSTRUCTIONS}`;
+
+/**
+ * Returns an error message when a summarization response cannot safely be persisted.
+ * A length stop contains partial text and must not become a session checkpoint.
+ */
+export function getSummarizationFailure(response: AssistantMessage, label: string): string | undefined {
+	if (response.stopReason === "error") {
+		return `${label} failed: ${response.errorMessage || "Unknown error"}`;
+	}
+	if (response.stopReason === "length") {
+		return `${label} failed: generation hit the token cap and the summary is incomplete`;
+	}
+	return undefined;
+}
+
+function createSummarizationOptions(
+	model: Model<any>,
+	maxTokens: number,
+	apiKey: string | undefined,
+	headers: Record<string, string> | undefined,
+	env: Record<string, string> | undefined,
+	signal: AbortSignal | undefined,
+	thinkingLevel: ThinkingLevel | undefined,
+	sessionId: string | undefined,
+): SimpleStreamOptions {
+	const options: SimpleStreamOptions = { maxTokens, signal, apiKey, headers, env, sessionId };
+	if (model.reasoning && thinkingLevel && thinkingLevel !== "off") {
+		options.reasoning = thinkingLevel;
+	}
+	return options;
+}
+
+/**
+ * Shared choke point for every compaction/branch-summary summarization call. Wraps the
+ * single LLM call in {@link retryAssistantCall} so transient stream drops (e.g.
+ * `terminated`, socket close) honor the configured retry policy instead of failing
+ * the whole compaction on the first attempt. Deterministic errors and aborts return
+ * immediately (see {@link retryAssistantCall}).
+ */
+export async function completeSummarization(
+	model: Model<any>,
+	context: Context,
+	options: SimpleStreamOptions,
+	streamFn?: StreamFn,
+	retry?: RetryPolicy,
+	callbacks?: RetryCallbacks,
+): Promise<AssistantMessage> {
+	// Avoid cache writes for one-off summaries. Reuse caller-supplied routing when available;
+	// callers without a session ID, including branch summaries, receive a fresh routing ID.
+	const requestOptions: SimpleStreamOptions = {
+		...options,
+		cacheRetention: "none",
+		sessionId: options.sessionId ?? uuidv7(),
+	};
+	const produce = async (): Promise<AssistantMessage> =>
+		streamFn
+			? (await streamFn(model, context, requestOptions)).result()
+			: completeSimple(model, context, requestOptions);
+	return retryAssistantCall(produce, retry, requestOptions.signal, callbacks);
+}
+
+/**
+ * Generate a summary of the conversation using the LLM.
+ * If previousSummary is provided, uses the update prompt to merge.
+ */
+export async function generateSummary(
+	currentMessages: AgentMessage[],
+	model: Model<any>,
+	reserveTokens: number,
+	apiKey: string | undefined,
+	headers?: Record<string, string>,
+	signal?: AbortSignal,
+	customInstructions?: string,
+	previousSummary?: string,
+	thinkingLevel?: ThinkingLevel,
+	streamFn?: StreamFn,
+	env?: Record<string, string>,
+	retry?: RetryPolicy,
+	callbacks?: RetryCallbacks,
+	sessionId?: string,
+): Promise<string> {
+	return (
+		await generateSummaryWithUsage(
+			currentMessages,
+			model,
+			reserveTokens,
+			apiKey,
+			headers,
+			signal,
+			customInstructions,
+			previousSummary,
+			thinkingLevel,
+			streamFn,
+			env,
+			retry,
+			callbacks,
+			sessionId,
+		)
+	).text;
+}
+
+/** Build the provider context for a standalone summary request. */
+function buildSummarizationContext(promptText: string): Context {
+	return {
+		systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
+		messages: [
+			{
+				role: "user",
+				content: [{ type: "text", text: promptText }],
+				timestamp: Date.now(),
+			},
+		],
+	};
+}
+
+/** Generate or update a conversation summary and return its provider usage. */
+export async function generateSummaryWithUsage(
+	currentMessages: AgentMessage[],
+	model: Model<any>,
+	reserveTokens: number,
+	apiKey: string | undefined,
+	headers?: Record<string, string>,
+	signal?: AbortSignal,
+	customInstructions?: string,
+	previousSummary?: string,
+	thinkingLevel?: ThinkingLevel,
+	streamFn?: StreamFn,
+	env?: Record<string, string>,
+	retry?: RetryPolicy,
+	callbacks?: RetryCallbacks,
+	sessionId?: string,
+): Promise<{ text: string; usage: Usage }> {
+	const maxTokens = Math.min(
+		Math.floor(0.8 * reserveTokens),
+		model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY,
+	);
+
+	// Use update prompt if we have a previous summary, otherwise initial prompt
+	let basePrompt = previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT;
+	if (customInstructions) {
+		basePrompt = `${basePrompt}\n\nAdditional focus: ${customInstructions}`;
+	}
+
+	// Serialize conversation to text so model doesn't try to continue it
+	// Convert to LLM messages first (handles custom types like bashExecution, custom, etc.)
+	const llmMessages = convertToLlm(currentMessages);
+	const conversationText = serializeConversation(llmMessages);
+
+	// Build the prompt with conversation wrapped in tags
+	let promptText = `<conversation>\n${conversationText}\n</conversation>\n\n`;
+	if (previousSummary) {
+		promptText += `<previous-summary>\n${previousSummary}\n</previous-summary>\n\n`;
+	}
+	promptText += basePrompt;
+
+	const completionOptions = createSummarizationOptions(
+		model,
+		maxTokens,
+		apiKey,
+		headers,
+		env,
+		signal,
+		thinkingLevel,
+		sessionId,
+	);
+
+	const response = await completeSummarization(
+		model,
+		buildSummarizationContext(promptText),
+		completionOptions,
+		streamFn,
+		retry,
+		callbacks,
+	);
+
+	const failure = getSummarizationFailure(response, "Summarization");
+	if (failure) {
+		throw new Error(failure);
+	}
+	if (response.content.some((block) => block.type === "toolCall")) {
+		throw new Error("Summarization attempted to call a tool");
+	}
+
+	const textContent = contentText(response.content);
+
+	return { text: textContent, usage: response.usage };
+}
+
+// ============================================================================
+// Compaction Preparation (for extensions)
+// ============================================================================
+
+export interface CompactionPreparation {
+	/** UUID of first entry to keep */
+	firstKeptEntryId: string;
+	/** Messages that will be summarized and discarded */
+	messagesToSummarize: AgentMessage[];
+	/** Messages that will be turned into turn prefix summary (if splitting) */
+	turnPrefixMessages: AgentMessage[];
+	/** Whether this is a split turn (cut point in middle of turn) */
+	isSplitTurn: boolean;
+	tokensBefore: number;
+	/** Summary from previous compaction, for iterative update */
+	previousSummary?: string;
+	/** File operations extracted from messagesToSummarize */
+	fileOps: FileOperations;
+	/** Compaction settions from settings.jsonl	*/
+	settings: CompactionSettings;
+}
+
+export function prepareCompaction(
+	pathEntries: SessionEntry[],
+	settings: CompactionSettings,
+): CompactionPreparation | undefined {
+	if (pathEntries.length > 0 && pathEntries[pathEntries.length - 1].type === "compaction") {
+		return undefined;
+	}
+
+	let prevCompactionIndex = -1;
+	for (let i = pathEntries.length - 1; i >= 0; i--) {
+		if (pathEntries[i].type === "compaction") {
+			prevCompactionIndex = i;
+			break;
+		}
+	}
+
+	let previousSummary: string | undefined;
+	let boundaryStart = 0;
+	if (prevCompactionIndex >= 0) {
+		const prevCompaction = pathEntries[prevCompactionIndex] as CompactionEntry;
+		previousSummary = prevCompaction.summary;
+		const firstKeptEntryIndex = pathEntries.findIndex((entry) => entry.id === prevCompaction.firstKeptEntryId);
+		boundaryStart = firstKeptEntryIndex >= 0 ? firstKeptEntryIndex : prevCompactionIndex + 1;
+	}
+	const boundaryEnd = pathEntries.length;
+
+	const tokensBefore = estimateContextTokens(buildSessionContext(pathEntries).messages).tokens;
+
+	const cutPoint = findCutPoint(pathEntries, boundaryStart, boundaryEnd, settings.keepRecentTokens);
+
+	// Get UUID of first kept entry
+	const firstKeptEntry = pathEntries[cutPoint.firstKeptEntryIndex];
+	if (!firstKeptEntry?.id) {
+		return undefined; // Session needs migration
+	}
+	const firstKeptEntryId = firstKeptEntry.id;
+
+	const historyEnd = cutPoint.isSplitTurn ? cutPoint.turnStartIndex : cutPoint.firstKeptEntryIndex;
+
+	// Messages to summarize (will be discarded after summary)
+	const messagesToSummarize: AgentMessage[] = [];
+	for (let i = boundaryStart; i < historyEnd; i++) {
+		const msg = getMessageFromEntryForCompaction(pathEntries[i]);
+		if (msg) messagesToSummarize.push(msg);
+	}
+
+	// Messages for turn prefix summary (if splitting a turn)
+	const turnPrefixMessages: AgentMessage[] = [];
+	if (cutPoint.isSplitTurn) {
+		for (let i = cutPoint.turnStartIndex; i < cutPoint.firstKeptEntryIndex; i++) {
+			const msg = getMessageFromEntryForCompaction(pathEntries[i]);
+			if (msg) turnPrefixMessages.push(msg);
+		}
+	}
+
+	if (messagesToSummarize.length === 0 && turnPrefixMessages.length === 0) {
+		return undefined;
+	}
+
+	// Extract file operations from messages and previous compaction
+	const fileOps = extractFileOperations(messagesToSummarize, pathEntries, prevCompactionIndex);
+
+	// Also extract file ops from turn prefix if splitting
+	if (cutPoint.isSplitTurn) {
+		for (const msg of turnPrefixMessages) {
+			extractFileOpsFromMessage(msg, fileOps);
+		}
+	}
+
+	return {
+		firstKeptEntryId,
+		messagesToSummarize,
+		turnPrefixMessages,
+		isSplitTurn: cutPoint.isSplitTurn,
+		tokensBefore,
+		previousSummary,
+		fileOps,
+		settings,
+	};
+}
+
+// ============================================================================
+// Main compaction function
+// ============================================================================
+
+const TURN_PREFIX_SUMMARIZATION_PROMPT = `This is the PREFIX of a turn that was too large to keep. The SUFFIX (recent work) is retained.
+
+Summarize the prefix to provide context for the retained suffix:
+
+## Original Request
+[What did the user ask for in this turn?]
+
+## Early Progress
+- [Key decisions and work done in the prefix]
+
+## Context for Suffix
+- [Information needed to understand the retained recent work]
+
+Be concise. Focus on what's needed to understand the kept suffix.`;
+
+/**
+ * Generate summaries for compaction using prepared data.
+ * Returns CompactionResult - SessionManager adds uuid/parentUuid when saving.
+ *
+ * @param preparation - Pre-calculated preparation from prepareCompaction()
+ * @param customInstructions - Optional custom focus for the summary
+ * @param sessionId - Optional routing session ID forwarded without enabling prompt caching
+ */
+export async function compact(
+	preparation: CompactionPreparation,
+	model: Model<any>,
+	apiKey: string | undefined,
+	headers?: Record<string, string>,
+	customInstructions?: string,
+	signal?: AbortSignal,
+	thinkingLevel?: ThinkingLevel,
+	streamFn?: StreamFn,
+	env?: Record<string, string>,
+	retry?: RetryPolicy,
+	callbacks?: RetryCallbacks,
+	sessionId?: string,
+): Promise<CompactionResult> {
+	const {
+		firstKeptEntryId,
+		messagesToSummarize,
+		turnPrefixMessages,
+		isSplitTurn,
+		tokensBefore,
+		previousSummary,
+		fileOps,
+		settings,
+	} = preparation;
+
+	// Generate summaries and merge into one
+	let summary: string;
+	let summaryUsage: Usage;
+
+	if (isSplitTurn && turnPrefixMessages.length > 0) {
+		let historyText = "No prior history.";
+		let historyUsage: Usage | undefined;
+		if (messagesToSummarize.length > 0) {
+			const historyResult = await generateSummaryWithUsage(
+				messagesToSummarize,
+				model,
+				settings.reserveTokens,
+				apiKey,
+				headers,
+				signal,
+				customInstructions,
+				previousSummary,
+				thinkingLevel,
+				streamFn,
+				env,
+				retry,
+				callbacks,
+				sessionId,
+			);
+			historyText = historyResult.text;
+			historyUsage = historyResult.usage;
+		}
+		const turnPrefixResult = await generateTurnPrefixSummary(
+			turnPrefixMessages,
+			model,
+			settings.reserveTokens,
+			apiKey,
+			headers,
+			env,
+			signal,
+			thinkingLevel,
+			streamFn,
+			retry,
+			callbacks,
+			sessionId,
+		);
+		// Merge into single summary
+		summary = `${historyText}\n\n---\n\n**Turn Context (split turn):**\n\n${turnPrefixResult.text}`;
+		summaryUsage = historyUsage ? combineUsage(historyUsage, turnPrefixResult.usage) : turnPrefixResult.usage;
+	} else {
+		// Just generate history summary
+		const result = await generateSummaryWithUsage(
+			messagesToSummarize,
+			model,
+			settings.reserveTokens,
+			apiKey,
+			headers,
+			signal,
+			customInstructions,
+			previousSummary,
+			thinkingLevel,
+			streamFn,
+			env,
+			retry,
+			callbacks,
+			sessionId,
+		);
+		summary = result.text;
+		summaryUsage = result.usage;
+	}
+
+	// Compute file lists and append to summary
+	const { readFiles, modifiedFiles } = computeFileLists(fileOps);
+	summary += formatFileOperations(readFiles, modifiedFiles);
+
+	if (!firstKeptEntryId) {
+		throw new Error("First kept entry has no UUID - session may need migration");
+	}
+
+	return {
+		summary,
+		firstKeptEntryId,
+		tokensBefore,
+		usage: summaryUsage,
+		details: { readFiles, modifiedFiles } as CompactionDetails,
+	};
+}
+
+/**
+ * Generate a summary for a turn prefix (when splitting a turn).
+ */
+async function generateTurnPrefixSummary(
+	messages: AgentMessage[],
+	model: Model<any>,
+	reserveTokens: number,
+	apiKey: string | undefined,
+	headers?: Record<string, string>,
+	env?: Record<string, string>,
+	signal?: AbortSignal,
+	thinkingLevel?: ThinkingLevel,
+	streamFn?: StreamFn,
+	retry?: RetryPolicy,
+	callbacks?: RetryCallbacks,
+	sessionId?: string,
+): Promise<{ text: string; usage: Usage }> {
+	const maxTokens = Math.min(
+		Math.floor(0.5 * reserveTokens),
+		model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY,
+	); // Smaller budget for turn prefix
+	const llmMessages = convertToLlm(messages);
+	const conversationText = serializeConversation(llmMessages);
+	const promptText = `<conversation>\n${conversationText}\n</conversation>\n\n${TURN_PREFIX_SUMMARIZATION_PROMPT}`;
+
+	const response = await completeSummarization(
+		model,
+		buildSummarizationContext(promptText),
+		createSummarizationOptions(model, maxTokens, apiKey, headers, env, signal, thinkingLevel, sessionId),
+		streamFn,
+		retry,
+		callbacks,
+	);
+
+	const failure = getSummarizationFailure(response, "Turn prefix summarization");
+	if (failure) {
+		throw new Error(failure);
+	}
+	if (response.content.some((block) => block.type === "toolCall")) {
+		throw new Error("Turn prefix summarization attempted to call a tool");
+	}
+
+	return {
+		text: contentText(response.content),
+		usage: response.usage,
+	};
+}

packages/coding-agent/src/core/compaction/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Compaction and summarization utilities.
+ */
+
+export * from "./branch-summarization.ts";
+export * from "./compaction.ts";
+export * from "./utils.ts";

packages/coding-agent/src/core/compaction/utils.ts

@@ -0,0 +1,158 @@
+/**
+ * Shared utilities for compaction and branch summarization.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { contentText, type Message } from "@earendil-works/pi-ai";
+
+// ============================================================================
+// File Operation Tracking
+// ============================================================================
+
+export interface FileOperations {
+	read: Set<string>;
+	written: Set<string>;
+	edited: Set<string>;
+}
+
+export function createFileOps(): FileOperations {
+	return {
+		read: new Set(),
+		written: new Set(),
+		edited: new Set(),
+	};
+}
+
+/**
+ * Extract file operations from tool calls in an assistant message.
+ */
+export function extractFileOpsFromMessage(message: AgentMessage, fileOps: FileOperations): void {
+	if (message.role !== "assistant") return;
+	if (!("content" in message) || !Array.isArray(message.content)) return;
+
+	for (const block of message.content) {
+		if (typeof block !== "object" || block === null) continue;
+		if (!("type" in block) || block.type !== "toolCall") continue;
+		if (!("arguments" in block) || !("name" in block)) continue;
+
+		const args = block.arguments as Record<string, unknown> | undefined;
+		if (!args) continue;
+
+		const path = typeof args.path === "string" ? args.path : undefined;
+		if (!path) continue;
+
+		switch (block.name) {
+			case "read":
+				fileOps.read.add(path);
+				break;
+			case "write":
+				fileOps.written.add(path);
+				break;
+			case "edit":
+				fileOps.edited.add(path);
+				break;
+		}
+	}
+}
+
+/**
+ * Compute final file lists from file operations.
+ * Returns readFiles (files only read, not modified) and modifiedFiles.
+ */
+export function computeFileLists(fileOps: FileOperations): { readFiles: string[]; modifiedFiles: string[] } {
+	const modified = new Set([...fileOps.edited, ...fileOps.written]);
+	const readOnly = [...fileOps.read].filter((f) => !modified.has(f)).sort();
+	const modifiedFiles = [...modified].sort();
+	return { readFiles: readOnly, modifiedFiles };
+}
+
+/**
+ * Format file operations as XML tags for summary.
+ */
+export function formatFileOperations(readFiles: string[], modifiedFiles: string[]): string {
+	const sections: string[] = [];
+	if (readFiles.length > 0) {
+		sections.push(`<read-files>\n${readFiles.join("\n")}\n</read-files>`);
+	}
+	if (modifiedFiles.length > 0) {
+		sections.push(`<modified-files>\n${modifiedFiles.join("\n")}\n</modified-files>`);
+	}
+	if (sections.length === 0) return "";
+	return `\n\n${sections.join("\n\n")}`;
+}
+
+// ============================================================================
+// Message Serialization
+// ============================================================================
+
+/** Maximum characters for a tool result in serialized summaries. */
+const TOOL_RESULT_MAX_CHARS = 2000;
+
+/**
+ * Truncate text to a maximum character length for summarization.
+ * Keeps the beginning and appends a truncation marker.
+ */
+function truncateForSummary(text: string, maxChars: number): string {
+	if (text.length <= maxChars) return text;
+	const truncatedChars = text.length - maxChars;
+	return `${text.slice(0, maxChars)}\n\n[... ${truncatedChars} more characters truncated]`;
+}
+
+/**
+ * Serialize LLM messages to text for summarization.
+ * This prevents the model from treating it as a conversation to continue.
+ * Call convertToLlm() first to handle custom message types.
+ *
+ * Tool results are truncated to keep the summarization request within
+ * reasonable token budgets. Full content is not needed for summarization.
+ */
+export function serializeConversation(messages: Message[]): string {
+	const parts: string[] = [];
+
+	for (const msg of messages) {
+		if (msg.role === "user") {
+			const content = contentText(msg.content, "");
+			if (content) parts.push(`[User]: ${content}`);
+		} else if (msg.role === "assistant") {
+			const thinkingParts: string[] = [];
+			const toolCalls: string[] = [];
+
+			for (const block of msg.content) {
+				if (block.type === "thinking") {
+					thinkingParts.push(block.thinking);
+				} else if (block.type === "toolCall") {
+					const args = block.arguments as Record<string, unknown>;
+					const argsStr = Object.entries(args)
+						.map(([k, v]) => `${k}=${JSON.stringify(v)}`)
+						.join(", ");
+					toolCalls.push(`${block.name}(${argsStr})`);
+				}
+			}
+
+			if (thinkingParts.length > 0) {
+				parts.push(`[Assistant thinking]: ${thinkingParts.join("\n")}`);
+			}
+			if (msg.content.some((block) => block.type === "text")) {
+				parts.push(`[Assistant]: ${contentText(msg.content)}`);
+			}
+			if (toolCalls.length > 0) {
+				parts.push(`[Assistant tool calls]: ${toolCalls.join("; ")}`);
+			}
+		} else if (msg.role === "toolResult") {
+			const content = contentText(msg.content, "");
+			if (content) {
+				parts.push(`[Tool result]: ${truncateForSummary(content, TOOL_RESULT_MAX_CHARS)}`);
+			}
+		}
+	}
+
+	return parts.join("\n\n");
+}
+
+// ============================================================================
+// Summarization System Prompt
+// ============================================================================
+
+export const SUMMARIZATION_SYSTEM_PROMPT = `You are a context summarization assistant. Your task is to read a conversation between a user and an AI assistant, then produce a structured summary following the exact format specified.
+
+Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.`;

packages/coding-agent/src/core/export-html/ansi-to-html.ts

@@ -0,0 +1,258 @@
+/**
+ * ANSI escape code to HTML converter.
+ *
+ * Converts terminal ANSI color/style codes to HTML with inline styles.
+ * Supports:
+ * - Standard foreground colors (30-37) and bright variants (90-97)
+ * - Standard background colors (40-47) and bright variants (100-107)
+ * - 256-color palette (38;5;N and 48;5;N)
+ * - RGB true color (38;2;R;G;B and 48;2;R;G;B)
+ * - Text styles: bold (1), dim (2), italic (3), underline (4)
+ * - Reset (0)
+ */
+
+// Standard ANSI color palette (0-15)
+const ANSI_COLORS = [
+	"#000000", // 0: black
+	"#800000", // 1: red
+	"#008000", // 2: green
+	"#808000", // 3: yellow
+	"#000080", // 4: blue
+	"#800080", // 5: magenta
+	"#008080", // 6: cyan
+	"#c0c0c0", // 7: white
+	"#808080", // 8: bright black
+	"#ff0000", // 9: bright red
+	"#00ff00", // 10: bright green
+	"#ffff00", // 11: bright yellow
+	"#0000ff", // 12: bright blue
+	"#ff00ff", // 13: bright magenta
+	"#00ffff", // 14: bright cyan
+	"#ffffff", // 15: bright white
+];
+
+/**
+ * Convert 256-color index to hex.
+ */
+function color256ToHex(index: number): string {
+	// Standard colors (0-15)
+	if (index < 16) {
+		return ANSI_COLORS[index];
+	}
+
+	// Color cube (16-231): 6x6x6 = 216 colors
+	if (index < 232) {
+		const cubeIndex = index - 16;
+		const r = Math.floor(cubeIndex / 36);
+		const g = Math.floor((cubeIndex % 36) / 6);
+		const b = cubeIndex % 6;
+		const toComponent = (n: number) => (n === 0 ? 0 : 55 + n * 40);
+		const toHex = (n: number) => toComponent(n).toString(16).padStart(2, "0");
+		return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+	}
+
+	// Grayscale (232-255): 24 shades
+	const gray = 8 + (index - 232) * 10;
+	const grayHex = gray.toString(16).padStart(2, "0");
+	return `#${grayHex}${grayHex}${grayHex}`;
+}
+
+/**
+ * Escape HTML special characters.
+ */
+function escapeHtml(text: string): string {
+	return text
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&#039;");
+}
+
+interface TextStyle {
+	fg: string | null;
+	bg: string | null;
+	bold: boolean;
+	dim: boolean;
+	italic: boolean;
+	underline: boolean;
+}
+
+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;
+}
+
+/**
+ * Parse ANSI SGR (Select Graphic Rendition) codes and update style.
+ */
+function applySgrCode(params: number[], style: TextStyle): void {
+	let i = 0;
+	while (i < params.length) {
+		const code = params[i];
+
+		if (code === 0) {
+			// Reset all
+			style.fg = null;
+			style.bg = null;
+			style.bold = false;
+			style.dim = false;
+			style.italic = false;
+			style.underline = false;
+		} 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) {
+			// Reset bold/dim
+			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) {
+			// Standard foreground colors
+			style.fg = ANSI_COLORS[code - 30];
+		} else if (code === 38) {
+			// Extended foreground color
+			if (params[i + 1] === 5 && params.length > i + 2) {
+				// 256-color: 38;5;N
+				style.fg = color256ToHex(params[i + 2]);
+				i += 2;
+			} else if (params[i + 1] === 2 && params.length > i + 4) {
+				// RGB: 38;2;R;G;B
+				const r = params[i + 2];
+				const g = params[i + 3];
+				const b = params[i + 4];
+				style.fg = `rgb(${r},${g},${b})`;
+				i += 4;
+			}
+		} else if (code === 39) {
+			// Default foreground
+			style.fg = null;
+		} else if (code >= 40 && code <= 47) {
+			// Standard background colors
+			style.bg = ANSI_COLORS[code - 40];
+		} else if (code === 48) {
+			// Extended background color
+			if (params[i + 1] === 5 && params.length > i + 2) {
+				// 256-color: 48;5;N
+				style.bg = color256ToHex(params[i + 2]);
+				i += 2;
+			} else if (params[i + 1] === 2 && params.length > i + 4) {
+				// RGB: 48;2;R;G;B
+				const r = params[i + 2];
+				const g = params[i + 3];
+				const b = params[i + 4];
+				style.bg = `rgb(${r},${g},${b})`;
+				i += 4;
+			}
+		} else if (code === 49) {
+			// Default background
+			style.bg = null;
+		} else if (code >= 90 && code <= 97) {
+			// Bright foreground colors
+			style.fg = ANSI_COLORS[code - 90 + 8];
+		} else if (code >= 100 && code <= 107) {
+			// Bright background colors
+			style.bg = ANSI_COLORS[code - 100 + 8];
+		}
+		// Ignore unrecognized codes
+
+		i++;
+	}
+}
+
+// Match ANSI escape sequences: ESC[ followed by params and ending with 'm'
+const ANSI_REGEX = /\x1b\[([\d;]*)m/g;
+
+/**
+ * Convert ANSI-escaped text to HTML with inline styles.
+ */
+export function ansiToHtml(text: string): string {
+	const style = createEmptyStyle();
+	let result = "";
+	let lastIndex = 0;
+	let inSpan = false;
+
+	// Reset regex state
+	ANSI_REGEX.lastIndex = 0;
+
+	let match = ANSI_REGEX.exec(text);
+	while (match !== null) {
+		// Add text before this escape sequence
+		const beforeText = text.slice(lastIndex, match.index);
+		if (beforeText) {
+			result += escapeHtml(beforeText);
+		}
+
+		// Parse SGR parameters
+		const paramStr = match[1];
+		const params = paramStr ? paramStr.split(";").map((p) => parseInt(p, 10) || 0) : [0];
+
+		// Close existing span if we have one
+		if (inSpan) {
+			result += "</span>";
+			inSpan = false;
+		}
+
+		// Apply the codes
+		applySgrCode(params, style);
+
+		// Open new span if we have any styling
+		if (hasStyle(style)) {
+			result += `<span style="${styleToInlineCSS(style)}">`;
+			inSpan = true;
+		}
+
+		lastIndex = match.index + match[0].length;
+		match = ANSI_REGEX.exec(text);
+	}
+
+	// Add remaining text
+	const remainingText = text.slice(lastIndex);
+	if (remainingText) {
+		result += escapeHtml(remainingText);
+	}
+
+	// Close any open span
+	if (inSpan) {
+		result += "</span>";
+	}
+
+	return result;
+}
+
+/**
+ * Convert array of ANSI-escaped lines to HTML.
+ * Each line is wrapped in a div element.
+ */
+export function ansiLinesToHtml(lines: string[]): string {
+	return lines.map((line) => `<div class="ansi-line">${ansiToHtml(line) || "&nbsp;"}</div>`).join("");
+}

packages/coding-agent/src/core/export-html/index.ts

@@ -0,0 +1,316 @@
+import type { AgentState } from "@earendil-works/pi-agent-core";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { basename, join } from "path";
+import { APP_NAME, getExportTemplateDir } from "../../config.ts";
+import { getResolvedThemeColors, getThemeExportColors } from "../../modes/interactive/theme/theme.ts";
+import { normalizePath, resolvePath } from "../../utils/paths.ts";
+import type { ToolDefinition } from "../extensions/types.ts";
+import type { SessionEntry } from "../session-manager.ts";
+import { SessionManager } from "../session-manager.ts";
+
+/**
+ * Interface for rendering custom tools to HTML.
+ * Used by agent-session to pre-render extension tool output.
+ */
+export interface ToolHtmlRenderer {
+	/** Render a tool call to HTML. Returns undefined if tool has no custom renderer. */
+	renderCall(toolCallId: string, toolName: string, args: unknown): string | undefined;
+	/** Render a tool result to HTML. Returns collapsed/expanded or undefined if tool has no custom renderer. */
+	renderResult(
+		toolCallId: string,
+		toolName: string,
+		result: Array<{ type: string; text?: string; data?: string; mimeType?: string }>,
+		details: unknown,
+		isError: boolean,
+	): { collapsed?: string; expanded?: string } | undefined;
+}
+
+/** Pre-rendered HTML for a custom tool call and result */
+interface RenderedToolHtml {
+	callHtml?: string;
+	resultHtmlCollapsed?: string;
+	resultHtmlExpanded?: string;
+}
+
+export interface ExportOptions {
+	outputPath?: string;
+	themeName?: string;
+	/** Optional tool renderer for custom tools */
+	toolRenderer?: ToolHtmlRenderer;
+}
+
+/** Parse a color string to RGB values. Supports hex (#RRGGBB) and rgb(r,g,b) formats. */
+function parseColor(color: string): { r: number; g: number; b: number } | undefined {
+	const hexMatch = color.match(/^#([0-9a-fA-F]{2})([0-9a-fA-F]{2})([0-9a-fA-F]{2})$/);
+	if (hexMatch) {
+		return {
+			r: Number.parseInt(hexMatch[1], 16),
+			g: Number.parseInt(hexMatch[2], 16),
+			b: Number.parseInt(hexMatch[3], 16),
+		};
+	}
+	const rgbMatch = color.match(/^rgb\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$/);
+	if (rgbMatch) {
+		return {
+			r: Number.parseInt(rgbMatch[1], 10),
+			g: Number.parseInt(rgbMatch[2], 10),
+			b: Number.parseInt(rgbMatch[3], 10),
+		};
+	}
+	return undefined;
+}
+
+/** Calculate relative luminance of a color (0-1, higher = lighter). */
+function getLuminance(r: number, g: number, b: number): number {
+	const toLinear = (c: number) => {
+		const s = c / 255;
+		return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+	};
+	return 0.2126 * toLinear(r) + 0.7152 * toLinear(g) + 0.0722 * toLinear(b);
+}
+
+/** Adjust color brightness. Factor > 1 lightens, < 1 darkens. */
+function adjustBrightness(color: string, factor: number): string {
+	const parsed = parseColor(color);
+	if (!parsed) return color;
+	const adjust = (c: number) => Math.min(255, Math.max(0, Math.round(c * factor)));
+	return `rgb(${adjust(parsed.r)}, ${adjust(parsed.g)}, ${adjust(parsed.b)})`;
+}
+
+/** Derive export background colors from a base color (e.g., userMessageBg). */
+function deriveExportColors(baseColor: string): { pageBg: string; cardBg: string; infoBg: string } {
+	const parsed = parseColor(baseColor);
+	if (!parsed) {
+		return {
+			pageBg: "rgb(24, 24, 30)",
+			cardBg: "rgb(30, 30, 36)",
+			infoBg: "rgb(60, 55, 40)",
+		};
+	}
+
+	const luminance = getLuminance(parsed.r, parsed.g, parsed.b);
+	const isLight = luminance > 0.5;
+
+	if (isLight) {
+		return {
+			pageBg: adjustBrightness(baseColor, 0.96),
+			cardBg: baseColor,
+			infoBg: `rgb(${Math.min(255, parsed.r + 10)}, ${Math.min(255, parsed.g + 5)}, ${Math.max(0, parsed.b - 20)})`,
+		};
+	}
+	return {
+		pageBg: adjustBrightness(baseColor, 0.7),
+		cardBg: adjustBrightness(baseColor, 0.85),
+		infoBg: `rgb(${Math.min(255, parsed.r + 20)}, ${Math.min(255, parsed.g + 15)}, ${parsed.b})`,
+	};
+}
+
+/**
+ * Generate CSS custom property declarations from theme colors.
+ */
+function generateThemeVars(themeName?: string): string {
+	const colors = getResolvedThemeColors(themeName);
+	const lines: string[] = [];
+	for (const [key, value] of Object.entries(colors)) {
+		lines.push(`--${key}: ${value};`);
+	}
+
+	// Use explicit theme export colors if available, otherwise derive from userMessageBg
+	const themeExport = getThemeExportColors(themeName);
+	const userMessageBg = colors.userMessageBg || "#343541";
+	const derivedColors = deriveExportColors(userMessageBg);
+
+	lines.push(`--exportPageBg: ${themeExport.pageBg ?? derivedColors.pageBg};`);
+	lines.push(`--exportCardBg: ${themeExport.cardBg ?? derivedColors.cardBg};`);
+	lines.push(`--exportInfoBg: ${themeExport.infoBg ?? derivedColors.infoBg};`);
+
+	return lines.join("\n      ");
+}
+
+interface SessionData {
+	header: ReturnType<SessionManager["getHeader"]>;
+	entries: ReturnType<SessionManager["getEntries"]>;
+	leafId: string | null;
+	systemPrompt?: string;
+	tools?: Array<Pick<ToolDefinition, "name" | "description" | "parameters">>;
+	/** Pre-rendered HTML for custom tool calls/results, keyed by tool call ID */
+	renderedTools?: Record<string, RenderedToolHtml>;
+}
+
+/**
+ * Core HTML generation logic shared by both export functions.
+ */
+function generateHtml(sessionData: SessionData, themeName?: string): string {
+	const templateDir = getExportTemplateDir();
+	const template = readFileSync(join(templateDir, "template.html"), "utf-8");
+	const templateCss = readFileSync(join(templateDir, "template.css"), "utf-8");
+	const templateJs = readFileSync(join(templateDir, "template.js"), "utf-8");
+	const markedJs = readFileSync(join(templateDir, "vendor", "marked.min.js"), "utf-8");
+	const hljsJs = readFileSync(join(templateDir, "vendor", "highlight.min.js"), "utf-8");
+
+	const themeVars = generateThemeVars(themeName);
+	const colors = getResolvedThemeColors(themeName);
+	const themeExport = getThemeExportColors(themeName);
+	const derivedExportColors = deriveExportColors(colors.userMessageBg || "#343541");
+	const bodyBg = themeExport.pageBg ?? derivedExportColors.pageBg;
+	const containerBg = themeExport.cardBg ?? derivedExportColors.cardBg;
+	const infoBg = themeExport.infoBg ?? derivedExportColors.infoBg;
+
+	// Base64 encode session data to avoid escaping issues
+	const sessionDataBase64 = Buffer.from(JSON.stringify(sessionData)).toString("base64");
+
+	// Build the CSS with theme variables injected
+	const css = templateCss
+		.replace("{{THEME_VARS}}", themeVars)
+		.replace("{{BODY_BG}}", bodyBg)
+		.replace("{{CONTAINER_BG}}", containerBg)
+		.replace("{{INFO_BG}}", infoBg);
+
+	return template
+		.replace("{{CSS}}", css)
+		.replace("{{JS}}", templateJs)
+		.replace("{{SESSION_DATA}}", sessionDataBase64)
+		.replace("{{MARKED_JS}}", markedJs)
+		.replace("{{HIGHLIGHT_JS}}", hljsJs);
+}
+
+/** Tools rendered directly by the HTML template (not pre-rendered via TUI→ANSI→HTML pipeline) */
+const TEMPLATE_RENDERED_TOOLS = new Set(["bash", "read", "write", "edit", "ls"]);
+
+/**
+ * Pre-render custom tools to HTML using their TUI renderers.
+ */
+function preRenderCustomTools(
+	entries: SessionEntry[],
+	toolRenderer: ToolHtmlRenderer,
+): Record<string, RenderedToolHtml> {
+	const renderedTools: Record<string, RenderedToolHtml> = {};
+
+	for (const entry of entries) {
+		if (entry.type !== "message") continue;
+		const msg = entry.message;
+
+		// Find tool calls in assistant messages
+		if (msg.role === "assistant" && Array.isArray(msg.content)) {
+			for (const block of msg.content) {
+				if (block.type === "toolCall" && !TEMPLATE_RENDERED_TOOLS.has(block.name)) {
+					const callHtml = toolRenderer.renderCall(block.id, block.name, block.arguments);
+					if (callHtml) {
+						renderedTools[block.id] = { callHtml };
+					}
+				}
+			}
+		}
+
+		// Find tool results
+		if (msg.role === "toolResult" && msg.toolCallId) {
+			const toolName = msg.toolName || "";
+			// Only render if we have a pre-rendered call OR it's not template-rendered
+			const existing = renderedTools[msg.toolCallId];
+			if (existing || !TEMPLATE_RENDERED_TOOLS.has(toolName)) {
+				const rendered = toolRenderer.renderResult(
+					msg.toolCallId,
+					toolName,
+					msg.content,
+					msg.details,
+					msg.isError || false,
+				);
+				if (rendered) {
+					renderedTools[msg.toolCallId] = {
+						...existing,
+						resultHtmlCollapsed: rendered.collapsed,
+						resultHtmlExpanded: rendered.expanded,
+					};
+				}
+			}
+		}
+	}
+
+	return renderedTools;
+}
+
+/**
+ * Export session to HTML using SessionManager and AgentState.
+ * Used by TUI's /export command.
+ */
+export async function exportSessionToHtml(
+	sm: SessionManager,
+	state?: AgentState,
+	options?: ExportOptions | string,
+): Promise<string> {
+	const opts: ExportOptions = typeof options === "string" ? { outputPath: options } : options || {};
+
+	const sessionFile = sm.getSessionFile();
+	if (!sessionFile) {
+		throw new Error("Cannot export in-memory session to HTML");
+	}
+	if (!existsSync(sessionFile)) {
+		throw new Error("Nothing to export yet - start a conversation first");
+	}
+
+	const entries = sm.getEntries();
+
+	// Pre-render custom tools if a tool renderer is provided
+	let renderedTools: Record<string, RenderedToolHtml> | undefined;
+	if (opts.toolRenderer) {
+		renderedTools = preRenderCustomTools(entries, opts.toolRenderer);
+		// Only include if we actually rendered something
+		if (Object.keys(renderedTools).length === 0) {
+			renderedTools = undefined;
+		}
+	}
+
+	const sessionData: SessionData = {
+		header: sm.getHeader(),
+		entries,
+		leafId: sm.getLeafId(),
+		systemPrompt: state?.systemPrompt,
+		tools: state?.tools?.map((t) => ({ name: t.name, description: t.description, parameters: t.parameters })),
+		renderedTools,
+	};
+
+	const html = generateHtml(sessionData, opts.themeName);
+
+	let outputPath = opts.outputPath ? normalizePath(opts.outputPath) : undefined;
+	if (!outputPath) {
+		const sessionBasename = basename(sessionFile, ".jsonl");
+		outputPath = `${APP_NAME}-session-${sessionBasename}.html`;
+	}
+
+	writeFileSync(outputPath, html, "utf8");
+	return outputPath;
+}
+
+/**
+ * Export session file to HTML (standalone, without AgentState).
+ * Used by CLI for exporting arbitrary session files.
+ */
+export async function exportFromFile(inputPath: string, options?: ExportOptions | string): Promise<string> {
+	const opts: ExportOptions = typeof options === "string" ? { outputPath: options } : options || {};
+	const resolvedInputPath = resolvePath(inputPath);
+
+	if (!existsSync(resolvedInputPath)) {
+		throw new Error(`File not found: ${resolvedInputPath}`);
+	}
+
+	const sm = SessionManager.open(resolvedInputPath);
+
+	const sessionData: SessionData = {
+		header: sm.getHeader(),
+		entries: sm.getEntries(),
+		leafId: sm.getLeafId(),
+		systemPrompt: undefined,
+		tools: undefined,
+	};
+
+	const html = generateHtml(sessionData, opts.themeName);
+
+	let outputPath = opts.outputPath ? normalizePath(opts.outputPath) : undefined;
+	if (!outputPath) {
+		const inputBasename = basename(resolvedInputPath, ".jsonl");
+		outputPath = `${APP_NAME}-session-${inputBasename}.html`;
+	}
+
+	writeFileSync(outputPath, html, "utf8");
+	return outputPath;
+}

packages/coding-agent/src/core/export-html/template.css

@@ -0,0 +1,1066 @@
+    :root {
+      {{THEME_VARS}}
+      --body-bg: {{BODY_BG}};
+      --container-bg: {{CONTAINER_BG}};
+      --info-bg: {{INFO_BG}};
+    }
+
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+
+    :root {
+      --line-height: 18px; /* 12px font * 1.5 */
+      --sidebar-width: 400px;
+      --sidebar-min-width: 240px;
+      --sidebar-max-width: 840px;
+      --sidebar-resizer-width: 6px;
+    }
+
+    body {
+      font-family: ui-monospace, 'Cascadia Code', 'Source Code Pro', Menlo, Consolas, 'DejaVu Sans Mono', monospace;
+      font-size: 12px;
+      line-height: var(--line-height);
+      color: var(--text);
+      background: var(--body-bg);
+    }
+
+    body.sidebar-resizing {
+      cursor: col-resize;
+      user-select: none;
+    }
+
+    #app {
+      display: flex;
+      min-height: 100vh;
+    }
+
+    /* Sidebar */
+    #sidebar {
+      width: var(--sidebar-width);
+      min-width: var(--sidebar-width);
+      max-width: var(--sidebar-width);
+      background: var(--container-bg);
+      flex-shrink: 0;
+      display: flex;
+      flex-direction: column;
+      position: sticky;
+      top: 0;
+      height: 100vh;
+      border-right: 1px solid var(--dim);
+    }
+
+    #sidebar-resizer {
+      width: var(--sidebar-resizer-width);
+      flex-shrink: 0;
+      position: sticky;
+      top: 0;
+      height: 100vh;
+      cursor: col-resize;
+      touch-action: none;
+      background: transparent;
+      border-right: 1px solid transparent;
+    }
+
+    #sidebar-resizer:hover,
+    body.sidebar-resizing #sidebar-resizer {
+      background: var(--selectedBg);
+      border-right-color: var(--dim);
+    }
+
+    .sidebar-header {
+      padding: 8px 12px;
+      flex-shrink: 0;
+    }
+
+    .sidebar-controls {
+      padding: 8px 8px 4px 8px;
+    }
+
+    .sidebar-search {
+      width: 100%;
+      box-sizing: border-box;
+      padding: 4px 8px;
+      font-size: 11px;
+      font-family: inherit;
+      background: var(--body-bg);
+      color: var(--text);
+      border: 1px solid var(--dim);
+      border-radius: 3px;
+    }
+
+    .sidebar-filters {
+      display: flex;
+      padding: 4px 8px 8px 8px;
+      gap: 4px;
+      align-items: center;
+      flex-wrap: wrap;
+    }
+
+    .sidebar-search:focus {
+      outline: none;
+      border-color: var(--accent);
+    }
+
+    .sidebar-search::placeholder {
+      color: var(--muted);
+    }
+
+    .filter-btn {
+      padding: 3px 8px;
+      font-size: 10px;
+      font-family: inherit;
+      background: transparent;
+      color: var(--muted);
+      border: 1px solid var(--dim);
+      border-radius: 3px;
+      cursor: pointer;
+    }
+
+    .filter-btn:hover {
+      color: var(--text);
+      border-color: var(--text);
+    }
+
+    .filter-btn.active {
+      background: var(--accent);
+      color: var(--body-bg);
+      border-color: var(--accent);
+    }
+
+    .sidebar-close {
+      display: none;
+      padding: 3px 8px;
+      font-size: 12px;
+      font-family: inherit;
+      background: transparent;
+      color: var(--muted);
+      border: 1px solid var(--dim);
+      border-radius: 3px;
+      cursor: pointer;
+      margin-left: auto;
+    }
+
+    .sidebar-close:hover {
+      color: var(--text);
+      border-color: var(--text);
+    }
+
+    .tree-container {
+      flex: 1;
+      overflow: auto;
+      padding: 4px 0;
+    }
+
+    .tree-node {
+      padding: 0 8px;
+      cursor: pointer;
+      display: flex;
+      align-items: baseline;
+      font-size: 11px;
+      line-height: 13px;
+      white-space: nowrap;
+    }
+
+    .tree-node:hover {
+      background: var(--selectedBg);
+    }
+
+    .tree-node.active {
+      background: var(--selectedBg);
+    }
+
+    .tree-node.active .tree-content {
+      font-weight: bold;
+    }
+
+    .tree-node.in-path {
+      background: color-mix(in srgb, var(--accent) 10%, transparent);
+    }
+
+    .tree-node:not(.in-path) {
+      opacity: 0.5;
+    }
+
+    .tree-node:not(.in-path):hover {
+      opacity: 1;
+    }
+
+    .tree-prefix {
+      color: var(--muted);
+      flex-shrink: 0;
+      font-family: monospace;
+      white-space: pre;
+    }
+
+    .tree-marker {
+      color: var(--accent);
+      flex-shrink: 0;
+    }
+
+    .tree-content {
+      color: var(--text);
+    }
+
+    .tree-role-user {
+      color: var(--accent);
+    }
+
+    .tree-role-skill {
+      color: var(--customMessageLabel);
+    }
+
+    .tree-role-assistant {
+      color: var(--success);
+    }
+
+    .tree-role-tool {
+      color: var(--muted);
+    }
+
+    .tree-muted {
+      color: var(--muted);
+    }
+
+    .tree-error {
+      color: var(--error);
+    }
+
+    .tree-compaction {
+      color: var(--borderAccent);
+    }
+
+    .tree-branch-summary {
+      color: var(--warning);
+    }
+
+    .tree-custom-message {
+      color: var(--customMessageLabel);
+    }
+
+    .tree-status {
+      padding: 4px 12px;
+      font-size: 10px;
+      color: var(--muted);
+      flex-shrink: 0;
+    }
+
+    /* Main content */
+    #content {
+      flex: 1;
+      min-width: 0;
+      overflow-y: auto;
+      padding: var(--line-height) calc(var(--line-height) * 2);
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+    }
+
+    #content > * {
+      width: 100%;
+      max-width: 800px;
+    }
+
+    /* Help bar */
+    .help-bar {
+      font-size: 11px;
+      color: var(--warning);
+      margin-bottom: var(--line-height);
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      flex-wrap: wrap;
+      gap: 12px;
+    }
+
+    .help-hint {
+      flex: 1 1 240px;
+    }
+
+    .help-actions {
+      display: flex;
+      align-items: center;
+      flex-wrap: wrap;
+      gap: 8px;
+    }
+
+    .header-toggle-btn,
+    .download-json-btn {
+      font-size: 10px;
+      padding: 2px 8px;
+      background: var(--container-bg);
+      border: 1px solid var(--border);
+      border-radius: 3px;
+      color: var(--text);
+      cursor: pointer;
+      font-family: inherit;
+    }
+
+    .header-toggle-btn:hover,
+    .download-json-btn:hover {
+      background: var(--hover);
+      border-color: var(--borderAccent);
+    }
+
+    /* Header */
+    .header {
+      background: var(--container-bg);
+      border-radius: 4px;
+      padding: var(--line-height);
+      margin-bottom: var(--line-height);
+    }
+
+    .header h1 {
+      font-size: 12px;
+      font-weight: bold;
+      color: var(--borderAccent);
+      margin-bottom: var(--line-height);
+    }
+
+    .header-info {
+      display: flex;
+      flex-direction: column;
+      gap: 0;
+      font-size: 11px;
+    }
+
+    .info-item {
+      color: var(--dim);
+      display: flex;
+      align-items: baseline;
+    }
+
+    .info-label {
+      font-weight: 600;
+      margin-right: 8px;
+      min-width: 100px;
+    }
+
+    .info-value {
+      color: var(--text);
+      flex: 1;
+    }
+
+    /* Messages */
+    #messages {
+      display: flex;
+      flex-direction: column;
+      gap: var(--line-height);
+    }
+
+    .message-timestamp {
+      font-size: 10px;
+      color: var(--dim);
+      opacity: 0.8;
+    }
+
+    .user-message {
+      background: var(--userMessageBg);
+      color: var(--userMessageText);
+      padding: var(--line-height);
+      border-radius: 4px;
+      position: relative;
+    }
+
+    .assistant-message {
+      padding: 0;
+      position: relative;
+    }
+
+    /* Copy link button - appears on hover */
+    .copy-link-btn {
+      position: absolute;
+      top: 8px;
+      right: 8px;
+      width: 28px;
+      height: 28px;
+      padding: 6px;
+      background: var(--container-bg);
+      border: 1px solid var(--dim);
+      border-radius: 4px;
+      color: var(--muted);
+      cursor: pointer;
+      opacity: 0;
+      transition: opacity 0.15s, background 0.15s, color 0.15s;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      z-index: 10;
+    }
+
+    .user-message:hover .copy-link-btn,
+    .assistant-message:hover .copy-link-btn,
+    .skill-user-entry:hover .copy-link-btn {
+      opacity: 1;
+    }
+
+    .copy-link-btn:hover {
+      background: var(--accent);
+      color: var(--body-bg);
+      border-color: var(--accent);
+    }
+
+    .copy-link-btn.copied {
+      background: var(--success, #22c55e);
+      color: white;
+      border-color: var(--success, #22c55e);
+    }
+
+    /* Highlight effect for deep-linked messages */
+    .user-message.highlight,
+    .assistant-message.highlight {
+      animation: highlight-pulse 2s ease-out;
+    }
+
+    @keyframes highlight-pulse {
+      0% {
+        box-shadow: 0 0 0 3px var(--accent);
+      }
+      100% {
+        box-shadow: 0 0 0 0 transparent;
+      }
+    }
+
+    .assistant-message > .message-timestamp {
+      padding-left: var(--line-height);
+    }
+
+    .assistant-text {
+      padding: var(--line-height);
+      padding-bottom: 0;
+    }
+
+    .message-timestamp + .assistant-text,
+    .message-timestamp + .thinking-block {
+      padding-top: 0;
+    }
+
+    .thinking-block + .assistant-text {
+      padding-top: 0;
+    }
+
+    .thinking-text {
+      padding: var(--line-height);
+      color: var(--thinkingText);
+      font-style: italic;
+      white-space: pre-wrap;
+    }
+
+    .message-timestamp + .thinking-block .thinking-text,
+    .message-timestamp + .thinking-block .thinking-collapsed {
+      padding-top: 0;
+    }
+
+    .thinking-collapsed {
+      display: none;
+      padding: var(--line-height);
+      color: var(--thinkingText);
+      font-style: italic;
+    }
+
+    /* Tool execution */
+    .tool-execution {
+      padding: var(--line-height);
+      border-radius: 4px;
+    }
+
+    .tool-execution + .tool-execution {
+      margin-top: var(--line-height);
+    }
+
+    .assistant-text + .tool-execution {
+      margin-top: var(--line-height);
+    }
+
+    .tool-execution.pending { background: var(--toolPendingBg); }
+    .tool-execution.success { background: var(--toolSuccessBg); }
+    .tool-execution.error { background: var(--toolErrorBg); }
+
+    .tool-header, .tool-name {
+      font-weight: bold;
+    }
+
+    .tool-path {
+      color: var(--accent);
+      word-break: break-all;
+    }
+
+    .line-numbers {
+      color: var(--warning);
+    }
+
+    .line-count {
+      color: var(--dim);
+    }
+
+    .tool-command {
+      font-weight: bold;
+      white-space: pre-wrap;
+      word-wrap: break-word;
+      overflow-wrap: break-word;
+      word-break: break-word;
+    }
+
+    .tool-output {
+      margin-top: var(--line-height);
+      color: var(--toolOutput);
+      word-wrap: break-word;
+      overflow-wrap: break-word;
+      word-break: break-word;
+      font-family: inherit;
+      overflow-x: auto;
+    }
+
+    .tool-output > div,
+    .output-preview > div,
+    .output-full > div {
+      margin: 0;
+      padding: 0;
+      line-height: var(--line-height);
+    }
+
+    .tool-output > div:not(.output-preview):not(.output-full),
+    .output-preview > div:not(.expand-hint),
+    .output-full > div:not(.expand-hint) {
+      white-space: pre-wrap;
+    }
+
+    .tool-output pre {
+      margin: 0;
+      padding: 0;
+      font-family: inherit;
+      color: inherit;
+      white-space: pre-wrap;
+      word-wrap: break-word;
+      overflow-wrap: break-word;
+    }
+
+    .tool-output code {
+      padding: 0;
+      background: none;
+      color: var(--text);
+    }
+
+    .tool-output.expandable {
+      cursor: pointer;
+    }
+
+    .tool-output.expandable:hover {
+      opacity: 0.9;
+    }
+
+    .tool-output.expandable .output-full {
+      display: none;
+    }
+
+    .tool-output.expandable.expanded .output-preview {
+      display: none;
+    }
+
+    .tool-output.expandable.expanded .output-full {
+      display: block;
+    }
+
+    .ansi-line {
+      white-space: pre;
+    }
+
+    .tool-images {
+    }
+
+    .tool-image {
+      max-width: 100%;
+      max-height: 500px;
+      border-radius: 4px;
+      margin: var(--line-height) 0;
+    }
+
+    .expand-hint {
+      color: var(--toolOutput);
+    }
+
+    /* Diff */
+    .tool-diff {
+      font-size: 11px;
+      overflow-x: auto;
+      white-space: pre;
+    }
+
+    .diff-added { color: var(--toolDiffAdded); }
+    .diff-removed { color: var(--toolDiffRemoved); }
+    .diff-context { color: var(--toolDiffContext); }
+
+    /* Model change */
+    .model-change {
+      padding: 0 var(--line-height);
+      color: var(--dim);
+      font-size: 11px;
+    }
+
+    .model-name {
+      color: var(--borderAccent);
+      font-weight: bold;
+    }
+
+    /* Compaction / Branch Summary - matches customMessage colors from TUI */
+    .compaction {
+      background: var(--customMessageBg);
+      border-radius: 4px;
+      padding: var(--line-height);
+      cursor: pointer;
+    }
+
+    .compaction-label {
+      color: var(--customMessageLabel);
+      font-weight: bold;
+    }
+
+    .compaction-collapsed {
+      color: var(--customMessageText);
+    }
+
+    .compaction-content {
+      display: none;
+      color: var(--customMessageText);
+      white-space: pre-wrap;
+      margin-top: var(--line-height);
+    }
+
+    .compaction.expanded .compaction-collapsed {
+      display: none;
+    }
+
+    .compaction.expanded .compaction-content {
+      display: block;
+    }
+
+    /* System prompt */
+    .system-prompt {
+      background: var(--customMessageBg);
+      padding: var(--line-height);
+      border-radius: 4px;
+      margin-bottom: var(--line-height);
+    }
+
+    .system-prompt.expandable {
+      cursor: pointer;
+    }
+
+    .system-prompt-header {
+      font-weight: bold;
+      color: var(--customMessageLabel);
+    }
+
+    .system-prompt-preview {
+      color: var(--customMessageText);
+      white-space: pre-wrap;
+      word-wrap: break-word;
+      font-size: 11px;
+      margin-top: var(--line-height);
+    }
+
+    .system-prompt-expand-hint {
+      color: var(--muted);
+      font-style: italic;
+      margin-top: 4px;
+    }
+
+    .system-prompt-full {
+      display: none;
+      color: var(--customMessageText);
+      white-space: pre-wrap;
+      word-wrap: break-word;
+      font-size: 11px;
+      margin-top: var(--line-height);
+    }
+
+    .system-prompt.expanded .system-prompt-preview,
+    .system-prompt.expanded .system-prompt-expand-hint {
+      display: none;
+    }
+
+    .system-prompt.expanded .system-prompt-full {
+      display: block;
+    }
+
+    .system-prompt.provider-prompt {
+      border-left: 3px solid var(--warning);
+    }
+
+    .system-prompt-note {
+      font-size: 10px;
+      font-style: italic;
+      color: var(--muted);
+      margin-top: 4px;
+    }
+
+    /* Tools list */
+    .tools-list {
+      background: var(--customMessageBg);
+      padding: var(--line-height);
+      border-radius: 4px;
+      margin-bottom: var(--line-height);
+    }
+
+    .tools-header {
+      font-weight: bold;
+      color: var(--customMessageLabel);
+      margin-bottom: var(--line-height);
+    }
+
+    .tool-item {
+      font-size: 11px;
+    }
+
+    .tool-item-name {
+      font-weight: bold;
+      color: var(--text);
+    }
+
+    .tool-item-desc {
+      color: var(--dim);
+    }
+
+    .tool-params-hint {
+      color: var(--muted);
+      font-style: italic;
+    }
+
+    .tool-item:has(.tool-params-hint) {
+      cursor: pointer;
+    }
+
+    .tool-params-hint::after {
+      content: '[click to show parameters]';
+    }
+
+    .tool-item.params-expanded .tool-params-hint::after {
+      content: '[hide parameters]';
+    }
+
+    .tool-params-content {
+      display: none;
+      margin-top: 4px;
+      margin-left: 12px;
+      padding-left: 8px;
+      border-left: 1px solid var(--dim);
+    }
+
+    .tool-item.params-expanded .tool-params-content {
+      display: block;
+    }
+
+    .tool-param {
+      margin-bottom: 4px;
+      font-size: 11px;
+    }
+
+    .tool-param-name {
+      font-weight: bold;
+      color: var(--text);
+    }
+
+    .tool-param-type {
+      color: var(--dim);
+      font-style: italic;
+    }
+
+    .tool-param-required {
+      color: var(--warning, #e8a838);
+      font-size: 10px;
+    }
+
+    .tool-param-optional {
+      color: var(--dim);
+      font-size: 10px;
+    }
+
+    .tool-param-desc {
+      color: var(--dim);
+      margin-left: 8px;
+    }
+
+    /* Hook/custom messages */
+    .hook-message {
+      background: var(--customMessageBg);
+      color: var(--customMessageText);
+      padding: var(--line-height);
+      border-radius: 4px;
+    }
+
+    .hook-type {
+      color: var(--customMessageLabel);
+      font-weight: bold;
+    }
+
+    /* Skill invocation - matches compaction style (clickable, collapsed by default) */
+    .skill-invocation {
+      background: var(--customMessageBg);
+      border-radius: 4px;
+      padding: var(--line-height);
+      cursor: pointer;
+    }
+
+    .skill-invocation-label {
+      color: var(--customMessageLabel);
+      font-weight: bold;
+    }
+
+    .skill-invocation-collapsed {
+      color: var(--customMessageText);
+    }
+
+    .skill-invocation-content {
+      display: none;
+      color: var(--customMessageText);
+      margin-top: var(--line-height);
+    }
+
+    .skill-invocation.expanded .skill-invocation-collapsed {
+      display: none;
+    }
+
+    .skill-invocation.expanded .skill-invocation-content {
+      display: block;
+    }
+
+    .skill-invocation + .user-message {
+      margin-top: var(--line-height);
+    }
+
+    .skill-user-entry {
+      position: relative;
+    }
+
+    /* Branch summary */
+    .branch-summary {
+      background: var(--customMessageBg);
+      padding: var(--line-height);
+      border-radius: 4px;
+    }
+
+    .branch-summary-header {
+      font-weight: bold;
+      color: var(--borderAccent);
+    }
+
+    /* Error */
+    .error-text {
+      color: var(--error);
+      padding: 0 var(--line-height);
+    }
+    .tool-error {
+      color: var(--error);
+    }
+
+    /* Images */
+    .message-images {
+      margin-bottom: 12px;
+    }
+
+    .message-image {
+      max-width: 100%;
+      max-height: 400px;
+      border-radius: 4px;
+      margin: var(--line-height) 0;
+    }
+
+    /* Markdown content */
+    .markdown-content h1,
+    .markdown-content h2,
+    .markdown-content h3,
+    .markdown-content h4,
+    .markdown-content h5,
+    .markdown-content h6 {
+      color: var(--mdHeading);
+      margin: var(--line-height) 0 0 0;
+      font-weight: bold;
+    }
+
+    .markdown-content h1 { font-size: 1em; }
+    .markdown-content h2 { font-size: 1em; }
+    .markdown-content h3 { font-size: 1em; }
+    .markdown-content h4 { font-size: 1em; }
+    .markdown-content h5 { font-size: 1em; }
+    .markdown-content h6 { font-size: 1em; }
+    .markdown-content p { margin: 0; }
+    .markdown-content p + p { margin-top: var(--line-height); }
+
+    .markdown-content a {
+      color: var(--mdLink);
+      text-decoration: underline;
+    }
+
+    .markdown-content code {
+      background: rgba(128, 128, 128, 0.2);
+      color: var(--mdCode);
+      padding: 0 4px;
+      border-radius: 3px;
+      font-family: inherit;
+    }
+
+    .markdown-content pre {
+      background: transparent;
+      margin: var(--line-height) 0;
+      overflow-x: auto;
+    }
+
+    .markdown-content pre code {
+      display: block;
+      background: none;
+      color: var(--text);
+    }
+
+    .markdown-content blockquote {
+      border-left: 3px solid var(--mdQuoteBorder);
+      padding-left: var(--line-height);
+      margin: var(--line-height) 0;
+      color: var(--mdQuote);
+      font-style: italic;
+    }
+
+    .markdown-content ul,
+    .markdown-content ol {
+      margin: var(--line-height) 0;
+      padding-left: calc(var(--line-height) * 2);
+    }
+
+    .markdown-content li { margin: 0; }
+    .markdown-content li::marker { color: var(--mdListBullet); }
+
+    .markdown-content hr {
+      border: none;
+      border-top: 1px solid var(--mdHr);
+      margin: var(--line-height) 0;
+    }
+
+    .markdown-content table {
+      border-collapse: collapse;
+      margin: 0.5em 0;
+      width: 100%;
+    }
+
+    .markdown-content th,
+    .markdown-content td {
+      border: 1px solid var(--mdCodeBlockBorder);
+      padding: 6px 10px;
+      text-align: left;
+    }
+
+    .markdown-content th {
+      background: rgba(128, 128, 128, 0.1);
+      font-weight: bold;
+    }
+
+    .markdown-content img {
+      max-width: 100%;
+      border-radius: 4px;
+    }
+
+    /* Syntax highlighting */
+    .hljs { background: transparent; color: var(--text); }
+    .hljs-comment, .hljs-quote { color: var(--syntaxComment); }
+    .hljs-keyword, .hljs-selector-tag { color: var(--syntaxKeyword); }
+    .hljs-number, .hljs-literal { color: var(--syntaxNumber); }
+    .hljs-string, .hljs-doctag { color: var(--syntaxString); }
+    /* Function names: hljs v11 uses .hljs-title.function_ compound class */
+    .hljs-function, .hljs-title, .hljs-title.function_, .hljs-section, .hljs-name { color: var(--syntaxFunction); }
+    /* Types: hljs v11 uses .hljs-title.class_ for class names */
+    .hljs-type, .hljs-class, .hljs-title.class_, .hljs-built_in { color: var(--syntaxType); }
+    .hljs-attr, .hljs-variable, .hljs-variable.language_, .hljs-params, .hljs-property { color: var(--syntaxVariable); }
+    .hljs-meta, .hljs-meta .hljs-keyword, .hljs-meta .hljs-string { color: var(--syntaxKeyword); }
+    .hljs-operator { color: var(--syntaxOperator); }
+    .hljs-punctuation { color: var(--syntaxPunctuation); }
+    .hljs-subst { color: var(--text); }
+
+    /* Footer */
+    .footer {
+      margin-top: 48px;
+      padding: 20px;
+      text-align: center;
+      color: var(--dim);
+      font-size: 10px;
+    }
+
+    /* Mobile */
+    #hamburger {
+      display: none;
+      position: fixed;
+      top: 10px;
+      left: 10px;
+      z-index: 100;
+      padding: 3px 8px;
+      font-size: 12px;
+      font-family: inherit;
+      background: transparent;
+      color: var(--muted);
+      border: 1px solid var(--dim);
+      border-radius: 3px;
+      cursor: pointer;
+    }
+
+    #hamburger:hover {
+      color: var(--text);
+      border-color: var(--text);
+    }
+
+
+
+    #sidebar-overlay {
+      display: none;
+      position: fixed;
+      top: 0;
+      left: 0;
+      right: 0;
+      bottom: 0;
+      background: rgba(0, 0, 0, 0.5);
+      z-index: 98;
+    }
+
+    @media (max-width: 900px) {
+      #sidebar {
+        position: fixed;
+        left: 0;
+        width: min(var(--sidebar-width), 100vw);
+        min-width: min(var(--sidebar-width), 100vw);
+        max-width: min(var(--sidebar-width), 100vw);
+        top: 0;
+        bottom: 0;
+        height: 100vh;
+        z-index: 99;
+        transform: translateX(-100%);
+        transition: transform 0.3s;
+      }
+
+      #sidebar.open {
+        transform: translateX(0);
+      }
+
+      #sidebar-resizer {
+        display: none;
+      }
+
+      #sidebar-overlay.open {
+        display: block;
+      }
+
+      #hamburger {
+        display: block;
+      }
+
+      .sidebar-close {
+        display: block;
+      }
+
+      #content {
+        padding: var(--line-height) 16px;
+      }
+
+      #content > * {
+        max-width: 100%;
+      }
+    }
+
+    @media print {
+      #sidebar, #sidebar-resizer, #sidebar-toggle { display: none !important; }
+      body { background: white; color: black; }
+      #content { max-width: none; }
+    }

packages/coding-agent/src/core/export-html/template.html

@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Session Export</title>
+  <style>
+{{CSS}}
+  </style>
+</head>
+<body>
+  <button id="hamburger" title="Open sidebar"><svg width="14" height="14" viewBox="0 0 24 24" fill="currentColor" stroke="none"><circle cx="6" cy="6" r="2.5"/><circle cx="6" cy="18" r="2.5"/><circle cx="18" cy="12" r="2.5"/><rect x="5" y="6" width="2" height="12"/><path d="M6 12h10c1 0 2 0 2-2V8"/></svg></button>
+  <div id="sidebar-overlay"></div>
+  <div id="app">
+    <aside id="sidebar">
+      <div class="sidebar-header">
+        <div class="sidebar-controls">
+          <input type="text" class="sidebar-search" id="tree-search" placeholder="Search...">
+        </div>
+        <div class="sidebar-filters">
+          <button class="filter-btn active" data-filter="default" title="Hide settings entries">Default</button>
+          <button class="filter-btn" data-filter="no-tools" title="Default minus tool results">No-tools</button>
+          <button class="filter-btn" data-filter="user-only" title="Only user messages">User</button>
+          <button class="filter-btn" data-filter="labeled-only" title="Only labeled entries">Labeled</button>
+          <button class="filter-btn" data-filter="all" title="Show everything">All</button>
+          <button class="sidebar-close" id="sidebar-close" title="Close">✕</button>
+        </div>
+      </div>
+      <div class="tree-container" id="tree-container"></div>
+      <div class="tree-status" id="tree-status"></div>
+    </aside>
+    <div id="sidebar-resizer" role="separator" aria-orientation="vertical" aria-label="Resize session tree sidebar"></div>
+    <main id="content">
+      <div id="header-container"></div>
+      <div id="messages"></div>
+    </main>
+    <div id="image-modal" class="image-modal">
+      <img id="modal-image" src="" alt="">
+    </div>
+  </div>
+
+  <script id="session-data" type="application/json">{{SESSION_DATA}}</script>
+
+  <!-- Vendored libraries -->
+  <script>{{MARKED_JS}}</script>
+
+  <!-- highlight.js -->
+  <script>{{HIGHLIGHT_JS}}</script>
+
+  <!-- Main application code -->
+  <script>
+{{JS}}
+  </script>
+</body>
+</html>

packages/coding-agent/src/core/export-html/template.js

@@ -0,0 +1,1864 @@
+    (function() {
+      'use strict';
+
+      // ============================================================
+      // DATA LOADING
+      // ============================================================
+
+      const base64 = document.getElementById('session-data').textContent;
+      const binary = atob(base64);
+      const bytes = new Uint8Array(binary.length);
+      for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+      }
+      const data = JSON.parse(new TextDecoder('utf-8').decode(bytes));
+      const { header, entries, leafId: defaultLeafId, systemPrompt, tools, renderedTools } = data;
+
+      // ============================================================
+      // URL PARAMETER HANDLING
+      // ============================================================
+
+      // Parse URL parameters for deep linking: leafId and targetId
+      // Check for injected params (when loaded in iframe via srcdoc) or use window.location
+      const injectedParams = document.querySelector('meta[name="pi-url-params"]');
+      const searchString = injectedParams ? injectedParams.content : window.location.search.substring(1);
+      const urlParams = new URLSearchParams(searchString);
+      const urlLeafId = urlParams.get('leafId');
+      const urlTargetId = urlParams.get('targetId');
+      // Use URL leafId if provided, otherwise fall back to session default
+      const leafId = urlLeafId || defaultLeafId;
+
+      // ============================================================
+      // DATA STRUCTURES
+      // ============================================================
+
+      // Entry lookup by ID
+      const byId = new Map();
+      for (const entry of entries) {
+        byId.set(entry.id, entry);
+      }
+
+      // Tool call lookup (toolCallId -> {name, arguments})
+      const toolCallMap = new Map();
+      for (const entry of entries) {
+        if (entry.type === 'message' && entry.message.role === 'assistant') {
+          const content = entry.message.content;
+          if (Array.isArray(content)) {
+            for (const block of content) {
+              if (block.type === 'toolCall') {
+                toolCallMap.set(block.id, { name: block.name, arguments: block.arguments });
+              }
+            }
+          }
+        }
+      }
+
+      // Label lookup (entryId -> label string)
+      // Labels are stored in 'label' entries that reference their target via targetId
+      const labelMap = new Map();
+      for (const entry of entries) {
+        if (entry.type === 'label' && entry.targetId && entry.label) {
+          labelMap.set(entry.targetId, entry.label);
+        }
+      }
+
+      // ============================================================
+      // TREE DATA PREPARATION (no DOM, pure data)
+      // ============================================================
+
+      /**
+       * Build tree structure from flat entries.
+       * Returns array of root nodes, each with { entry, children, label }.
+       */
+      function buildTree() {
+        const nodeMap = new Map();
+        const roots = [];
+
+        // Create nodes
+        for (const entry of entries) {
+          nodeMap.set(entry.id, {
+            entry,
+            children: [],
+            label: labelMap.get(entry.id)
+          });
+        }
+
+        // Build parent-child relationships
+        for (const entry of entries) {
+          const node = nodeMap.get(entry.id);
+          if (entry.parentId === null || entry.parentId === undefined || entry.parentId === entry.id) {
+            roots.push(node);
+          } else {
+            const parent = nodeMap.get(entry.parentId);
+            if (parent) {
+              parent.children.push(node);
+            } else {
+              roots.push(node);
+            }
+          }
+        }
+
+        // Sort children by timestamp
+        function sortChildren(node) {
+          node.children.sort((a, b) =>
+            new Date(a.entry.timestamp).getTime() - new Date(b.entry.timestamp).getTime()
+          );
+          node.children.forEach(sortChildren);
+        }
+        roots.forEach(sortChildren);
+
+        return roots;
+      }
+
+      /**
+       * Build set of entry IDs on path from root to target.
+       */
+      function buildActivePathIds(targetId) {
+        const ids = new Set();
+        let current = byId.get(targetId);
+        while (current) {
+          ids.add(current.id);
+          // Stop if no parent or self-referencing (root)
+          if (!current.parentId || current.parentId === current.id) {
+            break;
+          }
+          current = byId.get(current.parentId);
+        }
+        return ids;
+      }
+
+      /**
+       * Get array of entries from root to target (the conversation path).
+       */
+      function getPath(targetId) {
+        const path = [];
+        let current = byId.get(targetId);
+        while (current) {
+          path.unshift(current);
+          // Stop if no parent or self-referencing (root)
+          if (!current.parentId || current.parentId === current.id) {
+            break;
+          }
+          current = byId.get(current.parentId);
+        }
+        return path;
+      }
+
+      // Tree node lookup for finding leaves
+      let treeNodeMap = null;
+
+      /**
+       * Find the newest leaf node reachable from a given node.
+       * This allows clicking any node in a branch to show the full branch.
+       * Children are sorted by timestamp, so the newest is always last.
+       */
+      function findNewestLeaf(nodeId) {
+        // Build tree node map lazily
+        if (!treeNodeMap) {
+          treeNodeMap = new Map();
+          const tree = buildTree();
+          function mapNodes(node) {
+            treeNodeMap.set(node.entry.id, node);
+            node.children.forEach(mapNodes);
+          }
+          tree.forEach(mapNodes);
+        }
+
+        const node = treeNodeMap.get(nodeId);
+        if (!node) return nodeId;
+
+        // Follow the newest (last) child at each level
+        let current = node;
+        while (current.children.length > 0) {
+          current = current.children[current.children.length - 1];
+        }
+        return current.entry.id;
+      }
+
+      /**
+       * Flatten tree into list with indentation and connector info.
+       * Returns array of { node, indent, showConnector, isLast, gutters, isVirtualRootChild, multipleRoots }.
+       * Matches tree-selector.ts logic exactly.
+       */
+      function flattenTree(roots, activePathIds) {
+        const result = [];
+        const multipleRoots = roots.length > 1;
+
+        // Mark which subtrees contain the active leaf
+        const containsActive = new Map();
+        function markActive(node) {
+          let has = activePathIds.has(node.entry.id);
+          for (const child of node.children) {
+            if (markActive(child)) has = true;
+          }
+          containsActive.set(node, has);
+          return has;
+        }
+        roots.forEach(markActive);
+
+        // Stack: [node, indent, justBranched, showConnector, isLast, gutters, isVirtualRootChild]
+        const stack = [];
+
+        // Add roots (prioritize branch containing active leaf)
+        const orderedRoots = [...roots].sort((a, b) =>
+          Number(containsActive.get(b)) - Number(containsActive.get(a))
+        );
+        for (let i = orderedRoots.length - 1; i >= 0; i--) {
+          const isLast = i === orderedRoots.length - 1;
+          stack.push([orderedRoots[i], multipleRoots ? 1 : 0, multipleRoots, multipleRoots, isLast, [], multipleRoots]);
+        }
+
+        while (stack.length > 0) {
+          const [node, indent, justBranched, showConnector, isLast, gutters, isVirtualRootChild] = stack.pop();
+
+          result.push({ node, indent, showConnector, isLast, gutters, isVirtualRootChild, multipleRoots });
+
+          const children = node.children;
+          const multipleChildren = children.length > 1;
+
+          // Order children (active branch first)
+          const orderedChildren = [...children].sort((a, b) =>
+            Number(containsActive.get(b)) - Number(containsActive.get(a))
+          );
+
+          // Calculate child indent (matches tree-selector.ts)
+          let childIndent;
+          if (multipleChildren) {
+            // Parent branches: children get +1
+            childIndent = indent + 1;
+          } else if (justBranched && indent > 0) {
+            // First generation after a branch: +1 for visual grouping
+            childIndent = indent + 1;
+          } else {
+            // Single-child chain: stay flat
+            childIndent = indent;
+          }
+
+          // Build gutters for children
+          const connectorDisplayed = showConnector && !isVirtualRootChild;
+          const currentDisplayIndent = multipleRoots ? Math.max(0, indent - 1) : indent;
+          const connectorPosition = Math.max(0, currentDisplayIndent - 1);
+          const childGutters = connectorDisplayed
+            ? [...gutters, { position: connectorPosition, show: !isLast }]
+            : gutters;
+
+          // Add children in reverse order for stack
+          for (let i = orderedChildren.length - 1; i >= 0; i--) {
+            const childIsLast = i === orderedChildren.length - 1;
+            stack.push([orderedChildren[i], childIndent, multipleChildren, multipleChildren, childIsLast, childGutters, false]);
+          }
+        }
+
+        return result;
+      }
+
+      /**
+       * Build ASCII prefix string for tree node.
+       */
+      function buildTreePrefix(flatNode) {
+        const { indent, showConnector, isLast, gutters, isVirtualRootChild, multipleRoots } = flatNode;
+        const displayIndent = multipleRoots ? Math.max(0, indent - 1) : indent;
+        const connector = showConnector && !isVirtualRootChild ? (isLast ? '└─ ' : '├─ ') : '';
+        const connectorPosition = connector ? displayIndent - 1 : -1;
+
+        const totalChars = displayIndent * 3;
+        const prefixChars = [];
+        for (let i = 0; i < totalChars; i++) {
+          const level = Math.floor(i / 3);
+          const posInLevel = i % 3;
+
+          const gutter = gutters.find(g => g.position === level);
+          if (gutter) {
+            prefixChars.push(posInLevel === 0 ? (gutter.show ? '│' : ' ') : ' ');
+          } else if (connector && level === connectorPosition) {
+            if (posInLevel === 0) {
+              prefixChars.push(isLast ? '└' : '├');
+            } else if (posInLevel === 1) {
+              prefixChars.push('─');
+            } else {
+              prefixChars.push(' ');
+            }
+          } else {
+            prefixChars.push(' ');
+          }
+        }
+        return prefixChars.join('');
+      }
+
+      // ============================================================
+      // FILTERING (pure data)
+      // ============================================================
+
+      let filterMode = 'default';
+      let searchQuery = '';
+
+      function hasTextContent(content) {
+        if (typeof content === 'string') return content.trim().length > 0;
+        if (Array.isArray(content)) {
+          for (const c of content) {
+            if (c.type === 'text' && c.text && c.text.trim().length > 0) return true;
+          }
+        }
+        return false;
+      }
+
+      function extractContent(content) {
+        if (typeof content === 'string') return content;
+        if (Array.isArray(content)) {
+          return content
+            .filter(c => c.type === 'text' && c.text)
+            .map(c => c.text)
+            .join('');
+        }
+        return '';
+      }
+
+      /**
+       * Parse a skill block from message text.
+       * Returns null if the text doesn't contain a skill block.
+       * Matches the format: <skill name="..." location="...">\n...\n</skill>\n\nuser message
+       */
+      function parseSkillBlock(text) {
+        const match = text.match(/^<skill name="([^"]+)" location="([^"]+)">\n([\s\S]*?)\n<\/skill>(?:\n\n([\s\S]+))?$/);
+        if (!match) return null;
+        return {
+          name: match[1],
+          location: match[2],
+          content: match[3],
+          userMessage: match[4]?.trim() || undefined,
+        };
+      }
+
+      function getSearchableText(entry, label) {
+        const parts = [];
+        if (label) parts.push(label);
+
+        switch (entry.type) {
+          case 'message': {
+            const msg = entry.message;
+            parts.push(msg.role);
+            if (msg.content) parts.push(extractContent(msg.content));
+            if (msg.role === 'bashExecution' && msg.command) parts.push(msg.command);
+            break;
+          }
+          case 'custom_message':
+            parts.push(entry.customType);
+            parts.push(typeof entry.content === 'string' ? entry.content : extractContent(entry.content));
+            break;
+          case 'compaction':
+            parts.push('compaction');
+            break;
+          case 'branch_summary':
+            parts.push('branch summary', entry.summary);
+            break;
+          case 'model_change':
+            parts.push('model', entry.modelId);
+            break;
+          case 'thinking_level_change':
+            parts.push('thinking', entry.thinkingLevel);
+            break;
+        }
+
+        return parts.join(' ').toLowerCase();
+      }
+
+      /**
+       * Filter flat nodes based on current filterMode and searchQuery.
+       */
+      function filterNodes(flatNodes, currentLeafId) {
+        const searchTokens = searchQuery.toLowerCase().split(/\s+/).filter(Boolean);
+
+        const filtered = flatNodes.filter(flatNode => {
+          const entry = flatNode.node.entry;
+          const label = flatNode.node.label;
+          const isCurrentLeaf = entry.id === currentLeafId;
+
+          // Always show current leaf
+          if (isCurrentLeaf) return true;
+
+          // Hide assistant messages with only tool calls (no text) unless error/aborted
+          if (entry.type === 'message' && entry.message.role === 'assistant') {
+            const msg = entry.message;
+            const hasText = hasTextContent(msg.content);
+            const isErrorOrAborted = msg.stopReason && msg.stopReason !== 'stop' && msg.stopReason !== 'toolUse';
+            if (!hasText && !isErrorOrAborted) return false;
+          }
+
+          // Apply filter mode
+          const isSettingsEntry = ['label', 'custom', 'model_change', 'thinking_level_change'].includes(entry.type);
+          let passesFilter = true;
+
+          switch (filterMode) {
+            case 'user-only':
+              passesFilter = entry.type === 'message' && entry.message.role === 'user';
+              break;
+            case 'no-tools':
+              passesFilter = !isSettingsEntry && !(entry.type === 'message' && entry.message.role === 'toolResult');
+              break;
+            case 'labeled-only':
+              passesFilter = label !== undefined;
+              break;
+            case 'all':
+              passesFilter = true;
+              break;
+            default: // 'default'
+              passesFilter = !isSettingsEntry;
+              break;
+          }
+
+          if (!passesFilter) return false;
+
+          // Apply search filter
+          if (searchTokens.length > 0) {
+            const nodeText = getSearchableText(entry, label);
+            if (!searchTokens.every(t => nodeText.includes(t))) return false;
+          }
+
+          return true;
+        });
+
+        // Recalculate visual structure based on visible tree
+        recalculateVisualStructure(filtered, flatNodes);
+
+        return filtered;
+      }
+
+      /**
+       * Recompute indentation/connectors for the filtered view
+       *
+       * Filtering can hide intermediate entries; descendants attach to the nearest visible ancestor.
+       * Keep indentation semantics aligned with flattenTree() so single-child chains don't drift right.
+       */
+      function recalculateVisualStructure(filteredNodes, allFlatNodes) {
+        if (filteredNodes.length === 0) return;
+
+        const visibleIds = new Set(filteredNodes.map(n => n.node.entry.id));
+
+        // Build entry map for parent lookup (using full tree)
+        const entryMap = new Map();
+        for (const flatNode of allFlatNodes) {
+          entryMap.set(flatNode.node.entry.id, flatNode);
+        }
+
+        // Find nearest visible ancestor for a node
+        function findVisibleAncestor(nodeId) {
+          let currentId = entryMap.get(nodeId)?.node.entry.parentId;
+          while (currentId != null) {
+            if (visibleIds.has(currentId)) {
+              return currentId;
+            }
+            currentId = entryMap.get(currentId)?.node.entry.parentId;
+          }
+          return null;
+        }
+
+        // Build visible tree structure
+        const visibleParent = new Map();
+        const visibleChildren = new Map();
+        visibleChildren.set(null, []); // root-level nodes
+
+        for (const flatNode of filteredNodes) {
+          const nodeId = flatNode.node.entry.id;
+          const ancestorId = findVisibleAncestor(nodeId);
+          visibleParent.set(nodeId, ancestorId);
+
+          if (!visibleChildren.has(ancestorId)) {
+            visibleChildren.set(ancestorId, []);
+          }
+          visibleChildren.get(ancestorId).push(nodeId);
+        }
+
+        // Update multipleRoots based on visible roots
+        const visibleRootIds = visibleChildren.get(null);
+        const multipleRoots = visibleRootIds.length > 1;
+
+        // Build a map for quick lookup: nodeId → FlatNode
+        const filteredNodeMap = new Map();
+        for (const flatNode of filteredNodes) {
+          filteredNodeMap.set(flatNode.node.entry.id, flatNode);
+        }
+
+        // DFS traversal of visible tree, applying same indentation rules as flattenTree()
+        // Stack items: [nodeId, indent, justBranched, showConnector, isLast, gutters, isVirtualRootChild]
+        const stack = [];
+
+        // Add visible roots in reverse order (to process in forward order via stack)
+        for (let i = visibleRootIds.length - 1; i >= 0; i--) {
+          const isLast = i === visibleRootIds.length - 1;
+          stack.push([
+            visibleRootIds[i],
+            multipleRoots ? 1 : 0,
+            multipleRoots,
+            multipleRoots,
+            isLast,
+            [],
+            multipleRoots
+          ]);
+        }
+
+        while (stack.length > 0) {
+          const [nodeId, indent, justBranched, showConnector, isLast, gutters, isVirtualRootChild] = stack.pop();
+
+          const flatNode = filteredNodeMap.get(nodeId);
+          if (!flatNode) continue;
+
+          // Update this node's visual properties
+          flatNode.indent = indent;
+          flatNode.showConnector = showConnector;
+          flatNode.isLast = isLast;
+          flatNode.gutters = gutters;
+          flatNode.isVirtualRootChild = isVirtualRootChild;
+          flatNode.multipleRoots = multipleRoots;
+
+          // Get visible children of this node
+          const children = visibleChildren.get(nodeId) || [];
+          const multipleChildren = children.length > 1;
+
+          // Calculate child indent using same rules as flattenTree():
+          // - Parent branches (multiple children): children get +1
+          // - Just branched and indent > 0: children get +1 for visual grouping
+          // - Single-child chain: stay flat
+          let childIndent;
+          if (multipleChildren) {
+            childIndent = indent + 1;
+          } else if (justBranched && indent > 0) {
+            childIndent = indent + 1;
+          } else {
+            childIndent = indent;
+          }
+
+          // Build gutters for children (same logic as flattenTree)
+          const connectorDisplayed = showConnector && !isVirtualRootChild;
+          const currentDisplayIndent = multipleRoots ? Math.max(0, indent - 1) : indent;
+          const connectorPosition = Math.max(0, currentDisplayIndent - 1);
+          const childGutters = connectorDisplayed
+            ? [...gutters, { position: connectorPosition, show: !isLast }]
+            : gutters;
+
+          // Add children in reverse order (to process in forward order via stack)
+          for (let i = children.length - 1; i >= 0; i--) {
+            const childIsLast = i === children.length - 1;
+            stack.push([
+              children[i],
+              childIndent,
+              multipleChildren,
+              multipleChildren,
+              childIsLast,
+              childGutters,
+              false
+            ]);
+          }
+        }
+      }
+
+      // ============================================================
+      // TREE DISPLAY TEXT (pure data -> string)
+      // ============================================================
+
+      function shortenPath(p) {
+        if (typeof p !== 'string') return '';
+        if (p.startsWith('/Users/')) {
+          const parts = p.split('/');
+          if (parts.length > 2) return '~' + p.slice(('/Users/' + parts[2]).length);
+        }
+        if (p.startsWith('/home/')) {
+          const parts = p.split('/');
+          if (parts.length > 2) return '~' + p.slice(('/home/' + parts[2]).length);
+        }
+        return p;
+      }
+
+      function formatToolCall(name, args) {
+        switch (name) {
+          case 'read': {
+            const path = shortenPath(String(args.path || args.file_path || ''));
+            const offset = args.offset;
+            const limit = args.limit;
+            let display = path;
+            if (offset !== undefined || limit !== undefined) {
+              const start = offset ?? 1;
+              const end = limit !== undefined ? start + limit - 1 : '';
+              display += `:${start}${end ? `-${end}` : ''}`;
+            }
+            return `[read: ${display}]`;
+          }
+          case 'write':
+            return `[write: ${shortenPath(String(args.path || args.file_path || ''))}]`;
+          case 'edit':
+            return `[edit: ${shortenPath(String(args.path || args.file_path || ''))}]`;
+          case 'bash': {
+            const rawCmd = String(args.command || '');
+            const cmd = rawCmd.replace(/[\n\t]/g, ' ').trim().slice(0, 50);
+            return `[bash: ${cmd}${rawCmd.length > 50 ? '...' : ''}]`;
+          }
+          case 'grep':
+            return `[grep: /${args.pattern || ''}/ in ${shortenPath(String(args.path || '.'))}]`;
+          case 'find':
+            return `[find: ${args.pattern || ''} in ${shortenPath(String(args.path || '.'))}]`;
+          case 'ls':
+            return `[ls: ${shortenPath(String(args.path || '.'))}]`;
+          default: {
+            const argsStr = JSON.stringify(args).slice(0, 40);
+            return `[${name}: ${argsStr}${JSON.stringify(args).length > 40 ? '...' : ''}]`;
+          }
+        }
+      }
+
+      function escapeHtml(text) {
+        return String(text)
+          .replace(/&/g, '&amp;')
+          .replace(/</g, '&lt;')
+          .replace(/>/g, '&gt;')
+          .replace(/"/g, '&quot;')
+          .replace(/'/g, '&#39;');
+      }
+
+      function sanitizeMarkdownUrl(value) {
+        const href = String(value || '').trim().replace(/[\x00-\x1f\x7f]/g, '');
+        if (!href) return href;
+
+        const scheme = href.match(/^([A-Za-z][A-Za-z0-9+.-]*):/);
+        if (scheme && !/^(https?|mailto|tel|ftp)$/i.test(scheme[1])) {
+          return null;
+        }
+
+        return href;
+      }
+
+      /**
+       * Truncate string to maxLen chars, append "..." if truncated.
+       */
+      function truncate(s, maxLen = 100) {
+        if (s.length <= maxLen) return s;
+        return s.slice(0, maxLen) + '...';
+      }
+
+      /**
+       * Get display text for tree node (returns HTML string).
+       */
+      function getTreeNodeDisplayHtml(entry, label) {
+        const normalize = s => s.replace(/[\n\t]/g, ' ').trim();
+        const labelHtml = label ? `<span class="tree-label">[${escapeHtml(label)}]</span> ` : '';
+
+        switch (entry.type) {
+          case 'message': {
+            const msg = entry.message;
+            if (msg.role === 'user') {
+              const rawContent = extractContent(msg.content);
+              const skillBlock = parseSkillBlock(rawContent);
+              if (skillBlock) {
+                let treeHtml = labelHtml + `<span class="tree-role-skill">skill:</span> ${escapeHtml(skillBlock.name)}`;
+                if (skillBlock.userMessage) {
+                  treeHtml += ` · <span class="tree-role-user">user:</span> ${escapeHtml(truncate(normalize(skillBlock.userMessage)))}`;
+                }
+                return treeHtml;
+              }
+              const content = truncate(normalize(rawContent));
+              return labelHtml + `<span class="tree-role-user">user:</span> ${escapeHtml(content)}`;
+            }
+            if (msg.role === 'assistant') {
+              const textContent = truncate(normalize(extractContent(msg.content)));
+              if (textContent) {
+                return labelHtml + `<span class="tree-role-assistant">assistant:</span> ${escapeHtml(textContent)}`;
+              }
+              if (msg.stopReason === 'aborted') {
+                return labelHtml + `<span class="tree-role-assistant">assistant:</span> <span class="tree-muted">(aborted)</span>`;
+              }
+              if (msg.errorMessage) {
+                return labelHtml + `<span class="tree-role-assistant">assistant:</span> <span class="tree-error">${escapeHtml(truncate(msg.errorMessage))}</span>`;
+              }
+              return labelHtml + `<span class="tree-role-assistant">assistant:</span> <span class="tree-muted">(no text)</span>`;
+            }
+            if (msg.role === 'toolResult') {
+              const toolCall = msg.toolCallId ? toolCallMap.get(msg.toolCallId) : null;
+              if (toolCall) {
+                return labelHtml + `<span class="tree-role-tool">${escapeHtml(formatToolCall(toolCall.name, toolCall.arguments))}</span>`;
+              }
+              return labelHtml + `<span class="tree-role-tool">[${escapeHtml(msg.toolName || 'tool')}]</span>`;
+            }
+            if (msg.role === 'bashExecution') {
+              const cmd = truncate(normalize(msg.command || ''));
+              return labelHtml + `<span class="tree-role-tool">[bash]:</span> ${escapeHtml(cmd)}`;
+            }
+            return labelHtml + `<span class="tree-muted">[${escapeHtml(msg.role)}]</span>`;
+          }
+          case 'compaction':
+            return labelHtml + `<span class="tree-compaction">[compaction: ${Math.round(entry.tokensBefore/1000)}k tokens]</span>`;
+          case 'branch_summary': {
+            const summary = truncate(normalize(entry.summary || ''));
+            return labelHtml + `<span class="tree-branch-summary">[branch summary]:</span> ${escapeHtml(summary)}`;
+          }
+          case 'custom_message': {
+            const content = typeof entry.content === 'string' ? entry.content : extractContent(entry.content);
+            return labelHtml + `<span class="tree-custom">[${escapeHtml(entry.customType)}]:</span> ${escapeHtml(truncate(normalize(content)))}`;
+          }
+          case 'model_change':
+            return labelHtml + `<span class="tree-muted">[model: ${escapeHtml(entry.modelId)}]</span>`;
+          case 'thinking_level_change':
+            return labelHtml + `<span class="tree-muted">[thinking: ${escapeHtml(entry.thinkingLevel)}]</span>`;
+          default:
+            return labelHtml + `<span class="tree-muted">[${escapeHtml(entry.type)}]</span>`;
+        }
+      }
+
+      // ============================================================
+      // TREE RENDERING (DOM manipulation)
+      // ============================================================
+
+      let currentLeafId = leafId;
+      let currentTargetId = urlTargetId || leafId;
+      let treeRendered = false;
+
+      function renderTree() {
+        const tree = buildTree();
+        const activePathIds = buildActivePathIds(currentLeafId);
+        const flatNodes = flattenTree(tree, activePathIds);
+        const filtered = filterNodes(flatNodes, currentLeafId);
+        const container = document.getElementById('tree-container');
+
+        // Full render only on first call or when filter/search changes
+        if (!treeRendered) {
+          container.innerHTML = '';
+
+          for (const flatNode of filtered) {
+            const entry = flatNode.node.entry;
+            const isOnPath = activePathIds.has(entry.id);
+            const isTarget = entry.id === currentTargetId;
+
+            const div = document.createElement('div');
+            div.className = 'tree-node';
+            if (isOnPath) div.classList.add('in-path');
+            if (isTarget) div.classList.add('active');
+            div.dataset.id = entry.id;
+
+            const prefix = buildTreePrefix(flatNode);
+            const prefixSpan = document.createElement('span');
+            prefixSpan.className = 'tree-prefix';
+            prefixSpan.textContent = prefix;
+
+            const marker = document.createElement('span');
+            marker.className = 'tree-marker';
+            marker.textContent = isOnPath ? '•' : ' ';
+
+            const content = document.createElement('span');
+            content.className = 'tree-content';
+            content.innerHTML = getTreeNodeDisplayHtml(entry, flatNode.node.label);
+
+            div.appendChild(prefixSpan);
+            div.appendChild(marker);
+            div.appendChild(content);
+            // Navigate to the newest leaf through this node, but scroll to the clicked node
+            div.addEventListener('click', () => {
+              if (window.getSelection().toString()) return;
+              const leafId = findNewestLeaf(entry.id);
+              navigateTo(leafId, 'target', entry.id);
+            });
+
+            container.appendChild(div);
+          }
+
+          treeRendered = true;
+        } else {
+          // Just update markers and classes
+          const nodes = container.querySelectorAll('.tree-node');
+          for (const node of nodes) {
+            const id = node.dataset.id;
+            const isOnPath = activePathIds.has(id);
+            const isTarget = id === currentTargetId;
+
+            node.classList.toggle('in-path', isOnPath);
+            node.classList.toggle('active', isTarget);
+
+            const marker = node.querySelector('.tree-marker');
+            if (marker) {
+              marker.textContent = isOnPath ? '•' : ' ';
+            }
+          }
+        }
+
+        document.getElementById('tree-status').textContent = `${filtered.length} / ${flatNodes.length} entries`;
+
+        // Scroll active node into view after layout
+        setTimeout(() => {
+          const activeNode = container.querySelector('.tree-node.active');
+          if (activeNode) {
+            activeNode.scrollIntoView({ block: 'nearest' });
+          }
+        }, 0);
+      }
+
+      function forceTreeRerender() {
+        treeRendered = false;
+        renderTree();
+      }
+
+      // ============================================================
+      // MESSAGE RENDERING
+      // ============================================================
+
+      function formatTokens(count) {
+        if (count < 1000) return count.toString();
+        if (count < 10000) return (count / 1000).toFixed(1) + 'k';
+        if (count < 1000000) return Math.round(count / 1000) + 'k';
+        return (count / 1000000).toFixed(1) + 'M';
+      }
+
+      function formatTimestamp(ts) {
+        if (!ts) return '';
+        const date = new Date(ts);
+        return date.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit', second: '2-digit' });
+      }
+
+      function replaceTabs(text) {
+        return text.replace(/\t/g, '   ');
+      }
+
+      /** Safely coerce value to string for display. Returns null if invalid type. */
+      function str(value) {
+        if (typeof value === 'string') return value;
+        if (value == null) return '';
+        return null;
+      }
+
+      function getLanguageFromPath(filePath) {
+        const ext = filePath.split('.').pop()?.toLowerCase();
+        const extToLang = {
+          ts: 'typescript', tsx: 'typescript', js: 'javascript', jsx: 'javascript',
+          py: 'python', rb: 'ruby', rs: 'rust', go: 'go', java: 'java',
+          c: 'c', cpp: 'cpp', h: 'c', hpp: 'cpp', cs: 'csharp',
+          php: 'php', sh: 'bash', bash: 'bash', zsh: 'bash',
+          sql: 'sql', html: 'html', css: 'css', scss: 'scss',
+          json: 'json', yaml: 'yaml', yml: 'yaml', xml: 'xml',
+          md: 'markdown', dockerfile: 'dockerfile'
+        };
+        return extToLang[ext];
+      }
+
+      function findToolResult(toolCallId) {
+        for (const entry of entries) {
+          if (entry.type === 'message' && entry.message.role === 'toolResult') {
+            if (entry.message.toolCallId === toolCallId) {
+              return entry.message;
+            }
+          }
+        }
+        return null;
+      }
+
+      function formatExpandableOutput(text, maxLines, lang) {
+        text = replaceTabs(text);
+        const lines = text.split('\n');
+        const displayLines = lines.slice(0, maxLines);
+        const remaining = lines.length - maxLines;
+
+        if (lang) {
+          let highlighted;
+          try {
+            highlighted = hljs.highlight(text, { language: lang }).value;
+          } catch {
+            highlighted = escapeHtml(text);
+          }
+
+          if (remaining > 0) {
+            const previewCode = displayLines.join('\n');
+            let previewHighlighted;
+            try {
+              previewHighlighted = hljs.highlight(previewCode, { language: lang }).value;
+            } catch {
+              previewHighlighted = escapeHtml(previewCode);
+            }
+
+            return `<div class="tool-output expandable" onclick="if(window.getSelection().toString())return;this.classList.toggle('expanded')">
+              <div class="output-preview"><pre><code class="hljs">${previewHighlighted}</code></pre>
+              <div class="expand-hint">... (${remaining} more lines)</div></div>
+              <div class="output-full"><pre><code class="hljs">${highlighted}</code></pre></div></div>`;
+          }
+
+          return `<div class="tool-output"><pre><code class="hljs">${highlighted}</code></pre></div>`;
+        }
+
+        // Plain text output
+        if (remaining > 0) {
+          let out = '<div class="tool-output expandable" onclick="if(window.getSelection().toString())return;this.classList.toggle(\'expanded\')">';
+          out += '<div class="output-preview">';
+          for (const line of displayLines) {
+            out += `<div>${escapeHtml(replaceTabs(line))}</div>`;
+          }
+          out += `<div class="expand-hint">... (${remaining} more lines)</div></div>`;
+          out += '<div class="output-full">';
+          for (const line of lines) {
+            out += `<div>${escapeHtml(replaceTabs(line))}</div>`;
+          }
+          out += '</div></div>';
+          return out;
+        }
+
+        let out = '<div class="tool-output">';
+        for (const line of displayLines) {
+          out += `<div>${escapeHtml(replaceTabs(line))}</div>`;
+        }
+        out += '</div>';
+        return out;
+      }
+
+      function renderToolCall(call) {
+        const result = findToolResult(call.id);
+        const isError = result?.isError || false;
+        const statusClass = result ? (isError ? 'error' : 'success') : 'pending';
+
+        const getResultText = () => {
+          if (!result) return '';
+          const textBlocks = result.content.filter(c => c.type === 'text');
+          return textBlocks.map(c => c.text).join('\n');
+        };
+
+        const getResultImages = () => {
+          if (!result) return [];
+          return result.content.filter(c => c.type === 'image');
+        };
+
+        const renderResultImages = () => {
+          const images = getResultImages();
+          if (images.length === 0) return '';
+          return '<div class="tool-images">' +
+            images.map(img => `<img src="data:${escapeHtml(img.mimeType || 'image/png')};base64,${escapeHtml(img.data || '')}" class="tool-image" />`).join('') +
+            '</div>';
+        };
+
+        const toolDomId = `tool-call-${escapeHtml(call.id)}`;
+        let html = `<div class="tool-execution ${statusClass}" id="${toolDomId}">`;
+        const args = call.arguments || {};
+        const name = call.name;
+
+        const invalidArg = '<span class="tool-error">[invalid arg]</span>';
+
+        switch (name) {
+          case 'bash': {
+            const command = str(args.command);
+            const cmdDisplay = command === null ? invalidArg : escapeHtml(command || '...');
+            html += `<div class="tool-command">$ ${cmdDisplay}</div>`;
+            if (result) {
+              const output = getResultText().trim();
+              if (output) html += formatExpandableOutput(output, 5);
+            }
+            break;
+          }
+          case 'read': {
+            const filePath = str(args.file_path ?? args.path);
+            const offset = args.offset;
+            const limit = args.limit;
+
+            let pathHtml = filePath === null ? invalidArg : escapeHtml(shortenPath(filePath || ''));
+            if (filePath !== null && (offset !== undefined || limit !== undefined)) {
+              const startLine = offset ?? 1;
+              const endLine = limit !== undefined ? startLine + limit - 1 : '';
+              pathHtml += `<span class="line-numbers">:${startLine}${endLine ? '-' + endLine : ''}</span>`;
+            }
+
+            html += `<div class="tool-header"><span class="tool-name">read</span> <span class="tool-path">${pathHtml}</span></div>`;
+            if (result) {
+              html += renderResultImages();
+              const output = getResultText();
+              const lang = filePath ? getLanguageFromPath(filePath) : null;
+              if (output) html += formatExpandableOutput(output, 10, lang);
+            }
+            break;
+          }
+          case 'write': {
+            const filePath = str(args.file_path ?? args.path);
+            const content = str(args.content);
+
+            html += `<div class="tool-header"><span class="tool-name">write</span> <span class="tool-path">${filePath === null ? invalidArg : escapeHtml(shortenPath(filePath || ''))}</span>`;
+            if (content !== null && content) {
+              const lines = content.split('\n');
+              if (lines.length > 10) html += ` <span class="line-count">(${lines.length} lines)</span>`;
+            }
+            html += '</div>';
+
+            if (content === null) {
+              html += `<div class="tool-error">[invalid content arg - expected string]</div>`;
+            } else if (content) {
+              const lang = filePath ? getLanguageFromPath(filePath) : null;
+              html += formatExpandableOutput(content, 10, lang);
+            }
+            if (result) {
+              const output = getResultText().trim();
+              if (output) html += `<div class="tool-output"><div>${escapeHtml(output)}</div></div>`;
+            }
+            break;
+          }
+          case 'edit': {
+            const filePath = str(args.file_path ?? args.path);
+            html += `<div class="tool-header"><span class="tool-name">edit</span> <span class="tool-path">${filePath === null ? invalidArg : escapeHtml(shortenPath(filePath || ''))}</span></div>`;
+
+            if (result?.details?.diff) {
+              const diffLines = result.details.diff.split('\n');
+              html += '<div class="tool-diff">';
+              for (const line of diffLines) {
+                const cls = line.match(/^\+/) ? 'diff-added' : line.match(/^-/) ? 'diff-removed' : 'diff-context';
+                html += `<div class="${cls}">${escapeHtml(replaceTabs(line))}</div>`;
+              }
+              html += '</div>';
+            } else if (result) {
+              const output = getResultText().trim();
+              if (output) html += `<div class="tool-output"><pre>${escapeHtml(output)}</pre></div>`;
+            }
+            break;
+          }
+          case 'ls': {
+            const dirPath = str(args.path);
+            const limit = args.limit;
+
+            let pathHtml = dirPath === null ? invalidArg : escapeHtml(shortenPath(dirPath || '.'));
+            if (limit !== undefined) {
+              pathHtml += ` <span class="line-count">(limit ${escapeHtml(String(limit))})</span>`;
+            }
+
+            html += `<div class="tool-header"><span class="tool-name">ls</span> <span class="tool-path">${pathHtml}</span></div>`;
+            if (result) {
+              const output = getResultText().trim();
+              if (output) html += formatExpandableOutput(output, 20);
+            }
+            break;
+          }
+          default: {
+            // Check for pre-rendered custom tool HTML
+            const rendered = renderedTools?.[call.id];
+            if (rendered?.callHtml || rendered?.resultHtmlCollapsed || rendered?.resultHtmlExpanded) {
+              // Custom tool with pre-rendered HTML from TUI renderer
+              if (rendered.callHtml) {
+                html += `<div class="tool-header ansi-rendered">${rendered.callHtml}</div>`;
+              } else {
+                html += `<div class="tool-header"><span class="tool-name">${escapeHtml(name)}</span></div>`;
+              }
+
+              if (rendered.resultHtmlCollapsed && rendered.resultHtmlExpanded && rendered.resultHtmlCollapsed !== rendered.resultHtmlExpanded) {
+                // Both collapsed and expanded differ - render expandable section
+                html += `<div class="tool-output expandable ansi-rendered" onclick="if(window.getSelection().toString())return;this.classList.toggle('expanded')">
+                  <div class="output-preview">${rendered.resultHtmlCollapsed}</div>
+                  <div class="output-full">${rendered.resultHtmlExpanded}</div>
+                </div>`;
+              } else if (rendered.resultHtmlExpanded) {
+                // Only expanded exists (or collapsed is identical) - show directly
+                html += `<div class="tool-output ansi-rendered">${rendered.resultHtmlExpanded}</div>`;
+              } else if (result) {
+                // No pre-rendered result HTML - fallback to JSON
+                const output = getResultText();
+                if (output) html += formatExpandableOutput(output, 10);
+              }
+            } else {
+              // Fallback to JSON display (existing behavior)
+              html += `<div class="tool-header"><span class="tool-name">${escapeHtml(name)}</span></div>`;
+              html += `<div class="tool-output"><pre>${escapeHtml(JSON.stringify(args, null, 2))}</pre></div>`;
+              if (result) {
+                const output = getResultText();
+                if (output) html += formatExpandableOutput(output, 10);
+              }
+            }
+          }
+        }
+
+        html += '</div>';
+        return html;
+      }
+
+      /**
+       * Download the session data as a JSONL file.
+       * Reconstructs the original format: header line + entry lines.
+       */
+      window.downloadSessionJson = function() {
+        // Build JSONL content: header first, then all entries
+        const lines = [];
+        if (header) {
+          lines.push(JSON.stringify({ type: 'header', ...header }));
+        }
+        for (const entry of entries) {
+          lines.push(JSON.stringify(entry));
+        }
+        const jsonlContent = lines.join('\n');
+
+        // Create download
+        const blob = new Blob([jsonlContent], { type: 'application/x-ndjson' });
+        const url = URL.createObjectURL(blob);
+        const a = document.createElement('a');
+        a.href = url;
+        a.download = `${header?.id || 'session'}.jsonl`;
+        document.body.appendChild(a);
+        a.click();
+        document.body.removeChild(a);
+        URL.revokeObjectURL(url);
+      }
+
+      /**
+       * Build a shareable URL for a specific message.
+       * URL format: base?gistId&leafId=<leafId>&targetId=<entryId>
+       */
+      function buildShareUrl(entryId) {
+        // Check for injected base URL (used when loaded in iframe via srcdoc)
+        const baseUrlMeta = document.querySelector('meta[name="pi-share-base-url"]');
+        const baseUrl = baseUrlMeta ? baseUrlMeta.content : window.location.href.split('?')[0];
+
+        const url = new URL(window.location.href);
+        // Find the gist ID (first query param without value, e.g., ?abc123)
+        const gistId = Array.from(url.searchParams.keys()).find(k => !url.searchParams.get(k));
+
+        // Build the share URL
+        const params = new URLSearchParams();
+        params.set('leafId', currentLeafId);
+        params.set('targetId', entryId);
+
+        // If we have an injected base URL (iframe context), use it directly
+        if (baseUrlMeta) {
+          return `${baseUrl}&${params.toString()}`;
+        }
+
+        // Otherwise build from current location (direct file access)
+        url.search = gistId ? `?${gistId}&${params.toString()}` : `?${params.toString()}`;
+        return url.toString();
+      }
+
+      /**
+       * Copy text to clipboard with visual feedback.
+       * Uses navigator.clipboard with fallback to execCommand for HTTP contexts.
+       */
+      async function copyToClipboard(text, button) {
+        let success = false;
+        try {
+          if (navigator.clipboard && navigator.clipboard.writeText) {
+            await navigator.clipboard.writeText(text);
+            success = true;
+          }
+        } catch (err) {
+          // Clipboard API failed, try fallback
+        }
+
+        // Fallback for HTTP or when Clipboard API is unavailable
+        if (!success) {
+          try {
+            const textarea = document.createElement('textarea');
+            textarea.value = text;
+            textarea.style.position = 'fixed';
+            textarea.style.opacity = '0';
+            document.body.appendChild(textarea);
+            textarea.select();
+            success = document.execCommand('copy');
+            document.body.removeChild(textarea);
+          } catch (err) {
+            console.error('Failed to copy:', err);
+          }
+        }
+
+        if (success && button) {
+          const originalHtml = button.innerHTML;
+          button.innerHTML = '✓';
+          button.classList.add('copied');
+          setTimeout(() => {
+            button.innerHTML = originalHtml;
+            button.classList.remove('copied');
+          }, 1500);
+        }
+      }
+
+      /**
+       * Render the copy-link button HTML for a message.
+       */
+      function renderCopyLinkButton(entryId) {
+        return `<button class="copy-link-btn" data-entry-id="${escapeHtml(entryId)}" title="Copy link to this message">
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"/>
+            <path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"/>
+          </svg>
+        </button>`;
+      }
+
+      function renderEntry(entry) {
+        const ts = formatTimestamp(entry.timestamp);
+        const tsHtml = ts ? `<div class="message-timestamp">${ts}</div>` : '';
+        const entryDomId = `entry-${escapeHtml(entry.id)}`;
+        const copyBtnHtml = renderCopyLinkButton(entry.id);
+
+        if (entry.type === 'message') {
+          const msg = entry.message;
+
+          if (msg.role === 'user') {
+            const content = msg.content;
+            const text = typeof content === 'string' ? content :
+              content.filter(c => c.type === 'text').map(c => c.text).join('\n');
+            const skillBlock = parseSkillBlock(text);
+
+            if (skillBlock) {
+              // Collect images from content array
+              const images = Array.isArray(content) ? content.filter(c => c.type === 'image') : [];
+              const hasUserContent = skillBlock.userMessage || images.length > 0;
+              let html = `<div class="skill-user-entry" id="${entryDomId}">${copyBtnHtml}${tsHtml}`;
+
+              // Skill invocation (collapsed by default, click to expand)
+              html += `<div class="skill-invocation" onclick="if(window.getSelection().toString())return;this.classList.toggle('expanded')">
+                <div class="skill-invocation-label">[skill] ${escapeHtml(skillBlock.name)}</div>
+                <div class="skill-invocation-collapsed">${escapeHtml(skillBlock.name)} (click to expand)</div>
+                <div class="skill-invocation-content markdown-content">${safeMarkedParse(skillBlock.content)}</div>
+              </div>`;
+
+              // User message (separate block if present)
+              if (hasUserContent) {
+                html += '<div class="user-message">';
+                if (images.length > 0) {
+                  html += '<div class="message-images">';
+                  for (const img of images) {
+                    html += `<img src="data:${escapeHtml(img.mimeType || 'image/png')};base64,${escapeHtml(img.data || '')}" class="message-image" />`;
+                  }
+                  html += '</div>';
+                }
+                if (skillBlock.userMessage) {
+                  html += `<div class="markdown-content">${safeMarkedParse(skillBlock.userMessage)}</div>`;
+                }
+                html += '</div>';
+              }
+
+              html += '</div>';
+              return html;
+            }
+
+            // No skill block - normal user message
+            let html = `<div class="user-message" id="${entryDomId}">${copyBtnHtml}${tsHtml}`;
+
+            if (Array.isArray(content)) {
+              const images = content.filter(c => c.type === 'image');
+              if (images.length > 0) {
+                html += '<div class="message-images">';
+                for (const img of images) {
+                  html += `<img src="data:${escapeHtml(img.mimeType || 'image/png')};base64,${escapeHtml(img.data || '')}" class="message-image" />`;
+                }
+                html += '</div>';
+              }
+            }
+
+            if (text.trim()) {
+              html += `<div class="markdown-content">${safeMarkedParse(text)}</div>`;
+            }
+            html += '</div>';
+            return html;
+          }
+
+          if (msg.role === 'assistant') {
+            let html = `<div class="assistant-message" id="${entryDomId}">${copyBtnHtml}${tsHtml}`;
+
+            for (const block of msg.content) {
+              if (block.type === 'text' && block.text.trim()) {
+                html += `<div class="assistant-text markdown-content">${safeMarkedParse(block.text)}</div>`;
+              } else if (block.type === 'thinking' && block.thinking.trim()) {
+                html += `<div class="thinking-block">
+                  <div class="thinking-text">${escapeHtml(block.thinking)}</div>
+                  <div class="thinking-collapsed">Thinking ...</div>
+                </div>`;
+              }
+            }
+
+            for (const block of msg.content) {
+              if (block.type === 'toolCall') {
+                html += renderToolCall(block);
+              }
+            }
+
+            if (msg.stopReason === 'aborted') {
+              html += '<div class="error-text">Aborted</div>';
+            } else if (msg.stopReason === 'error') {
+              html += `<div class="error-text">Error: ${escapeHtml(msg.errorMessage || 'Unknown error')}</div>`;
+            }
+
+            html += '</div>';
+            return html;
+          }
+
+          if (msg.role === 'bashExecution') {
+            const isError = msg.cancelled || (msg.exitCode !== 0 && msg.exitCode !== null);
+            let html = `<div class="tool-execution ${isError ? 'error' : 'success'}" id="${entryDomId}">${tsHtml}`;
+            html += `<div class="tool-command">$ ${escapeHtml(msg.command)}</div>`;
+            if (msg.output) html += formatExpandableOutput(msg.output, 10);
+            if (msg.cancelled) {
+              html += '<div style="color: var(--warning)">(cancelled)</div>';
+            } else if (msg.exitCode !== 0 && msg.exitCode !== null) {
+              html += `<div style="color: var(--error)">(exit ${msg.exitCode})</div>`;
+            }
+            html += '</div>';
+            return html;
+          }
+
+          if (msg.role === 'toolResult') return '';
+        }
+
+        if (entry.type === 'model_change') {
+          return `<div class="model-change" id="${entryDomId}">${tsHtml}Switched to model: <span class="model-name">${escapeHtml(entry.provider)}/${escapeHtml(entry.modelId)}</span></div>`;
+        }
+
+        if (entry.type === 'compaction') {
+          return `<div class="compaction" id="${entryDomId}" onclick="if(window.getSelection().toString())return;this.classList.toggle('expanded')">
+            <div class="compaction-label">[compaction]</div>
+            <div class="compaction-collapsed">Compacted from ${entry.tokensBefore.toLocaleString()} tokens</div>
+            <div class="compaction-content"><strong>Compacted from ${entry.tokensBefore.toLocaleString()} tokens</strong>\n\n${escapeHtml(entry.summary)}</div>
+          </div>`;
+        }
+
+        if (entry.type === 'branch_summary') {
+          return `<div class="branch-summary" id="${entryDomId}">${tsHtml}
+            <div class="branch-summary-header">Branch Summary</div>
+            <div class="markdown-content">${safeMarkedParse(entry.summary)}</div>
+          </div>`;
+        }
+
+        if (entry.type === 'custom_message' && entry.display) {
+          return `<div class="hook-message" id="${entryDomId}">${tsHtml}
+            <div class="hook-type">[${escapeHtml(entry.customType)}]</div>
+            <div class="markdown-content">${safeMarkedParse(typeof entry.content === 'string' ? entry.content : JSON.stringify(entry.content))}</div>
+          </div>`;
+        }
+
+        return '';
+      }
+
+      // ============================================================
+      // HEADER / STATS
+      // ============================================================
+
+      function computeStats(entryList) {
+        let userMessages = 0, assistantMessages = 0, toolResults = 0;
+        let customMessages = 0, compactions = 0, branchSummaries = 0, toolCalls = 0;
+        const tokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+        const cost = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+        const models = new Set();
+
+        for (const entry of entryList) {
+          if (entry.type === 'message') {
+            const msg = entry.message;
+            if (msg.role === 'user') userMessages++;
+            if (msg.role === 'assistant') {
+              assistantMessages++;
+              if (msg.model) models.add(msg.provider ? `${msg.provider}/${msg.model}` : msg.model);
+              if (msg.usage) {
+                tokens.input += msg.usage.input || 0;
+                tokens.output += msg.usage.output || 0;
+                tokens.cacheRead += msg.usage.cacheRead || 0;
+                tokens.cacheWrite += msg.usage.cacheWrite || 0;
+                if (msg.usage.cost) {
+                  cost.input += msg.usage.cost.input || 0;
+                  cost.output += msg.usage.cost.output || 0;
+                  cost.cacheRead += msg.usage.cost.cacheRead || 0;
+                  cost.cacheWrite += msg.usage.cost.cacheWrite || 0;
+                }
+              }
+              toolCalls += msg.content.filter(c => c.type === 'toolCall').length;
+            }
+            if (msg.role === 'toolResult') toolResults++;
+          } else if (entry.type === 'compaction') {
+            compactions++;
+          } else if (entry.type === 'branch_summary') {
+            branchSummaries++;
+          } else if (entry.type === 'custom_message') {
+            customMessages++;
+          }
+        }
+
+        return { userMessages, assistantMessages, toolResults, customMessages, compactions, branchSummaries, toolCalls, tokens, cost, models: Array.from(models) };
+      }
+
+      const globalStats = computeStats(entries);
+
+      function renderHeader() {
+        const totalCost = globalStats.cost.input + globalStats.cost.output + globalStats.cost.cacheRead + globalStats.cost.cacheWrite;
+
+        const tokenParts = [];
+        if (globalStats.tokens.input) tokenParts.push(`↑${formatTokens(globalStats.tokens.input)}`);
+        if (globalStats.tokens.output) tokenParts.push(`↓${formatTokens(globalStats.tokens.output)}`);
+        if (globalStats.tokens.cacheRead) tokenParts.push(`R${formatTokens(globalStats.tokens.cacheRead)}`);
+        if (globalStats.tokens.cacheWrite) tokenParts.push(`W${formatTokens(globalStats.tokens.cacheWrite)}`);
+
+        const msgParts = [];
+        if (globalStats.userMessages) msgParts.push(`${globalStats.userMessages} user`);
+        if (globalStats.assistantMessages) msgParts.push(`${globalStats.assistantMessages} assistant`);
+        if (globalStats.toolResults) msgParts.push(`${globalStats.toolResults} tool results`);
+        if (globalStats.customMessages) msgParts.push(`${globalStats.customMessages} custom`);
+        if (globalStats.compactions) msgParts.push(`${globalStats.compactions} compactions`);
+        if (globalStats.branchSummaries) msgParts.push(`${globalStats.branchSummaries} branch summaries`);
+
+        let html = `
+          <div class="header">
+            <h1>Session: ${escapeHtml(header?.id || 'unknown')}</h1>
+            <div class="help-bar">
+              <span class="help-hint">T toggle thinking · O toggle tools</span>
+              <div class="help-actions">
+                <button type="button" class="header-toggle-btn" data-action="toggle-thinking" title="Toggle thinking (T)">Toggle thinking</button>
+                <button type="button" class="header-toggle-btn" data-action="toggle-tools" title="Toggle tools (O)">Toggle tools</button>
+                <button type="button" class="download-json-btn" onclick="downloadSessionJson()" title="Download session as JSONL">↓ JSONL</button>
+              </div>
+            </div>
+            <div class="header-info">
+              <div class="info-item"><span class="info-label">Date:</span><span class="info-value">${header?.timestamp ? new Date(header.timestamp).toLocaleString() : 'unknown'}</span></div>
+              <div class="info-item"><span class="info-label">Models:</span><span class="info-value">${escapeHtml(globalStats.models.join(', ') || 'unknown')}</span></div>
+              <div class="info-item"><span class="info-label">Messages:</span><span class="info-value">${msgParts.join(', ') || '0'}</span></div>
+              <div class="info-item"><span class="info-label">Tool Calls:</span><span class="info-value">${globalStats.toolCalls}</span></div>
+              <div class="info-item"><span class="info-label">Tokens:</span><span class="info-value">${tokenParts.join(' ') || '0'}</span></div>
+              <div class="info-item"><span class="info-label">Cost:</span><span class="info-value">$${totalCost.toFixed(3)}</span></div>
+            </div>
+          </div>`;
+
+        // Render system prompt (user's base prompt, applies to all providers)
+        if (systemPrompt) {
+          const lines = systemPrompt.split('\n');
+          const previewLines = 10;
+          if (lines.length > previewLines) {
+            const preview = lines.slice(0, previewLines).join('\n');
+            const remaining = lines.length - previewLines;
+            html += `<div class="system-prompt expandable" onclick="if(window.getSelection().toString())return;this.classList.toggle('expanded')">
+              <div class="system-prompt-header">System Prompt</div>
+              <div class="system-prompt-preview">${escapeHtml(preview)}</div>
+              <div class="system-prompt-expand-hint">... (${remaining} more lines, click to expand)</div>
+              <div class="system-prompt-full">${escapeHtml(systemPrompt)}</div>
+            </div>`;
+          } else {
+            html += `<div class="system-prompt">
+              <div class="system-prompt-header">System Prompt</div>
+              <div class="system-prompt-full" style="display: block">${escapeHtml(systemPrompt)}</div>
+            </div>`;
+          }
+        }
+
+        if (tools && tools.length > 0) {
+          html += `<div class="tools-list">
+            <div class="tools-header">Available Tools</div>
+            <div class="tools-content">
+              ${tools.map(t => {
+                const hasParams = t.parameters && typeof t.parameters === 'object' && t.parameters.properties && Object.keys(t.parameters.properties).length > 0;
+                if (!hasParams) {
+                  return `<div class="tool-item"><span class="tool-item-name">${escapeHtml(t.name)}</span> - <span class="tool-item-desc">${escapeHtml(t.description)}</span></div>`;
+                }
+                const params = t.parameters;
+                const properties = params.properties;
+                const required = params.required || [];
+                let paramsHtml = '';
+                for (const [name, prop] of Object.entries(properties)) {
+                  const isRequired = required.includes(name);
+                  const typeStr = prop.type || 'any';
+                  const reqLabel = isRequired ? '<span class="tool-param-required">required</span>' : '<span class="tool-param-optional">optional</span>';
+                  paramsHtml += `<div class="tool-param"><span class="tool-param-name">${escapeHtml(name)}</span> <span class="tool-param-type">${escapeHtml(typeStr)}</span> ${reqLabel}`;
+                  if (prop.description) {
+                    paramsHtml += `<div class="tool-param-desc">${escapeHtml(prop.description)}</div>`;
+                  }
+                  paramsHtml += `</div>`;
+                }
+                return `<div class="tool-item" onclick="if(window.getSelection().toString())return;this.classList.toggle('params-expanded')"><span class="tool-item-name">${escapeHtml(t.name)}</span> - <span class="tool-item-desc">${escapeHtml(t.description)}</span> <span class="tool-params-hint"></span><div class="tool-params-content">${paramsHtml}</div></div>`;
+              }).join('')}
+            </div>
+          </div>`;
+        }
+
+        return html;
+      }
+
+      // ============================================================
+      // NAVIGATION
+      // ============================================================
+
+      // Cache for rendered entry DOM nodes
+      const entryCache = new Map();
+
+      function getScrollTargetElementId(entryId) {
+        const entry = byId.get(entryId);
+        if (entry?.type === 'message' && entry.message.role === 'toolResult' && entry.message.toolCallId) {
+          // getElementById() matches the parsed DOM id attribute, whose HTML entities
+          // were already resolved from the escaped id rendered by renderToolCall().
+          return `tool-call-${entry.message.toolCallId}`;
+        }
+        return `entry-${entryId}`;
+      }
+
+      function renderEntryToNode(entry) {
+        // Check cache first
+        if (entryCache.has(entry.id)) {
+          return entryCache.get(entry.id).cloneNode(true);
+        }
+
+        // Render to HTML string, then parse to node
+        const html = renderEntry(entry);
+        if (!html) return null;
+
+        const template = document.createElement('template');
+        template.innerHTML = html;
+        const node = template.content.firstElementChild;
+
+        // Cache the node
+        if (node) {
+          entryCache.set(entry.id, node.cloneNode(true));
+        }
+        return node;
+      }
+
+      function navigateTo(targetId, scrollMode = 'target', scrollToEntryId = null) {
+        currentLeafId = targetId;
+        currentTargetId = scrollToEntryId || targetId;
+        const path = getPath(targetId);
+
+        renderTree();
+
+        document.getElementById('header-container').innerHTML = renderHeader();
+        attachHeaderHandlers();
+
+        // Build messages using cached DOM nodes
+        const messagesEl = document.getElementById('messages');
+        const fragment = document.createDocumentFragment();
+
+        for (const entry of path) {
+          const node = renderEntryToNode(entry);
+          if (node) {
+            fragment.appendChild(node);
+          }
+        }
+
+        messagesEl.innerHTML = '';
+        messagesEl.appendChild(fragment);
+
+        // Attach click handlers for copy-link buttons
+        messagesEl.querySelectorAll('.copy-link-btn').forEach(btn => {
+          btn.addEventListener('click', (e) => {
+            e.stopPropagation();
+            const entryId = btn.dataset.entryId;
+            const shareUrl = buildShareUrl(entryId);
+            copyToClipboard(shareUrl, btn);
+          });
+        });
+
+        // Use setTimeout(0) to ensure DOM is fully laid out before scrolling
+        setTimeout(() => {
+          const content = document.getElementById('content');
+          if (scrollMode === 'bottom') {
+            content.scrollTop = content.scrollHeight;
+          } else if (scrollMode === 'target') {
+            // If scrollToEntryId is provided, scroll to that specific entry.
+            // Tool result entries are rendered inside their assistant tool-call block,
+            // so route them to the visible tool-call element instead.
+            const scrollTargetId = scrollToEntryId || targetId;
+            const targetEl = document.getElementById(getScrollTargetElementId(scrollTargetId)) ||
+              document.getElementById(`entry-${scrollTargetId}`);
+            if (targetEl) {
+              targetEl.scrollIntoView({ block: 'center' });
+              // Briefly highlight the target message
+              if (scrollToEntryId) {
+                targetEl.classList.add('highlight');
+                setTimeout(() => targetEl.classList.remove('highlight'), 2000);
+              }
+            }
+          }
+        }, 0);
+      }
+
+      // ============================================================
+      // INITIALIZATION
+      // ============================================================
+
+      // Configure marked with syntax highlighting and TUI-compatible HTML handling
+      const strictStrikethroughRegex = /^(~~)(?=[^\s~])((?:\\.|[^\\])*?(?:\\.|[^\s~\\]))\1(?=[^~]|$)/;
+
+      marked.use({
+        breaks: true,
+        gfm: true,
+        tokenizer: {
+          // Treat HTML-like input as plain text so tags are shown verbatim,
+          // matching the TUI markdown renderer.
+          html() {
+            return undefined;
+          },
+          tag() {
+            return undefined;
+          },
+          del(src) {
+            const match = strictStrikethroughRegex.exec(src);
+            if (!match) return undefined;
+            return {
+              type: 'del',
+              raw: match[0],
+              text: match[2],
+              tokens: this.lexer.inlineTokens(match[2])
+            };
+          }
+        },
+        renderer: {
+          // Sanitize link URLs with a scheme allow-list. Browsers strip C0
+          // controls from schemes, so strip them before checking and emitting.
+          link(token) {
+            const href = sanitizeMarkdownUrl(token.href);
+            if (href === null) {
+              return this.parser.parseInline(token.tokens);
+            }
+            let out = '<a href="' + escapeHtml(href) + '"';
+            if (token.title) {
+              out += ' title="' + escapeHtml(token.title) + '"';
+            }
+            out += '>' + this.parser.parseInline(token.tokens) + '</a>';
+            return out;
+          },
+          // Sanitize image src URLs with the same scheme allow-list.
+          image(token) {
+            const href = sanitizeMarkdownUrl(token.href);
+            if (href === null) {
+              return escapeHtml(token.text || '');
+            }
+            let out = '<img src="' + escapeHtml(href) + '" alt="' + escapeHtml(token.text || '') + '"';
+            if (token.title) {
+              out += ' title="' + escapeHtml(token.title) + '"';
+            }
+            out += '>';
+            return out;
+          },
+          // Code blocks: syntax highlight, no HTML escaping
+          code(token) {
+            const code = token.text;
+            const lang = token.lang;
+            let highlighted;
+            if (lang && hljs.getLanguage(lang)) {
+              try {
+                highlighted = hljs.highlight(code, { language: lang }).value;
+              } catch {
+                highlighted = escapeHtml(code);
+              }
+            } else {
+              // Auto-detect language if not specified
+              try {
+                highlighted = hljs.highlightAuto(code).value;
+              } catch {
+                highlighted = escapeHtml(code);
+              }
+            }
+            return `<pre><code class="hljs">${highlighted}</code></pre>`;
+          },
+          // Inline code: escape HTML
+          codespan(token) {
+            return `<code>${escapeHtml(token.text)}</code>`;
+          }
+        }
+      });
+
+      // Simple marked parse (escaping handled in renderers)
+      function safeMarkedParse(text) {
+        return marked.parse(text);
+      }
+
+      // Search input
+      const searchInput = document.getElementById('tree-search');
+      searchInput.addEventListener('input', (e) => {
+        searchQuery = e.target.value;
+        forceTreeRerender();
+      });
+
+      // Filter buttons
+      document.querySelectorAll('.filter-btn').forEach(btn => {
+        btn.addEventListener('click', () => {
+          document.querySelectorAll('.filter-btn').forEach(b => b.classList.remove('active'));
+          btn.classList.add('active');
+          filterMode = btn.dataset.filter;
+          forceTreeRerender();
+        });
+      });
+
+      // Sidebar toggle
+      const sidebar = document.getElementById('sidebar');
+      const overlay = document.getElementById('sidebar-overlay');
+      const hamburger = document.getElementById('hamburger');
+      const sidebarResizer = document.getElementById('sidebar-resizer');
+      const SIDEBAR_WIDTH_STORAGE_KEY = 'pi-share:v1:sidebar-width';
+      const MIN_CONTENT_WIDTH = 320;
+
+      function isMobileLayout() {
+        return window.matchMedia('(max-width: 900px)').matches;
+      }
+
+      function getSidebarBounds() {
+        const rootStyles = getComputedStyle(document.documentElement);
+        const minWidth = parseFloat(rootStyles.getPropertyValue('--sidebar-min-width')) || 240;
+        const maxWidth = parseFloat(rootStyles.getPropertyValue('--sidebar-max-width')) || 720;
+        const viewportMaxWidth = window.innerWidth - MIN_CONTENT_WIDTH;
+        return {
+          minWidth,
+          maxWidth: Math.max(minWidth, Math.min(maxWidth, viewportMaxWidth))
+        };
+      }
+
+      function clampSidebarWidth(width) {
+        const { minWidth, maxWidth } = getSidebarBounds();
+        return Math.max(minWidth, Math.min(maxWidth, width));
+      }
+
+      function applySidebarWidth(width) {
+        document.documentElement.style.setProperty('--sidebar-width', `${Math.round(clampSidebarWidth(width))}px`);
+      }
+
+      function loadSidebarWidth() {
+        try {
+          const raw = localStorage.getItem(SIDEBAR_WIDTH_STORAGE_KEY);
+          if (raw === null) return null;
+          const width = Number(raw);
+          return Number.isFinite(width) ? width : null;
+        } catch {
+          return null;
+        }
+      }
+
+      function saveSidebarWidth(width) {
+        try {
+          localStorage.setItem(SIDEBAR_WIDTH_STORAGE_KEY, String(Math.round(clampSidebarWidth(width))));
+        } catch {
+          // Ignore storage failures (e.g. private browsing restrictions)
+        }
+      }
+
+      function setupSidebarResize() {
+        const savedWidth = loadSidebarWidth();
+        if (savedWidth !== null) {
+          applySidebarWidth(savedWidth);
+        }
+
+        if (!sidebarResizer) return;
+
+        let cleanupDrag = null;
+
+        const stopDrag = (pointerId) => {
+          if (cleanupDrag) {
+            cleanupDrag(pointerId);
+            cleanupDrag = null;
+          }
+        };
+
+        sidebarResizer.addEventListener('pointerdown', (e) => {
+          if (isMobileLayout()) return;
+
+          e.preventDefault();
+          const startX = e.clientX;
+          const startWidth = sidebar.getBoundingClientRect().width;
+          document.body.classList.add('sidebar-resizing');
+          sidebarResizer.setPointerCapture?.(e.pointerId);
+
+          const onPointerMove = (event) => {
+            applySidebarWidth(startWidth + (event.clientX - startX));
+          };
+
+          cleanupDrag = (pointerIdToRelease) => {
+            document.body.classList.remove('sidebar-resizing');
+            sidebarResizer.releasePointerCapture?.(pointerIdToRelease);
+            window.removeEventListener('pointermove', onPointerMove);
+            window.removeEventListener('pointerup', onPointerUp);
+            window.removeEventListener('pointercancel', onPointerCancel);
+            saveSidebarWidth(sidebar.getBoundingClientRect().width);
+          };
+
+          const onPointerUp = (event) => stopDrag(event.pointerId);
+          const onPointerCancel = (event) => stopDrag(event.pointerId);
+
+          window.addEventListener('pointermove', onPointerMove);
+          window.addEventListener('pointerup', onPointerUp);
+          window.addEventListener('pointercancel', onPointerCancel);
+        });
+
+        sidebarResizer.addEventListener('dblclick', () => {
+          if (isMobileLayout()) return;
+          applySidebarWidth(400);
+          saveSidebarWidth(400);
+        });
+
+        window.addEventListener('resize', () => {
+          if (isMobileLayout()) return;
+          applySidebarWidth(sidebar.getBoundingClientRect().width);
+        });
+      }
+
+      setupSidebarResize();
+
+      hamburger.addEventListener('click', () => {
+        sidebar.classList.add('open');
+        overlay.classList.add('open');
+        hamburger.style.display = 'none';
+      });
+
+      const closeSidebar = () => {
+        sidebar.classList.remove('open');
+        overlay.classList.remove('open');
+        hamburger.style.display = '';
+      };
+
+      overlay.addEventListener('click', closeSidebar);
+      document.getElementById('sidebar-close').addEventListener('click', closeSidebar);
+
+      // Toggle states
+      let thinkingExpanded = true;
+      let toolOutputsExpanded = false;
+
+      const toggleThinking = () => {
+        thinkingExpanded = !thinkingExpanded;
+        document.querySelectorAll('.thinking-text').forEach(el => {
+          el.style.display = thinkingExpanded ? '' : 'none';
+        });
+        document.querySelectorAll('.thinking-collapsed').forEach(el => {
+          el.style.display = thinkingExpanded ? 'none' : 'block';
+        });
+      };
+
+      const toggleToolOutputs = () => {
+        toolOutputsExpanded = !toolOutputsExpanded;
+        document.querySelectorAll('.tool-output.expandable').forEach(el => {
+          el.classList.toggle('expanded', toolOutputsExpanded);
+        });
+        document.querySelectorAll('.compaction').forEach(el => {
+          el.classList.toggle('expanded', toolOutputsExpanded);
+        });
+        document.querySelectorAll('.skill-invocation').forEach(el => {
+          el.classList.toggle('expanded', toolOutputsExpanded);
+        });
+      };
+
+      const attachHeaderHandlers = () => {
+        document.querySelector('[data-action="toggle-thinking"]')?.addEventListener('click', toggleThinking);
+        document.querySelector('[data-action="toggle-tools"]')?.addEventListener('click', toggleToolOutputs);
+      };
+
+      const isEditableTarget = (element) => {
+        if (!element) return false;
+        const tagName = element.tagName;
+        if (tagName === 'INPUT' || tagName === 'TEXTAREA' || tagName === 'SELECT' || tagName === 'BUTTON') {
+          return true;
+        }
+        return element.isContentEditable || Boolean(element.closest?.('[contenteditable="true"]'));
+      };
+
+      // Keyboard shortcuts
+      document.addEventListener('keydown', (e) => {
+        if (e.key === 'Escape') {
+          searchInput.value = '';
+          searchQuery = '';
+          navigateTo(leafId, 'bottom');
+        }
+
+        if (isEditableTarget(document.activeElement)) {
+          return;
+        }
+
+        const key = e.key.toLowerCase();
+        if (key === 't') {
+          e.preventDefault();
+          toggleThinking();
+        } else if (key === 'o') {
+          e.preventDefault();
+          toggleToolOutputs();
+        }
+      });
+
+      // Initial render
+      // If URL has targetId, scroll to that specific message; otherwise stay at top
+      if (leafId) {
+        if (urlTargetId && byId.has(urlTargetId)) {
+          // Deep link: navigate to leaf and scroll to target message
+          navigateTo(leafId, 'target', urlTargetId);
+        } else {
+          navigateTo(leafId, 'none');
+        }
+      } else if (entries.length > 0) {
+        // Fallback: use last entry if no leafId
+        navigateTo(entries[entries.length - 1].id, 'none');
+      }
+    })();

packages/coding-agent/src/core/export-html/tool-renderer.ts

@@ -0,0 +1,172 @@
+/**
+ * Tool HTML renderer for custom tools in HTML export.
+ *
+ * Renders custom tool calls and results to HTML by invoking their TUI renderers
+ * and converting the ANSI output to HTML.
+ */
+
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import type { Component } from "@earendil-works/pi-tui";
+import type { Theme } from "../../modes/interactive/theme/theme.ts";
+import type { ToolDefinition, ToolRenderContext } from "../extensions/types.ts";
+import { ansiLinesToHtml } from "./ansi-to-html.ts";
+
+export interface ToolHtmlRendererDeps {
+	/** Function to look up tool definition by name */
+	getToolDefinition: (name: string) => ToolDefinition | undefined;
+	/** Theme for styling */
+	theme: Theme;
+	/** Working directory for render context */
+	cwd: string;
+	/** Terminal width for rendering (default: 100) */
+	width?: number;
+}
+
+export interface ToolHtmlRenderer {
+	/** Render a tool call to HTML. Returns undefined if tool has no custom renderer. */
+	renderCall(toolCallId: string, toolName: string, args: unknown): string | undefined;
+	/** Render a tool result to collapsed/expanded HTML. Returns undefined if tool has no custom renderer. */
+	renderResult(
+		toolCallId: string,
+		toolName: string,
+		result: Array<{ type: string; text?: string; data?: string; mimeType?: string }>,
+		details: unknown,
+		isError: boolean,
+	): { collapsed?: string; expanded?: string } | undefined;
+}
+
+/**
+ * Create a tool HTML renderer.
+ *
+ * The renderer looks up tool definitions and invokes their renderCall/renderResult
+ * methods, converting the resulting TUI Component output (ANSI) to HTML.
+ */
+const ANSI_ESCAPE_REGEX = /\x1b\[[\d;]*m/g;
+
+function isBlankRenderedLine(line: string): boolean {
+	return line.replace(ANSI_ESCAPE_REGEX, "").trim().length === 0;
+}
+
+function trimRenderedResultLines(lines: string[]): string[] {
+	let start = 0;
+	let end = lines.length;
+	while (start < end && isBlankRenderedLine(lines[start])) start++;
+	while (end > start && isBlankRenderedLine(lines[end - 1])) end--;
+	return lines.slice(start, end);
+}
+
+export function createToolHtmlRenderer(deps: ToolHtmlRendererDeps): ToolHtmlRenderer {
+	const { getToolDefinition, theme, cwd, width = 100 } = deps;
+
+	const renderedCallComponents = new Map<string, Component>();
+	const renderedResultComponents = new Map<string, Component>();
+	const renderedStates = new Map<string, any>();
+	const renderedArgs = new Map<string, unknown>();
+
+	const getState = (toolCallId: string): any => {
+		let state = renderedStates.get(toolCallId);
+		if (!state) {
+			state = {};
+			renderedStates.set(toolCallId, state);
+		}
+		return state;
+	};
+
+	const createRenderContext = (
+		toolCallId: string,
+		lastComponent: Component | undefined,
+		expanded: boolean,
+		isPartial: boolean,
+		isError: boolean,
+	): ToolRenderContext => {
+		return {
+			args: renderedArgs.get(toolCallId),
+			toolCallId,
+			invalidate: () => {},
+			lastComponent,
+			state: getState(toolCallId),
+			cwd,
+			executionStarted: true,
+			argsComplete: true,
+			isPartial,
+			expanded,
+			showImages: false,
+			isError,
+		};
+	};
+
+	return {
+		renderCall(toolCallId: string, toolName: string, args: unknown): string | undefined {
+			try {
+				renderedArgs.set(toolCallId, args);
+				const toolDef = getToolDefinition(toolName);
+				if (!toolDef?.renderCall) {
+					return undefined;
+				}
+
+				const component = toolDef.renderCall(
+					args,
+					theme,
+					createRenderContext(toolCallId, renderedCallComponents.get(toolCallId), false, true, false),
+				);
+				renderedCallComponents.set(toolCallId, component);
+				const lines = component.render(width);
+				return ansiLinesToHtml(lines);
+			} catch {
+				// On error, return undefined so HTML export can fall back to structured result rendering
+				return undefined;
+			}
+		},
+
+		renderResult(
+			toolCallId: string,
+			toolName: string,
+			result: Array<{ type: string; text?: string; data?: string; mimeType?: string }>,
+			details: unknown,
+			isError: boolean,
+		): { collapsed?: string; expanded?: string } | undefined {
+			try {
+				const toolDef = getToolDefinition(toolName);
+				if (!toolDef?.renderResult) {
+					return undefined;
+				}
+
+				// Build AgentToolResult from content array
+				// Cast content since session storage uses generic object types
+				const agentToolResult = {
+					content: result as (TextContent | ImageContent)[],
+					details,
+					isError,
+				};
+
+				// Render collapsed
+				const collapsedComponent = toolDef.renderResult(
+					agentToolResult,
+					{ expanded: false, isPartial: false },
+					theme,
+					createRenderContext(toolCallId, renderedResultComponents.get(toolCallId), false, false, isError),
+				);
+				renderedResultComponents.set(toolCallId, collapsedComponent);
+				const collapsed = ansiLinesToHtml(trimRenderedResultLines(collapsedComponent.render(width)));
+
+				// Render expanded
+				const expandedComponent = toolDef.renderResult(
+					agentToolResult,
+					{ expanded: true, isPartial: false },
+					theme,
+					createRenderContext(toolCallId, renderedResultComponents.get(toolCallId), true, false, isError),
+				);
+				renderedResultComponents.set(toolCallId, expandedComponent);
+				const expanded = ansiLinesToHtml(trimRenderedResultLines(expandedComponent.render(width)));
+
+				return {
+					...(collapsed && collapsed !== expanded ? { collapsed } : {}),
+					expanded,
+				};
+			} catch {
+				// On error, return undefined so HTML export can fall back to structured result rendering
+				return undefined;
+			}
+		},
+	};
+}

packages/coding-agent/src/core/export-html/vendor/marked.min.js

@@ -0,0 +1,78 @@
+/**
+ * marked v18.0.5 - a markdown parser
+ * Copyright (c) 2018-2026, MarkedJS. (MIT License)
+ * Copyright (c) 2011-2018, Christopher Jeffrey. (MIT License)
+ * https://github.com/markedjs/marked
+ */
+
+/**
+ * DO NOT EDIT THIS FILE
+ * The code in this file is generated from files in ./src/
+ */
+(function(g,f){if(typeof exports=="object"&&typeof module<"u"){module.exports=f()}else if("function"==typeof define && define.amd){define("marked",f)}else {g["marked"]=f()}}(typeof globalThis < "u" ? globalThis : typeof self < "u" ? self : this,function(){var exports={};var __exports=exports;var module={exports};
+"use strict";var N=Object.defineProperty;var Oe=Object.getOwnPropertyDescriptor;var we=Object.getOwnPropertyNames;var ye=Object.prototype.hasOwnProperty;var Pe=(l,e)=>{for(var t in e)N(l,t,{get:e[t],enumerable:!0})},Se=(l,e,t,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let s of we(e))!ye.call(l,s)&&s!==t&&N(l,s,{get:()=>e[s],enumerable:!(n=Oe(e,s))||n.enumerable});return l};var $e=l=>Se(N({},"__esModule",{value:!0}),l);var Rt={};Pe(Rt,{Hooks:()=>P,Lexer:()=>x,Marked:()=>C,Parser:()=>b,Renderer:()=>y,TextRenderer:()=>S,Tokenizer:()=>w,defaults:()=>T,getDefaults:()=>_,lexer:()=>bt,marked:()=>g,options:()=>ht,parse:()=>mt,parseInline:()=>ft,parser:()=>xt,setOptions:()=>kt,use:()=>dt,walkTokens:()=>gt});module.exports=$e(Rt);function _(){return{async:!1,breaks:!1,extensions:null,gfm:!0,hooks:null,pedantic:!1,renderer:null,silent:!1,tokenizer:null,walkTokens:null}}var T=_();function Q(l){T=l}var z={exec:()=>null};function E(l){let e=[];return t=>{let n=Math.max(0,Math.min(3,t-1)),s=e[n];return s||(s=l(n),e[n]=s),s}}function d(l,e=""){let t=typeof l=="string"?l:l.source,n={replace:(s,r)=>{let i=typeof r=="string"?r:r.source;return i=i.replace(m.caret,"$1"),t=t.replace(s,i),n},getRegex:()=>new RegExp(t,e)};return n}var Le=((l="")=>{try{return!!new RegExp("(?<=1)(?<!1)"+l)}catch{return!1}})(),m={codeRemoveIndent:/^(?: {1,4}| {0,3}\t)/gm,outputLinkReplace:/\\([\[\]])/g,indentCodeCompensation:/^(\s+)(?:```)/,beginningSpace:/^\s+/,endingHash:/#$/,startingSpaceChar:/^ /,endingSpaceChar:/ $/,nonSpaceChar:/[^ ]/,newLineCharGlobal:/\n/g,tabCharGlobal:/\t/g,multipleSpaceGlobal:/\s+/g,blankLine:/^[ \t]*$/,doubleBlankLine:/\n[ \t]*\n[ \t]*$/,blockquoteStart:/^ {0,3}>/,blockquoteSetextReplace:/\n {0,3}((?:=+|-+) *)(?=\n|$)/g,blockquoteSetextReplace2:/^ {0,3}>[ \t]?/gm,listReplaceNesting:/^ {1,4}(?=( {4})*[^ ])/g,listIsTask:/^\[[ xX]\] +\S/,listReplaceTask:/^\[[ xX]\] +/,listTaskCheckbox:/\[[ xX]\]/,anyLine:/\n.*\n/,hrefBrackets:/^<(.*)>$/,tableDelimiter:/[:|]/,tableAlignChars:/^\||\| *$/g,tableRowBlankLine:/\n[ \t]*$/,tableAlignRight:/^ *-+: *$/,tableAlignCenter:/^ *:-+: *$/,tableAlignLeft:/^ *:-+ *$/,startATag:/^<a /i,endATag:/^<\/a>/i,startPreScriptTag:/^<(pre|code|kbd|script)(\s|>)/i,endPreScriptTag:/^<\/(pre|code|kbd|script)(\s|>)/i,startAngleBracket:/^</,endAngleBracket:/>$/,pedanticHrefTitle:/^([^'"]*[^\s])\s+(['"])(.*)\2/,unicodeAlphaNumeric:/[\p{L}\p{N}]/u,escapeTest:/[&<>"']/,escapeReplace:/[&<>"']/g,escapeTestNoEncode:/[<>"']|&(?!(#\d{1,7}|#[Xx][a-fA-F0-9]{1,6}|\w+);)/,escapeReplaceNoEncode:/[<>"']|&(?!(#\d{1,7}|#[Xx][a-fA-F0-9]{1,6}|\w+);)/g,caret:/(^|[^\[])\^/g,percentDecode:/%25/g,findPipe:/\|/g,splitPipe:/ \|/,slashPipe:/\\\|/g,carriageReturn:/\r\n|\r/g,spaceLine:/^ +$/gm,notSpaceStart:/^\S*/,endingNewline:/\n$/,listItemRegex:l=>new RegExp(`^( {0,3}${l})((?:[	 ][^\\n]*)?(?:\\n|$))`),nextBulletRegex:E(l=>new RegExp(`^ {0,${l}}(?:[*+-]|\\d{1,9}[.)])((?:[ 	][^\\n]*)?(?:\\n|$))`)),hrRegex:E(l=>new RegExp(`^ {0,${l}}((?:- *){3,}|(?:_ *){3,}|(?:\\* *){3,})(?:\\n+|$)`)),fencesBeginRegex:E(l=>new RegExp(`^ {0,${l}}(?:\`\`\`|~~~)`)),headingBeginRegex:E(l=>new RegExp(`^ {0,${l}}#`)),htmlBeginRegex:E(l=>new RegExp(`^ {0,${l}}<(?:[a-z].*>|!--)`,"i")),blockquoteBeginRegex:E(l=>new RegExp(`^ {0,${l}}>`))},_e=/^(?:[ \t]*(?:\n|$))+/,ze=/^((?: {4}| {0,3}\t)[^\n]+(?:\n(?:[ \t]*(?:\n|$))*)?)+/,Me=/^ {0,3}(`{3,}(?=[^`\n]*(?:\n|$))|~{3,})([^\n]*)(?:\n|$)(?:|([\s\S]*?)(?:\n|$))(?: {0,3}\1[~`]* *(?=\n|$)|$)/,D=/^ {0,3}((?:-[\t ]*){3,}|(?:_[ \t]*){3,}|(?:\*[ \t]*){3,})(?:\n+|$)/,Ee=/^ {0,3}(#{1,6})(?=\s|$)(.*)(?:\n+|$)/,F=/ {0,3}(?:[*+-]|\d{1,9}[.)])/,ae=/^(?!bull |blockCode|fences|blockquote|heading|html|table)((?:.|\n(?!\s*?\n|bull |blockCode|fences|blockquote|heading|html|table))+?)\n {0,3}(=+|-+) *(?:\n+|$)/,le=d(ae).replace(/bull/g,F).replace(/blockCode/g,/(?: {4}| {0,3}\t)/).replace(/fences/g,/ {0,3}(?:`{3,}|~{3,})/).replace(/blockquote/g,/ {0,3}>/).replace(/heading/g,/ {0,3}#{1,6}/).replace(/html/g,/ {0,3}<[^\n>]+>\n/).replace(/\|table/g,"").getRegex(),Ie=d(ae).replace(/bull/g,F).replace(/blockCode/g,/(?: {4}| {0,3}\t)/).replace(/fences/g,/ {0,3}(?:`{3,}|~{3,})/).replace(/blockquote/g,/ {0,3}>/).replace(/heading/g,/ {0,3}#{1,6}/).replace(/html/g,/ {0,3}<[^\n>]+>\n/).replace(/table/g,/ {0,3}\|?(?:[:\- ]*\|)+[\:\- ]*\n/).getRegex(),U=/^([^\n]+(?:\n(?!hr|heading|lheading|blockquote|fences|list|html|table| +\n)[^\n]+)*)/,Ae=/^[^\n]+/,K=/(?!\s*\])(?:\\[\s\S]|[^\[\]\\])+/,Ce=d(/^ {0,3}\[(label)\]: *(?:\n[ \t]*)?([^<\s][^\s]*|<.*?>)(?:(?: +(?:\n[ \t]*)?| *\n[ \t]*)(title))? *(?:\n+|$)/).replace("label",K).replace("title",/(?:"(?:\\"?|[^"\\])*"|'[^'\n]*(?:\n[^'\n]+)*\n?'|\([^()]*\))/).getRegex(),Be=d(/^(bull)([ \t][^\n]*?)?(?:\n|$)/).replace(/bull/g,F).getRegex(),H="address|article|aside|base|basefont|blockquote|body|caption|center|col|colgroup|dd|details|dialog|dir|div|dl|dt|fieldset|figcaption|figure|footer|form|frame|frameset|h[1-6]|head|header|hr|html|iframe|legend|li|link|main|menu|menuitem|meta|nav|noframes|ol|optgroup|option|p|param|search|section|summary|table|tbody|td|tfoot|th|thead|title|tr|track|ul",W=/<!--(?:-?>|[\s\S]*?(?:-->|$))/,De=d("^ {0,3}(?:<(script|pre|style|textarea)[\\s>][\\s\\S]*?(?:</\\1>[^\\n]*\\n+|$)|comment[^\\n]*(\\n+|$)|<\\?[\\s\\S]*?(?:\\?>\\n*|$)|<![A-Z][\\s\\S]*?(?:>\\n*|$)|<!\\[CDATA\\[[\\s\\S]*?(?:\\]\\]>\\n*|$)|</?(tag)(?: +|\\n|/?>)[\\s\\S]*?(?:(?:\\n[ 	]*)+\\n|$)|<(?!script|pre|style|textarea)([a-z][\\w-]*)(?:attribute)*? */?>(?=[ \\t]*(?:\\n|$))[\\s\\S]*?(?:(?:\\n[ 	]*)+\\n|$)|</(?!script|pre|style|textarea)[a-z][\\w-]*\\s*>(?=[ \\t]*(?:\\n|$))[\\s\\S]*?(?:(?:\\n[ 	]*)+\\n|$))","i").replace("comment",W).replace("tag",H).replace("attribute",/ +[a-zA-Z:_][\w.:-]*(?: *= *"[^"\n]*"| *= *'[^'\n]*'| *= *[^\s"'=<>`]+)?/).getRegex(),ue=d(U).replace("hr",D).replace("heading"," {0,3}#{1,6}(?:\\s|$)").replace("|lheading","").replace("|table","").replace("blockquote"," {0,3}>").replace("fences"," {0,3}(?:`{3,}(?=[^`\\n]*\\n)|~{3,})[^\\n]*\\n").replace("list"," {0,3}(?:[*+-]|1[.)])[ \\t]+[^ \\t\\n]").replace("html","</?(?:tag)(?: +|\\n|/?>)|<(?:script|pre|style|textarea|!--)").replace("tag",H).getRegex(),qe=d(/^( {0,3}> ?(paragraph|[^\n]*)(?:\n|$))+/).replace("paragraph",ue).getRegex(),X={blockquote:qe,code:ze,def:Ce,fences:Me,heading:Ee,hr:D,html:De,lheading:le,list:Be,newline:_e,paragraph:ue,table:z,text:Ae},ie=d("^ *([^\\n ].*)\\n {0,3}((?:\\| *)?:?-+:? *(?:\\| *:?-+:? *)*(?:\\| *)?)(?:\\n((?:(?! *\\n|hr|heading|blockquote|code|fences|list|html).*(?:\\n|$))*)\\n*|$)").replace("hr",D).replace("heading"," {0,3}#{1,6}(?:\\s|$)").replace("blockquote"," {0,3}>").replace("code","(?: {4}| {0,3}	)[^\\n]").replace("fences"," {0,3}(?:`{3,}(?=[^`\\n]*\\n)|~{3,})[^\\n]*\\n").replace("list"," {0,3}(?:[*+-]|1[.)])[ \\t]").replace("html","</?(?:tag)(?: +|\\n|/?>)|<(?:script|pre|style|textarea|!--)").replace("tag",H).getRegex(),ve={...X,lheading:Ie,table:ie,paragraph:d(U).replace("hr",D).replace("heading"," {0,3}#{1,6}(?:\\s|$)").replace("|lheading","").replace("table",ie).replace("blockquote"," {0,3}>").replace("fences"," {0,3}(?:`{3,}(?=[^`\\n]*\\n)|~{3,})[^\\n]*\\n").replace("list"," {0,3}(?:[*+-]|1[.)])[ \\t]+[^ \\t\\n]").replace("html","</?(?:tag)(?: +|\\n|/?>)|<(?:script|pre|style|textarea|!--)").replace("tag",H).getRegex()},He={...X,html:d(`^ *(?:comment *(?:\\n|\\s*$)|<(tag)[\\s\\S]+?</\\1> *(?:\\n{2,}|\\s*$)|<tag(?:"[^"]*"|'[^']*'|\\s[^'"/>\\s]*)*?/?> *(?:\\n{2,}|\\s*$))`).replace("comment",W).replace(/tag/g,"(?!(?:a|em|strong|small|s|cite|q|dfn|abbr|data|time|code|var|samp|kbd|sub|sup|i|b|u|mark|ruby|rt|rp|bdi|bdo|span|br|wbr|ins|del|img)\\b)\\w+(?!:|[^\\w\\s@]*@)\\b").getRegex(),def:/^ *\[([^\]]+)\]: *<?([^\s>]+)>?(?: +(["(][^\n]+[")]))? *(?:\n+|$)/,heading:/^(#{1,6})(.*)(?:\n+|$)/,fences:z,lheading:/^(.+?)\n {0,3}(=+|-+) *(?:\n+|$)/,paragraph:d(U).replace("hr",D).replace("heading",` *#{1,6} *[^
+]`).replace("lheading",le).replace("|table","").replace("blockquote"," {0,3}>").replace("|fences","").replace("|list","").replace("|html","").replace("|tag","").getRegex()},Ze=/^\\([!"#$%&'()*+,\-./:;<=>?@\[\]\\^_`{|}~])/,Ge=/^(`+)([^`]|[^`][\s\S]*?[^`])\1(?!`)/,pe=/^( {2,}|\\)\n(?!\s*$)/,Ne=/^(`+|[^`])(?:(?= {2,}\n)|[\s\S]*?(?:(?=[\\<!\[`*_]|\b_|$)|[^ ](?= {2,}\n)))/,I=/[\p{P}\p{S}]/u,Z=/[\s\p{P}\p{S}]/u,J=/[^\s\p{P}\p{S}]/u,Qe=d(/^((?![*_])punctSpace)/,"u").replace(/punctSpace/g,Z).getRegex(),ce=/(?!~)[\p{P}\p{S}]/u,je=/(?!~)[\s\p{P}\p{S}]/u,Fe=/(?:[^\s\p{P}\p{S}]|~)/u,Ue=d(/link|precode-code|html/,"g").replace("link",/\[(?:[^\[\]`]|(?<a>`+)[^`]+\k<a>(?!`))*?\]\((?:\\[\s\S]|[^\\\(\)]|\((?:\\[\s\S]|[^\\\(\)])*\))*\)/).replace("precode-",Le?"(?<!`)()":"(^^|[^`])").replace("code",/(?<b>`+)[^`]+\k<b>(?!`)/).replace("html",/<(?! )[^<>]*?>/).getRegex(),he=/^(?:\*+(?:((?!\*)punct)|([^\s*]))?)|^_+(?:((?!_)punct)|([^\s_]))?/,Ke=d(he,"u").replace(/punct/g,I).getRegex(),We=d(he,"u").replace(/punct/g,ce).getRegex(),ke="^[^_*]*?__[^_*]*?\\*[^_*]*?(?=__)|[^*]+(?=[^*])|(?!\\*)punct(\\*+)(?=[\\s]|$)|notPunctSpace(\\*+)(?!\\*)(?=punctSpace|$)|(?!\\*)punctSpace(\\*+)(?=notPunctSpace)|[\\s](\\*+)(?!\\*)(?=punct)|(?!\\*)punct(\\*+)(?!\\*)(?=punct)|notPunctSpace(\\*+)(?=notPunctSpace)",Xe=d(ke,"gu").replace(/notPunctSpace/g,J).replace(/punctSpace/g,Z).replace(/punct/g,I).getRegex(),Je=d(ke,"gu").replace(/notPunctSpace/g,Fe).replace(/punctSpace/g,je).replace(/punct/g,ce).getRegex(),Ve=d("^[^_*]*?\\*\\*[^_*]*?_[^_*]*?(?=\\*\\*)|[^_]+(?=[^_])|(?!_)punct(_+)(?=[\\s]|$)|notPunctSpace(_+)(?!_)(?=punctSpace|$)|(?!_)punctSpace(_+)(?=notPunctSpace)|[\\s](_+)(?!_)(?=punct)|(?!_)punct(_+)(?!_)(?=punct)","gu").replace(/notPunctSpace/g,J).replace(/punctSpace/g,Z).replace(/punct/g,I).getRegex(),Ye=d(/^~~?(?:((?!~)punct)|[^\s~])/,"u").replace(/punct/g,I).getRegex(),et="^[^~]+(?=[^~])|(?!~)punct(~~?)(?=[\\s]|$)|notPunctSpace(~~?)(?!~)(?=punctSpace|$)|(?!~)punctSpace(~~?)(?=notPunctSpace)|[\\s](~~?)(?!~)(?=punct)|(?!~)punct(~~?)(?!~)(?=punct)|notPunctSpace(~~?)(?=notPunctSpace)",tt=d(et,"gu").replace(/notPunctSpace/g,J).replace(/punctSpace/g,Z).replace(/punct/g,I).getRegex(),nt=d(/\\(punct)/,"gu").replace(/punct/g,I).getRegex(),rt=d(/^<(scheme:[^\s\x00-\x1f<>]*|email)>/).replace("scheme",/[a-zA-Z][a-zA-Z0-9+.-]{1,31}/).replace("email",/[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+(@)[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)+(?![-_])/).getRegex(),st=d(W).replace("(?:-->|$)","-->").getRegex(),it=d("^comment|^</[a-zA-Z][\\w:-]*\\s*>|^<[a-zA-Z][\\w-]*(?:attribute)*?\\s*/?>|^<\\?[\\s\\S]*?\\?>|^<![a-zA-Z]+\\s[\\s\\S]*?>|^<!\\[CDATA\\[[\\s\\S]*?\\]\\]>").replace("comment",st).replace("attribute",/\s+[a-zA-Z:_][\w.:-]*(?:\s*=\s*"[^"]*"|\s*=\s*'[^']*'|\s*=\s*[^\s"'=<>`]+)?/).getRegex(),v=/(?:\[(?:\\[\s\S]|[^\[\]\\])*\]|\\[\s\S]|`+(?!`)[^`]*?`+(?!`)|``+(?=\])|[^\[\]\\`])*?/,ot=d(/^!?\[(label)\]\(\s*(href)(?:(?:[ \t]+(?:\n[ \t]*)?|\n[ \t]*)(title))?\s*\)/).replace("label",v).replace("href",/<(?:\\.|[^\n<>\\])+>|[^ \t\n\x00-\x1f]*/).replace("title",/"(?:\\"?|[^"\\])*"|'(?:\\'?|[^'\\])*'|\((?:\\\)?|[^)\\])*\)/).getRegex(),de=d(/^!?\[(label)\]\[(ref)\]/).replace("label",v).replace("ref",K).getRegex(),ge=d(/^!?\[(ref)\](?:\[\])?/).replace("ref",K).getRegex(),at=d("reflink|nolink(?!\\()","g").replace("reflink",de).replace("nolink",ge).getRegex(),oe=/[hH][tT][tT][pP][sS]?|[fF][tT][pP]/,V={_backpedal:z,anyPunctuation:nt,autolink:rt,blockSkip:Ue,br:pe,code:Ge,del:z,delLDelim:z,delRDelim:z,emStrongLDelim:Ke,emStrongRDelimAst:Xe,emStrongRDelimUnd:Ve,escape:Ze,link:ot,nolink:ge,punctuation:Qe,reflink:de,reflinkSearch:at,tag:it,text:Ne,url:z},lt={...V,link:d(/^!?\[(label)\]\((.*?)\)/).replace("label",v).getRegex(),reflink:d(/^!?\[(label)\]\s*\[([^\]]*)\]/).replace("label",v).getRegex()},j={...V,emStrongRDelimAst:Je,emStrongLDelim:We,delLDelim:Ye,delRDelim:tt,url:d(/^((?:protocol):\/\/|www\.)(?:[a-zA-Z0-9\-]+\.?)+[^\s<]*|^email/).replace("protocol",oe).replace("email",/[A-Za-z0-9._+-]+(@)[a-zA-Z0-9-_]+(?:\.[a-zA-Z0-9-_]*[a-zA-Z0-9])+(?![-_])/).getRegex(),_backpedal:/(?:[^?!.,:;*_'"~()&]+|\([^)]*\)|&(?![a-zA-Z0-9]+;$)|[?!.,:;*_'"~)]+(?!$))+/,del:/^(~~?)(?=[^\s~])((?:\\[\s\S]|[^\\])*?(?:\\[\s\S]|[^\s~\\]))\1(?=[^~]|$)/,text:d(/^([`~]+|[^`~])(?:(?= {2,}\n)|(?=[a-zA-Z0-9.!#$%&'*+\/=?_`{\|}~-]+@)|[\s\S]*?(?:(?=[\\<!\[`*~_]|\b_|protocol:\/\/|www\.|$)|[^ ](?= {2,}\n)|[^a-zA-Z0-9.!#$%&'*+\/=?_`{\|}~-](?=[a-zA-Z0-9.!#$%&'*+\/=?_`{\|}~-]+@)))/).replace("protocol",oe).getRegex()},ut={...j,br:d(pe).replace("{2,}","*").getRegex(),text:d(j.text).replace("\\b_","\\b_| {2,}\\n").replace(/\{2,\}/g,"*").getRegex()},q={normal:X,gfm:ve,pedantic:He},A={normal:V,gfm:j,breaks:ut,pedantic:lt};var pt={"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"},fe=l=>pt[l];function O(l,e){if(e){if(m.escapeTest.test(l))return l.replace(m.escapeReplace,fe)}else if(m.escapeTestNoEncode.test(l))return l.replace(m.escapeReplaceNoEncode,fe);return l}function Y(l){try{l=encodeURI(l).replace(m.percentDecode,"%")}catch{return null}return l}function ee(l,e){let t=l.replace(m.findPipe,(r,i,o)=>{let u=!1,a=i;for(;--a>=0&&o[a]==="\\";)u=!u;return u?"|":" |"}),n=t.split(m.splitPipe),s=0;if(n[0].trim()||n.shift(),n.length>0&&!n.at(-1)?.trim()&&n.pop(),e)if(n.length>e)n.splice(e);else for(;n.length<e;)n.push("");for(;s<n.length;s++)n[s]=n[s].trim().replace(m.slashPipe,"|");return n}function L(l,e,t){let n=l.length;if(n===0)return"";let s=0;for(;s<n;){let r=l.charAt(n-s-1);if(r===e&&!t)s++;else if(r!==e&&t)s++;else break}return l.slice(0,n-s)}function te(l){let e=l.split(`
+`),t=e.length-1;for(;t>=0&&m.blankLine.test(e[t]);)t--;return e.length-t<=2?l:e.slice(0,t+1).join(`
+`)}function me(l,e){if(l.indexOf(e[1])===-1)return-1;let t=0;for(let n=0;n<l.length;n++)if(l[n]==="\\")n++;else if(l[n]===e[0])t++;else if(l[n]===e[1]&&(t--,t<0))return n;return t>0?-2:-1}function xe(l,e=0){let t=e,n="";for(let s of l)if(s==="	"){let r=4-t%4;n+=" ".repeat(r),t+=r}else n+=s,t++;return n}function be(l,e,t,n,s){let r=e.href,i=e.title||null,o=l[1].replace(s.other.outputLinkReplace,"$1");n.state.inLink=!0;let u={type:l[0].charAt(0)==="!"?"image":"link",raw:t,href:r,title:i,text:o,tokens:n.inlineTokens(o)};return n.state.inLink=!1,u}function ct(l,e,t){let n=l.match(t.other.indentCodeCompensation);if(n===null)return e;let s=n[1];return e.split(`
+`).map(r=>{let i=r.match(t.other.beginningSpace);if(i===null)return r;let[o]=i;return o.length>=s.length?r.slice(s.length):r}).join(`
+`)}var w=class{options;rules;lexer;constructor(e){this.options=e||T}space(e){let t=this.rules.block.newline.exec(e);if(t&&t[0].length>0)return{type:"space",raw:t[0]}}code(e){let t=this.rules.block.code.exec(e);if(t){let n=this.options.pedantic?t[0]:te(t[0]),s=n.replace(this.rules.other.codeRemoveIndent,"");return{type:"code",raw:n,codeBlockStyle:"indented",text:s}}}fences(e){let t=this.rules.block.fences.exec(e);if(t){let n=t[0],s=ct(n,t[3]||"",this.rules);return{type:"code",raw:n,lang:t[2]?t[2].trim().replace(this.rules.inline.anyPunctuation,"$1"):t[2],text:s}}}heading(e){let t=this.rules.block.heading.exec(e);if(t){let n=t[2].trim();if(this.rules.other.endingHash.test(n)){let s=L(n,"#");(this.options.pedantic||!s||this.rules.other.endingSpaceChar.test(s))&&(n=s.trim())}return{type:"heading",raw:L(t[0],`
+`),depth:t[1].length,text:n,tokens:this.lexer.inline(n)}}}hr(e){let t=this.rules.block.hr.exec(e);if(t)return{type:"hr",raw:L(t[0],`
+`)}}blockquote(e){let t=this.rules.block.blockquote.exec(e);if(t){let n=L(t[0],`
+`).split(`
+`),s="",r="",i=[];for(;n.length>0;){let o=!1,u=[],a;for(a=0;a<n.length;a++)if(this.rules.other.blockquoteStart.test(n[a]))u.push(n[a]),o=!0;else if(!o)u.push(n[a]);else break;n=n.slice(a);let c=u.join(`
+`),p=c.replace(this.rules.other.blockquoteSetextReplace,`
+    $1`).replace(this.rules.other.blockquoteSetextReplace2,"");s=s?`${s}
+${c}`:c,r=r?`${r}
+${p}`:p;let k=this.lexer.state.top;if(this.lexer.state.top=!0,this.lexer.blockTokens(p,i,!0),this.lexer.state.top=k,n.length===0)break;let h=i.at(-1);if(h?.type==="code")break;if(h?.type==="blockquote"){let R=h,f=R.raw+`
+`+n.join(`
+`),$=this.blockquote(f);i[i.length-1]=$,s=s.substring(0,s.length-R.raw.length)+$.raw,r=r.substring(0,r.length-R.text.length)+$.text;break}else if(h?.type==="list"){let R=h,f=R.raw+`
+`+n.join(`
+`),$=this.list(f);i[i.length-1]=$,s=s.substring(0,s.length-h.raw.length)+$.raw,r=r.substring(0,r.length-R.raw.length)+$.raw,n=f.substring(i.at(-1).raw.length).split(`
+`);continue}}return{type:"blockquote",raw:s,tokens:i,text:r}}}list(e){let t=this.rules.block.list.exec(e);if(t){let n=t[1].trim(),s=n.length>1,r={type:"list",raw:"",ordered:s,start:s?+n.slice(0,-1):"",loose:!1,items:[]};n=s?`\\d{1,9}\\${n.slice(-1)}`:`\\${n}`,this.options.pedantic&&(n=s?n:"[*+-]");let i=this.rules.other.listItemRegex(n),o=!1;for(;e;){let a=!1,c="",p="";if(!(t=i.exec(e))||this.rules.block.hr.test(e))break;c=t[0],e=e.substring(c.length);let k=xe(t[2].split(`
+`,1)[0],t[1].length),h=e.split(`
+`,1)[0],R=!k.trim(),f=0;if(this.options.pedantic?(f=2,p=k.trimStart()):R?f=t[1].length+1:(f=k.search(this.rules.other.nonSpaceChar),f=f>4?1:f,p=k.slice(f),f+=t[1].length),R&&this.rules.other.blankLine.test(h)&&(c+=h+`
+`,e=e.substring(h.length+1),a=!0),!a){let $=this.rules.other.nextBulletRegex(f),ne=this.rules.other.hrRegex(f),re=this.rules.other.fencesBeginRegex(f),se=this.rules.other.headingBeginRegex(f),Re=this.rules.other.htmlBeginRegex(f),Te=this.rules.other.blockquoteBeginRegex(f);for(;e;){let G=e.split(`
+`,1)[0],B;if(h=G,this.options.pedantic?(h=h.replace(this.rules.other.listReplaceNesting,"  "),B=h):B=h.replace(this.rules.other.tabCharGlobal,"    "),re.test(h)||se.test(h)||Re.test(h)||Te.test(h)||$.test(h)||ne.test(h))break;if(B.search(this.rules.other.nonSpaceChar)>=f||!h.trim())p+=`
+`+B.slice(f);else{if(R||k.replace(this.rules.other.tabCharGlobal,"    ").search(this.rules.other.nonSpaceChar)>=4||re.test(k)||se.test(k)||ne.test(k))break;p+=`
+`+h}R=!h.trim(),c+=G+`
+`,e=e.substring(G.length+1),k=B.slice(f)}}r.loose||(o?r.loose=!0:this.rules.other.doubleBlankLine.test(c)&&(o=!0)),r.items.push({type:"list_item",raw:c,task:!!this.options.gfm&&this.rules.other.listIsTask.test(p),loose:!1,text:p,tokens:[]}),r.raw+=c}let u=r.items.at(-1);if(u)u.raw=u.raw.trimEnd(),u.text=u.text.trimEnd();else return;r.raw=r.raw.trimEnd();for(let a of r.items){this.lexer.state.top=!1,a.tokens=this.lexer.blockTokens(a.text,[]);let c=a.tokens[0];if(a.task&&(c?.type==="text"||c?.type==="paragraph")){a.text=a.text.replace(this.rules.other.listReplaceTask,""),c.raw=c.raw.replace(this.rules.other.listReplaceTask,""),c.text=c.text.replace(this.rules.other.listReplaceTask,"");for(let k=this.lexer.inlineQueue.length-1;k>=0;k--)if(this.rules.other.listIsTask.test(this.lexer.inlineQueue[k].src)){this.lexer.inlineQueue[k].src=this.lexer.inlineQueue[k].src.replace(this.rules.other.listReplaceTask,"");break}let p=this.rules.other.listTaskCheckbox.exec(a.raw);if(p){let k={type:"checkbox",raw:p[0]+" ",checked:p[0]!=="[ ]"};a.checked=k.checked,r.loose?a.tokens[0]&&["paragraph","text"].includes(a.tokens[0].type)&&"tokens"in a.tokens[0]&&a.tokens[0].tokens?(a.tokens[0].raw=k.raw+a.tokens[0].raw,a.tokens[0].text=k.raw+a.tokens[0].text,a.tokens[0].tokens.unshift(k)):a.tokens.unshift({type:"paragraph",raw:k.raw,text:k.raw,tokens:[k]}):a.tokens.unshift(k)}}else a.task&&(a.task=!1);if(!r.loose){let p=a.tokens.filter(h=>h.type==="space"),k=p.length>0&&p.some(h=>this.rules.other.anyLine.test(h.raw));r.loose=k}}if(r.loose)for(let a of r.items){a.loose=!0;for(let c of a.tokens)c.type==="text"&&(c.type="paragraph")}return r}}html(e){let t=this.rules.block.html.exec(e);if(t){let n=te(t[0]);return{type:"html",block:!0,raw:n,pre:t[1]==="pre"||t[1]==="script"||t[1]==="style",text:n}}}def(e){let t=this.rules.block.def.exec(e);if(t){let n=t[1].toLowerCase().replace(this.rules.other.multipleSpaceGlobal," "),s=t[2]?t[2].replace(this.rules.other.hrefBrackets,"$1").replace(this.rules.inline.anyPunctuation,"$1"):"",r=t[3]?t[3].substring(1,t[3].length-1).replace(this.rules.inline.anyPunctuation,"$1"):t[3];return{type:"def",tag:n,raw:L(t[0],`
+`),href:s,title:r}}}table(e){let t=this.rules.block.table.exec(e);if(!t||!this.rules.other.tableDelimiter.test(t[2]))return;let n=ee(t[1]),s=t[2].replace(this.rules.other.tableAlignChars,"").split("|"),r=t[3]?.trim()?t[3].replace(this.rules.other.tableRowBlankLine,"").split(`
+`):[],i={type:"table",raw:L(t[0],`
+`),header:[],align:[],rows:[]};if(n.length===s.length){for(let o of s)this.rules.other.tableAlignRight.test(o)?i.align.push("right"):this.rules.other.tableAlignCenter.test(o)?i.align.push("center"):this.rules.other.tableAlignLeft.test(o)?i.align.push("left"):i.align.push(null);for(let o=0;o<n.length;o++)i.header.push({text:n[o],tokens:this.lexer.inline(n[o]),header:!0,align:i.align[o]});for(let o of r)i.rows.push(ee(o,i.header.length).map((u,a)=>({text:u,tokens:this.lexer.inline(u),header:!1,align:i.align[a]})));return i}}lheading(e){let t=this.rules.block.lheading.exec(e);if(t){let n=t[1].trim();return{type:"heading",raw:L(t[0],`
+`),depth:t[2].charAt(0)==="="?1:2,text:n,tokens:this.lexer.inline(n)}}}paragraph(e){let t=this.rules.block.paragraph.exec(e);if(t){let n=t[1].charAt(t[1].length-1)===`
+`?t[1].slice(0,-1):t[1];return{type:"paragraph",raw:t[0],text:n,tokens:this.lexer.inline(n)}}}text(e){let t=this.rules.block.text.exec(e);if(t)return{type:"text",raw:t[0],text:t[0],tokens:this.lexer.inline(t[0])}}escape(e){let t=this.rules.inline.escape.exec(e);if(t)return{type:"escape",raw:t[0],text:t[1]}}tag(e){let t=this.rules.inline.tag.exec(e);if(t)return!this.lexer.state.inLink&&this.rules.other.startATag.test(t[0])?this.lexer.state.inLink=!0:this.lexer.state.inLink&&this.rules.other.endATag.test(t[0])&&(this.lexer.state.inLink=!1),!this.lexer.state.inRawBlock&&this.rules.other.startPreScriptTag.test(t[0])?this.lexer.state.inRawBlock=!0:this.lexer.state.inRawBlock&&this.rules.other.endPreScriptTag.test(t[0])&&(this.lexer.state.inRawBlock=!1),{type:"html",raw:t[0],inLink:this.lexer.state.inLink,inRawBlock:this.lexer.state.inRawBlock,block:!1,text:t[0]}}link(e){let t=this.rules.inline.link.exec(e);if(t){let n=t[2].trim();if(!this.options.pedantic&&this.rules.other.startAngleBracket.test(n)){if(!this.rules.other.endAngleBracket.test(n))return;let i=L(n.slice(0,-1),"\\");if((n.length-i.length)%2===0)return}else{let i=me(t[2],"()");if(i===-2)return;if(i>-1){let u=(t[0].indexOf("!")===0?5:4)+t[1].length+i;t[2]=t[2].substring(0,i),t[0]=t[0].substring(0,u).trim(),t[3]=""}}let s=t[2],r="";if(this.options.pedantic){let i=this.rules.other.pedanticHrefTitle.exec(s);i&&(s=i[1],r=i[3])}else r=t[3]?t[3].slice(1,-1):"";return s=s.trim(),this.rules.other.startAngleBracket.test(s)&&(this.options.pedantic&&!this.rules.other.endAngleBracket.test(n)?s=s.slice(1):s=s.slice(1,-1)),be(t,{href:s&&s.replace(this.rules.inline.anyPunctuation,"$1"),title:r&&r.replace(this.rules.inline.anyPunctuation,"$1")},t[0],this.lexer,this.rules)}}reflink(e,t){let n;if((n=this.rules.inline.reflink.exec(e))||(n=this.rules.inline.nolink.exec(e))){let s=(n[2]||n[1]).replace(this.rules.other.multipleSpaceGlobal," "),r=t[s.toLowerCase()];if(!r){let i=n[0].charAt(0);return{type:"text",raw:i,text:i}}return be(n,r,n[0],this.lexer,this.rules)}}emStrong(e,t,n=""){let s=this.rules.inline.emStrongLDelim.exec(e);if(!s||!s[1]&&!s[2]&&!s[3]&&!s[4]||s[4]&&n.match(this.rules.other.unicodeAlphaNumeric))return;if(!(s[1]||s[3]||"")||!n||this.rules.inline.punctuation.exec(n)){let i=[...s[0]].length-1,o,u,a=i,c=0,p=s[0][0]==="*"?this.rules.inline.emStrongRDelimAst:this.rules.inline.emStrongRDelimUnd;for(p.lastIndex=0,t=t.slice(-1*e.length+i);(s=p.exec(t))!==null;){if(o=s[1]||s[2]||s[3]||s[4]||s[5]||s[6],!o)continue;if(u=[...o].length,s[3]||s[4]){a+=u;continue}else if((s[5]||s[6])&&i%3&&!((i+u)%3)){c+=u;continue}if(a-=u,a>0)continue;u=Math.min(u,u+a+c);let k=[...s[0]][0].length,h=e.slice(0,i+s.index+k+u);if(Math.min(i,u)%2){let f=h.slice(1,-1);return{type:"em",raw:h,text:f,tokens:this.lexer.inlineTokens(f)}}let R=h.slice(2,-2);return{type:"strong",raw:h,text:R,tokens:this.lexer.inlineTokens(R)}}}}codespan(e){let t=this.rules.inline.code.exec(e);if(t){let n=t[2].replace(this.rules.other.newLineCharGlobal," "),s=this.rules.other.nonSpaceChar.test(n),r=this.rules.other.startingSpaceChar.test(n)&&this.rules.other.endingSpaceChar.test(n);return s&&r&&(n=n.substring(1,n.length-1)),{type:"codespan",raw:t[0],text:n}}}br(e){let t=this.rules.inline.br.exec(e);if(t)return{type:"br",raw:t[0]}}del(e,t,n=""){let s=this.rules.inline.delLDelim.exec(e);if(!s)return;if(!(s[1]||"")||!n||this.rules.inline.punctuation.exec(n)){let i=[...s[0]].length-1,o,u,a=i,c=this.rules.inline.delRDelim;for(c.lastIndex=0,t=t.slice(-1*e.length+i);(s=c.exec(t))!==null;){if(o=s[1]||s[2]||s[3]||s[4]||s[5]||s[6],!o||(u=[...o].length,u!==i))continue;if(s[3]||s[4]){a+=u;continue}if(a-=u,a>0)continue;u=Math.min(u,u+a);let p=[...s[0]][0].length,k=e.slice(0,i+s.index+p+u),h=k.slice(i,-i);return{type:"del",raw:k,text:h,tokens:this.lexer.inlineTokens(h)}}}}autolink(e){let t=this.rules.inline.autolink.exec(e);if(t){let n,s;return t[2]==="@"?(n=t[1],s="mailto:"+n):(n=t[1],s=n),{type:"link",raw:t[0],text:n,href:s,tokens:[{type:"text",raw:n,text:n}]}}}url(e){let t;if(t=this.rules.inline.url.exec(e)){let n,s;if(t[2]==="@")n=t[0],s="mailto:"+n;else{let r;do r=t[0],t[0]=this.rules.inline._backpedal.exec(t[0])?.[0]??"";while(r!==t[0]);n=t[0],t[1]==="www."?s="http://"+t[0]:s=t[0]}return{type:"link",raw:t[0],text:n,href:s,tokens:[{type:"text",raw:n,text:n}]}}}inlineText(e){let t=this.rules.inline.text.exec(e);if(t){let n=this.lexer.state.inRawBlock;return{type:"text",raw:t[0],text:t[0],escaped:n}}}};var x=class l{tokens;options;state;inlineQueue;tokenizer;constructor(e){this.tokens=[],this.tokens.links=Object.create(null),this.options=e||T,this.options.tokenizer=this.options.tokenizer||new w,this.tokenizer=this.options.tokenizer,this.tokenizer.options=this.options,this.tokenizer.lexer=this,this.inlineQueue=[],this.state={inLink:!1,inRawBlock:!1,top:!0};let t={other:m,block:q.normal,inline:A.normal};this.options.pedantic?(t.block=q.pedantic,t.inline=A.pedantic):this.options.gfm&&(t.block=q.gfm,this.options.breaks?t.inline=A.breaks:t.inline=A.gfm),this.tokenizer.rules=t}static get rules(){return{block:q,inline:A}}static lex(e,t){return new l(t).lex(e)}static lexInline(e,t){return new l(t).inlineTokens(e)}lex(e){e=e.replace(m.carriageReturn,`
+`),this.blockTokens(e,this.tokens);for(let t=0;t<this.inlineQueue.length;t++){let n=this.inlineQueue[t];this.inlineTokens(n.src,n.tokens)}return this.inlineQueue=[],this.tokens}blockTokens(e,t=[],n=!1){this.tokenizer.lexer=this,this.options.pedantic&&(e=e.replace(m.tabCharGlobal,"    ").replace(m.spaceLine,""));let s=1/0;for(;e;){if(e.length<s)s=e.length;else{this.infiniteLoopError(e.charCodeAt(0));break}let r;if(this.options.extensions?.block?.some(o=>(r=o.call({lexer:this},e,t))?(e=e.substring(r.raw.length),t.push(r),!0):!1))continue;if(r=this.tokenizer.space(e)){e=e.substring(r.raw.length);let o=t.at(-1);r.raw.length===1&&o!==void 0?o.raw+=`
+`:t.push(r);continue}if(r=this.tokenizer.code(e)){e=e.substring(r.raw.length);let o=t.at(-1);o?.type==="paragraph"||o?.type==="text"?(o.raw+=(o.raw.endsWith(`
+`)?"":`
+`)+r.raw,o.text+=`
+`+r.text,this.inlineQueue.at(-1).src=o.text):t.push(r);continue}if(r=this.tokenizer.fences(e)){e=e.substring(r.raw.length),t.push(r);continue}if(r=this.tokenizer.heading(e)){e=e.substring(r.raw.length),t.push(r);continue}if(r=this.tokenizer.hr(e)){e=e.substring(r.raw.length),t.push(r);continue}if(r=this.tokenizer.blockquote(e)){e=e.substring(r.raw.length),t.push(r);continue}if(r=this.tokenizer.list(e)){e=e.substring(r.raw.length),t.push(r);continue}if(r=this.tokenizer.html(e)){e=e.substring(r.raw.length),t.push(r);continue}if(r=this.tokenizer.def(e)){e=e.substring(r.raw.length);let o=t.at(-1);o?.type==="paragraph"||o?.type==="text"?(o.raw+=(o.raw.endsWith(`
+`)?"":`
+`)+r.raw,o.text+=`
+`+r.raw,this.inlineQueue.at(-1).src=o.text):this.tokens.links[r.tag]||(this.tokens.links[r.tag]={href:r.href,title:r.title},t.push(r));continue}if(r=this.tokenizer.table(e)){e=e.substring(r.raw.length),t.push(r);continue}if(r=this.tokenizer.lheading(e)){e=e.substring(r.raw.length),t.push(r);continue}let i=e;if(this.options.extensions?.startBlock){let o=1/0,u=e.slice(1),a;this.options.extensions.startBlock.forEach(c=>{a=c.call({lexer:this},u),typeof a=="number"&&a>=0&&(o=Math.min(o,a))}),o<1/0&&o>=0&&(i=e.substring(0,o+1))}if(this.state.top&&(r=this.tokenizer.paragraph(i))){let o=t.at(-1);n&&o?.type==="paragraph"?(o.raw+=(o.raw.endsWith(`
+`)?"":`
+`)+r.raw,o.text+=`
+`+r.text,this.inlineQueue.pop(),this.inlineQueue.at(-1).src=o.text):t.push(r),n=i.length!==e.length,e=e.substring(r.raw.length);continue}if(r=this.tokenizer.text(e)){e=e.substring(r.raw.length);let o=t.at(-1);o?.type==="text"?(o.raw+=(o.raw.endsWith(`
+`)?"":`
+`)+r.raw,o.text+=`
+`+r.text,this.inlineQueue.pop(),this.inlineQueue.at(-1).src=o.text):t.push(r);continue}if(e){this.infiniteLoopError(e.charCodeAt(0));break}}return this.state.top=!0,t}inline(e,t=[]){return this.inlineQueue.push({src:e,tokens:t}),t}inlineTokens(e,t=[]){this.tokenizer.lexer=this;let n=e,s=null;if(this.tokens.links){let a=Object.keys(this.tokens.links);if(a.length>0)for(;(s=this.tokenizer.rules.inline.reflinkSearch.exec(n))!==null;)a.includes(s[0].slice(s[0].lastIndexOf("[")+1,-1))&&(n=n.slice(0,s.index)+"["+"a".repeat(s[0].length-2)+"]"+n.slice(this.tokenizer.rules.inline.reflinkSearch.lastIndex))}for(;(s=this.tokenizer.rules.inline.anyPunctuation.exec(n))!==null;)n=n.slice(0,s.index)+"++"+n.slice(this.tokenizer.rules.inline.anyPunctuation.lastIndex);let r;for(;(s=this.tokenizer.rules.inline.blockSkip.exec(n))!==null;)r=s[2]?s[2].length:0,n=n.slice(0,s.index+r)+"["+"a".repeat(s[0].length-r-2)+"]"+n.slice(this.tokenizer.rules.inline.blockSkip.lastIndex);n=this.options.hooks?.emStrongMask?.call({lexer:this},n)??n;let i=!1,o="",u=1/0;for(;e;){if(e.length<u)u=e.length;else{this.infiniteLoopError(e.charCodeAt(0));break}i||(o=""),i=!1;let a;if(this.options.extensions?.inline?.some(p=>(a=p.call({lexer:this},e,t))?(e=e.substring(a.raw.length),t.push(a),!0):!1))continue;if(a=this.tokenizer.escape(e)){e=e.substring(a.raw.length),t.push(a);continue}if(a=this.tokenizer.tag(e)){e=e.substring(a.raw.length),t.push(a);continue}if(a=this.tokenizer.link(e)){e=e.substring(a.raw.length),t.push(a);continue}if(a=this.tokenizer.reflink(e,this.tokens.links)){e=e.substring(a.raw.length);let p=t.at(-1);a.type==="text"&&p?.type==="text"?(p.raw+=a.raw,p.text+=a.text):t.push(a);continue}if(a=this.tokenizer.emStrong(e,n,o)){e=e.substring(a.raw.length),t.push(a);continue}if(a=this.tokenizer.codespan(e)){e=e.substring(a.raw.length),t.push(a);continue}if(a=this.tokenizer.br(e)){e=e.substring(a.raw.length),t.push(a);continue}if(a=this.tokenizer.del(e,n,o)){e=e.substring(a.raw.length),t.push(a);continue}if(a=this.tokenizer.autolink(e)){e=e.substring(a.raw.length),t.push(a);continue}if(!this.state.inLink&&(a=this.tokenizer.url(e))){e=e.substring(a.raw.length),t.push(a);continue}let c=e;if(this.options.extensions?.startInline){let p=1/0,k=e.slice(1),h;this.options.extensions.startInline.forEach(R=>{h=R.call({lexer:this},k),typeof h=="number"&&h>=0&&(p=Math.min(p,h))}),p<1/0&&p>=0&&(c=e.substring(0,p+1))}if(a=this.tokenizer.inlineText(c)){e=e.substring(a.raw.length),a.raw.slice(-1)!=="_"&&(o=a.raw.slice(-1)),i=!0;let p=t.at(-1);p?.type==="text"?(p.raw+=a.raw,p.text+=a.text):t.push(a);continue}if(e){this.infiniteLoopError(e.charCodeAt(0));break}}return t}infiniteLoopError(e){let t="Infinite loop on byte: "+e;if(this.options.silent)console.error(t);else throw new Error(t)}};var y=class{options;parser;constructor(e){this.options=e||T}space(e){return""}code({text:e,lang:t,escaped:n}){let s=(t||"").match(m.notSpaceStart)?.[0],r=e.replace(m.endingNewline,"")+`
+`;return s?'<pre><code class="language-'+O(s)+'">'+(n?r:O(r,!0))+`</code></pre>
+`:"<pre><code>"+(n?r:O(r,!0))+`</code></pre>
+`}blockquote({tokens:e}){return`<blockquote>
+${this.parser.parse(e)}</blockquote>
+`}html({text:e}){return e}def(e){return""}heading({tokens:e,depth:t}){return`<h${t}>${this.parser.parseInline(e)}</h${t}>
+`}hr(e){return`<hr>
+`}list(e){let t=e.ordered,n=e.start,s="";for(let o=0;o<e.items.length;o++){let u=e.items[o];s+=this.listitem(u)}let r=t?"ol":"ul",i=t&&n!==1?' start="'+n+'"':"";return"<"+r+i+`>
+`+s+"</"+r+`>
+`}listitem(e){return`<li>${this.parser.parse(e.tokens)}</li>
+`}checkbox({checked:e}){return"<input "+(e?'checked="" ':"")+'disabled="" type="checkbox"> '}paragraph({tokens:e}){return`<p>${this.parser.parseInline(e)}</p>
+`}table(e){let t="",n="";for(let r=0;r<e.header.length;r++)n+=this.tablecell(e.header[r]);t+=this.tablerow({text:n});let s="";for(let r=0;r<e.rows.length;r++){let i=e.rows[r];n="";for(let o=0;o<i.length;o++)n+=this.tablecell(i[o]);s+=this.tablerow({text:n})}return s&&(s=`<tbody>${s}</tbody>`),`<table>
+<thead>
+`+t+`</thead>
+`+s+`</table>
+`}tablerow({text:e}){return`<tr>
+${e}</tr>
+`}tablecell(e){let t=this.parser.parseInline(e.tokens),n=e.header?"th":"td";return(e.align?`<${n} align="${e.align}">`:`<${n}>`)+t+`</${n}>
+`}strong({tokens:e}){return`<strong>${this.parser.parseInline(e)}</strong>`}em({tokens:e}){return`<em>${this.parser.parseInline(e)}</em>`}codespan({text:e}){return`<code>${O(e,!0)}</code>`}br(e){return"<br>"}del({tokens:e}){return`<del>${this.parser.parseInline(e)}</del>`}link({href:e,title:t,tokens:n}){let s=this.parser.parseInline(n),r=Y(e);if(r===null)return s;e=r;let i='<a href="'+e+'"';return t&&(i+=' title="'+O(t)+'"'),i+=">"+s+"</a>",i}image({href:e,title:t,text:n,tokens:s}){s&&(n=this.parser.parseInline(s,this.parser.textRenderer));let r=Y(e);if(r===null)return O(n);e=r;let i=`<img src="${e}" alt="${O(n)}"`;return t&&(i+=` title="${O(t)}"`),i+=">",i}text(e){return"tokens"in e&&e.tokens?this.parser.parseInline(e.tokens):"escaped"in e&&e.escaped?e.text:O(e.text)}};var S=class{strong({text:e}){return e}em({text:e}){return e}codespan({text:e}){return e}del({text:e}){return e}html({text:e}){return e}text({text:e}){return e}link({text:e}){return""+e}image({text:e}){return""+e}br(){return""}checkbox({raw:e}){return e}};var b=class l{options;renderer;textRenderer;constructor(e){this.options=e||T,this.options.renderer=this.options.renderer||new y,this.renderer=this.options.renderer,this.renderer.options=this.options,this.renderer.parser=this,this.textRenderer=new S}static parse(e,t){return new l(t).parse(e)}static parseInline(e,t){return new l(t).parseInline(e)}parse(e){this.renderer.parser=this;let t="";for(let n=0;n<e.length;n++){let s=e[n];if(this.options.extensions?.renderers?.[s.type]){let i=s,o=this.options.extensions.renderers[i.type].call({parser:this},i);if(o!==!1||!["space","hr","heading","code","table","blockquote","list","html","def","paragraph","text"].includes(i.type)){t+=o||"";continue}}let r=s;switch(r.type){case"space":{t+=this.renderer.space(r);break}case"hr":{t+=this.renderer.hr(r);break}case"heading":{t+=this.renderer.heading(r);break}case"code":{t+=this.renderer.code(r);break}case"table":{t+=this.renderer.table(r);break}case"blockquote":{t+=this.renderer.blockquote(r);break}case"list":{t+=this.renderer.list(r);break}case"checkbox":{t+=this.renderer.checkbox(r);break}case"html":{t+=this.renderer.html(r);break}case"def":{t+=this.renderer.def(r);break}case"paragraph":{t+=this.renderer.paragraph(r);break}case"text":{t+=this.renderer.text(r);break}default:{let i='Token with "'+r.type+'" type was not found.';if(this.options.silent)return console.error(i),"";throw new Error(i)}}}return t}parseInline(e,t=this.renderer){this.renderer.parser=this;let n="";for(let s=0;s<e.length;s++){let r=e[s];if(this.options.extensions?.renderers?.[r.type]){let o=this.options.extensions.renderers[r.type].call({parser:this},r);if(o!==!1||!["escape","html","link","image","strong","em","codespan","br","del","text"].includes(r.type)){n+=o||"";continue}}let i=r;switch(i.type){case"escape":{n+=t.text(i);break}case"html":{n+=t.html(i);break}case"link":{n+=t.link(i);break}case"image":{n+=t.image(i);break}case"checkbox":{n+=t.checkbox(i);break}case"strong":{n+=t.strong(i);break}case"em":{n+=t.em(i);break}case"codespan":{n+=t.codespan(i);break}case"br":{n+=t.br(i);break}case"del":{n+=t.del(i);break}case"text":{n+=t.text(i);break}default:{let o='Token with "'+i.type+'" type was not found.';if(this.options.silent)return console.error(o),"";throw new Error(o)}}}return n}};var P=class{options;block;constructor(e){this.options=e||T}static passThroughHooks=new Set(["preprocess","postprocess","processAllTokens","emStrongMask"]);static passThroughHooksRespectAsync=new Set(["preprocess","postprocess","processAllTokens"]);preprocess(e){return e}postprocess(e){return e}processAllTokens(e){return e}emStrongMask(e){return e}provideLexer(e=this.block){return e?x.lex:x.lexInline}provideParser(e=this.block){return e?b.parse:b.parseInline}};var C=class{defaults=_();options=this.setOptions;parse=this.parseMarkdown(!0);parseInline=this.parseMarkdown(!1);Parser=b;Renderer=y;TextRenderer=S;Lexer=x;Tokenizer=w;Hooks=P;constructor(...e){this.use(...e)}walkTokens(e,t){let n=[];for(let s of e)switch(n=n.concat(t.call(this,s)),s.type){case"table":{let r=s;for(let i of r.header)n=n.concat(this.walkTokens(i.tokens,t));for(let i of r.rows)for(let o of i)n=n.concat(this.walkTokens(o.tokens,t));break}case"list":{let r=s;n=n.concat(this.walkTokens(r.items,t));break}default:{let r=s;this.defaults.extensions?.childTokens?.[r.type]?this.defaults.extensions.childTokens[r.type].forEach(i=>{let o=r[i].flat(1/0);n=n.concat(this.walkTokens(o,t))}):r.tokens&&(n=n.concat(this.walkTokens(r.tokens,t)))}}return n}use(...e){let t=this.defaults.extensions||{renderers:{},childTokens:{}};return e.forEach(n=>{let s={...n};if(s.async=this.defaults.async||s.async||!1,n.extensions&&(n.extensions.forEach(r=>{if(!r.name)throw new Error("extension name required");if("renderer"in r){let i=t.renderers[r.name];i?t.renderers[r.name]=function(...o){let u=r.renderer.apply(this,o);return u===!1&&(u=i.apply(this,o)),u}:t.renderers[r.name]=r.renderer}if("tokenizer"in r){if(!r.level||r.level!=="block"&&r.level!=="inline")throw new Error("extension level must be 'block' or 'inline'");let i=t[r.level];i?i.unshift(r.tokenizer):t[r.level]=[r.tokenizer],r.start&&(r.level==="block"?t.startBlock?t.startBlock.push(r.start):t.startBlock=[r.start]:r.level==="inline"&&(t.startInline?t.startInline.push(r.start):t.startInline=[r.start]))}"childTokens"in r&&r.childTokens&&(t.childTokens[r.name]=r.childTokens)}),s.extensions=t),n.renderer){let r=this.defaults.renderer||new y(this.defaults);for(let i in n.renderer){if(!(i in r))throw new Error(`renderer '${i}' does not exist`);if(["options","parser"].includes(i))continue;let o=i,u=n.renderer[o],a=r[o];r[o]=(...c)=>{let p=u.apply(r,c);return p===!1&&(p=a.apply(r,c)),p||""}}s.renderer=r}if(n.tokenizer){let r=this.defaults.tokenizer||new w(this.defaults);for(let i in n.tokenizer){if(!(i in r))throw new Error(`tokenizer '${i}' does not exist`);if(["options","rules","lexer"].includes(i))continue;let o=i,u=n.tokenizer[o],a=r[o];r[o]=(...c)=>{let p=u.apply(r,c);return p===!1&&(p=a.apply(r,c)),p}}s.tokenizer=r}if(n.hooks){let r=this.defaults.hooks||new P;for(let i in n.hooks){if(!(i in r))throw new Error(`hook '${i}' does not exist`);if(["options","block"].includes(i))continue;let o=i,u=n.hooks[o],a=r[o];P.passThroughHooks.has(i)?r[o]=c=>{if(this.defaults.async&&P.passThroughHooksRespectAsync.has(i))return(async()=>{let k=await u.call(r,c);return a.call(r,k)})();let p=u.call(r,c);return a.call(r,p)}:r[o]=(...c)=>{if(this.defaults.async)return(async()=>{let k=await u.apply(r,c);return k===!1&&(k=await a.apply(r,c)),k})();let p=u.apply(r,c);return p===!1&&(p=a.apply(r,c)),p}}s.hooks=r}if(n.walkTokens){let r=this.defaults.walkTokens,i=n.walkTokens;s.walkTokens=function(o){let u=[];return u.push(i.call(this,o)),r&&(u=u.concat(r.call(this,o))),u}}this.defaults={...this.defaults,...s}}),this}setOptions(e){return this.defaults={...this.defaults,...e},this}lexer(e,t){return x.lex(e,t??this.defaults)}parser(e,t){return b.parse(e,t??this.defaults)}parseMarkdown(e){return(n,s)=>{let r={...s},i={...this.defaults,...r},o=this.onError(!!i.silent,!!i.async);if(this.defaults.async===!0&&r.async===!1)return o(new Error("marked(): The async option was set to true by an extension. Remove async: false from the parse options object to return a Promise."));if(typeof n>"u"||n===null)return o(new Error("marked(): input parameter is undefined or null"));if(typeof n!="string")return o(new Error("marked(): input parameter is of type "+Object.prototype.toString.call(n)+", string expected"));if(i.hooks&&(i.hooks.options=i,i.hooks.block=e),i.async)return(async()=>{let u=i.hooks?await i.hooks.preprocess(n):n,c=await(i.hooks?await i.hooks.provideLexer(e):e?x.lex:x.lexInline)(u,i),p=i.hooks?await i.hooks.processAllTokens(c):c;i.walkTokens&&await Promise.all(this.walkTokens(p,i.walkTokens));let h=await(i.hooks?await i.hooks.provideParser(e):e?b.parse:b.parseInline)(p,i);return i.hooks?await i.hooks.postprocess(h):h})().catch(o);try{i.hooks&&(n=i.hooks.preprocess(n));let a=(i.hooks?i.hooks.provideLexer(e):e?x.lex:x.lexInline)(n,i);i.hooks&&(a=i.hooks.processAllTokens(a)),i.walkTokens&&this.walkTokens(a,i.walkTokens);let p=(i.hooks?i.hooks.provideParser(e):e?b.parse:b.parseInline)(a,i);return i.hooks&&(p=i.hooks.postprocess(p)),p}catch(u){return o(u)}}}onError(e,t){return n=>{if(n.message+=`
+Please report this to https://github.com/markedjs/marked.`,e){let s="<p>An error occurred:</p><pre>"+O(n.message+"",!0)+"</pre>";return t?Promise.resolve(s):s}if(t)return Promise.reject(n);throw n}}};var M=new C;function g(l,e){return M.parse(l,e)}g.options=g.setOptions=function(l){return M.setOptions(l),g.defaults=M.defaults,Q(g.defaults),g};g.getDefaults=_;g.defaults=T;g.use=function(...l){return M.use(...l),g.defaults=M.defaults,Q(g.defaults),g};g.walkTokens=function(l,e){return M.walkTokens(l,e)};g.parseInline=M.parseInline;g.Parser=b;g.parser=b.parse;g.Renderer=y;g.TextRenderer=S;g.Lexer=x;g.lexer=x.lex;g.Tokenizer=w;g.Hooks=P;g.parse=g;var ht=g.options,kt=g.setOptions,dt=g.use,gt=g.walkTokens,ft=g.parseInline,mt=g,xt=b.parse,bt=x.lex;
+
+if(__exports != exports)module.exports = exports;return module.exports}));

packages/coding-agent/src/core/extensions/index.ts

@@ -0,0 +1,193 @@
+/**
+ * Extension system for lifecycle events and custom tools.
+ */
+
+export type { SlashCommandInfo, SlashCommandSource } from "../slash-commands.ts";
+export type { SourceInfo } from "../source-info.ts";
+export {
+	createExtensionRuntime,
+	discoverAndLoadExtensions,
+	loadExtensionFromFactory,
+	loadExtensions,
+} from "./loader.ts";
+export type {
+	ExtensionErrorListener,
+	ForkHandler,
+	NavigateTreeHandler,
+	NewSessionHandler,
+	ShutdownHandler,
+	SwitchSessionHandler,
+} from "./runner.ts";
+export { ExtensionRunner } from "./runner.ts";
+export type {
+	AfterProviderResponseEvent,
+	AgentEndEvent,
+	AgentSettledEvent,
+	AgentStartEvent,
+	// Re-exports
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	AppendEntryHandler,
+	// App keybindings (for custom editors)
+	AppKeybinding,
+	AutocompleteProviderFactory,
+	// Events - Tool (ToolCallEvent types)
+	BashToolCallEvent,
+	BashToolResultEvent,
+	BeforeAgentStartEvent,
+	BeforeAgentStartEventResult,
+	BeforeProviderHeadersEvent,
+	BeforeProviderRequestEvent,
+	BeforeProviderRequestEventResult,
+	BuildSystemPromptOptions,
+	// Context
+	CompactOptions,
+	// Events - Agent
+	ContextEvent,
+	// Event Results
+	ContextEventResult,
+	ContextUsage,
+	CustomToolCallEvent,
+	CustomToolResultEvent,
+	EditorFactory,
+	EditToolCallEvent,
+	EditToolResultEvent,
+	// Message and Entry Rendering
+	EntryRenderer,
+	EntryRenderOptions,
+	ExecOptions,
+	ExecResult,
+	Extension,
+	ExtensionActions,
+	// API
+	ExtensionAPI,
+	ExtensionCommandContext,
+	ExtensionCommandContextActions,
+	ExtensionContext,
+	ExtensionContextActions,
+	// Errors
+	ExtensionError,
+	ExtensionEvent,
+	ExtensionFactory,
+	ExtensionFlag,
+	ExtensionHandler,
+	ExtensionMode,
+	// Runtime
+	ExtensionRuntime,
+	ExtensionShortcut,
+	ExtensionUIContext,
+	ExtensionUIDialogOptions,
+	ExtensionWidgetOptions,
+	FindToolCallEvent,
+	FindToolResultEvent,
+	GetActiveToolsHandler,
+	GetAllToolsHandler,
+	GetCommandsHandler,
+	GetThinkingLevelHandler,
+	GrepToolCallEvent,
+	GrepToolResultEvent,
+	InlineExtension,
+	// Events - Input
+	InputEvent,
+	InputEventResult,
+	InputSource,
+	KeybindingsManager,
+	LoadExtensionsResult,
+	LsToolCallEvent,
+	LsToolResultEvent,
+	MarkdownTransformContext,
+	MarkdownTransformer,
+	// Events - Message
+	MessageEndEvent,
+	MessageRenderer,
+	MessageRenderOptions,
+	MessageStartEvent,
+	MessageUpdateEvent,
+	ModelSelectEvent,
+	ModelSelectSource,
+	PowerShellToolCallEvent,
+	PowerShellToolResultEvent,
+	ProjectTrustContext,
+	ProjectTrustEvent,
+	ProjectTrustEventDecision,
+	ProjectTrustEventResult,
+	ProjectTrustHandler,
+	// Provider Registration
+	ProviderConfig,
+	ProviderModelConfig,
+	ReadToolCallEvent,
+	ReadToolResultEvent,
+	// Commands
+	RegisteredCommand,
+	RegisteredTool,
+	ReplacedSessionContext,
+	ResolvedCommand,
+	// Events - Resources
+	ResourcesDiscoverEvent,
+	ResourcesDiscoverResult,
+	SendMessageHandler,
+	SendUserMessageHandler,
+	SessionBeforeCompactEvent,
+	SessionBeforeCompactResult,
+	SessionBeforeForkEvent,
+	SessionBeforeForkResult,
+	SessionBeforeSwitchEvent,
+	SessionBeforeSwitchResult,
+	SessionBeforeTreeEvent,
+	SessionBeforeTreeResult,
+	SessionCompactEvent,
+	SessionCompactFailedEvent,
+	SessionEvent,
+	SessionInfoChangedEvent,
+	SessionShutdownEvent,
+	// Events - Session
+	SessionStartEvent,
+	SessionTreeEvent,
+	SetActiveToolsHandler,
+	SetLabelHandler,
+	SetModelHandler,
+	SetThinkingLevelHandler,
+	TerminalInputHandler,
+	// Events - Tool
+	ToolCallEvent,
+	ToolCallEventResult,
+	// Tools
+	ToolDefinition,
+	// Events - Tool Execution
+	ToolExecutionEndEvent,
+	// Tool execution mode
+	ToolExecutionMode,
+	ToolExecutionStartEvent,
+	ToolExecutionUpdateEvent,
+	ToolInfo,
+	ToolRenderResultOptions,
+	ToolResultEvent,
+	ToolResultEventResult,
+	TreePreparation,
+	TurnEndEvent,
+	TurnStartEvent,
+	UIPromptEndEvent,
+	UIPromptKind,
+	UIPromptStartEvent,
+	// Events - User Bash
+	UserBashEvent,
+	UserBashEventResult,
+	WidgetPlacement,
+	WorkingIndicatorOptions,
+	WriteToolCallEvent,
+	WriteToolResultEvent,
+} from "./types.ts";
+// Type guards
+export {
+	defineTool,
+	isBashToolResult,
+	isEditToolResult,
+	isFindToolResult,
+	isGrepToolResult,
+	isLsToolResult,
+	isPowerShellToolResult,
+	isReadToolResult,
+	isToolCallEventType,
+	isWriteToolResult,
+} from "./types.ts";
+export { wrapRegisteredTool, wrapRegisteredTools } from "./wrapper.ts";

packages/coding-agent/src/core/extensions/loader.ts

@@ -0,0 +1,809 @@
+/**
+ * Extension loader - loads TypeScript extension modules using jiti.
+ *
+ */
+
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as _bundledPiAgentCore from "@earendil-works/pi-agent-core";
+import type { Provider } from "@earendil-works/pi-ai";
+import * as _bundledPiAiCompat from "@earendil-works/pi-ai/compat";
+import * as _bundledPiAiOauth from "@earendil-works/pi-ai/oauth";
+import * as _bundledPiAiProviders from "@earendil-works/pi-ai/providers/all";
+import type { KeyId } from "@earendil-works/pi-tui";
+import * as _bundledPiTui from "@earendil-works/pi-tui";
+import { createJiti } from "jiti/static";
+// Static imports of packages that extensions may use.
+// These MUST be static so Bun bundles them into the compiled binary.
+// The virtualModules option then makes them available to extensions.
+import * as _bundledTypebox from "typebox";
+import * as _bundledTypeboxCompile from "typebox/compile";
+import * as _bundledTypeboxValue from "typebox/value";
+import { CONFIG_DIR_NAME, getAgentDir, isBunBinary, isBundledNode } from "../../config.ts";
+// NOTE: This import works because loader.ts exports are NOT re-exported from index.ts,
+// avoiding a circular dependency. Extensions can import from @earendil-works/pi-coding-agent.
+import * as _bundledPiCodingAgent from "../../index.ts";
+import { resolvePath } from "../../utils/paths.ts";
+import { createEventBus, type EventBus } from "../event-bus.ts";
+import type { ExecOptions } from "../exec.ts";
+import { execCommand } from "../exec.ts";
+import { readPiManifest } from "../pi-manifest.ts";
+import { createSyntheticSourceInfo } from "../source-info.ts";
+import { time } from "../timings.ts";
+import type {
+	EntryRenderer,
+	Extension,
+	ExtensionAPI,
+	ExtensionFactory,
+	ExtensionRuntime,
+	LoadExtensionsResult,
+	MarkdownTransformer,
+	MessageRenderer,
+	ProviderConfig,
+	RegisteredCommand,
+	ToolDefinition,
+} from "./types.ts";
+
+/** Modules available to extensions via virtualModules (for compiled binaries) */
+const VIRTUAL_MODULES: Record<string, unknown> = {
+	typebox: _bundledTypebox,
+	"typebox/compile": _bundledTypeboxCompile,
+	"typebox/value": _bundledTypeboxValue,
+	"@sinclair/typebox": _bundledTypebox,
+	"@sinclair/typebox/compile": _bundledTypeboxCompile,
+	"@sinclair/typebox/value": _bundledTypeboxValue,
+	"@earendil-works/pi-agent-core": _bundledPiAgentCore,
+	"@earendil-works/pi-tui": _bundledPiTui,
+	// Extensions resolve the pi-ai root to the compat entrypoint (a strict
+	// superset of the core entrypoint): existing extensions using the old
+	// global API keep working at runtime until compat is removed.
+	"@earendil-works/pi-ai": _bundledPiAiCompat,
+	"@earendil-works/pi-ai/compat": _bundledPiAiCompat,
+	"@earendil-works/pi-ai/oauth": _bundledPiAiOauth,
+	"@earendil-works/pi-ai/providers/all": _bundledPiAiProviders,
+	"@earendil-works/pi-coding-agent": _bundledPiCodingAgent,
+	"@mariozechner/pi-agent-core": _bundledPiAgentCore,
+	"@mariozechner/pi-tui": _bundledPiTui,
+	"@mariozechner/pi-ai": _bundledPiAiCompat,
+	"@mariozechner/pi-ai/compat": _bundledPiAiCompat,
+	"@mariozechner/pi-ai/oauth": _bundledPiAiOauth,
+	"@mariozechner/pi-ai/providers/all": _bundledPiAiProviders,
+	"@mariozechner/pi-coding-agent": _bundledPiCodingAgent,
+};
+
+const require = createRequire(import.meta.url);
+
+const isNodeSeaBinary =
+	("sea" in process.features && process.features.sea === true) ||
+	process.getBuiltinModule("node:sea")?.isSea() === true;
+const isTypeScriptSourceRuntime = !isBunBinary && path.extname(fileURLToPath(import.meta.url)) === ".ts";
+
+/**
+ * Get aliases for jiti (used in built Node.js mode).
+ * In compiled binary mode, virtualModules is used instead.
+ */
+let _aliases: Record<string, string> | null = null;
+
+function getAliases(): Record<string, string> {
+	if (_aliases) return _aliases;
+
+	const __dirname = path.dirname(fileURLToPath(import.meta.url));
+	const packageIndex = path.resolve(__dirname, "../..", "index.js");
+
+	const typeboxEntry = require.resolve("typebox");
+	const typeboxCompileEntry = require.resolve("typebox/compile");
+	const typeboxValueEntry = require.resolve("typebox/value");
+
+	const packagesRoot = path.resolve(__dirname, "../../../../");
+	const resolveWorkspaceOrImport = (workspaceRelativePath: string, specifier: string): string => {
+		const workspacePath = path.join(packagesRoot, workspaceRelativePath);
+		if (fs.existsSync(workspacePath)) {
+			return workspacePath;
+		}
+		return fileURLToPath(import.meta.resolve(specifier));
+	};
+
+	const piCodingAgentEntry = packageIndex;
+	const piAgentCoreEntry = resolveWorkspaceOrImport("agent/dist/index.js", "@earendil-works/pi-agent-core");
+	const piTuiEntry = resolveWorkspaceOrImport("tui/dist/index.js", "@earendil-works/pi-tui");
+	// Extensions resolve the pi-ai root to the compat entrypoint (a strict
+	// superset of the core entrypoint): existing extensions using the old
+	// global API keep working at runtime until compat is removed.
+	const piAiCompatEntry = resolveWorkspaceOrImport("ai/dist/compat.js", "@earendil-works/pi-ai/compat");
+	const piAiOauthEntry = resolveWorkspaceOrImport("ai/dist/oauth.js", "@earendil-works/pi-ai/oauth");
+	const piAiProvidersEntry = resolveWorkspaceOrImport(
+		"ai/dist/providers/all.js",
+		"@earendil-works/pi-ai/providers/all",
+	);
+
+	_aliases = {
+		"@earendil-works/pi-coding-agent": piCodingAgentEntry,
+		"@earendil-works/pi-agent-core": piAgentCoreEntry,
+		"@earendil-works/pi-tui": piTuiEntry,
+		"@earendil-works/pi-ai/providers/all": piAiProvidersEntry,
+		"@earendil-works/pi-ai/compat": piAiCompatEntry,
+		"@earendil-works/pi-ai/oauth": piAiOauthEntry,
+		"@earendil-works/pi-ai": piAiCompatEntry,
+		"@mariozechner/pi-coding-agent": piCodingAgentEntry,
+		"@mariozechner/pi-agent-core": piAgentCoreEntry,
+		"@mariozechner/pi-tui": piTuiEntry,
+		"@mariozechner/pi-ai/providers/all": piAiProvidersEntry,
+		"@mariozechner/pi-ai/compat": piAiCompatEntry,
+		"@mariozechner/pi-ai/oauth": piAiOauthEntry,
+		"@mariozechner/pi-ai": piAiCompatEntry,
+		typebox: typeboxEntry,
+		"typebox/compile": typeboxCompileEntry,
+		"typebox/value": typeboxValueEntry,
+		"@sinclair/typebox": typeboxEntry,
+		"@sinclair/typebox/compile": typeboxCompileEntry,
+		"@sinclair/typebox/value": typeboxValueEntry,
+	};
+
+	return _aliases;
+}
+
+type HandlerFn = (...args: unknown[]) => Promise<unknown>;
+
+let extensionCacheCwd: string | undefined;
+let extensionCacheGeneration = 0;
+const extensionCache = new Map<string, ExtensionFactory>();
+
+interface ExtensionCacheToken {
+	cwd: string;
+	generation: number;
+}
+
+export function clearExtensionCache(): void {
+	extensionCache.clear();
+	extensionCacheCwd = undefined;
+	extensionCacheGeneration++;
+}
+
+function useExtensionCacheCwd(cwd: string): ExtensionCacheToken {
+	const resolvedCwd = resolvePath(cwd);
+	if (extensionCacheCwd !== undefined && extensionCacheCwd !== resolvedCwd) {
+		clearExtensionCache();
+	}
+	extensionCacheCwd = resolvedCwd;
+	return { cwd: resolvedCwd, generation: extensionCacheGeneration };
+}
+
+/**
+ * Create a runtime with throwing stubs for action methods.
+ * Runner.bindCore() replaces these with real implementations.
+ */
+export function createExtensionRuntime(): ExtensionRuntime {
+	const notInitialized = () => {
+		throw new Error("Extension runtime not initialized. Action methods cannot be called during extension loading.");
+	};
+	const state: { staleMessage?: string } = {};
+	const eventBusUnsubscribers = new Set<() => void>();
+	const assertActive = () => {
+		if (state.staleMessage) {
+			throw new Error(state.staleMessage);
+		}
+	};
+
+	const runtime: ExtensionRuntime = {
+		sendMessage: notInitialized,
+		sendUserMessage: notInitialized,
+		appendEntry: notInitialized,
+		setSessionName: notInitialized,
+		getSessionName: notInitialized,
+		setLabel: notInitialized,
+		getActiveTools: notInitialized,
+		getAllTools: notInitialized,
+		setActiveTools: notInitialized,
+		// registerTool() is valid during extension load; refresh is only needed post-bind.
+		refreshTools: () => {},
+		getCommands: notInitialized,
+		setModel: () => Promise.reject(new Error("Extension runtime not initialized")),
+		getThinkingLevel: notInitialized,
+		setThinkingLevel: notInitialized,
+		flagValues: new Map(),
+		pendingProviderRegistrations: [],
+		pendingNativeProviderRegistrations: [],
+		assertActive,
+		invalidate: (message) => {
+			if (state.staleMessage) return;
+			state.staleMessage =
+				message ??
+				"This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().";
+			for (const unsubscribe of eventBusUnsubscribers) unsubscribe();
+			eventBusUnsubscribers.clear();
+		},
+		trackEventBusSubscription: (unsubscribe) => {
+			let active = true;
+			const trackedUnsubscribe = () => {
+				if (!active) return;
+				active = false;
+				eventBusUnsubscribers.delete(trackedUnsubscribe);
+				unsubscribe();
+			};
+			eventBusUnsubscribers.add(trackedUnsubscribe);
+			return trackedUnsubscribe;
+		},
+		// Pre-bind: queue registrations so bindCore() can flush them once the
+		// model registry is available. bindCore() replaces both with direct calls.
+		registerProvider: (name, config, extensionPath = "<unknown>") => {
+			runtime.pendingProviderRegistrations.push({ name, config, extensionPath });
+		},
+		registerNativeProvider: (provider, extensionPath = "<unknown>") => {
+			runtime.pendingNativeProviderRegistrations.push({ provider, extensionPath });
+		},
+		unregisterProvider: (name) => {
+			runtime.pendingProviderRegistrations = runtime.pendingProviderRegistrations.filter((r) => r.name !== name);
+			runtime.pendingNativeProviderRegistrations = runtime.pendingNativeProviderRegistrations.filter(
+				(r) => r.provider.id !== name,
+			);
+		},
+	};
+
+	return runtime;
+}
+
+/**
+ * Create the ExtensionAPI for an extension.
+ * Registration methods write to the extension object.
+ * Action methods delegate to the shared runtime.
+ */
+function createExtensionAPI(
+	extension: Extension,
+	runtime: ExtensionRuntime,
+	cwd: string,
+	eventBus: EventBus,
+): { api: ExtensionAPI; commit: () => void; discard: () => void } {
+	const pendingFlagValues = new Map<string, boolean | string>();
+	const pendingRuntimeChanges: Array<() => void> = [];
+	const loadingUnsubscribers: Array<() => void> = [];
+	let state: "loading" | "active" | "failed" = "loading";
+	const assertActive = () => {
+		if (state === "failed") {
+			throw new Error(`Extension "${extension.path}" failed to load and its API is no longer active.`);
+		}
+		runtime.assertActive();
+	};
+	const applyRuntimeChange = (change: () => void) => {
+		if (state === "loading") pendingRuntimeChanges.push(change);
+		else change();
+	};
+	const clearPending = () => {
+		pendingFlagValues.clear();
+		pendingRuntimeChanges.length = 0;
+		loadingUnsubscribers.length = 0;
+	};
+
+	const api = {
+		// Registration methods - write to extension
+		on(event: string, handler: HandlerFn): void {
+			assertActive();
+			const list = extension.handlers.get(event) ?? [];
+			list.push(handler);
+			extension.handlers.set(event, list);
+		},
+
+		registerTool(tool: ToolDefinition): void {
+			assertActive();
+			if (typeof tool.parameters !== "object" || tool.parameters === null || Array.isArray(tool.parameters)) {
+				throw new Error(
+					`Tool "${tool.name}" registered by extension "${extension.path}" must define an object parameter schema.`,
+				);
+			}
+			extension.tools.set(tool.name, {
+				definition: tool,
+				sourceInfo: extension.sourceInfo,
+			});
+			runtime.refreshTools();
+		},
+
+		registerCommand(name: string, options: Omit<RegisteredCommand, "name" | "sourceInfo">): void {
+			assertActive();
+			extension.commands.set(name, {
+				name,
+				sourceInfo: extension.sourceInfo,
+				...options,
+			});
+		},
+
+		registerShortcut(
+			shortcut: KeyId,
+			options: {
+				description?: string;
+				handler: (ctx: import("./types.ts").ExtensionContext) => Promise<void> | void;
+			},
+		): void {
+			assertActive();
+			extension.shortcuts.set(shortcut, { shortcut, extensionPath: extension.path, ...options });
+		},
+
+		registerFlag(
+			name: string,
+			options: { description?: string; type: "boolean" | "string"; default?: boolean | string },
+		): void {
+			assertActive();
+			if (options.default !== undefined && typeof options.default !== options.type) {
+				throw new Error(
+					`Invalid default for flag "${name}": expected ${options.type}, got ${typeof options.default}`,
+				);
+			}
+			extension.flags.set(name, { name, extensionPath: extension.path, ...options });
+			if (options.default !== undefined && !runtime.flagValues.has(name)) {
+				if (state === "loading") {
+					if (!pendingFlagValues.has(name)) pendingFlagValues.set(name, options.default);
+				} else {
+					runtime.flagValues.set(name, options.default);
+				}
+			}
+		},
+
+		registerMessageRenderer<T>(customType: string, renderer: MessageRenderer<T>): void {
+			assertActive();
+			extension.messageRenderers.set(customType, renderer as MessageRenderer);
+		},
+
+		registerMarkdownTransformer(transformer: MarkdownTransformer): void {
+			assertActive();
+			extension.markdownTransformer = transformer;
+		},
+
+		registerEntryRenderer<T>(customType: string, renderer: EntryRenderer<T>): void {
+			assertActive();
+			extension.entryRenderers ??= new Map();
+			extension.entryRenderers.set(customType, renderer as EntryRenderer);
+		},
+
+		// Flag access - checks extension registered it, reads from runtime
+		getFlag(name: string): boolean | string | undefined {
+			assertActive();
+			if (!extension.flags.has(name)) return undefined;
+			return runtime.flagValues.has(name) ? runtime.flagValues.get(name) : pendingFlagValues.get(name);
+		},
+
+		// Action methods - delegate to shared runtime
+		sendMessage(message, options): void {
+			assertActive();
+			runtime.sendMessage(message, options);
+		},
+
+		sendUserMessage(content, options): void {
+			assertActive();
+			runtime.sendUserMessage(content, options);
+		},
+
+		appendEntry(customType: string, data?: unknown): void {
+			assertActive();
+			runtime.appendEntry(customType, data);
+		},
+
+		setSessionName(name: string): void {
+			assertActive();
+			runtime.setSessionName(name);
+		},
+
+		getSessionName(): string | undefined {
+			assertActive();
+			return runtime.getSessionName();
+		},
+
+		setLabel(entryId: string, label: string | undefined): void {
+			assertActive();
+			runtime.setLabel(entryId, label);
+		},
+
+		exec(command: string, args: string[], options?: ExecOptions) {
+			assertActive();
+			return execCommand(command, args, options?.cwd ?? cwd, options);
+		},
+
+		getActiveTools(): string[] {
+			assertActive();
+			return runtime.getActiveTools();
+		},
+
+		getAllTools() {
+			assertActive();
+			return runtime.getAllTools();
+		},
+
+		setActiveTools(toolNames: string[]): void {
+			assertActive();
+			runtime.setActiveTools(toolNames);
+		},
+
+		getCommands() {
+			assertActive();
+			return runtime.getCommands();
+		},
+
+		setModel(model) {
+			assertActive();
+			return runtime.setModel(model);
+		},
+
+		getThinkingLevel() {
+			assertActive();
+			return runtime.getThinkingLevel();
+		},
+
+		setThinkingLevel(level) {
+			assertActive();
+			runtime.setThinkingLevel(level);
+		},
+
+		registerProvider(providerOrName: Provider | string, config?: ProviderConfig) {
+			assertActive();
+			if (typeof providerOrName === "string") {
+				if (!config) throw new Error("Provider config is required when registering by name");
+				applyRuntimeChange(() => runtime.registerProvider(providerOrName, config, extension.path));
+				return;
+			}
+			applyRuntimeChange(() => runtime.registerNativeProvider(providerOrName, extension.path));
+		},
+
+		unregisterProvider(name: string) {
+			assertActive();
+			applyRuntimeChange(() => runtime.unregisterProvider(name, extension.path));
+		},
+
+		events: {
+			emit(channel, data) {
+				assertActive();
+				eventBus.emit(channel, data);
+			},
+			on(channel, handler) {
+				assertActive();
+				const unsubscribe = runtime.trackEventBusSubscription(eventBus.on(channel, handler));
+				if (state === "loading") loadingUnsubscribers.push(unsubscribe);
+				return unsubscribe;
+			},
+		},
+	} as ExtensionAPI;
+
+	return {
+		api,
+		commit: () => {
+			if (state !== "loading") return;
+			runtime.assertActive();
+			for (const [name, value] of pendingFlagValues) {
+				if (!runtime.flagValues.has(name)) runtime.flagValues.set(name, value);
+			}
+			for (const apply of pendingRuntimeChanges) apply();
+			state = "active";
+			clearPending();
+		},
+		discard: () => {
+			if (state !== "loading") return;
+			state = "failed";
+			for (const unsubscribe of loadingUnsubscribers) unsubscribe();
+			clearPending();
+		},
+	};
+}
+
+function isCurrentCacheToken(cacheToken: ExtensionCacheToken | undefined): cacheToken is ExtensionCacheToken {
+	return (
+		cacheToken !== undefined &&
+		extensionCacheCwd === cacheToken.cwd &&
+		extensionCacheGeneration === cacheToken.generation
+	);
+}
+
+async function loadExtensionModule(extensionPath: string, cacheToken?: ExtensionCacheToken) {
+	if (isCurrentCacheToken(cacheToken)) {
+		const cachedFactory = extensionCache.get(extensionPath);
+		if (cachedFactory) {
+			return cachedFactory;
+		}
+	}
+
+	const jiti = createJiti(import.meta.url, {
+		moduleCache: false,
+		// Compiled binaries and the bundled Node distribution use embedded modules.
+		// Source TypeScript reuses host modules and root tsconfig paths. Unbundled
+		// Node builds use dist aliases.
+		...(isBunBinary || isNodeSeaBinary || isBundledNode
+			? { virtualModules: VIRTUAL_MODULES, tryNative: false }
+			: isTypeScriptSourceRuntime
+				? { virtualModules: VIRTUAL_MODULES, tsconfigPaths: true }
+				: { alias: getAliases() }),
+	});
+
+	const module = await jiti.import(extensionPath, { default: true });
+	const factory = module as ExtensionFactory;
+	if (typeof factory !== "function") {
+		return undefined;
+	}
+	if (isCurrentCacheToken(cacheToken)) {
+		extensionCache.set(extensionPath, factory);
+	}
+	return factory;
+}
+
+/**
+ * Create an Extension object with empty collections.
+ */
+function createExtension(extensionPath: string, resolvedPath: string): Extension {
+	const source =
+		extensionPath.startsWith("<") && extensionPath.endsWith(">")
+			? extensionPath.slice(1, -1).split(":")[0] || "temporary"
+			: "local";
+	const baseDir = extensionPath.startsWith("<") ? undefined : path.dirname(resolvedPath);
+
+	return {
+		path: extensionPath,
+		resolvedPath,
+		sourceInfo: createSyntheticSourceInfo(extensionPath, { source, baseDir }),
+		handlers: new Map(),
+		tools: new Map(),
+		messageRenderers: new Map(),
+		entryRenderers: new Map(),
+		commands: new Map(),
+		flags: new Map(),
+		shortcuts: new Map(),
+	};
+}
+
+async function initializeExtension(
+	factory: ExtensionFactory,
+	extensionPath: string,
+	resolvedPath: string,
+	cwd: string,
+	eventBus: EventBus,
+	runtime: ExtensionRuntime,
+): Promise<Extension> {
+	const extension = createExtension(extensionPath, resolvedPath);
+	const load = createExtensionAPI(extension, runtime, cwd, eventBus);
+	try {
+		await factory(load.api);
+		load.commit();
+	} catch (error) {
+		load.discard();
+		throw error;
+	}
+	time(`${extensionPath} factory`, "extensions");
+	return extension;
+}
+
+async function loadExtension(
+	extensionPath: string,
+	cwd: string,
+	eventBus: EventBus,
+	runtime: ExtensionRuntime,
+	cacheToken?: ExtensionCacheToken,
+): Promise<{ extension: Extension | null; error: string | null }> {
+	const resolvedPath = resolvePath(extensionPath, cwd, { normalizeUnicodeSpaces: true });
+
+	try {
+		const factory = await loadExtensionModule(resolvedPath, cacheToken);
+		time(`${extensionPath} module import`, "extensions");
+		if (!factory) {
+			return { extension: null, error: `Extension does not export a valid factory function: ${extensionPath}` };
+		}
+
+		const extension = await initializeExtension(factory, extensionPath, resolvedPath, cwd, eventBus, runtime);
+
+		return { extension, error: null };
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { extension: null, error: `Failed to load extension: ${message}` };
+	}
+}
+
+/**
+ * Create an Extension from an inline factory function.
+ */
+export async function loadExtensionFromFactory(
+	factory: ExtensionFactory,
+	cwd: string,
+	eventBus: EventBus,
+	runtime: ExtensionRuntime,
+	extensionPath = "<inline>",
+): Promise<Extension> {
+	const resolvedCwd = resolvePath(cwd);
+	return initializeExtension(factory, extensionPath, extensionPath, resolvedCwd, eventBus, runtime);
+}
+
+/**
+ * Load extensions from paths.
+ */
+async function loadExtensionsInternal(
+	paths: string[],
+	cwd: string,
+	eventBus?: EventBus,
+	runtime?: ExtensionRuntime,
+	useCache = false,
+): Promise<LoadExtensionsResult> {
+	const extensions: Extension[] = [];
+	const errors: Array<{ path: string; error: string }> = [];
+	const cacheToken = useCache ? useExtensionCacheCwd(cwd) : undefined;
+	const resolvedCwd = cacheToken?.cwd ?? resolvePath(cwd);
+	const resolvedEventBus = eventBus ?? createEventBus();
+	const resolvedRuntime = runtime ?? createExtensionRuntime();
+
+	for (const extPath of paths) {
+		const { extension, error } = await loadExtension(
+			extPath,
+			resolvedCwd,
+			resolvedEventBus,
+			resolvedRuntime,
+			cacheToken,
+		);
+
+		if (error) {
+			errors.push({ path: extPath, error });
+			continue;
+		}
+
+		if (extension) {
+			extensions.push(extension);
+		}
+	}
+
+	return {
+		extensions,
+		errors,
+		runtime: resolvedRuntime,
+	};
+}
+
+export async function loadExtensions(
+	paths: string[],
+	cwd: string,
+	eventBus?: EventBus,
+	runtime?: ExtensionRuntime,
+): Promise<LoadExtensionsResult> {
+	return loadExtensionsInternal(paths, cwd, eventBus, runtime);
+}
+
+export async function loadExtensionsCached(
+	paths: string[],
+	cwd: string,
+	eventBus?: EventBus,
+	runtime?: ExtensionRuntime,
+): Promise<LoadExtensionsResult> {
+	return loadExtensionsInternal(paths, cwd, eventBus, runtime, true);
+}
+
+function isExtensionFile(name: string): boolean {
+	return name.endsWith(".ts") || name.endsWith(".js");
+}
+
+/**
+ * Resolve extension entry points from a directory.
+ *
+ * Checks for:
+ * 1. package.json with "pi.extensions" field -> returns declared paths
+ * 2. index.ts or index.js -> returns the index file
+ *
+ * Returns resolved paths or null if no entry points found.
+ */
+function resolveExtensionEntries(dir: string): string[] | null {
+	// Check for package.json with "pi" field first
+	const packageJsonPath = path.join(dir, "package.json");
+	if (fs.existsSync(packageJsonPath)) {
+		const manifest = readPiManifest(packageJsonPath);
+		if (manifest?.extensions?.length) {
+			const entries: string[] = [];
+			for (const extPath of manifest.extensions) {
+				const resolvedExtPath = path.resolve(dir, extPath);
+				if (fs.existsSync(resolvedExtPath)) {
+					entries.push(resolvedExtPath);
+				}
+			}
+			if (entries.length > 0) {
+				return entries;
+			}
+		}
+	}
+
+	// Check for index.ts or index.js
+	const indexTs = path.join(dir, "index.ts");
+	const indexJs = path.join(dir, "index.js");
+	if (fs.existsSync(indexTs)) {
+		return [indexTs];
+	}
+	if (fs.existsSync(indexJs)) {
+		return [indexJs];
+	}
+
+	return null;
+}
+
+/**
+ * Discover extensions in a directory.
+ *
+ * Discovery rules:
+ * 1. Direct files: `extensions/*.ts` or `*.js` → load
+ * 2. Subdirectory with index: `extensions/* /index.ts` or `index.js` → load
+ * 3. Subdirectory with package.json: `extensions/* /package.json` with "pi" field → load what it declares
+ *
+ * No recursion beyond one level. Complex packages must use package.json manifest.
+ */
+function discoverExtensionsInDir(dir: string): string[] {
+	if (!fs.existsSync(dir)) {
+		return [];
+	}
+
+	const discovered: string[] = [];
+
+	try {
+		const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+		for (const entry of entries) {
+			const entryPath = path.join(dir, entry.name);
+
+			// 1. Direct files: *.ts or *.js
+			if ((entry.isFile() || entry.isSymbolicLink()) && isExtensionFile(entry.name)) {
+				discovered.push(entryPath);
+				continue;
+			}
+
+			// 2 & 3. Subdirectories
+			if (entry.isDirectory() || entry.isSymbolicLink()) {
+				const entries = resolveExtensionEntries(entryPath);
+				if (entries) {
+					discovered.push(...entries);
+				}
+			}
+		}
+	} catch {
+		return [];
+	}
+
+	return discovered;
+}
+
+/**
+ * Discover and load extensions from standard locations.
+ */
+export async function discoverAndLoadExtensions(
+	configuredPaths: string[],
+	cwd: string,
+	agentDir: string = getAgentDir(),
+	eventBus?: EventBus,
+): Promise<LoadExtensionsResult> {
+	const resolvedCwd = resolvePath(cwd);
+	const resolvedAgentDir = resolvePath(agentDir);
+	const allPaths: string[] = [];
+	const seen = new Set<string>();
+
+	const addPaths = (paths: string[]) => {
+		for (const p of paths) {
+			const resolved = path.resolve(p);
+			if (!seen.has(resolved)) {
+				seen.add(resolved);
+				allPaths.push(p);
+			}
+		}
+	};
+
+	// 1. Project-local extensions: cwd/${CONFIG_DIR_NAME}/extensions/
+	const localExtDir = path.join(resolvedCwd, CONFIG_DIR_NAME, "extensions");
+	addPaths(discoverExtensionsInDir(localExtDir));
+
+	// 2. Global extensions: agentDir/extensions/
+	const globalExtDir = path.join(resolvedAgentDir, "extensions");
+	addPaths(discoverExtensionsInDir(globalExtDir));
+
+	// 3. Explicitly configured paths
+	for (const p of configuredPaths) {
+		const resolved = resolvePath(p, resolvedCwd, { normalizeUnicodeSpaces: true });
+		if (fs.existsSync(resolved) && fs.statSync(resolved).isDirectory()) {
+			// Check for package.json with pi manifest or index.ts
+			const entries = resolveExtensionEntries(resolved);
+			if (entries) {
+				addPaths(entries);
+				continue;
+			}
+			// No explicit entries - discover individual files in directory
+			addPaths(discoverExtensionsInDir(resolved));
+			continue;
+		}
+
+		addPaths([resolved]);
+	}
+
+	return loadExtensions(allPaths, resolvedCwd, eventBus);
+}

packages/coding-agent/src/core/extensions/runner.ts

@@ -0,0 +1,1286 @@
+/**
+ * Extension runner - executes extensions and manages their lifecycle.
+ */
+
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { ImageContent, Model, Provider, ProviderHeaders } from "@earendil-works/pi-ai";
+import type { KeyId } from "@earendil-works/pi-tui";
+import { type Theme, theme } from "../../modes/interactive/theme/theme.ts";
+import type { ResourceDiagnostic } from "../diagnostics.ts";
+import type { KeybindingsConfig } from "../keybindings.ts";
+import type { ModelRegistry } from "../model-registry.ts";
+import type { ScopedModel } from "../model-resolver.ts";
+import type { SessionManager } from "../session-manager.ts";
+import type { BuildSystemPromptOptions } from "../system-prompt.ts";
+import type {
+	BeforeAgentStartEvent,
+	BeforeAgentStartEventResult,
+	BeforeProviderHeadersEvent,
+	BeforeProviderRequestEvent,
+	CompactOptions,
+	ContextEvent,
+	ContextEventResult,
+	ContextUsage,
+	EntryRenderer,
+	Extension,
+	ExtensionActions,
+	ExtensionCommandContext,
+	ExtensionCommandContextActions,
+	ExtensionContext,
+	ExtensionContextActions,
+	ExtensionError,
+	ExtensionEvent,
+	ExtensionFlag,
+	ExtensionMode,
+	ExtensionRuntime,
+	ExtensionShortcut,
+	ExtensionUIContext,
+	InputEvent,
+	InputEventResult,
+	InputSource,
+	LoadExtensionsResult,
+	MarkdownTransformer,
+	MessageEndEvent,
+	MessageEndEventResult,
+	MessageRenderer,
+	ProjectTrustContext,
+	ProjectTrustEvent,
+	ProjectTrustEventResult,
+	ProviderConfig,
+	RegisteredCommand,
+	RegisteredTool,
+	ReplacedSessionContext,
+	ResolvedCommand,
+	ResourcesDiscoverEvent,
+	ResourcesDiscoverResult,
+	SessionBeforeCompactResult,
+	SessionBeforeForkResult,
+	SessionBeforeSwitchResult,
+	SessionBeforeTreeResult,
+	SessionShutdownEvent,
+	ToolCallEvent,
+	ToolCallEventResult,
+	ToolResultEvent,
+	ToolResultEventResult,
+	UIPromptKind,
+	UserBashEvent,
+	UserBashEventResult,
+} from "./types.ts";
+
+// Extension shortcuts compete with canonical keybinding ids from keybindings.json.
+// Only editor-global shortcuts are reserved here. Picker-specific bindings are not.
+const RESERVED_KEYBINDINGS_FOR_EXTENSION_CONFLICTS = [
+	"app.interrupt",
+	"app.clear",
+	"app.exit",
+	"app.suspend",
+	"app.thinking.cycle",
+	"app.model.cycleForward",
+	"app.model.cycleBackward",
+	"app.model.select",
+	"app.tools.expand",
+	"app.thinking.toggle",
+	"app.editor.external",
+	"app.message.copy",
+	"app.message.followUp",
+	"tui.input.submit",
+	"tui.select.confirm",
+	"tui.select.cancel",
+	"tui.input.copy",
+	"tui.editor.deleteToLineEnd",
+] as const;
+
+type BuiltInKeyBindings = Partial<Record<KeyId, { keybinding: string; restrictOverride: boolean }>>;
+
+const buildBuiltinKeybindings = (resolvedKeybindings: KeybindingsConfig): BuiltInKeyBindings => {
+	const builtinKeybindings = {} as BuiltInKeyBindings;
+	for (const [keybinding, keys] of Object.entries(resolvedKeybindings)) {
+		if (keys === undefined) continue;
+		const keyList = Array.isArray(keys) ? keys : [keys];
+		const restrictOverride = (RESERVED_KEYBINDINGS_FOR_EXTENSION_CONFLICTS as readonly string[]).includes(keybinding);
+		for (const key of keyList) {
+			const normalizedKey = key.toLowerCase() as KeyId;
+			// If multiple actions bind the same key, the reserved action wins so extensions
+			// remain blocked by reserved shortcuts regardless of iteration order.
+			const existing = builtinKeybindings[normalizedKey];
+			if (existing?.restrictOverride && !restrictOverride) continue;
+			builtinKeybindings[normalizedKey] = {
+				keybinding,
+				restrictOverride,
+			};
+		}
+	}
+	return builtinKeybindings;
+};
+
+/** Combined result from all before_agent_start handlers */
+interface BeforeAgentStartCombinedResult {
+	messages?: NonNullable<BeforeAgentStartEventResult["message"]>[];
+	systemPrompt?: string;
+}
+
+/**
+ * Events handled by the generic emit() method.
+ * Events with dedicated emitXxx() methods are excluded for stronger type safety.
+ */
+type RunnerEmitEvent = Exclude<
+	ExtensionEvent,
+	| ToolCallEvent
+	| ProjectTrustEvent
+	| ToolResultEvent
+	| UserBashEvent
+	| ContextEvent
+	| BeforeProviderRequestEvent
+	| BeforeProviderHeadersEvent
+	| BeforeAgentStartEvent
+	| MessageEndEvent
+	| ResourcesDiscoverEvent
+	| InputEvent
+>;
+
+type SessionBeforeEvent = Extract<
+	RunnerEmitEvent,
+	{ type: "session_before_switch" | "session_before_fork" | "session_before_compact" | "session_before_tree" }
+>;
+
+type SessionBeforeEventResult =
+	| SessionBeforeSwitchResult
+	| SessionBeforeForkResult
+	| SessionBeforeCompactResult
+	| SessionBeforeTreeResult;
+
+type RunnerEmitResult<TEvent extends RunnerEmitEvent> = TEvent extends { type: "session_before_switch" }
+	? SessionBeforeSwitchResult | undefined
+	: TEvent extends { type: "session_before_fork" }
+		? SessionBeforeForkResult | undefined
+		: TEvent extends { type: "session_before_compact" }
+			? SessionBeforeCompactResult | undefined
+			: TEvent extends { type: "session_before_tree" }
+				? SessionBeforeTreeResult | undefined
+				: undefined;
+
+export type ExtensionErrorListener = (error: ExtensionError) => void;
+
+export type NewSessionHandler = (options?: {
+	parentSession?: string;
+	setup?: (sessionManager: SessionManager) => Promise<void>;
+	withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+}) => Promise<{ cancelled: boolean }>;
+
+export type ForkHandler = (
+	entryId: string,
+	options?: { position?: "before" | "at"; withSession?: (ctx: ReplacedSessionContext) => Promise<void> },
+) => Promise<{ cancelled: boolean }>;
+
+export type NavigateTreeHandler = (
+	targetId: string,
+	options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string },
+) => Promise<{ cancelled: boolean }>;
+
+export type SwitchSessionHandler = (
+	sessionPath: string,
+	options?: { withSession?: (ctx: ReplacedSessionContext) => Promise<void> },
+) => Promise<{ cancelled: boolean }>;
+
+export type ReloadHandler = () => Promise<void>;
+
+export type ShutdownHandler = () => void;
+
+/**
+ * Helper function to emit session_shutdown event to extensions.
+ * Returns true if the event was emitted, false if there were no handlers.
+ */
+export async function emitSessionShutdownEvent(
+	extensionRunner: ExtensionRunner,
+	event: SessionShutdownEvent,
+): Promise<boolean> {
+	if (extensionRunner.hasHandlers("session_shutdown")) {
+		await extensionRunner.emit(event);
+		return true;
+	}
+	return false;
+}
+
+export async function emitProjectTrustEvent(
+	extensionsResult: LoadExtensionsResult,
+	event: ProjectTrustEvent,
+	ctx: ProjectTrustContext,
+): Promise<{ result?: ProjectTrustEventResult; errors: ExtensionError[] }> {
+	const errors: ExtensionError[] = [];
+	for (const ext of extensionsResult.extensions) {
+		// A single extension may register multiple handlers for the same event.
+		// The first project_trust handler that returns yes/no wins; undecided falls through.
+		const handlers = ext.handlers.get("project_trust");
+		if (!handlers || handlers.length === 0) continue;
+
+		for (const handler of handlers) {
+			try {
+				const handlerResult = (await handler(event, ctx)) as ProjectTrustEventResult;
+				if (handlerResult.trusted === "undecided") {
+					continue;
+				}
+				return { result: handlerResult, errors };
+			} catch (error) {
+				errors.push({
+					extensionPath: ext.path,
+					event: event.type,
+					error: error instanceof Error ? error.message : String(error),
+					stack: error instanceof Error ? error.stack : undefined,
+				});
+			}
+		}
+	}
+	return { errors };
+}
+
+const noOpUIContext: ExtensionUIContext = {
+	select: async () => undefined,
+	confirm: async () => false,
+	input: async () => undefined,
+	notify: () => {},
+	onTerminalInput: () => () => {},
+	setStatus: () => {},
+	setWorkingMessage: () => {},
+	setWorkingVisible: () => {},
+	setWorkingIndicator: () => {},
+	setHiddenThinkingLabel: () => {},
+	setWidget: () => {},
+	setFooter: () => {},
+	setHeader: () => {},
+	setTitle: () => {},
+	custom: async () => undefined as never,
+	pasteToEditor: () => {},
+	setEditorText: () => {},
+	getEditorText: () => "",
+	editor: async () => undefined,
+	addAutocompleteProvider: () => {},
+	setEditorComponent: () => {},
+	getEditorComponent: () => undefined,
+	get theme() {
+		return theme;
+	},
+	getAllThemes: () => [],
+	getTheme: () => undefined,
+	setTheme: (_theme: string | Theme) => ({ success: false, error: "UI not available" }),
+	getToolsExpanded: () => false,
+	setToolsExpanded: () => {},
+};
+
+export class ExtensionRunner {
+	private extensions: Extension[];
+	private runtime: ExtensionRuntime;
+	private uiContext: ExtensionUIContext;
+	private mode: ExtensionMode = "print";
+	private cwd: string;
+	private sessionManager: SessionManager;
+	private modelRegistry: ModelRegistry;
+	private errorListeners: Set<ExtensionErrorListener> = new Set();
+	private getModel: () => Model<any> | undefined = () => undefined;
+	private getScopedModels: () => readonly ScopedModel[] = () => [];
+	private isIdleFn: () => boolean = () => true;
+	private isProjectTrustedFn: () => boolean = () => true;
+	private getSignalFn: () => AbortSignal | undefined = () => undefined;
+	private waitForIdleFn: () => Promise<void> = async () => {};
+	private abortFn: () => void = () => {};
+	private hasPendingMessagesFn: () => boolean = () => false;
+	private getContextUsageFn: () => ContextUsage | undefined = () => undefined;
+	private compactFn: (options?: CompactOptions) => void = () => {};
+	private getSystemPromptFn: () => string = () => "";
+	private getSystemPromptOptionsFn: () => BuildSystemPromptOptions = () => ({ cwd: this.cwd });
+	private newSessionHandler: NewSessionHandler = async () => ({ cancelled: false });
+	private forkHandler: ForkHandler = async () => ({ cancelled: false });
+	private navigateTreeHandler: NavigateTreeHandler = async () => ({ cancelled: false });
+	private switchSessionHandler: SwitchSessionHandler = async () => ({ cancelled: false });
+	private reloadHandler: ReloadHandler = async () => {};
+	private shutdownHandler: ShutdownHandler = () => {};
+	private shortcutDiagnostics: ResourceDiagnostic[] = [];
+	private commandDiagnostics: ResourceDiagnostic[] = [];
+	private staleMessage: string | undefined;
+	private uiPromptDepth = 0;
+	private activeUIPrompt: { kind: UIPromptKind; title?: string } | undefined;
+
+	constructor(
+		extensions: Extension[],
+		runtime: ExtensionRuntime,
+		cwd: string,
+		sessionManager: SessionManager,
+		modelRegistry: ModelRegistry,
+	) {
+		this.extensions = extensions;
+		this.runtime = runtime;
+		this.uiContext = noOpUIContext;
+		this.cwd = cwd;
+		this.sessionManager = sessionManager;
+		this.modelRegistry = modelRegistry;
+	}
+
+	bindCore(
+		actions: ExtensionActions,
+		contextActions: ExtensionContextActions,
+		providerActions?: {
+			registerProvider?: (name: string, config: ProviderConfig) => void;
+			registerNativeProvider?: (provider: Provider) => void;
+			unregisterProvider?: (name: string) => void;
+		},
+	): void {
+		// Copy actions into the shared runtime (all extension APIs reference this)
+		this.runtime.sendMessage = actions.sendMessage;
+		this.runtime.sendUserMessage = actions.sendUserMessage;
+		this.runtime.appendEntry = actions.appendEntry;
+		this.runtime.setSessionName = actions.setSessionName;
+		this.runtime.getSessionName = actions.getSessionName;
+		this.runtime.setLabel = actions.setLabel;
+		this.runtime.getActiveTools = actions.getActiveTools;
+		this.runtime.getAllTools = actions.getAllTools;
+		this.runtime.setActiveTools = actions.setActiveTools;
+		this.runtime.refreshTools = actions.refreshTools;
+		this.runtime.getCommands = actions.getCommands;
+		this.runtime.setModel = actions.setModel;
+		this.runtime.getThinkingLevel = actions.getThinkingLevel;
+		this.runtime.setThinkingLevel = actions.setThinkingLevel;
+
+		// Context actions (required)
+		this.getModel = contextActions.getModel;
+		this.getScopedModels = contextActions.getScopedModels;
+		this.isIdleFn = contextActions.isIdle;
+		this.isProjectTrustedFn = contextActions.isProjectTrusted;
+		this.getSignalFn = contextActions.getSignal;
+		this.abortFn = contextActions.abort;
+		this.hasPendingMessagesFn = contextActions.hasPendingMessages;
+		this.shutdownHandler = contextActions.shutdown;
+		this.getContextUsageFn = contextActions.getContextUsage;
+		this.compactFn = contextActions.compact;
+		this.getSystemPromptFn = contextActions.getSystemPrompt;
+		this.getSystemPromptOptionsFn = contextActions.getSystemPromptOptions ?? (() => ({ cwd: this.cwd }));
+
+		// Flush provider registrations queued during extension loading
+		for (const { name, config, extensionPath } of this.runtime.pendingProviderRegistrations) {
+			try {
+				if (providerActions?.registerProvider) {
+					providerActions.registerProvider(name, config);
+				} else {
+					this.modelRegistry.registerProvider(name, config);
+				}
+			} catch (err) {
+				this.emitError({
+					extensionPath,
+					event: "register_provider",
+					error: err instanceof Error ? err.message : String(err),
+					stack: err instanceof Error ? err.stack : undefined,
+				});
+			}
+		}
+		this.runtime.pendingProviderRegistrations = [];
+		for (const { provider, extensionPath } of this.runtime.pendingNativeProviderRegistrations) {
+			try {
+				if (providerActions?.registerNativeProvider) {
+					providerActions.registerNativeProvider(provider);
+				} else {
+					this.modelRegistry.registerProvider(provider);
+				}
+			} catch (err) {
+				this.emitError({
+					extensionPath,
+					event: "register_provider",
+					error: err instanceof Error ? err.message : String(err),
+					stack: err instanceof Error ? err.stack : undefined,
+				});
+			}
+		}
+		this.runtime.pendingNativeProviderRegistrations = [];
+
+		// From this point on, provider registration/unregistration takes effect immediately
+		// without requiring a /reload.
+		this.runtime.registerProvider = (name, config) => {
+			if (providerActions?.registerProvider) {
+				providerActions.registerProvider(name, config);
+				return;
+			}
+			this.modelRegistry.registerProvider(name, config);
+		};
+		this.runtime.registerNativeProvider = (provider) => {
+			if (providerActions?.registerNativeProvider) {
+				providerActions.registerNativeProvider(provider);
+				return;
+			}
+			this.modelRegistry.registerProvider(provider);
+		};
+		this.runtime.unregisterProvider = (name) => {
+			if (providerActions?.unregisterProvider) {
+				providerActions.unregisterProvider(name);
+				return;
+			}
+			this.modelRegistry.unregisterProvider(name);
+		};
+	}
+
+	bindCommandContext(actions?: ExtensionCommandContextActions): void {
+		if (actions) {
+			this.waitForIdleFn = actions.waitForIdle;
+			this.newSessionHandler = actions.newSession;
+			this.forkHandler = actions.fork;
+			this.navigateTreeHandler = actions.navigateTree;
+			this.switchSessionHandler = actions.switchSession;
+			this.reloadHandler = actions.reload;
+			return;
+		}
+
+		this.waitForIdleFn = async () => {};
+		this.newSessionHandler = async () => ({ cancelled: false });
+		this.forkHandler = async () => ({ cancelled: false });
+		this.navigateTreeHandler = async () => ({ cancelled: false });
+		this.switchSessionHandler = async () => ({ cancelled: false });
+		this.reloadHandler = async () => {};
+	}
+
+	setUIContext(uiContext?: ExtensionUIContext, mode: ExtensionMode = "print"): void {
+		this.uiContext = uiContext ? this.wrapUIPromptContext(uiContext) : noOpUIContext;
+		this.mode = mode;
+	}
+
+	private wrapUIPromptContext(ui: ExtensionUIContext): ExtensionUIContext {
+		return {
+			...ui,
+			select: (title, options, opts) => this.withUIPrompt("select", title, () => ui.select(title, options, opts)),
+			confirm: (title, message, opts) => this.withUIPrompt("confirm", title, () => ui.confirm(title, message, opts)),
+			input: (title, placeholder, opts) =>
+				this.withUIPrompt("input", title, () => ui.input(title, placeholder, opts)),
+			editor: (title, prefill) => this.withUIPrompt("editor", title, () => ui.editor(title, prefill)),
+			custom: (factory, options) => this.withUIPrompt("custom", undefined, () => ui.custom(factory, options)),
+		};
+	}
+
+	private withUIPrompt<T>(kind: UIPromptKind, title: string | undefined, run: () => Promise<T>): Promise<T> {
+		const outerPrompt = this.uiPromptDepth++ === 0;
+		if (outerPrompt) {
+			this.activeUIPrompt = { kind, title };
+			this.emitUIPromptEvent({ type: "ui_prompt_start", reason: "ui_prompt", kind, ...(title ? { title } : {}) });
+		}
+
+		const finish = () => {
+			if (--this.uiPromptDepth > 0) return;
+			this.uiPromptDepth = 0;
+
+			const prompt = this.activeUIPrompt ?? { kind, title };
+			this.activeUIPrompt = undefined;
+			this.emitUIPromptEvent({
+				type: "ui_prompt_end",
+				reason: "ui_prompt",
+				kind: prompt.kind,
+				...(prompt.title ? { title: prompt.title } : {}),
+			});
+		};
+
+		try {
+			return run().finally(finish);
+		} catch (err) {
+			finish();
+			throw err;
+		}
+	}
+
+	private emitUIPromptEvent(event: Extract<RunnerEmitEvent, { type: "ui_prompt_start" | "ui_prompt_end" }>): void {
+		queueMicrotask(() => {
+			void this.emit(event);
+		});
+	}
+
+	getUIContext(): ExtensionUIContext {
+		return this.uiContext;
+	}
+
+	hasUI(): boolean {
+		return this.uiContext !== noOpUIContext;
+	}
+
+	getExtensionPaths(): string[] {
+		return this.extensions.map((e) => e.path);
+	}
+
+	/** Get all registered tools from all extensions (first registration per name wins). */
+	getAllRegisteredTools(): RegisteredTool[] {
+		const toolsByName = new Map<string, RegisteredTool>();
+		for (const ext of this.extensions) {
+			for (const tool of ext.tools.values()) {
+				if (!toolsByName.has(tool.definition.name)) {
+					toolsByName.set(tool.definition.name, tool);
+				}
+			}
+		}
+		return Array.from(toolsByName.values());
+	}
+
+	/** Get a tool definition by name. Returns undefined if not found. */
+	getToolDefinition(toolName: string): RegisteredTool["definition"] | undefined {
+		for (const ext of this.extensions) {
+			const tool = ext.tools.get(toolName);
+			if (tool) {
+				return tool.definition;
+			}
+		}
+		return undefined;
+	}
+
+	getFlags(): Map<string, ExtensionFlag> {
+		const allFlags = new Map<string, ExtensionFlag>();
+		for (const ext of this.extensions) {
+			for (const [name, flag] of ext.flags) {
+				if (!allFlags.has(name)) {
+					allFlags.set(name, flag);
+				}
+			}
+		}
+		return allFlags;
+	}
+
+	setFlagValue(name: string, value: boolean | string): void {
+		this.runtime.flagValues.set(name, value);
+	}
+
+	getFlagValues(): Map<string, boolean | string> {
+		return new Map(this.runtime.flagValues);
+	}
+
+	getShortcuts(resolvedKeybindings: KeybindingsConfig): Map<KeyId, ExtensionShortcut> {
+		this.shortcutDiagnostics = [];
+		const builtinKeybindings = buildBuiltinKeybindings(resolvedKeybindings);
+		const extensionShortcuts = new Map<KeyId, ExtensionShortcut>();
+
+		const addDiagnostic = (message: string, extensionPath: string) => {
+			this.shortcutDiagnostics.push({ type: "warning", message, path: extensionPath });
+			if (!this.hasUI()) {
+				console.warn(message);
+			}
+		};
+
+		for (const ext of this.extensions) {
+			for (const [key, shortcut] of ext.shortcuts) {
+				const normalizedKey = key.toLowerCase() as KeyId;
+
+				const builtInKeybinding = builtinKeybindings[normalizedKey];
+				if (builtInKeybinding?.restrictOverride === true) {
+					addDiagnostic(
+						`Extension shortcut '${key}' from ${shortcut.extensionPath} conflicts with built-in shortcut. Skipping.`,
+						shortcut.extensionPath,
+					);
+					continue;
+				}
+
+				if (builtInKeybinding?.restrictOverride === false) {
+					addDiagnostic(
+						`Extension shortcut conflict: '${key}' is built-in shortcut for ${builtInKeybinding.keybinding} and ${shortcut.extensionPath}. Using ${shortcut.extensionPath}.`,
+						shortcut.extensionPath,
+					);
+				}
+
+				const existingExtensionShortcut = extensionShortcuts.get(normalizedKey);
+				if (existingExtensionShortcut) {
+					addDiagnostic(
+						`Extension shortcut conflict: '${key}' registered by both ${existingExtensionShortcut.extensionPath} and ${shortcut.extensionPath}. Using ${shortcut.extensionPath}.`,
+						shortcut.extensionPath,
+					);
+				}
+				extensionShortcuts.set(normalizedKey, shortcut);
+			}
+		}
+		return extensionShortcuts;
+	}
+
+	getShortcutDiagnostics(): ResourceDiagnostic[] {
+		return this.shortcutDiagnostics;
+	}
+
+	invalidate(
+		message = "This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). For newSession, fork, and switchSession, move post-replacement work into withSession and use the ctx passed to withSession. For reload, do not use the old ctx after await ctx.reload().",
+	): void {
+		if (!this.staleMessage) {
+			this.staleMessage = message;
+			this.runtime.invalidate(message);
+		}
+	}
+
+	private assertActive(): void {
+		if (this.staleMessage) {
+			throw new Error(this.staleMessage);
+		}
+	}
+
+	onError(listener: ExtensionErrorListener): () => void {
+		this.errorListeners.add(listener);
+		return () => this.errorListeners.delete(listener);
+	}
+
+	emitError(error: ExtensionError): void {
+		for (const listener of this.errorListeners) {
+			listener(error);
+		}
+	}
+
+	hasHandlers(eventType: string): boolean {
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get(eventType);
+			if (handlers && handlers.length > 0) {
+				return true;
+			}
+		}
+		return false;
+	}
+
+	getMessageRenderer(customType: string): MessageRenderer | undefined {
+		for (const ext of this.extensions) {
+			const renderer = ext.messageRenderers.get(customType);
+			if (renderer) {
+				return renderer;
+			}
+		}
+		return undefined;
+	}
+
+	getMarkdownTransformers(): MarkdownTransformer[] {
+		return this.extensions.flatMap((ext) => (ext.markdownTransformer ? [ext.markdownTransformer] : []));
+	}
+
+	getEntryRenderer(customType: string): EntryRenderer | undefined {
+		for (const ext of this.extensions) {
+			const renderer = ext.entryRenderers?.get(customType);
+			if (renderer) {
+				return renderer;
+			}
+		}
+		return undefined;
+	}
+
+	private resolveRegisteredCommands(): ResolvedCommand[] {
+		const commands: RegisteredCommand[] = [];
+		const counts = new Map<string, number>();
+
+		for (const ext of this.extensions) {
+			for (const command of ext.commands.values()) {
+				commands.push(command);
+				counts.set(command.name, (counts.get(command.name) ?? 0) + 1);
+			}
+		}
+
+		const seen = new Map<string, number>();
+		const takenInvocationNames = new Set<string>();
+
+		return commands.map((command) => {
+			const occurrence = (seen.get(command.name) ?? 0) + 1;
+			seen.set(command.name, occurrence);
+
+			let invocationName = (counts.get(command.name) ?? 0) > 1 ? `${command.name}:${occurrence}` : command.name;
+
+			if (takenInvocationNames.has(invocationName)) {
+				let suffix = occurrence;
+				do {
+					suffix++;
+					invocationName = `${command.name}:${suffix}`;
+				} while (takenInvocationNames.has(invocationName));
+			}
+
+			takenInvocationNames.add(invocationName);
+			return {
+				...command,
+				invocationName,
+			};
+		});
+	}
+
+	getModelRegistry(): ModelRegistry {
+		return this.modelRegistry;
+	}
+
+	getRegisteredCommands(): ResolvedCommand[] {
+		this.commandDiagnostics = [];
+		return this.resolveRegisteredCommands();
+	}
+
+	getCommandDiagnostics(): ResourceDiagnostic[] {
+		return this.commandDiagnostics;
+	}
+
+	getCommand(name: string): ResolvedCommand | undefined {
+		return this.resolveRegisteredCommands().find((command) => command.invocationName === name);
+	}
+
+	/**
+	 * Request a graceful shutdown. Called by extension tools and event handlers.
+	 * The actual shutdown behavior is provided by the mode via bindExtensions().
+	 */
+	shutdown(): void {
+		this.shutdownHandler();
+	}
+
+	getActiveTools(): string[] {
+		this.assertActive();
+		return this.runtime.getActiveTools();
+	}
+
+	/**
+	 * Create an ExtensionContext for use in event handlers and tool execution.
+	 * Context values are resolved at call time, so changes via bindCore/bindUI are reflected.
+	 */
+	createContext(): ExtensionContext {
+		const runner = this;
+		const getModel = this.getModel;
+		const getScopedModels = this.getScopedModels;
+		return {
+			get ui() {
+				runner.assertActive();
+				return runner.uiContext;
+			},
+			get mode() {
+				runner.assertActive();
+				return runner.mode;
+			},
+			get hasUI() {
+				runner.assertActive();
+				return runner.hasUI();
+			},
+			get cwd() {
+				runner.assertActive();
+				return runner.cwd;
+			},
+			get sessionManager() {
+				runner.assertActive();
+				return runner.sessionManager;
+			},
+			get modelRegistry() {
+				runner.assertActive();
+				return runner.modelRegistry;
+			},
+			get model() {
+				runner.assertActive();
+				return getModel();
+			},
+			get scopedModels() {
+				runner.assertActive();
+				return getScopedModels();
+			},
+			get thinkingLevel() {
+				runner.assertActive();
+				return runner.runtime.getThinkingLevel();
+			},
+			isIdle: () => {
+				runner.assertActive();
+				return runner.isIdleFn();
+			},
+			isProjectTrusted: () => {
+				runner.assertActive();
+				return runner.isProjectTrustedFn();
+			},
+			get signal() {
+				runner.assertActive();
+				return runner.getSignalFn();
+			},
+			abort: () => {
+				runner.assertActive();
+				runner.abortFn();
+			},
+			hasPendingMessages: () => {
+				runner.assertActive();
+				return runner.hasPendingMessagesFn();
+			},
+			shutdown: () => {
+				runner.assertActive();
+				runner.shutdownHandler();
+			},
+			getContextUsage: () => {
+				runner.assertActive();
+				return runner.getContextUsageFn();
+			},
+			compact: (options) => {
+				runner.assertActive();
+				runner.compactFn(options);
+			},
+			getSystemPrompt: () => {
+				runner.assertActive();
+				return runner.getSystemPromptFn();
+			},
+		};
+	}
+
+	createCommandContext(): ExtensionCommandContext {
+		// Use property descriptors instead of object spread so the guarded getters from
+		// createContext() stay lazy. A spread would eagerly read them once and freeze the
+		// old values into the returned object, bypassing stale-instance checks.
+		const context = Object.defineProperties(
+			{},
+			Object.getOwnPropertyDescriptors(this.createContext()),
+		) as ExtensionCommandContext;
+		context.getSystemPromptOptions = () => {
+			this.assertActive();
+			return this.getSystemPromptOptionsFn();
+		};
+		context.waitForIdle = () => {
+			this.assertActive();
+			return this.waitForIdleFn();
+		};
+		context.newSession = (options) => {
+			this.assertActive();
+			return this.newSessionHandler(options);
+		};
+		context.fork = (entryId, options) => {
+			this.assertActive();
+			return this.forkHandler(entryId, options);
+		};
+		context.navigateTree = (targetId, options) => {
+			this.assertActive();
+			return this.navigateTreeHandler(targetId, options);
+		};
+		context.switchSession = (sessionPath, options) => {
+			this.assertActive();
+			return this.switchSessionHandler(sessionPath, options);
+		};
+		context.reload = () => {
+			this.assertActive();
+			return this.reloadHandler();
+		};
+		return context;
+	}
+
+	private isSessionBeforeEvent(event: RunnerEmitEvent): event is SessionBeforeEvent {
+		return (
+			event.type === "session_before_switch" ||
+			event.type === "session_before_fork" ||
+			event.type === "session_before_compact" ||
+			event.type === "session_before_tree"
+		);
+	}
+
+	async emit<TEvent extends RunnerEmitEvent>(event: TEvent): Promise<RunnerEmitResult<TEvent>> {
+		const ctx = this.createContext();
+		let result: SessionBeforeEventResult | undefined;
+
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get(event.type);
+			if (!handlers || handlers.length === 0) continue;
+
+			for (const handler of handlers) {
+				try {
+					const handlerResult = await handler(event, ctx);
+
+					if (this.isSessionBeforeEvent(event) && handlerResult) {
+						result = handlerResult as SessionBeforeEventResult;
+						if (result.cancel) {
+							return result as RunnerEmitResult<TEvent>;
+						}
+					}
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					const stack = err instanceof Error ? err.stack : undefined;
+					this.emitError({
+						extensionPath: ext.path,
+						event: event.type,
+						error: message,
+						stack,
+					});
+				}
+			}
+		}
+
+		return result as RunnerEmitResult<TEvent>;
+	}
+
+	async emitMessageEnd(event: MessageEndEvent): Promise<AgentMessage | undefined> {
+		const ctx = this.createContext();
+		let currentMessage = event.message;
+		let modified = false;
+
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get("message_end");
+			if (!handlers || handlers.length === 0) continue;
+
+			for (const handler of handlers) {
+				try {
+					const currentEvent: MessageEndEvent = { ...event, message: currentMessage };
+					const handlerResult = (await handler(currentEvent, ctx)) as MessageEndEventResult | undefined;
+					if (!handlerResult?.message) continue;
+
+					if (handlerResult.message.role !== currentMessage.role) {
+						this.emitError({
+							extensionPath: ext.path,
+							event: "message_end",
+							error: "message_end handlers must return a message with the same role",
+						});
+						continue;
+					}
+
+					currentMessage = handlerResult.message;
+					modified = true;
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					const stack = err instanceof Error ? err.stack : undefined;
+					this.emitError({
+						extensionPath: ext.path,
+						event: "message_end",
+						error: message,
+						stack,
+					});
+				}
+			}
+		}
+
+		return modified ? currentMessage : undefined;
+	}
+
+	async emitToolResult(event: ToolResultEvent): Promise<ToolResultEventResult | undefined> {
+		const ctx = this.createContext();
+		const currentEvent: ToolResultEvent = { ...event };
+		let modified = false;
+
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get("tool_result");
+			if (!handlers || handlers.length === 0) continue;
+
+			for (const handler of handlers) {
+				try {
+					const handlerResult = (await handler(currentEvent, ctx)) as ToolResultEventResult | undefined;
+					if (!handlerResult) continue;
+
+					if (handlerResult.content !== undefined) {
+						currentEvent.content = handlerResult.content;
+						modified = true;
+					}
+					if (handlerResult.details !== undefined) {
+						currentEvent.details = handlerResult.details;
+						modified = true;
+					}
+					if (handlerResult.isError !== undefined) {
+						currentEvent.isError = handlerResult.isError;
+						modified = true;
+					}
+					if (handlerResult.usage !== undefined) {
+						currentEvent.usage = handlerResult.usage;
+						modified = true;
+					}
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					const stack = err instanceof Error ? err.stack : undefined;
+					this.emitError({
+						extensionPath: ext.path,
+						event: "tool_result",
+						error: message,
+						stack,
+					});
+				}
+			}
+		}
+
+		if (!modified) {
+			return undefined;
+		}
+
+		return {
+			content: currentEvent.content,
+			details: currentEvent.details,
+			isError: currentEvent.isError,
+			usage: currentEvent.usage,
+		};
+	}
+
+	async emitToolCall(event: ToolCallEvent): Promise<ToolCallEventResult | undefined> {
+		const ctx = this.createContext();
+		let result: ToolCallEventResult | undefined;
+
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get("tool_call");
+			if (!handlers || handlers.length === 0) continue;
+
+			for (const handler of handlers) {
+				const handlerResult = await handler(event, ctx);
+
+				if (handlerResult) {
+					result = handlerResult as ToolCallEventResult;
+					if (result.block) {
+						return result;
+					}
+				}
+			}
+		}
+
+		return result;
+	}
+
+	async emitUserBash(event: UserBashEvent): Promise<UserBashEventResult | undefined> {
+		const ctx = this.createContext();
+
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get("user_bash");
+			if (!handlers || handlers.length === 0) continue;
+
+			for (const handler of handlers) {
+				try {
+					const handlerResult = await handler(event, ctx);
+					if (handlerResult) {
+						return handlerResult as UserBashEventResult;
+					}
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					const stack = err instanceof Error ? err.stack : undefined;
+					this.emitError({
+						extensionPath: ext.path,
+						event: "user_bash",
+						error: message,
+						stack,
+					});
+				}
+			}
+		}
+
+		return undefined;
+	}
+
+	async emitContext(messages: AgentMessage[]): Promise<AgentMessage[]> {
+		const ctx = this.createContext();
+		let currentMessages = structuredClone(messages);
+
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get("context");
+			if (!handlers || handlers.length === 0) continue;
+
+			for (const handler of handlers) {
+				try {
+					const event: ContextEvent = { type: "context", messages: currentMessages };
+					const handlerResult = await handler(event, ctx);
+
+					if (handlerResult && (handlerResult as ContextEventResult).messages) {
+						currentMessages = (handlerResult as ContextEventResult).messages!;
+					}
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					const stack = err instanceof Error ? err.stack : undefined;
+					this.emitError({
+						extensionPath: ext.path,
+						event: "context",
+						error: message,
+						stack,
+					});
+				}
+			}
+		}
+
+		return currentMessages;
+	}
+
+	async emitBeforeProviderRequest(payload: unknown): Promise<unknown> {
+		const ctx = this.createContext();
+		let currentPayload = payload;
+
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get("before_provider_request");
+			if (!handlers || handlers.length === 0) continue;
+
+			for (const handler of handlers) {
+				try {
+					const event: BeforeProviderRequestEvent = {
+						type: "before_provider_request",
+						payload: currentPayload,
+					};
+					const handlerResult = await handler(event, ctx);
+					if (handlerResult !== undefined) {
+						currentPayload = handlerResult;
+					}
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					const stack = err instanceof Error ? err.stack : undefined;
+					this.emitError({
+						extensionPath: ext.path,
+						event: "before_provider_request",
+						error: message,
+						stack,
+					});
+				}
+			}
+		}
+
+		return currentPayload;
+	}
+
+	async emitBeforeProviderHeaders(headers: ProviderHeaders): Promise<ProviderHeaders> {
+		const ctx = this.createContext();
+
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get("before_provider_headers");
+			if (!handlers || handlers.length === 0) continue;
+
+			for (const handler of handlers) {
+				try {
+					// Handlers mutate `headers` in place; the return value is ignored.
+					const event: BeforeProviderHeadersEvent = {
+						type: "before_provider_headers",
+						headers,
+					};
+					await handler(event, ctx);
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					const stack = err instanceof Error ? err.stack : undefined;
+					this.emitError({
+						extensionPath: ext.path,
+						event: "before_provider_headers",
+						error: message,
+						stack,
+					});
+				}
+			}
+		}
+
+		return headers;
+	}
+
+	async emitBeforeAgentStart(
+		prompt: string,
+		images: ImageContent[] | undefined,
+		systemPrompt: string,
+		systemPromptOptions: BuildSystemPromptOptions,
+	): Promise<BeforeAgentStartCombinedResult | undefined> {
+		let currentSystemPrompt = systemPrompt;
+		const ctx = Object.defineProperties(
+			{},
+			Object.getOwnPropertyDescriptors(this.createContext()),
+		) as ExtensionContext;
+		ctx.getSystemPrompt = () => {
+			this.assertActive();
+			return currentSystemPrompt;
+		};
+		const messages: NonNullable<BeforeAgentStartEventResult["message"]>[] = [];
+		let systemPromptModified = false;
+
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get("before_agent_start");
+			if (!handlers || handlers.length === 0) continue;
+
+			for (const handler of handlers) {
+				try {
+					const event: BeforeAgentStartEvent = {
+						type: "before_agent_start",
+						prompt,
+						images,
+						systemPrompt: currentSystemPrompt,
+						systemPromptOptions,
+					};
+					const handlerResult = await handler(event, ctx);
+
+					if (handlerResult) {
+						const result = handlerResult as BeforeAgentStartEventResult;
+						if (result.message) {
+							messages.push(result.message);
+						}
+						if (result.systemPrompt !== undefined) {
+							currentSystemPrompt = result.systemPrompt;
+							systemPromptModified = true;
+						}
+					}
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					const stack = err instanceof Error ? err.stack : undefined;
+					this.emitError({
+						extensionPath: ext.path,
+						event: "before_agent_start",
+						error: message,
+						stack,
+					});
+				}
+			}
+		}
+
+		if (messages.length > 0 || systemPromptModified) {
+			return {
+				messages: messages.length > 0 ? messages : undefined,
+				systemPrompt: systemPromptModified ? currentSystemPrompt : undefined,
+			};
+		}
+
+		return undefined;
+	}
+
+	async emitResourcesDiscover(
+		cwd: string,
+		reason: ResourcesDiscoverEvent["reason"],
+	): Promise<{
+		skillPaths: Array<{ path: string; extensionPath: string }>;
+		promptPaths: Array<{ path: string; extensionPath: string }>;
+		themePaths: Array<{ path: string; extensionPath: string }>;
+	}> {
+		const ctx = this.createContext();
+		const skillPaths: Array<{ path: string; extensionPath: string }> = [];
+		const promptPaths: Array<{ path: string; extensionPath: string }> = [];
+		const themePaths: Array<{ path: string; extensionPath: string }> = [];
+
+		for (const ext of this.extensions) {
+			const handlers = ext.handlers.get("resources_discover");
+			if (!handlers || handlers.length === 0) continue;
+
+			for (const handler of handlers) {
+				try {
+					const event: ResourcesDiscoverEvent = { type: "resources_discover", cwd, reason };
+					const handlerResult = await handler(event, ctx);
+					const result = handlerResult as ResourcesDiscoverResult | undefined;
+
+					if (result?.skillPaths?.length) {
+						skillPaths.push(...result.skillPaths.map((path) => ({ path, extensionPath: ext.path })));
+					}
+					if (result?.promptPaths?.length) {
+						promptPaths.push(...result.promptPaths.map((path) => ({ path, extensionPath: ext.path })));
+					}
+					if (result?.themePaths?.length) {
+						themePaths.push(...result.themePaths.map((path) => ({ path, extensionPath: ext.path })));
+					}
+				} catch (err) {
+					const message = err instanceof Error ? err.message : String(err);
+					const stack = err instanceof Error ? err.stack : undefined;
+					this.emitError({
+						extensionPath: ext.path,
+						event: "resources_discover",
+						error: message,
+						stack,
+					});
+				}
+			}
+		}
+
+		return { skillPaths, promptPaths, themePaths };
+	}
+
+	/** Emit input event. Transforms chain, "handled" short-circuits. */
+	async emitInput(
+		text: string,
+		images: ImageContent[] | undefined,
+		source: InputSource,
+		streamingBehavior?: "steer" | "followUp",
+	): Promise<InputEventResult> {
+		const ctx = this.createContext();
+		let currentText = text;
+		let currentImages = images;
+
+		for (const ext of this.extensions) {
+			for (const handler of ext.handlers.get("input") ?? []) {
+				try {
+					const event: InputEvent = {
+						type: "input",
+						text: currentText,
+						images: currentImages,
+						source,
+						streamingBehavior,
+					};
+					const result = (await handler(event, ctx)) as InputEventResult | undefined;
+					if (result?.action === "handled") return result;
+					if (result?.action === "transform") {
+						currentText = result.text;
+						currentImages = result.images ?? currentImages;
+					}
+				} catch (err) {
+					this.emitError({
+						extensionPath: ext.path,
+						event: "input",
+						error: err instanceof Error ? err.message : String(err),
+						stack: err instanceof Error ? err.stack : undefined,
+					});
+				}
+			}
+		}
+		return currentText !== text || currentImages !== images
+			? { action: "transform", text: currentText, images: currentImages }
+			: { action: "continue" };
+	}
+}

packages/coding-agent/src/core/extensions/types.ts

@@ -0,0 +1,1797 @@
+/**
+ * Extension system types.
+ *
+ * Extensions are TypeScript modules that can:
+ * - Subscribe to agent lifecycle events
+ * - Register LLM-callable tools
+ * - Register commands, keyboard shortcuts, and CLI flags
+ * - Interact with the user via UI primitives
+ */
+
+import type {
+	AgentMessage,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	ThinkingLevel,
+	ToolExecutionMode,
+} from "@earendil-works/pi-agent-core";
+import type {
+	Api,
+	AssistantMessageEvent,
+	AssistantMessageEventStream,
+	ConstrainedSamplingConfig,
+	Context,
+	ImageContent,
+	Model,
+	OAuthCredentials,
+	OAuthLoginCallbacks,
+	Provider,
+	ProviderHeaders,
+	RefreshModelsContext,
+	SimpleStreamOptions,
+	TextContent,
+	ToolResultMessage,
+	Usage,
+} from "@earendil-works/pi-ai";
+import type {
+	AutocompleteItem,
+	AutocompleteProvider,
+	Component,
+	EditorComponent,
+	EditorTheme,
+	KeyId,
+	OverlayHandle,
+	OverlayOptions,
+	TUI,
+} from "@earendil-works/pi-tui";
+import type { Static, TSchema } from "typebox";
+import type { Theme } from "../../modes/interactive/theme/theme.ts";
+import type { BashResult } from "../bash-executor.ts";
+import type { CompactionPreparation, CompactionResult } from "../compaction/index.ts";
+import type { EventBus } from "../event-bus.ts";
+import type { ExecOptions, ExecResult } from "../exec.ts";
+import type { ReadonlyFooterDataProvider } from "../footer-data-provider.ts";
+import type { KeybindingsManager } from "../keybindings.ts";
+import type { CustomMessage } from "../messages.ts";
+import type { ModelRegistry } from "../model-registry.ts";
+import type { ScopedModel } from "../model-resolver.ts";
+import type {
+	BranchSummaryEntry,
+	CompactionEntry,
+	CustomEntry,
+	ReadonlySessionManager,
+	SessionEntry,
+	SessionManager,
+} from "../session-manager.ts";
+import type { SlashCommandInfo } from "../slash-commands.ts";
+import type { SourceInfo } from "../source-info.ts";
+import type { BuildSystemPromptOptions } from "../system-prompt.ts";
+import type { BashOperations } from "../tools/bash.ts";
+import type { EditToolDetails } from "../tools/edit.ts";
+import type {
+	BashToolDetails,
+	BashToolInput,
+	EditToolInput,
+	FindToolDetails,
+	FindToolInput,
+	GrepToolDetails,
+	GrepToolInput,
+	LsToolDetails,
+	LsToolInput,
+	PowerShellToolDetails,
+	PowerShellToolInput,
+	ReadToolDetails,
+	ReadToolInput,
+	WriteToolInput,
+} from "../tools/index.ts";
+
+export type { ExecOptions, ExecResult } from "../exec.ts";
+export type { BuildSystemPromptOptions } from "../system-prompt.ts";
+export type { AgentToolResult, AgentToolUpdateCallback, ToolExecutionMode };
+export type { AppKeybinding, KeybindingsManager } from "../keybindings.ts";
+
+// ============================================================================
+// UI Context
+// ============================================================================
+
+/** Options for extension UI dialogs. */
+export interface ExtensionUIDialogOptions {
+	/** AbortSignal to programmatically dismiss the dialog. */
+	signal?: AbortSignal;
+	/** Timeout in milliseconds. Dialog auto-dismisses with live countdown display. */
+	timeout?: number;
+}
+
+/** Placement for extension widgets. */
+export type WidgetPlacement = "aboveEditor" | "belowEditor";
+
+/** Options for extension widgets. */
+export interface ExtensionWidgetOptions {
+	/** Where the widget is rendered. Defaults to "aboveEditor". */
+	placement?: WidgetPlacement;
+}
+
+/** Raw terminal input listener for extensions. */
+export type TerminalInputHandler = (data: string) => { consume?: boolean; data?: string } | undefined;
+
+/** Working indicator configuration for the interactive streaming loader. */
+export interface WorkingIndicatorOptions {
+	/** Animation frames. Use an empty array to hide the indicator entirely. Custom frames are rendered verbatim. */
+	frames?: string[];
+	/** Frame interval in milliseconds for animated indicators. */
+	intervalMs?: number;
+}
+
+/** Wrap the current autocomplete provider with additional behavior. */
+export type AutocompleteProviderFactory = (current: AutocompleteProvider) => AutocompleteProvider;
+export type EditorFactory = (tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) => EditorComponent;
+
+/**
+ * UI context for extensions to request interactive UI.
+ * Each mode (interactive, RPC, print) provides its own implementation.
+ */
+export interface ExtensionUIContext {
+	/** Show a selector and return the user's choice. */
+	select(title: string, options: string[], opts?: ExtensionUIDialogOptions): Promise<string | undefined>;
+
+	/** Show a confirmation dialog. */
+	confirm(title: string, message: string, opts?: ExtensionUIDialogOptions): Promise<boolean>;
+
+	/** Show a text input dialog. */
+	input(title: string, placeholder?: string, opts?: ExtensionUIDialogOptions): Promise<string | undefined>;
+
+	/** Show a notification to the user. */
+	notify(message: string, type?: "info" | "warning" | "error"): void;
+
+	/** Listen to raw terminal input (interactive mode only). Returns an unsubscribe function. */
+	onTerminalInput(handler: TerminalInputHandler): () => void;
+
+	/** Set status text in the footer/status bar. Pass undefined to clear. */
+	setStatus(key: string, text: string | undefined): void;
+
+	/** Set the working/loading message shown during streaming. Call with no argument to restore default. */
+	setWorkingMessage(message?: string): void;
+
+	/** Show or hide the built-in interactive working loader row during streaming. */
+	setWorkingVisible(visible: boolean): void;
+
+	/**
+	 * Configure the interactive working indicator shown during streaming.
+	 *
+	 * - Omit the argument to restore the default animated spinner.
+	 * - Use `frames: ["●"]` for a static indicator.
+	 * - Use `frames: []` to hide the indicator entirely.
+	 * - Custom frames are rendered as provided, so extensions must add their own colors.
+	 */
+	setWorkingIndicator(options?: WorkingIndicatorOptions): void;
+
+	/** Set the label shown for hidden thinking blocks. Call with no argument to restore default. */
+	setHiddenThinkingLabel(label?: string): void;
+
+	/** Set a widget to display above or below the editor. Accepts string array or component factory. */
+	setWidget(key: string, content: string[] | undefined, options?: ExtensionWidgetOptions): void;
+	setWidget(
+		key: string,
+		content: ((tui: TUI, theme: Theme) => Component & { dispose?(): void }) | undefined,
+		options?: ExtensionWidgetOptions,
+	): void;
+
+	/** Set a custom footer component, or undefined to restore the built-in footer.
+	 *
+	 * The factory receives a FooterDataProvider for data not otherwise accessible:
+	 * git branch and extension statuses from setStatus(). Context usage is on
+	 * ctx.getContextUsage(), token stats on ctx.sessionManager.getEntries(), model info on ctx.model.
+	 */
+	setFooter(
+		factory:
+			| ((tui: TUI, theme: Theme, footerData: ReadonlyFooterDataProvider) => Component & { dispose?(): void })
+			| undefined,
+	): void;
+
+	/** Set a custom header component (shown at startup, above chat), or undefined to restore the built-in header. */
+	setHeader(factory: ((tui: TUI, theme: Theme) => Component & { dispose?(): void }) | undefined): void;
+
+	/** Set the terminal window/tab title. */
+	setTitle(title: string): void;
+
+	/** Show a custom component with keyboard focus. */
+	custom<T>(
+		factory: (
+			tui: TUI,
+			theme: Theme,
+			keybindings: KeybindingsManager,
+			done: (result: T) => void,
+		) => (Component & { dispose?(): void }) | Promise<Component & { dispose?(): void }>,
+		options?: {
+			overlay?: boolean;
+			/** Overlay positioning/sizing options. Can be static or a function for dynamic updates. */
+			overlayOptions?: OverlayOptions | (() => OverlayOptions);
+			/** Called with the overlay handle after the overlay is shown. Use to control visibility. */
+			onHandle?: (handle: OverlayHandle) => void;
+		},
+	): Promise<T>;
+
+	/** Paste text into the editor, triggering paste handling (collapse for large content). */
+	pasteToEditor(text: string): void;
+
+	/** Set the text in the core input editor. */
+	setEditorText(text: string): void;
+
+	/** Get the current text from the core input editor. */
+	getEditorText(): string;
+
+	/** Show a multi-line editor for text editing. */
+	editor(title: string, prefill?: string): Promise<string | undefined>;
+
+	/** Stack additional autocomplete behavior on top of the built-in provider. */
+	addAutocompleteProvider(factory: AutocompleteProviderFactory): void;
+
+	/**
+	 * Set a custom editor component via factory function.
+	 * Pass undefined to restore the default editor.
+	 *
+	 * The factory receives:
+	 * - `theme`: EditorTheme for styling borders and autocomplete
+	 * - `keybindings`: KeybindingsManager for app-level keybindings
+	 *
+	 * For full app keybinding support (escape, ctrl+d, model switching, etc.),
+	 * extend `CustomEditor` from `@earendil-works/pi-coding-agent` and call
+	 * `super.handleInput(data)` for keys you don't handle.
+	 *
+	 * @example
+	 * ```ts
+	 * import { CustomEditor } from "@earendil-works/pi-coding-agent";
+	 *
+	 * class VimEditor extends CustomEditor {
+	 *   private mode: "normal" | "insert" = "insert";
+	 *
+	 *   handleInput(data: string): void {
+	 *     if (this.mode === "normal") {
+	 *       // Handle vim normal mode keys...
+	 *       if (data === "i") { this.mode = "insert"; return; }
+	 *     }
+	 *     super.handleInput(data);  // App keybindings + text editing
+	 *   }
+	 * }
+	 *
+	 * ctx.ui.setEditorComponent((tui, theme, keybindings) =>
+	 *   new VimEditor(tui, theme, keybindings)
+	 * );
+	 * ```
+	 */
+	setEditorComponent(factory: EditorFactory | undefined): void;
+
+	/** Get the currently configured custom editor factory, or undefined when using the default editor. */
+	getEditorComponent(): EditorFactory | undefined;
+
+	/** Get the current theme for styling. */
+	readonly theme: Theme;
+
+	/** Get all available themes with their names and file paths. */
+	getAllThemes(): { name: string; path: string | undefined }[];
+
+	/** Load a theme by name without switching to it. Returns undefined if not found. */
+	getTheme(name: string): Theme | undefined;
+
+	/** Set the current theme by name or Theme object. */
+	setTheme(theme: string | Theme): { success: boolean; error?: string };
+
+	/** Get current tool output expansion state. */
+	getToolsExpanded(): boolean;
+
+	/** Set tool output expansion state. */
+	setToolsExpanded(expanded: boolean): void;
+}
+
+// ============================================================================
+// Extension Context
+// ============================================================================
+
+export interface ContextUsage {
+	/** Estimated context tokens, or null if unknown (e.g. right after compaction, before next LLM response). */
+	tokens: number | null;
+	contextWindow: number;
+	/** Context usage as percentage of context window, or null if tokens is unknown. */
+	percent: number | null;
+}
+
+export interface CompactOptions {
+	customInstructions?: string;
+	onComplete?: (result: CompactionResult) => void;
+	onError?: (error: Error) => void;
+}
+
+/**
+ * Context passed to extension event handlers.
+ */
+export type ExtensionMode = "tui" | "rpc" | "json" | "print";
+
+export interface ExtensionContext {
+	/** UI methods for user interaction */
+	ui: ExtensionUIContext;
+	/** Current run mode. Use "tui" to guard terminal-only UI such as custom components. */
+	mode: ExtensionMode;
+	/** Whether dialog-capable UI is available (true in TUI and RPC modes) */
+	hasUI: boolean;
+	/** Current working directory */
+	cwd: string;
+	/** Session manager (read-only) */
+	sessionManager: ReadonlySessionManager;
+	/** Model registry for API key resolution */
+	modelRegistry: ModelRegistry;
+	/** Current model (may be undefined) */
+	model: Model<any> | undefined;
+	/** Models scoped to this session (resolved from `--models` /
+	 *  `enabledModels` settings against the available catalogue). Same set
+	 *  the `/scoped-models` command shows. Empty when no scoping is
+	 *  configured (all available models are usable). Read-only snapshot. */
+	scopedModels: readonly ScopedModel[];
+	/** Current thinking level, when provided by the session runtime. */
+	thinkingLevel?: ThinkingLevel;
+	/** Whether the agent is idle (not streaming) */
+	isIdle(): boolean;
+	/** Whether project-local trust is active for this context. */
+	isProjectTrusted(): boolean;
+	/** The current abort signal, or undefined when the agent is not streaming. */
+	signal: AbortSignal | undefined;
+	/** Abort the current agent operation */
+	abort(): void;
+	/** Whether there are queued messages waiting */
+	hasPendingMessages(): boolean;
+	/** Gracefully shutdown pi and exit. Available in all contexts. */
+	shutdown(): void;
+	/** Get current context usage for the active model. */
+	getContextUsage(): ContextUsage | undefined;
+	/** Trigger compaction without awaiting completion. */
+	compact(options?: CompactOptions): void;
+	/** Get the current effective system prompt. */
+	getSystemPrompt(): string;
+}
+
+/**
+ * Extended context for command handlers.
+ * Includes session control methods only safe in user-initiated commands.
+ */
+export interface ExtensionCommandContext extends ExtensionContext {
+	/** Get the current base system-prompt construction options. */
+	getSystemPromptOptions(): BuildSystemPromptOptions;
+
+	/** Wait for the agent to finish streaming */
+	waitForIdle(): Promise<void>;
+
+	/** Start a new session, optionally with initialization. */
+	newSession(options?: {
+		parentSession?: string;
+		setup?: (sessionManager: SessionManager) => Promise<void>;
+		withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+	}): Promise<{ cancelled: boolean }>;
+
+	/** Fork from a specific entry, creating a new session file. */
+	fork(
+		entryId: string,
+		options?: { position?: "before" | "at"; withSession?: (ctx: ReplacedSessionContext) => Promise<void> },
+	): Promise<{ cancelled: boolean }>;
+
+	/** Navigate to a different point in the session tree. */
+	navigateTree(
+		targetId: string,
+		options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string },
+	): Promise<{ cancelled: boolean }>;
+
+	/** Switch to a different session file. */
+	switchSession(
+		sessionPath: string,
+		options?: { withSession?: (ctx: ReplacedSessionContext) => Promise<void> },
+	): Promise<{ cancelled: boolean }>;
+
+	/** Reload extensions, skills, prompts, themes, and context files. */
+	reload(): Promise<void>;
+}
+
+/**
+ * Fresh command-capable context bound to the replacement session after a session switch.
+ *
+ * This is passed to `withSession()` callbacks on `newSession()`, `fork()`, and `switchSession()`.
+ */
+export interface ReplacedSessionContext extends ExtensionCommandContext {
+	sendMessage<T = unknown>(
+		message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">,
+		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+	): Promise<void>;
+
+	sendUserMessage(
+		content: string | (TextContent | ImageContent)[],
+		options?: { deliverAs?: "steer" | "followUp"; expandPromptTemplates?: boolean },
+	): Promise<void>;
+}
+
+// ============================================================================
+// Tool Types
+// ============================================================================
+
+/** Rendering options for tool results */
+export interface ToolRenderResultOptions {
+	/** Whether the result view is expanded */
+	expanded: boolean;
+	/** Whether this is a partial/streaming result */
+	isPartial: boolean;
+}
+
+/** Context passed to tool renderers. */
+export interface ToolRenderContext<TState = any, TArgs = any> {
+	/** Current tool call arguments. Shared across call/result renders for the same tool call. */
+	args: TArgs;
+	/** Unique id for this tool execution. Stable across call/result renders for the same tool call. */
+	toolCallId: string;
+	/** Invalidate just this tool execution component for redraw. */
+	invalidate: () => void;
+	/** Previously returned component for this render slot, if any. */
+	lastComponent: Component | undefined;
+	/** Shared renderer state for this tool row. Initialized by tool-execution.ts. */
+	state: TState;
+	/** Working directory for this tool execution. */
+	cwd: string;
+	/** Whether the tool execution has started. */
+	executionStarted: boolean;
+	/** Whether the tool call arguments are complete. */
+	argsComplete: boolean;
+	/** Whether the tool result is partial/streaming. */
+	isPartial: boolean;
+	/** Whether the result view is expanded. */
+	expanded: boolean;
+	/** Whether inline images are currently shown in the TUI. */
+	showImages: boolean;
+	/** Whether the current result is an error. */
+	isError: boolean;
+}
+
+/**
+ * Tool definition for registerTool().
+ */
+export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = unknown, TState = any> {
+	/** Tool name (used in LLM tool calls) */
+	name: string;
+	/** Human-readable label for UI */
+	label: string;
+	/** Description for LLM */
+	description: string;
+	/** Optional one-line snippet for the Available tools section in the default system prompt. Custom tools are omitted from that section when this is not provided. */
+	promptSnippet?: string;
+	/** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */
+	promptGuidelines?: string[];
+	/** Parameter schema (TypeBox) */
+	parameters: TParams;
+	/** Optional provider-side constrained sampling request for this tool. Set false to explicitly disable it, equivalent to leaving it undefined. */
+	constrainedSampling?: false | ConstrainedSamplingConfig;
+	/** Controls whether ToolExecutionComponent renders the standard colored shell or the tool renders its own framing. */
+	renderShell?: "default" | "self";
+
+	/** Optional compatibility shim to prepare raw tool call arguments before schema validation. Must return an object conforming to TParams. */
+	prepareArguments?: (args: unknown) => Static<TParams>;
+
+	/**
+	 * Per-tool execution mode override.
+	 * - "sequential": this tool must execute one at a time with other tool calls.
+	 * - "parallel": this tool can execute concurrently with other tool calls.
+	 *
+	 * If omitted, the default execution mode applies.
+	 */
+	executionMode?: ToolExecutionMode;
+
+	/** Execute the tool. */
+	execute(
+		toolCallId: string,
+		params: Static<TParams>,
+		signal: AbortSignal | undefined,
+		onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
+		ctx: ExtensionContext,
+	): Promise<AgentToolResult<TDetails>>;
+
+	/** Custom rendering for tool call display */
+	renderCall?: (args: Static<TParams>, theme: Theme, context: ToolRenderContext<TState, Static<TParams>>) => Component;
+
+	/** Custom rendering for tool result display */
+	renderResult?: (
+		result: AgentToolResult<TDetails>,
+		options: ToolRenderResultOptions,
+		theme: Theme,
+		context: ToolRenderContext<TState, Static<TParams>>,
+	) => Component;
+}
+
+type AnyToolDefinition = ToolDefinition<any, any, any>;
+
+/**
+ * Preserve parameter inference for standalone tool definitions.
+ *
+ * Use this when assigning a tool to a variable or passing it through arrays such
+ * as `customTools`, where contextual typing would otherwise widen params to
+ * `unknown`.
+ */
+export function defineTool<TParams extends TSchema, TDetails = unknown, TState = any>(
+	tool: ToolDefinition<TParams, TDetails, TState>,
+): ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition {
+	return tool as ToolDefinition<TParams, TDetails, TState> & AnyToolDefinition;
+}
+
+// ============================================================================
+// Startup/Resource Events
+// ============================================================================
+
+export interface ProjectTrustEvent {
+	type: "project_trust";
+	cwd: string;
+}
+
+export type ProjectTrustEventDecision = "yes" | "no" | "undecided";
+
+export interface ProjectTrustEventResult {
+	trusted: ProjectTrustEventDecision;
+	remember?: boolean;
+}
+
+export interface ProjectTrustContext {
+	cwd: string;
+	mode: ExtensionMode;
+	hasUI: boolean;
+	ui: Pick<ExtensionUIContext, "select" | "confirm" | "input" | "notify">;
+}
+
+export type ProjectTrustHandler = (
+	event: ProjectTrustEvent,
+	ctx: ProjectTrustContext,
+) => Promise<ProjectTrustEventResult> | ProjectTrustEventResult;
+
+/** Fired after session_start to allow extensions to provide additional resource paths. */
+export interface ResourcesDiscoverEvent {
+	type: "resources_discover";
+	cwd: string;
+	reason: "startup" | "reload";
+}
+
+/** Result from resources_discover event handler */
+export interface ResourcesDiscoverResult {
+	skillPaths?: string[];
+	promptPaths?: string[];
+	themePaths?: string[];
+}
+
+// ============================================================================
+// Session Events
+// ============================================================================
+
+/** Fired when a session is started, loaded, or reloaded */
+export interface SessionStartEvent {
+	type: "session_start";
+	/** Why this session start happened. */
+	reason: "startup" | "reload" | "new" | "resume" | "fork";
+	/** Previously active session file. Present for "new", "resume", and "fork". */
+	previousSessionFile?: string;
+}
+
+/** Fired when the current session metadata changes. */
+export interface SessionInfoChangedEvent {
+	type: "session_info_changed";
+	/** Current normalized session name. Undefined when the name is cleared. */
+	name: string | undefined;
+}
+
+/** Fired before switching to another session (can be cancelled) */
+export interface SessionBeforeSwitchEvent {
+	type: "session_before_switch";
+	reason: "new" | "resume";
+	targetSessionFile?: string;
+}
+
+/** Fired before forking a session (can be cancelled) */
+export interface SessionBeforeForkEvent {
+	type: "session_before_fork";
+	entryId: string;
+	position: "before" | "at";
+}
+
+/** Fired before context compaction (can be cancelled or customized) */
+export interface SessionBeforeCompactEvent {
+	type: "session_before_compact";
+	preparation: CompactionPreparation;
+	branchEntries: SessionEntry[];
+	customInstructions?: string;
+	/** What triggered the compaction: manual /compact, the context threshold, or context overflow recovery */
+	reason: "manual" | "threshold" | "overflow";
+	/** True when the aborted turn is retried after this compaction (overflow recovery) */
+	willRetry: boolean;
+	signal: AbortSignal;
+}
+
+/** Fired after context compaction succeeds */
+export interface SessionCompactEvent {
+	type: "session_compact";
+	compactionEntry: CompactionEntry;
+	fromExtension: boolean;
+	/** What triggered the compaction: manual /compact, the context threshold, or context overflow recovery */
+	reason: "manual" | "threshold" | "overflow";
+	/** True when the aborted turn is retried after this compaction (overflow recovery) */
+	willRetry: boolean;
+}
+
+/** Fired after context compaction fails or is aborted */
+export interface SessionCompactFailedEvent {
+	type: "session_compact_failed";
+	/** What triggered the compaction: manual /compact, the context threshold, or context overflow recovery */
+	reason: "manual" | "threshold" | "overflow";
+	/** Error text when compaction failed for a non-abort reason. */
+	errorMessage?: string;
+	/** True when compaction was cancelled or aborted. */
+	aborted: boolean;
+	/** True when the aborted turn would have been retried after this compaction (overflow recovery) */
+	willRetry: boolean;
+	/** True when the failing compaction content came from a session_before_compact handler. */
+	fromExtension: boolean;
+}
+
+/** Fired before an extension runtime is torn down due to quit, reload, or session replacement. */
+export interface SessionShutdownEvent {
+	type: "session_shutdown";
+	reason: "quit" | "reload" | "new" | "resume" | "fork";
+	/** Destination session file when shutting down due to session replacement. */
+	targetSessionFile?: string;
+}
+
+/** Preparation data for tree navigation */
+export interface TreePreparation {
+	targetId: string;
+	oldLeafId: string | null;
+	commonAncestorId: string | null;
+	entriesToSummarize: SessionEntry[];
+	userWantsSummary: boolean;
+	/** Custom instructions for summarization */
+	customInstructions?: string;
+	/** If true, customInstructions replaces the default prompt instead of being appended */
+	replaceInstructions?: boolean;
+	/** Label to attach to the branch summary entry */
+	label?: string;
+}
+
+/** Fired before navigating in the session tree (can be cancelled) */
+export interface SessionBeforeTreeEvent {
+	type: "session_before_tree";
+	preparation: TreePreparation;
+	signal: AbortSignal;
+}
+
+/** Fired after navigating in the session tree */
+export interface SessionTreeEvent {
+	type: "session_tree";
+	newLeafId: string | null;
+	oldLeafId: string | null;
+	summaryEntry?: BranchSummaryEntry;
+	fromExtension?: boolean;
+}
+
+export type SessionEvent =
+	| SessionStartEvent
+	| SessionInfoChangedEvent
+	| SessionBeforeSwitchEvent
+	| SessionBeforeForkEvent
+	| SessionBeforeCompactEvent
+	| SessionCompactEvent
+	| SessionCompactFailedEvent
+	| SessionShutdownEvent
+	| SessionBeforeTreeEvent
+	| SessionTreeEvent;
+
+// ============================================================================
+// Agent Events
+// ============================================================================
+
+/** Fired before each LLM call. Can modify messages. */
+export interface ContextEvent {
+	type: "context";
+	messages: AgentMessage[];
+}
+
+/** Fired before a provider request is sent. Can replace the payload. */
+export interface BeforeProviderRequestEvent {
+	type: "before_provider_request";
+	payload: unknown;
+}
+
+/**
+ * Fired after request headers are assembled, before the provider HTTP call.
+ * Handlers mutate `headers` in place (e.g. to inject tracing/session headers);
+ * the return value is ignored. A `null` value deletes that header.
+ */
+export interface BeforeProviderHeadersEvent {
+	type: "before_provider_headers";
+	headers: ProviderHeaders;
+}
+
+/** Fired after a provider response is received and before the response stream is consumed. */
+export interface AfterProviderResponseEvent {
+	type: "after_provider_response";
+	status: number;
+	headers: Record<string, string>;
+}
+
+/** Fired after user submits prompt but before agent loop. */
+export interface BeforeAgentStartEvent {
+	type: "before_agent_start";
+	/** The raw user prompt text (after expansion). */
+	prompt: string;
+	/** Images attached to the user prompt, if any. */
+	images?: ImageContent[];
+	/** The fully assembled system prompt string. */
+	systemPrompt: string;
+	/** Structured options used to build the system prompt. Extensions can inspect this to understand what Pi loaded without re-discovering resources. */
+	systemPromptOptions: BuildSystemPromptOptions;
+}
+
+/** Fired when an agent loop starts */
+export interface AgentStartEvent {
+	type: "agent_start";
+}
+
+/** Fired when an agent loop ends */
+export interface AgentEndEvent {
+	type: "agent_end";
+	messages: AgentMessage[];
+}
+
+/** Fired after an agent run has fully settled and no automatic retry, compaction, or queued continuation will run. */
+export interface AgentSettledEvent {
+	type: "agent_settled";
+}
+
+export type UIPromptKind = "select" | "confirm" | "input" | "editor" | "custom";
+
+/** Fired when Pi starts waiting on a blocking user-facing extension UI prompt. */
+export interface UIPromptStartEvent {
+	type: "ui_prompt_start";
+	reason: "ui_prompt";
+	kind: UIPromptKind;
+	title?: string;
+}
+
+/** Fired when Pi is no longer waiting on a blocking user-facing extension UI prompt. */
+export interface UIPromptEndEvent {
+	type: "ui_prompt_end";
+	reason: "ui_prompt";
+	kind: UIPromptKind;
+	title?: string;
+}
+
+/** Fired at the start of each turn */
+export interface TurnStartEvent {
+	type: "turn_start";
+	turnIndex: number;
+	timestamp: number;
+}
+
+/** Fired at the end of each turn */
+export interface TurnEndEvent {
+	type: "turn_end";
+	turnIndex: number;
+	message: AgentMessage;
+	toolResults: ToolResultMessage[];
+}
+
+/** Fired when a message starts (user, assistant, or toolResult) */
+export interface MessageStartEvent {
+	type: "message_start";
+	message: AgentMessage;
+}
+
+/** Fired during assistant message streaming with token-by-token updates */
+export interface MessageUpdateEvent {
+	type: "message_update";
+	message: AgentMessage;
+	assistantMessageEvent: AssistantMessageEvent;
+}
+
+/** Fired when a message ends */
+export interface MessageEndEvent {
+	type: "message_end";
+	message: AgentMessage;
+}
+
+/** Fired when a tool starts executing */
+export interface ToolExecutionStartEvent {
+	type: "tool_execution_start";
+	toolCallId: string;
+	toolName: string;
+	args: any;
+}
+
+/** Fired during tool execution with partial/streaming output */
+export interface ToolExecutionUpdateEvent {
+	type: "tool_execution_update";
+	toolCallId: string;
+	toolName: string;
+	args: any;
+	partialResult: any;
+}
+
+/** Fired when a tool finishes executing */
+export interface ToolExecutionEndEvent {
+	type: "tool_execution_end";
+	toolCallId: string;
+	toolName: string;
+	result: any;
+	isError: boolean;
+}
+
+// ============================================================================
+// Model Events
+// ============================================================================
+
+export type ModelSelectSource = "set" | "cycle" | "restore";
+
+/** Fired when a new model is selected */
+export interface ModelSelectEvent {
+	type: "model_select";
+	model: Model<any>;
+	previousModel: Model<any> | undefined;
+	source: ModelSelectSource;
+}
+
+/** Fired when a new thinking level is selected */
+export interface ThinkingLevelSelectEvent {
+	type: "thinking_level_select";
+	level: ThinkingLevel;
+	previousLevel: ThinkingLevel;
+}
+
+// ============================================================================
+// User Bash Events
+// ============================================================================
+
+/** Fired when user executes a bash command via ! or !! prefix */
+export interface UserBashEvent {
+	type: "user_bash";
+	/** The command to execute */
+	command: string;
+	/** True if !! prefix was used (excluded from LLM context) */
+	excludeFromContext: boolean;
+	/** Current working directory */
+	cwd: string;
+}
+
+// ============================================================================
+// Input Events
+// ============================================================================
+
+/** Source of user input */
+export type InputSource = "interactive" | "rpc" | "extension";
+
+/** Fired when user input is received, before agent processing */
+export interface InputEvent {
+	type: "input";
+	/** The input text */
+	text: string;
+	/** Attached images, if any */
+	images?: ImageContent[];
+	/** Where the input came from */
+	source: InputSource;
+	/** How the input will be delivered during streaming, or undefined when idle */
+	streamingBehavior?: "steer" | "followUp";
+}
+
+/** Result from input event handler */
+export type InputEventResult =
+	| { action: "continue" }
+	| { action: "transform"; text: string; images?: ImageContent[] }
+	| { action: "handled" };
+
+// ============================================================================
+// Tool Events
+// ============================================================================
+
+interface ToolCallEventBase {
+	type: "tool_call";
+	toolCallId: string;
+}
+
+export interface BashToolCallEvent extends ToolCallEventBase {
+	toolName: "bash";
+	input: BashToolInput;
+}
+
+export interface PowerShellToolCallEvent extends ToolCallEventBase {
+	toolName: "powershell";
+	input: PowerShellToolInput;
+}
+
+export interface ReadToolCallEvent extends ToolCallEventBase {
+	toolName: "read";
+	input: ReadToolInput;
+}
+
+export interface EditToolCallEvent extends ToolCallEventBase {
+	toolName: "edit";
+	input: EditToolInput;
+}
+
+export interface WriteToolCallEvent extends ToolCallEventBase {
+	toolName: "write";
+	input: WriteToolInput;
+}
+
+export interface GrepToolCallEvent extends ToolCallEventBase {
+	toolName: "grep";
+	input: GrepToolInput;
+}
+
+export interface FindToolCallEvent extends ToolCallEventBase {
+	toolName: "find";
+	input: FindToolInput;
+}
+
+export interface LsToolCallEvent extends ToolCallEventBase {
+	toolName: "ls";
+	input: LsToolInput;
+}
+
+export interface CustomToolCallEvent extends ToolCallEventBase {
+	toolName: string;
+	input: Record<string, unknown>;
+}
+
+/**
+ * Fired before a tool executes. Can block.
+ *
+ * `event.input` is mutable. Mutate it in place to patch tool arguments before execution.
+ * Later `tool_call` handlers see earlier mutations. No re-validation is performed after mutation.
+ */
+export type ToolCallEvent =
+	| BashToolCallEvent
+	| PowerShellToolCallEvent
+	| ReadToolCallEvent
+	| EditToolCallEvent
+	| WriteToolCallEvent
+	| GrepToolCallEvent
+	| FindToolCallEvent
+	| LsToolCallEvent
+	| CustomToolCallEvent;
+
+interface ToolResultEventBase {
+	type: "tool_result";
+	toolCallId: string;
+	input: Record<string, unknown>;
+	content: (TextContent | ImageContent)[];
+	isError: boolean;
+	/** Usage from the tool execution itself, if available. */
+	usage?: Usage;
+}
+
+export interface BashToolResultEvent extends ToolResultEventBase {
+	toolName: "bash";
+	details: BashToolDetails | undefined;
+}
+
+export interface PowerShellToolResultEvent extends ToolResultEventBase {
+	toolName: "powershell";
+	details: PowerShellToolDetails | undefined;
+}
+
+export interface ReadToolResultEvent extends ToolResultEventBase {
+	toolName: "read";
+	details: ReadToolDetails | undefined;
+}
+
+export interface EditToolResultEvent extends ToolResultEventBase {
+	toolName: "edit";
+	details: EditToolDetails | undefined;
+}
+
+export interface WriteToolResultEvent extends ToolResultEventBase {
+	toolName: "write";
+	details: undefined;
+}
+
+export interface GrepToolResultEvent extends ToolResultEventBase {
+	toolName: "grep";
+	details: GrepToolDetails | undefined;
+}
+
+export interface FindToolResultEvent extends ToolResultEventBase {
+	toolName: "find";
+	details: FindToolDetails | undefined;
+}
+
+export interface LsToolResultEvent extends ToolResultEventBase {
+	toolName: "ls";
+	details: LsToolDetails | undefined;
+}
+
+export interface CustomToolResultEvent extends ToolResultEventBase {
+	toolName: string;
+	details: unknown;
+}
+
+/** Fired after a tool executes. Can modify result. */
+export type ToolResultEvent =
+	| BashToolResultEvent
+	| PowerShellToolResultEvent
+	| ReadToolResultEvent
+	| EditToolResultEvent
+	| WriteToolResultEvent
+	| GrepToolResultEvent
+	| FindToolResultEvent
+	| LsToolResultEvent
+	| CustomToolResultEvent;
+
+// Type guards for ToolResultEvent
+export function isBashToolResult(e: ToolResultEvent): e is BashToolResultEvent {
+	return e.toolName === "bash";
+}
+export function isPowerShellToolResult(e: ToolResultEvent): e is PowerShellToolResultEvent {
+	return e.toolName === "powershell";
+}
+export function isReadToolResult(e: ToolResultEvent): e is ReadToolResultEvent {
+	return e.toolName === "read";
+}
+export function isEditToolResult(e: ToolResultEvent): e is EditToolResultEvent {
+	return e.toolName === "edit";
+}
+export function isWriteToolResult(e: ToolResultEvent): e is WriteToolResultEvent {
+	return e.toolName === "write";
+}
+export function isGrepToolResult(e: ToolResultEvent): e is GrepToolResultEvent {
+	return e.toolName === "grep";
+}
+export function isFindToolResult(e: ToolResultEvent): e is FindToolResultEvent {
+	return e.toolName === "find";
+}
+export function isLsToolResult(e: ToolResultEvent): e is LsToolResultEvent {
+	return e.toolName === "ls";
+}
+
+/**
+ * Type guard for narrowing ToolCallEvent by tool name.
+ *
+ * Built-in tools narrow automatically (no type params needed):
+ * ```ts
+ * if (isToolCallEventType("bash", event)) {
+ *   event.input.command;  // string
+ * }
+ * ```
+ *
+ * Custom tools require explicit type parameters:
+ * ```ts
+ * if (isToolCallEventType<"my_tool", MyToolInput>("my_tool", event)) {
+ *   event.input.action;  // typed
+ * }
+ * ```
+ *
+ * Note: Direct narrowing via `event.toolName === "bash"` doesn't work because
+ * CustomToolCallEvent.toolName is `string` which overlaps with all literals.
+ */
+export function isToolCallEventType(toolName: "bash", event: ToolCallEvent): event is BashToolCallEvent;
+export function isToolCallEventType(toolName: "powershell", event: ToolCallEvent): event is PowerShellToolCallEvent;
+export function isToolCallEventType(toolName: "read", event: ToolCallEvent): event is ReadToolCallEvent;
+export function isToolCallEventType(toolName: "edit", event: ToolCallEvent): event is EditToolCallEvent;
+export function isToolCallEventType(toolName: "write", event: ToolCallEvent): event is WriteToolCallEvent;
+export function isToolCallEventType(toolName: "grep", event: ToolCallEvent): event is GrepToolCallEvent;
+export function isToolCallEventType(toolName: "find", event: ToolCallEvent): event is FindToolCallEvent;
+export function isToolCallEventType(toolName: "ls", event: ToolCallEvent): event is LsToolCallEvent;
+export function isToolCallEventType<TName extends string, TInput extends Record<string, unknown>>(
+	toolName: TName,
+	event: ToolCallEvent,
+): event is ToolCallEvent & { toolName: TName; input: TInput };
+export function isToolCallEventType(toolName: string, event: ToolCallEvent): boolean {
+	return event.toolName === toolName;
+}
+
+/** Union of all event types */
+export type ExtensionEvent =
+	| ProjectTrustEvent
+	| ResourcesDiscoverEvent
+	| SessionEvent
+	| ContextEvent
+	| BeforeProviderRequestEvent
+	| BeforeProviderHeadersEvent
+	| AfterProviderResponseEvent
+	| BeforeAgentStartEvent
+	| AgentStartEvent
+	| AgentEndEvent
+	| AgentSettledEvent
+	| UIPromptStartEvent
+	| UIPromptEndEvent
+	| TurnStartEvent
+	| TurnEndEvent
+	| MessageStartEvent
+	| MessageUpdateEvent
+	| MessageEndEvent
+	| ToolExecutionStartEvent
+	| ToolExecutionUpdateEvent
+	| ToolExecutionEndEvent
+	| ModelSelectEvent
+	| ThinkingLevelSelectEvent
+	| UserBashEvent
+	| InputEvent
+	| ToolCallEvent
+	| ToolResultEvent;
+
+// ============================================================================
+// Event Results
+// ============================================================================
+
+export interface ContextEventResult {
+	messages?: AgentMessage[];
+}
+
+export type BeforeProviderRequestEventResult = unknown;
+
+export interface ToolCallEventResult {
+	/** Block tool execution. To modify arguments, mutate `event.input` in place instead. */
+	block?: boolean;
+	reason?: string;
+	/**
+	 * Hint that the agent should stop after the current tool batch when this call is blocked.
+	 * Early termination only happens when every finalized tool result in the batch sets this to true.
+	 */
+	terminate?: boolean;
+}
+
+/** Result from user_bash event handler */
+export interface UserBashEventResult {
+	/** Custom operations to use for execution */
+	operations?: BashOperations;
+	/** Full replacement: extension handled execution, use this result */
+	result?: BashResult;
+}
+
+export interface ToolResultEventResult {
+	content?: (TextContent | ImageContent)[];
+	details?: unknown;
+	isError?: boolean;
+	usage?: Usage;
+}
+
+export interface MessageEndEventResult {
+	/** Replace the finalized message. The replacement must keep the original message role. */
+	message?: AgentMessage;
+}
+
+export interface BeforeAgentStartEventResult {
+	message?: Pick<CustomMessage, "customType" | "content" | "display" | "details">;
+	/** Replace the system prompt for this turn. If multiple extensions return this, they are chained. */
+	systemPrompt?: string;
+}
+
+export interface SessionBeforeSwitchResult {
+	cancel?: boolean;
+}
+
+export interface SessionBeforeForkResult {
+	cancel?: boolean;
+	skipConversationRestore?: boolean;
+}
+
+export interface SessionBeforeCompactResult {
+	cancel?: boolean;
+	compaction?: CompactionResult;
+}
+
+export interface SessionBeforeTreeResult {
+	cancel?: boolean;
+	summary?: {
+		summary: string;
+		details?: unknown;
+		usage?: Usage;
+	};
+	/** Override custom instructions for summarization */
+	customInstructions?: string;
+	/** Override whether customInstructions replaces the default prompt */
+	replaceInstructions?: boolean;
+	/** Override label to attach to the branch summary entry */
+	label?: string;
+}
+
+// ============================================================================
+// Message and Entry Rendering
+// ============================================================================
+
+export interface MessageRenderOptions {
+	expanded: boolean;
+	/** Horizontal padding configured by the outputPad setting. */
+	outputPad: number;
+}
+
+export interface MarkdownTransformContext {
+	messageType: "user" | "assistant" | "assistant-thinking";
+	isStreaming: boolean;
+	availableWidth: number;
+}
+
+export type MarkdownTransformer = (markdown: string, context: MarkdownTransformContext) => string;
+
+export interface EntryRenderOptions {
+	expanded: boolean;
+}
+
+export type MessageRenderer<T = unknown> = (
+	message: CustomMessage<T>,
+	options: MessageRenderOptions,
+	theme: Theme,
+) => Component | undefined;
+
+export type EntryRenderer<T = unknown> = (
+	entry: CustomEntry<T>,
+	options: EntryRenderOptions,
+	theme: Theme,
+) => Component | undefined;
+
+// ============================================================================
+// Command Registration
+// ============================================================================
+
+export interface RegisteredCommand {
+	name: string;
+	sourceInfo: SourceInfo;
+	description?: string;
+	getArgumentCompletions?: (argumentPrefix: string) => AutocompleteItem[] | null | Promise<AutocompleteItem[] | null>;
+	handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
+}
+
+export interface ResolvedCommand extends RegisteredCommand {
+	invocationName: string;
+}
+
+// ============================================================================
+// Extension API
+// ============================================================================
+
+/** Handler function type for events */
+// biome-ignore lint/suspicious/noConfusingVoidType: void allows bare return statements
+export type ExtensionHandler<E, R = undefined> = (event: E, ctx: ExtensionContext) => Promise<R | void> | R | void;
+
+/**
+ * ExtensionAPI passed to extension factory functions.
+ */
+export interface ExtensionAPI {
+	// =========================================================================
+	// Event Subscription
+	// =========================================================================
+
+	on(event: "project_trust", handler: ProjectTrustHandler): void;
+	on(event: "resources_discover", handler: ExtensionHandler<ResourcesDiscoverEvent, ResourcesDiscoverResult>): void;
+	on(event: "session_start", handler: ExtensionHandler<SessionStartEvent>): void;
+	on(event: "session_info_changed", handler: ExtensionHandler<SessionInfoChangedEvent>): void;
+	on(
+		event: "session_before_switch",
+		handler: ExtensionHandler<SessionBeforeSwitchEvent, SessionBeforeSwitchResult>,
+	): void;
+	on(event: "session_before_fork", handler: ExtensionHandler<SessionBeforeForkEvent, SessionBeforeForkResult>): void;
+	on(
+		event: "session_before_compact",
+		handler: ExtensionHandler<SessionBeforeCompactEvent, SessionBeforeCompactResult>,
+	): void;
+	on(event: "session_compact", handler: ExtensionHandler<SessionCompactEvent>): void;
+	on(event: "session_compact_failed", handler: ExtensionHandler<SessionCompactFailedEvent>): void;
+	on(event: "session_shutdown", handler: ExtensionHandler<SessionShutdownEvent>): void;
+	on(event: "session_before_tree", handler: ExtensionHandler<SessionBeforeTreeEvent, SessionBeforeTreeResult>): void;
+	on(event: "session_tree", handler: ExtensionHandler<SessionTreeEvent>): void;
+	on(event: "context", handler: ExtensionHandler<ContextEvent, ContextEventResult>): void;
+	on(
+		event: "before_provider_request",
+		handler: ExtensionHandler<BeforeProviderRequestEvent, BeforeProviderRequestEventResult>,
+	): void;
+	on(event: "before_provider_headers", handler: ExtensionHandler<BeforeProviderHeadersEvent>): void;
+	on(event: "after_provider_response", handler: ExtensionHandler<AfterProviderResponseEvent>): void;
+	on(event: "before_agent_start", handler: ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult>): void;
+	on(event: "agent_start", handler: ExtensionHandler<AgentStartEvent>): void;
+	on(event: "agent_end", handler: ExtensionHandler<AgentEndEvent>): void;
+	on(event: "agent_settled", handler: ExtensionHandler<AgentSettledEvent>): void;
+	on(event: "ui_prompt_start", handler: ExtensionHandler<UIPromptStartEvent>): void;
+	on(event: "ui_prompt_end", handler: ExtensionHandler<UIPromptEndEvent>): void;
+	on(event: "turn_start", handler: ExtensionHandler<TurnStartEvent>): void;
+	on(event: "turn_end", handler: ExtensionHandler<TurnEndEvent>): void;
+	on(event: "message_start", handler: ExtensionHandler<MessageStartEvent>): void;
+	on(event: "message_update", handler: ExtensionHandler<MessageUpdateEvent>): void;
+	on(event: "message_end", handler: ExtensionHandler<MessageEndEvent, MessageEndEventResult>): void;
+	on(event: "tool_execution_start", handler: ExtensionHandler<ToolExecutionStartEvent>): void;
+	on(event: "tool_execution_update", handler: ExtensionHandler<ToolExecutionUpdateEvent>): void;
+	on(event: "tool_execution_end", handler: ExtensionHandler<ToolExecutionEndEvent>): void;
+	on(event: "model_select", handler: ExtensionHandler<ModelSelectEvent>): void;
+	on(event: "thinking_level_select", handler: ExtensionHandler<ThinkingLevelSelectEvent>): void;
+	on(event: "tool_call", handler: ExtensionHandler<ToolCallEvent, ToolCallEventResult>): void;
+	on(event: "tool_result", handler: ExtensionHandler<ToolResultEvent, ToolResultEventResult>): void;
+	on(event: "user_bash", handler: ExtensionHandler<UserBashEvent, UserBashEventResult>): void;
+	on(event: "input", handler: ExtensionHandler<InputEvent, InputEventResult>): void;
+
+	// =========================================================================
+	// Tool Registration
+	// =========================================================================
+
+	/** Register a tool that the LLM can call. */
+	registerTool<TParams extends TSchema = TSchema, TDetails = unknown, TState = any>(
+		tool: ToolDefinition<TParams, TDetails, TState>,
+	): void;
+
+	// =========================================================================
+	// Command, Shortcut, Flag Registration
+	// =========================================================================
+
+	/** Register a custom command. */
+	registerCommand(name: string, options: Omit<RegisteredCommand, "name" | "sourceInfo">): void;
+
+	/** Register a keyboard shortcut. */
+	registerShortcut(
+		shortcut: KeyId,
+		options: {
+			description?: string;
+			handler: (ctx: ExtensionContext) => Promise<void> | void;
+		},
+	): void;
+
+	/** Register a CLI flag. */
+	registerFlag(
+		name: string,
+		options:
+			| {
+					description?: string;
+					type: "boolean";
+					default?: boolean;
+			  }
+			| {
+					description?: string;
+					type: "string";
+					default?: string;
+			  },
+	): void;
+
+	/** Get the value of a registered CLI flag. */
+	getFlag(name: string): boolean | string | undefined;
+
+	// =========================================================================
+	// Message Rendering
+	// =========================================================================
+
+	/** Register a custom renderer for CustomMessageEntry. */
+	registerMessageRenderer<T = unknown>(customType: string, renderer: MessageRenderer<T>): void;
+
+	/** Register a transformer for user and assistant Markdown before Pi renders it in the interactive transcript. */
+	registerMarkdownTransformer(transformer: MarkdownTransformer): void;
+
+	/** Register a custom renderer for CustomEntry. Custom entries do not participate in LLM context. */
+	registerEntryRenderer<T = unknown>(customType: string, renderer: EntryRenderer<T>): void;
+
+	// =========================================================================
+	// Actions
+	// =========================================================================
+
+	/** Send a custom message to the session. */
+	sendMessage<T = unknown>(
+		message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">,
+		options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+	): void;
+
+	/**
+	 * Send a user message to the agent. Always triggers a turn.
+	 * When the agent is streaming, use deliverAs to specify how to queue the message.
+	 * Set expandPromptTemplates to dispatch extension commands and expand skill commands and prompt templates.
+	 */
+	sendUserMessage(
+		content: string | (TextContent | ImageContent)[],
+		options?: { deliverAs?: "steer" | "followUp"; expandPromptTemplates?: boolean },
+	): void;
+
+	/** Append a custom entry to the session for state persistence (not sent to LLM). */
+	appendEntry<T = unknown>(customType: string, data?: T): void;
+
+	// =========================================================================
+	// Session Metadata
+	// =========================================================================
+
+	/** Set the session display name (shown in session selector). */
+	setSessionName(name: string): void;
+
+	/** Get the current session name, if set. */
+	getSessionName(): string | undefined;
+
+	/** Set or clear a label on an entry. Labels are user-defined markers for bookmarking/navigation. */
+	setLabel(entryId: string, label: string | undefined): void;
+
+	/** Execute a shell command. */
+	exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
+
+	/** Get the list of currently active tool names. */
+	getActiveTools(): string[];
+
+	/** Get all configured tools with parameter schema, prompt guidelines, and source metadata. */
+	getAllTools(): ToolInfo[];
+
+	/** Set the active tools by name. */
+	setActiveTools(toolNames: string[]): void;
+
+	/** Get available slash commands in the current session. */
+	getCommands(): SlashCommandInfo[];
+
+	// =========================================================================
+	// Model and Thinking Level
+	// =========================================================================
+
+	/**
+	 * Set the model for the current session without changing the configured default for new sessions.
+	 * Returns false if authentication is not configured for the model's provider.
+	 */
+	setModel(model: Model<any>): Promise<boolean>;
+
+	/** Get current thinking level. */
+	getThinkingLevel(): ThinkingLevel;
+
+	/**
+	 * Set the thinking level (clamped to model capabilities) for the current session without changing the configured default
+	 * for new sessions.
+	 */
+	setThinkingLevel(level: ThinkingLevel): void;
+
+	// =========================================================================
+	// Provider Registration
+	// =========================================================================
+
+	/**
+	 * Register or override a model provider.
+	 *
+	 * If `models` is provided: replaces all existing models for this provider.
+	 * If only `baseUrl` is provided: overrides the URL for existing models.
+	 * If `oauth` is provided: registers OAuth provider for /login support.
+	 * If `streamSimple` is provided: registers a custom API stream handler.
+	 *
+	 * During initial extension load this call is queued and applied once the
+	 * runner has bound its context. After that it takes effect immediately, so
+	 * it is safe to call from command handlers or event callbacks without
+	 * requiring a `/reload`.
+	 *
+	 * @example
+	 * // Register a new provider with custom models
+	 * pi.registerProvider("my-proxy", {
+	 *   baseUrl: "https://proxy.example.com",
+	 *   apiKey: "$PROXY_API_KEY",
+	 *   api: "anthropic-messages",
+	 *   models: [
+	 *     {
+	 *       id: "claude-sonnet-4-20250514",
+	 *       name: "Claude 4 Sonnet (proxy)",
+	 *       reasoning: false,
+	 *       input: ["text", "image"],
+	 *       cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	 *       contextWindow: 200000,
+	 *       maxTokens: 16384
+	 *     }
+	 *   ]
+	 * });
+	 *
+	 * @example
+	 * // Override baseUrl for an existing provider
+	 * pi.registerProvider("anthropic", {
+	 *   baseUrl: "https://proxy.example.com"
+	 * });
+	 *
+	 * @example
+	 * // Register provider with OAuth support
+	 * pi.registerProvider("corporate-ai", {
+	 *   baseUrl: "https://ai.corp.com",
+	 *   api: "openai-responses",
+	 *   models: [...],
+	 *   oauth: {
+	 *     name: "Corporate AI (SSO)",
+	 *     async login(callbacks) { ... },
+	 *     async refreshToken(credentials) { ... },
+	 *     getApiKey(credentials) { return credentials.access; }
+	 *   }
+	 * });
+	 */
+	registerProvider(provider: Provider): void;
+	registerProvider(name: string, config: ProviderConfig): void;
+
+	/**
+	 * Unregister a previously registered provider.
+	 *
+	 * Removes all models belonging to the named provider and restores any
+	 * built-in models that were overridden by it. Has no effect if the provider
+	 * is not currently registered.
+	 *
+	 * Like `registerProvider`, this takes effect immediately when called after
+	 * the initial load phase.
+	 *
+	 * @example
+	 * pi.unregisterProvider("my-proxy");
+	 */
+	unregisterProvider(name: string): void;
+
+	/** Shared event bus for extension communication. */
+	events: EventBus;
+}
+
+// ============================================================================
+// Provider Registration Types
+// ============================================================================
+
+/** Configuration for registering a provider via pi.registerProvider(). */
+export interface ProviderConfig {
+	/** Display name for the provider in UI. */
+	name?: string;
+	/** Base URL for the API endpoint. Required when defining models. */
+	baseUrl?: string;
+	/** API key literal, env interpolation ($ENV_VAR or ${ENV_VAR}), or leading !command. Required when defining models (unless oauth provided). */
+	apiKey?: string;
+	/** API type. Required at provider or model level when defining models. */
+	api?: Api;
+	/**
+	 * Optional streamSimple handler for custom APIs.
+	 * Implementations must invoke `options.onPayload` before sending the provider request and use any
+	 * returned replacement payload. They must invoke `options.onResponse` after receiving the response
+	 * and before consuming its body, matching built-in providers.
+	 */
+	streamSimple?: (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => AssistantMessageEventStream;
+	/** Custom headers to include in requests. */
+	headers?: Record<string, string>;
+	/** If true, adds Authorization: Bearer header with the resolved API key. */
+	authHeader?: boolean;
+	/** Models to register. If provided, replaces all existing models for this provider. */
+	models?: ProviderModelConfig[];
+	/**
+	 * Refresh this provider's model list. The returned list replaces extension-provided models.
+	 * Use context.publish({ persist: entry }) when the catalog should persist across sessions.
+	 */
+	refreshModels?(context: RefreshModelsContext): Promise<ProviderModelConfig[]>;
+	/** OAuth provider for /login support. The `id` is set automatically from the provider name. */
+	oauth?: {
+		/** Display name for the provider in login UI. */
+		name: string;
+		/** Whether access through this auth method is backed by a provider subscription. */
+		isSubscription?: boolean;
+		/** @deprecated Retained for source compatibility; canonical auth flows ignore it. */
+		usesCallbackServer?: boolean;
+		/** Run the login flow, return credentials to persist. */
+		login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+		/** Refresh expired credentials, return updated credentials to persist. */
+		refreshToken(credentials: OAuthCredentials, signal: AbortSignal): Promise<OAuthCredentials>;
+		/** Convert credentials to API key string for the provider. */
+		getApiKey(credentials: OAuthCredentials): string;
+		/** Legacy synchronous credential-dependent model projection. */
+		modifyModels?(models: Model<Api>[], credentials: OAuthCredentials): Model<Api>[];
+	};
+}
+
+/** Configuration for a model within a provider. */
+export interface ProviderModelConfig {
+	/** Model ID (e.g., "claude-sonnet-4-20250514"). */
+	id: string;
+	/** Display name (e.g., "Claude 4 Sonnet"). */
+	name: string;
+	/** API type override for this model. */
+	api?: Api;
+	/** API endpoint URL override for this model. */
+	baseUrl?: string;
+	/** Whether the model supports extended thinking. */
+	reasoning: boolean;
+	/** Maps pi thinking levels to provider/model-specific values; null marks a level unsupported. */
+	thinkingLevelMap?: Model<Api>["thinkingLevelMap"];
+	/** Supported input types. */
+	input: ("text" | "image")[];
+	/** Per-million-token cost rates and optional request-wide input pricing tiers. */
+	cost: Model<Api>["cost"];
+	/** Maximum context window size in tokens. */
+	contextWindow: number;
+	/** Maximum output tokens. */
+	maxTokens: number;
+	/** Custom headers for this model. */
+	headers?: Record<string, string>;
+	/** OpenAI compatibility settings. */
+	compat?: Model<Api>["compat"];
+}
+
+/** Extension factory function type. Supports both sync and async initialization. */
+export type ExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>;
+
+export type InlineExtension =
+	| ExtensionFactory
+	| {
+			/** Display name shown as `<inline:name>` in the startup Extensions list. */
+			name: string;
+			factory: ExtensionFactory;
+			/** Omit this extension from the startup Extensions list. */
+			hidden?: boolean;
+	  };
+
+// ============================================================================
+// Loaded Extension Types
+// ============================================================================
+
+export interface RegisteredTool {
+	definition: ToolDefinition;
+	sourceInfo: SourceInfo;
+}
+
+export interface ExtensionFlag {
+	name: string;
+	description?: string;
+	type: "boolean" | "string";
+	default?: boolean | string;
+	extensionPath: string;
+}
+
+export interface ExtensionShortcut {
+	shortcut: KeyId;
+	description?: string;
+	handler: (ctx: ExtensionContext) => Promise<void> | void;
+	extensionPath: string;
+}
+
+type HandlerFn = (...args: unknown[]) => Promise<unknown>;
+
+export type SendMessageHandler = <T = unknown>(
+	message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details">,
+	options?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+) => void;
+
+export type SendUserMessageHandler = (
+	content: string | (TextContent | ImageContent)[],
+	options?: { deliverAs?: "steer" | "followUp"; expandPromptTemplates?: boolean },
+) => void;
+
+export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) => void;
+
+export type SetSessionNameHandler = (name: string) => void;
+
+export type GetSessionNameHandler = () => string | undefined;
+
+export type GetActiveToolsHandler = () => string[];
+
+/** Tool info with name, description, parameter schema, prompt guidelines, and source metadata. */
+export type ToolInfo = Pick<ToolDefinition, "name" | "description" | "parameters" | "promptGuidelines"> & {
+	sourceInfo: SourceInfo;
+};
+
+export type GetAllToolsHandler = () => ToolInfo[];
+
+export type GetCommandsHandler = () => SlashCommandInfo[];
+
+export type SetActiveToolsHandler = (toolNames: string[]) => void;
+
+export type RefreshToolsHandler = () => void;
+
+export type SetModelHandler = (model: Model<any>) => Promise<boolean>;
+
+export type GetThinkingLevelHandler = () => ThinkingLevel;
+
+export type SetThinkingLevelHandler = (level: ThinkingLevel) => void;
+
+export type SetLabelHandler = (entryId: string, label: string | undefined) => void;
+
+/**
+ * Shared state created by loader, used during registration and runtime.
+ * Contains flag values (defaults set during registration, CLI values set after).
+ */
+export interface ExtensionRuntimeState {
+	flagValues: Map<string, boolean | string>;
+	/** Legacy provider-config registrations queued during extension loading, processed when runner binds. */
+	pendingProviderRegistrations: Array<{ name: string; config: ProviderConfig; extensionPath: string }>;
+	/** Native pi-ai provider registrations queued during extension loading, processed when runner binds. */
+	pendingNativeProviderRegistrations: Array<{ provider: Provider; extensionPath: string }>;
+	/** Throws when this extension instance is stale after runtime replacement. */
+	assertActive: () => void;
+	/** Marks this extension instance as stale after runtime replacement or reload. */
+	invalidate: (message?: string) => void;
+	/** Retain an event-bus subscription until this runtime is invalidated. */
+	trackEventBusSubscription: (unsubscribe: () => void) => () => void;
+	/**
+	 * Register or unregister a provider.
+	 *
+	 * Before bindCore(): queues registrations / removes from queue.
+	 * After bindCore(): calls ModelRegistry directly for immediate effect.
+	 */
+	registerProvider: (name: string, config: ProviderConfig, extensionPath?: string) => void;
+	registerNativeProvider: (provider: Provider, extensionPath?: string) => void;
+	unregisterProvider: (name: string, extensionPath?: string) => void;
+}
+
+/**
+ * Action implementations for pi.* API methods.
+ * Provided to runner.initialize(), copied into the shared runtime.
+ */
+export interface ExtensionActions {
+	sendMessage: SendMessageHandler;
+	sendUserMessage: SendUserMessageHandler;
+	appendEntry: AppendEntryHandler;
+	setSessionName: SetSessionNameHandler;
+	getSessionName: GetSessionNameHandler;
+	setLabel: SetLabelHandler;
+	getActiveTools: GetActiveToolsHandler;
+	getAllTools: GetAllToolsHandler;
+	setActiveTools: SetActiveToolsHandler;
+	refreshTools: RefreshToolsHandler;
+	getCommands: GetCommandsHandler;
+	setModel: SetModelHandler;
+	getThinkingLevel: GetThinkingLevelHandler;
+	setThinkingLevel: SetThinkingLevelHandler;
+}
+
+/**
+ * Actions for ExtensionContext (ctx.* in event handlers).
+ * Required by all modes.
+ */
+export interface ExtensionContextActions {
+	getModel: () => Model<any> | undefined;
+	getScopedModels: () => readonly ScopedModel[];
+	isIdle: () => boolean;
+	isProjectTrusted: () => boolean;
+	getSignal: () => AbortSignal | undefined;
+	abort: () => void;
+	hasPendingMessages: () => boolean;
+	shutdown: () => void;
+	getContextUsage: () => ContextUsage | undefined;
+	compact: (options?: CompactOptions) => void;
+	getSystemPrompt: () => string;
+	getSystemPromptOptions?: () => BuildSystemPromptOptions;
+}
+
+/**
+ * Actions for ExtensionCommandContext (ctx.* in command handlers).
+ * Only needed for interactive mode where extension commands are invokable.
+ */
+export interface ExtensionCommandContextActions {
+	waitForIdle: () => Promise<void>;
+	newSession: (options?: {
+		parentSession?: string;
+		setup?: (sessionManager: SessionManager) => Promise<void>;
+		withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
+	}) => Promise<{ cancelled: boolean }>;
+	fork: (
+		entryId: string,
+		options?: { position?: "before" | "at"; withSession?: (ctx: ReplacedSessionContext) => Promise<void> },
+	) => Promise<{ cancelled: boolean }>;
+	navigateTree: (
+		targetId: string,
+		options?: { summarize?: boolean; customInstructions?: string; replaceInstructions?: boolean; label?: string },
+	) => Promise<{ cancelled: boolean }>;
+	switchSession: (
+		sessionPath: string,
+		options?: { withSession?: (ctx: ReplacedSessionContext) => Promise<void> },
+	) => Promise<{ cancelled: boolean }>;
+	reload: () => Promise<void>;
+}
+
+/**
+ * Full runtime = state + actions.
+ * Created by loader with throwing action stubs, completed by runner.initialize().
+ */
+export interface ExtensionRuntime extends ExtensionRuntimeState, ExtensionActions {}
+
+/** Loaded extension with all registered items. */
+export interface Extension {
+	path: string;
+	resolvedPath: string;
+	hidden?: boolean;
+	sourceInfo: SourceInfo;
+	handlers: Map<string, HandlerFn[]>;
+	tools: Map<string, RegisteredTool>;
+	messageRenderers: Map<string, MessageRenderer>;
+	markdownTransformer?: MarkdownTransformer;
+	entryRenderers?: Map<string, EntryRenderer>;
+	commands: Map<string, RegisteredCommand>;
+	flags: Map<string, ExtensionFlag>;
+	shortcuts: Map<KeyId, ExtensionShortcut>;
+}
+
+/** Result of loading extensions. */
+export interface LoadExtensionsResult {
+	extensions: Extension[];
+	errors: Array<{ path: string; error: string }>;
+	/** Shared runtime - actions are throwing stubs until runner.initialize() */
+	runtime: ExtensionRuntime;
+}
+
+// ============================================================================
+// Extension Error
+// ============================================================================
+
+export interface ExtensionError {
+	extensionPath: string;
+	event: string;
+	error: string;
+	stack?: string;
+}

packages/coding-agent/src/core/extensions/wrapper.ts

@@ -0,0 +1,45 @@
+/**
+ * Tool wrappers for extension-registered tools.
+ *
+ * These wrappers only adapt tool execution so extension tools receive the runner context.
+ * Tool call and tool result interception is handled by AgentSession via agent-core hooks.
+ */
+
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { wrapToolDefinition } from "../tools/tool-definition-wrapper.ts";
+import type { ExtensionRunner } from "./runner.ts";
+import type { RegisteredTool } from "./types.ts";
+
+/**
+ * Wrap a RegisteredTool into an AgentTool.
+ * Uses the runner's createContext() for consistent context across tools and event handlers.
+ */
+export function wrapRegisteredTool(registeredTool: RegisteredTool, runner: ExtensionRunner): AgentTool {
+	const tool = wrapToolDefinition(registeredTool.definition, () => runner.createContext());
+	const execute = tool.execute;
+	return {
+		...tool,
+		execute: async (toolCallId, params, signal, onUpdate) => {
+			const activeBefore = runner.getActiveTools();
+			const result = await execute(toolCallId, params, signal, onUpdate);
+			const activeAfter = runner.getActiveTools();
+			if (!activeBefore.every((name) => activeAfter.includes(name))) return result;
+
+			const beforeNames = new Set(activeBefore);
+			const addedToolNames = activeAfter.filter((name) => !beforeNames.has(name));
+			if (addedToolNames.length === 0) return result;
+			return {
+				...result,
+				addedToolNames: [...new Set([...(result.addedToolNames ?? []), ...addedToolNames])],
+			};
+		},
+	};
+}
+
+/**
+ * Wrap all registered tools into AgentTools.
+ * Uses the runner's createContext() for consistent context across tools and event handlers.
+ */
+export function wrapRegisteredTools(registeredTools: RegisteredTool[], runner: ExtensionRunner): AgentTool[] {
+	return registeredTools.map((tool) => wrapRegisteredTool(tool, runner));
+}

packages/coding-agent/src/core/tools/bash.ts

@@ -0,0 +1,400 @@
+import { constants } from "node:fs";
+import { access as fsAccess } from "node:fs/promises";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { spawn } from "child_process";
+import { type Static, Type } from "typebox";
+import { waitForChildProcess } from "../../utils/child-process.ts";
+import {
+	getShellConfig,
+	getShellEnv,
+	killProcessTree,
+	type ShellConfig,
+	trackDetachedChildPid,
+	untrackDetachedChildPid,
+} from "../../utils/shell.ts";
+import type { ExtensionContext, ToolDefinition } from "../extensions/types.ts";
+import { OutputAccumulator } from "./output-accumulator.ts";
+import { BASH_UPDATE_THROTTLE_MS, createShellRenderers } from "./renderers/bash.ts";
+import { wrapToolDefinition } from "./tool-definition-wrapper.ts";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult } from "./truncate.ts";
+
+const MAX_TIMEOUT_MS = 2_147_483_647;
+const MAX_TIMEOUT_SECONDS = MAX_TIMEOUT_MS / 1000;
+
+function resolveTimeoutMs(timeout: number | undefined): number | undefined {
+	if (timeout === undefined) return undefined;
+	if (!Number.isFinite(timeout) || timeout <= 0) {
+		throw new Error("Invalid timeout: must be a finite number of seconds");
+	}
+
+	const timeoutMs = timeout * 1000;
+	if (timeoutMs > MAX_TIMEOUT_MS) {
+		throw new Error(`Invalid timeout: maximum is ${MAX_TIMEOUT_SECONDS} seconds`);
+	}
+	return timeoutMs;
+}
+
+const bashSchema = Type.Object({
+	command: Type.String({ description: "Shell command to execute" }),
+	timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional, no default timeout)" })),
+});
+
+export const bashToolSystemPromptContribution = {
+	snippet: "Execute bash commands (ls, grep, find, etc.)",
+	guidelines: ["You can inspect PI_* environment variables for current model and session details."],
+} as const;
+
+export type BashToolInput = Static<typeof bashSchema>;
+
+export interface BashToolDetails {
+	truncation?: TruncationResult;
+	fullOutputPath?: string;
+}
+
+/**
+ * Pluggable operations for the bash tool.
+ * Override these to delegate command execution to remote systems (for example SSH).
+ */
+export interface BashOperations {
+	/**
+	 * Execute a command and stream output.
+	 * @param command The command to execute
+	 * @param cwd Working directory
+	 * @param options Execution options
+	 * @returns Promise resolving to exit code (null if killed)
+	 */
+	exec: (
+		command: string,
+		cwd: string,
+		options: {
+			onData: (data: Buffer) => void;
+			signal?: AbortSignal;
+			timeout?: number;
+			env?: NodeJS.ProcessEnv;
+		},
+	) => Promise<{ exitCode: number | null }>;
+}
+
+/** Shared process execution used by the built-in shell tools. */
+export function createLocalShellOperations(shellName: string, resolveShellConfig: () => ShellConfig): BashOperations {
+	return {
+		exec: async (command, cwd, { onData, signal, timeout, env }) => {
+			const timeoutMs = resolveTimeoutMs(timeout);
+			if (signal?.aborted) {
+				throw new Error("aborted");
+			}
+			const shellConfig = resolveShellConfig();
+			try {
+				await fsAccess(cwd, constants.F_OK);
+			} catch {
+				throw new Error(`Working directory does not exist: ${cwd}\nCannot execute ${shellName} commands.`);
+			}
+
+			const commandFromStdin = shellConfig.commandTransport === "stdin";
+			const child = spawn(shellConfig.shell, commandFromStdin ? shellConfig.args : [...shellConfig.args, command], {
+				cwd,
+				detached: process.platform !== "win32",
+				env: env ?? getShellEnv(),
+				stdio: [commandFromStdin ? "pipe" : "ignore", "pipe", "pipe"],
+				windowsHide: true,
+			});
+			if (commandFromStdin) {
+				child.stdin?.on("error", () => {});
+				child.stdin?.end(command);
+			}
+			if (child.pid) trackDetachedChildPid(child.pid);
+			let timedOut = false;
+			let timeoutHandle: NodeJS.Timeout | undefined;
+			const onAbort = () => {
+				if (child.pid) killProcessTree(child.pid);
+			};
+
+			try {
+				// Set timeout if provided.
+				if (timeoutMs !== undefined) {
+					timeoutHandle = setTimeout(() => {
+						timedOut = true;
+						if (child.pid) killProcessTree(child.pid);
+					}, timeoutMs);
+				}
+				// Stream stdout and stderr.
+				child.stdout?.on("data", onData);
+				child.stderr?.on("data", onData);
+				// Handle abort signal by killing the entire process tree.
+				if (signal) {
+					if (signal.aborted) onAbort();
+					else signal.addEventListener("abort", onAbort, { once: true });
+				}
+				// Handle shell spawn errors and wait for the process to terminate without hanging
+				// on inherited stdio handles held by detached descendants.
+				const exitCode = await waitForChildProcess(child);
+				if (signal?.aborted) {
+					throw new Error("aborted");
+				}
+				if (timedOut) {
+					throw new Error(`timeout:${timeout}`);
+				}
+				return { exitCode };
+			} finally {
+				if (child.pid) untrackDetachedChildPid(child.pid);
+				if (timeoutHandle) clearTimeout(timeoutHandle);
+				if (signal) signal.removeEventListener("abort", onAbort);
+			}
+		},
+	};
+}
+
+/**
+ * Create bash operations using pi's built-in local shell execution backend.
+ *
+ * This is useful for extensions that intercept user_bash and still want pi's
+ * standard local shell behavior while wrapping or rewriting commands.
+ */
+export function createLocalBashOperations(options?: { shellPath?: string }): BashOperations {
+	return createLocalShellOperations("bash", () => getShellConfig(options?.shellPath));
+}
+
+export interface BashSpawnContext {
+	command: string;
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+}
+
+export type BashSpawnHook = (context: BashSpawnContext) => BashSpawnContext;
+
+function resolveSpawnContext(
+	command: string,
+	cwd: string,
+	spawnHook: BashSpawnHook | undefined,
+	exposeSessionEnvironment: boolean,
+	ctx: ExtensionContext | undefined,
+): BashSpawnContext {
+	const env = { ...getShellEnv() };
+	delete env.PI_SESSION_ID;
+	delete env.PI_SESSION_FILE;
+	delete env.PI_PROVIDER;
+	delete env.PI_MODEL;
+	delete env.PI_REASONING_LEVEL;
+	if (exposeSessionEnvironment && ctx) {
+		const model = ctx.model;
+		env.PI_SESSION_ID = ctx.sessionManager.getSessionId();
+		const sessionFile = ctx.sessionManager.getSessionFile();
+		if (sessionFile) env.PI_SESSION_FILE = sessionFile;
+		if (model) {
+			env.PI_PROVIDER = model.provider;
+			env.PI_MODEL = model.id;
+		}
+		if (ctx.thinkingLevel) env.PI_REASONING_LEVEL = ctx.thinkingLevel;
+	}
+	const baseContext: BashSpawnContext = { command, cwd, env };
+	return spawnHook ? spawnHook(baseContext) : baseContext;
+}
+
+export interface BashToolOptions {
+	/** Custom operations for command execution. Default: local shell */
+	operations?: BashOperations;
+	/** Command prefix prepended to every command (for example shell setup commands) */
+	commandPrefix?: string;
+	/** Optional explicit shell path from settings */
+	shellPath?: string;
+	/** Expose current Pi session metadata as PI_* environment variables. Default: true */
+	exposeSessionEnvironment?: boolean;
+	/** Hook to adjust command, cwd, or env before execution */
+	spawnHook?: BashSpawnHook;
+}
+
+export type BashRenderState = {
+	startedAt: number | undefined;
+	endedAt: number | undefined;
+	interval: NodeJS.Timeout | undefined;
+};
+
+export interface ShellToolConfig {
+	name: string;
+	label: string;
+	shellName: string;
+	prompt: string;
+	promptSnippet: string;
+	promptGuidelines?: readonly string[];
+	tempFilePrefix: string;
+}
+
+export function createShellToolDefinition(
+	cwd: string,
+	config: ShellToolConfig,
+	options?: BashToolOptions,
+): ToolDefinition<typeof bashSchema, BashToolDetails | undefined, BashRenderState> {
+	const ops = options?.operations ?? createLocalBashOperations({ shellPath: options?.shellPath });
+	const commandPrefix = options?.commandPrefix;
+	const exposeSessionEnvironment = options?.exposeSessionEnvironment ?? true;
+	const spawnHook = options?.spawnHook;
+	return {
+		name: config.name,
+		label: config.label,
+		description: `Execute a ${config.shellName} command in the current working directory. Returns stdout and stderr. Output is truncated to last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.`,
+		promptSnippet: config.promptSnippet,
+		promptGuidelines: exposeSessionEnvironment && config.promptGuidelines ? [...config.promptGuidelines] : undefined,
+		parameters: bashSchema,
+		constrainedSampling: { type: "json_schema", strict: "prefer" },
+		async execute(
+			_toolCallId,
+			{ command, timeout }: { command: string; timeout?: number },
+			signal?: AbortSignal,
+			onUpdate?,
+			ctx?: ExtensionContext,
+		) {
+			const resolvedCommand = commandPrefix ? `${commandPrefix}\n${command}` : command;
+			const spawnContext = resolveSpawnContext(
+				resolvedCommand,
+				ctx?.cwd || cwd,
+				spawnHook,
+				exposeSessionEnvironment,
+				ctx,
+			);
+			const output = new OutputAccumulator({ tempFilePrefix: config.tempFilePrefix });
+			let acceptingOutput = true;
+			let updateTimer: NodeJS.Timeout | undefined;
+			let updateDirty = false;
+			let lastUpdateAt = 0;
+
+			const emitOutputUpdate = () => {
+				if (!onUpdate || !updateDirty) return;
+				updateDirty = false;
+				lastUpdateAt = Date.now();
+				const snapshot = output.snapshot({ persistIfTruncated: true });
+				onUpdate({
+					content: [{ type: "text", text: snapshot.content || "" }],
+					details: {
+						truncation: snapshot.truncation.truncated ? snapshot.truncation : undefined,
+						fullOutputPath: snapshot.fullOutputPath,
+					},
+				});
+			};
+
+			const clearUpdateTimer = () => {
+				if (updateTimer) {
+					clearTimeout(updateTimer);
+					updateTimer = undefined;
+				}
+			};
+
+			const scheduleOutputUpdate = () => {
+				if (!onUpdate) return;
+				updateDirty = true;
+				const delay = BASH_UPDATE_THROTTLE_MS - (Date.now() - lastUpdateAt);
+				if (delay <= 0) {
+					clearUpdateTimer();
+					emitOutputUpdate();
+					return;
+				}
+				updateTimer ??= setTimeout(() => {
+					updateTimer = undefined;
+					emitOutputUpdate();
+				}, delay);
+			};
+
+			if (onUpdate) {
+				onUpdate({ content: [], details: undefined });
+			}
+
+			const handleData = (data: Buffer) => {
+				if (!acceptingOutput) return;
+				output.append(data);
+				scheduleOutputUpdate();
+			};
+
+			const finishOutput = async () => {
+				acceptingOutput = false;
+				output.finish();
+				clearUpdateTimer();
+				emitOutputUpdate();
+				const snapshot = output.snapshot({ persistIfTruncated: true });
+				await output.closeTempFile();
+				return snapshot;
+			};
+
+			const formatOutput = (snapshot: Awaited<ReturnType<typeof finishOutput>>, emptyText = "(no output)") => {
+				const truncation = snapshot.truncation;
+				let text = snapshot.content || emptyText;
+				let details: BashToolDetails | undefined;
+				if (truncation.truncated) {
+					details = { truncation, fullOutputPath: snapshot.fullOutputPath };
+					const startLine = truncation.totalLines - truncation.outputLines + 1;
+					const endLine = truncation.totalLines;
+					if (truncation.lastLinePartial) {
+						const lastLineSize = formatSize(output.getLastLineBytes());
+						text += `\n\n[Showing last ${formatSize(truncation.outputBytes)} of line ${endLine} (line is ${lastLineSize}). Full output: ${snapshot.fullOutputPath}]`;
+					} else if (truncation.truncatedBy === "lines") {
+						text += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines}. Full output: ${snapshot.fullOutputPath}]`;
+					} else {
+						text += `\n\n[Showing lines ${startLine}-${endLine} of ${truncation.totalLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Full output: ${snapshot.fullOutputPath}]`;
+					}
+				}
+				return { text, details };
+			};
+
+			const appendStatus = (text: string, status: string) => `${text ? `${text}\n\n` : ""}${status}`;
+
+			try {
+				let exitCode: number | null;
+				try {
+					const result = await ops.exec(spawnContext.command, spawnContext.cwd, {
+						onData: handleData,
+						signal,
+						timeout,
+						env: spawnContext.env,
+					});
+					exitCode = result.exitCode;
+				} catch (err) {
+					const snapshot = await finishOutput();
+					const { text } = formatOutput(snapshot, "");
+					if (err instanceof Error && err.message === "aborted") {
+						throw new Error(appendStatus(text, "Command aborted"));
+					}
+					if (err instanceof Error && err.message.startsWith("timeout:")) {
+						const timeoutSecs = err.message.split(":")[1];
+						throw new Error(appendStatus(text, `Command timed out after ${timeoutSecs} seconds`));
+					}
+					throw err;
+				}
+
+				const snapshot = await finishOutput();
+				const { text: outputText, details } = formatOutput(snapshot);
+				if (exitCode !== 0 && exitCode !== null) {
+					throw new Error(appendStatus(outputText, `Command exited with code ${exitCode}`));
+				}
+				return { content: [{ type: "text", text: outputText }], details };
+			} finally {
+				clearUpdateTimer();
+			}
+		},
+		...createShellRenderers(config.prompt),
+	};
+}
+
+const bashToolConfig: ShellToolConfig = {
+	name: "bash",
+	label: "bash",
+	shellName: "bash",
+	prompt: "$",
+	promptSnippet: bashToolSystemPromptContribution.snippet,
+	promptGuidelines: bashToolSystemPromptContribution.guidelines,
+	tempFilePrefix: "pi-bash",
+};
+
+export function createBashToolDefinition(
+	cwd: string,
+	options?: BashToolOptions,
+): ToolDefinition<typeof bashSchema, BashToolDetails | undefined, BashRenderState> {
+	return createShellToolDefinition(cwd, bashToolConfig, options);
+}
+
+export function createBashTool(cwd: string, options?: BashToolOptions): AgentTool<typeof bashSchema> {
+	const definition = createBashToolDefinition(cwd, options);
+	const tool = wrapToolDefinition(definition);
+	Object.assign(tool, {
+		promptSnippet: definition.promptSnippet,
+		promptGuidelines: definition.promptGuidelines,
+	});
+	return tool;
+}

packages/coding-agent/src/core/tools/edit-diff.ts

@@ -0,0 +1,556 @@
+/**
+ * Shared diff computation utilities for the edit and similar tools.
+ */
+
+import * as Diff from "diff";
+import { constants } from "fs";
+import { access, readFile } from "fs/promises";
+import { splitBom } from "../../utils/text.ts";
+import { resolveToCwd } from "./path-utils.ts";
+
+export function detectLineEnding(content: string): "\r\n" | "\n" {
+	const crlfIdx = content.indexOf("\r\n");
+	const lfIdx = content.indexOf("\n");
+	if (lfIdx === -1) return "\n";
+	if (crlfIdx === -1) return "\n";
+	return crlfIdx < lfIdx ? "\r\n" : "\n";
+}
+
+export function normalizeToLF(text: string): string {
+	return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+export function restoreLineEndings(text: string, ending: "\r\n" | "\n"): string {
+	return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+}
+
+/**
+ * Normalize text for fuzzy matching. Applies progressive transformations:
+ * - Strip trailing whitespace from each line
+ * - Normalize smart quotes to ASCII equivalents
+ * - Normalize Unicode dashes/hyphens to ASCII hyphen
+ * - Normalize special Unicode spaces to regular space
+ */
+export function normalizeForFuzzyMatch(text: string): string {
+	return (
+		text
+			.normalize("NFKC")
+			// Strip trailing whitespace per line
+			.split("\n")
+			.map((line) => line.trimEnd())
+			.join("\n")
+			// Smart single quotes → '
+			.replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+			// Smart double quotes → "
+			.replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+			// Various dashes/hyphens → -
+			// U+2010 hyphen, U+2011 non-breaking hyphen, U+2012 figure dash,
+			// U+2013 en-dash, U+2014 em-dash, U+2015 horizontal bar, U+2212 minus
+			.replace(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g, "-")
+			// Special spaces → regular space
+			// U+00A0 NBSP, U+2002-U+200A various spaces, U+202F narrow NBSP,
+			// U+205F medium math space, U+3000 ideographic space
+			.replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " ")
+	);
+}
+
+function splitLinesWithEndings(content: string): string[] {
+	return content.match(/[^\n]*\n|[^\n]+/g) ?? [];
+}
+
+interface LineSpan {
+	start: number;
+	end: number;
+}
+
+interface MatchedEdit {
+	editIndex: number;
+	matchIndex: number;
+	matchLength: number;
+	newText: string;
+}
+
+type TextReplacement = Pick<MatchedEdit, "matchIndex" | "matchLength" | "newText">;
+
+function getLineSpans(content: string): LineSpan[] {
+	let offset = 0;
+	return splitLinesWithEndings(content).map((line) => {
+		const span = { start: offset, end: offset + line.length };
+		offset = span.end;
+		return span;
+	});
+}
+
+function getReplacementLineRange(lines: LineSpan[], replacement: TextReplacement) {
+	const replacementStart = replacement.matchIndex;
+	const replacementEnd = replacement.matchIndex + replacement.matchLength;
+
+	let startLine = -1;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (replacementStart >= line.start && replacementStart < line.end) {
+			startLine = i;
+			break;
+		}
+	}
+	if (startLine === -1) {
+		throw new Error("Replacement range is outside the base content.");
+	}
+
+	let endLine = startLine;
+	while (endLine < lines.length && lines[endLine].end < replacementEnd) {
+		endLine++;
+	}
+	if (endLine >= lines.length) {
+		throw new Error("Replacement range is outside the base content.");
+	}
+
+	return { startLine, endLine: endLine + 1 };
+}
+
+function applyReplacements(content: string, replacements: TextReplacement[], offset = 0): string {
+	let result = content;
+	for (let i = replacements.length - 1; i >= 0; i--) {
+		const replacement = replacements[i];
+		const matchIndex = replacement.matchIndex - offset;
+		result =
+			result.substring(0, matchIndex) + replacement.newText + result.substring(matchIndex + replacement.matchLength);
+	}
+	return result;
+}
+
+/**
+ * Apply replacements matched against `baseContent` to `originalContent` while
+ * preserving unchanged line blocks from the original.
+ *
+ * This is useful when `baseContent` is a normalized view of the original. Each
+ * replacement is widened to the lines it actually touches, those touched lines
+ * are rewritten from the normalized base, and all other lines are copied back
+ * from `originalContent`. The actual replacement ranges drive preservation so
+ * duplicate normalized lines cannot be aligned to the wrong occurrence.
+ */
+export function applyReplacementsPreservingUnchangedLines(
+	originalContent: string,
+	baseContent: string,
+	replacements: TextReplacement[],
+): string {
+	const originalLines = splitLinesWithEndings(originalContent);
+	const baseLines = getLineSpans(baseContent);
+	if (originalLines.length !== baseLines.length) {
+		throw new Error("Cannot preserve unchanged lines because the base content has a different line count.");
+	}
+
+	const groups: Array<{ startLine: number; endLine: number; replacements: TextReplacement[] }> = [];
+	const sortedReplacements = [...replacements].sort((a, b) => a.matchIndex - b.matchIndex);
+	for (const replacement of sortedReplacements) {
+		const range = getReplacementLineRange(baseLines, replacement);
+		const current = groups[groups.length - 1];
+		if (current && range.startLine < current.endLine) {
+			current.endLine = Math.max(current.endLine, range.endLine);
+			current.replacements.push(replacement);
+			continue;
+		}
+		groups.push({ ...range, replacements: [replacement] });
+	}
+
+	let originalLineIndex = 0;
+	let result = "";
+	for (const group of groups) {
+		result += originalLines.slice(originalLineIndex, group.startLine).join("");
+
+		const groupStartOffset = baseLines[group.startLine].start;
+		const groupEndOffset = baseLines[group.endLine - 1].end;
+		result += applyReplacements(
+			baseContent.slice(groupStartOffset, groupEndOffset),
+			group.replacements,
+			groupStartOffset,
+		);
+		originalLineIndex = group.endLine;
+	}
+	result += originalLines.slice(originalLineIndex).join("");
+
+	return result;
+}
+
+export interface FuzzyMatchResult {
+	/** Whether a match was found */
+	found: boolean;
+	/** The index where the match starts (in the content that should be used for replacement) */
+	index: number;
+	/** Length of the matched text */
+	matchLength: number;
+	/** Whether fuzzy matching was used (false = exact match) */
+	usedFuzzyMatch: boolean;
+	/**
+	 * The content to use for replacement operations.
+	 * When exact match: original content. When fuzzy match: normalized content.
+	 */
+	contentForReplacement: string;
+}
+
+export interface Edit {
+	oldText: string;
+	newText: string;
+}
+
+export interface AppliedEditsResult {
+	baseContent: string;
+	newContent: string;
+}
+
+/**
+ * Find oldText in content, trying exact match first, then fuzzy match.
+ * When fuzzy matching is used, the returned contentForReplacement is the
+ * fuzzy-normalized version of the content (trailing whitespace stripped,
+ * Unicode quotes/dashes normalized to ASCII).
+ */
+export function fuzzyFindText(content: string, oldText: string): FuzzyMatchResult {
+	// Try exact match first
+	const exactIndex = content.indexOf(oldText);
+	if (exactIndex !== -1) {
+		return {
+			found: true,
+			index: exactIndex,
+			matchLength: oldText.length,
+			usedFuzzyMatch: false,
+			contentForReplacement: content,
+		};
+	}
+
+	// Try fuzzy match - work entirely in normalized space
+	const fuzzyContent = normalizeForFuzzyMatch(content);
+	const fuzzyOldText = normalizeForFuzzyMatch(oldText);
+	const fuzzyIndex = fuzzyContent.indexOf(fuzzyOldText);
+
+	if (fuzzyIndex === -1) {
+		return {
+			found: false,
+			index: -1,
+			matchLength: 0,
+			usedFuzzyMatch: false,
+			contentForReplacement: content,
+		};
+	}
+
+	// When fuzzy matching, return offsets in normalized space. Callers can use
+	// the normalized content to compute replacements, then decide how much of
+	// that normalized output should be written back.
+	return {
+		found: true,
+		index: fuzzyIndex,
+		matchLength: fuzzyOldText.length,
+		usedFuzzyMatch: true,
+		contentForReplacement: fuzzyContent,
+	};
+}
+
+function countOccurrences(content: string, oldText: string): number {
+	const fuzzyContent = normalizeForFuzzyMatch(content);
+	const fuzzyOldText = normalizeForFuzzyMatch(oldText);
+	return fuzzyContent.split(fuzzyOldText).length - 1;
+}
+
+function getNotFoundError(path: string, editIndex: number, totalEdits: number): Error {
+	if (totalEdits === 1) {
+		return new Error(
+			`Could not find the exact text in ${path}. The old text must match exactly including all whitespace and newlines.`,
+		);
+	}
+	return new Error(
+		`Could not find edits[${editIndex}] in ${path}. The oldText must match exactly including all whitespace and newlines.`,
+	);
+}
+
+function getDuplicateError(path: string, editIndex: number, totalEdits: number, occurrences: number): Error {
+	if (totalEdits === 1) {
+		return new Error(
+			`Found ${occurrences} occurrences of the text in ${path}. The text must be unique. Please provide more context to make it unique.`,
+		);
+	}
+	return new Error(
+		`Found ${occurrences} occurrences of edits[${editIndex}] in ${path}. Each oldText must be unique. Please provide more context to make it unique.`,
+	);
+}
+
+function getEmptyOldTextError(path: string, editIndex: number, totalEdits: number): Error {
+	if (totalEdits === 1) {
+		return new Error(`oldText must not be empty in ${path}.`);
+	}
+	return new Error(`edits[${editIndex}].oldText must not be empty in ${path}.`);
+}
+
+function getNoChangeError(path: string, totalEdits: number): Error {
+	if (totalEdits === 1) {
+		return new Error(
+			`No changes made to ${path}. The replacement produced identical content. This might indicate an issue with special characters or the text not existing as expected.`,
+		);
+	}
+	return new Error(`No changes made to ${path}. The replacements produced identical content.`);
+}
+
+/**
+ * Apply one or more exact-text replacements to LF-normalized content.
+ *
+ * All edits are matched against the same original content. Replacements are
+ * then applied in reverse order so offsets remain stable. If any edit needs
+ * fuzzy matching, the operation runs in fuzzy-normalized content space and then
+ * overlays those line-level changes onto the original content so unchanged line
+ * blocks keep their original bytes.
+ */
+export function applyEditsToNormalizedContent(
+	normalizedContent: string,
+	edits: Edit[],
+	path: string,
+): AppliedEditsResult {
+	const normalizedEdits = edits.map((edit) => ({
+		oldText: normalizeToLF(edit.oldText),
+		newText: normalizeToLF(edit.newText),
+	}));
+
+	for (let i = 0; i < normalizedEdits.length; i++) {
+		if (normalizedEdits[i].oldText.length === 0) {
+			throw getEmptyOldTextError(path, i, normalizedEdits.length);
+		}
+	}
+
+	const initialMatches = normalizedEdits.map((edit) => fuzzyFindText(normalizedContent, edit.oldText));
+	const usedFuzzyMatch = initialMatches.some((match) => match.usedFuzzyMatch);
+	const replacementBaseContent = usedFuzzyMatch ? normalizeForFuzzyMatch(normalizedContent) : normalizedContent;
+
+	const matchedEdits: MatchedEdit[] = [];
+	for (let i = 0; i < normalizedEdits.length; i++) {
+		const edit = normalizedEdits[i];
+		const matchResult = fuzzyFindText(replacementBaseContent, edit.oldText);
+		if (!matchResult.found) {
+			throw getNotFoundError(path, i, normalizedEdits.length);
+		}
+
+		const occurrences = countOccurrences(replacementBaseContent, edit.oldText);
+		if (occurrences > 1) {
+			throw getDuplicateError(path, i, normalizedEdits.length, occurrences);
+		}
+
+		matchedEdits.push({
+			editIndex: i,
+			matchIndex: matchResult.index,
+			matchLength: matchResult.matchLength,
+			newText: edit.newText,
+		});
+	}
+
+	matchedEdits.sort((a, b) => a.matchIndex - b.matchIndex);
+	for (let i = 1; i < matchedEdits.length; i++) {
+		const previous = matchedEdits[i - 1];
+		const current = matchedEdits[i];
+		if (previous.matchIndex + previous.matchLength > current.matchIndex) {
+			throw new Error(
+				`edits[${previous.editIndex}] and edits[${current.editIndex}] overlap in ${path}. Merge them into one edit or target disjoint regions.`,
+			);
+		}
+	}
+
+	const baseContent = normalizedContent;
+	const newContent = usedFuzzyMatch
+		? applyReplacementsPreservingUnchangedLines(normalizedContent, replacementBaseContent, matchedEdits)
+		: applyReplacements(replacementBaseContent, matchedEdits);
+
+	if (baseContent === newContent) {
+		throw getNoChangeError(path, normalizedEdits.length);
+	}
+
+	return { baseContent, newContent };
+}
+
+/** Generate a standard unified patch. */
+export function generateUnifiedPatch(path: string, oldContent: string, newContent: string, contextLines = 4): string {
+	return Diff.createTwoFilesPatch(path, path, oldContent, newContent, undefined, undefined, {
+		context: contextLines,
+		headerOptions: Diff.FILE_HEADERS_ONLY,
+	});
+}
+
+/**
+ * Generate a display-oriented diff string with line numbers and context.
+ * Returns both the diff string and the first changed line number (in the new file).
+ */
+export function generateDiffString(
+	oldContent: string,
+	newContent: string,
+	contextLines = 4,
+): { diff: string; firstChangedLine: number | undefined } {
+	const parts = Diff.diffLines(oldContent, newContent);
+	const output: string[] = [];
+
+	const oldLines = oldContent.split("\n");
+	const newLines = newContent.split("\n");
+	const maxLineNum = Math.max(oldLines.length, newLines.length);
+	const lineNumWidth = String(maxLineNum).length;
+
+	let oldLineNum = 1;
+	let newLineNum = 1;
+	let lastWasChange = false;
+	let firstChangedLine: number | undefined;
+
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		const raw = part.value.split("\n");
+		if (raw[raw.length - 1] === "") {
+			raw.pop();
+		}
+
+		if (part.added || part.removed) {
+			// Capture the first changed line (in the new file)
+			if (firstChangedLine === undefined) {
+				firstChangedLine = newLineNum;
+			}
+
+			// Show the change
+			for (const line of raw) {
+				if (part.added) {
+					const lineNum = String(newLineNum).padStart(lineNumWidth, " ");
+					output.push(`+${lineNum} ${line}`);
+					newLineNum++;
+				} else {
+					// removed
+					const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+					output.push(`-${lineNum} ${line}`);
+					oldLineNum++;
+				}
+			}
+			lastWasChange = true;
+		} else {
+			// Context lines - only show a few before/after changes
+			const nextPartIsChange = i < parts.length - 1 && (parts[i + 1].added || parts[i + 1].removed);
+			const hasLeadingChange = lastWasChange;
+			const hasTrailingChange = nextPartIsChange;
+
+			if (hasLeadingChange && hasTrailingChange) {
+				if (raw.length <= contextLines * 2) {
+					for (const line of raw) {
+						const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+						output.push(` ${lineNum} ${line}`);
+						oldLineNum++;
+						newLineNum++;
+					}
+				} else {
+					const leadingLines = raw.slice(0, contextLines);
+					const trailingLines = raw.slice(raw.length - contextLines);
+					const skippedLines = raw.length - leadingLines.length - trailingLines.length;
+
+					for (const line of leadingLines) {
+						const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+						output.push(` ${lineNum} ${line}`);
+						oldLineNum++;
+						newLineNum++;
+					}
+
+					output.push(` ${"".padStart(lineNumWidth, " ")} ...`);
+					oldLineNum += skippedLines;
+					newLineNum += skippedLines;
+
+					for (const line of trailingLines) {
+						const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+						output.push(` ${lineNum} ${line}`);
+						oldLineNum++;
+						newLineNum++;
+					}
+				}
+			} else if (hasLeadingChange) {
+				const shownLines = raw.slice(0, contextLines);
+				const skippedLines = raw.length - shownLines.length;
+
+				for (const line of shownLines) {
+					const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+					output.push(` ${lineNum} ${line}`);
+					oldLineNum++;
+					newLineNum++;
+				}
+
+				if (skippedLines > 0) {
+					output.push(` ${"".padStart(lineNumWidth, " ")} ...`);
+					oldLineNum += skippedLines;
+					newLineNum += skippedLines;
+				}
+			} else if (hasTrailingChange) {
+				const skippedLines = Math.max(0, raw.length - contextLines);
+				if (skippedLines > 0) {
+					output.push(` ${"".padStart(lineNumWidth, " ")} ...`);
+					oldLineNum += skippedLines;
+					newLineNum += skippedLines;
+				}
+
+				for (const line of raw.slice(skippedLines)) {
+					const lineNum = String(oldLineNum).padStart(lineNumWidth, " ");
+					output.push(` ${lineNum} ${line}`);
+					oldLineNum++;
+					newLineNum++;
+				}
+			} else {
+				// Skip these context lines entirely
+				oldLineNum += raw.length;
+				newLineNum += raw.length;
+			}
+
+			lastWasChange = false;
+		}
+	}
+
+	return { diff: output.join("\n"), firstChangedLine };
+}
+
+export interface EditDiffResult {
+	diff: string;
+	firstChangedLine: number | undefined;
+}
+
+export interface EditDiffError {
+	error: string;
+}
+
+/**
+ * Compute the diff for one or more edit operations without applying them.
+ * Used for preview rendering in the TUI before the tool executes.
+ */
+export async function computeEditsDiff(
+	path: string,
+	edits: Edit[],
+	cwd: string,
+): Promise<EditDiffResult | EditDiffError> {
+	const absolutePath = resolveToCwd(path, cwd);
+
+	try {
+		// Check if file exists and is readable
+		try {
+			await access(absolutePath, constants.R_OK);
+		} catch (error: unknown) {
+			const errorMessage = error instanceof Error && "code" in error ? `Error code: ${error.code}` : String(error);
+			return { error: `Could not edit file: ${path}. ${errorMessage}.` };
+		}
+
+		// Read the file
+		const rawContent = await readFile(absolutePath, "utf-8");
+
+		// Strip BOM before matching (LLM won't include invisible BOM in oldText)
+		const { text: content } = splitBom(rawContent);
+		const normalizedContent = normalizeToLF(content);
+		const { baseContent, newContent } = applyEditsToNormalizedContent(normalizedContent, edits, path);
+
+		// Generate the diff
+		return generateDiffString(baseContent, newContent);
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+/**
+ * Compute the diff for a single edit operation without applying it.
+ * Kept as a convenience wrapper for single-edit callers.
+ */
+export async function computeEditDiff(
+	path: string,
+	oldText: string,
+	newText: string,
+	cwd: string,
+): Promise<EditDiffResult | EditDiffError> {
+	return computeEditsDiff(path, [{ oldText, newText }], cwd);
+}

packages/coding-agent/src/core/tools/edit.ts

@@ -0,0 +1,220 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { constants } from "fs";
+import { access as fsAccess, readFile as fsReadFile, writeFile as fsWriteFile } from "fs/promises";
+import { type Static, Type } from "typebox";
+import { splitBom } from "../../utils/text.ts";
+import type { ExtensionContext, ToolDefinition } from "../extensions/types.ts";
+import {
+	applyEditsToNormalizedContent,
+	detectLineEnding,
+	type Edit,
+	generateDiffString,
+	generateUnifiedPatch,
+	normalizeToLF,
+	restoreLineEndings,
+} from "./edit-diff.ts";
+import { withFileMutationQueue } from "./file-mutation-queue.ts";
+import { resolveToCwd } from "./path-utils.ts";
+import { type EditRenderState, editRenderers } from "./renderers/edit.ts";
+import { wrapToolDefinition } from "./tool-definition-wrapper.ts";
+
+const replaceEditSchema = Type.Object(
+	{
+		oldText: Type.String({
+			description:
+				"Exact text for one targeted replacement. It must be unique in the original file and must not overlap with any other edits[].oldText in the same call.",
+		}),
+		newText: Type.String({ description: "Replacement text for this targeted edit." }),
+	},
+	{},
+);
+
+const editSchema = Type.Object(
+	{
+		path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
+		edits: Type.Array(replaceEditSchema, {
+			description:
+				"One or more targeted replacements. Each edit is matched against the original file, not incrementally. Do not include overlapping or nested edits. If two changes touch the same block or nearby lines, merge them into one edit instead.",
+		}),
+	},
+	{},
+);
+
+export const editToolSystemPromptContribution = {
+	snippet: "Make precise file edits with exact text replacement, including multiple disjoint edits in one call",
+	guidelines: [
+		"Use edit for precise changes (edits[].oldText must match exactly)",
+		"When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls",
+		"Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits. Merge nearby changes into one edit.",
+		"Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions.",
+	],
+} as const;
+
+export type EditToolInput = Static<typeof editSchema>;
+type LegacyEditToolInput = EditToolInput & {
+	oldText?: unknown;
+	newText?: unknown;
+};
+
+type SingleEditInput = { oldText: string; newText: string };
+
+function isSingleEditInput(value: unknown): value is SingleEditInput {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return false;
+	}
+
+	const edit = value as Record<string, unknown>;
+	return typeof edit.oldText === "string" && typeof edit.newText === "string";
+}
+
+export interface EditToolDetails {
+	/** Display-oriented diff of the changes made */
+	diff: string;
+	/** Standard unified patch of the changes made */
+	patch: string;
+	/** Line number of the first change in the new file (for editor navigation) */
+	firstChangedLine?: number;
+}
+
+/**
+ * Pluggable operations for the edit tool.
+ * Override these to delegate file editing to remote systems (for example SSH).
+ */
+export interface EditOperations {
+	/** Read file contents as a Buffer */
+	readFile: (absolutePath: string) => Promise<Buffer>;
+	/** Write content to a file */
+	writeFile: (absolutePath: string, content: string) => Promise<void>;
+	/** Check if file is readable and writable (throw if not) */
+	access: (absolutePath: string) => Promise<void>;
+}
+
+const defaultEditOperations: EditOperations = {
+	readFile: (path) => fsReadFile(path),
+	writeFile: (path, content) => fsWriteFile(path, content, "utf-8"),
+	access: (path) => fsAccess(path, constants.R_OK | constants.W_OK),
+};
+
+export interface EditToolOptions {
+	/** Custom operations for file editing. Default: local filesystem */
+	operations?: EditOperations;
+}
+
+function prepareEditArguments(input: unknown): EditToolInput {
+	if (!input || typeof input !== "object") {
+		return input as EditToolInput;
+	}
+
+	const args = input as Record<string, unknown>;
+
+	// Some models (Opus 4.6, GLM-5.1) send edits as a JSON string instead of an array.
+	// Others send a single edit object instead of a one-element edits array.
+	if (typeof args.edits === "string") {
+		try {
+			const parsed = JSON.parse(args.edits);
+			if (Array.isArray(parsed)) {
+				args.edits = parsed;
+			} else if (isSingleEditInput(parsed)) {
+				args.edits = [parsed];
+			}
+		} catch {}
+	} else if (isSingleEditInput(args.edits)) {
+		args.edits = [args.edits];
+	}
+
+	const legacy = args as LegacyEditToolInput;
+	if (typeof legacy.oldText !== "string" || typeof legacy.newText !== "string") {
+		return args as EditToolInput;
+	}
+
+	const edits = Array.isArray(legacy.edits) ? [...legacy.edits] : [];
+	edits.push({ oldText: legacy.oldText, newText: legacy.newText });
+	const { oldText: _oldText, newText: _newText, ...rest } = legacy;
+	return { ...rest, edits } as EditToolInput;
+}
+
+function validateEditInput(input: EditToolInput): { path: string; edits: Edit[] } {
+	if (!Array.isArray(input.edits) || input.edits.length === 0) {
+		throw new Error("Edit tool input is invalid. edits must contain at least one replacement.");
+	}
+	return { path: input.path, edits: input.edits };
+}
+
+export function createEditToolDefinition(
+	cwd: string,
+	options?: EditToolOptions,
+): ToolDefinition<typeof editSchema, EditToolDetails | undefined, EditRenderState> {
+	const ops = options?.operations ?? defaultEditOperations;
+	return {
+		name: "edit",
+		label: "edit",
+		description:
+			"Edit a single file using exact text replacement. Every edits[].oldText must match a unique, non-overlapping region of the original file. If two changes affect the same block or nearby lines, merge them into one edit instead of emitting overlapping edits. Do not include large unchanged regions just to connect distant changes.",
+		promptSnippet: editToolSystemPromptContribution.snippet,
+		promptGuidelines: [...editToolSystemPromptContribution.guidelines],
+		parameters: editSchema,
+		constrainedSampling: { type: "json_schema", strict: "prefer" },
+		renderShell: "self",
+		prepareArguments: prepareEditArguments,
+		async execute(_toolCallId, input: EditToolInput, signal?: AbortSignal, _onUpdate?, ctx?: ExtensionContext) {
+			const { path, edits } = validateEditInput(input);
+			const absolutePath = resolveToCwd(path, ctx?.cwd || cwd);
+
+			return withFileMutationQueue(absolutePath, async () => {
+				// Do not reject from an abort event listener here: that would release the
+				// mutation queue while an in-flight filesystem operation may still finish.
+				// Checking signal.aborted after each await observes the same aborts while
+				// keeping the queue locked until the current operation has settled.
+				const throwIfAborted = (): void => {
+					if (signal?.aborted) throw new Error("Operation aborted");
+				};
+
+				throwIfAborted();
+
+				// Check if file exists.
+				try {
+					await ops.access(absolutePath);
+				} catch (error: unknown) {
+					throwIfAborted();
+					const errorMessage =
+						error instanceof Error && "code" in error ? `Error code: ${error.code}` : String(error);
+					throw new Error(`Could not edit file: ${path}. ${errorMessage}.`);
+				}
+				throwIfAborted();
+
+				// Read the file.
+				const buffer = await ops.readFile(absolutePath);
+				const rawContent = buffer.toString("utf-8");
+				throwIfAborted();
+
+				// Strip BOM before matching. The model will not include an invisible BOM in oldText.
+				const { bom, text: content } = splitBom(rawContent);
+				const originalEnding = detectLineEnding(content);
+				const normalizedContent = normalizeToLF(content);
+				const { baseContent, newContent } = applyEditsToNormalizedContent(normalizedContent, edits, path);
+				throwIfAborted();
+
+				const finalContent = bom + restoreLineEndings(newContent, originalEnding);
+				await ops.writeFile(absolutePath, finalContent);
+				throwIfAborted();
+
+				const diffResult = generateDiffString(baseContent, newContent);
+				const patch = generateUnifiedPatch(path, baseContent, newContent);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Successfully replaced ${edits.length} block(s) in ${path}.`,
+						},
+					],
+					details: { diff: diffResult.diff, patch, firstChangedLine: diffResult.firstChangedLine },
+				};
+			});
+		},
+		...editRenderers,
+	};
+}
+
+export function createEditTool(cwd: string, options?: EditToolOptions): AgentTool<typeof editSchema> {
+	return wrapToolDefinition(createEditToolDefinition(cwd, options));
+}

packages/coding-agent/src/core/tools/file-mutation-queue.ts

@@ -0,0 +1,61 @@
+import { realpath } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const fileMutationQueues = new Map<string, Promise<void>>();
+let registrationQueue = Promise.resolve();
+
+function isMissingPathError(error: unknown): boolean {
+	return (
+		typeof error === "object" &&
+		error !== null &&
+		"code" in error &&
+		(error.code === "ENOENT" || error.code === "ENOTDIR")
+	);
+}
+
+async function getMutationQueueKey(filePath: string): Promise<string> {
+	const resolvedPath = resolve(filePath);
+	try {
+		return await realpath(resolvedPath);
+	} catch (error) {
+		if (isMissingPathError(error)) {
+			return resolvedPath;
+		}
+		throw error;
+	}
+}
+
+/**
+ * Serialize file mutation operations targeting the same file.
+ * Operations for different files still run in parallel.
+ */
+export async function withFileMutationQueue<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
+	const registration = registrationQueue.then(async () => {
+		const key = await getMutationQueueKey(filePath);
+		const currentQueue = fileMutationQueues.get(key) ?? Promise.resolve();
+
+		let releaseNext!: () => void;
+		const nextQueue = new Promise<void>((resolveQueue) => {
+			releaseNext = resolveQueue;
+		});
+		const chainedQueue = currentQueue.then(() => nextQueue);
+		fileMutationQueues.set(key, chainedQueue);
+
+		return { key, currentQueue, chainedQueue, releaseNext };
+	});
+	registrationQueue = registration.then(
+		() => undefined,
+		() => undefined,
+	);
+
+	const { key, currentQueue, chainedQueue, releaseNext } = await registration;
+	await currentQueue;
+	try {
+		return await fn();
+	} finally {
+		releaseNext();
+		if (fileMutationQueues.get(key) === chainedQueue) {
+			fileMutationQueues.delete(key);
+		}
+	}
+}

packages/coding-agent/src/core/tools/find.ts

@@ -0,0 +1,318 @@
+import { createInterface } from "node:readline";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { spawn } from "child_process";
+import path from "path";
+import { type Static, Type } from "typebox";
+import { ensureTool } from "../../utils/tools-manager.ts";
+import type { ExtensionContext, ToolDefinition } from "../extensions/types.ts";
+import { pathExists, resolveToCwd } from "./path-utils.ts";
+import { findRenderers } from "./renderers/find.ts";
+import { wrapToolDefinition } from "./tool-definition-wrapper.ts";
+import { DEFAULT_MAX_BYTES, formatSize, type TruncationResult, truncateHead } from "./truncate.ts";
+
+/** Relativize a find result against the search root and normalize it to posix separators. */
+export function relativizeFindResultPath(
+	resultPath: string,
+	searchPath: string,
+	pathModule: path.PlatformPath = path,
+): string {
+	const hadTrailingSeparator =
+		resultPath.endsWith(pathModule.sep) || (pathModule.sep === "\\" && resultPath.endsWith("/"));
+	const relativePath = pathModule.isAbsolute(resultPath) ? pathModule.relative(searchPath, resultPath) : resultPath;
+	const posixPath = relativePath.split(pathModule.sep).join("/");
+	return hadTrailingSeparator && !posixPath.endsWith("/") ? `${posixPath}/` : posixPath;
+}
+
+const findSchema = Type.Object({
+	pattern: Type.String({
+		description: "Glob pattern to match files, e.g. '*.ts', '**/*.json', or 'src/**/*.spec.ts'",
+	}),
+	path: Type.Optional(Type.String({ description: "Directory to search in (default: current directory)" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum number of results (default: 1000)" })),
+});
+
+export const findToolSystemPromptContribution = {
+	snippet: "Find files by glob pattern (respects .gitignore)",
+	guidelines: [],
+} as const;
+
+export type FindToolInput = Static<typeof findSchema>;
+
+const DEFAULT_LIMIT = 1000;
+
+export interface FindToolDetails {
+	truncation?: TruncationResult;
+	resultLimitReached?: number;
+}
+
+/**
+ * Pluggable operations for the find tool.
+ * Override these to delegate file search to remote systems (for example SSH).
+ */
+export interface FindOperations {
+	/** Check if path exists */
+	exists: (absolutePath: string) => Promise<boolean> | boolean;
+	/** Find files matching glob pattern. Returns relative or absolute paths. */
+	glob: (pattern: string, cwd: string, options: { ignore: string[]; limit: number }) => Promise<string[]> | string[];
+}
+
+const defaultFindOperations: FindOperations = {
+	exists: pathExists,
+	// This is a placeholder. Actual fd execution happens in execute() when no custom glob is provided.
+	glob: () => [],
+};
+
+export interface FindToolOptions {
+	/** Custom operations for find. Default: local filesystem plus fd */
+	operations?: FindOperations;
+}
+
+export function createFindToolDefinition(
+	cwd: string,
+	options?: FindToolOptions,
+): ToolDefinition<typeof findSchema, FindToolDetails | undefined> {
+	const customOps = options?.operations;
+	return {
+		name: "find",
+		label: "find",
+		description: `Search for files by glob pattern. Returns matching file paths relative to the search directory. Respects .gitignore. Output is truncated to ${DEFAULT_LIMIT} results or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first).`,
+		promptSnippet: findToolSystemPromptContribution.snippet,
+		parameters: findSchema,
+		async execute(
+			_toolCallId,
+			{ pattern, path: searchDir, limit }: { pattern: string; path?: string; limit?: number },
+			signal?: AbortSignal,
+			_onUpdate?,
+			ctx?: ExtensionContext,
+		) {
+			return new Promise((resolve, reject) => {
+				if (signal?.aborted) {
+					reject(new Error("Operation aborted"));
+					return;
+				}
+
+				let settled = false;
+				let stopChild: (() => void) | undefined;
+				const settle = (fn: () => void) => {
+					if (settled) return;
+					settled = true;
+					signal?.removeEventListener("abort", onAbort);
+					stopChild = undefined;
+					fn();
+				};
+				const onAbort = () => {
+					stopChild?.();
+					settle(() => reject(new Error("Operation aborted")));
+				};
+				signal?.addEventListener("abort", onAbort, { once: true });
+
+				(async () => {
+					try {
+						const searchPath = resolveToCwd(searchDir || ".", ctx?.cwd || cwd);
+						const effectiveLimit = limit ?? DEFAULT_LIMIT;
+						const ops = customOps ?? defaultFindOperations;
+
+						// If custom operations provide glob(), use that instead of fd.
+						if (customOps?.glob) {
+							if (!(await ops.exists(searchPath))) {
+								settle(() => reject(new Error(`Path not found: ${searchPath}`)));
+								return;
+							}
+							if (signal?.aborted) {
+								settle(() => reject(new Error("Operation aborted")));
+								return;
+							}
+							const results = await ops.glob(pattern, searchPath, {
+								ignore: ["**/node_modules/**", "**/.git/**"],
+								limit: effectiveLimit,
+							});
+							if (signal?.aborted) {
+								settle(() => reject(new Error("Operation aborted")));
+								return;
+							}
+							if (results.length === 0) {
+								settle(() =>
+									resolve({
+										content: [{ type: "text", text: "No files found matching pattern" }],
+										details: undefined,
+									}),
+								);
+								return;
+							}
+
+							// Relativize paths against the search root for stable output.
+							const relativized = results.map((p) => relativizeFindResultPath(p, searchPath));
+							const resultLimitReached = relativized.length >= effectiveLimit;
+							const rawOutput = relativized.join("\n");
+							const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
+							let resultOutput = truncation.content;
+							const details: FindToolDetails = {};
+							const notices: string[] = [];
+							if (resultLimitReached) {
+								notices.push(`${effectiveLimit} results limit reached`);
+								details.resultLimitReached = effectiveLimit;
+							}
+							if (truncation.truncated) {
+								notices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);
+								details.truncation = truncation;
+							}
+							if (notices.length > 0) {
+								resultOutput += `\n\n[${notices.join(". ")}]`;
+							}
+							settle(() =>
+								resolve({
+									content: [{ type: "text", text: resultOutput }],
+									details: Object.keys(details).length > 0 ? details : undefined,
+								}),
+							);
+							return;
+						}
+
+						// Default implementation uses fd.
+						const fdPath = await ensureTool("fd");
+						if (signal?.aborted) {
+							settle(() => reject(new Error("Operation aborted")));
+							return;
+						}
+						if (!fdPath) {
+							settle(() => reject(new Error("fd is not available and could not be downloaded")));
+							return;
+						}
+
+						const args: string[] = ["--glob", "--color=never", "--hidden"];
+
+						// fd normally ignores .gitignore outside git repos, so keep --no-require-git
+						// there. Inside repos, use fd's default git-aware behavior so parent
+						// .gitignore rules stop at nested repo boundaries:
+						// https://github.com/earendil-works/pi/issues/5960
+						let insideGitRepo = false;
+						for (let current = searchPath; ; ) {
+							if (await pathExists(path.join(current, ".git"))) {
+								insideGitRepo = true;
+								break;
+							}
+							const parent = path.dirname(current);
+							if (parent === current) break;
+							current = parent;
+						}
+						if (!insideGitRepo) args.push("--no-require-git");
+						args.push("--max-results", String(effectiveLimit));
+
+						// fd --glob matches against the basename unless --full-path is set; in --full-path
+						// mode it matches against the absolute candidate path, so a path-containing
+						// pattern like 'src/**/*.spec.ts' needs a leading '**/' to match anything.
+						let effectivePattern = pattern;
+						if (pattern.includes("/")) {
+							args.push("--full-path");
+							if (!pattern.startsWith("/") && !pattern.startsWith("**/") && pattern !== "**") {
+								effectivePattern = `**/${pattern}`;
+							}
+							// fd matches full paths using native separators on Windows.
+							if (process.platform === "win32")
+								effectivePattern = effectivePattern.replaceAll("/", String.raw`[/\\]`);
+						}
+						args.push("--", effectivePattern, searchPath);
+
+						const child = spawn(fdPath, args, { stdio: ["ignore", "pipe", "pipe"] });
+						const rl = createInterface({ input: child.stdout });
+						let stderr = "";
+						const lines: string[] = [];
+
+						stopChild = () => {
+							if (!child.killed) {
+								child.kill();
+							}
+						};
+
+						const cleanup = () => {
+							rl.close();
+						};
+
+						child.stderr?.on("data", (chunk) => {
+							stderr += chunk.toString();
+						});
+
+						rl.on("line", (line) => {
+							lines.push(line);
+						});
+
+						child.on("error", (error) => {
+							cleanup();
+							settle(() => reject(new Error(`Failed to run fd: ${error.message}`)));
+						});
+
+						child.on("close", (code) => {
+							cleanup();
+							if (signal?.aborted) {
+								settle(() => reject(new Error("Operation aborted")));
+								return;
+							}
+							const output = lines.join("\n");
+							if (code !== 0) {
+								const errorMsg = stderr.trim() || `fd exited with code ${code}`;
+								if (!output) {
+									settle(() => reject(new Error(errorMsg)));
+									return;
+								}
+							}
+							if (!output) {
+								settle(() =>
+									resolve({
+										content: [{ type: "text", text: "No files found matching pattern" }],
+										details: undefined,
+									}),
+								);
+								return;
+							}
+
+							const relativized: string[] = [];
+							for (const rawLine of lines) {
+								const line = rawLine.replace(/\r$/, "").trim();
+								if (!line) continue;
+								relativized.push(relativizeFindResultPath(line, searchPath));
+							}
+
+							const resultLimitReached = relativized.length >= effectiveLimit;
+							const rawOutput = relativized.join("\n");
+							const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
+							let resultOutput = truncation.content;
+							const details: FindToolDetails = {};
+							const notices: string[] = [];
+							if (resultLimitReached) {
+								notices.push(
+									`${effectiveLimit} results limit reached. Use limit=${effectiveLimit * 2} for more, or refine pattern`,
+								);
+								details.resultLimitReached = effectiveLimit;
+							}
+							if (truncation.truncated) {
+								notices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);
+								details.truncation = truncation;
+							}
+							if (notices.length > 0) {
+								resultOutput += `\n\n[${notices.join(". ")}]`;
+							}
+							settle(() =>
+								resolve({
+									content: [{ type: "text", text: resultOutput }],
+									details: Object.keys(details).length > 0 ? details : undefined,
+								}),
+							);
+						});
+					} catch (e) {
+						if (signal?.aborted) {
+							settle(() => reject(new Error("Operation aborted")));
+							return;
+						}
+						const error = e instanceof Error ? e : new Error(String(e));
+						settle(() => reject(error));
+					}
+				})();
+			});
+		},
+		...findRenderers,
+	};
+}
+
+export function createFindTool(cwd: string, options?: FindToolOptions): AgentTool<typeof findSchema> {
+	return wrapToolDefinition(createFindToolDefinition(cwd, options));
+}

packages/coding-agent/src/core/tools/grep.ts

@@ -0,0 +1,323 @@
+import { readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { spawn } from "child_process";
+import path from "path";
+import { type Static, Type } from "typebox";
+import { ensureTool } from "../../utils/tools-manager.ts";
+import type { ExtensionContext, ToolDefinition } from "../extensions/types.ts";
+import { resolveToCwd } from "./path-utils.ts";
+import { grepRenderers } from "./renderers/grep.ts";
+import { wrapToolDefinition } from "./tool-definition-wrapper.ts";
+import {
+	DEFAULT_MAX_BYTES,
+	formatSize,
+	GREP_MAX_LINE_LENGTH,
+	type TruncationResult,
+	truncateHead,
+	truncateLine,
+} from "./truncate.ts";
+
+const grepSchema = Type.Object({
+	pattern: Type.String({ description: "Search pattern (regex or literal string)" }),
+	path: Type.Optional(Type.String({ description: "Directory or file to search (default: current directory)" })),
+	glob: Type.Optional(Type.String({ description: "Filter files by glob pattern, e.g. '*.ts' or '**/*.spec.ts'" })),
+	ignoreCase: Type.Optional(Type.Boolean({ description: "Case-insensitive search (default: false)" })),
+	literal: Type.Optional(
+		Type.Boolean({ description: "Treat pattern as literal string instead of regex (default: false)" }),
+	),
+	context: Type.Optional(
+		Type.Number({ description: "Number of lines to show before and after each match (default: 0)" }),
+	),
+	limit: Type.Optional(Type.Number({ description: "Maximum number of matches to return (default: 100)" })),
+});
+
+export const grepToolSystemPromptContribution = {
+	snippet: "Search file contents for patterns (respects .gitignore)",
+	guidelines: [],
+} as const;
+
+export type GrepToolInput = Static<typeof grepSchema>;
+const DEFAULT_LIMIT = 100;
+
+export interface GrepToolDetails {
+	truncation?: TruncationResult;
+	matchLimitReached?: number;
+	linesTruncated?: boolean;
+}
+
+/**
+ * Pluggable operations for the grep tool.
+ * Override these to delegate search to remote systems (for example SSH).
+ */
+export interface GrepOperations {
+	/** Check if path is a directory. Throws if path does not exist. */
+	isDirectory: (absolutePath: string) => Promise<boolean> | boolean;
+	/** Read file contents for context lines */
+	readFile: (absolutePath: string) => Promise<string> | string;
+}
+
+const defaultGrepOperations: GrepOperations = {
+	isDirectory: async (p) => (await fsStat(p)).isDirectory(),
+	readFile: (p) => fsReadFile(p, "utf-8"),
+};
+
+export interface GrepToolOptions {
+	/** Custom operations for grep. Default: local filesystem plus ripgrep */
+	operations?: GrepOperations;
+}
+
+export function createGrepToolDefinition(
+	cwd: string,
+	options?: GrepToolOptions,
+): ToolDefinition<typeof grepSchema, GrepToolDetails | undefined> {
+	const customOps = options?.operations;
+	return {
+		name: "grep",
+		label: "grep",
+		description: `Search file contents for a pattern. Returns matching lines with file paths and line numbers. Respects .gitignore. Output is truncated to ${DEFAULT_LIMIT} matches or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Long lines are truncated to ${GREP_MAX_LINE_LENGTH} chars.`,
+		promptSnippet: grepToolSystemPromptContribution.snippet,
+		parameters: grepSchema,
+		async execute(
+			_toolCallId,
+			{
+				pattern,
+				path: searchDir,
+				glob,
+				ignoreCase,
+				literal,
+				context,
+				limit,
+			}: {
+				pattern: string;
+				path?: string;
+				glob?: string;
+				ignoreCase?: boolean;
+				literal?: boolean;
+				context?: number;
+				limit?: number;
+			},
+			signal?: AbortSignal,
+			_onUpdate?,
+			ctx?: ExtensionContext,
+		) {
+			return new Promise((resolve, reject) => {
+				if (signal?.aborted) {
+					reject(new Error("Operation aborted"));
+					return;
+				}
+				let settled = false;
+				const settle = (fn: () => void) => {
+					if (!settled) {
+						settled = true;
+						fn();
+					}
+				};
+
+				(async () => {
+					try {
+						const rgPath = await ensureTool("rg");
+						if (!rgPath) {
+							settle(() => reject(new Error("ripgrep (rg) is not available and could not be downloaded")));
+							return;
+						}
+
+						const searchPath = resolveToCwd(searchDir || ".", ctx?.cwd || cwd);
+						const ops = customOps ?? defaultGrepOperations;
+						let isDirectory: boolean;
+						try {
+							isDirectory = await ops.isDirectory(searchPath);
+						} catch {
+							settle(() => reject(new Error(`Path not found: ${searchPath}`)));
+							return;
+						}
+
+						const contextValue = context && context > 0 ? context : 0;
+						const effectiveLimit = Math.max(1, limit ?? DEFAULT_LIMIT);
+						const formatPath = (filePath: string): string => {
+							if (isDirectory) {
+								const relative = path.relative(searchPath, filePath);
+								if (relative && !relative.startsWith("..")) {
+									return relative.replace(/\\/g, "/");
+								}
+							}
+							return path.basename(filePath);
+						};
+
+						const fileCache = new Map<string, string[]>();
+						const getFileLines = async (filePath: string): Promise<string[]> => {
+							let lines = fileCache.get(filePath);
+							if (!lines) {
+								try {
+									const content = await ops.readFile(filePath);
+									lines = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+								} catch {
+									lines = [];
+								}
+								fileCache.set(filePath, lines);
+							}
+							return lines;
+						};
+
+						const args: string[] = ["--json", "--line-number", "--color=never", "--hidden"];
+						if (ignoreCase) args.push("--ignore-case");
+						if (literal) args.push("--fixed-strings");
+						if (glob) args.push("--glob", glob);
+						args.push("--", pattern, searchPath);
+
+						const child = spawn(rgPath, args, { stdio: ["ignore", "pipe", "pipe"] });
+						const rl = createInterface({ input: child.stdout });
+						let stderr = "";
+						let matchCount = 0;
+						let matchLimitReached = false;
+						let linesTruncated = false;
+						let aborted = false;
+						let killedDueToLimit = false;
+						const outputLines: string[] = [];
+
+						const cleanup = () => {
+							rl.close();
+							signal?.removeEventListener("abort", onAbort);
+						};
+						const stopChild = (dueToLimit = false) => {
+							if (!child.killed) {
+								killedDueToLimit = dueToLimit;
+								child.kill();
+							}
+						};
+						const onAbort = () => {
+							aborted = true;
+							stopChild();
+						};
+						signal?.addEventListener("abort", onAbort, { once: true });
+						child.stderr?.on("data", (chunk) => {
+							stderr += chunk.toString();
+						});
+
+						const formatBlock = async (filePath: string, lineNumber: number): Promise<string[]> => {
+							const relativePath = formatPath(filePath);
+							const lines = await getFileLines(filePath);
+							if (!lines.length) return [`${relativePath}:${lineNumber}: (unable to read file)`];
+							const block: string[] = [];
+							const start = contextValue > 0 ? Math.max(1, lineNumber - contextValue) : lineNumber;
+							const end = contextValue > 0 ? Math.min(lines.length, lineNumber + contextValue) : lineNumber;
+							for (let current = start; current <= end; current++) {
+								const lineText = lines[current - 1] ?? "";
+								const sanitized = lineText.replace(/\r/g, "");
+								const isMatchLine = current === lineNumber;
+								// Truncate long lines so grep output stays compact.
+								const { text: truncatedText, wasTruncated } = truncateLine(sanitized);
+								if (wasTruncated) linesTruncated = true;
+								if (isMatchLine) block.push(`${relativePath}:${current}: ${truncatedText}`);
+								else block.push(`${relativePath}-${current}- ${truncatedText}`);
+							}
+							return block;
+						};
+
+						// Collect matches during streaming, then format them after rg exits.
+						const matches: Array<{ filePath: string; lineNumber: number; lineText?: string }> = [];
+						rl.on("line", (line) => {
+							if (!line.trim() || matchCount >= effectiveLimit) return;
+							let event: any;
+							try {
+								event = JSON.parse(line);
+							} catch {
+								return;
+							}
+							if (event.type === "match") {
+								matchCount++;
+								const filePath = event.data?.path?.text;
+								const lineNumber = event.data?.line_number;
+								const lineText = event.data?.lines?.text;
+								if (filePath && typeof lineNumber === "number")
+									matches.push({ filePath, lineNumber, lineText });
+								if (matchCount >= effectiveLimit) {
+									matchLimitReached = true;
+									stopChild(true);
+								}
+							}
+						});
+
+						child.on("error", (error) => {
+							cleanup();
+							settle(() => reject(new Error(`Failed to run ripgrep: ${error.message}`)));
+						});
+						child.on("close", async (code) => {
+							cleanup();
+							if (aborted) {
+								settle(() => reject(new Error("Operation aborted")));
+								return;
+							}
+							if (!killedDueToLimit && code !== 0 && code !== 1) {
+								const errorMsg = stderr.trim() || `ripgrep exited with code ${code}`;
+								settle(() => reject(new Error(errorMsg)));
+								return;
+							}
+							if (matchCount === 0) {
+								settle(() =>
+									resolve({ content: [{ type: "text", text: "No matches found" }], details: undefined }),
+								);
+								return;
+							}
+
+							// Format matches after streaming finishes so custom readFile() backends can be async.
+							for (const match of matches) {
+								if (contextValue === 0 && match.lineText !== undefined) {
+									const relativePath = formatPath(match.filePath);
+									const sanitized = match.lineText
+										.replace(/\r\n/g, "\n")
+										.replace(/\r/g, "")
+										.replace(/\n$/, "");
+									const { text: truncatedText, wasTruncated } = truncateLine(sanitized);
+									if (wasTruncated) linesTruncated = true;
+									outputLines.push(`${relativePath}:${match.lineNumber}: ${truncatedText}`);
+								} else {
+									const block = await formatBlock(match.filePath, match.lineNumber);
+									outputLines.push(...block);
+								}
+							}
+
+							const rawOutput = outputLines.join("\n");
+							// Apply byte truncation. There is no line limit here because the match limit already capped rows.
+							const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
+							let output = truncation.content;
+							const details: GrepToolDetails = {};
+							// Build actionable notices for truncation and match limits.
+							const notices: string[] = [];
+							if (matchLimitReached) {
+								notices.push(
+									`${effectiveLimit} matches limit reached. Use limit=${effectiveLimit * 2} for more, or refine pattern`,
+								);
+								details.matchLimitReached = effectiveLimit;
+							}
+							if (truncation.truncated) {
+								notices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);
+								details.truncation = truncation;
+							}
+							if (linesTruncated) {
+								notices.push(
+									`Some lines truncated to ${GREP_MAX_LINE_LENGTH} chars. Use read tool to see full lines`,
+								);
+								details.linesTruncated = true;
+							}
+							if (notices.length > 0) output += `\n\n[${notices.join(". ")}]`;
+							settle(() =>
+								resolve({
+									content: [{ type: "text", text: output }],
+									details: Object.keys(details).length > 0 ? details : undefined,
+								}),
+							);
+						});
+					} catch (err) {
+						settle(() => reject(err as Error));
+					}
+				})();
+			});
+		},
+		...grepRenderers,
+	};
+}
+
+export function createGrepTool(cwd: string, options?: GrepToolOptions): AgentTool<typeof grepSchema> {
+	return wrapToolDefinition(createGrepToolDefinition(cwd, options));
+}

packages/coding-agent/src/core/tools/index.ts

@@ -0,0 +1,224 @@
+export {
+	type BashOperations,
+	type BashSpawnContext,
+	type BashSpawnHook,
+	type BashToolDetails,
+	type BashToolInput,
+	type BashToolOptions,
+	createBashTool,
+	createBashToolDefinition,
+	createLocalBashOperations,
+} from "./bash.ts";
+export {
+	createEditTool,
+	createEditToolDefinition,
+	type EditOperations,
+	type EditToolDetails,
+	type EditToolInput,
+	type EditToolOptions,
+} from "./edit.ts";
+export { withFileMutationQueue } from "./file-mutation-queue.ts";
+export {
+	createFindTool,
+	createFindToolDefinition,
+	type FindOperations,
+	type FindToolDetails,
+	type FindToolInput,
+	type FindToolOptions,
+} from "./find.ts";
+export {
+	createGrepTool,
+	createGrepToolDefinition,
+	type GrepOperations,
+	type GrepToolDetails,
+	type GrepToolInput,
+	type GrepToolOptions,
+} from "./grep.ts";
+export {
+	createLsTool,
+	createLsToolDefinition,
+	type LsOperations,
+	type LsToolDetails,
+	type LsToolInput,
+	type LsToolOptions,
+} from "./ls.ts";
+export {
+	createLocalPowerShellOperations,
+	createPowerShellTool,
+	createPowerShellToolDefinition,
+	type PowerShellOperations,
+	type PowerShellSpawnContext,
+	type PowerShellSpawnHook,
+	type PowerShellToolDetails,
+	type PowerShellToolInput,
+	type PowerShellToolOptions,
+} from "./powershell.ts";
+export {
+	createReadTool,
+	createReadToolDefinition,
+	type ReadOperations,
+	type ReadToolDetails,
+	type ReadToolInput,
+	type ReadToolOptions,
+} from "./read.ts";
+export {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	type TruncationOptions,
+	type TruncationResult,
+	truncateHead,
+	truncateLine,
+	truncateTail,
+} from "./truncate.ts";
+export {
+	createWriteTool,
+	createWriteToolDefinition,
+	type WriteOperations,
+	type WriteToolInput,
+	type WriteToolOptions,
+} from "./write.ts";
+
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { ToolDefinition } from "../extensions/types.ts";
+import { type BashToolOptions, createBashTool, createBashToolDefinition } from "./bash.ts";
+import { createEditTool, createEditToolDefinition, type EditToolOptions } from "./edit.ts";
+import { createFindTool, createFindToolDefinition, type FindToolOptions } from "./find.ts";
+import { createGrepTool, createGrepToolDefinition, type GrepToolOptions } from "./grep.ts";
+import { createLsTool, createLsToolDefinition, type LsToolOptions } from "./ls.ts";
+import { createPowerShellTool, createPowerShellToolDefinition, type PowerShellToolOptions } from "./powershell.ts";
+import { createReadTool, createReadToolDefinition, type ReadToolOptions } from "./read.ts";
+import { createWriteTool, createWriteToolDefinition, type WriteToolOptions } from "./write.ts";
+
+export type Tool = AgentTool<any>;
+export type ToolDef = ToolDefinition<any, any>;
+export type ToolName = "read" | "bash" | "powershell" | "edit" | "write" | "grep" | "find" | "ls";
+export const allToolNames: Set<ToolName> = new Set([
+	"read",
+	"bash",
+	"powershell",
+	"edit",
+	"write",
+	"grep",
+	"find",
+	"ls",
+]);
+
+export interface ToolsOptions {
+	read?: ReadToolOptions;
+	bash?: BashToolOptions;
+	powershell?: PowerShellToolOptions;
+	write?: WriteToolOptions;
+	edit?: EditToolOptions;
+	grep?: GrepToolOptions;
+	find?: FindToolOptions;
+	ls?: LsToolOptions;
+}
+
+export function createToolDefinition(toolName: ToolName, cwd: string, options?: ToolsOptions): ToolDef {
+	switch (toolName) {
+		case "read":
+			return createReadToolDefinition(cwd, options?.read);
+		case "bash":
+			return createBashToolDefinition(cwd, options?.bash);
+		case "powershell":
+			return createPowerShellToolDefinition(cwd, options?.powershell);
+		case "edit":
+			return createEditToolDefinition(cwd, options?.edit);
+		case "write":
+			return createWriteToolDefinition(cwd, options?.write);
+		case "grep":
+			return createGrepToolDefinition(cwd, options?.grep);
+		case "find":
+			return createFindToolDefinition(cwd, options?.find);
+		case "ls":
+			return createLsToolDefinition(cwd, options?.ls);
+		default:
+			throw new Error(`Unknown tool name: ${toolName}`);
+	}
+}
+
+export function createTool(toolName: ToolName, cwd: string, options?: ToolsOptions): Tool {
+	switch (toolName) {
+		case "read":
+			return createReadTool(cwd, options?.read);
+		case "bash":
+			return createBashTool(cwd, options?.bash);
+		case "powershell":
+			return createPowerShellTool(cwd, options?.powershell);
+		case "edit":
+			return createEditTool(cwd, options?.edit);
+		case "write":
+			return createWriteTool(cwd, options?.write);
+		case "grep":
+			return createGrepTool(cwd, options?.grep);
+		case "find":
+			return createFindTool(cwd, options?.find);
+		case "ls":
+			return createLsTool(cwd, options?.ls);
+		default:
+			throw new Error(`Unknown tool name: ${toolName}`);
+	}
+}
+
+export function createCodingToolDefinitions(cwd: string, options?: ToolsOptions): ToolDef[] {
+	return [
+		createReadToolDefinition(cwd, options?.read),
+		createBashToolDefinition(cwd, options?.bash),
+		createEditToolDefinition(cwd, options?.edit),
+		createWriteToolDefinition(cwd, options?.write),
+	];
+}
+
+export function createReadOnlyToolDefinitions(cwd: string, options?: ToolsOptions): ToolDef[] {
+	return [
+		createReadToolDefinition(cwd, options?.read),
+		createGrepToolDefinition(cwd, options?.grep),
+		createFindToolDefinition(cwd, options?.find),
+		createLsToolDefinition(cwd, options?.ls),
+	];
+}
+
+export function createAllToolDefinitions(cwd: string, options?: ToolsOptions): Record<ToolName, ToolDef> {
+	return {
+		read: createReadToolDefinition(cwd, options?.read),
+		bash: createBashToolDefinition(cwd, options?.bash),
+		powershell: createPowerShellToolDefinition(cwd, options?.powershell),
+		edit: createEditToolDefinition(cwd, options?.edit),
+		write: createWriteToolDefinition(cwd, options?.write),
+		grep: createGrepToolDefinition(cwd, options?.grep),
+		find: createFindToolDefinition(cwd, options?.find),
+		ls: createLsToolDefinition(cwd, options?.ls),
+	};
+}
+
+export function createCodingTools(cwd: string, options?: ToolsOptions): Tool[] {
+	return [
+		createReadTool(cwd, options?.read),
+		createBashTool(cwd, options?.bash),
+		createEditTool(cwd, options?.edit),
+		createWriteTool(cwd, options?.write),
+	];
+}
+
+export function createReadOnlyTools(cwd: string, options?: ToolsOptions): Tool[] {
+	return [
+		createReadTool(cwd, options?.read),
+		createGrepTool(cwd, options?.grep),
+		createFindTool(cwd, options?.find),
+		createLsTool(cwd, options?.ls),
+	];
+}
+
+export function createAllTools(cwd: string, options?: ToolsOptions): Record<ToolName, Tool> {
+	return {
+		read: createReadTool(cwd, options?.read),
+		bash: createBashTool(cwd, options?.bash),
+		powershell: createPowerShellTool(cwd, options?.powershell),
+		edit: createEditTool(cwd, options?.edit),
+		write: createWriteTool(cwd, options?.write),
+		grep: createGrepTool(cwd, options?.grep),
+		find: createFindTool(cwd, options?.find),
+		ls: createLsTool(cwd, options?.ls),
+	};
+}

packages/coding-agent/src/core/tools/ls.ts

@@ -0,0 +1,175 @@
+import { readdir as fsReaddir, stat as fsStat } from "node:fs/promises";
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import nodePath from "path";
+import { type Static, Type } from "typebox";
+import type { ExtensionContext, ToolDefinition } from "../extensions/types.ts";
+import { pathExists, resolveToCwd } from "./path-utils.ts";
+import { lsRenderers } from "./renderers/ls.ts";
+import { wrapToolDefinition } from "./tool-definition-wrapper.ts";
+import { DEFAULT_MAX_BYTES, formatSize, type TruncationResult, truncateHead } from "./truncate.ts";
+
+const lsSchema = Type.Object({
+	path: Type.Optional(Type.String({ description: "Directory to list (default: current directory)" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum number of entries to return (default: 500)" })),
+});
+
+export const lsToolSystemPromptContribution = {
+	snippet: "List directory contents",
+	guidelines: [],
+} as const;
+
+export type LsToolInput = Static<typeof lsSchema>;
+
+const DEFAULT_LIMIT = 500;
+
+export interface LsToolDetails {
+	truncation?: TruncationResult;
+	entryLimitReached?: number;
+}
+
+/**
+ * Pluggable operations for the ls tool.
+ * Override these to delegate directory listing to remote systems (for example SSH).
+ */
+export interface LsOperations {
+	/** Check if path exists */
+	exists: (absolutePath: string) => Promise<boolean> | boolean;
+	/** Get file or directory stats. Throws if not found. */
+	stat: (absolutePath: string) => Promise<{ isDirectory: () => boolean }> | { isDirectory: () => boolean };
+	/** Read directory entries */
+	readdir: (absolutePath: string) => Promise<string[]> | string[];
+}
+
+const defaultLsOperations: LsOperations = {
+	exists: pathExists,
+	stat: fsStat,
+	readdir: fsReaddir,
+};
+
+export interface LsToolOptions {
+	/** Custom operations for directory listing. Default: local filesystem */
+	operations?: LsOperations;
+}
+
+export function createLsToolDefinition(
+	cwd: string,
+	options?: LsToolOptions,
+): ToolDefinition<typeof lsSchema, LsToolDetails | undefined> {
+	const ops = options?.operations ?? defaultLsOperations;
+	return {
+		name: "ls",
+		label: "ls",
+		description: `List directory contents. Returns entries sorted alphabetically, with '/' suffix for directories. Includes dotfiles. Output is truncated to ${DEFAULT_LIMIT} entries or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first).`,
+		promptSnippet: lsToolSystemPromptContribution.snippet,
+		parameters: lsSchema,
+		async execute(
+			_toolCallId,
+			{ path, limit }: { path?: string; limit?: number },
+			signal?: AbortSignal,
+			_onUpdate?,
+			ctx?: ExtensionContext,
+		) {
+			return new Promise((resolve, reject) => {
+				if (signal?.aborted) {
+					reject(new Error("Operation aborted"));
+					return;
+				}
+
+				const onAbort = () => reject(new Error("Operation aborted"));
+				signal?.addEventListener("abort", onAbort, { once: true });
+
+				(async () => {
+					try {
+						const dirPath = resolveToCwd(path || ".", ctx?.cwd || cwd);
+						const effectiveLimit = limit ?? DEFAULT_LIMIT;
+
+						// Check if path exists.
+						if (!(await ops.exists(dirPath))) {
+							reject(new Error(`Path not found: ${dirPath}`));
+							return;
+						}
+
+						// Check if path is a directory.
+						const stat = await ops.stat(dirPath);
+						if (!stat.isDirectory()) {
+							reject(new Error(`Not a directory: ${dirPath}`));
+							return;
+						}
+
+						// Read directory entries.
+						let entries: string[];
+						try {
+							entries = await ops.readdir(dirPath);
+						} catch (e: any) {
+							reject(new Error(`Cannot read directory: ${e.message}`));
+							return;
+						}
+
+						// Sort alphabetically, case-insensitive.
+						entries.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()));
+
+						// Format entries with directory indicators.
+						const results: string[] = [];
+						let entryLimitReached = false;
+						for (const entry of entries) {
+							if (results.length >= effectiveLimit) {
+								entryLimitReached = true;
+								break;
+							}
+
+							const fullPath = nodePath.join(dirPath, entry);
+							let suffix = "";
+							try {
+								const entryStat = await ops.stat(fullPath);
+								if (entryStat.isDirectory()) suffix = "/";
+							} catch {
+								// Skip entries we cannot stat.
+								continue;
+							}
+							results.push(entry + suffix);
+						}
+
+						signal?.removeEventListener("abort", onAbort);
+
+						if (results.length === 0) {
+							resolve({ content: [{ type: "text", text: "(empty directory)" }], details: undefined });
+							return;
+						}
+
+						const rawOutput = results.join("\n");
+						// Apply byte truncation. There is no separate line limit because entry count is already capped.
+						const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
+						let output = truncation.content;
+						const details: LsToolDetails = {};
+						// Build actionable notices for truncation and entry limits.
+						const notices: string[] = [];
+						if (entryLimitReached) {
+							notices.push(`${effectiveLimit} entries limit reached. Use limit=${effectiveLimit * 2} for more`);
+							details.entryLimitReached = effectiveLimit;
+						}
+						if (truncation.truncated) {
+							notices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);
+							details.truncation = truncation;
+						}
+						if (notices.length > 0) {
+							output += `\n\n[${notices.join(". ")}]`;
+						}
+
+						resolve({
+							content: [{ type: "text", text: output }],
+							details: Object.keys(details).length > 0 ? details : undefined,
+						});
+					} catch (e: any) {
+						signal?.removeEventListener("abort", onAbort);
+						reject(e);
+					}
+				})();
+			});
+		},
+		...lsRenderers,
+	};
+}
+
+export function createLsTool(cwd: string, options?: LsToolOptions): AgentTool<typeof lsSchema> {
+	return wrapToolDefinition(createLsToolDefinition(cwd, options));
+}

packages/coding-agent/src/core/tools/output-accumulator.ts

@@ -0,0 +1,222 @@
+import { randomBytes } from "node:crypto";
+import { createWriteStream, type WriteStream } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, type TruncationResult, truncateTail } from "./truncate.ts";
+
+export interface OutputAccumulatorOptions {
+	maxLines?: number;
+	maxBytes?: number;
+	tempFilePrefix?: string;
+}
+
+export interface OutputSnapshot {
+	content: string;
+	truncation: TruncationResult;
+	fullOutputPath?: string;
+}
+
+function defaultTempFilePath(prefix: string): string {
+	const id = randomBytes(8).toString("hex");
+	return join(tmpdir(), `${prefix}-${id}.log`);
+}
+
+function byteLength(text: string): number {
+	return Buffer.byteLength(text, "utf-8");
+}
+
+/**
+ * Incrementally tracks streaming output with bounded memory.
+ *
+ * Appends decode chunks with a streaming UTF-8 decoder, keeps only a decoded
+ * tail for display snapshots, and opens a temp file when the full output needs
+ * to be preserved.
+ */
+export class OutputAccumulator {
+	private readonly maxLines: number;
+	private readonly maxBytes: number;
+	private readonly maxRollingBytes: number;
+	private readonly tempFilePrefix: string;
+	private readonly decoder = new TextDecoder();
+
+	private rawChunks: Buffer[] = [];
+	private tailText = "";
+	private tailBytes = 0;
+	private tailStartsAtLineBoundary = true;
+	private totalRawBytes = 0;
+	private totalDecodedBytes = 0;
+	private completedLines = 0;
+	private totalLines = 0;
+	private currentLineBytes = 0;
+	private hasOpenLine = false;
+	private finished = false;
+
+	private tempFilePath: string | undefined;
+	private tempFileStream: WriteStream | undefined;
+
+	constructor(options: OutputAccumulatorOptions = {}) {
+		this.maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+		this.maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+		this.maxRollingBytes = Math.max(this.maxBytes * 2, 1);
+		this.tempFilePrefix = options.tempFilePrefix ?? "pi-output";
+	}
+
+	append(data: Buffer): void {
+		if (this.finished) {
+			throw new Error("Cannot append to a finished output accumulator");
+		}
+
+		this.totalRawBytes += data.length;
+		this.appendDecodedText(this.decoder.decode(data, { stream: true }));
+
+		if (this.tempFileStream || this.shouldUseTempFile()) {
+			this.ensureTempFile();
+			this.tempFileStream?.write(data);
+		} else if (data.length > 0) {
+			this.rawChunks.push(data);
+		}
+	}
+
+	finish(): void {
+		if (this.finished) {
+			return;
+		}
+		this.finished = true;
+		this.appendDecodedText(this.decoder.decode());
+		if (this.shouldUseTempFile()) {
+			this.ensureTempFile();
+		}
+	}
+
+	snapshot(options: { persistIfTruncated?: boolean } = {}): OutputSnapshot {
+		const tailTruncation = truncateTail(this.getSnapshotText(), {
+			maxLines: this.maxLines,
+			maxBytes: this.maxBytes,
+		});
+		const truncated = this.totalLines > this.maxLines || this.totalDecodedBytes > this.maxBytes;
+		const truncatedBy = truncated
+			? (tailTruncation.truncatedBy ?? (this.totalDecodedBytes > this.maxBytes ? "bytes" : "lines"))
+			: null;
+		const truncation: TruncationResult = {
+			...tailTruncation,
+			truncated,
+			truncatedBy,
+			totalLines: this.totalLines,
+			totalBytes: this.totalDecodedBytes,
+			maxLines: this.maxLines,
+			maxBytes: this.maxBytes,
+		};
+
+		if (options.persistIfTruncated && truncation.truncated) {
+			this.ensureTempFile();
+		}
+
+		return {
+			content: truncation.content,
+			truncation,
+			fullOutputPath: this.tempFilePath,
+		};
+	}
+
+	async closeTempFile(): Promise<void> {
+		if (!this.tempFileStream) {
+			return;
+		}
+
+		const stream = this.tempFileStream;
+		this.tempFileStream = undefined;
+
+		await new Promise<void>((resolve, reject) => {
+			const onError = (error: Error) => {
+				stream.off("finish", onFinish);
+				reject(error);
+			};
+			const onFinish = () => {
+				stream.off("error", onError);
+				resolve();
+			};
+			stream.once("error", onError);
+			stream.once("finish", onFinish);
+			stream.end();
+		});
+	}
+
+	getLastLineBytes(): number {
+		return this.currentLineBytes;
+	}
+
+	private appendDecodedText(text: string): void {
+		if (text.length === 0) {
+			return;
+		}
+
+		const bytes = byteLength(text);
+		this.totalDecodedBytes += bytes;
+		this.tailText += text;
+		this.tailBytes += bytes;
+		if (this.tailBytes > this.maxRollingBytes * 2) {
+			this.trimTail();
+		}
+
+		let newlines = 0;
+		let lastNewline = -1;
+		for (let i = text.indexOf("\n"); i !== -1; i = text.indexOf("\n", i + 1)) {
+			newlines++;
+			lastNewline = i;
+		}
+		if (newlines === 0) {
+			this.currentLineBytes += bytes;
+			this.hasOpenLine = true;
+		} else {
+			this.completedLines += newlines;
+			const tail = text.slice(lastNewline + 1);
+			this.currentLineBytes = byteLength(tail);
+			this.hasOpenLine = tail.length > 0;
+		}
+		this.totalLines = this.completedLines + (this.hasOpenLine ? 1 : 0);
+	}
+
+	private trimTail(): void {
+		const buffer = Buffer.from(this.tailText, "utf-8");
+		if (buffer.length <= this.maxRollingBytes) {
+			this.tailBytes = buffer.length;
+			return;
+		}
+
+		let start = buffer.length - this.maxRollingBytes;
+		while (start < buffer.length && (buffer[start] & 0xc0) === 0x80) {
+			start++;
+		}
+
+		this.tailStartsAtLineBoundary = start === 0 ? this.tailStartsAtLineBoundary : buffer[start - 1] === 0x0a;
+		this.tailText = buffer.subarray(start).toString("utf-8");
+		this.tailBytes = byteLength(this.tailText);
+	}
+
+	private getSnapshotText(): string {
+		if (this.tailStartsAtLineBoundary) {
+			return this.tailText;
+		}
+
+		const firstNewline = this.tailText.indexOf("\n");
+		return firstNewline === -1 ? this.tailText : this.tailText.slice(firstNewline + 1);
+	}
+
+	private shouldUseTempFile(): boolean {
+		return (
+			this.totalRawBytes > this.maxBytes || this.totalDecodedBytes > this.maxBytes || this.totalLines > this.maxLines
+		);
+	}
+
+	private ensureTempFile(): void {
+		if (this.tempFilePath) {
+			return;
+		}
+		this.tempFilePath = defaultTempFilePath(this.tempFilePrefix);
+		this.tempFileStream = createWriteStream(this.tempFilePath);
+		for (const chunk of this.rawChunks) {
+			this.tempFileStream.write(chunk);
+		}
+		this.rawChunks = [];
+	}
+}

packages/coding-agent/src/core/tools/path-utils.ts

@@ -0,0 +1,118 @@
+import { accessSync, constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { normalizePath, resolvePath } from "../../utils/paths.ts";
+
+const NARROW_NO_BREAK_SPACE = "\u202F";
+
+function tryMacOSScreenshotPath(filePath: string): string {
+	return filePath.replace(/ (AM|PM)\./gi, `${NARROW_NO_BREAK_SPACE}$1.`);
+}
+
+function tryNFDVariant(filePath: string): string {
+	// macOS stores filenames in NFD (decomposed) form, try converting user input to NFD
+	return filePath.normalize("NFD");
+}
+
+function tryCurlyQuoteVariant(filePath: string): string {
+	// macOS uses U+2019 (right single quotation mark) in screenshot names like "Capture d'écran"
+	// Users typically type U+0027 (straight apostrophe)
+	return filePath.replace(/'/g, "\u2019");
+}
+
+function fileExists(filePath: string): boolean {
+	try {
+		accessSync(filePath, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function pathExists(filePath: string): Promise<boolean> {
+	try {
+		await access(filePath, constants.F_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export function expandPath(filePath: string): string {
+	return normalizePath(filePath, { normalizeUnicodeSpaces: true, stripAtPrefix: true });
+}
+
+/**
+ * Resolve a path relative to the given cwd.
+ * Handles ~ expansion and absolute paths.
+ */
+export function resolveToCwd(filePath: string, cwd: string): string {
+	return resolvePath(filePath, cwd, { normalizeUnicodeSpaces: true, stripAtPrefix: true });
+}
+
+export function resolveReadPath(filePath: string, cwd: string): string {
+	const resolved = resolveToCwd(filePath, cwd);
+
+	if (fileExists(resolved)) {
+		return resolved;
+	}
+
+	// Try macOS AM/PM variant (narrow no-break space before AM/PM)
+	const amPmVariant = tryMacOSScreenshotPath(resolved);
+	if (amPmVariant !== resolved && fileExists(amPmVariant)) {
+		return amPmVariant;
+	}
+
+	// Try NFD variant (macOS stores filenames in NFD form)
+	const nfdVariant = tryNFDVariant(resolved);
+	if (nfdVariant !== resolved && fileExists(nfdVariant)) {
+		return nfdVariant;
+	}
+
+	// Try curly quote variant (macOS uses U+2019 in screenshot names)
+	const curlyVariant = tryCurlyQuoteVariant(resolved);
+	if (curlyVariant !== resolved && fileExists(curlyVariant)) {
+		return curlyVariant;
+	}
+
+	// Try combined NFD + curly quote (for French macOS screenshots like "Capture d'écran")
+	const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
+	if (nfdCurlyVariant !== resolved && fileExists(nfdCurlyVariant)) {
+		return nfdCurlyVariant;
+	}
+
+	return resolved;
+}
+
+export async function resolveReadPathAsync(filePath: string, cwd: string): Promise<string> {
+	const resolved = resolveToCwd(filePath, cwd);
+
+	if (await pathExists(resolved)) {
+		return resolved;
+	}
+
+	// Try macOS AM/PM variant (narrow no-break space before AM/PM)
+	const amPmVariant = tryMacOSScreenshotPath(resolved);
+	if (amPmVariant !== resolved && (await pathExists(amPmVariant))) {
+		return amPmVariant;
+	}
+
+	// Try NFD variant (macOS stores filenames in NFD form)
+	const nfdVariant = tryNFDVariant(resolved);
+	if (nfdVariant !== resolved && (await pathExists(nfdVariant))) {
+		return nfdVariant;
+	}
+
+	// Try curly quote variant (macOS uses U+2019 in screenshot names)
+	const curlyVariant = tryCurlyQuoteVariant(resolved);
+	if (curlyVariant !== resolved && (await pathExists(curlyVariant))) {
+		return curlyVariant;
+	}
+
+	// Try combined NFD + curly quote (for French macOS screenshots like "Capture d'écran")
+	const nfdCurlyVariant = tryCurlyQuoteVariant(nfdVariant);
+	if (nfdCurlyVariant !== resolved && (await pathExists(nfdCurlyVariant))) {
+		return nfdCurlyVariant;
+	}
+
+	return resolved;
+}

packages/coding-agent/src/core/tools/powershell.ts

@@ -0,0 +1,67 @@
+import { getPowerShellConfig } from "../../utils/shell.ts";
+import {
+	type BashOperations,
+	type BashSpawnContext,
+	type BashSpawnHook,
+	type BashToolDetails,
+	type BashToolInput,
+	type BashToolOptions,
+	type createBashTool,
+	createLocalShellOperations,
+	createShellToolDefinition,
+	type ShellToolConfig,
+} from "./bash.ts";
+import { wrapToolDefinition } from "./tool-definition-wrapper.ts";
+
+const UTF8_OUTPUT_PREFIX = "try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}\n";
+
+export const powershellToolSystemPromptContribution = {
+	snippet: "Execute PowerShell commands",
+	guidelines: ["You can inspect PI_* environment variables for current model and session details."],
+} as const;
+
+export type PowerShellOperations = BashOperations;
+export type PowerShellSpawnContext = BashSpawnContext;
+export type PowerShellSpawnHook = BashSpawnHook;
+export type PowerShellToolDetails = BashToolDetails;
+export type PowerShellToolInput = BashToolInput;
+
+export interface PowerShellToolOptions
+	extends Pick<BashToolOptions, "operations" | "exposeSessionEnvironment" | "spawnHook"> {}
+
+export function createLocalPowerShellOperations(): PowerShellOperations {
+	const operations = createLocalShellOperations("PowerShell", getPowerShellConfig);
+	return {
+		exec: (command, cwd, options) => operations.exec(`${UTF8_OUTPUT_PREFIX}${command}`, cwd, options),
+	};
+}
+
+const powershellToolConfig: ShellToolConfig = {
+	name: "powershell",
+	label: "powershell",
+	shellName: "PowerShell",
+	prompt: "PS>",
+	promptSnippet: powershellToolSystemPromptContribution.snippet,
+	promptGuidelines: powershellToolSystemPromptContribution.guidelines,
+	tempFilePrefix: "pi-powershell",
+};
+
+export function createPowerShellToolDefinition(
+	cwd: string,
+	options?: PowerShellToolOptions,
+): ReturnType<typeof createShellToolDefinition> {
+	return createShellToolDefinition(cwd, powershellToolConfig, {
+		...options,
+		operations: options?.operations ?? createLocalPowerShellOperations(),
+	});
+}
+
+export function createPowerShellTool(cwd: string, options?: PowerShellToolOptions): ReturnType<typeof createBashTool> {
+	const definition = createPowerShellToolDefinition(cwd, options);
+	const tool = wrapToolDefinition(definition);
+	Object.assign(tool, {
+		promptSnippet: definition.promptSnippet,
+		promptGuidelines: definition.promptGuidelines,
+	});
+	return tool;
+}

packages/coding-agent/src/core/tools/read.ts

@@ -0,0 +1,197 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { Api, ImageContent, Model, TextContent } from "@earendil-works/pi-ai";
+import { constants } from "fs";
+import { access as fsAccess, readFile as fsReadFile } from "fs/promises";
+import { type Static, Type } from "typebox";
+import { processImage } from "../../utils/image-process.ts";
+import { detectSupportedImageMimeTypeFromFile } from "../../utils/mime.ts";
+import type { ExtensionContext, ToolDefinition } from "../extensions/types.ts";
+import { resolveReadPathAsync } from "./path-utils.ts";
+import { readRenderers } from "./renderers/read.ts";
+import { wrapToolDefinition } from "./tool-definition-wrapper.ts";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationResult, truncateHead } from "./truncate.ts";
+
+const readSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
+	offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+});
+
+export const readToolSystemPromptContribution = {
+	snippet: "Read file contents",
+	guidelines: ["Use read to examine files instead of cat or sed."],
+} as const;
+
+export type ReadToolInput = Static<typeof readSchema>;
+
+export interface ReadToolDetails {
+	truncation?: TruncationResult;
+}
+
+/**
+ * Pluggable operations for the read tool.
+ * Override these to delegate file reading to remote systems (for example SSH).
+ */
+export interface ReadOperations {
+	/** Read file contents as a Buffer */
+	readFile: (absolutePath: string) => Promise<Buffer>;
+	/** Check if file is readable (throw if not) */
+	access: (absolutePath: string) => Promise<void>;
+	/** Detect image MIME type, return null or undefined for non-images */
+	detectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;
+}
+
+const defaultReadOperations: ReadOperations = {
+	readFile: (path) => fsReadFile(path),
+	access: (path) => fsAccess(path, constants.R_OK),
+	detectImageMimeType: detectSupportedImageMimeTypeFromFile,
+};
+
+export interface ReadToolOptions {
+	/** Whether to auto-resize images to 2000x2000 max. Default: true */
+	autoResizeImages?: boolean;
+	/** Custom operations for file reading. Default: local filesystem */
+	operations?: ReadOperations;
+}
+
+function getNonVisionImageNote(model: Model<Api> | undefined): string | undefined {
+	if (!model || model.input.includes("image")) {
+		return undefined;
+	}
+	return "[Current model does not support images. The image will be omitted from this request.]";
+}
+
+export function createReadToolDefinition(
+	cwd: string,
+	options?: ReadToolOptions,
+): ToolDefinition<typeof readSchema, ReadToolDetails | undefined> {
+	const autoResizeImages = options?.autoResizeImages ?? true;
+	const ops = options?.operations ?? defaultReadOperations;
+	return {
+		name: "read",
+		label: "read",
+		description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp, bmp). Images are sent as attachments. For text files, output is truncated to ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.`,
+		promptSnippet: readToolSystemPromptContribution.snippet,
+		promptGuidelines: [...readToolSystemPromptContribution.guidelines],
+		parameters: readSchema,
+		constrainedSampling: { type: "json_schema", strict: "prefer" },
+		async execute(
+			_toolCallId,
+			{ path, offset, limit }: { path: string; offset?: number; limit?: number },
+			signal?: AbortSignal,
+			_onUpdate?,
+			ctx?: ExtensionContext,
+		) {
+			return new Promise<{ content: (TextContent | ImageContent)[]; details: ReadToolDetails | undefined }>(
+				(resolve, reject) => {
+					if (signal?.aborted) {
+						reject(new Error("Operation aborted"));
+						return;
+					}
+					let aborted = false;
+					const onAbort = () => {
+						aborted = true;
+						reject(new Error("Operation aborted"));
+					};
+					signal?.addEventListener("abort", onAbort, { once: true });
+
+					(async () => {
+						try {
+							const absolutePath = await resolveReadPathAsync(path, ctx?.cwd || cwd);
+							if (aborted) return;
+							// Check if file exists and is readable.
+							await ops.access(absolutePath);
+							if (aborted) return;
+							const mimeType = ops.detectImageMimeType ? await ops.detectImageMimeType(absolutePath) : undefined;
+							let content: (TextContent | ImageContent)[];
+							let details: ReadToolDetails | undefined;
+							const nonVisionImageNote = getNonVisionImageNote(ctx?.model);
+							if (mimeType) {
+								// Read image as binary.
+								const buffer = await ops.readFile(absolutePath);
+								const processed = await processImage(buffer, mimeType, { autoResizeImages });
+								if (!processed.ok) {
+									let textNote = `Read image file [${mimeType}]\n${processed.message}`;
+									if (nonVisionImageNote) textNote += `\n${nonVisionImageNote}`;
+									content = [{ type: "text", text: textNote }];
+								} else {
+									let textNote = `Read image file [${processed.mimeType}]`;
+									if (processed.hints.length > 0) textNote += `\n${processed.hints.join("\n")}`;
+									if (nonVisionImageNote) textNote += `\n${nonVisionImageNote}`;
+									content = [
+										{ type: "text", text: textNote },
+										{ type: "image", data: processed.data, mimeType: processed.mimeType },
+									];
+								}
+							} else {
+								// Read text content.
+								const buffer = await ops.readFile(absolutePath);
+								const textContent = buffer.toString("utf-8");
+								const allLines = textContent.split("\n");
+								const totalFileLines = allLines.length;
+								// Apply offset if specified. Convert from 1-indexed input to 0-indexed array access.
+								const startLine = offset ? Math.max(0, offset - 1) : 0;
+								const startLineDisplay = startLine + 1;
+								// Check if offset is out of bounds.
+								if (startLine >= allLines.length) {
+									throw new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);
+								}
+								let selectedContent: string;
+								let userLimitedLines: number | undefined;
+								// If limit is specified by the user, honor it first. Otherwise truncateHead decides.
+								if (limit !== undefined) {
+									const endLine = Math.min(startLine + limit, allLines.length);
+									selectedContent = allLines.slice(startLine, endLine).join("\n");
+									userLimitedLines = endLine - startLine;
+								} else {
+									selectedContent = allLines.slice(startLine).join("\n");
+								}
+								// Apply truncation, respecting both line and byte limits.
+								const truncation = truncateHead(selectedContent);
+								let outputText: string;
+								if (truncation.firstLineExceedsLimit) {
+									// First line alone exceeds the byte limit. Point the model at a bash fallback.
+									const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine], "utf-8"));
+									outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${path} | head -c ${DEFAULT_MAX_BYTES}]`;
+									details = { truncation };
+								} else if (truncation.truncated) {
+									// Truncation occurred. Build an actionable continuation notice.
+									const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
+									const nextOffset = endLineDisplay + 1;
+									outputText = truncation.content;
+									if (truncation.truncatedBy === "lines") {
+										outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue.]`;
+									} else {
+										outputText += `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;
+									}
+									details = { truncation };
+								} else if (userLimitedLines !== undefined && startLine + userLimitedLines < allLines.length) {
+									// User-specified limit stopped early, but the file still has more content.
+									const remaining = allLines.length - (startLine + userLimitedLines);
+									const nextOffset = startLine + userLimitedLines + 1;
+									outputText = `${truncation.content}\n\n[${remaining} more lines in file. Use offset=${nextOffset} to continue.]`;
+								} else {
+									// No truncation and no remaining user-limited content.
+									outputText = truncation.content;
+								}
+								content = [{ type: "text", text: outputText }];
+							}
+
+							if (aborted) return;
+							signal?.removeEventListener("abort", onAbort);
+							resolve({ content, details });
+						} catch (error: any) {
+							signal?.removeEventListener("abort", onAbort);
+							if (!aborted) reject(error);
+						}
+					})();
+				},
+			);
+		},
+		...readRenderers,
+	};
+}
+
+export function createReadTool(cwd: string, options?: ReadToolOptions): AgentTool<typeof readSchema> {
+	return wrapToolDefinition(createReadToolDefinition(cwd, options));
+}

packages/coding-agent/src/core/tools/render-utils.ts

@@ -0,0 +1,85 @@
+import * as os from "node:os";
+import { pathToFileURL } from "node:url";
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import { getCapabilities, getImageDimensions, hyperlink, imageFallback } from "@earendil-works/pi-tui";
+import type { Theme } from "../../modes/interactive/theme/theme.ts";
+import { stripAnsi } from "../../utils/ansi.ts";
+import { resolvePath } from "../../utils/paths.ts";
+import { sanitizeBinaryOutput } from "../../utils/shell.ts";
+
+export function shortenPath(path: unknown): string {
+	if (typeof path !== "string") return "";
+	const home = os.homedir();
+	if (path.startsWith(home)) {
+		return `~${path.slice(home.length)}`;
+	}
+	return path;
+}
+
+export function linkPath(styledText: string, rawPath: string, cwd: string): string {
+	if (!getCapabilities().hyperlinks) return styledText;
+	const absolutePath = resolvePath(rawPath, cwd);
+	return hyperlink(styledText, pathToFileURL(absolutePath).href);
+}
+
+export function str(value: unknown): string | null {
+	if (typeof value === "string") return value;
+	if (value == null) return "";
+	return null;
+}
+
+export function replaceTabs(text: string): string {
+	return text.replace(/\t/g, "   ");
+}
+
+export function normalizeDisplayText(text: string): string {
+	return text.replace(/\r/g, "");
+}
+
+export function getTextOutput(
+	result: { content: Array<{ type: string; text?: string; data?: string; mimeType?: string }> } | undefined,
+	showImages: boolean,
+): string {
+	if (!result) return "";
+
+	const textBlocks = result.content.filter((c) => c.type === "text");
+	const imageBlocks = result.content.filter((c) => c.type === "image");
+
+	let output = textBlocks.map((c) => sanitizeBinaryOutput(stripAnsi(c.text || "")).replace(/\r/g, "")).join("\n");
+
+	const caps = getCapabilities();
+	if (imageBlocks.length > 0 && (!caps.images || !showImages)) {
+		const imageIndicators = imageBlocks
+			.map((img) => {
+				const mimeType = img.mimeType ?? "image/unknown";
+				const dims =
+					img.data && img.mimeType ? (getImageDimensions(img.data, img.mimeType) ?? undefined) : undefined;
+				return imageFallback(mimeType, dims);
+			})
+			.join("\n");
+		output = output ? `${output}\n${imageIndicators}` : imageIndicators;
+	}
+
+	return output;
+}
+
+export type ToolRenderResultLike<TDetails> = {
+	content: (TextContent | ImageContent)[];
+	details: TDetails;
+};
+
+export function invalidArgText(theme: Theme): string {
+	return theme.fg("error", "[invalid arg]");
+}
+
+export function renderToolPath(
+	rawPath: string | null,
+	theme: Theme,
+	cwd: string,
+	options?: { emptyFallback?: string },
+): string {
+	if (rawPath === null) return invalidArgText(theme);
+	const value = rawPath || options?.emptyFallback;
+	if (!value) return theme.fg("toolOutput", "...");
+	return linkPath(theme.fg("accent", shortenPath(value)), value, cwd);
+}

packages/coding-agent/src/core/tools/renderers/bash.ts

@@ -0,0 +1,163 @@
+/**
+ * Presentation for the shell tools.
+ *
+ * Renderers live apart from the implementation so a process that only displays tool output does not
+ * load the execution path or its typebox parameter schema. `bash.ts` spreads these into the shell
+ * tool definition, so the tool's public shape is unchanged.
+ */
+
+import { Container, Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { keyHint } from "../../../modes/interactive/components/keybinding-hints.ts";
+import { truncateToVisualLines } from "../../../modes/interactive/components/visual-truncate.ts";
+import { theme } from "../../../modes/interactive/theme/theme.ts";
+import type { ToolDefinition, ToolRenderResultOptions } from "../../extensions/types.ts";
+import type { BashToolDetails } from "../bash.ts";
+import { getTextOutput, invalidArgText, str } from "../render-utils.ts";
+import { DEFAULT_MAX_BYTES, formatSize } from "../truncate.ts";
+
+const BASH_PREVIEW_LINES = 5;
+export const BASH_UPDATE_THROTTLE_MS = 100;
+type BashResultRenderState = {
+	cachedWidth: number | undefined;
+	cachedLines: string[] | undefined;
+	cachedSkipped: number | undefined;
+};
+class BashResultRenderComponent extends Container {
+	state: BashResultRenderState = {
+		cachedWidth: undefined,
+		cachedLines: undefined,
+		cachedSkipped: undefined,
+	};
+}
+function formatDuration(ms: number): string {
+	return `${(ms / 1000).toFixed(1)}s`;
+}
+function formatShellCall(args: { command?: string; timeout?: number } | undefined, prompt: string): string {
+	const command = str(args?.command);
+	const timeout = args?.timeout as number | undefined;
+	const timeoutSuffix = timeout ? theme.fg("muted", ` (timeout ${timeout}s)`) : "";
+	const commandDisplay = command === null ? invalidArgText(theme) : command ? command : theme.fg("toolOutput", "...");
+	return theme.fg("toolTitle", theme.bold(`${prompt} ${commandDisplay}`)) + timeoutSuffix;
+}
+function rebuildBashResultRenderComponent(
+	component: BashResultRenderComponent,
+	result: {
+		content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
+		details?: BashToolDetails;
+	},
+	options: ToolRenderResultOptions,
+	showImages: boolean,
+	startedAt: number | undefined,
+	endedAt: number | undefined,
+): void {
+	const state = component.state;
+	component.clear();
+
+	let output = getTextOutput(result as any, showImages).trim();
+	const truncation = result.details?.truncation;
+	const fullOutputPath = result.details?.fullOutputPath;
+	if (!options.isPartial && truncation?.truncated && fullOutputPath && output.endsWith("]")) {
+		const footerStart = output.lastIndexOf("\n\n[");
+		if (footerStart !== -1 && output.slice(footerStart).includes(fullOutputPath)) {
+			output = output.slice(0, footerStart).trimEnd();
+		}
+	}
+
+	if (output) {
+		const styledOutput = output
+			.split("\n")
+			.map((line) => theme.fg("toolOutput", line))
+			.join("\n");
+
+		if (options.expanded) {
+			component.addChild(new Text(`\n${styledOutput}`, 0, 0));
+		} else {
+			component.addChild({
+				render: (width: number) => {
+					if (state.cachedLines === undefined || state.cachedWidth !== width) {
+						const preview = truncateToVisualLines(styledOutput, BASH_PREVIEW_LINES, width);
+						state.cachedLines = preview.visualLines;
+						state.cachedSkipped = preview.skippedCount;
+						state.cachedWidth = width;
+					}
+					if (state.cachedSkipped && state.cachedSkipped > 0) {
+						const hint =
+							theme.fg("muted", `... (${state.cachedSkipped} earlier lines,`) +
+							` ${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`;
+						return ["", truncateToWidth(hint, width, "..."), ...(state.cachedLines ?? [])];
+					}
+					return ["", ...(state.cachedLines ?? [])];
+				},
+				invalidate: () => {
+					state.cachedWidth = undefined;
+					state.cachedLines = undefined;
+					state.cachedSkipped = undefined;
+				},
+			});
+		}
+	}
+
+	if (truncation?.truncated || fullOutputPath) {
+		const warnings: string[] = [];
+		if (fullOutputPath) {
+			warnings.push(`Full output: ${fullOutputPath}`);
+		}
+		if (truncation?.truncated) {
+			if (truncation.truncatedBy === "lines") {
+				warnings.push(`Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines`);
+			} else {
+				warnings.push(
+					`Truncated: ${truncation.outputLines} lines shown (${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit)`,
+				);
+			}
+		}
+		component.addChild(new Text(`\n${theme.fg("warning", `[${warnings.join(". ")}]`)}`, 0, 0));
+	}
+
+	if (startedAt !== undefined) {
+		const label = options.isPartial ? "Elapsed" : "Took";
+		const endTime = endedAt ?? Date.now();
+		component.addChild(new Text(`\n${theme.fg("muted", `${label} ${formatDuration(endTime - startedAt)}`)}`, 0, 0));
+	}
+}
+
+/** Shell renderers are shared by bash and powershell, which differ only in the prompt they display. */
+export function createShellRenderers(prompt: string): Pick<ToolDefinition<any, any>, "renderCall" | "renderResult"> {
+	return {
+		renderCall(args, _theme, context) {
+			const state = context.state;
+			if (context.executionStarted && state.startedAt === undefined) {
+				state.startedAt = Date.now();
+				state.endedAt = undefined;
+			}
+			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+			text.setText(formatShellCall(args as { command?: string; timeout?: number } | undefined, prompt));
+			return text;
+		},
+		renderResult(result, options, _theme, context) {
+			const state = context.state;
+			if (state.startedAt !== undefined && options.isPartial && !state.interval) {
+				state.interval = setInterval(() => context.invalidate(), 1000);
+			}
+			if (!options.isPartial || context.isError) {
+				state.endedAt ??= Date.now();
+				if (state.interval) {
+					clearInterval(state.interval);
+					state.interval = undefined;
+				}
+			}
+			const component =
+				(context.lastComponent as BashResultRenderComponent | undefined) ?? new BashResultRenderComponent();
+			rebuildBashResultRenderComponent(
+				component,
+				result as any,
+				options,
+				context.showImages,
+				state.startedAt,
+				state.endedAt,
+			);
+			component.invalidate();
+			return component;
+		},
+	};
+}

packages/coding-agent/src/core/tools/renderers/edit.ts

@@ -0,0 +1,238 @@
+/**
+ * Presentation for the edit tool.
+ *
+ * Renderers live apart from the implementation so a process that only displays tool output does not
+ * load the execution path or its typebox parameter schema. `edit.ts` spreads these into its
+ * definition, so the tool's public shape is unchanged.
+ */
+
+import { Box, Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { renderDiff } from "../../../modes/interactive/components/diff.ts";
+import type { Theme } from "../../../modes/interactive/theme/theme.ts";
+import type { ToolDefinition } from "../../extensions/types.ts";
+import type { EditToolDetails } from "../edit.ts";
+import { computeEditsDiff, type Edit, type EditDiffError, type EditDiffResult } from "../edit-diff.ts";
+import { renderToolPath, str } from "../render-utils.ts";
+
+type EditPreview = EditDiffResult | EditDiffError;
+export type EditRenderState = {
+	callComponent?: EditCallRenderComponent;
+};
+type RenderableEditArgs = {
+	path?: string;
+	file_path?: string;
+	edits?: Edit[];
+	oldText?: string;
+	newText?: string;
+};
+type EditToolResultLike = {
+	content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
+	details?: EditToolDetails;
+};
+type EditCallRenderComponent = Box & {
+	preview?: EditPreview;
+	previewArgsKey?: string;
+	previewPending?: boolean;
+	settledError?: boolean;
+};
+function createEditCallRenderComponent(): EditCallRenderComponent {
+	return Object.assign(new Box(1, 1, (text: string) => text), {
+		preview: undefined as EditPreview | undefined,
+		previewArgsKey: undefined as string | undefined,
+		previewPending: false,
+		settledError: false,
+	});
+}
+function getEditCallRenderComponent(state: EditRenderState, lastComponent: unknown): EditCallRenderComponent {
+	if (lastComponent instanceof Box) {
+		const component = lastComponent as EditCallRenderComponent;
+		state.callComponent = component;
+		return component;
+	}
+	if (state.callComponent) {
+		return state.callComponent;
+	}
+	const component = createEditCallRenderComponent();
+	state.callComponent = component;
+	return component;
+}
+function getRenderablePreviewInput(args: RenderableEditArgs | undefined): { path: string; edits: Edit[] } | null {
+	if (!args) {
+		return null;
+	}
+
+	const path = typeof args.path === "string" ? args.path : typeof args.file_path === "string" ? args.file_path : null;
+	if (!path) {
+		return null;
+	}
+
+	if (
+		Array.isArray(args.edits) &&
+		args.edits.length > 0 &&
+		args.edits.every((edit) => typeof edit?.oldText === "string" && typeof edit?.newText === "string")
+	) {
+		return { path, edits: args.edits };
+	}
+
+	if (typeof args.oldText === "string" && typeof args.newText === "string") {
+		return { path, edits: [{ oldText: args.oldText, newText: args.newText }] };
+	}
+
+	return null;
+}
+function formatEditCall(args: RenderableEditArgs | undefined, theme: Theme, cwd: string): string {
+	const pathDisplay = renderToolPath(str(args?.file_path ?? args?.path), theme, cwd);
+	return `${theme.fg("toolTitle", theme.bold("edit"))} ${pathDisplay}`;
+}
+function formatEditResult(
+	args: RenderableEditArgs | undefined,
+	preview: EditPreview | undefined,
+	result: EditToolResultLike,
+	theme: Theme,
+	isError: boolean,
+): string | undefined {
+	const rawPath = str(args?.file_path ?? args?.path);
+	const previewDiff = preview && !("error" in preview) ? preview.diff : undefined;
+	const previewError = preview && "error" in preview ? preview.error : undefined;
+	if (isError) {
+		const errorText = result.content
+			.filter((c) => c.type === "text")
+			.map((c) => c.text || "")
+			.join("\n");
+		if (!errorText || errorText === previewError) {
+			return undefined;
+		}
+		return theme.fg("error", errorText);
+	}
+
+	const resultDiff = result.details?.diff;
+	if (resultDiff && resultDiff !== previewDiff) {
+		return renderDiff(resultDiff, { filePath: rawPath ?? undefined });
+	}
+
+	return undefined;
+}
+function getEditHeaderBg(
+	preview: EditPreview | undefined,
+	settledError: boolean | undefined,
+	theme: Theme,
+): (text: string) => string {
+	if (preview) {
+		if ("error" in preview) {
+			return (text: string) => theme.bg("toolErrorBg", text);
+		}
+		return (text: string) => theme.bg("toolSuccessBg", text);
+	}
+	if (settledError) {
+		return (text: string) => theme.bg("toolErrorBg", text);
+	}
+	return (text: string) => theme.bg("toolPendingBg", text);
+}
+function buildEditCallComponent(
+	component: EditCallRenderComponent,
+	args: RenderableEditArgs | undefined,
+	theme: Theme,
+	cwd: string,
+): EditCallRenderComponent {
+	component.setBgFn(getEditHeaderBg(component.preview, component.settledError, theme));
+	component.clear();
+	component.addChild(new Text(formatEditCall(args, theme, cwd), 0, 0));
+
+	if (!component.preview) {
+		return component;
+	}
+
+	const body =
+		"error" in component.preview ? theme.fg("error", component.preview.error) : renderDiff(component.preview.diff);
+	component.addChild(new Spacer(1));
+	component.addChild(new Text(body, 0, 0));
+	return component;
+}
+function setEditPreview(
+	component: EditCallRenderComponent,
+	preview: EditPreview,
+	argsKey: string | undefined,
+): boolean {
+	const current = component.preview;
+	const changed =
+		current === undefined ||
+		("error" in current && "error" in preview
+			? current.error !== preview.error
+			: "error" in current !== "error" in preview) ||
+		(!("error" in current) &&
+			!("error" in preview) &&
+			(current.diff !== preview.diff || current.firstChangedLine !== preview.firstChangedLine));
+	component.preview = preview;
+	component.previewArgsKey = argsKey;
+	component.previewPending = false;
+	return changed;
+}
+
+export const editRenderers: Pick<ToolDefinition<any, any>, "renderCall" | "renderResult"> = {
+	renderCall(args, theme, context) {
+		const component = getEditCallRenderComponent(context.state, context.lastComponent);
+		const previewInput = getRenderablePreviewInput(args as RenderableEditArgs | undefined);
+		const argsKey = previewInput ? JSON.stringify({ path: previewInput.path, edits: previewInput.edits }) : undefined;
+
+		if (component.previewArgsKey !== argsKey) {
+			component.preview = undefined;
+			component.previewArgsKey = argsKey;
+			component.previewPending = false;
+			component.settledError = false;
+		}
+
+		if (context.argsComplete && previewInput && !component.preview && !component.previewPending) {
+			component.previewPending = true;
+			const requestKey = argsKey;
+			void computeEditsDiff(previewInput.path, previewInput.edits, context.cwd).then((preview) => {
+				if (component.previewArgsKey === requestKey) {
+					setEditPreview(component, preview, requestKey);
+					context.invalidate();
+				}
+			});
+		}
+
+		return buildEditCallComponent(component, args as RenderableEditArgs | undefined, theme, context.cwd);
+	},
+	renderResult(result, _options, theme, context) {
+		const callComponent = context.state.callComponent;
+		const previewInput = getRenderablePreviewInput(context.args as RenderableEditArgs | undefined);
+		const argsKey = previewInput ? JSON.stringify({ path: previewInput.path, edits: previewInput.edits }) : undefined;
+		const typedResult = result as EditToolResultLike;
+		const resultDiff = !context.isError ? typedResult.details?.diff : undefined;
+		let changed = false;
+		if (callComponent) {
+			if (typeof resultDiff === "string") {
+				changed =
+					setEditPreview(
+						callComponent,
+						{ diff: resultDiff, firstChangedLine: typedResult.details?.firstChangedLine },
+						argsKey,
+					) || changed;
+			}
+			if (callComponent.settledError !== context.isError) {
+				callComponent.settledError = context.isError;
+				changed = true;
+			}
+			if (changed) {
+				buildEditCallComponent(callComponent, context.args as RenderableEditArgs | undefined, theme, context.cwd);
+			}
+		}
+
+		const output = formatEditResult(
+			context.args as RenderableEditArgs | undefined,
+			callComponent?.preview,
+			typedResult,
+			theme,
+			context.isError,
+		);
+		const component = (context.lastComponent as Container | undefined) ?? new Container();
+		component.clear();
+		if (!output) {
+			return component;
+		}
+		component.addChild(new Spacer(1));
+		component.addChild(new Text(output, 1, 0));
+		return component;
+	},
+};

packages/coding-agent/src/core/tools/renderers/find.ts

@@ -0,0 +1,77 @@
+/**
+ * Presentation for the find tool.
+ *
+ * Renderers live apart from the implementation so a process that only displays tool output does not
+ * load the execution path or its typebox parameter schema. `find.ts` spreads these into its
+ * definition, so the tool's public shape is unchanged.
+ */
+
+import { Text } from "@earendil-works/pi-tui";
+import { keyHint } from "../../../modes/interactive/components/keybinding-hints.ts";
+import type { Theme } from "../../../modes/interactive/theme/theme.ts";
+import type { ToolDefinition, ToolRenderResultOptions } from "../../extensions/types.ts";
+import type { FindToolDetails } from "../find.ts";
+import { getTextOutput, invalidArgText, shortenPath, str } from "../render-utils.ts";
+import { DEFAULT_MAX_BYTES, formatSize } from "../truncate.ts";
+
+function formatFindCall(args: { pattern: string; path?: string; limit?: number } | undefined, theme: Theme): string {
+	const pattern = str(args?.pattern);
+	const rawPath = str(args?.path);
+	const path = rawPath !== null ? shortenPath(rawPath || ".") : null;
+	const limit = args?.limit;
+	const invalidArg = invalidArgText(theme);
+	let text =
+		theme.fg("toolTitle", theme.bold("find")) +
+		" " +
+		(pattern === null ? invalidArg : theme.fg("accent", pattern || "")) +
+		theme.fg("toolOutput", ` in ${path === null ? invalidArg : path}`);
+	if (limit !== undefined) {
+		text += theme.fg("toolOutput", ` (limit ${limit})`);
+	}
+	return text;
+}
+function formatFindResult(
+	result: {
+		content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
+		details?: FindToolDetails;
+	},
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	showImages: boolean,
+): string {
+	const output = getTextOutput(result, showImages).trim();
+	let text = "";
+	if (output) {
+		const lines = output.split("\n");
+		const maxLines = options.expanded ? lines.length : 20;
+		const displayLines = lines.slice(0, maxLines);
+		const remaining = lines.length - maxLines;
+		text += `\n${displayLines.map((line) => theme.fg("toolOutput", line)).join("\n")}`;
+		if (remaining > 0) {
+			text += `${theme.fg("muted", `\n... (${remaining} more lines,`)} ${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`;
+		}
+	}
+
+	const resultLimit = result.details?.resultLimitReached;
+	const truncation = result.details?.truncation;
+	if (resultLimit || truncation?.truncated) {
+		const warnings: string[] = [];
+		if (resultLimit) warnings.push(`${resultLimit} results limit`);
+		if (truncation?.truncated) warnings.push(`${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit`);
+		text += `\n${theme.fg("warning", `[Truncated: ${warnings.join(", ")}]`)}`;
+	}
+	return text;
+}
+
+export const findRenderers: Pick<ToolDefinition<any, any>, "renderCall" | "renderResult"> = {
+	renderCall(args, theme, context) {
+		const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+		text.setText(formatFindCall(args as any, theme));
+		return text;
+	},
+	renderResult(result, options, theme, context) {
+		const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+		text.setText(formatFindResult(result as any, options, theme, context.showImages));
+		return text;
+	},
+};

packages/coding-agent/src/core/tools/renderers/grep.ts

@@ -0,0 +1,82 @@
+/**
+ * Presentation for the grep tool.
+ *
+ * Renderers live apart from the implementation so a process that only displays tool output does not
+ * load the execution path or its typebox parameter schema. `grep.ts` spreads these into its
+ * definition, so the tool's public shape is unchanged.
+ */
+
+import { Text } from "@earendil-works/pi-tui";
+import { keyHint } from "../../../modes/interactive/components/keybinding-hints.ts";
+import type { Theme } from "../../../modes/interactive/theme/theme.ts";
+import type { ToolDefinition, ToolRenderResultOptions } from "../../extensions/types.ts";
+import type { GrepToolDetails } from "../grep.ts";
+import { getTextOutput, invalidArgText, shortenPath, str } from "../render-utils.ts";
+import { DEFAULT_MAX_BYTES, formatSize } from "../truncate.ts";
+
+function formatGrepCall(
+	args: { pattern: string; path?: string; glob?: string; limit?: number } | undefined,
+	theme: Theme,
+): string {
+	const pattern = str(args?.pattern);
+	const rawPath = str(args?.path);
+	const path = rawPath !== null ? shortenPath(rawPath || ".") : null;
+	const glob = str(args?.glob);
+	const limit = args?.limit;
+	const invalidArg = invalidArgText(theme);
+	let text =
+		theme.fg("toolTitle", theme.bold("grep")) +
+		" " +
+		(pattern === null ? invalidArg : theme.fg("accent", `/${pattern || ""}/`)) +
+		theme.fg("toolOutput", ` in ${path === null ? invalidArg : path}`);
+	if (glob) text += theme.fg("toolOutput", ` (${glob})`);
+	if (limit !== undefined) text += theme.fg("toolOutput", ` limit ${limit}`);
+	return text;
+}
+function formatGrepResult(
+	result: {
+		content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
+		details?: GrepToolDetails;
+	},
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	showImages: boolean,
+): string {
+	const output = getTextOutput(result, showImages).trim();
+	let text = "";
+	if (output) {
+		const lines = output.split("\n");
+		const maxLines = options.expanded ? lines.length : 15;
+		const displayLines = lines.slice(0, maxLines);
+		const remaining = lines.length - maxLines;
+		text += `\n${displayLines.map((line) => theme.fg("toolOutput", line)).join("\n")}`;
+		if (remaining > 0) {
+			text += `${theme.fg("muted", `\n... (${remaining} more lines,`)} ${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`;
+		}
+	}
+
+	const matchLimit = result.details?.matchLimitReached;
+	const truncation = result.details?.truncation;
+	const linesTruncated = result.details?.linesTruncated;
+	if (matchLimit || truncation?.truncated || linesTruncated) {
+		const warnings: string[] = [];
+		if (matchLimit) warnings.push(`${matchLimit} matches limit`);
+		if (truncation?.truncated) warnings.push(`${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit`);
+		if (linesTruncated) warnings.push("some lines truncated");
+		text += `\n${theme.fg("warning", `[Truncated: ${warnings.join(", ")}]`)}`;
+	}
+	return text;
+}
+
+export const grepRenderers: Pick<ToolDefinition<any, any>, "renderCall" | "renderResult"> = {
+	renderCall(args, theme, context) {
+		const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+		text.setText(formatGrepCall(args as any, theme));
+		return text;
+	},
+	renderResult(result, options, theme, context) {
+		const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+		text.setText(formatGrepResult(result as any, options, theme, context.showImages));
+		return text;
+	},
+};

packages/coding-agent/src/core/tools/renderers/index.ts

@@ -0,0 +1,63 @@
+/**
+ * Built-in tool renderers, without the tools themselves.
+ *
+ * A presentation displays tool calls and results; it does not execute them and does not need their
+ * typebox parameter schemas. Importing this instead of `core/tools/index.ts` keeps ~17 MB of module
+ * graph out of a process that only renders.
+ */
+
+import type { ToolDefinition } from "../../extensions/types.ts";
+import type { ToolName } from "../index.ts";
+import { createShellRenderers } from "./bash.ts";
+import { editRenderers } from "./edit.ts";
+import { findRenderers } from "./find.ts";
+import { grepRenderers } from "./grep.ts";
+import { lsRenderers } from "./ls.ts";
+import { readRenderers } from "./read.ts";
+import { writeRenderers } from "./write.ts";
+
+export type ToolRenderers = Pick<ToolDefinition<any, any>, "renderCall" | "renderResult">;
+
+export {
+	createShellRenderers,
+	editRenderers,
+	findRenderers,
+	grepRenderers,
+	lsRenderers,
+	readRenderers,
+	writeRenderers,
+};
+
+/** Renderers for every built-in tool, keyed by tool name. */
+export function createAllToolRenderers(): Record<ToolName, ToolRenderers> {
+	return {
+		read: readRenderers,
+		bash: createShellRenderers("$"),
+		powershell: createShellRenderers("PS>"),
+		edit: editRenderers,
+		write: writeRenderers,
+		grep: grepRenderers,
+		find: findRenderers,
+		ls: lsRenderers,
+	};
+}
+
+/**
+ * Merge built-in renderers into a tool definition that does not supply its own.
+ *
+ * `ToolExecutionComponent` used to do this lookup itself, which forced every presentation to import
+ * the tool implementations. Callers do it now, so a process that renders can import renderers alone.
+ */
+export function withBuiltInRenderers<TDefinition extends ToolRenderers>(
+	toolName: string,
+	definition: TDefinition | undefined,
+): TDefinition | ToolRenderers | undefined {
+	const builtIn = createAllToolRenderers()[toolName as ToolName];
+	if (!definition) return builtIn;
+	if (!builtIn) return definition;
+	return {
+		...definition,
+		renderCall: definition.renderCall ?? builtIn.renderCall,
+		renderResult: definition.renderResult ?? builtIn.renderResult,
+	};
+}

packages/coding-agent/src/core/tools/renderers/ls.ts

@@ -0,0 +1,70 @@
+/**
+ * Presentation for the ls tool.
+ *
+ * Renderers live apart from the implementation so a process that only displays tool output does not
+ * load the execution path or its typebox parameter schema. `ls.ts` spreads these into its
+ * definition, so the tool's public shape is unchanged.
+ */
+
+import { Text } from "@earendil-works/pi-tui";
+import { keyHint } from "../../../modes/interactive/components/keybinding-hints.ts";
+import type { Theme } from "../../../modes/interactive/theme/theme.ts";
+import type { ToolDefinition, ToolRenderResultOptions } from "../../extensions/types.ts";
+import type { LsToolDetails } from "../ls.ts";
+import { getTextOutput, renderToolPath, str } from "../render-utils.ts";
+import { DEFAULT_MAX_BYTES, formatSize } from "../truncate.ts";
+
+function formatLsCall(args: { path?: string; limit?: number } | undefined, theme: Theme, cwd: string): string {
+	const limit = args?.limit;
+	const pathDisplay = renderToolPath(str(args?.path), theme, cwd, { emptyFallback: "." });
+	let text = `${theme.fg("toolTitle", theme.bold("ls"))} ${pathDisplay}`;
+	if (limit !== undefined) {
+		text += theme.fg("toolOutput", ` (limit ${limit})`);
+	}
+	return text;
+}
+function formatLsResult(
+	result: {
+		content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>;
+		details?: LsToolDetails;
+	},
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	showImages: boolean,
+): string {
+	const output = getTextOutput(result, showImages).trim();
+	let text = "";
+	if (output) {
+		const lines = output.split("\n");
+		const maxLines = options.expanded ? lines.length : 20;
+		const displayLines = lines.slice(0, maxLines);
+		const remaining = lines.length - maxLines;
+		text += `\n${displayLines.map((line) => theme.fg("toolOutput", line)).join("\n")}`;
+		if (remaining > 0) {
+			text += `${theme.fg("muted", `\n... (${remaining} more lines,`)} ${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`;
+		}
+	}
+
+	const entryLimit = result.details?.entryLimitReached;
+	const truncation = result.details?.truncation;
+	if (entryLimit || truncation?.truncated) {
+		const warnings: string[] = [];
+		if (entryLimit) warnings.push(`${entryLimit} entries limit`);
+		if (truncation?.truncated) warnings.push(`${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit`);
+		text += `\n${theme.fg("warning", `[Truncated: ${warnings.join(", ")}]`)}`;
+	}
+	return text;
+}
+
+export const lsRenderers: Pick<ToolDefinition<any, any>, "renderCall" | "renderResult"> = {
+	renderCall(args, theme, context) {
+		const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+		text.setText(formatLsCall(args as any, theme, context.cwd));
+		return text;
+	},
+	renderResult(result, options, theme, context) {
+		const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+		text.setText(formatLsResult(result as any, options, theme, context.showImages));
+		return text;
+	},
+};

packages/coding-agent/src/core/tools/renderers/read.ts

@@ -0,0 +1,175 @@
+/**
+ * Presentation for the read tool.
+ *
+ * Renderers live apart from the implementation so a process that only displays tool output does not
+ * load the execution path or its typebox parameter schema. `read.ts` spreads these into its
+ * definition, so the tool's public shape is unchanged.
+ */
+
+import { basename, dirname, isAbsolute, relative, resolve as resolvePath, sep } from "node:path";
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import { Text } from "@earendil-works/pi-tui";
+import { getReadmePath } from "../../../config.ts";
+import { keyHint, keyText } from "../../../modes/interactive/components/keybinding-hints.ts";
+import { getLanguageFromPath, highlightCode, type Theme } from "../../../modes/interactive/theme/theme.ts";
+import { formatPathRelativeToCwdOrAbsolute } from "../../../utils/paths.ts";
+import type { ToolDefinition, ToolRenderResultOptions } from "../../extensions/types.ts";
+import { resolveToCwd } from "../path-utils.ts";
+import type { ReadToolDetails } from "../read.ts";
+import { getTextOutput, renderToolPath, replaceTabs, str } from "../render-utils.ts";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "../truncate.ts";
+
+interface CompactReadClassification {
+	kind: "docs" | "resource" | "skill";
+	label: string;
+}
+const COMPACT_RESOURCE_FILE_NAMES = new Set(["AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"]);
+type ReadRenderArgs = { path?: string; file_path?: string; offset?: number; limit?: number };
+function formatReadLineRange(args: ReadRenderArgs | undefined, theme: Theme): string {
+	if (args?.offset === undefined && args?.limit === undefined) return "";
+	const startLine = args.offset ?? 1;
+	const endLine = args.limit !== undefined ? startLine + args.limit - 1 : "";
+	return theme.fg("warning", `:${startLine}${endLine ? `-${endLine}` : ""}`);
+}
+function formatReadCall(args: ReadRenderArgs | undefined, theme: Theme, cwd: string): string {
+	const pathDisplay = renderToolPath(str(args?.file_path ?? args?.path), theme, cwd);
+	return `${theme.fg("toolTitle", theme.bold("read"))} ${pathDisplay}${formatReadLineRange(args, theme)}`;
+}
+function trimTrailingEmptyLines(lines: string[]): string[] {
+	let end = lines.length;
+	while (end > 0 && lines[end - 1] === "") {
+		end--;
+	}
+	return lines.slice(0, end);
+}
+function toPosixPath(filePath: string): string {
+	return filePath.split(sep).join("/");
+}
+function getPiDocsClassification(absolutePath: string): CompactReadClassification | undefined {
+	const packageRoot = dirname(getReadmePath());
+	const relativePath = relative(resolvePath(packageRoot), resolvePath(absolutePath));
+	if (
+		relativePath === "" ||
+		relativePath === ".." ||
+		relativePath.startsWith(`..${sep}`) ||
+		isAbsolute(relativePath)
+	) {
+		return undefined;
+	}
+
+	const label = toPosixPath(relativePath);
+	if (label === "README.md" || label.startsWith("docs/") || label.startsWith("examples/")) {
+		return { kind: "docs", label };
+	}
+	return undefined;
+}
+function getCompactReadClassification(
+	args: ReadRenderArgs | undefined,
+	cwd: string,
+): CompactReadClassification | undefined {
+	const rawPath = str(args?.file_path ?? args?.path);
+	if (!rawPath) return undefined;
+
+	const absolutePath = resolveToCwd(rawPath, cwd);
+	const fileName = basename(absolutePath);
+	if (fileName === "SKILL.md") {
+		return { kind: "skill", label: basename(dirname(absolutePath)) || fileName };
+	}
+
+	const docsClassification = getPiDocsClassification(absolutePath);
+	if (docsClassification) return docsClassification;
+
+	if (COMPACT_RESOURCE_FILE_NAMES.has(fileName)) {
+		return { kind: "resource", label: formatPathRelativeToCwdOrAbsolute(absolutePath, cwd) };
+	}
+
+	return undefined;
+}
+function formatCompactReadCall(
+	classification: CompactReadClassification,
+	args: ReadRenderArgs | undefined,
+	theme: Theme,
+): string {
+	const expandHint = theme.fg("dim", ` (${keyText("app.tools.expand")} to expand)`);
+	if (classification.kind === "skill") {
+		return (
+			theme.fg("customMessageLabel", `\x1b[1m[skill]\x1b[22m `) +
+			theme.fg("customMessageText", classification.label) +
+			formatReadLineRange(args, theme) +
+			expandHint
+		);
+	}
+
+	return (
+		theme.fg("toolTitle", theme.bold(`read ${classification.kind}`)) +
+		" " +
+		theme.fg("accent", classification.label) +
+		formatReadLineRange(args, theme) +
+		expandHint
+	);
+}
+function formatReadResult(
+	args: ReadRenderArgs | undefined,
+	result: { content: (TextContent | ImageContent)[]; details?: ReadToolDetails },
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	showImages: boolean,
+	_cwd: string,
+	isError: boolean,
+): string {
+	if (!options.expanded && !isError) {
+		return "";
+	}
+
+	const rawPath = str(args?.file_path ?? args?.path);
+	const output = getTextOutput(result, showImages);
+	const lang = !isError && rawPath ? getLanguageFromPath(rawPath) : undefined;
+	const renderedLines = lang ? highlightCode(replaceTabs(output), lang) : output.split("\n");
+	const lines = trimTrailingEmptyLines(renderedLines);
+	const maxLines = options.expanded ? lines.length : 10;
+	const displayLines = lines.slice(0, maxLines);
+	const remaining = lines.length - maxLines;
+	let text = `\n${displayLines.map((line) => (lang ? replaceTabs(line) : theme.fg("toolOutput", replaceTabs(line)))).join("\n")}`;
+	if (remaining > 0) {
+		text += `${theme.fg("muted", `\n... (${remaining} more lines,`)} ${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`;
+	}
+
+	const truncation = result.details?.truncation;
+	if (truncation?.truncated) {
+		if (truncation.firstLineExceedsLimit) {
+			text += `\n${theme.fg("warning", `[First line exceeds ${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit]`)}`;
+		} else if (truncation.truncatedBy === "lines") {
+			text += `\n${theme.fg("warning", `[Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${truncation.maxLines ?? DEFAULT_MAX_LINES} line limit)]`)}`;
+		} else {
+			text += `\n${theme.fg("warning", `[Truncated: ${truncation.outputLines} lines shown (${formatSize(truncation.maxBytes ?? DEFAULT_MAX_BYTES)} limit)]`)}`;
+		}
+	}
+	return text;
+}
+
+export const readRenderers: Pick<ToolDefinition<any, ReadToolDetails | undefined>, "renderCall" | "renderResult"> = {
+	renderCall(rawArgs, theme, context) {
+		const args = rawArgs as ReadRenderArgs | undefined;
+		const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+		const classification = !context.expanded ? getCompactReadClassification(args, context.cwd) : undefined;
+		text.setText(
+			classification ? formatCompactReadCall(classification, args, theme) : formatReadCall(args, theme, context.cwd),
+		);
+		return text;
+	},
+	renderResult(result, options, theme, context) {
+		const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+		text.setText(
+			formatReadResult(
+				context.args as ReadRenderArgs | undefined,
+				result,
+				options,
+				theme,
+				context.showImages,
+				context.cwd,
+				context.isError,
+			),
+		);
+		return text;
+	},
+};

packages/coding-agent/src/core/tools/renderers/write.ts

@@ -0,0 +1,181 @@
+/**
+ * Presentation for the write tool.
+ *
+ * Renderers live apart from the implementation so a process that only displays tool output does not
+ * load the execution path or its typebox parameter schema. `write.ts` spreads these into its
+ * definition, so the tool's public shape is unchanged.
+ */
+
+import { Container, Text } from "@earendil-works/pi-tui";
+import { keyHint } from "../../../modes/interactive/components/keybinding-hints.ts";
+import { getLanguageFromPath, highlightCode, type Theme } from "../../../modes/interactive/theme/theme.ts";
+import type { ToolDefinition, ToolRenderResultOptions } from "../../extensions/types.ts";
+import { normalizeDisplayText, renderToolPath, replaceTabs, str } from "../render-utils.ts";
+
+type WriteHighlightCache = {
+	rawPath: string | null;
+	lang: string;
+	rawContent: string;
+	normalizedLines: string[];
+	highlightedLines: string[];
+};
+class WriteCallRenderComponent extends Text {
+	cache?: WriteHighlightCache;
+
+	constructor() {
+		super("", 0, 0);
+	}
+}
+const WRITE_PARTIAL_FULL_HIGHLIGHT_LINES = 50;
+function highlightSingleLine(line: string, lang: string): string {
+	const highlighted = highlightCode(line, lang);
+	return highlighted[0] ?? "";
+}
+function refreshWriteHighlightPrefix(cache: WriteHighlightCache): void {
+	const prefixCount = Math.min(WRITE_PARTIAL_FULL_HIGHLIGHT_LINES, cache.normalizedLines.length);
+	if (prefixCount === 0) return;
+	const prefixSource = cache.normalizedLines.slice(0, prefixCount).join("\n");
+	const prefixHighlighted = highlightCode(prefixSource, cache.lang);
+	for (let i = 0; i < prefixCount; i++) {
+		cache.highlightedLines[i] =
+			prefixHighlighted[i] ?? highlightSingleLine(cache.normalizedLines[i] ?? "", cache.lang);
+	}
+}
+function rebuildWriteHighlightCacheFull(rawPath: string | null, fileContent: string): WriteHighlightCache | undefined {
+	const lang = rawPath ? getLanguageFromPath(rawPath) : undefined;
+	if (!lang) return undefined;
+	const displayContent = normalizeDisplayText(fileContent);
+	const normalized = replaceTabs(displayContent);
+	return {
+		rawPath,
+		lang,
+		rawContent: fileContent,
+		normalizedLines: normalized.split("\n"),
+		highlightedLines: highlightCode(normalized, lang),
+	};
+}
+function updateWriteHighlightCacheIncremental(
+	cache: WriteHighlightCache | undefined,
+	rawPath: string | null,
+	fileContent: string,
+): WriteHighlightCache | undefined {
+	const lang = rawPath ? getLanguageFromPath(rawPath) : undefined;
+	if (!lang) return undefined;
+	if (!cache) return rebuildWriteHighlightCacheFull(rawPath, fileContent);
+	if (cache.lang !== lang || cache.rawPath !== rawPath) return rebuildWriteHighlightCacheFull(rawPath, fileContent);
+	if (!fileContent.startsWith(cache.rawContent)) return rebuildWriteHighlightCacheFull(rawPath, fileContent);
+	if (fileContent.length === cache.rawContent.length) return cache;
+
+	const deltaRaw = fileContent.slice(cache.rawContent.length);
+	const deltaDisplay = normalizeDisplayText(deltaRaw);
+	const deltaNormalized = replaceTabs(deltaDisplay);
+	cache.rawContent = fileContent;
+	if (cache.normalizedLines.length === 0) {
+		cache.normalizedLines.push("");
+		cache.highlightedLines.push("");
+	}
+
+	const segments = deltaNormalized.split("\n");
+	const lastIndex = cache.normalizedLines.length - 1;
+	cache.normalizedLines[lastIndex] += segments[0];
+	cache.highlightedLines[lastIndex] = highlightSingleLine(cache.normalizedLines[lastIndex], cache.lang);
+	for (let i = 1; i < segments.length; i++) {
+		cache.normalizedLines.push(segments[i]);
+		cache.highlightedLines.push(highlightSingleLine(segments[i], cache.lang));
+	}
+	refreshWriteHighlightPrefix(cache);
+	return cache;
+}
+function trimTrailingEmptyLines(lines: string[]): string[] {
+	let end = lines.length;
+	while (end > 0 && lines[end - 1] === "") {
+		end--;
+	}
+	return lines.slice(0, end);
+}
+function formatWriteCall(
+	args: { path?: string; file_path?: string; content?: string } | undefined,
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	cache: WriteHighlightCache | undefined,
+	cwd: string,
+): string {
+	const rawPath = str(args?.file_path ?? args?.path);
+	const fileContent = str(args?.content);
+	const pathDisplay = renderToolPath(rawPath, theme, cwd);
+	let text = `${theme.fg("toolTitle", theme.bold("write"))} ${pathDisplay}`;
+
+	if (fileContent === null) {
+		text += `\n\n${theme.fg("error", "[invalid content arg - expected string]")}`;
+	} else if (fileContent) {
+		const lang = rawPath ? getLanguageFromPath(rawPath) : undefined;
+		const renderedLines = lang
+			? (cache?.highlightedLines ?? highlightCode(replaceTabs(normalizeDisplayText(fileContent)), lang))
+			: normalizeDisplayText(fileContent).split("\n");
+		const lines = trimTrailingEmptyLines(renderedLines);
+		const totalLines = lines.length;
+		const maxLines = options.expanded ? lines.length : 10;
+		const displayLines = lines.slice(0, maxLines);
+		const remaining = lines.length - maxLines;
+		text += `\n\n${displayLines.map((line) => (lang ? line : theme.fg("toolOutput", replaceTabs(line)))).join("\n")}`;
+		if (remaining > 0) {
+			text += `${theme.fg("muted", `\n... (${remaining} more lines, ${totalLines} total,`)} ${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`;
+		}
+	}
+
+	return text;
+}
+function formatWriteResult(
+	result: { content: Array<{ type: string; text?: string; data?: string; mimeType?: string }>; isError?: boolean },
+	theme: Theme,
+): string | undefined {
+	if (!result.isError) {
+		return undefined;
+	}
+	const output = result.content
+		.filter((c) => c.type === "text")
+		.map((c) => c.text || "")
+		.join("\n");
+	if (!output) {
+		return undefined;
+	}
+	return `\n${theme.fg("error", output)}`;
+}
+
+export const writeRenderers: Pick<ToolDefinition<any, any>, "renderCall" | "renderResult"> = {
+	renderCall(args, theme, context) {
+		const renderArgs = args as { path?: string; file_path?: string; content?: string } | undefined;
+		const rawPath = str(renderArgs?.file_path ?? renderArgs?.path);
+		const fileContent = str(renderArgs?.content);
+		const component =
+			(context.lastComponent as WriteCallRenderComponent | undefined) ?? new WriteCallRenderComponent();
+		if (fileContent !== null) {
+			component.cache = context.argsComplete
+				? rebuildWriteHighlightCacheFull(rawPath, fileContent)
+				: updateWriteHighlightCacheIncremental(component.cache, rawPath, fileContent);
+		} else {
+			component.cache = undefined;
+		}
+		component.setText(
+			formatWriteCall(
+				renderArgs,
+				{ expanded: context.expanded, isPartial: context.isPartial },
+				theme,
+				component.cache,
+				context.cwd,
+			),
+		);
+		return component;
+	},
+	renderResult(result, _options, theme, context) {
+		const output = formatWriteResult({ ...result, isError: context.isError }, theme);
+		if (!output) {
+			const component = (context.lastComponent as Container | undefined) ?? new Container();
+			component.clear();
+			return component;
+		}
+		const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+		text.setText(output);
+		return text;
+	},
+};

packages/coding-agent/src/core/tools/tool-definition-wrapper.ts

@@ -0,0 +1,47 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import type { ExtensionContext, ToolDefinition } from "../extensions/types.ts";
+
+/** Wrap a ToolDefinition into an AgentTool for the core runtime. */
+export function wrapToolDefinition<TDetails = unknown>(
+	definition: ToolDefinition<any, TDetails>,
+	ctxFactory?: () => ExtensionContext,
+): AgentTool<any, TDetails> {
+	return {
+		name: definition.name,
+		label: definition.label,
+		description: definition.description,
+		parameters: definition.parameters,
+		constrainedSampling: definition.constrainedSampling,
+		prepareArguments: definition.prepareArguments,
+		executionMode: definition.executionMode,
+		execute: (toolCallId, params, signal, onUpdate, ctx?: ExtensionContext) =>
+			definition.execute(toolCallId, params, signal, onUpdate, ctx ?? (ctxFactory?.() as ExtensionContext)),
+	};
+}
+
+/** Wrap multiple ToolDefinitions into AgentTools for the core runtime. */
+export function wrapToolDefinitions(
+	definitions: ToolDefinition<any, any>[],
+	ctxFactory?: () => ExtensionContext,
+): AgentTool<any>[] {
+	return definitions.map((definition) => wrapToolDefinition(definition, ctxFactory));
+}
+
+/**
+ * Synthesize a minimal ToolDefinition from an AgentTool.
+ *
+ * This keeps AgentSession's internal registry definition-first even when a caller
+ * provides plain AgentTool overrides that do not include prompt metadata or renderers.
+ */
+export function createToolDefinitionFromAgentTool(tool: AgentTool<any>): ToolDefinition<any, unknown> {
+	return {
+		name: tool.name,
+		label: tool.label,
+		description: tool.description,
+		parameters: tool.parameters as any,
+		constrainedSampling: tool.constrainedSampling,
+		prepareArguments: tool.prepareArguments,
+		executionMode: tool.executionMode,
+		execute: async (toolCallId, params, signal, onUpdate) => tool.execute(toolCallId, params, signal, onUpdate),
+	};
+}

packages/coding-agent/src/core/tools/truncate.ts

@@ -0,0 +1,276 @@
+/**
+ * Shared truncation utilities for tool outputs.
+ *
+ * Truncation is based on two independent limits - whichever is hit first wins:
+ * - Line limit (default: 2000 lines)
+ * - Byte limit (default: 50KB)
+ *
+ * Never returns partial lines (except bash tail truncation edge case).
+ */
+
+export const DEFAULT_MAX_LINES = 2000;
+export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB
+export const GREP_MAX_LINE_LENGTH = 500; // Max chars per grep match line
+
+export interface TruncationResult {
+	/** The truncated content */
+	content: string;
+	/** Whether truncation occurred */
+	truncated: boolean;
+	/** Which limit was hit: "lines", "bytes", or null if not truncated */
+	truncatedBy: "lines" | "bytes" | null;
+	/** Total number of lines in the original content */
+	totalLines: number;
+	/** Total number of bytes in the original content */
+	totalBytes: number;
+	/** Number of complete lines in the truncated output */
+	outputLines: number;
+	/** Number of bytes in the truncated output */
+	outputBytes: number;
+	/** Whether the last line was partially truncated (only for tail truncation edge case) */
+	lastLinePartial: boolean;
+	/** Whether the first line exceeded the byte limit (for head truncation) */
+	firstLineExceedsLimit: boolean;
+	/** The max lines limit that was applied */
+	maxLines: number;
+	/** The max bytes limit that was applied */
+	maxBytes: number;
+}
+
+export interface TruncationOptions {
+	/** Maximum number of lines (default: 2000) */
+	maxLines?: number;
+	/** Maximum number of bytes (default: 50KB) */
+	maxBytes?: number;
+}
+
+function splitLinesForCounting(content: string): string[] {
+	if (content.length === 0) {
+		return [];
+	}
+	const lines = content.split("\n");
+	if (content.endsWith("\n")) {
+		lines.pop();
+	}
+	return lines;
+}
+
+/**
+ * Format bytes as human-readable size.
+ */
+export function formatSize(bytes: number): string {
+	if (bytes < 1024) {
+		return `${bytes}B`;
+	} else if (bytes < 1024 * 1024) {
+		return `${(bytes / 1024).toFixed(1)}KB`;
+	} else {
+		return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+	}
+}
+
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Suitable for file reads where you want to see the beginning.
+ *
+ * Never returns partial lines. If first line exceeds byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ */
+export function truncateHead(content: string, options: TruncationOptions = {}): TruncationResult {
+	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+
+	const totalBytes = Buffer.byteLength(content, "utf-8");
+	const lines = splitLinesForCounting(content);
+	const totalLines = lines.length;
+
+	// Check if no truncation needed
+	if (totalLines <= maxLines && totalBytes <= maxBytes) {
+		return {
+			content,
+			truncated: false,
+			truncatedBy: null,
+			totalLines,
+			totalBytes,
+			outputLines: totalLines,
+			outputBytes: totalBytes,
+			lastLinePartial: false,
+			firstLineExceedsLimit: false,
+			maxLines,
+			maxBytes,
+		};
+	}
+
+	// Check if first line alone exceeds byte limit
+	const firstLineBytes = Buffer.byteLength(lines[0], "utf-8");
+	if (firstLineBytes > maxBytes) {
+		return {
+			content: "",
+			truncated: true,
+			truncatedBy: "bytes",
+			totalLines,
+			totalBytes,
+			outputLines: 0,
+			outputBytes: 0,
+			lastLinePartial: false,
+			firstLineExceedsLimit: true,
+			maxLines,
+			maxBytes,
+		};
+	}
+
+	// Collect complete lines that fit
+	const outputLinesArr: string[] = [];
+	let outputBytesCount = 0;
+	let truncatedBy: "lines" | "bytes" = "lines";
+
+	for (let i = 0; i < lines.length && i < maxLines; i++) {
+		const line = lines[i];
+		const lineBytes = Buffer.byteLength(line, "utf-8") + (i > 0 ? 1 : 0); // +1 for newline
+
+		if (outputBytesCount + lineBytes > maxBytes) {
+			truncatedBy = "bytes";
+			break;
+		}
+
+		outputLinesArr.push(line);
+		outputBytesCount += lineBytes;
+	}
+
+	// If we exited due to line limit
+	if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+		truncatedBy = "lines";
+	}
+
+	const outputContent = outputLinesArr.join("\n");
+	const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+
+	return {
+		content: outputContent,
+		truncated: true,
+		truncatedBy,
+		totalLines,
+		totalBytes,
+		outputLines: outputLinesArr.length,
+		outputBytes: finalOutputBytes,
+		lastLinePartial: false,
+		firstLineExceedsLimit: false,
+		maxLines,
+		maxBytes,
+	};
+}
+
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * Suitable for bash output where you want to see the end (errors, final results).
+ *
+ * May return partial first line if the last line of original content exceeds byte limit.
+ */
+export function truncateTail(content: string, options: TruncationOptions = {}): TruncationResult {
+	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+
+	const totalBytes = Buffer.byteLength(content, "utf-8");
+	const lines = splitLinesForCounting(content);
+	const totalLines = lines.length;
+
+	// Check if no truncation needed
+	if (totalLines <= maxLines && totalBytes <= maxBytes) {
+		return {
+			content,
+			truncated: false,
+			truncatedBy: null,
+			totalLines,
+			totalBytes,
+			outputLines: totalLines,
+			outputBytes: totalBytes,
+			lastLinePartial: false,
+			firstLineExceedsLimit: false,
+			maxLines,
+			maxBytes,
+		};
+	}
+
+	// Work backwards from the end
+	const outputLinesArr: string[] = [];
+	let outputBytesCount = 0;
+	let truncatedBy: "lines" | "bytes" = "lines";
+	let lastLinePartial = false;
+
+	for (let i = lines.length - 1; i >= 0 && outputLinesArr.length < maxLines; i--) {
+		const line = lines[i];
+		const lineBytes = Buffer.byteLength(line, "utf-8") + (outputLinesArr.length > 0 ? 1 : 0); // +1 for newline
+
+		if (outputBytesCount + lineBytes > maxBytes) {
+			truncatedBy = "bytes";
+			// Edge case: if we haven't added ANY lines yet and this line exceeds maxBytes,
+			// take the end of the line (partial)
+			if (outputLinesArr.length === 0) {
+				const truncatedLine = truncateStringToBytesFromEnd(line, maxBytes);
+				outputLinesArr.unshift(truncatedLine);
+				outputBytesCount = Buffer.byteLength(truncatedLine, "utf-8");
+				lastLinePartial = true;
+			}
+			break;
+		}
+
+		outputLinesArr.unshift(line);
+		outputBytesCount += lineBytes;
+	}
+
+	// If we exited due to line limit
+	if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+		truncatedBy = "lines";
+	}
+
+	const outputContent = outputLinesArr.join("\n");
+	const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+
+	return {
+		content: outputContent,
+		truncated: true,
+		truncatedBy,
+		totalLines,
+		totalBytes,
+		outputLines: outputLinesArr.length,
+		outputBytes: finalOutputBytes,
+		lastLinePartial,
+		firstLineExceedsLimit: false,
+		maxLines,
+		maxBytes,
+	};
+}
+
+/**
+ * Truncate a string to fit within a byte limit (from the end).
+ * Handles multi-byte UTF-8 characters correctly.
+ */
+function truncateStringToBytesFromEnd(str: string, maxBytes: number): string {
+	const buf = Buffer.from(str, "utf-8");
+	if (buf.length <= maxBytes) {
+		return str;
+	}
+
+	// Start from the end, skip maxBytes back
+	let start = buf.length - maxBytes;
+
+	// Find a valid UTF-8 boundary (start of a character)
+	while (start < buf.length && (buf[start] & 0xc0) === 0x80) {
+		start++;
+	}
+
+	return buf.slice(start).toString("utf-8");
+}
+
+/**
+ * Truncate a single line to max characters, adding [truncated] suffix.
+ * Used for grep match lines.
+ */
+export function truncateLine(
+	line: string,
+	maxChars: number = GREP_MAX_LINE_LENGTH,
+): { text: string; wasTruncated: boolean } {
+	if (line.length <= maxChars) {
+		return { text: line, wasTruncated: false };
+	}
+	return { text: `${line.slice(0, maxChars)}... [truncated]`, wasTruncated: true };
+}

packages/coding-agent/src/core/tools/write.ts

@@ -0,0 +1,97 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import { mkdir as fsMkdir, writeFile as fsWriteFile } from "fs/promises";
+import { dirname } from "path";
+import { type Static, Type } from "typebox";
+import type { ExtensionContext, ToolDefinition } from "../extensions/types.ts";
+import { withFileMutationQueue } from "./file-mutation-queue.ts";
+import { resolveToCwd } from "./path-utils.ts";
+import { writeRenderers } from "./renderers/write.ts";
+import { wrapToolDefinition } from "./tool-definition-wrapper.ts";
+
+const writeSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to write (relative or absolute)" }),
+	content: Type.String({ description: "Content to write to the file" }),
+});
+
+export const writeToolSystemPromptContribution = {
+	snippet: "Create or overwrite files",
+	guidelines: ["Use write only for new files or complete rewrites."],
+} as const;
+
+export type WriteToolInput = Static<typeof writeSchema>;
+
+/**
+ * Pluggable operations for the write tool.
+ * Override these to delegate file writing to remote systems (for example SSH).
+ */
+export interface WriteOperations {
+	/** Write content to a file */
+	writeFile: (absolutePath: string, content: string) => Promise<void>;
+	/** Create directory recursively */
+	mkdir: (dir: string) => Promise<void>;
+}
+
+const defaultWriteOperations: WriteOperations = {
+	writeFile: (path, content) => fsWriteFile(path, content, "utf-8"),
+	mkdir: (dir) => fsMkdir(dir, { recursive: true }).then(() => {}),
+};
+
+export interface WriteToolOptions {
+	/** Custom operations for file writing. Default: local filesystem */
+	operations?: WriteOperations;
+}
+
+export function createWriteToolDefinition(
+	cwd: string,
+	options?: WriteToolOptions,
+): ToolDefinition<typeof writeSchema, undefined> {
+	const ops = options?.operations ?? defaultWriteOperations;
+	return {
+		name: "write",
+		label: "write",
+		description:
+			"Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+		promptSnippet: writeToolSystemPromptContribution.snippet,
+		promptGuidelines: [...writeToolSystemPromptContribution.guidelines],
+		parameters: writeSchema,
+		constrainedSampling: { type: "json_schema", strict: "prefer" },
+		async execute(
+			_toolCallId,
+			{ path, content }: { path: string; content: string },
+			signal?: AbortSignal,
+			_onUpdate?,
+			ctx?: ExtensionContext,
+		) {
+			const absolutePath = resolveToCwd(path, ctx?.cwd || cwd);
+			const dir = dirname(absolutePath);
+			return withFileMutationQueue(absolutePath, async () => {
+				// Do not reject from an abort event listener here: that would release the
+				// mutation queue while an in-flight filesystem operation may still finish.
+				// Checking signal.aborted after each await observes the same aborts while
+				// keeping the queue locked until the current operation has settled.
+				const throwIfAborted = (): void => {
+					if (signal?.aborted) throw new Error("Operation aborted");
+				};
+
+				throwIfAborted();
+				// Create parent directories if needed.
+				await ops.mkdir(dir);
+				throwIfAborted();
+
+				// Write the file contents.
+				await ops.writeFile(absolutePath, content);
+				throwIfAborted();
+
+				return {
+					content: [{ type: "text", text: `Successfully wrote to ${path}` }],
+					details: undefined,
+				};
+			});
+		},
+		...writeRenderers,
+	};
+}
+
+export function createWriteTool(cwd: string, options?: WriteToolOptions): AgentTool<typeof writeSchema> {
+	return wrapToolDefinition(createWriteToolDefinition(cwd, options));
+}

packages/coding-agent/src/experimental/mini/README.md

@@ -0,0 +1,107 @@
+# mini
+
+A minimal coding agent on the durable `AgentHarness`, split across three processes that talk JSON
+over a socket and a pipe. It exists to exercise the harness from a real client and to find out what
+an RPC-shaped presentation actually needs from it.
+
+```bash
+node packages/coding-agent/src/experimental/mini/main.ts [--continue]
+
+# while the harness is changing under us, run from source instead of built dist:
+./node_modules/.bin/tsx --tsconfig tsconfig.json packages/coding-agent/src/experimental/mini/main.ts
+```
+
+`--continue` attaches to the newest session for the current directory. Starting `mini` twice attaches
+two presentations to the same session; both see the same transcript, live.
+
+## Topology
+
+```text
+tui        tui        tui          presentations: render, no agent state
+  \         |         /
+   \        |        /             unix socket, ~/.pi/agent/experimental/mini.sock
+    \       |       /
+        server                     routes calls, fans out events, spawns workers
+       /        \
+      /          \                 child process stdio pipes
+  worker       worker              one per session: harness, storage, model runtime
+```
+
+A presentation holds one connection and reaches every service through it. The server answers
+`sessions` itself and forwards anything else to the worker that connection is attached to, so the TUI
+never learns which host answers what. The same rule runs backwards: a worker calling `sessions.list`
+is answered by the server.
+
+The first `mini` to start spawns the server detached. The server kills a worker when its last
+presentation disconnects, and retires itself ten seconds after the last presentation leaves, so the
+next start always runs current code. If that worker held an open durable operation, its replacement
+automatically resumes the operation from the last recorded recovery state.
+
+## Layout
+
+| path | role |
+| --- | --- |
+| `main.ts` | the `mini` command |
+| `shared/transport.ts` | `Connection`: newline-delimited JSON over any duplex pair |
+| `shared/rpc.ts` | frames, named services, routing, liveness, cancellation |
+| `shared/protocol.ts` | service tokens, contracts, wire types |
+| `server/run.ts` | routes, worker supervision, event fan-out |
+| `worker/run.ts` | opens the session, builds the harness, provides services |
+| `worker/lane-service.ts` | `Lane`: watch subscriptions and lane commands |
+| `worker/models-service.ts` | `Models`: catalog, accounts, interactive login |
+| `tui/run.ts` | presentation host: ensure server, attach, run the view |
+| `tui/session.ts` | attach, subscribe, hold the replicated snapshot |
+| `tui/view.ts` | alt-screen rendering, reusing interactive-mode components |
+
+## RPC
+
+Two verbs. **Call** asks a question and gets one answer; **emit** publishes to whoever listens. Both
+directions on every connection.
+
+```ts
+const peer = createPeer(connection, { forward });   // forward handles names this peer lacks
+peer.provide(Lane, laneService);                    // register and announce
+const lane = peer.use(Lane);                        // Remote<LaneServiceApi>
+await lane.prompt("hi");                            // -> { kind: "call", id, method: "lane.prompt" }
+peer.on(Lane, (event) => fold(event));              // typed by the token
+```
+
+The wire is six frame kinds: `call`, `result`, `error`, `cancel`, `event`, `announce`, `ping`.
+Replies correlate by `id` and resolve one promise; events carry a service name and no id, so the two
+never interfere — a five-minute `lane.prompt` sits pending while its stream of events flows past.
+
+Services are plain objects registered under a token, and a token carries the name plus the call and
+event types, so `provide` checks the implementation and `use` checks the caller. Names are announced
+on registration, so routing is a lookup and an unroutable call fails with both inventories named.
+
+Failure handling: a closed connection rejects every pending call and aborts every in-flight handler;
+peers ping every five seconds and declare a silent line dead after fifteen, which catches a wedged
+process that never closes; callers may pass a `signal` (sends `cancel`) or a `timeoutMs`. Timeouts
+are opt-in per call site, because an agent turn has no bounded duration.
+
+## State replication
+
+The worker holds every live object. A presentation holds a `LaneSnapshot` and nothing else.
+
+Each presentation gets **its own** `lane.watch()` in the worker, in the harness's two phases:
+`watch()` captures a snapshot while the harness buffers that subscription's events, and `start()`
+drains them. Because the harness pairs snapshot and stream with no gap and no duplicate, the client
+needs no buffering or ordering logic of its own — it applies events with the harness's own
+`reduceLaneSnapshot`. When the fold answers `{ rebase: true }`, which a completed navigation does, the
+presentation takes a fresh subscription and drops the old one. First attach and rebase are the same
+function.
+
+Rendering is a pure function of that snapshot. Transcript entries are keyed by id and appended, so a
+streamed token costs one markdown rebuild rather than a repaint; the view repaints wholesale only
+when the entry-id prefix diverges, which is what compaction and navigation do.
+
+## What it is not
+
+No slash-command system, extensions, skills, hooks, themes beyond the shared one, session picker, or
+tree navigation. Interactive login and model selection exist because they proved the awkward
+directions of the protocol: server-to-client requests, and identity-based configuration.
+
+Two known shortcuts: the server broadcasts a worker's events to every attached presentation, so with
+N presentations each event crosses N² times and each client discards the copies that are not its own;
+and cancelling an interactive login only interrupts at a prompt, since the worker's login has no
+abort path yet.

packages/coding-agent/src/experimental/mini/main.ts

@@ -0,0 +1,24 @@
+/**
+ * The `mini` command. Runs the presentation host.
+ *
+ * Run: node packages/coding-agent/src/experimental/mini/main.ts [--continue]
+ */
+
+import { runTui, type TuiOptions } from "./tui/run.ts";
+
+function parseArgs(argv: readonly string[]): TuiOptions {
+	const options: TuiOptions = {};
+	for (const arg of argv) {
+		if (arg === "--continue" || arg === "-c") options.continueSession = true;
+		else throw new Error(`Unknown argument: ${arg}`);
+	}
+	return options;
+}
+
+runTui(parseArgs(process.argv.slice(2))).then(
+	() => process.exit(0),
+	(error: unknown) => {
+		console.error(error);
+		process.exit(1);
+	},
+);

packages/coding-agent/src/experimental/mini/server/entry.ts

@@ -0,0 +1,12 @@
+/** Server process entry: `node server/entry.ts <socketPath> <sessionsRoot>`. Spawned detached by the CLI. */
+
+import { socketTransport } from "../shared/transport.ts";
+import { runServer } from "./run.ts";
+
+const [socketPath, sessionsRoot] = process.argv.slice(2);
+if (!socketPath || !sessionsRoot) throw new Error("Server requires <socketPath> <sessionsRoot>");
+
+void runServer({ transport: socketTransport(socketPath), sessionsRoot }).catch((error: unknown) => {
+	console.error(error);
+	process.exit(1);
+});

packages/coding-agent/src/experimental/mini/server/run.ts

@@ -0,0 +1,160 @@
+/**
+ * Session server: accepts client connections, spawns one worker process per session, routes.
+ *
+ * It provides `Sessions` and holds no agent state. Any other service name is forwarded to the worker
+ * the calling client is attached to, and every worker event is pushed back to that worker's clients.
+ * Workers reach `Sessions` over the same peer, because the routing rule is symmetric.
+ */
+
+import { spawn } from "node:child_process";
+import { extname } from "node:path";
+import { fileURLToPath } from "node:url";
+// Narrow entries: the server routes and lists sessions, it never runs an agent.
+import { BACKGROUND_CONTEXT } from "@earendil-works/pi-agent-core/harness/context";
+import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/harness/env/nodejs";
+import { JsonlSessionRepo } from "@earendil-works/pi-agent-core/harness/session";
+import { type SessionSummary, Sessions, type SessionsServiceApi, Worker } from "../shared/protocol.ts";
+import { createPeer, type RpcPeer } from "../shared/rpc.ts";
+import { childConnection, type Transport } from "../shared/transport.ts";
+
+const SELF_EXTENSION = extname(fileURLToPath(import.meta.url));
+const WORKER_ENTRY = fileURLToPath(new URL(`../worker/entry${SELF_EXTENSION}`, import.meta.url));
+const WORKER_START_TIMEOUT_MS = 30_000;
+/** Grace period before an idle server retires, so a reconnecting presentation does not race it. */
+const IDLE_SHUTDOWN_MS = 10_000;
+
+/** The server's routing entry for one session worker process. The worker knows none of this. */
+interface Route {
+	sessionId: string;
+	/** Peer to the worker process. */
+	worker: RpcPeer;
+	/** Attached presentations by id, so an addressed event goes to exactly one of them. */
+	subscribers: Map<string, RpcPeer>;
+	stop(): void;
+}
+
+async function listSessions(sessionsRoot: string): Promise<SessionSummary[]> {
+	const executionEnv = new NodeExecutionEnv({ cwd: process.cwd() });
+	const repo = new JsonlSessionRepo({ fileSystem: executionEnv, sessionsRoot });
+	try {
+		return (await repo.list(undefined, BACKGROUND_CONTEXT)).map((metadata) => ({
+			id: metadata.id,
+			path: metadata.path,
+			cwd: metadata.cwd,
+			createdAt: metadata.createdAt,
+		}));
+	} finally {
+		await repo.close(BACKGROUND_CONTEXT);
+		await executionEnv.cleanup(BACKGROUND_CONTEXT);
+	}
+}
+
+export async function runServer(options: { transport: Transport; sessionsRoot: string }): Promise<void> {
+	const routes = new Map<string, Route>();
+	let presentations = 0;
+	let retire = (): void => {};
+	const retired = new Promise<void>((resolve) => {
+		retire = resolve;
+	});
+	let idleTimer: NodeJS.Timeout | undefined;
+	/** Nothing to serve and nothing running: leave, so the next start always gets current code. */
+	const considerRetiring = (): void => {
+		if (idleTimer) clearTimeout(idleTimer);
+		if (presentations > 0 || routes.size > 0) return;
+		idleTimer = setTimeout(() => {
+			if (presentations === 0 && routes.size === 0) retire();
+		}, IDLE_SHUTDOWN_MS);
+		idleTimer.unref();
+	};
+	/** Concurrent attaches to one session must share a worker: two writers would corrupt the session. */
+	const spawning = new Map<string, Promise<Route>>();
+
+	const spawnWorker = async (sessionId: string | undefined, cwd: string): Promise<Route> => {
+		const args = [...process.execArgv, WORKER_ENTRY, options.sessionsRoot, cwd, ...(sessionId ? [sessionId] : [])];
+		const child = spawn(process.execPath, args, { stdio: ["pipe", "pipe", "inherit"] });
+		const connection = childConnection(child);
+		const peer = createPeer(connection);
+		// Workers consume `Sessions` through this same peer.
+		peer.provide(Sessions, { list, attach: attachUnsupported });
+		// A worker that never answers must not wedge the attach that spawned it.
+		const described = await peer.use(Worker, { timeoutMs: WORKER_START_TIMEOUT_MS }).describe();
+		const route: Route = {
+			sessionId: described.sessionId,
+			worker: peer,
+			subscribers: new Map(),
+			stop: () => child.kill(),
+		};
+		// Routing is the server's job. An addressed event reaches one presentation; the rest are shared.
+		peer.onEvent((service, payload, to) => {
+			if (to !== undefined) {
+				route.subscribers.get(to)?.emitRaw(service, payload);
+				return;
+			}
+			for (const subscriber of route.subscribers.values()) subscriber.emitRaw(service, payload);
+		});
+		peer.onClose(() => {
+			routes.delete(route.sessionId);
+			considerRetiring();
+		});
+		routes.set(route.sessionId, route);
+		return route;
+	};
+
+	const ensureRoute = (sessionId: string | null, cwd: string): Promise<Route> => {
+		if (sessionId === null) return spawnWorker(undefined, cwd);
+		const existing = routes.get(sessionId);
+		if (existing) return Promise.resolve(existing);
+		const pending = spawning.get(sessionId);
+		if (pending) return pending;
+		const started = spawnWorker(sessionId, cwd).finally(() => spawning.delete(sessionId));
+		spawning.set(sessionId, started);
+		return started;
+	};
+
+	const list = (): Promise<SessionSummary[]> => listSessions(options.sessionsRoot);
+	const attachUnsupported = async (): Promise<string> => {
+		throw new Error("Only presentations attach to sessions");
+	};
+
+	const listener = await options.transport.listen((connection) => {
+		presentations += 1;
+		let route: Route | undefined;
+		let attachedAs: string | undefined;
+		const sessions: SessionsServiceApi = {
+			list,
+			attach: async (sessionId, cwd, presentationId) => {
+				route?.subscribers.delete(attachedAs ?? "");
+				attachedAs = presentationId;
+				route = await ensureRoute(sessionId, cwd);
+				route.subscribers.set(presentationId, presentation);
+				return route.sessionId;
+			},
+		};
+		const presentation: RpcPeer = createPeer(connection, {
+			forward: (method, args) => {
+				if (!route) throw new Error("Not attached to a session");
+				const service = method.slice(0, method.indexOf("."));
+				if (!route.worker.announced.has(service)) {
+					throw new Error(
+						`No host provides ${service}: server has [${[...presentation.provided]}], worker has [${[...route.worker.announced]}]`,
+					);
+				}
+				return route.worker.call(method, ...args);
+			},
+		});
+		presentation.provide(Sessions, sessions);
+		connection.onClose(() => {
+			presentations -= 1;
+			if (route && attachedAs !== undefined) {
+				route.subscribers.delete(attachedAs);
+				// One worker per session, kept alive only while someone is looking at it.
+				if (route.subscribers.size === 0) route.stop();
+			}
+			considerRetiring();
+		});
+	});
+
+	considerRetiring();
+	await retired;
+	await listener.close();
+}

packages/coding-agent/src/experimental/mini/shared/protocol.ts

@@ -0,0 +1,138 @@
+/** Service contracts and everything that crosses the wire. */
+
+import type { HarnessEvent, LaneSnapshot } from "@earendil-works/pi-agent-core";
+import type { AuthEvent, AuthPrompt } from "@earendil-works/pi-ai";
+
+/** Commands answer with data, never exceptions, exactly like a remote call would. */
+export type CommandResult = { ok: true } | { ok: false; error: string };
+
+/** Durable model identity. Nothing outside a worker holds a `Model` object. */
+export interface ModelRef {
+	provider: string;
+	modelId: string;
+}
+
+export interface ModelSummary extends ModelRef {
+	name: string;
+}
+
+export interface ProviderAccount {
+	id: string;
+	name: string;
+	authType: "oauth" | "api_key";
+	configured: boolean;
+	/** Where the credential came from, for display: "stored", "environment", an env var name. */
+	source?: string;
+	/** False for ambient credentials pi cannot collect itself, such as AWS profiles or env vars. */
+	interactive: boolean;
+	methodName?: string;
+}
+
+export interface ModelsState {
+	readonly models: readonly ModelSummary[];
+	readonly accounts: readonly ProviderAccount[];
+	readonly refreshing: boolean;
+}
+
+/** An auth prompt without its `AbortSignal`: the part that can cross a transport. */
+export type AuthPromptRequest = AuthPrompt extends infer Prompt
+	? Prompt extends unknown
+		? Omit<Prompt, "signal">
+		: never
+	: never;
+
+/** A service seen from the other side of a connection: every method returns a promise. */
+export type Remote<T> = {
+	[K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<Awaited<R>> : never;
+};
+
+/** Names one service and carries its call and event types. Names are globally unique. */
+export interface ServiceToken<TApi extends object, TEvent = never> {
+	readonly name: string;
+	/** Phantom, never read: keeps the types attached to the token. */
+	readonly types?: (api: TApi, event: TEvent) => void;
+}
+
+export function defineService<TApi extends object, TEvent = never>(name: string): ServiceToken<TApi, TEvent> {
+	return { name };
+}
+
+export interface SessionSummary {
+	id: string;
+	path: string;
+	cwd: string;
+	createdAt: number;
+}
+
+export interface SessionSnapshot {
+	sessionId: string;
+	cwd: string;
+	sessionPath: string;
+	/** Carries the lane configuration, queues, and stats: no side-channel replication. */
+	lane: LaneSnapshot;
+	models: ModelsState;
+}
+
+/** Everything the `Models` service publishes. */
+export type ModelsEvent =
+	| { type: "state"; state: ModelsState }
+	// Login runs the wrong way round: the request is an event, the answer is an ordinary call.
+	| { type: "prompt"; requestId: string; request: AuthPromptRequest }
+	| { type: "notice"; notice: AuthEvent };
+
+/** The login half, for whatever drives the dialog. */
+export type AuthEventPayload = Exclude<ModelsEvent, { type: "state" }>;
+
+/** One presentation's subscription: a `lane.watch()` in the worker, named so its events can be filtered. */
+export interface LaneSubscription {
+	subscriptionId: string;
+	snapshot: SessionSnapshot;
+}
+
+/** Lane events are addressed to the subscription whose watch produced them. */
+export interface LaneEvent {
+	subscriptionId: string;
+	event: HarnessEvent;
+}
+
+export interface LaneServiceApi {
+	/**
+	 * Capture a snapshot and open a subscription for one presentation. Its events are addressed to
+	 * `presentationId`, so the server routes them instead of broadcasting. Buffered until `start`.
+	 */
+	watch(presentationId: string): Promise<LaneSubscription>;
+	/** Begin delivery, draining everything buffered since the snapshot. */
+	start(subscriptionId: string): Promise<void>;
+	unwatch(subscriptionId: string): Promise<void>;
+	prompt(text: string): Promise<CommandResult>;
+	steer(text: string): Promise<CommandResult>;
+	followUp(text: string): Promise<CommandResult>;
+	compact(): Promise<CommandResult>;
+	abort(): Promise<CommandResult>;
+	setModel(ref: ModelRef): Promise<CommandResult>;
+}
+
+export interface ModelsServiceApi {
+	refresh(): Promise<CommandResult>;
+	login(providerId: string, authType: "oauth" | "api_key"): Promise<CommandResult>;
+	authReply(requestId: string, answer: string | null): Promise<void>;
+}
+
+/** Provided by a worker so the server can identify the session it opened, without naming lane methods. */
+export interface WorkerServiceApi {
+	describe(): Promise<{ sessionId: string }>;
+}
+
+export interface SessionsServiceApi {
+	list(): Promise<SessionSummary[]>;
+	attach(sessionId: string | null, cwd: string, presentationId: string): Promise<string>;
+}
+
+/** Provided by the worker. One subscription per presentation; `watch` again to rebase. */
+export const Lane = defineService<LaneServiceApi, LaneEvent>("lane");
+/** Provided by the worker. Small enough to publish whole. */
+export const Models = defineService<ModelsServiceApi, ModelsEvent>("models");
+/** Provided by the worker, consumed only by the server. */
+export const Worker = defineService<WorkerServiceApi>("worker");
+/** Provided by the server. */
+export const Sessions = defineService<SessionsServiceApi>("sessions");