@matthewfl/pi-contemplator 0.0.1

package/src/agents/reflector/prompts.ts

@@ -0,0 +1,81 @@
+export const REFLECTOR_SYSTEM = `You are the reflection agent for a coding assistant.
+
+These records are the ONLY information the assistant will have about past interactions once the raw conversation is compacted out of context. Anything you fail to preserve may be forgotten. Anything you distort may be remembered wrong. Take this seriously. Over-reflection is also memory distortion: it makes transient details look durable and crowds out the few facts future runs actually need.
+
+Your task is different from the observer's: you are not recording events, you are distilling stable, long-lived facts and patterns from active observations into new reflections by calling record_reflections. Reflections are scarce, expensive durable orientation anchors, not a second observation layer.
+
+You receive:
+- Current reflections: durable facts already crystallized.
+- Current observations: active timestamped evidence lines, each shown as "[id] YYYY-MM-DD HH:MM [relevance] [coverage: none|partial|strong] content".
+- Coverage tiers are review context: none means no current reflection supports the observation id, partial means exactly one current reflection supports it, and strong means two or more current reflections support it. Coverage is not a quota, target, priority score, or instruction to emit reflections.
+
+What to emit:
+- Emit only new durable reflections not already present in current reflections.
+- A good reflection captures meaning that should survive after individual observations are dropped from active compacted memory.
+- High and critical observations deserve careful review, not automatic reflection. Many high observations are still active working evidence and should remain observations until completed, superseded, or generalized into a durable decision, invariant, or rationale.
+- Ignore low observations unless a repeated pattern across many low observations is itself significant.
+- Do not lightly reword existing reflections. Rewording creates a separate reflection, so only use different wording when the durable meaning is materially different, more specific, or corrects/refines an existing reflection.
+- Do not emit update-style records or provenance metadata. Reflections are plain durable facts, not patches.
+- It is fine to emit zero reflections when nothing new is stable enough; in that case do not call the tool and reply briefly.
+
+Decision procedure:
+1. First reject observations that are transient, low-level, partial, routine, or only useful as current working state.
+2. From the remaining observations, identify only durable orientation facts: user preferences, constraints, corrections, decisions, invariants, completed outcomes, long-lived blockers, stable project goals, or rationale that future runs must know.
+3. Apply the future-agent utility test: would a future assistant need this fact automatically in compressed context to avoid a wrong decision, repeated work, or user-preference violation?
+4. If the candidate fails that future-agent utility test, leave it as an observation.
+5. If unsure, emit no reflection.
+
+Abstraction gate:
+- Do not turn each observation into a reflection. Observations are evidence; reflections are compressed durable conclusions.
+- A reflection should usually do at least one of these: combine multiple observations into one durable pattern, preserve a user preference/constraint/correction/decision, record a completed outcome future runs must not redo, or capture durable rationale that explains why a decision was made.
+- Single-observation reflections are allowed when the observation itself contains a durable user preference, constraint, correction, decision, invariant, completed outcome, or long-lived blocker.
+- Do not copy or lightly paraphrase observation lines just because they are high or critical. If the reflection would say nearly the same thing as one observation with a few words removed, usually emit no reflection unless that observation contains a durable user assertion, durable decision, invariant, or completed outcome.
+- Most transient task-log observations, tool status, one-off attempts, files inspected, commands run, failed attempts, partial implementation, and current working state should not become reflections. Let them remain observations until they are completed, superseded, repeated into a pattern, or captured by a higher-value reflection.
+- Prefer fewer, higher-value reflections. It is better to emit zero reflections than to create one reflection per observation.
+
+Focus on:
+- User identity, role, preferences, constraints, and durable corrections.
+- Project goals, architecture, technical decisions, and the rationale behind them.
+- Recurring user behavior or preferences that will matter in future turns.
+- Completed outcomes future runs must not redo.
+- Durable blockers, invariants, and open decisions that should survive compaction.
+
+Support ids and coverage stewardship:
+- Every reflection must include supportingObservationIds from the current observations list.
+- First decide whether the reflection content passes the durable-value bar. Then audit support ids for that already-worthy reflection.
+- supportingObservationIds are a coverage/provenance set and downstream dropper coverage evidence: include all current observation ids whose durable meaning is preserved by the reflection with equivalent fidelity and can later be treated as redundant active-memory detail.
+- supportingObservationIds are not a checklist to cover every observation. Do not add ids merely to improve coverage counts, maximize support ids, maximize strong coverage, or unlock the dropper.
+- False or inflated support ids can cause unsafe downstream dropper pruning, including removal of high-resistance active observations whose meaning was not actually preserved.
+- Include additional observation ids only when the reflection preserves their durable meaning with equivalent fidelity.
+- Leave observations unsupported when their details are still active working state, too specific to compress safely, or not yet durable enough.
+- Do not include observations whose unique exact detail, current task state, user correction, user constraint, or concrete completion is not captured by the reflection.
+- If no candidate reflection passes the durable-value bar, emit zero reflections even when observations have coverage: none.
+- Never invent observation ids. Proposals with missing, empty, or invalid supportingObservationIds are rejected.
+
+User assertions are authoritative. If the observation pool contains both "User stated they use Postgres" and a later "User asked which db they are on", the assertion answers the question — crystallize the assertion, never the question, as the durable fact.
+
+Reflection content rules:
+- Single line of plain prose. No markdown, no bullets, no code fences, no XML/HTML tags, no emojis.
+- No timestamp, no priority marker, no bracketed tags, no "key: value" fields, no JSON.
+- Lead with the fact or pattern; include the reason or mechanism when known so future readers can judge edge cases.
+- Preserve user assertions exactly. Use the user's exact words when non-standard.
+- Preserve named identifiers, paths, commands, package names, error codes, dates, decisions, constraints, and rationale when those details are part of the durable meaning.
+
+Examples:
+- BAD: User discussed databases.
+- GOOD: User stated they use Postgres for the project database.
+- BAD: User asked about database setup.
+- GOOD: User stated they use Postgres for the project database.
+- BAD: User ran npm test and it failed.
+- GOOD: The test suite currently fails because auth middleware rejects expired JWT fixtures.
+- BAD: User prefers React Query.
+- BAD: User switched from SWR.
+- GOOD: User chose React Query over SWR for server-state caching.
+- BAD: completed: edited src/hooks/reflect-drop-trigger.ts.
+- GOOD: completed: V3 reflect/drop coverage now uses raw progress watermarks, so same-turn reflection entries are no longer used as drop progress markers.
+- BAD: npm test passed.
+- GOOD: completed: V3 package namespace migration passed full tests and typecheck.
+- BAD: Observation aaaaaaaaaaaa says the user likes short answers.
+- GOOD: User prefers short answers without generic summaries.
+- ZERO REFLECTIONS: The only new observations are files inspected, commands run, failed attempts, partial implementation, transient debugging, or current working state with no durable conclusion yet.
+- ZERO REFLECTIONS: The only new observations are routine command outputs, transient debugging attempts, or partial work with no durable conclusion yet.`;

package/src/agents/reviewer/agent.ts

@@ -0,0 +1,187 @@
+import { agentLoop, type AgentContext, type AgentLoopConfig, type AgentMessage, type AgentTool } from "@earendil-works/pi-agent-core";
+import type { Message, Model } from "@earendil-works/pi-ai";
+import { streamSimple } from "@earendil-works/pi-ai/compat";
+import { hashId } from "../../ids.js";
+import { boundedMaxTokens, REVIEWER_TOTAL_TOKEN_LIMIT } from "../../model-budget.js";
+import type { LlmUsageInput } from "../../runtime.js";
+import type { Entry, ReviewResult, StructuralReviewRequest } from "../../session-ledger/types.js";
+import { createRecallAgentTool } from "../../tools/recall-observation.js";
+import { createSearchMemoriesAgentTool } from "../../tools/search-memories.js";
+import { logAgentStreamError } from "../stream-errors.js";
+import { createReadChatHistoryAgentTool, createSearchChatHistoryAgentTool } from "./history-tools.js";
+import { buildReviewerSystemPrompt } from "./prompts.js";
+import { createNoProposalTool, createSoftwareProposalTool, createWorkflowProposalTool, type ReviewTerminalResult } from "./tools.js";
+
+export const REVIEWER_KEEP_GOING_MESSAGE =
+	"You have not yet produced a terminal review outcome. Continue investigating the memories and, when you are ready, call exactly one terminal tool: the available proposal tool if a durable conceptual proposal is supported, or review_concluded_no_proposal otherwise. Do not call any terminal tool more than once.";
+
+/** Avoid an expensive live spin when a reviewer repeatedly stops with ordinary text. */
+export const REVIEWER_MAX_INVOCATIONS_PER_LAUNCH = 5;
+
+export interface RunStructuralReviewArgs {
+	request: StructuralReviewRequest;
+	model: Model<any>;
+	apiKey: string;
+	headers?: Record<string, string>;
+	getBranch: () => Entry[];
+	signal?: AbortSignal;
+	agentLoop?: typeof agentLoop;
+	recordUsage?: (usage: LlmUsageInput) => void;
+	/** Receives the reviewer's assistant output for durable debug/view rendering. */
+	onMessages?: (messages: AgentMessage[]) => void;
+	/** Previously persisted reviewer transcript; a non-empty history resumes work. */
+	history?: AgentMessage[];
+}
+
+export function buildReviewRequestMessage(request: StructuralReviewRequest): Message {
+	return {
+		role: "user",
+		content: [{ type: "text", text: `STRUCTURAL REVIEW REQUEST
+
+Review request id:
+${request.id}
+
+Scope:
+${request.scope}
+
+Evidence identified by the contemplator:
+${request.evidence}
+
+Suspected concern:
+${request.concern}
+
+Review focus:
+${request.reviewFocus}
+
+Relevant constraints:
+${request.constraints ?? "(none recorded)"}
+
+Recall the cited memories first. Then search for surrounding, supporting, contrary, and previously proposed material before reaching a conclusion.` }],
+		timestamp: Date.now(),
+	};
+}
+
+function assistantOutputTokens(messages: AgentMessage[]): number {
+	let total = 0;
+	for (const message of messages) {
+		if (message.role !== "assistant") continue;
+		const usage = message.usage as { output?: unknown } | undefined;
+		if (typeof usage?.output === "number" && Number.isFinite(usage.output)) total += Math.max(0, usage.output);
+	}
+	return total;
+}
+
+export async function runStructuralReview(args: RunStructuralReviewArgs): Promise<ReviewResult | undefined> {
+	let terminal: ReviewTerminalResult | undefined;
+	const acceptTerminal = (candidate: ReviewTerminalResult): void => {
+		if (terminal) throw new Error("A structural reviewer may make only one terminal tool call.");
+		terminal = candidate;
+	};
+	const searchMemories = createSearchMemoriesAgentTool(args.getBranch);
+	const recall = createRecallAgentTool(args.getBranch);
+	const searchChatHistory = createSearchChatHistoryAgentTool(args.getBranch);
+	const readChatHistory = createReadChatHistoryAgentTool(args.getBranch);
+	const scopeTool = args.request.scope === "workflow"
+		? createWorkflowProposalTool(acceptTerminal)
+		: createSoftwareProposalTool(acceptTerminal);
+	const noProposal = createNoProposalTool(args.request.scope, acceptTerminal);
+	const tools = [
+		searchMemories as AgentTool<any>,
+		recall as AgentTool<any>,
+		searchChatHistory as AgentTool<any>,
+		readChatHistory as AgentTool<any>,
+		scopeTool as AgentTool<any>,
+		noProposal as AgentTool<any>,
+	];
+	const loop = args.agentLoop ?? agentLoop;
+	const history = [...(args.history ?? [])];
+	// Usage on persisted assistant messages makes this a lifetime request budget,
+	// rather than a fresh allowance on each session/tree resumption.
+	let totalOutputTokens = assistantOutputTokens(history);
+	if (totalOutputTokens >= REVIEWER_TOTAL_TOKEN_LIMIT) return undefined;
+
+	// Persist both the user continuation and the returned messages immediately.
+	// This makes the transcript sufficient to resume a review after shutdown.
+	const runOnce = async (prompt: Message): Promise<number> => {
+		const iterationStartTokens = totalOutputTokens;
+		let streamedOutputTokens = 0;
+		const remainingBudget = () => Math.max(0, REVIEWER_TOTAL_TOKEN_LIMIT - totalOutputTokens);
+		// agentLoop can make several model calls while following tool calls. Wrap its
+		// stream function so every internal response gets only the lifetime budget
+		// remaining after earlier responses, not a fresh per-turn allowance.
+		const budgetedStreamSimple: typeof streamSimple = ((model: Model<any>, context: any, options: any) => {
+			const response = streamSimple(model, context, {
+				...options,
+				maxTokens: boundedMaxTokens(model, remainingBudget()),
+			});
+			let accounted = false;
+			const result = async () => {
+				const message = await response.result();
+				if (!accounted) {
+					accounted = true;
+					const output = assistantOutputTokens([message as AgentMessage]);
+					streamedOutputTokens += output;
+					totalOutputTokens += output;
+				}
+				return message;
+			};
+			return { [Symbol.asyncIterator]: () => response[Symbol.asyncIterator](), result } as ReturnType<typeof streamSimple>;
+		}) as typeof streamSimple;
+		const config: AgentLoopConfig = {
+			model: args.model,
+			apiKey: args.apiKey,
+			headers: args.headers,
+			maxTokens: boundedMaxTokens(args.model, remainingBudget()),
+			convertToLlm: (messages) => messages as Message[],
+			toolExecution: "sequential",
+			shouldStopAfterTurn: () => terminal !== undefined || remainingBudget() === 0,
+		};
+		const promptMessage = prompt as AgentMessage;
+		// agentLoop receives the new prompt separately. Its context must therefore
+		// contain only prior messages, otherwise a resumed prompt is sent twice.
+		const context: AgentContext = { systemPrompt: buildReviewerSystemPrompt(args.request.scope), messages: history.slice(), tools };
+		history.push(promptMessage);
+		args.onMessages?.([promptMessage]);
+		const stream = loop([prompt], context, config, args.signal, budgetedStreamSimple);
+		for await (const event of stream) logAgentStreamError("reviewer", event);
+		const newMessages = await stream.result();
+		history.push(...newMessages);
+		args.onMessages?.(newMessages);
+		const assistants = newMessages.filter((message): message is AgentMessage => message.role === "assistant");
+		if (args.recordUsage) {
+			for (const message of assistants) {
+				const usage = (message as { usage?: LlmUsageInput }).usage;
+				if (usage) args.recordUsage(usage);
+			}
+		}
+		// Injected test loops do not use the supplied stream function. Count any
+		// assistant usage that the real stream wrapper did not already account for.
+		const reportedOutputTokens = assistantOutputTokens(assistants);
+		totalOutputTokens += Math.max(0, reportedOutputTokens - streamedOutputTokens);
+		return totalOutputTokens - iterationStartTokens;
+	};
+
+	let invocations = 0;
+	let progress = await runOnce(history.length === 0
+		? buildReviewRequestMessage(args.request)
+		: { role: "user", content: [{ type: "text", text: REVIEWER_KEEP_GOING_MESSAGE }], timestamp: Date.now() });
+	invocations++;
+
+	// agentLoop already continues through memory/history tool calls. Permit a
+	// small number of explicit retries when it stops with ordinary text, but do
+	// not re-feed an ever-growing transcript until the token budget is exhausted.
+	while (!terminal && progress > 0 && totalOutputTokens < REVIEWER_TOTAL_TOKEN_LIMIT && invocations < REVIEWER_MAX_INVOCATIONS_PER_LAUNCH) {
+		const keepGoing: Message = { role: "user", content: [{ type: "text", text: REVIEWER_KEEP_GOING_MESSAGE }], timestamp: Date.now() };
+		progress = await runOnce(keepGoing);
+		invocations++;
+	}
+	if (!terminal) return undefined;
+	return {
+		...terminal,
+		id: hashId(`${args.request.id}:${JSON.stringify(terminal)}:${Date.now()}`),
+		version: 1,
+		reviewRequestId: args.request.id,
+		createdAt: Date.now(),
+		requestedBy: "contemplator",
+	} as ReviewResult;
+}

package/src/agents/reviewer/history-tools.ts

@@ -0,0 +1,337 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+import {
+  Type,
+  type Message,
+  type ToolResultMessage,
+} from "@earendil-works/pi-ai";
+import type { Static } from "typebox";
+import { renderRecallSourceEntry } from "../../serialize.js";
+import type { Entry } from "../../session-ledger/types.js";
+
+export const SEARCH_CHAT_HISTORY_TOOL_NAME = "search_chat_history";
+export const READ_CHAT_HISTORY_TOOL_NAME = "read_chat_history";
+
+export const SEARCH_CHAT_HISTORY_DESCRIPTION = `Search the primary agent's recorded chat history with a regular expression, newest entries first.
+
+The expression is matched globally against each complete rendered chat entry. Every match is returned separately, so one entry may appear more than once. Matching stops when the limit is reached. Matching is deterministic and does not perform semantic interpretation or relevance ranking. Zero-width matches are returned, with scanning advanced by one Unicode code point afterward.
+
+To include text surrounding a term, put the context in the expression itself, for example .{0,100}target.{0,100}. Dot matches newlines. Results include stable entry ids that can be passed to read_chat_history.`;
+
+export const READ_CHAT_HISTORY_DESCRIPTION = `Read one exact primary-chat entry by the entry id returned from search_chat_history, optionally with preceding and following primary-chat entries for conversational context.`;
+
+export const SEARCH_CHAT_HISTORY_PARAMETERS = Type.Object({
+  pattern: Type.String({
+    minLength: 1,
+    maxLength: 500,
+    description:
+      "Regular expression matched against complete rendered primary-chat entries. Use constructs such as .{0,100}target.{0,100} to return surrounding text.",
+  }),
+  case_sensitive: Type.Optional(
+    Type.Boolean({
+      description: "Whether matching is case-sensitive. Defaults to false.",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: 100,
+      description:
+        "Maximum number of individual matches to return. Defaults to 20.",
+    }),
+  ),
+});
+
+export const READ_CHAT_HISTORY_PARAMETERS = Type.Object({
+  entry_id: Type.String({
+    minLength: 1,
+    description: "Entry identifier returned by search_chat_history.",
+  }),
+  context_before: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      maximum: 10,
+      description:
+        "Number of preceding primary-chat entries to return. Defaults to 0.",
+    }),
+  ),
+  context_after: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      maximum: 10,
+      description:
+        "Number of following primary-chat entries to return. Defaults to 0.",
+    }),
+  ),
+});
+
+export type SearchChatHistoryArgs = Static<
+  typeof SEARCH_CHAT_HISTORY_PARAMETERS
+>;
+export type ReadChatHistoryArgs = Static<typeof READ_CHAT_HISTORY_PARAMETERS>;
+
+export type ChatHistoryMatch = {
+  entryId: string;
+  origin: string;
+  timestamp?: string | number;
+  match: string;
+  start: number;
+  end: number;
+};
+
+export type SearchChatHistoryDetails = {
+  pattern: string;
+  caseSensitive: boolean;
+  limit: number;
+  limitReached: boolean;
+  matches: ChatHistoryMatch[];
+  error?: string;
+};
+
+export type ReadChatHistoryDetails = {
+  entryId: string;
+  contextBefore: number;
+  contextAfter: number;
+  entries: Array<{
+    id: string;
+    origin: string;
+    timestamp?: string | number;
+    selected: boolean;
+    content: string;
+  }>;
+  found: boolean;
+};
+
+type RenderedHistoryEntry = {
+  entry: Entry;
+  text: string;
+  origin: string;
+  timestamp?: string | number;
+};
+
+function messageTimestamp(entry: Entry): string | number | undefined {
+  if (
+    entry.type === "message" &&
+    entry.message &&
+    typeof entry.message === "object"
+  ) {
+    const timestamp = (entry.message as Message).timestamp;
+    if (timestamp !== undefined) return timestamp;
+  }
+  return entry.timestamp;
+}
+
+function entryOrigin(entry: Entry): string {
+  if (
+    entry.type === "message" &&
+    entry.message &&
+    typeof entry.message === "object"
+  ) {
+    const message = entry.message as Message;
+    if (message.role === "user") return "user";
+    if (message.role === "assistant") return "assistant";
+    const toolName = (message as ToolResultMessage).toolName;
+    return `tool result${typeof toolName === "string" && toolName ? `: ${toolName}` : ""}`;
+  }
+  if (entry.type === "custom_message")
+    return entry.customType
+      ? `background message: ${entry.customType}`
+      : "background message";
+  if (entry.type === "branch_summary") return "branch summary";
+  return entry.type;
+}
+
+function historyEntries(entries: Entry[]): RenderedHistoryEntry[] {
+  const rendered: RenderedHistoryEntry[] = [];
+  for (const entry of entries) {
+    const text = renderRecallSourceEntry(entry);
+    if (!text?.trim()) continue;
+    rendered.push({
+      entry,
+      text,
+      origin: entryOrigin(entry),
+      timestamp: messageTimestamp(entry),
+    });
+  }
+  return rendered;
+}
+
+function advanceAfterEmptyMatch(text: string, index: number): number {
+  if (index >= text.length) return index + 1;
+  const first = text.charCodeAt(index);
+  if (first >= 0xd800 && first <= 0xdbff && index + 1 < text.length) {
+    const second = text.charCodeAt(index + 1);
+    if (second >= 0xdc00 && second <= 0xdfff) return index + 2;
+  }
+  return index + 1;
+}
+
+function textResult<T>(text: string, details: T) {
+  return { content: [{ type: "text" as const, text }], details };
+}
+
+export function executeSearchChatHistory(
+  entries: Entry[],
+  args: SearchChatHistoryArgs,
+) {
+  const caseSensitive = args.case_sensitive ?? false;
+  const limit = args.limit ?? 20;
+  let expression: RegExp;
+  try {
+    expression = new RegExp(args.pattern, caseSensitive ? "gsu" : "gisu");
+  } catch (error) {
+    const message = `Invalid regular expression: ${error instanceof Error ? error.message : String(error)}`;
+    return textResult(message, {
+      pattern: args.pattern,
+      caseSensitive,
+      limit,
+      limitReached: false,
+      matches: [],
+      error: message,
+    } satisfies SearchChatHistoryDetails);
+  }
+
+  const matches: ChatHistoryMatch[] = [];
+  let limitReached = false;
+  const searchable = historyEntries(entries);
+  outer: for (
+    let entryIndex = searchable.length - 1;
+    entryIndex >= 0;
+    entryIndex--
+  ) {
+    const item = searchable[entryIndex];
+    expression.lastIndex = 0;
+    while (true) {
+      const match = expression.exec(item.text);
+      if (!match) break;
+      matches.push({
+        entryId: item.entry.id,
+        origin: item.origin,
+        timestamp: item.timestamp,
+        match: match[0],
+        start: match.index,
+        end: match.index + match[0].length,
+      });
+      if (matches.length >= limit) {
+        limitReached = true;
+        break outer;
+      }
+      if (match[0].length === 0)
+        expression.lastIndex = advanceAfterEmptyMatch(
+          item.text,
+          expression.lastIndex,
+        );
+    }
+  }
+
+  const flags = caseSensitive ? "gsu" : "gisu";
+  const lines = [
+    `Pattern /${args.pattern}/${flags} produced ${matches.length} match${matches.length === 1 ? "" : "es"}, newest entries first.`,
+  ];
+  matches.forEach((match, index) => {
+    lines.push(
+      "",
+      `MATCH ${index + 1}`,
+      `Entry: [${match.entryId}]`,
+      `Origin: ${match.origin}`,
+    );
+    if (match.timestamp !== undefined)
+      lines.push(`Time: ${String(match.timestamp)}`);
+    lines.push(
+      `Range: ${match.start}-${match.end}`,
+      "",
+      match.match || "(empty match)",
+    );
+  });
+  if (limitReached)
+    lines.push(
+      "",
+      `Stopped after ${limit} matches. Older matching entries may exist.`,
+    );
+  return textResult(lines.join("\n"), {
+    pattern: args.pattern,
+    caseSensitive,
+    limit,
+    limitReached,
+    matches,
+  } satisfies SearchChatHistoryDetails);
+}
+
+export function executeReadChatHistory(
+  entries: Entry[],
+  args: ReadChatHistoryArgs,
+) {
+  const contextBefore = args.context_before ?? 0;
+  const contextAfter = args.context_after ?? 0;
+  const searchable = historyEntries(entries);
+  const selectedIndex = searchable.findIndex(
+    (item) => item.entry.id === args.entry_id,
+  );
+  if (selectedIndex < 0) {
+    return textResult(
+      `No primary-chat entry with id ${args.entry_id} was found on the current branch.`,
+      {
+        entryId: args.entry_id,
+        contextBefore,
+        contextAfter,
+        entries: [],
+        found: false,
+      } satisfies ReadChatHistoryDetails,
+    );
+  }
+
+  const selected = searchable.slice(
+    Math.max(0, selectedIndex - contextBefore),
+    selectedIndex + contextAfter + 1,
+  );
+  const detailsEntries = selected.map((item) => ({
+    id: item.entry.id,
+    origin: item.origin,
+    timestamp: item.timestamp,
+    selected: item.entry.id === args.entry_id,
+    content: item.text,
+  }));
+  const lines = [
+    `CHAT HISTORY CONTEXT FOR [${args.entry_id}]`,
+    `${selectedIndex - Math.max(0, selectedIndex - contextBefore)} entries before, ${Math.min(searchable.length, selectedIndex + contextAfter + 1) - selectedIndex - 1} entries after`,
+  ];
+  for (const item of detailsEntries) {
+    lines.push(
+      "",
+      `${item.selected ? ">>> " : ""}[${item.id}] ${item.origin}${item.timestamp !== undefined ? ` @ ${String(item.timestamp)}` : ""}`,
+      item.content,
+    );
+  }
+  return textResult(lines.join("\n"), {
+    entryId: args.entry_id,
+    contextBefore,
+    contextAfter,
+    entries: detailsEntries,
+    found: true,
+  } satisfies ReadChatHistoryDetails);
+}
+
+export function createSearchChatHistoryAgentTool(
+  getBranch: () => Entry[],
+): AgentTool<typeof SEARCH_CHAT_HISTORY_PARAMETERS> {
+  return {
+    name: SEARCH_CHAT_HISTORY_TOOL_NAME,
+    label: "Search primary chat history",
+    description: SEARCH_CHAT_HISTORY_DESCRIPTION,
+    parameters: SEARCH_CHAT_HISTORY_PARAMETERS,
+    execute: async (_toolCallId, args) =>
+      executeSearchChatHistory(getBranch(), args),
+  };
+}
+
+export function createReadChatHistoryAgentTool(
+  getBranch: () => Entry[],
+): AgentTool<typeof READ_CHAT_HISTORY_PARAMETERS> {
+  return {
+    name: READ_CHAT_HISTORY_TOOL_NAME,
+    label: "Read primary chat history",
+    description: READ_CHAT_HISTORY_DESCRIPTION,
+    parameters: READ_CHAT_HISTORY_PARAMETERS,
+    execute: async (_toolCallId, args) =>
+      executeReadChatHistory(getBranch(), args),
+  };
+}