@oh-my-pi/pi-coding-agent 15.5.15 → 15.7.0

package/src/tools/memory-render.ts

@@ -0,0 +1,185 @@
+/**
+ * Inline TUI renderers for the long-term memory tools (`retain`, `recall`,
+ * `reflect`).
+ *
+ * These keep the transcript terse — one status line plus, for `retain`, one
+ * `Remember: …` line per stored item — instead of the generic JSON arg tree,
+ * which exploded multi-line memory blobs into an unreadable wall.
+ */
+import type { Component } from "@oh-my-pi/pi-tui";
+import { Text } from "@oh-my-pi/pi-tui";
+import type { RenderResultOptions } from "../extensibility/custom-tools/types";
+import type { Theme } from "../modes/theme/theme";
+import { Ellipsis, renderStatusLine, truncateToWidth } from "../tui";
+import {
+	createCachedComponent,
+	formatErrorMessage,
+	formatExpandHint,
+	PREVIEW_LIMITS,
+	replaceTabs,
+	type ToolUIStatus,
+} from "./render-utils";
+
+// Each stored memory renders as `<bullet> <content>`; the bullet glyph comes
+// from the active theme (`•` by default, a nerd-font dot under nerd themes).
+
+interface RetainRenderArgs {
+	items?: Array<{ content?: string; context?: string }>;
+}
+
+interface QueryRenderArgs {
+	query?: string;
+}
+
+function retainContents(args: RetainRenderArgs | undefined): string[] {
+	return (args?.items ?? []).map(item => replaceTabs((item?.content ?? "").trim())).filter(line => line.length > 0);
+}
+
+function resultText(result: { content?: Array<{ type: string; text?: string }> }): string {
+	return (result.content?.find(c => c.type === "text")?.text ?? "").trim();
+}
+
+/** Single-line query header used by `recall`/`reflect` calls and results. */
+function queryHeader(
+	title: string,
+	query: string | undefined,
+	icon: ToolUIStatus,
+	theme: Theme,
+	meta?: string[],
+): string {
+	const trimmed = replaceTabs((query ?? "").trim());
+	const description = trimmed ? truncateToWidth(trimmed, 80, Ellipsis.Unicode) : undefined;
+	return renderStatusLine({ icon, title, description, meta }, theme);
+}
+
+function retainComponent(contents: string[], header: string, getExpanded: () => boolean, theme: Theme): Component {
+	return createCachedComponent(getExpanded, (width, expanded) => {
+		const lines = [header];
+		const limit = expanded ? contents.length : PREVIEW_LIMITS.COLLAPSED_ITEMS;
+		const shown = contents.slice(0, limit);
+		const bullet = theme.format.bullet;
+		const contentWidth = Math.max(8, width - 2 - Bun.stringWidth(bullet) - 1);
+		for (const content of shown) {
+			const value = truncateToWidth(content, contentWidth, Ellipsis.Unicode);
+			lines.push(`  ${theme.fg("muted", bullet)} ${theme.fg("toolOutput", value)}`);
+		}
+		const remaining = contents.length - shown.length;
+		if (remaining > 0) {
+			lines.push(`  ${theme.fg("dim", `… ${remaining} more`)} ${formatExpandHint(theme, expanded, true)}`);
+		}
+		return lines.map(line => truncateToWidth(line, width, Ellipsis.Omit));
+	});
+}
+
+export const retainToolRenderer = {
+	inline: true,
+	mergeCallAndResult: true,
+	renderCall(args: RetainRenderArgs, options: RenderResultOptions, theme: Theme): Component {
+		const contents = retainContents(args);
+		const header = renderStatusLine({ icon: "pending", title: "Retain" }, theme);
+		return retainComponent(contents, header, () => options.expanded, theme);
+	},
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: { count?: number }; isError?: boolean },
+		options: RenderResultOptions,
+		theme: Theme,
+		args?: RetainRenderArgs,
+	): Component {
+		if (result.isError) {
+			return new Text(formatErrorMessage(resultText(result) || "Retain failed", theme), 0, 0);
+		}
+		const contents = retainContents(args);
+		// `summary` is the tool's own "N memories stored/queued." line; drop the
+		// trailing period so it reads cleanly as a status meta segment.
+		const summary = resultText(result).replace(/\.$/, "");
+		const header = renderStatusLine(
+			{ icon: "success", title: "Retain", meta: summary ? [summary] : undefined },
+			theme,
+		);
+		return retainComponent(contents, header, () => options.expanded, theme);
+	},
+};
+
+export const recallToolRenderer = {
+	inline: true,
+	mergeCallAndResult: true,
+	renderCall(args: QueryRenderArgs, _options: RenderResultOptions, theme: Theme): Component {
+		return new Text(queryHeader("Recall", args.query, "pending", theme), 0, 0);
+	},
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; isError?: boolean },
+		options: RenderResultOptions,
+		theme: Theme,
+		args?: QueryRenderArgs,
+	): Component {
+		if (result.isError) {
+			return new Text(formatErrorMessage(resultText(result) || "Recall failed", theme), 0, 0);
+		}
+		const text = resultText(result);
+		const match = text.match(/^Found (\d+) relevant/);
+		const found = match ? Number(match[1]) : 0;
+		const icon: ToolUIStatus = found > 0 ? "success" : "warning";
+		const meta = [found > 0 ? `${found} found` : "no matches"];
+		const header = queryHeader("Recall", args?.query, icon, theme, meta);
+		if (found === 0) {
+			return new Text(header, 0, 0);
+		}
+		// Collapsed view is the header alone; expand to inspect the recalled
+		// memories without dumping the whole block into the transcript.
+		const body = text.replace(/^[^\n]*\n+/, "");
+		return createCachedComponent(
+			() => options.expanded,
+			(width, expanded) => {
+				const lines = [header];
+				if (expanded) {
+					const bodyLines = body.split("\n").slice(0, PREVIEW_LIMITS.OUTPUT_EXPANDED);
+					for (const line of bodyLines) {
+						lines.push(`  ${theme.fg("muted", replaceTabs(line))}`);
+					}
+				} else {
+					lines.push(`  ${formatExpandHint(theme, false, true)}`);
+				}
+				return lines.map(line => truncateToWidth(line, width, Ellipsis.Omit));
+			},
+		);
+	},
+};
+
+export const reflectToolRenderer = {
+	inline: true,
+	mergeCallAndResult: true,
+	renderCall(args: QueryRenderArgs, _options: RenderResultOptions, theme: Theme): Component {
+		return new Text(queryHeader("Reflect", args.query, "pending", theme), 0, 0);
+	},
+	renderResult(
+		result: { content: Array<{ type: string; text?: string }>; isError?: boolean },
+		options: RenderResultOptions,
+		theme: Theme,
+		args?: QueryRenderArgs,
+	): Component {
+		if (result.isError) {
+			return new Text(formatErrorMessage(resultText(result) || "Reflect failed", theme), 0, 0);
+		}
+		const header = queryHeader("Reflect", args?.query, "success", theme);
+		const answer = resultText(result);
+		const answerLines = answer.split("\n").filter(line => line.trim().length > 0);
+		return createCachedComponent(
+			() => options.expanded,
+			(width, expanded) => {
+				const limit = expanded ? PREVIEW_LIMITS.OUTPUT_EXPANDED : PREVIEW_LIMITS.OUTPUT_COLLAPSED;
+				const shown = answerLines.slice(0, limit);
+				const lines = [header];
+				for (const line of shown) {
+					lines.push(`  ${theme.fg("toolOutput", replaceTabs(line))}`);
+				}
+				const remaining = answerLines.length - shown.length;
+				if (remaining > 0) {
+					lines.push(
+						`  ${theme.fg("dim", `… ${remaining} more lines`)} ${formatExpandHint(theme, expanded, true)}`,
+					);
+				}
+				return lines.map(line => truncateToWidth(line, width, Ellipsis.Omit));
+			},
+		);
+	},
+};

package/src/tools/memory-retain.ts

@@ -0,0 +1,91 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import * as z from "zod/v4";
+import retainDescription from "../prompts/tools/retain.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const memoryRetainSchema = z.object({
+	items: z
+		.array(
+			z.object({
+				content: z.string().describe("information to remember"),
+				context: z.string().describe("source context").optional(),
+			}),
+		)
+		.min(1)
+		.describe("memories to retain"),
+});
+
+export type MemoryRetainParams = z.infer<typeof memoryRetainSchema>;
+export class MemoryRetainTool implements AgentTool<typeof memoryRetainSchema> {
+	readonly name = "retain";
+	readonly approval = "read" as const;
+	readonly label = "Retain";
+	readonly description = retainDescription;
+	readonly parameters = memoryRetainSchema;
+	readonly strict = true;
+	readonly loadMode = "discoverable";
+	readonly summary = "Store important facts in long-term memory";
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): MemoryRetainTool | null {
+		const backend = session.settings.get("memory.backend");
+		if (backend !== "hindsight" && backend !== "mnemosyne") return null;
+		return new MemoryRetainTool(session);
+	}
+
+	async execute(_id: string, params: MemoryRetainParams): Promise<AgentToolResult> {
+		const backend = this.session.settings.get("memory.backend");
+		if (backend === "mnemosyne") {
+			const state = this.session.getMnemosyneSessionState?.();
+			if (!state) {
+				throw new Error("Mnemosyne backend is not initialised for this session.");
+			}
+
+			for (const item of params.items) {
+				state.rememberScoped(item.content, {
+					source: "coding-agent-retain",
+					importance: 0.75,
+					metadata: {
+						session_id: state.sessionId,
+						cwd: state.session.sessionManager.getCwd(),
+						context: item.context ?? null,
+						tool: "retain",
+					},
+					scope: "bank",
+					extract: true,
+					extractEntities: true,
+					veracity: "tool",
+					memoryType: "fact",
+				});
+			}
+
+			const count = params.items.length;
+			const noun = count === 1 ? "memory" : "memories";
+			return {
+				content: [{ type: "text", text: `${count} ${noun} stored.` }],
+				details: { count },
+			};
+		}
+
+		const state = this.session.getHindsightSessionState?.();
+		if (!state) {
+			throw new Error("Hindsight backend is not initialised for this session.");
+		}
+
+		// Push every item onto the session-owned queue and return immediately.
+		// The queue flushes either when it reaches its batch threshold or when
+		// its debounce timer fires. If the eventual batch fails, the queue
+		// surfaces a UI-only warning notice — the LLM is not informed.
+		for (const item of params.items) {
+			state.enqueueRetain(item.content, item.context);
+		}
+
+		const count = params.items.length;
+		const noun = count === 1 ? "memory" : "memories";
+		return {
+			content: [{ type: "text", text: `${count} ${noun} queued.` }],
+			details: { count },
+		};
+	}
+}

package/src/tools/read.ts

@@ -689,6 +689,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 			DEFAULT_MAX_LINES: String(DEFAULT_MAX_LINES),
 			IS_HL_MODE: displayMode.hashLines,
 			IS_LINE_NUMBER_MODE: !displayMode.hashLines && displayMode.lineNumbers,
+			INSPECT_IMAGE_ENABLED: this.#inspectImageEnabled,
 		});
 	}
 

package/src/tools/renderers.ts

@@ -22,8 +22,8 @@ import { findToolRenderer } from "./find";
 import { githubToolRenderer } from "./gh-renderer";
 import { inspectImageToolRenderer } from "./inspect-image-renderer";
 import { jobToolRenderer } from "./job";
+import { recallToolRenderer, reflectToolRenderer, retainToolRenderer } from "./memory-render";
 import { readToolRenderer } from "./read";
-import { recipeToolRenderer } from "./recipe/render";
 import { resolveToolRenderer } from "./resolve";
 import { searchToolRenderer } from "./search";
 import { searchToolBm25Renderer } from "./search-tool-bm25";
@@ -50,7 +50,6 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	ast_edit: astEditToolRenderer as ToolRenderer,
 	bash: bashToolRenderer as ToolRenderer,
 	browser: browserToolRenderer as ToolRenderer,
-	recipe: recipeToolRenderer as ToolRenderer,
 	debug: debugToolRenderer as ToolRenderer,
 	eval: evalToolRenderer as ToolRenderer,
 	edit: editToolRenderer as ToolRenderer,
@@ -62,6 +61,9 @@ export const toolRenderers: Record<string, ToolRenderer> = {
 	read: readToolRenderer as ToolRenderer,
 	job: jobToolRenderer as ToolRenderer,
 	resolve: resolveToolRenderer as ToolRenderer,
+	retain: retainToolRenderer as ToolRenderer,
+	recall: recallToolRenderer as ToolRenderer,
+	reflect: reflectToolRenderer as ToolRenderer,
 	search_tool_bm25: searchToolBm25Renderer as ToolRenderer,
 	ssh: sshToolRenderer as ToolRenderer,
 	task: taskToolRenderer as ToolRenderer,

package/src/tools/todo-write.ts

@@ -35,9 +35,15 @@ export interface TodoPhase {
 	tasks: TodoItem[];
 }
 
+export interface TodoCompletionTransition {
+	phase: string;
+	content: string;
+}
+
 export interface TodoWriteToolDetails {
 	phases: TodoPhase[];
 	storage: "session" | "memory";
+	completedTasks?: TodoCompletionTransition[];
 }
 
 // =============================================================================
@@ -97,6 +103,31 @@ function clonePhases(phases: TodoPhase[]): TodoPhase[] {
 	return phases.map(phase => ({ name: phase.name, tasks: phase.tasks.map(cloneTask) }));
 }
 
+function todoTransitionKey(phase: string, content: string): string {
+	return `${phase}\u0000${content}`;
+}
+
+function getCompletionTransitions(previous: TodoPhase[], updated: TodoPhase[]): TodoCompletionTransition[] {
+	const previousStatuses = new Map<string, TodoStatus>();
+	for (const phase of previous) {
+		for (const task of phase.tasks) {
+			previousStatuses.set(todoTransitionKey(phase.name, task.content), task.status);
+		}
+	}
+
+	const transitions: TodoCompletionTransition[] = [];
+	for (const phase of updated) {
+		for (const task of phase.tasks) {
+			if (task.status !== "completed") continue;
+			const previousStatus = previousStatuses.get(todoTransitionKey(phase.name, task.content));
+			if (previousStatus && previousStatus !== "completed") {
+				transitions.push({ phase: phase.name, content: task.content });
+			}
+		}
+	}
+	return transitions;
+}
+
 function normalizeInProgressTask(phases: TodoPhase[]): void {
 	const orderedTasks = phases.flatMap(phase => phase.tasks);
 	if (orderedTasks.length === 0) return;
@@ -577,13 +608,16 @@ export class TodoWriteTool implements AgentTool<typeof todoWriteSchema, TodoWrit
 		_context?: AgentToolContext,
 	): Promise<AgentToolResult<TodoWriteToolDetails>> {
 		const previousPhases = clonePhases(this.session.getTodoPhases?.() ?? []);
-		const { phases: updated, errors } = applyParams(previousPhases, params);
+		const { phases: updated, errors } = applyParams(clonePhases(previousPhases), params);
+		const completedTasks = getCompletionTransitions(previousPhases, updated);
 		this.session.setTodoPhases?.(updated);
 		const storage = this.session.getSessionFile() ? "session" : "memory";
+		const details: TodoWriteToolDetails = { phases: updated, storage };
+		if (completedTasks.length > 0) details.completedTasks = completedTasks;
 
 		return {
 			content: [{ type: "text", text: formatSummary(updated, errors) }],
-			details: { phases: updated, storage },
+			details,
 			isError: errors.length > 0 ? true : undefined,
 		};
 	}
@@ -667,16 +701,55 @@ function noteMarker(count: number, uiTheme: Theme): string {
 	return uiTheme.fg("dim", chalk.italic(` \u207a${toSuperscript(count)}`));
 }
 
-function formatTodoLine(item: TodoItem, uiTheme: Theme, prefix: string): string {
+export const TODO_WRITE_STRIKE_HOLD_FRAMES = 2;
+export const TODO_WRITE_STRIKE_REVEAL_FRAMES = 12;
+export const TODO_WRITE_STRIKE_TOTAL_FRAMES = TODO_WRITE_STRIKE_HOLD_FRAMES + TODO_WRITE_STRIKE_REVEAL_FRAMES;
+const EMPTY_COMPLETION_KEYS = new Set<string>();
+const STRIKE_START = "\x1b[9m";
+const STRIKE_END = "\x1b[29m";
+
+function strikethroughText(text: string): string {
+	return `${STRIKE_START}${text}${STRIKE_END}`;
+}
+
+function partialStrikethrough(text: string, visibleChars: number): string {
+	if (visibleChars <= 0) return text;
+	const chars = [...text];
+	if (visibleChars >= chars.length) return strikethroughText(text);
+	return `${strikethroughText(chars.slice(0, visibleChars).join(""))}${chars.slice(visibleChars).join("")}`;
+}
+
+function strikeRevealCount(text: string, frame: number | undefined): number | undefined {
+	if (frame === undefined) return undefined;
+	if (frame <= TODO_WRITE_STRIKE_HOLD_FRAMES) return 0;
+	const chars = [...text];
+	if (chars.length === 0) return undefined;
+	const revealFrame = Math.min(frame - TODO_WRITE_STRIKE_HOLD_FRAMES, TODO_WRITE_STRIKE_REVEAL_FRAMES);
+	return Math.ceil((chars.length * revealFrame) / TODO_WRITE_STRIKE_REVEAL_FRAMES);
+}
+
+function formatTodoLine(
+	item: TodoItem,
+	uiTheme: Theme,
+	prefix: string,
+	completionKeys: Set<string>,
+	frame: number | undefined,
+): string {
 	const checkbox = uiTheme.checkbox;
 	const marker = noteMarker(item.notes?.length ?? 0, uiTheme);
 	switch (item.status) {
-		case "completed":
-			return uiTheme.fg("success", `${prefix}${checkbox.checked} ${chalk.strikethrough(item.content)}`) + marker;
+		case "completed": {
+			const revealCount = completionKeys.has(item.content) ? strikeRevealCount(item.content, frame) : undefined;
+			const content =
+				revealCount === undefined
+					? strikethroughText(item.content)
+					: partialStrikethrough(item.content, revealCount);
+			return uiTheme.fg("success", `${prefix}${checkbox.checked} ${content}`) + marker;
+		}
 		case "in_progress":
 			return uiTheme.fg("accent", `${prefix}${checkbox.unchecked} ${item.content}`) + marker;
 		case "abandoned":
-			return uiTheme.fg("error", `${prefix}${checkbox.unchecked} ${chalk.strikethrough(item.content)}`) + marker;
+			return uiTheme.fg("error", `${prefix}${checkbox.unchecked} ${strikethroughText(item.content)}`) + marker;
 		default:
 			return uiTheme.fg("dim", `${prefix}${checkbox.unchecked} ${item.content}`) + marker;
 	}
@@ -722,6 +795,16 @@ export const todoWriteToolRenderer = {
 		_args?: TodoWriteRenderArgs,
 	): Component {
 		const phases = (result.details?.phases ?? []).filter(phase => phase.tasks.length > 0);
+		const completedTasks = result.details?.completedTasks ?? [];
+		const completionKeysByPhase = new Map<string, Set<string>>();
+		for (const task of completedTasks) {
+			let keys = completionKeysByPhase.get(task.phase);
+			if (!keys) {
+				keys = new Set<string>();
+				completionKeysByPhase.set(task.phase, keys);
+			}
+			keys.add(task.content);
+		}
 		const allTasks = phases.flatMap(phase => phase.tasks);
 		const header = renderStatusLine(
 			{ icon: "success", title: "Todo Write", meta: [`${allTasks.length} tasks`] },
@@ -732,29 +815,45 @@ export const todoWriteToolRenderer = {
 			return new Text(`${header}\n${uiTheme.fg("dim", fallback)}`, 0, 0);
 		}
 
-		const { expanded } = options;
-		const lines: string[] = [header];
-		for (let p = 0; p < phases.length; p++) {
-			const phase = phases[p];
-			if (phases.length > 1) {
-				lines.push(uiTheme.fg("accent", chalk.bold(`  ${formatPhaseDisplayName(phase.name, p + 1)}`)));
-			}
-			const treeLines = renderTreeList(
-				{
-					items: phase.tasks,
-					expanded,
-					maxCollapsed: PREVIEW_LIMITS.COLLAPSED_ITEMS,
-					itemType: "todo",
-					renderItem: todo => formatTodoLine(todo, uiTheme, ""),
-				},
-				uiTheme,
-			);
-			for (const line of treeLines) {
-				lines.push(`  ${line}`);
-			}
-		}
-		lines.push(...renderNoteAttachments(phases, uiTheme));
-		return new Text(lines.join("\n"), 0, 0);
+		let cachedKey: string | undefined;
+		let cachedLines: string[] | undefined;
+		return {
+			invalidate(): void {
+				cachedKey = undefined;
+				cachedLines = undefined;
+			},
+			render(width: number): string[] {
+				const { expanded, spinnerFrame } = options;
+				const key = `${expanded ? 1 : 0}:${spinnerFrame ?? -1}:${width}`;
+				if (cachedKey === key && cachedLines) return cachedLines;
+
+				const lines: string[] = [header];
+				for (let p = 0; p < phases.length; p++) {
+					const phase = phases[p];
+					if (phases.length > 1) {
+						lines.push(uiTheme.fg("accent", chalk.bold(`  ${formatPhaseDisplayName(phase.name, p + 1)}`)));
+					}
+					const completionKeys = completionKeysByPhase.get(phase.name) ?? EMPTY_COMPLETION_KEYS;
+					const treeLines = renderTreeList(
+						{
+							items: phase.tasks,
+							expanded,
+							maxCollapsed: PREVIEW_LIMITS.COLLAPSED_ITEMS,
+							itemType: "todo",
+							renderItem: todo => formatTodoLine(todo, uiTheme, "", completionKeys, spinnerFrame),
+						},
+						uiTheme,
+					);
+					for (const line of treeLines) {
+						lines.push(`  ${line}`);
+					}
+				}
+				lines.push(...renderNoteAttachments(phases, uiTheme));
+				cachedKey = key;
+				cachedLines = lines;
+				return lines;
+			},
+		};
 	},
 	mergeCallAndResult: true,
 };

package/src/tools/tool-result.ts

@@ -12,6 +12,7 @@ export class ToolResultBuilder<TDetails extends DetailsWithMeta> {
 	#details: TDetails;
 	#meta = outputMeta();
 	#content: ToolContent = [];
+	#isError = false;
 
 	constructor(details?: TDetails) {
 		this.#details = details ?? ({} as TDetails);
@@ -67,6 +68,12 @@ export class ToolResultBuilder<TDetails extends DetailsWithMeta> {
 		return this;
 	}
 
+	/** Flag the result as a non-throwing failure (agent-loop surfaces it as a tool error). */
+	error(value = true): this {
+		this.#isError = value;
+		return this;
+	}
+
 	done(): AgentToolResult<TDetails> {
 		const meta = this.#meta.get();
 		if (meta) {
@@ -77,6 +84,7 @@ export class ToolResultBuilder<TDetails extends DetailsWithMeta> {
 		return {
 			content: this.#content,
 			details: hasDetails ? this.#details : undefined,
+			...(this.#isError ? { isError: true } : {}),
 		};
 	}
 }

package/src/tui/code-cell.ts

@@ -26,6 +26,8 @@ export interface CodeCellOptions {
 	outputMaxLines?: number;
 	codeMaxLines?: number;
 	expanded?: boolean;
+	/** Animate the cell border with a sweeping segment while pending/running. */
+	animate?: boolean;
 	width: number;
 }
 
@@ -130,7 +132,10 @@ export function renderCodeCell(options: CodeCellOptions, theme: Theme): string[]
 		sections.push({ label: theme.fg("toolTitle", "Output"), lines: outputLines });
 	}
 
-	return renderOutputBlock({ header: title, headerMeta: meta, state, sections, width }, theme);
+	return renderOutputBlock(
+		{ header: title, headerMeta: meta, state, sections, width, animate: options.animate },
+		theme,
+	);
 }
 
 export interface MarkdownCellOptions {