agent-sh 0.12.27 → 0.13.0

package/examples/extensions/ashi/README.md

@@ -0,0 +1,250 @@
+# ashi
+
+`ash` (agent-sh's built-in agent) running inside pi's TUI substrate, with no shell underneath.
+
+A test of agent-sh's claim that the kernel is a frontend-agnostic communication layer: `ashi`
+uses `createCore()` from agent-sh, skips `activateShell()`, disables the shell-coupled built-ins
+(`shell-context`, `tui-renderer`, `file-autocomplete`), and mounts `@earendil-works/pi-tui` as
+the only frontend. Backend, tools, slash commands, providers, and skills come along unchanged.
+
+## Install
+
+```bash
+agent-sh install ashi
+export PATH="$HOME/.agent-sh/bin:$PATH"
+ashi
+```
+
+`agent-sh install` copies this directory into `~/.agent-sh/extensions/ashi/`, runs
+`npm install` and `npm run build` there, and symlinks the built bin into `~/.agent-sh/bin/`.
+
+## Configure
+
+Reads `~/.agent-sh/settings.json` for providers and defaults, same as `agent-sh` itself. The
+quickest path is exporting `OPENROUTER_API_KEY` or `OPENAI_API_KEY` and running `ashi`.
+
+See the agent-sh [Usage Guide](https://github.com/guanyilun/agent-sh/blob/main/docs/usage.md)
+for the full `settings.json` schema, provider profiles, and model selection details.
+
+CLI flags mirror `agent-sh`:
+
+```
+--provider <name>    Provider profile from ~/.agent-sh/settings.json
+--model <id>         Override model
+--api-key <key>      Direct API key
+--base-url <url>     OpenAI-compatible base URL
+--backend <name>     Agent backend (default: ash)
+-e, --extensions     Extra extensions to load (comma-separated)
+```
+
+Extensions loaded via `-e` follow the standard agent-sh extension contract — see
+[Extensions](https://github.com/guanyilun/agent-sh/blob/main/docs/extensions.md) for the
+`ExtensionContext` API, event bus, content transforms, and custom backends.
+
+## Keybindings
+
+Match pi-coding-agent's convention:
+
+```
+Esc      Cancel active turn
+Ctrl+C   Clear editor
+Ctrl+D   Quit (when editor is empty)
+Ctrl+T   Toggle thinking-block visibility
+Ctrl+O   Expand/collapse the most recent tool result
+```
+
+## Sessions
+
+ashi mirrors pi's session model: many sessions per cwd, fresh by default.
+
+```
+/resume      Browse past sessions in this cwd (interactive picker)
+/new         Start a fresh session (discards in-memory context)
+/name <text> Set a display name for the current session
+/sessions    Text dump of all sessions in this cwd
+```
+
+Each session is its own tree (one JSONL file per session). Every entry has an `id` and
+`parentId`; sibling branches stay on disk; you can rewind and branch within a session.
+
+```
+/fork              Interactive in-session tree picker
+/fork <id-prefix>  Direct rewind to a specific entry
+/branch            Text dump of the active branch (root → leaf)
+```
+
+Storage: `~/.agent-sh/extensions/ashi/history/<cwd-slug>/sessions/<id>.jsonl`. Each line
+is a `SessionEntry`:
+
+```typescript
+type SessionEntry =
+  | { type: "session"; id; parentId: null; cwd; timestamp; version }
+  | { type: "message"; id; parentId; timestamp; message: AgentMessage }
+  | { type: "compaction"; id; parentId; timestamp; summary; firstKeptId; tokensBefore };
+```
+
+Raw `AgentMessage` objects are stored verbatim (full tool call arguments, tool results,
+etc.) so `/resume` and `/fork` faithfully reconstruct the original conversation — same
+shape as pi's session format.
+
+The kernel side adds three small handlers:
+optional `parentSeq`/`getBranch`/`getTree`/`setLeaf` on `NuclearEntry`/`HistoryAdapter`
+(useful for tree-aware HistoryAdapters in general — not used by this extension);
+`conversation:allocate-seq` and `conversation:reset-for-session` so multi-session adapters
+can swap context without nuclear-state bleed-through.
+
+ashi itself bypasses agent-sh's `NuclearEntry` pipeline entirely by installing a
+`NoopHistory` adapter — raw messages are captured directly via `agent:processing-done`
+and the `conversation:get-messages` handler.
+
+## Compaction
+
+ashi replaces agent-sh's default deterministic two-tier-pin compaction with a pi-style
+LLM-driven path:
+
+1. Cut point: walk back from the newest message until ~20K tokens are kept; never cut at
+   tool results or in the middle of an assistant→tool call group.
+2. LLM summarizes the older span into the pi structured format (Goal / Constraints /
+   Progress / Decisions / Next Steps / Critical Context).
+3. The live message array becomes `[summary, ...kept messages]`.
+4. The summary lands in the session as a `CompactionEntry` carrying `summary`,
+   `firstKeptId`, and `tokensBefore` — same shape as pi's compaction. Subsequent
+   compactions reference the previous one's summary so chains stay coherent.
+
+Triggered automatically when prompt tokens cross agent-sh's threshold, or manually with
+`/compact`. If the LLM call fails or the conversation is too short, falls through to the
+default eviction.
+
+The cut-point walker, prompt template, serialization, and LLM call all live in this
+extension. The kernel side is just the advisable `conversation:compact` seam.
+
+## What's intentionally missing
+
+This is a spike, not a clone of pi's full UI. The MVP renders:
+
+- User submissions, streaming assistant Markdown
+- Tool invocations with start/complete state
+- Slash commands with autocomplete (`/help`, `/model`, `/backend`, `/resume`, `/new`, `/fork`, …)
+- Multi-session tree history with `/resume` and `/fork` pickers
+- LLM compaction with summaries that survive across `/resume`
+- Loader, errors, info messages
+- Inline images via the `image` ContentBlock and the `render:image` handler — the
+  bundled `latex-images` extension works against ashi without modification
+  (terminal must support iTerm2 or Kitty graphics)
+
+Out of scope for v0: branch summaries on `/fork` navigation (pi has this), `/clone`
+(duplicate active branch into a new session), permission dialogs, diff renderer, file-path
+autocomplete, session search/rename/delete inside the `/resume` picker, theme selector.
+Each can be added by writing a pi-tui Component and subscribing to the corresponding
+bus event.
+
+## Extension surface
+
+Other extensions can override how chat entries render without forking ashi.
+Hooks are exposed via `ctx.define` (defaults) + `ctx.advise` (override).
+
+### Chat hooks
+
+| Hook | Args | Returns |
+|---|---|---|
+| `ashi:render-user-message` | `{ text, state, invalidate }` | `Component` |
+| `ashi:render-assistant` | `{ text, state, invalidate }` | `Component` |
+| `ashi:render-thinking` | `{ text, hidden, state, invalidate }` | `Component` |
+
+### Tool hooks (per-tool)
+
+Tool rendering is split into a call line (the input header) and a result body
+(streaming output + final state). Each side is dispatched by tool name with a
+`:default` fallback:
+
+| Hook | Args | Returns |
+|---|---|---|
+| `ashi:render-tool-call:{name}` | `{ toolCallId, name, title, kind, displayDetail, rawInput, state, invalidate }` | `ToolCallView` |
+| `ashi:render-tool-call:default` | (same) | `ToolCallView` |
+| `ashi:render-tool-result:{name}` | `{ toolCallId, name, kind, rawInput, mode, previewLines, state, invalidate }` | `ToolResultView` |
+| `ashi:render-tool-result:default` | (same) | `ToolResultView` |
+
+`state` is a per-call mutable bag; `invalidate()` requests a re-render.
+
+- `ToolCallView` extends `Component` with `setStatus({ exitCode, elapsedMs, summary })` — called once on completion.
+- `ToolResultView` extends `Component` with `appendChunk(chunk)`, `setDiff(lines)`, `finalize({ exitCode, summary })`, and `toggleExpanded()` — ashi mutates the result view as output streams in and when the user hits `Ctrl+O`.
+
+`mode` and `previewLines` on result args come from `ashi.display.{name}` config
+(see below) so renderers can honor the user's compactness preference without
+re-implementing the resolution logic.
+
+Example: override how `bash` calls render.
+
+```ts
+export default function activate(ctx) {
+  ctx.advise("ashi:render-tool-call:bash", (next, args) => {
+    return new MyFancyBashLine(args);  // must implement ToolCallView
+  });
+}
+```
+
+For non-render concerns (commands, settings, tools, providers) use the standard
+agent-sh extension API.
+
+## Display configuration
+
+Per-tool compactness lives under `ashi.display` in `~/.agent-sh/settings.json`:
+
+```json
+{
+  "ashi": {
+    "display": {
+      "default": { "result": "preview", "previewLines": 8 },
+      "read":    { "result": "hidden" },
+      "ls":      { "result": "hidden" },
+      "grep":    { "result": "summary" },
+      "bash":    { "result": "preview", "previewLines": 12 },
+      "edit":    { "result": "preview" },
+      "write":   { "result": "preview" }
+    }
+  }
+}
+```
+
+`result` modes:
+
+- `"hidden"` — call line only while streaming; line count (`↳ 42 lines`) after completion.
+- `"summary"` — 2-line tail while streaming; line count after completion.
+- `"preview"` — last `previewLines` lines of output (default 8), with a `... (N more lines)` hint when content overflows.
+
+For `edit_file` / `write_file`, the diff frame is treated as the output and
+follows the same gating: shown for `preview`, hidden for `hidden`/`summary`
+(the call line already carries `+12 -3` stats). The line-count hint is
+suppressed for diff-producing tools so edits stay quiet.
+
+Hit `Ctrl+O` to expand the most recent tool result inline — shows the full
+output buffer and the full diff regardless of mode. Press again to collapse.
+
+Each tool inherits from `default` and is overridden by its own block. Unknown
+tool names fall through to `default`. Built-in defaults aim for compactness
+(`read`/`ls` hidden, `grep` summarized) — override under `default` to widen
+everything, or under a specific tool to tune one.
+
+## Development
+
+`@guanyilun/ashi` depends on the published `agent-sh` package. To iterate against
+the parent checkout instead, use `npm link`:
+
+```bash
+# one-time: register the local agent-sh checkout
+cd /path/to/agent-sh
+npm run build
+npm link
+
+# in ashi, point its agent-sh dependency at the linked checkout
+cd examples/extensions/ashi
+npm install
+npm link agent-sh
+
+npm run dev      # tsx-driven, no compile step
+# or: npm run build && node dist/cli.js
+```
+
+Rebuild agent-sh (`npm run build` at the repo root) whenever you change the
+kernel — the link picks up `dist/` directly. To go back to the published
+version, run `npm unlink agent-sh && npm install` inside `examples/extensions/ashi`.

package/examples/extensions/ashi/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@guanyilun/ashi",
+  "version": "0.1.0",
+  "description": "Ash with a pi-tui frontend — agent-sh's kernel without the shell, rendered through pi's TUI library",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "ashi": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "agent-sh",
+    "ashi",
+    "ash",
+    "pi-tui",
+    "tui",
+    "agent",
+    "ai",
+    "llm",
+    "cli"
+  ],
+  "author": "Yilun Guan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guanyilun/agent-sh.git",
+    "directory": "examples/extensions/ashi"
+  },
+  "homepage": "https://github.com/guanyilun/agent-sh/tree/main/examples/extensions/ashi",
+  "bugs": {
+    "url": "https://github.com/guanyilun/agent-sh/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@earendil-works/pi-tui": "^0.74.0",
+    "agent-sh": "^0.12.27",
+    "chalk": "^5.5.0",
+    "cli-highlight": "^2.1.11"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.7.0"
+  }
+}

package/examples/extensions/ashi/src/autocomplete.ts

@@ -0,0 +1,91 @@
+import type {
+  AutocompleteItem,
+  AutocompleteProvider,
+  AutocompleteSuggestions,
+} from "@earendil-works/pi-tui";
+import type { EventBus } from "agent-sh/event-bus";
+
+/** Adapt pi-tui's AutocompleteProvider to agent-sh's autocomplete:request pipe.
+ *  Reads the line up to the cursor, asks the bus for suggestions, returns them. */
+export class BusAutocompleteProvider implements AutocompleteProvider {
+  constructor(private bus: EventBus) {}
+
+  async getSuggestions(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+  ): Promise<AutocompleteSuggestions | null> {
+    if (cursorLine !== 0) return null;
+    const line = lines[0] ?? "";
+    const before = line.slice(0, cursorCol);
+
+    const atSpan = findAtTrigger(before);
+    if (atSpan) {
+      const result = this.bus.emitPipe("autocomplete:request", {
+        buffer: atSpan.text, command: null, commandArgs: null, items: [],
+      });
+      if (result.items.length === 0) return null;
+      const items: AutocompleteItem[] = result.items.map((it) => ({
+        value: "@" + it.name,
+        label: "@" + it.name,
+        description: it.description,
+      }));
+      return { items, prefix: atSpan.text };
+    }
+
+    if (!before.startsWith("/")) return null;
+
+    const sp = before.indexOf(" ");
+    const command = sp === -1 ? null : before.slice(0, sp);
+    const commandArgs = sp === -1 ? null : before.slice(sp + 1);
+
+    const result = this.bus.emitPipe("autocomplete:request", {
+      buffer: before,
+      command,
+      commandArgs,
+      items: [],
+    });
+    if (result.items.length === 0) return null;
+
+    const items: AutocompleteItem[] = result.items.map((it) => ({
+      value: it.name,
+      label: it.name,
+      description: it.description,
+    }));
+    return { items, prefix: before };
+  }
+
+  applyCompletion(
+    lines: string[],
+    cursorLine: number,
+    cursorCol: number,
+    item: AutocompleteItem,
+    prefix: string,
+  ): { lines: string[]; cursorLine: number; cursorCol: number } {
+    const line = lines[cursorLine] ?? "";
+    // Replace the prefix span (the leading slash-word + args we sent) with
+    // the completion value. Anything after the cursor is preserved.
+    const head = line.slice(0, cursorCol - prefix.length);
+    const tail = line.slice(cursorCol);
+    const newLine = `${head}${item.value}${tail}`;
+    const out = lines.slice();
+    out[cursorLine] = newLine;
+    return {
+      lines: out,
+      cursorLine,
+      cursorCol: (head + item.value).length,
+    };
+  }
+}
+
+/** Locate an active `@` file-trigger in the text preceding the cursor.
+ *  Matches when `@` is at start or after whitespace and the chars from
+ *  `@` to cursor are path-friendly (letters, digits, `.`, `/`, `_`, `-`). */
+function findAtTrigger(before: string): { text: string } | null {
+  const at = before.lastIndexOf("@");
+  if (at < 0) return null;
+  if (at > 0 && !/\s/.test(before[at - 1]!)) return null;
+  const query = before.slice(at + 1);
+  if (!/^[a-zA-Z0-9_./-]*$/.test(query)) return null;
+  return { text: before.slice(at) };
+}

package/examples/extensions/ashi/src/capture.ts

@@ -0,0 +1,34 @@
+import type { ExtensionContext } from "agent-sh/types";
+import type { MultiSessionStore } from "./multi-session-store.js";
+import type { AgentMessage } from "./session-store.js";
+
+/** Maintains an `(entryId | null)[]` parallel to the live messages array;
+ *  null slots are synthetics like compaction summaries that have no entry. */
+export interface Capture {
+  flush(): Promise<void>;
+  getEntryIdAt(messageIndex: number): string | null;
+  resetTo(ids: (string | null)[]): void;
+}
+
+export function registerCapture(
+  ctx: ExtensionContext,
+  getStore: () => MultiSessionStore,
+): Capture {
+  let liveEntryIds: (string | null)[] = [];
+
+  const flush = async (): Promise<void> => {
+    const messages = ctx.call("conversation:get-messages") as AgentMessage[] | undefined;
+    if (!messages || messages.length <= liveEntryIds.length) return;
+    const newMessages = messages.slice(liveEntryIds.length);
+    const newIds = await getStore().current().appendMessages(newMessages);
+    liveEntryIds = [...liveEntryIds, ...newIds];
+  };
+
+  ctx.bus.on("agent:processing-done", () => { void flush(); });
+
+  return {
+    flush,
+    getEntryIdAt: (i) => liveEntryIds[i] ?? null,
+    resetTo: (ids) => { liveEntryIds = [...ids]; },
+  };
+}

package/examples/extensions/ashi/src/cli.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * ashi — agent-sh's ash backend with a pi-tui frontend, no shell.
+ *
+ * Boots the agent-sh kernel directly, skips the PTY shell and the
+ * default streaming tui-renderer, and mounts pi-tui as the sole
+ * frontend. Demonstrates that the kernel is frontend-agnostic — same
+ * backend, tools, slash commands, providers; different presentation.
+ */
+import { createCore, NoopHistory } from "agent-sh/core";
+import { loadBuiltinExtensions } from "agent-sh/extensions";
+import { loadExtensions } from "agent-sh/extension-loader";
+import { activateAgent } from "agent-sh/agent";
+import { getSettings } from "agent-sh/settings";
+import type { AppConfig } from "agent-sh/types";
+
+import { mountAshi } from "./frontend.js";
+import { MultiSessionStore } from "./multi-session-store.js";
+import { registerForkCommands } from "./commands.js";
+import { registerSessionCommands } from "./session-commands.js";
+import { registerCompaction } from "./compaction.js";
+import { registerCapture } from "./capture.js";
+import { registerRenderDefaults } from "./hooks.js";
+import { registerDefaultToolRenderers } from "./default-renderers.js";
+import * as os from "node:os";
+import * as path from "node:path";
+
+function parseArgs(argv: string[]): AppConfig & { extensions?: string[] } {
+  let model: string | undefined;
+  let apiKey: string | undefined = process.env.OPENAI_API_KEY ?? process.env.OPENROUTER_API_KEY;
+  let baseURL: string | undefined = process.env.OPENAI_BASE_URL;
+  let provider: string | undefined;
+  let backend: string | undefined;
+  const extensions: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--model" && argv[i + 1]) model = argv[++i];
+    else if (a === "--api-key" && argv[i + 1]) apiKey = argv[++i];
+    else if (a === "--base-url" && argv[i + 1]) baseURL = argv[++i];
+    else if (a === "--provider" && argv[i + 1]) provider = argv[++i];
+    else if (a === "--backend" && argv[i + 1]) backend = argv[++i];
+    else if ((a === "-e" || a === "--extensions") && argv[i + 1]) {
+      extensions.push(...argv[++i]!.split(",").map(s => s.trim()).filter(Boolean));
+    } else if (a === "-h" || a === "--help") {
+      process.stdout.write(`ashi — ash backend, pi-tui frontend\n\n` +
+        `Usage: ashi [--provider <name>] [--model <id>] [--api-key <key>] [--base-url <url>]\n` +
+        `            [--backend <name>] [-e <ext>[,<ext>...]]\n\n` +
+        `Reads ~/.agent-sh/settings.json for providers and defaults.\n`);
+      process.exit(0);
+    }
+  }
+
+  return { shell: "/bin/sh", model, apiKey, baseURL, provider, backend, extensions };
+}
+
+async function main(): Promise<void> {
+  const config = parseArgs(process.argv.slice(2));
+
+  if (!process.stdin.isTTY) {
+    process.stderr.write("ashi requires a TTY for interactive rendering.\n");
+    process.exit(1);
+  }
+
+  const cwd = process.cwd();
+  const cwdSlug = cwd.replace(/\//g, "-").replace(/^-/, "");
+  const sessionsDir = path.join(os.homedir(), ".agent-sh", "ashi", "history", cwdSlug, "sessions");
+  const store = new MultiSessionStore(sessionsDir, cwd);
+  const getStore = (): MultiSessionStore => store;
+
+  const core = createCore({ ...config, history: new NoopHistory() });
+
+  let stopFrontend: (() => void) | null = null;
+
+  const cleanup = (): void => {
+    try { stopFrontend?.(); } catch { /* ignore */ }
+    try { core.kill(); } catch { /* ignore */ }
+    if (process.stdin.isTTY) {
+      try { process.stdin.setRawMode(false); } catch { /* ignore */ }
+    }
+    process.exit(0);
+  };
+
+  const ctx = core.extensionContext({ quit: cleanup });
+
+  activateAgent(ctx);
+  await loadBuiltinExtensions(ctx);
+
+  const loaded = await loadExtensions(ctx, config.extensions);
+  core.bus.emit("core:extensions-loaded", { names: loaded });
+
+  const { names: backendNames } = core.bus.emitPipe("config:get-backends", {
+    names: [] as string[], active: null as string | null,
+  });
+  if (backendNames.length === 0) {
+    process.stderr.write("ashi: no agent backend registered. Set OPENAI_API_KEY or OPENROUTER_API_KEY, or configure ~/.agent-sh/settings.json.\n");
+    process.exit(1);
+  }
+
+  const capture = registerCapture(ctx, getStore);
+  registerCompaction(ctx, getStore, capture);
+  registerRenderDefaults(ctx);
+  registerDefaultToolRenderers(ctx);
+
+  ctx.advise("conversation:format-prior-history", () => null);
+  ctx.advise("system-prompt:build", (base) => `${base}\n\n<cwd>${process.cwd()}</cwd>`);
+
+  const handle = mountAshi(ctx, getStore, capture);
+  stopFrontend = handle.stop;
+
+  registerForkCommands(ctx, getStore, handle.openTreePicker, handle.rebuildChat, capture);
+  registerSessionCommands(ctx, getStore, capture, {
+    openSessionPicker: handle.openSessionPicker,
+    rebuildChat: handle.rebuildChat,
+  });
+
+  await core.activateBackend(config.backend ?? getSettings().defaultBackend);
+
+  process.on("SIGTERM", cleanup);
+  process.on("SIGHUP", cleanup);
+}
+
+main().catch((err) => {
+  process.stderr.write(`ashi fatal: ${err?.stack ?? err}\n`);
+  process.exit(1);
+});

package/examples/extensions/ashi/src/commands.ts

@@ -0,0 +1,82 @@
+import type { ExtensionContext } from "agent-sh/types";
+import type { MultiSessionStore } from "./multi-session-store.js";
+import type { AgentMessage } from "./session-store.js";
+import type { Capture } from "./capture.js";
+
+export function registerForkCommands(
+  ctx: ExtensionContext,
+  getStore: () => MultiSessionStore,
+  openTreePicker: () => Promise<void>,
+  rebuildChat: () => Promise<void>,
+  capture: Capture,
+): void {
+  const { bus } = ctx;
+
+  ctx.registerCommand("fork", "Rewind and branch: /fork (interactive picker) or /fork <id-prefix>", async (args) => {
+    const arg = args.trim();
+    if (arg === "") {
+      await openTreePicker();
+      return;
+    }
+    const branch = getStore().current().getBranch();
+    const matches = branch.filter((e) => e.id.startsWith(arg));
+    if (matches.length === 0) {
+      bus.emit("ui:error", { message: `fork: no entry matches "${arg}"` });
+      return;
+    }
+    if (matches.length > 1) {
+      bus.emit("ui:error", { message: `fork: ambiguous prefix "${arg}" matches ${matches.length} entries` });
+      return;
+    }
+    const target = matches[0]!;
+    getStore().current().setActiveLeaf(target.id);
+    applyBranchMessages(ctx, getStore, capture);
+    bus.emit("ui:info", { message: `fork: rewound to ${target.id}` });
+    await rebuildChat();
+  });
+
+  ctx.registerCommand("branch", "Show the active branch (root → leaf)", async () => {
+    const branch = getStore().current().getBranch();
+    if (branch.length === 0) {
+      bus.emit("ui:info", { message: "branch: empty" });
+      return;
+    }
+    const lines = branch.map((e) => {
+      if (e.type === "session") return `[${e.id}] session start (${e.cwd})`;
+      if (e.type === "compaction") return `[${e.id}] compaction (firstKept=${e.firstKeptId})`;
+      const msg = (e as { message: AgentMessage }).message;
+      const text = typeof msg.content === "string" ? msg.content : "";
+      return `[${e.id}] ${msg.role}: ${text.slice(0, 60)}`;
+    });
+    bus.emit("ui:info", { message: `branch (${branch.length} entries):\n${lines.join("\n")}` });
+  });
+}
+
+export function applyBranchMessages(
+  ctx: ExtensionContext,
+  getStore: () => MultiSessionStore,
+  capture: Capture,
+): void {
+  const store = getStore().current();
+  ctx.call("conversation:replace-messages", store.buildMessages());
+
+  const branch = store.getBranch();
+  let compaction: { firstKeptId: string } | null = null;
+  for (let i = branch.length - 1; i >= 0; i--) {
+    if (branch[i]!.type === "compaction") {
+      compaction = branch[i] as { firstKeptId: string };
+      break;
+    }
+  }
+  const ids: (string | null)[] = [];
+  if (compaction) {
+    ids.push(null);
+    const startIdx = branch.findIndex((e) => e.id === compaction!.firstKeptId);
+    for (let i = Math.max(0, startIdx); i < branch.length; i++) {
+      if (branch[i]!.type === "message") ids.push(branch[i]!.id);
+    }
+  } else {
+    for (const e of branch) if (e.type === "message") ids.push(e.id);
+  }
+  capture.resetTo(ids);
+}