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

package/src/tools/ast-edit.ts

@@ -5,7 +5,7 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
 import { $envpos, prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
-import { computeLineHash, HASHLINE_CONTENT_SEPARATOR } from "../edit/line-hash";
+import { computeLineHash, HL_BODY_SEP } from "../edit/line-hash";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import astEditDescription from "../prompts/tools/ast-edit.md" with { type: "text" };
@@ -20,6 +20,7 @@ import {
 	hasGlobPathChars,
 	normalizePathLikeInput,
 	parseSearchPath,
+	partitionExistingPaths,
 	resolveExplicitSearchPaths,
 	resolveToCwd,
 } from "./path-utils";
@@ -226,13 +227,21 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 				}
 				resolvedPathInputs.push(resource.sourcePath);
 			}
-			if (resolvedPathInputs.length === 1) {
-				const parsedPath = parseSearchPath(resolvedPathInputs[0] ?? ".");
+			let effectivePathInputs = 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(", ")}`);
+				}
+				effectivePathInputs = partition.valid;
+			}
+			if (effectivePathInputs.length === 1) {
+				const parsedPath = parseSearchPath(effectivePathInputs[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(effectivePathInputs, this.session.cwd, globFilter);
 				if (!multiSearchPath) {
 					throw new ToolError("`paths` must contain at least one path or glob");
 				}
@@ -321,7 +330,7 @@ export class AstEditTool implements AgentTool<typeof astEditSchema, AstEditToolD
 					const afterRef = useHashLines
 						? `${change.startLine}${computeLineHash(change.startLine, afterFirstLine)}`
 						: `${change.startLine}:${change.startColumn}`;
-					const lineSeparator = useHashLines ? HASHLINE_CONTENT_SEPARATOR : " ";
+					const lineSeparator = useHashLines ? HL_BODY_SEP : " ";
 					modelOut.push(`-${beforeRef}${lineSeparator}${beforeLine}`);
 					modelOut.push(`+${afterRef}${lineSeparator}${afterLine}`);
 					displayOut.push(formatCodeFrameLine("-", change.startLine, beforeLine, lineNumberWidth));

package/src/tools/ast-grep.ts

@@ -20,6 +20,7 @@ import {
 	hasGlobPathChars,
 	normalizePathLikeInput,
 	parseSearchPath,
+	partitionExistingPaths,
 	resolveExplicitSearchPaths,
 	resolveToCwd,
 } from "./path-utils";
@@ -171,13 +172,21 @@ export class AstGrepTool implements AgentTool<typeof astGrepSchema, AstGrepToolD
 				}
 				resolvedPathInputs.push(resource.sourcePath);
 			}
-			if (resolvedPathInputs.length === 1) {
-				const parsedPath = parseSearchPath(resolvedPathInputs[0] ?? ".");
+			let effectivePathInputs = 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(", ")}`);
+				}
+				effectivePathInputs = partition.valid;
+			}
+			if (effectivePathInputs.length === 1) {
+				const parsedPath = parseSearchPath(effectivePathInputs[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(effectivePathInputs, this.session.cwd, globFilter);
 				if (!multiSearchPath) {
 					throw new ToolError("`paths` must contain at least one path or glob");
 				}

package/src/tools/find.ts

@@ -27,6 +27,7 @@ import {
 	formatPathRelativeToCwd,
 	normalizePathLikeInput,
 	parseFindPattern,
+	partitionExistingPaths,
 	resolveExplicitFindPatterns,
 	resolveToCwd,
 } from "./path-utils";
@@ -59,6 +60,10 @@ export interface FindToolDetails {
 	files?: string[];
 	truncated?: boolean;
 	error?: 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[];
 }
 
 /**
@@ -114,8 +119,23 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 				throw new ToolError("`paths` must contain non-empty globs or paths");
 			}
 
-			const multiPattern = await resolveExplicitFindPatterns(normalizedPatterns, this.session.cwd);
-			const parsedPattern = multiPattern ? null : parseFindPattern(normalizedPatterns[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 — the user explicitly
+			// asked about that one path, so silent empty results would be misleading.
+			let missingPaths: string[] = [];
+			let effectivePatterns = normalizedPatterns;
+			if (normalizedPatterns.length > 1 && !this.#customOps) {
+				const partition = await partitionExistingPaths(normalizedPatterns, this.session.cwd, parseFindPattern);
+				if (partition.valid.length === 0) {
+					throw new ToolError(`Path not found: ${partition.missing.join(", ")}`);
+				}
+				effectivePatterns = partition.valid;
+				missingPaths = partition.missing;
+			}
+
+			const multiPattern = await resolveExplicitFindPatterns(effectivePatterns, this.session.cwd);
+			const parsedPattern = multiPattern ? null : parseFindPattern(effectivePatterns[0] ?? ".");
 			const hasGlob = multiPattern ? true : (parsedPattern?.hasGlob ?? false);
 			const globPattern = multiPattern?.globPattern ?? parsedPattern?.globPattern ?? "**/*";
 			const searchPath = resolveToCwd(multiPattern?.basePath ?? parsedPattern?.basePath ?? ".", this.session.cwd);
@@ -124,7 +144,6 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 			if (searchPath === "/") {
 				throw new ToolError("Searching from root directory '/' is not allowed");
 			}
-
 			const rawLimit = limit ?? DEFAULT_LIMIT;
 			const effectiveLimit = Number.isFinite(rawLimit) ? Math.floor(rawLimit) : Number.NaN;
 			if (!Number.isFinite(effectiveLimit) || effectiveLimit <= 0) {
@@ -141,16 +160,29 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 				});
 			};
 
+			const missingPathsNote =
+				missingPaths.length > 0 ? `Skipped missing paths: ${missingPaths.join(", ")}` : undefined;
+
 			const buildResult = (files: string[]): AgentToolResult<FindToolDetails> => {
 				if (files.length === 0) {
-					const details: FindToolDetails = { scopePath, fileCount: 0, files: [], truncated: false };
-					return toolResult(details).text("No files found matching pattern").done();
+					const details: FindToolDetails = {
+						scopePath,
+						fileCount: 0,
+						files: [],
+						truncated: false,
+						missingPaths: missingPaths.length > 0 ? missingPaths : undefined,
+					};
+					const text = missingPathsNote
+						? `No files found matching pattern\n${missingPathsNote}`
+						: "No files found matching pattern";
+					return toolResult(details).text(text).done();
 				}
 
 				const listLimit = applyListLimit(files, { limit: effectiveLimit });
 				const limited = listLimit.items;
 				const limitMeta = listLimit.meta;
-				const rawOutput = limited.join("\n");
+				const baseOutput = limited.join("\n");
+				const rawOutput = missingPathsNote ? `${baseOutput}\n\n${missingPathsNote}` : baseOutput;
 				const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
 
 				const details: FindToolDetails = {
@@ -160,6 +192,7 @@ export class FindTool implements AgentTool<typeof findSchema, FindToolDetails> {
 					truncated: Boolean(limitMeta.resultLimit || truncation.truncated),
 					resultLimitReached: limitMeta.resultLimit?.reached,
 					truncation: truncation.truncated ? truncation : undefined,
+					missingPaths: missingPaths.length > 0 ? missingPaths : undefined,
 				};
 
 				const resultBuilder = toolResult(details)
@@ -380,12 +413,18 @@ export const findToolRenderer = {
 		const truncated = Boolean(details?.truncated || truncation || details?.resultLimitReached || limits?.resultLimit);
 		const files = details?.files ?? [];
 
+		const missingPaths = details?.missingPaths ?? [];
+		const missingNote =
+			missingPaths.length > 0 ? uiTheme.fg("warning", `skipped missing: ${missingPaths.join(", ")}`) : undefined;
+
 		if (fileCount === 0) {
 			const header = renderStatusLine(
 				{ icon: "warning", title: "Find", description: args?.paths?.join(", "), meta: ["0 files"] },
 				uiTheme,
 			);
-			return new Text([header, formatEmptyMessage("No files found", uiTheme)].join("\n"), 0, 0);
+			const lines = [header, formatEmptyMessage("No files found", uiTheme)];
+			if (missingNote) lines.push(missingNote);
+			return new Text(lines.join("\n"), 0, 0);
 		}
 		const meta: string[] = [formatCount("file", fileCount)];
 		if (details?.scopePath) meta.push(`in ${details.scopePath}`);
@@ -406,6 +445,7 @@ export const findToolRenderer = {
 		if (truncationReasons.length > 0) {
 			extraLines.push(uiTheme.fg("warning", `truncated: ${truncationReasons.join(", ")}`));
 		}
+		if (missingNote) extraLines.push(missingNote);
 
 		let cached: RenderCache | undefined;
 		return {

package/src/tools/gh-renderer.ts

@@ -47,6 +47,9 @@ const OP_TITLES: Record<string, string> = {
 	pr_push: "GitHub PR Push",
 	search_issues: "GitHub Search Issues",
 	search_prs: "GitHub Search PRs",
+	search_code: "GitHub Search Code",
+	search_commits: "GitHub Search Commits",
+	search_repos: "GitHub Search Repos",
 	run_watch: "GitHub Run Watch",
 };
 
@@ -99,11 +102,17 @@ function buildOpMeta(args: GithubToolRenderArgs): string[] {
 			break;
 		}
 		case "search_issues":
-		case "search_prs": {
+		case "search_prs":
+		case "search_code":
+		case "search_commits": {
 			if (args.query) meta.push(truncateVisualWidth(args.query, TRUNCATE_LENGTHS.CONTENT));
 			if (args.repo) meta.push(args.repo);
 			break;
 		}
+		case "search_repos": {
+			if (args.query) meta.push(truncateVisualWidth(args.query, TRUNCATE_LENGTHS.CONTENT));
+			break;
+		}
 		case "repo_view": {
 			if (args.repo) meta.push(args.repo);
 			if (args.branch) meta.push(args.branch);

package/src/tools/gh.ts

@@ -113,6 +113,24 @@ const GH_SEARCH_FIELDS = [
 	"updatedAt",
 	"url",
 ];
+const GH_SEARCH_CODE_FIELDS = ["path", "repository", "sha", "textMatches", "url"];
+const GH_SEARCH_COMMITS_FIELDS = ["author", "commit", "committer", "id", "repository", "sha", "url"];
+const GH_SEARCH_REPOS_FIELDS = [
+	"createdAt",
+	"description",
+	"forksCount",
+	"fullName",
+	"isArchived",
+	"isFork",
+	"isPrivate",
+	"language",
+	"openIssuesCount",
+	"owner",
+	"stargazersCount",
+	"updatedAt",
+	"url",
+	"visibility",
+];
 const SEARCH_LIMIT_DEFAULT = 10;
 const SEARCH_LIMIT_MAX = 50;
 const FILE_PREVIEW_LIMIT = 50;
@@ -139,6 +157,9 @@ const githubSchema = Type.Object({
 			"pr_push",
 			"search_issues",
 			"search_prs",
+			"search_code",
+			"search_commits",
+			"search_repos",
 			"run_watch",
 		],
 		{ description: "github operation" },
@@ -186,11 +207,16 @@ const githubSchema = Type.Object({
 	forceWithLease: Type.Optional(Type.Boolean({ description: "force-with-lease push (pr_push)" })),
 	query: Type.Optional(
 		Type.String({
-			description: "search query (search_issues, search_prs)",
+			description: "search query (search_issues, search_prs, search_code, search_commits, search_repos)",
 			examples: ["is:open label:bug"],
 		}),
 	),
-	limit: Type.Optional(Type.Number({ description: "max results (search_issues, search_prs)", default: 10 })),
+	limit: Type.Optional(
+		Type.Number({
+			description: "max results (search_issues, search_prs, search_code, search_commits, search_repos)",
+			default: 10,
+		}),
+	),
 	run: Type.Optional(Type.String({ description: "actions run id or url (run_watch)", examples: ["123456"] })),
 	tail: Type.Optional(Type.Number({ description: "log lines per failed job (run_watch)", default: 15 })),
 });
@@ -414,6 +440,58 @@ interface GhSearchResult {
 	url?: string;
 }
 
+interface GhSearchCodeTextMatch {
+	fragment?: string;
+	property?: string;
+}
+
+interface GhSearchCodeResult {
+	path?: string;
+	repository?: GhSearchRepository | null;
+	sha?: string;
+	textMatches?: GhSearchCodeTextMatch[];
+	url?: string;
+}
+
+interface GhSearchCommitGitActor {
+	name?: string;
+	email?: string;
+	date?: string;
+}
+
+interface GhSearchCommitDetail {
+	author?: GhSearchCommitGitActor | null;
+	committer?: GhSearchCommitGitActor | null;
+	message?: string;
+}
+
+interface GhSearchCommitResult {
+	author?: GhUser | null;
+	commit?: GhSearchCommitDetail | null;
+	committer?: GhUser | null;
+	id?: string;
+	repository?: GhSearchRepository | null;
+	sha?: string;
+	url?: string;
+}
+
+interface GhSearchRepoResult {
+	createdAt?: string;
+	description?: string | null;
+	forksCount?: number;
+	fullName?: string;
+	isArchived?: boolean;
+	isFork?: boolean;
+	isPrivate?: boolean;
+	language?: string | null;
+	openIssuesCount?: number;
+	owner?: GhUser | null;
+	stargazersCount?: number;
+	updatedAt?: string;
+	url?: string;
+	visibility?: string | null;
+}
+
 interface GhRunReference {
 	repo?: string;
 	runId?: number;
@@ -551,14 +629,25 @@ function appendRepoFlag(args: string[], repo: string | undefined, identifier?: s
 	args.push("--repo", repo);
 }
 
+const SEARCH_FIELDS_BY_COMMAND: Record<"issues" | "prs" | "code" | "commits" | "repos", readonly string[]> = {
+	issues: GH_SEARCH_FIELDS,
+	prs: GH_SEARCH_FIELDS,
+	code: GH_SEARCH_CODE_FIELDS,
+	commits: GH_SEARCH_COMMITS_FIELDS,
+	repos: GH_SEARCH_REPOS_FIELDS,
+};
+
 function buildGhSearchArgs(
-	command: "issues" | "prs",
+	command: "issues" | "prs" | "code" | "commits" | "repos",
 	query: string,
 	limit: number,
 	repo: string | undefined,
 ): string[] {
-	const args = ["search", command, "--limit", String(limit), "--json", GH_SEARCH_FIELDS.join(",")];
-	appendRepoFlag(args, repo);
+	const fields = SEARCH_FIELDS_BY_COMMAND[command];
+	const args = ["search", command, "--limit", String(limit), "--json", fields.join(",")];
+	if (command !== "repos") {
+		appendRepoFlag(args, repo);
+	}
 	args.push("--", query);
 	return args;
 }
@@ -1826,6 +1915,94 @@ function formatSearchResults(
 	return lines.join("\n").trim();
 }
 
+function formatSearchCodeResults(query: string, repo: string | undefined, items: GhSearchCodeResult[]): string {
+	const lines: string[] = [`# GitHub code search`, "", `Query: ${query}`];
+	pushLine(lines, "Repository", repo);
+	pushLine(lines, "Results", items.length);
+
+	if (items.length === 0) {
+		lines.push("");
+		lines.push("No code matches found.");
+		return lines.join("\n").trim();
+	}
+
+	for (const item of items) {
+		lines.push("");
+		lines.push(`- ${item.path ?? "(unknown path)"}`);
+		pushLine(lines, "  Repo", item.repository?.nameWithOwner);
+		pushLine(lines, "  Commit", formatShortSha(item.sha));
+		pushLine(lines, "  URL", item.url);
+		const fragment = item.textMatches?.find(match => match.fragment)?.fragment;
+		if (fragment) {
+			pushLine(lines, "  Match", normalizeText(fragment).split("\n", 1)[0]);
+		}
+	}
+
+	return lines.join("\n").trim();
+}
+
+function formatSearchCommitMessage(message: string | undefined): string | undefined {
+	if (!message) return undefined;
+	const firstLine = normalizeText(message).split("\n", 1)[0];
+	return firstLine || undefined;
+}
+
+function formatSearchCommitsResults(query: string, repo: string | undefined, items: GhSearchCommitResult[]): string {
+	const lines: string[] = [`# GitHub commits search`, "", `Query: ${query}`];
+	pushLine(lines, "Repository", repo);
+	pushLine(lines, "Results", items.length);
+
+	if (items.length === 0) {
+		lines.push("");
+		lines.push("No commits found.");
+		return lines.join("\n").trim();
+	}
+
+	for (const item of items) {
+		lines.push("");
+		const sha = formatShortSha(item.sha) ?? "(unknown sha)";
+		const subject = formatSearchCommitMessage(item.commit?.message) ?? "(no commit message)";
+		lines.push(`- ${sha} ${subject}`);
+		pushLine(lines, "  Repo", item.repository?.nameWithOwner);
+		pushLine(lines, "  Author", formatAuthor(item.author) ?? item.commit?.author?.name);
+		pushLine(lines, "  Date", item.commit?.author?.date ?? item.commit?.committer?.date);
+		pushLine(lines, "  URL", item.url);
+	}
+
+	return lines.join("\n").trim();
+}
+
+function formatSearchReposResults(query: string, items: GhSearchRepoResult[]): string {
+	const lines: string[] = [`# GitHub repositories search`, "", `Query: ${query}`];
+	pushLine(lines, "Results", items.length);
+
+	if (items.length === 0) {
+		lines.push("");
+		lines.push("No repositories found.");
+		return lines.join("\n").trim();
+	}
+
+	for (const item of items) {
+		lines.push("");
+		lines.push(`- ${item.fullName ?? "(unknown repository)"}`);
+		const description = normalizeText(item.description).split("\n", 1)[0];
+		if (description) {
+			pushLine(lines, "  Description", description);
+		}
+		pushLine(lines, "  Language", item.language ?? undefined);
+		pushLine(lines, "  Stars", item.stargazersCount);
+		pushLine(lines, "  Forks", item.forksCount);
+		pushLine(lines, "  Open issues", item.openIssuesCount);
+		pushLine(lines, "  Visibility", item.visibility ?? undefined);
+		pushLine(lines, "  Archived", item.isArchived);
+		pushLine(lines, "  Fork", item.isFork);
+		pushLine(lines, "  Updated", item.updatedAt);
+		pushLine(lines, "  URL", item.url);
+	}
+
+	return lines.join("\n").trim();
+}
+
 async function saveArtifactText(session: ToolSession, toolType: string, text: string): Promise<string | undefined> {
 	const { path: artifactPath, id: artifactId } = (await session.allocateOutputArtifact?.(toolType)) ?? {};
 	if (!artifactPath || !artifactId) {
@@ -1898,6 +2075,12 @@ export class GithubTool implements AgentTool<typeof githubSchema, GhToolDetails>
 					return executeSearchIssues(this.session, params, signal);
 				case "search_prs":
 					return executeSearchPrs(this.session, params, signal);
+				case "search_code":
+					return executeSearchCode(this.session, params, signal);
+				case "search_commits":
+					return executeSearchCommits(this.session, params, signal);
+				case "search_repos":
+					return executeSearchRepos(this.session, params, signal);
 				case "run_watch":
 					return executeRunWatch(this.session, this.name, params, signal, onUpdate);
 			}
@@ -2291,6 +2474,51 @@ async function executeSearchPrs(
 	return buildTextResult(formatSearchResults("pull requests", query, repo, items));
 }
 
+async function executeSearchCode(
+	session: ToolSession,
+	params: GithubInput,
+	signal: AbortSignal | undefined,
+): Promise<AgentToolResult<GhToolDetails>> {
+	const query = requireNonEmpty(params.query, "query");
+	const repo = normalizeOptionalString(params.repo);
+	const limit = resolveSearchLimit(params.limit);
+	const args = buildGhSearchArgs("code", query, limit, repo);
+
+	const items = await git.github.json<GhSearchCodeResult[]>(session.cwd, args, signal, {
+		repoProvided: Boolean(repo),
+	});
+	return buildTextResult(formatSearchCodeResults(query, repo, items));
+}
+
+async function executeSearchCommits(
+	session: ToolSession,
+	params: GithubInput,
+	signal: AbortSignal | undefined,
+): Promise<AgentToolResult<GhToolDetails>> {
+	const query = requireNonEmpty(params.query, "query");
+	const repo = normalizeOptionalString(params.repo);
+	const limit = resolveSearchLimit(params.limit);
+	const args = buildGhSearchArgs("commits", query, limit, repo);
+
+	const items = await git.github.json<GhSearchCommitResult[]>(session.cwd, args, signal, {
+		repoProvided: Boolean(repo),
+	});
+	return buildTextResult(formatSearchCommitsResults(query, repo, items));
+}
+
+async function executeSearchRepos(
+	session: ToolSession,
+	params: GithubInput,
+	signal: AbortSignal | undefined,
+): Promise<AgentToolResult<GhToolDetails>> {
+	const query = requireNonEmpty(params.query, "query");
+	const limit = resolveSearchLimit(params.limit);
+	const args = buildGhSearchArgs("repos", query, limit, undefined);
+
+	const items = await git.github.json<GhSearchRepoResult[]>(session.cwd, args, signal);
+	return buildTextResult(formatSearchReposResults(query, items));
+}
+
 async function executeRunWatch(
 	session: ToolSession,
 	toolName: string,

package/src/tools/hindsight-recall.ts

@@ -0,0 +1,70 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { logger, untilAborted } from "@oh-my-pi/pi-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import { getHindsightSessionState } from "../hindsight/backend";
+import { formatCurrentTime, formatMemories } from "../hindsight/content";
+import recallDescription from "../prompts/tools/recall.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const hindsightRecallSchema = Type.Object({
+	query: Type.String({
+		description: "Natural language search query. Be specific about what you need to know.",
+	}),
+});
+
+export type HindsightRecallParams = Static<typeof hindsightRecallSchema>;
+
+export class HindsightRecallTool implements AgentTool<typeof hindsightRecallSchema> {
+	readonly name = "recall";
+	readonly label = "Recall";
+	readonly description = recallDescription;
+	readonly parameters = hindsightRecallSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): HindsightRecallTool | null {
+		if (session.settings.get("memory.backend") !== "hindsight") return null;
+		return new HindsightRecallTool(session);
+	}
+
+	async execute(_id: string, params: HindsightRecallParams, signal?: AbortSignal): Promise<AgentToolResult> {
+		return untilAborted(signal, async () => {
+			const sessionId = this.session.getSessionId?.();
+			const state = sessionId ? getHindsightSessionState(sessionId) : undefined;
+			if (!state) {
+				throw new Error("Hindsight backend is not initialised for this session.");
+			}
+
+			try {
+				const response = await state.client.recall(state.bankId, params.query, {
+					budget: state.config.recallBudget,
+					maxTokens: state.config.recallMaxTokens,
+					types: state.config.recallTypes.length > 0 ? state.config.recallTypes : undefined,
+					tags: state.recallTags,
+					tagsMatch: state.recallTagsMatch,
+				});
+				const results = response.results ?? [];
+				if (results.length === 0) {
+					return {
+						content: [{ type: "text", text: "No relevant memories found." }],
+						details: {},
+					};
+				}
+				const formatted = formatMemories(results);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Found ${results.length} relevant memories (as of ${formatCurrentTime()} UTC):\n\n${formatted}`,
+						},
+					],
+					details: {},
+				};
+			} catch (err) {
+				logger.warn("recall failed", { bankId: state.bankId, error: String(err) });
+				throw err instanceof Error ? err : new Error(String(err));
+			}
+		});
+	}
+}

package/src/tools/hindsight-reflect.ts

@@ -0,0 +1,57 @@
+import type { AgentTool, AgentToolResult } from "@oh-my-pi/pi-agent-core";
+import { logger, untilAborted } from "@oh-my-pi/pi-utils";
+import { type Static, Type } from "@sinclair/typebox";
+import { getHindsightSessionState } from "../hindsight/backend";
+import { ensureBankMission } from "../hindsight/bank";
+import reflectDescription from "../prompts/tools/reflect.md" with { type: "text" };
+import type { ToolSession } from ".";
+
+const hindsightReflectSchema = Type.Object({
+	query: Type.String({ description: "The question to answer using long-term memory." }),
+	context: Type.Optional(Type.String({ description: "Optional additional context to guide the reflection." })),
+});
+
+export type HindsightReflectParams = Static<typeof hindsightReflectSchema>;
+
+export class HindsightReflectTool implements AgentTool<typeof hindsightReflectSchema> {
+	readonly name = "reflect";
+	readonly label = "Reflect";
+	readonly description = reflectDescription;
+	readonly parameters = hindsightReflectSchema;
+	readonly strict = true;
+
+	constructor(private readonly session: ToolSession) {}
+
+	static createIf(session: ToolSession): HindsightReflectTool | null {
+		if (session.settings.get("memory.backend") !== "hindsight") return null;
+		return new HindsightReflectTool(session);
+	}
+
+	async execute(_id: string, params: HindsightReflectParams, signal?: AbortSignal): Promise<AgentToolResult> {
+		return untilAborted(signal, async () => {
+			const sessionId = this.session.getSessionId?.();
+			const state = sessionId ? getHindsightSessionState(sessionId) : undefined;
+			if (!state) {
+				throw new Error("Hindsight backend is not initialised for this session.");
+			}
+
+			try {
+				await ensureBankMission(state.client, state.bankId, state.config, state.missionsSet);
+				const response = await state.client.reflect(state.bankId, params.query, {
+					context: params.context,
+					budget: state.config.recallBudget,
+					tags: state.recallTags,
+					tagsMatch: state.recallTagsMatch,
+				});
+				const text = response.text?.trim() || "No relevant information found to reflect on.";
+				return {
+					content: [{ type: "text", text }],
+					details: {},
+				};
+			} catch (err) {
+				logger.warn("reflect failed", { bankId: state.bankId, error: String(err) });
+				throw err instanceof Error ? err : new Error(String(err));
+			}
+		});
+	}
+}