@oh-my-pi/pi-coding-agent 14.6.1 → 14.6.3

package/src/tools/hindsight-retain.ts

@@ -0,0 +1,63 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { type Static, Type } from "@sinclair/typebox";
+import { getHindsightSessionState } from "../hindsight/backend";
+import { enqueueRetain } from "../hindsight/retain-queue";
+import retainDescription from "../prompts/tools/retain.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const hindsightRetainSchema = Type.Object({
+	items: Type.Array(
+		Type.Object({
+			content: Type.String({
+				description: "The information to remember. Be specific and self-contained — include who, what, when, why.",
+			}),
+			context: Type.Optional(
+				Type.String({ description: "Optional context describing where this information came from." }),
+			),
+		}),
+		{
+			minItems: 1,
+			description:
+				"One or more memories to retain. Batch related facts in a single call rather than calling retain repeatedly — they are deduplicated and consolidated together.",
+		},
+	),
+});
+
+export type HindsightRetainParams = Static<typeof hindsightRetainSchema>;
+export class HindsightRetainTool implements AgentTool<typeof hindsightRetainSchema> {
+	readonly name = "retain";
+	readonly label = "Retain";
+	readonly description = retainDescription;
+	readonly parameters = hindsightRetainSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): HindsightRetainTool | null {
+		if (session.settings.get("memory.backend") !== "hindsight") return null;
+		return new HindsightRetainTool(session);
+	}
+
+	async execute(_id: string, params: HindsightRetainParams): Promise<AgentToolResult> {
+		const sessionId = this.session.getSessionId?.();
+		const state = sessionId ? getHindsightSessionState(sessionId) : undefined;
+		if (!state || !sessionId) {
+			throw new Error("Hindsight backend is not initialised for this session.");
+		}
+
+		// Push every item onto the global 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) {
+			enqueueRetain(sessionId, 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/index.ts

@@ -30,6 +30,9 @@ import { EvalTool } from "./eval";
 import { ExitPlanModeTool } from "./exit-plan-mode";
 import { FindTool } from "./find";
 import { GithubTool } from "./gh";
+import { HindsightRecallTool } from "./hindsight-recall";
+import { HindsightReflectTool } from "./hindsight-reflect";
+import { HindsightRetainTool } from "./hindsight-retain";
 import { InspectImageTool } from "./inspect-image";
 import { IrcTool } from "./irc";
 import { JobTool } from "./job";
@@ -69,6 +72,9 @@ export * from "./eval";
 export * from "./exit-plan-mode";
 export * from "./find";
 export * from "./gh";
+export * from "./hindsight-recall";
+export * from "./hindsight-reflect";
+export * from "./hindsight-retain";
 export * from "./image-gen";
 export * from "./inspect-image";
 export * from "./irc";
@@ -231,6 +237,9 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	web_search: s => new WebSearchTool(s),
 	search_tool_bm25: SearchToolBm25Tool.createIf,
 	write: s => new WriteTool(s),
+	retain: HindsightRetainTool.createIf,
+	recall: HindsightRecallTool.createIf,
+	reflect: HindsightReflectTool.createIf,
 };
 
 export const HIDDEN_TOOLS: Record<string, ToolFactory> = {
@@ -342,6 +351,11 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		) {
 			requestedTools.push("recipe");
 		}
+		if (session.settings.get("memory.backend") === "hindsight") {
+			for (const name of ["recall", "retain", "reflect"]) {
+				if (!requestedTools.includes(name)) requestedTools.push(name);
+			}
+		}
 	}
 	const allTools: Record<string, ToolFactory> = { ...BUILTIN_TOOLS, ...HIDDEN_TOOLS };
 	const isToolAllowed = (name: string) => {
@@ -365,6 +379,9 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "checkpoint" || name === "rewind") return session.settings.get("checkpoint.enabled");
 		if (name === "irc") return session.settings.get("irc.enabled");
 		if (name === "recipe") return session.settings.get("recipe.enabled");
+		if (name === "retain" || name === "recall" || name === "reflect") {
+			return session.settings.get("memory.backend") === "hindsight";
+		}
 		if (name === "task") {
 			const maxDepth = session.settings.get("task.maxRecursionDepth") ?? 2;
 			const currentDepth = session.taskDepth ?? 0;

package/src/tools/output-meta.ts

@@ -465,6 +465,7 @@ async function spillLargeResultToArtifact(
 ): Promise<AgentToolResult> {
 	const sessionManager = context?.sessionManager;
 	if (!sessionManager) return result;
+	if (toolName === "read") return result;
 	const { threshold, tailBytes, tailLines } = getSpillConfig(context?.settings);
 
 	// Skip if tool already saved an artifact

package/src/tools/path-utils.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as url from "node:url";
+import { isEnoent } from "@oh-my-pi/pi-utils";
 
 const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
 const NARROW_NO_BREAK_SPACE = "\u202F";
@@ -442,6 +443,60 @@ export async function resolveExplicitFindPatterns(
 	return resolveFindPatternItems([...new Set(patternItems)], cwd);
 }
 
+/**
+ * Result of partitioning a list of user-supplied paths/globs into entries whose
+ * base directory currently exists on disk versus those that do not.
+ *
+ * Used by multi-path tools (search, find, ast_grep, ast_edit) to tolerate one
+ * or more missing entries in a multi-path call: the surviving entries should
+ * still be searched, with the missing entries surfaced as a non-fatal warning.
+ */
+export interface PartitionedPaths {
+	/** Raw input strings whose resolved base path exists. */
+	valid: string[];
+	/** Raw input strings whose resolved base path is missing (ENOENT). */
+	missing: string[];
+}
+
+/**
+ * Stat each input's base path concurrently; return entries split by existence.
+ *
+ * `splitter` is expected to be {@link parseFindPattern} or
+ * {@link parseSearchPath}: both return a `basePath` field that this helper
+ * resolves against `cwd` and stats. ENOENT is the only swallowed error — every
+ * other stat failure (permission, IO, etc.) propagates so callers do not silently
+ * skip paths that exist but are unreadable.
+ *
+ * Order of `valid` and `missing` follows the input order, so callers can rely
+ * on `valid[0]` matching the first surviving user-supplied entry.
+ */
+export async function partitionExistingPaths(
+	items: string[],
+	cwd: string,
+	splitter: (item: string) => { basePath: string },
+): Promise<PartitionedPaths> {
+	const settled = await Promise.all(
+		items.map(async item => {
+			const { basePath } = splitter(item);
+			const absoluteBasePath = resolveToCwd(basePath, cwd);
+			try {
+				await fs.promises.stat(absoluteBasePath);
+				return { item, exists: true } as const;
+			} catch (err) {
+				if (isEnoent(err)) return { item, exists: false } as const;
+				throw err;
+			}
+		}),
+	);
+	const valid: string[] = [];
+	const missing: string[] = [];
+	for (const entry of settled) {
+		if (entry.exists) valid.push(entry.item);
+		else missing.push(entry.item);
+	}
+	return { valid, missing };
+}
+
 export function resolveReadPath(filePath: string, cwd: string): string {
 	const resolved = resolveToCwd(filePath, cwd);
 	const shellEscapedVariant = tryShellEscapedPath(resolved);

package/src/tools/read.ts

@@ -472,7 +472,7 @@ export class ReadTool implements AgentTool<typeof readSchema, ReadToolDetails> {
 		this.description = prompt.render(readDescription, {
 			DEFAULT_LIMIT: String(this.#defaultLimit),
 			DEFAULT_MAX_LINES: String(DEFAULT_MAX_LINES),
-			IS_HASHLINE_MODE: displayMode.hashLines,
+			IS_HL_MODE: displayMode.hashLines,
 			IS_LINE_NUMBER_MODE: !displayMode.hashLines && displayMode.lineNumbers,
 		});
 	}

package/src/tools/search.ts

@@ -22,6 +22,7 @@ import {
 	hasGlobPathChars,
 	normalizePathLikeInput,
 	parseSearchPath,
+	partitionExistingPaths,
 	resolveExplicitSearchPaths,
 	resolveToCwd,
 } from "./path-utils";
@@ -68,6 +69,10 @@ export interface SearchToolDetails {
 	 * `result.text` lines but uses a `│` gutter and `*` to mark match lines (vs space for
 	 * context). The TUI uses this directly so it never parses model-facing hashline anchors. */
 	displayContent?: string;
+	/** User-supplied paths whose base directory was missing on disk. The tool
+	 * skipped these and continued with the surviving entries; surfaced as a
+	 * non-fatal warning in the renderer and in the model-facing text. */
+	missingPaths?: string[];
 }
 
 type SearchParams = Static<typeof searchSchema>;
@@ -82,7 +87,7 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 	constructor(private readonly session: ToolSession) {
 		const displayMode = resolveFileDisplayMode(session);
 		this.description = prompt.render(searchDescription, {
-			IS_HASHLINE_MODE: displayMode.hashLines,
+			IS_HL_MODE: displayMode.hashLines,
 			IS_LINE_NUMBER_MODE: !displayMode.hashLines && displayMode.lineNumbers,
 		});
 	}
@@ -140,13 +145,26 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 				}
 				resolvedPathInputs.push(resource.sourcePath);
 			}
-			if (resolvedPathInputs.length === 1) {
-				const parsedPath = parseSearchPath(resolvedPathInputs[0] ?? ".");
+			// Tolerate missing entries in a multi-path call: skip ones whose base
+			// directory is gone, and only error if every entry is missing. Single
+			// missing path keeps the original ENOENT semantics.
+			let missingPaths: string[] = [];
+			let effectivePaths = resolvedPathInputs;
+			if (resolvedPathInputs.length > 1) {
+				const partition = await partitionExistingPaths(resolvedPathInputs, this.session.cwd, parseSearchPath);
+				if (partition.valid.length === 0) {
+					throw new ToolError(`Path not found: ${partition.missing.join(", ")}`);
+				}
+				effectivePaths = partition.valid;
+				missingPaths = partition.missing;
+			}
+			if (effectivePaths.length === 1) {
+				const parsedPath = parseSearchPath(effectivePaths[0] ?? ".");
 				searchPath = resolveToCwd(parsedPath.basePath, this.session.cwd);
 				globFilter = parsedPath.glob;
 				scopePath = formatScopePath(searchPath);
 			} else {
-				const multiSearchPath = await resolveExplicitSearchPaths(resolvedPathInputs, this.session.cwd, globFilter);
+				const multiSearchPath = await resolveExplicitSearchPaths(effectivePaths, this.session.cwd, globFilter);
 				if (!multiSearchPath) {
 					throw new ToolError("`paths` must contain at least one path or glob");
 				}
@@ -285,6 +303,8 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 			const limitMessage = `Result limit reached; narrow paths or use skip=${nextSkip}.`;
 			const { record: recordFile, list: fileList } = createFileRecorder();
 			const fileMatchCounts = new Map<string, number>();
+			const missingPathsNote =
+				missingPaths.length > 0 ? `Skipped missing paths: ${missingPaths.join(", ")}` : undefined;
 			if (selectedMatches.length === 0) {
 				const details: SearchToolDetails = {
 					scopePath,
@@ -292,8 +312,10 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 					fileCount: 0,
 					files: [],
 					truncated: false,
+					missingPaths: missingPaths.length > 0 ? missingPaths : undefined,
 				};
-				return toolResult(details).text("No matches found").done();
+				const text = missingPathsNote ? `No matches found\n${missingPathsNote}` : "No matches found";
+				return toolResult(details).text(text).done();
 			}
 			const outputLines: string[] = [];
 			let linesTruncated = false;
@@ -365,6 +387,9 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 			if (matchLimitReached || result.limitReached) {
 				outputLines.push("", limitMessage);
 			}
+			if (missingPathsNote) {
+				outputLines.push("", missingPathsNote);
+			}
 			const rawOutput = outputLines.join("\n");
 			const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
 			const output = truncation.content;
@@ -382,6 +407,7 @@ export class SearchTool implements AgentTool<typeof searchSchema, SearchToolDeta
 				matchLimitReached: matchLimitReached ? effectiveLimit : undefined,
 				resultLimitReached: result.limitReached ? internalLimit : undefined,
 				displayContent: displayLines.join("\n"),
+				missingPaths: missingPaths.length > 0 ? missingPaths : undefined,
 			};
 			if (truncation.truncated) details.truncation = truncation;
 			if (linesTruncated) details.linesTruncated = true;
@@ -487,12 +513,20 @@ export const searchToolRenderer = {
 			details?.truncated || truncation || limits?.matchLimit || limits?.resultLimit || limits?.columnTruncated,
 		);
 
+		const missingPathsList = details?.missingPaths ?? [];
+		const missingNote =
+			missingPathsList.length > 0
+				? uiTheme.fg("warning", `skipped missing: ${missingPathsList.join(", ")}`)
+				: undefined;
+
 		if (matchCount === 0) {
 			const header = renderStatusLine(
 				{ icon: "warning", title: "Search", description: args?.pattern, meta: ["0 matches"] },
 				uiTheme,
 			);
-			return new Text([header, formatEmptyMessage("No matches found", uiTheme)].join("\n"), 0, 0);
+			const lines = [header, formatEmptyMessage("No matches found", uiTheme)];
+			if (missingNote) lines.push(missingNote);
+			return new Text(lines.join("\n"), 0, 0);
 		}
 
 		const summaryParts = [formatCount("match", matchCount), formatCount("file", fileCount)];
@@ -538,8 +572,11 @@ export const searchToolRenderer = {
 		if (limits?.columnTruncated) truncationReasons.push(`line length ${limits.columnTruncated.maxColumn}`);
 		if (truncation?.artifactId) truncationReasons.push(formatFullOutputReference(truncation.artifactId));
 
-		const extraLines =
-			truncationReasons.length > 0 ? [uiTheme.fg("warning", `truncated: ${truncationReasons.join(", ")}`)] : [];
+		const extraLines: string[] = [];
+		if (truncationReasons.length > 0) {
+			extraLines.push(uiTheme.fg("warning", `truncated: ${truncationReasons.join(", ")}`));
+		}
+		if (missingNote) extraLines.push(missingNote);
 
 		let cached: RenderCache | undefined;
 		return {