pi-summarize 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bryan Jeffrey Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# pi-summarize
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [pi](https://github.com/earendil-works/pi) extension package with two features, both driven by a cheap side model:
+
+1. **Live activity line.** While the agent works, the working indicator shows one short, specific present-progressive line (≤ 12 words) describing the goal rather than the command, e.g. `Checking why the sync test fails`. Tool calls summarize immediately; text and thinking summarize at most every ~2 s. Subagents run their own copy of the extension and narrate themselves; the parent does not relay their progress. While a tool runs, the line shows elapsed time every 5 s (display only, not recorded), so long waits visibly move. Calls are cancelled when superseded or when the run ends, and failures or timeouts (10 s) fall back to a deterministic line such as `Reading files.js…` or `Working…`.
+
+   In the transcript, tool rows are hidden. Each step (one model turn that runs tools) leaves one breadcrumb, `◆ <summary>`, where its tool rows were, recorded at `turn_end` from that step's live line (waiting up to 2.5 s for it). A tool-only step with the same goal as the previous breadcrumb merges into it; a step with its own lead-in text always gets its own breadcrumb. Ctrl+O (expand) brings back the tool rows and shows each summary's thinking tail and tool calls. With `activity` off, tools render normally.
+2. **Auto-title.** After the first assistant reply in a session with no name, it sets a 2–4 word session name. It never overwrites a name you set, and it does not retry once it has named the session.
+
+Each breadcrumb and each generated title is persisted with `pi.appendEntry("pi-summarize", …)`. These custom entries are not sent to the LLM. Hosts can read them from the session JSONL.
+
+```jsonc
+// {"type":"custom","customType":"pi-summarize","data":{"kind":"activity","text":"Reading files.js…","at":1760000000000,"turn":2,"source":"fallback","toolCallIds":["t1"]}}
+// {"type":"custom","customType":"pi-summarize","data":{"kind":"title","text":"Fix Sync Adapter","auto":true,"at":1760000000000}}
+```
+
+## Host integration
+
+Each breadcrumb is also emitted on the extension bus as `pi.events` channel `pi-summarize:activity`, with payload `{ sessionId, text, at, turn, source, toolCallIds }`. `sessionId` is the session that produced the line, so a host running several sessions can route by it.
+
+Subagent children get their own bus unless the host passes one to their resource loader, so emits from a child do not reach the parent by default. Persisted history needs no bus: a child's session JSONL (the subagent `outputFile`) already contains its `pi-summarize` activity entries.
+
+## Install
+
+From npm:
+
+```sh
+pi install npm:pi-summarize
+```
+
+From git:
+
+```sh
+pi install git:github.com/bry-guy/pi-summarize
+```
+
+From a local checkout:
+
+```sh
+pi install /path/to/pi-summarize
+```
+
+## Configuration
+
+Set these in `~/.pi/agent/settings.json` under the `pi-summarize` key, or override with environment variables (env wins):
+
+```json
+{
+  "pi-summarize": {
+    "model": "anthropic/claude-haiku-5-5",
+    "thinking": "low",
+    "activity": true,
+    "title": true
+  }
+}
+```
+
+| Setting | Env var | Default | Notes |
+|---|---|---|---|
+| `model` | `PI_SUMMARIZE_MODEL` | session's current model | `provider/id`. If not found, a warning is shown once and only fallback lines are used. |
+| `thinking` | `PI_SUMMARIZE_THINKING` | `off` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`. Invalid values become `off`. |
+| `activity` | `PI_SUMMARIZE_ACTIVITY` | `true` | Live working line. `0`/`false`/`off`/`no` disable it. |
+| `title` | `PI_SUMMARIZE_TITLE` | `true` | Auto-title. Same false values. |
+
+The extension reads `settings.json` from `$PI_CODING_AGENT_DIR` (default `~/.pi/agent`). Project-level settings are not read.
+
+## Try it
+
+Run pi in the TUI and send a prompt that uses tools. The working line should change from the default spinner text to activity lines. After the first reply, the session name should be set (check `/name` or the session selector).
+
+Non-interactive check:
+
+```sh
+cd /tmp && pi --session-dir /tmp/ps-sessions -p "list files in /tmp briefly"
+grep '"customType":"pi-summarize"' /tmp/ps-sessions/*.jsonl
+```
+
+## Development
+
+```sh
+npm test   # node --test on test/*.test.ts (Node ≥ 22.18, native TS type stripping)
+mise run release   # tests, refuses an already-published version, then npm publish
+```
+
+- `src/core.ts`: config, fallback lines, debounced `ActivityTracker`, auto-title rules. No pi imports.
+- `extensions/index.ts`: pi wiring (events, model call via `ctx.modelRegistry.streamSimple`, `setWorkingMessage`, `appendEntry`, `setSessionName`).
+- `test/core.test.ts`: unit tests with an injected mock completion.
+- `test/extension.test.ts`: loads the extension against a fake pi API and mock registry.
+
+## Limits
+
+- Model calls use `streamSimple`, not `complete()`, because only `streamSimple` accepts a reasoning level. `complete()` is used in pi's own examples.
+- Activity entries record `toolCallIds` but not `fromEntryIds`, because streaming events do not carry transcript entry ids.
+- Each activity line costs one side-model call. A long run with text streaming makes roughly one call every 2 s. Use a small model.
+- Only user-scope settings are read. The extension does not add a settings UI.

package/extensions/index.ts

@@ -0,0 +1,211 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Box, Container, Text } from "@earendil-works/pi-tui";
+import { ActivityTracker, autoTitle, resolveConfig, type SummarizeConfig } from "../src/core.ts";
+
+type Ctx = ExtensionContext;
+type Context = Parameters<Ctx["modelRegistry"]["streamSimple"]>[1];
+type Content = { type?: string; text?: string };
+
+const textOf = (content: unknown): string =>
+	typeof content === "string"
+		? content
+		: Array.isArray(content)
+			? (content as Content[])
+					.filter((c) => c.type === "text" && typeof c.text === "string")
+					.map((c) => c.text)
+					.join("\n")
+			: "";
+
+/** Bus channel for each shown activity line. Hosts such as subagent runners listen here. */
+const ACTIVITY_CHANNEL = "pi-summarize:activity";
+
+const agentDir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+
+function loadSettings(): unknown {
+	try {
+		return JSON.parse(readFileSync(join(agentDir, "settings.json"), "utf8"));
+	} catch {
+		return {};
+	}
+}
+
+/** Configured "provider/id" model, or the session's current model when unset. */
+function resolveModel(ctx: Ctx, spec: string | undefined) {
+	if (!spec) return ctx.model;
+	const slash = spec.indexOf("/");
+	return slash > 0 ? ctx.modelRegistry.find(spec.slice(0, slash), spec.slice(slash + 1)) : undefined;
+}
+
+/** One side-model call. Rejects when no usable model exists, the call fails, or the signal aborts. */
+async function complete(ctx: Ctx, cfg: SummarizeConfig, prompt: string, signal: AbortSignal, maxTokens: number) {
+	const model = resolveModel(ctx, cfg.model);
+	if (!model || !ctx.modelRegistry.hasConfiguredAuth(model)) throw new Error("no usable summary model");
+	const context: Context = {
+		messages: [{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() }],
+	};
+	const stream = ctx.modelRegistry.streamSimple(model, context, {
+		...(cfg.thinking === "off" ? {} : { reasoning: cfg.thinking }),
+		signal,
+		maxTokens,
+	});
+	for await (const event of stream) {
+		if (event.type === "done") return textOf(event.message.content);
+		if (event.type === "error") throw new Error("summary model error");
+	}
+	throw new Error("summary stream ended without a result");
+}
+
+export default function (pi: ExtensionAPI) {
+	registerRenderers(pi, () => cfg.activity);
+	let live: Ctx | undefined; // latest context; the one captured at session_start can go stale
+	let cfg: SummarizeConfig = resolveConfig({}, {});
+	let tracker: ActivityTracker | undefined;
+	let titling = false;
+
+	pi.on("session_start", async (_event, ctx) => {
+		live = ctx;
+		cfg = resolveConfig(loadSettings(), process.env);
+		tracker?.stop();
+		const sessionId = ctx.sessionManager.getSessionId();
+		tracker = new ActivityTracker({
+			complete: (prompt, signal) => complete(live!, cfg, prompt, signal, 60),
+			show: (text) => live?.ui.setWorkingMessage(text),
+			record: (entry) => {
+				pi.appendEntry("pi-summarize", { kind: "activity", ...entry });
+				pi.events.emit(ACTIVITY_CHANNEL, { sessionId, ...entry });
+			},
+		});
+		// With tool rows hidden, hidden-thinking placeholders pile up between breadcrumbs; the breadcrumbs carry the thinking on Ctrl+O.
+		if (cfg.activity && ctx.hasUI) ctx.ui.setHiddenThinkingLabel("");
+		if (cfg.model && !resolveModel(ctx, cfg.model) && ctx.hasUI) {
+			ctx.ui.notify(`pi-summarize: model "${cfg.model}" not found; using fallback lines`, "warning");
+		}
+	});
+
+	pi.on("before_agent_start", async (event, ctx) => {
+		live = ctx;
+		if (cfg.activity) tracker?.begin("prompt" in event ? event.prompt : undefined);
+	});
+
+	pi.on("turn_start", async (event, ctx) => {
+		live = ctx;
+		if (cfg.activity) tracker?.turnStart(event.turnIndex);
+	});
+
+	pi.on("message_update", async (event, ctx) => {
+		live = ctx;
+		if (!cfg.activity) return;
+		const ev = event.assistantMessageEvent;
+		if (ev.type === "thinking_delta") tracker?.thinkingDelta(ev.delta);
+		if (ev.type === "text_delta") tracker?.textDelta(ev.delta);
+	});
+
+	pi.on("tool_execution_start", async (event, ctx) => {
+		live = ctx;
+		if (cfg.activity) tracker?.toolStart(event.toolCallId, event.toolName, event.args);
+	});
+
+	// Awaited so the breadcrumb lands where the step's hidden tool rows are, before the next step's text.
+	pi.on("turn_end", async (_event, ctx) => {
+		live = ctx;
+		if (cfg.activity) await tracker?.turnEnd();
+	});
+
+	pi.on("tool_execution_end", async (_event, ctx) => {
+		live = ctx;
+		if (cfg.activity) tracker?.toolEnd();
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		live = ctx;
+		if (cfg.activity) tracker?.stop();
+	});
+
+	// agent_settled, not agent_end: print mode can exit right after agent_end, and this must finish first.
+	pi.on("agent_settled", async (_event, ctx) => {
+		live = ctx;
+		if (!cfg.title || titling) return;
+
+		const branch = ctx.sessionManager.getBranch();
+		const alreadyTitled = branch.some(
+			(e) => e.type === "custom" && e.customType === "pi-summarize" && (e.data as { kind?: string })?.kind === "title",
+		);
+		const messages = branch.flatMap((e) => (e.type === "message" ? [e.message as { role?: string; content?: unknown }] : []));
+		const firstUser = messages.find((m) => m.role === "user");
+		const firstAssistant = messages.find((m) => m.role === "assistant");
+
+		titling = true;
+		try {
+			await autoTitle({
+				hasReply: Boolean(firstAssistant),
+				alreadyTitled,
+				getName: () => pi.getSessionName(),
+				setName: (name) => pi.setSessionName(name),
+				record: (entry) => pi.appendEntry("pi-summarize", entry),
+				complete: (prompt) => complete(live!, cfg, prompt, AbortSignal.timeout(15_000), 30),
+				firstUser: textOf(firstUser?.content),
+				firstAssistant: textOf(firstAssistant?.content),
+			});
+		} catch {
+			// titling is best-effort
+		} finally {
+			titling = false;
+		}
+	});
+
+	pi.on("session_shutdown", async () => {
+		tracker?.stop();
+	});
+}
+
+type Renderers = NonNullable<ReturnType<Parameters<ExtensionAPI["registerToolRenderer"]>[0]>>;
+type Data = { kind?: string; text?: string; source?: string; thinking?: string; tools?: string[] };
+
+/**
+ * Collapsed (default): tool rows render nothing, so the summary lines stand in for them.
+ * Expanded (Ctrl+O): tools render normally, and summaries show what they summarized.
+ */
+function registerRenderers(pi: ExtensionAPI, enabled: () => boolean) {
+	pi.registerEntryRenderer<Data>("pi-summarize", (entry, { expanded }, theme) => {
+		const d = entry.data;
+		if (d?.kind !== "activity" || !d.text || !enabled()) return new Container();
+		if (d.source === "fallback" && !expanded) return new Container(); // generic lines add nothing at a glance
+		const box = new Box(1, 0);
+		box.addChild(new Text(`${theme.fg("accent", "◆")} ${theme.fg("muted", d.text)}`, 0, 0));
+		if (expanded) {
+			if (d.thinking) box.addChild(new Text(theme.fg("dim", `  thinking: ${d.thinking.replace(/\s+/g, " ")}`), 0, 0));
+			for (const t of d.tools ?? []) box.addChild(new Text(theme.fg("dim", `  ${t}`), 0, 0));
+		}
+		return box;
+	});
+
+	pi.registerToolRenderer((toolName, next): Renderers | undefined => {
+		const inner = next();
+		if (!enabled()) return inner;
+		// renderShell "self" lets an empty render collapse the row to zero lines; when expanded we draw the shell ourselves.
+		type Theme = Parameters<NonNullable<Renderers["renderCall"]>>[1];
+		const shell = (child: unknown, theme: Theme, ctx: { isPartial: boolean; isError: boolean }) => {
+			const box = new Box(1, 0, (t: string) => theme.bg(ctx.isPartial ? "toolPendingBg" : ctx.isError ? "toolErrorBg" : "toolSuccessBg", t));
+			if (child) box.addChild(child as Text);
+			return box;
+		};
+		return {
+			renderShell: "self",
+			renderCall(args, theme, ctx) {
+				if (!ctx.expanded) return new Container();
+				if (inner?.renderShell === "self") return inner.renderCall?.(args, theme, ctx) ?? new Container();
+				return shell(inner?.renderCall?.(args, theme, { ...ctx, lastComponent: undefined }) ?? new Text(theme.fg("toolTitle", theme.bold(toolName)), 0, 0), theme, ctx);
+			},
+			renderResult(result, opts, theme, ctx) {
+				if (!ctx.expanded) return new Container();
+				if (inner?.renderShell === "self") return inner.renderResult?.(result, opts, theme, ctx) ?? new Container();
+				const text = (result.content as Content[] | undefined)?.filter((c) => c.type === "text").map((c) => c.text).join("\n");
+				const child = inner?.renderResult ? inner.renderResult(result, opts, theme, { ...ctx, lastComponent: undefined }) : text ? new Text(theme.fg("toolOutput", text), 0, 0) : undefined;
+				return shell(child, theme, ctx);
+			},
+		};
+	});
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "pi-summarize",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Pi extension: live one-line activity summaries and auto-titled sessions, using a cheap side model.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "summary",
+    "session-title"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bry-guy/pi-summarize.git"
+  },
+  "homepage": "https://github.com/bry-guy/pi-summarize#readme",
+  "bugs": {
+    "url": "https://github.com/bry-guy/pi-summarize/issues"
+  },
+  "files": [
+    "extensions",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --test test/*.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-tui": "^1.3.0"
+  }
+}

package/src/core.ts

@@ -0,0 +1,349 @@
+// Pure logic for pi-summarize: config, fallback lines, debounced activity tracker, auto-title rules.
+// No pi runtime imports, so it runs under plain `node --test`.
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+export interface SummarizeConfig {
+	/** "provider/id". Undefined means the session's current model. */
+	model?: string;
+	thinking: ThinkingLevel;
+	activity: boolean;
+	title: boolean;
+}
+
+const THINKING_LEVELS: readonly ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"];
+
+const flag = (value: unknown, fallback: boolean): boolean =>
+	value === undefined || value === null ? fallback : !/^(0|false|off|no)$/i.test(String(value));
+
+/** Env (PI_SUMMARIZE_*) wins over the "pi-summarize" key in settings.json. */
+export function resolveConfig(settings: unknown, env: Record<string, string | undefined>): SummarizeConfig {
+	const own = (settings as { "pi-summarize"?: Record<string, unknown> } | undefined)?.["pi-summarize"] ?? {};
+	const model = env.PI_SUMMARIZE_MODEL ?? (typeof own.model === "string" ? own.model : undefined);
+	const thinkingRaw = env.PI_SUMMARIZE_THINKING ?? own.thinking;
+	const thinking = THINKING_LEVELS.find((level) => level === thinkingRaw) ?? "off";
+	return {
+		model: model?.trim() || undefined,
+		thinking,
+		activity: flag(env.PI_SUMMARIZE_ACTIVITY ?? own.activity, true),
+		title: flag(env.PI_SUMMARIZE_TITLE ?? own.title, true),
+	};
+}
+
+export interface ToolActivity {
+	name: string;
+	args?: Record<string, unknown>;
+}
+
+const str = (value: unknown): string | undefined => (typeof value === "string" && value.trim() ? value : undefined);
+const clip = (text: string, max: number): string => {
+	const flat = text.replace(/\s+/g, " ").trim();
+	if (flat.length <= max) return flat;
+	const cut = flat.slice(0, max - 1);
+	const space = cut.lastIndexOf(" ");
+	return `${(space > max / 2 ? cut.slice(0, space) : cut).replace(/[\s.,;:\u2026]+$/, "")}\u2026`;
+};
+const baseName = (path: string): string => path.split("/").filter(Boolean).pop() ?? path;
+
+/** Deterministic line used when the model is unavailable, slow, or fails. */
+export function fallbackLine(tool?: ToolActivity): string {
+	if (!tool) return "Thinking…";
+	const args = tool.args ?? {};
+	const path = str(args.path) ?? str(args.file_path) ?? str(args.file);
+	const name = tool.name.toLowerCase();
+	if (name === "bash") return "Working…"; // the command itself is noise; the model supplies the goal
+	if (name === "read" && path) return `Reading ${baseName(path)}…`;
+	if (name === "edit" && path) return `Editing ${baseName(path)}…`;
+	if (name === "write" && path) return `Writing ${baseName(path)}…`;
+	if (["grep", "find", "glob"].includes(name)) return `Searching ${clip(str(args.pattern) ?? path ?? "files", 30).replace(/…$/, "")}…`;
+	if (name === "ls") return `Listing ${clip(path ?? "files", 30).replace(/…$/, "")}…`;
+	return `Running ${tool.name}…`;
+}
+
+const words = (text: string): Set<string> =>
+	new Set(text.toLowerCase().replace(/[^a-z0-9_\s-]/g, " ").split(/\s+/).filter((w) => w.length > 2));
+
+/** True when two lines say essentially the same thing (word overlap), so the newer one adds nothing. */
+export function similarLine(a: string | undefined, b: string): boolean {
+	if (!a) return false;
+	const x = words(a);
+	const y = words(b);
+	if (!x.size || !y.size) return a.trim() === b.trim();
+	let shared = 0;
+	for (const w of x) if (y.has(w)) shared++;
+	return shared / Math.min(x.size, y.size) >= 0.75;
+}
+
+/** Accept one short line; reject anything over 12 words so the fallback is used instead. */
+export function cleanLine(raw: string): string | undefined {
+	const line = raw
+		.split("\n")
+		.map((s) => s.trim())
+		.find(Boolean)
+		?.replace(/^["'`*#>\-\s]+|["'`*\s]+$/g, "")
+		.replace(/\.+$/, "");
+	if (!line || line.split(/\s+/).length > 12) return undefined;
+	if (/^same$/i.test(line)) return "SAME";
+	return clip(line, 80);
+}
+
+const tail = (text: string, max: number): string => (text.length > max ? text.slice(-max) : text);
+
+export interface ActivityRecord {
+	text: string;
+	at: number;
+	turn: number;
+	source: "model" | "fallback";
+	toolCallIds: string[];
+	/** What the line summarized, for the expanded transcript view. */
+	thinking?: string;
+	tools?: string[];
+}
+
+export interface TrackerOptions {
+	/** Calls the side model. Must reject on failure and honor the signal. */
+	complete(prompt: string, signal: AbortSignal): Promise<string>;
+	/** Shows a line in the working indicator; undefined restores the default. */
+	show(text: string | undefined): void;
+	record(entry: ActivityRecord): void;
+	debounceMs?: number;
+	timeoutMs?: number;
+	/** How long turnEnd waits for the step's live line before using the fallback. */
+	stepWaitMs?: number;
+	/** While a tool runs with no new line, re-show the line with elapsed time this often. 0 disables. */
+	heartbeatMs?: number;
+}
+
+export class ActivityTracker {
+	private userPrompt?: string;
+	private turn = 0;
+	private tools: string[] = [];
+	private lastTool?: ToolActivity;
+	private text = "";
+	private thinking = "";
+	/** The current step (one model turn): its lead-in text, thinking and tool calls. */
+	private step = { text: "", thinking: "", tools: [] as string[], ids: [] as string[] };
+	private timer?: ReturnType<typeof setTimeout>;
+	private inflight?: AbortController;
+	private pending?: Promise<void>;
+	private seq = 0;
+	private last?: string;
+	private lastTurn = -1;
+	private lastSource: ActivityRecord["source"] = "fallback";
+	/** Last recorded breadcrumb; survives across runs so a tool-only step can merge into it. */
+	private crumb?: string;
+	private stale = false;
+	private toolSince?: number;
+	private beat?: ReturnType<typeof setInterval>;
+
+	private readonly opts: TrackerOptions;
+
+	constructor(opts: TrackerOptions) {
+		this.opts = opts;
+	}
+
+	/** New agent run: forget the previous run's activity. */
+	begin(userPrompt?: string): void {
+		this.userPrompt = userPrompt;
+		this.tools = [];
+		this.lastTool = undefined;
+		this.text = "";
+		this.thinking = "";
+	}
+
+	turnStart(turn: number): void {
+		this.turn = turn;
+		this.step = { text: "", thinking: "", tools: [], ids: [] };
+	}
+
+	thinkingDelta(delta: string): void {
+		this.thinking = tail(this.thinking + delta, 400);
+		this.step.thinking = tail(this.step.thinking + delta, 400);
+		this.schedule();
+	}
+
+	textDelta(delta: string): void {
+		this.text = tail(this.text + delta, 600);
+		this.step.text = tail(this.step.text + delta, 600);
+		this.schedule();
+	}
+
+	/** Tool calls are the most informative boundary, so they summarize immediately. */
+	toolStart(toolCallId: string, name: string, args?: Record<string, unknown>): void {
+		this.lastTool = { name, args };
+		this.toolSince = Date.now();
+		this.stale = true; // no heartbeat until this tool's line is decided
+		this.startBeat();
+		const call = `${name}(${clip(JSON.stringify(args ?? {}), 160)})`;
+		this.tools = [...this.tools, call].slice(-4);
+		this.step.tools.push(call);
+		this.step.ids.push(toolCallId);
+		this.kick();
+	}
+
+	toolEnd(): void {
+		this.toolSince = undefined;
+		this.schedule();
+	}
+
+	/**
+	 * A step that ran tools ends: record one breadcrumb where its hidden tool rows sit.
+	 * Waits briefly for the step's live line; a tool-only step with the same goal merges into the previous breadcrumb.
+	 */
+	async turnEnd(): Promise<void> {
+		const step = this.step;
+		const turn = this.turn;
+		if (!step.ids.length) return;
+		this.step = { text: "", thinking: "", tools: [], ids: [] };
+		if (this.pending) {
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			await Promise.race([this.pending, new Promise((r) => (timer = setTimeout(r, this.opts.stepWaitMs ?? 2500)))]);
+			clearTimeout(timer);
+		}
+		const fresh = this.last !== undefined && this.lastTurn === turn;
+		const line = fresh ? (this.last as string) : fallbackLine(this.lastTool);
+		const source = fresh ? this.lastSource : "fallback";
+		const leadIn = step.text.trim() !== "";
+		if (this.crumb && (line === this.crumb || (!leadIn && (source === "fallback" || similarLine(this.crumb, line))))) return;
+		this.crumb = line;
+		this.opts.record({ text: line, at: Date.now(), turn, source, toolCallIds: step.ids, thinking: step.thinking.trim() || undefined, tools: step.tools });
+	}
+
+	/** Keeps the line visibly alive during long tools: same text plus elapsed seconds, display only. */
+	private startBeat(): void {
+		const every = this.opts.heartbeatMs ?? 5000;
+		if (!every || this.beat) return;
+		this.beat = setInterval(() => {
+			if (!this.toolSince || !this.last || this.stale) return;
+			const secs = Math.round((Date.now() - this.toolSince) / 1000);
+			if (secs >= 5) this.opts.show(`${this.last} · ${secs}s`);
+		}, every);
+		(this.beat as { unref?: () => void }).unref?.();
+	}
+
+	/** Agent run ended: drop pending work, cancel in-flight calls, restore the default line. */
+	stop(): void {
+		this.clearTimer();
+		if (this.beat) clearInterval(this.beat);
+		this.beat = undefined;
+		this.toolSince = undefined;
+		this.inflight?.abort();
+		this.inflight = undefined;
+		this.seq++;
+		this.last = undefined;
+		this.opts.show(undefined);
+	}
+
+	/** Max-wait debounce: the first event in a window arms one flush, so long streams still update. */
+	private schedule(): void {
+		if (this.timer) return;
+		this.timer = setTimeout(() => this.kick(), this.opts.debounceMs ?? 2000);
+	}
+
+	private clearTimer(): void {
+		if (this.timer) clearTimeout(this.timer);
+		this.timer = undefined;
+	}
+
+	private kick(): void {
+		this.pending = this.flush();
+	}
+
+	/** Updates the live working line only; breadcrumbs are recorded per step in turnEnd. */
+	private async flush(): Promise<void> {
+		this.clearTimer();
+		const seq = ++this.seq;
+		this.inflight?.abort();
+		const ctl = new AbortController();
+		this.inflight = ctl;
+		const timeout = setTimeout(() => ctl.abort(), this.opts.timeoutMs ?? 10_000);
+		let text: string | undefined;
+		try {
+			text = cleanLine(await this.opts.complete(this.prompt(), ctl.signal));
+		} catch {
+			text = undefined; // fail silently to the fallback below
+		} finally {
+			clearTimeout(timeout);
+		}
+		if (seq !== this.seq) return; // a newer flush or stop() superseded this one
+		this.stale = false;
+		this.inflight = undefined;
+		const same = text?.toUpperCase() === "SAME";
+		this.lastTurn = this.turn;
+		if (same && this.last) return; // the current line still describes this step
+		const line = text && !same ? text : fallbackLine(this.lastTool);
+		this.lastSource = text && !same ? "model" : "fallback";
+		if (line === this.last || (text && similarLine(this.last, line))) return;
+		this.last = line;
+		this.opts.show(line);
+	}
+
+	private prompt(): string {
+		const leadIn = this.step.text.trim();
+		return [
+			"You narrate the GOAL of a coding agent's current step, not the command it runs.",
+			"Infer intent from the agent's lead-in for this step, the user's request, and the step's tool calls.",
+			"Never name a shell command, flag, or tool; say why it is being run.",
+			'Good: "Checking why the sync test fails", "Finding where titles get set", "Skipping re-renders when state is unchanged".',
+			'Bad: "Running git status", "Running bash", "Reading core.ts".',
+			"Reply with ONE line, at most 12 words, present-progressive.",
+			"No quotes, no preamble, no trailing period. Output only the line.",
+			this.crumb ? `Previous step: ${this.crumb}. Describe what is new in this step; do not repeat it.` : "",
+			this.last && !leadIn ? `Current line: ${this.last}\nIf it still describes the work, reply exactly SAME.` : "",
+			"",
+			"<context>",
+			this.userPrompt ? `User asked: ${clip(this.userPrompt, 300)}` : "",
+			leadIn ? `Agent's lead-in for this step: ${clip(leadIn, 400)}` : "",
+			this.tools.length ? `Recent tool calls (latest last): ${this.tools.join("; ")}` : "",
+			!leadIn && this.text.trim() ? `Assistant text tail: ${clip(this.text, 600)}` : "",
+			this.thinking.trim() ? `Thinking tail: ${clip(this.thinking, 300)}` : "",
+			"</context>",
+		]
+			.filter(Boolean)
+			.join("\n");
+	}
+}
+
+/** Strip quotes/punctuation, keep 2–4 words. */
+export function cleanTitle(raw: string): string | undefined {
+	const line = raw
+		.split("\n")
+		.map((s) => s.trim())
+		.find(Boolean)
+		?.replace(/^["'`*#\s]+|["'`*.!?\s]+$/g, "");
+	if (!line) return undefined;
+	return clip(line.split(/\s+/).slice(0, 4).join(" "), 60);
+}
+
+export interface AutoTitleOptions {
+	hasReply: boolean;
+	/** True once pi-summarize has already named this session (see the "title" record). */
+	alreadyTitled: boolean;
+	getName(): string | undefined;
+	setName(name: string): void;
+	record(entry: { kind: "title"; text: string; auto: true; at: number }): void;
+	complete(prompt: string): Promise<string>;
+	firstUser?: string;
+	firstAssistant?: string;
+}
+
+/** Names an unnamed session after its first reply. Never overwrites a name that exists before or during the call. */
+export async function autoTitle(o: AutoTitleOptions): Promise<string | undefined> {
+	if (!o.hasReply || o.alreadyTitled || o.getName()) return undefined;
+	const prompt = [
+		"Give a 2-4 word title for this coding session. Reply with only the title, no quotes.",
+		"",
+		`User: ${clip(o.firstUser ?? "", 500)}`,
+		`Assistant: ${clip(o.firstAssistant ?? "", 500)}`,
+	].join("\n");
+	let title: string | undefined;
+	try {
+		title = cleanTitle(await o.complete(prompt));
+	} catch {
+		return undefined;
+	}
+	if (!title || o.getName()) return undefined;
+	o.setName(title);
+	o.record({ kind: "title", text: title, auto: true, at: Date.now() });
+	return title;
+}