@matthewfl/pi-contemplator 0.0.1

package/src/runtime.ts

@@ -0,0 +1,316 @@
+import { type Config, type ConfiguredModel, DEFAULTS, loadConfig } from "./config.js";
+
+export type ResolveResult =
+	| { ok: true; model: unknown; apiKey: string; headers?: Record<string, string> }
+	| { ok: false; reason: string };
+
+type NotifyLevel = "warning" | "info" | "error";
+type Notify = (message: string, type?: NotifyLevel) => void;
+export type ConsolidationPhase = "observer" | "reflector" | "dropper";
+
+export const OM_SETTINGS = "om.settings";
+
+function isConfiguredModel(value: unknown): value is ConfiguredModel {
+	if (!value || typeof value !== "object") return false;
+	const model = value as { provider?: unknown; id?: unknown; thinking?: unknown };
+	return typeof model.provider === "string" && model.provider.length > 0 && typeof model.id === "string" && model.id.length > 0;
+}
+
+function normalizeSessionSettings(settings: SessionSettings, baseConfig: Config): SessionSettings {
+	const normalized = { ...settings };
+	if (normalized.observationsPoolMaxTokens !== undefined && normalized.observationsPoolMaxTokens < 2) {
+		delete normalized.observationsPoolMaxTokens;
+	}
+	const maxTokens = normalized.observationsPoolMaxTokens ?? baseConfig.observationsPoolMaxTokens;
+	const targetTokens = normalized.observationsPoolTargetTokens ?? baseConfig.observationsPoolTargetTokens;
+	if (normalized.observationsPoolMaxTokens !== undefined && targetTokens >= maxTokens) {
+		normalized.observationsPoolTargetTokens = Math.floor(maxTokens / 2);
+	} else if (normalized.observationsPoolTargetTokens !== undefined && normalized.observationsPoolTargetTokens >= maxTokens) {
+		delete normalized.observationsPoolTargetTokens;
+	}
+	return normalized;
+}
+
+export type SessionSettings = Partial<Pick<Config,
+	| "observeAfterTokens" | "reflectAfterTokens" | "observerChunkMaxTokens" | "compactAfterTokens"
+	| "compactAfterTokensMode" | "compactAfterTokensRatio"
+	| "observationsPoolMaxTokens" | "observationsPoolTargetTokens" | "agentMaxTurns"
+	| "showWorkerNotifications" | "passive" | "compactionObserverEnabled" | "contemplatorEnabled" | "reviewerEnabled"
+	| "contemplatorMinNewObservations" | "contemplatorMinNewReflections" | "contemplatorMinTurns" | "debugLog"
+>> & {
+	/** null explicitly means use the configured/session model. */
+	model?: ConfiguredModel | null;
+	contemplatorModel?: ConfiguredModel | null;
+	reviewerModel?: ConfiguredModel | null;
+};
+
+export interface ResolveCtx {
+	model: unknown;
+	modelRegistry: any;
+	hasUI: boolean;
+	ui?: { notify: Notify };
+}
+
+export interface LaunchCtx {
+	hasUI: boolean;
+	ui?: { notify: Notify };
+}
+
+export interface MemoryUpdateCtx extends LaunchCtx {
+	cwd: string;
+	model: unknown;
+	modelRegistry: ResolveCtx["modelRegistry"];
+	sessionManager: { getBranch(): readonly unknown[] };
+}
+
+export interface LlmUsageTotals {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	/** Number of LLM calls contributing to these totals. */
+	runs: number;
+}
+
+export interface LlmUsageInput {
+	input?: number;
+	output?: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+	cost?: { total?: number };
+}
+
+/**
+ * Merge session-scoped settings from branch entries into a plain settings object.
+ * Compaction details.sessionSettings snapshots are point-in-time backups of the
+ * in-memory overlay, which can lag out-of-band om.settings appends, so live
+ * om.settings entries always win: snapshots are applied first, then live entries
+ * last, regardless of branch position. Per-key application means a source only
+ * overwrites keys it actually carries, so snapshot-only keys (whose original
+ * om.settings entries were folded away pre-boundary) are still preserved. Used
+ * both by restoreSessionSettings and by the compaction hook when baking the
+ * snapshot for a new compaction entry, so the two always agree.
+ */
+export function computeSessionSettings(entries: readonly unknown[]): SessionSettings {
+	const restored: SessionSettings = {};
+	const snapshotSources: unknown[] = [];
+	const liveSources: unknown[] = [];
+	for (const entry of entries) {
+		if (!entry || typeof entry !== "object") continue;
+		const candidate = entry as { type?: unknown; customType?: unknown; data?: unknown; details?: unknown };
+		if (candidate.customType === OM_SETTINGS) liveSources.push(candidate.data);
+		if (candidate.type === "compaction" && candidate.details && typeof candidate.details === "object") {
+			snapshotSources.push((candidate.details as { sessionSettings?: unknown }).sessionSettings);
+		}
+	}
+	const applySource = (source: unknown): void => {
+		if (!source || typeof source !== "object") return;
+		const data = source as Record<string, unknown>;
+		const booleanKeys = [
+			"showWorkerNotifications", "passive", "compactionObserverEnabled", "contemplatorEnabled", "reviewerEnabled", "debugLog",
+		] as const;
+		const numberKeys = [
+			"observeAfterTokens", "reflectAfterTokens", "observerChunkMaxTokens", "compactAfterTokens",
+			"observationsPoolMaxTokens", "observationsPoolTargetTokens", "agentMaxTurns",
+			"contemplatorMinNewObservations", "contemplatorMinNewReflections", "contemplatorMinTurns",
+		] as const;
+		for (const key of booleanKeys) if (typeof data[key] === "boolean") restored[key] = data[key];
+		for (const key of numberKeys) if (typeof data[key] === "number" && Number.isInteger(data[key]) && data[key] > 0) restored[key] = data[key];
+		if (data.compactAfterTokensMode === "calibrated" || data.compactAfterTokensMode === "ratio") restored.compactAfterTokensMode = data.compactAfterTokensMode;
+		if (typeof data.compactAfterTokensRatio === "number" && data.compactAfterTokensRatio > 0 && data.compactAfterTokensRatio < 1) restored.compactAfterTokensRatio = data.compactAfterTokensRatio;
+		if (data.model === null) restored.model = null;
+		else if (isConfiguredModel(data.model)) restored.model = data.model;
+		if (data.contemplatorModel === null) restored.contemplatorModel = null;
+		else if (isConfiguredModel(data.contemplatorModel)) restored.contemplatorModel = data.contemplatorModel;
+		if (data.reviewerModel === null) restored.reviewerModel = null;
+		else if (isConfiguredModel(data.reviewerModel)) restored.reviewerModel = data.reviewerModel;
+	};
+	for (const source of snapshotSources) applySource(source);
+	for (const source of liveSources) applySource(source);
+	return restored;
+}
+
+export class Runtime {
+	config: Config = { ...DEFAULTS };
+	private baseConfig: Config = { ...DEFAULTS };
+	private sessionSettings: SessionSettings = {};
+	configLoaded = false;
+	consolidationInFlight = false;
+	consolidationPromise: Promise<void> | null = null;
+	reviewInFlight = false;
+	reviewPromise: Promise<void> | null = null;
+	private memoryUpdateListener: ((ctx: MemoryUpdateCtx) => void) | undefined;
+	private contextGeneration = 0;
+	consolidationPhase: ConsolidationPhase | undefined;
+	compactInFlight = false;
+	compactRequested = false;
+	compactOrigin: "proactive" | "agent-requested" | undefined;
+	compactHookInFlight = false;
+	compactionResumePending = false;
+	compactionResumeGeneration = 0;
+	compactionResumeTimer: ReturnType<typeof setTimeout> | undefined;
+	resolveFailureNotified = false;
+	lastObserverError: string | undefined;
+	lastReflectorError: string | undefined;
+	lastDropperError: string | undefined;
+	agentUsage: LlmUsageTotals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, runs: 0 };
+
+	/** Accumulate usage from one background LLM call (contemplator flush/summary or observer/reflector/dropper run). */
+	recordAgentUsage(usage: LlmUsageInput): void {
+		const totals = this.agentUsage;
+		totals.input += usage.input ?? 0;
+		totals.output += usage.output ?? 0;
+		totals.cacheRead += usage.cacheRead ?? 0;
+		totals.cacheWrite += usage.cacheWrite ?? 0;
+		totals.cost += usage.cost?.total ?? 0;
+		totals.runs += 1;
+	}
+
+	ensureConfig(cwd: string): void {
+		if (this.configLoaded) return;
+		this.baseConfig = loadConfig(cwd);
+		this.config = { ...this.baseConfig };
+		this.configLoaded = true;
+	}
+
+	restoreSessionSettings(entries: readonly unknown[]): void {
+		this.sessionSettings = normalizeSessionSettings(computeSessionSettings(entries), this.baseConfig);
+		this.applySessionSettings();
+	}
+
+	private applySessionSettings(): void {
+		const { model, contemplatorModel, reviewerModel, ...scalarSettings } = this.sessionSettings;
+		this.config = {
+			...this.baseConfig,
+			...scalarSettings,
+			...(model === undefined ? {} : { model: model ?? undefined }),
+			...(contemplatorModel === undefined ? {} : { contemplatorModel: contemplatorModel ?? undefined }),
+			...(reviewerModel === undefined ? {} : { reviewerModel: reviewerModel ?? undefined }),
+		};
+	}
+
+	setSessionSettings(settings: SessionSettings): void {
+		this.sessionSettings = normalizeSessionSettings({ ...this.sessionSettings, ...settings }, this.baseConfig);
+		this.applySessionSettings();
+	}
+
+	getSessionSettings(): SessionSettings {
+		return { ...this.sessionSettings };
+	}
+
+	getDefaultConfig(): Config {
+		return { ...this.baseConfig };
+	}
+
+	advanceContextGeneration(): void {
+		this.contextGeneration++;
+		// A session switch (or reload/shutdown) invalidates any in-flight or pending
+		// compaction state: compactRequested/compactInFlight/compactOrigin were set
+		// against a different branch and would otherwise leak across sessions
+		// (e.g. a request made in session A compacting session B's branch, or a
+		// never-cleared compactInFlight bricking all future compactions).
+		this.compactInFlight = false;
+		this.compactRequested = false;
+		this.compactOrigin = undefined;
+		this.compactionResumePending = false;
+		this.compactionResumeGeneration += 1;
+		if (this.compactionResumeTimer !== undefined) clearTimeout(this.compactionResumeTimer);
+		this.compactionResumeTimer = undefined;
+	}
+
+	getContextGeneration(): number {
+		return this.contextGeneration;
+	}
+
+	async resolveModel(ctx: ResolveCtx & { configuredModel?: ConfiguredModel | null }): Promise<ResolveResult> {
+		let model = ctx.model;
+		const configuredModel = ctx.configuredModel === null
+			? undefined
+			: ctx.configuredModel ?? this.config.model;
+		if (configuredModel) {
+			const configured = ctx.modelRegistry.find(configuredModel.provider, configuredModel.id);
+			if (configured) {
+				model = configured;
+			} else if (ctx.hasUI && ctx.ui) {
+				ctx.ui.notify(
+					`Observational memory: configured model ${configuredModel.provider}/${configuredModel.id} not found, using session model`,
+					"warning",
+				);
+			}
+		}
+		if (!model) return { ok: false, reason: "no model available (session has no model and no observational-memory model configured)" };
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (!auth.ok || !auth.apiKey) {
+			const provider = (model as { provider?: string }).provider ?? "unknown";
+			return { ok: false, reason: `no API key for provider "${provider}"` };
+		}
+		return { ok: true, model, apiKey: auth.apiKey as string, headers: auth.headers as Record<string, string> | undefined };
+	}
+
+	setMemoryUpdateListener(listener: (ctx: MemoryUpdateCtx) => void): void {
+		this.memoryUpdateListener = listener;
+	}
+
+	notifyMemoryUpdate(ctx: MemoryUpdateCtx): void {
+		this.memoryUpdateListener?.(ctx);
+	}
+
+	launchConsolidationTask(ctx: LaunchCtx, work: () => Promise<void>): Promise<void> {
+		this.consolidationInFlight = true;
+		this.consolidationPhase = undefined;
+		this.lastObserverError = undefined;
+		this.lastReflectorError = undefined;
+		this.lastDropperError = undefined;
+		const promise = this.launchTrackedTask(ctx, "consolidation", work, () => {
+			this.consolidationInFlight = false;
+			this.consolidationPhase = undefined;
+			if (this.consolidationPromise === promise) this.consolidationPromise = null;
+		});
+		this.consolidationPromise = promise;
+		return promise;
+	}
+
+	launchReviewTask(ctx: LaunchCtx, work: () => Promise<void>): Promise<void> | undefined {
+		// Structural reviews are intentionally serialized. Pending requests are
+		// persisted in the session ledger and resumed after the active task exits.
+		if (this.reviewInFlight) return undefined;
+		this.reviewInFlight = true;
+		const promise = this.launchTrackedTask(ctx, "structural review", work, () => {
+			this.reviewInFlight = false;
+			if (this.reviewPromise === promise) this.reviewPromise = null;
+		});
+		this.reviewPromise = promise;
+		return promise;
+	}
+
+	recordConsolidationStageError(ctx: LaunchCtx, phase: ConsolidationPhase, error: unknown): string {
+		const message = error instanceof Error ? error.message : String(error);
+		if (phase === "observer") this.lastObserverError = message;
+		if (phase === "reflector") this.lastReflectorError = message;
+		if (phase === "dropper") this.lastDropperError = message;
+		if (ctx.hasUI && ctx.ui) ctx.ui.notify(`Observational memory: ${phase} failed: ${message}`, "warning");
+		return message;
+	}
+
+	private launchTrackedTask(
+		ctx: LaunchCtx,
+		label: string,
+		work: () => Promise<void>,
+		onFinally: (error: string | undefined) => void,
+	): Promise<void> {
+		const hasUI = ctx.hasUI;
+		const ui = ctx.ui;
+		return (async () => {
+			let errorMessage: string | undefined;
+			try {
+				await work();
+			} catch (error) {
+				errorMessage = error instanceof Error ? error.message : String(error);
+				if (hasUI && ui) ui.notify(`Observational memory: ${label} failed: ${errorMessage}`, "warning");
+			} finally {
+				onFinally(errorMessage);
+			}
+		})();
+	}
+}

package/src/serialize.ts

@@ -0,0 +1,274 @@
+import type { Message, TextContent, ToolResultMessage } from "@earendil-works/pi-ai";
+import { estimateStringTokens } from "./tokens.js";
+
+function pad(n: number): string {
+	return n.toString().padStart(2, "0");
+}
+
+function fmtLocal(d: Date): string {
+	return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}`;
+}
+
+function formatTimestamp(v: number | string | undefined): string {
+	if (v === undefined) return "????-??-?? ??:??";
+	const d = new Date(v);
+	return Number.isNaN(d.getTime()) ? "????-??-?? ??:??" : fmtLocal(d);
+}
+
+function formatRecallTimestamp(...values: Array<number | string | undefined>): string {
+	for (const v of values) {
+		if (v === undefined) continue;
+		const d = new Date(v);
+		if (!Number.isNaN(d.getTime())) return fmtLocal(d);
+	}
+	return "Unknown time";
+}
+
+function textAndPlaceholders(
+	content: unknown,
+	options: { omitRedactedThinking?: boolean; includeThinking?: boolean } = {},
+): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "[non-text content omitted]";
+
+	const parts: string[] = [];
+	for (const block of content as Array<Record<string, unknown>>) {
+		if (!block || typeof block !== "object") {
+			parts.push("[non-text content omitted]");
+			continue;
+		}
+		if (block.type === "text" && typeof block.text === "string") {
+			parts.push(block.text);
+			continue;
+		}
+		if (block.type === "thinking") {
+			if (options.omitRedactedThinking && block.redacted === true) continue;
+			if (options.includeThinking && typeof block.thinking === "string") {
+				parts.push(`[thinking: ${block.thinking}]`);
+				continue;
+			}
+			parts.push("[non-text content omitted]");
+			continue;
+		}
+		if (block.type === "toolCall" && typeof block.name === "string") {
+			parts.push(`[${block.name}(${JSON.stringify(block.arguments ?? {})})]`);
+			continue;
+		}
+		parts.push("[non-text content omitted]");
+	}
+	return parts.join("\n");
+}
+
+function textOnly(content: unknown): string {
+	if (content == null) return "";
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.filter((b): b is TextContent => b?.type === "text" && typeof b.text === "string")
+		.map((b) => b.text)
+		.join("\n");
+}
+
+export function serializeConversation(messages: Message[]): string {
+	return messages
+		.map((msg): string | null => {
+			const time = formatTimestamp(msg.timestamp);
+			if (msg.role === "user") {
+				const text = textOnly(msg.content);
+				return `[User @ ${time}]: ${text}`;
+			}
+			if (msg.role === "assistant") {
+				const body = textAndPlaceholders(msg.content, {
+					includeThinking: true,
+					omitRedactedThinking: true,
+				})
+					.split("\n")
+					.filter(Boolean)
+					.join("\n");
+				if (!body) return null;
+				return `[Assistant @ ${time}]: ${body}`;
+			}
+			const text = textOnly(msg.content);
+			return `[Tool result for ${(msg as ToolResultMessage).toolName} @ ${time}]: ${text}`;
+		})
+		.filter((line): line is string => line !== null)
+		.join("\n\n");
+}
+
+export function nowTimestamp(): string {
+	return fmtLocal(new Date());
+}
+
+export const MAX_RECORD_CONTENT_CHARS = 10_000;
+
+export function truncateRecordContent(content: string): string {
+	if (content.length <= MAX_RECORD_CONTENT_CHARS) return content;
+	const head = content.slice(0, MAX_RECORD_CONTENT_CHARS);
+	const dropped = content.length - MAX_RECORD_CONTENT_CHARS;
+	return `${head} … [truncated ${dropped} chars]`;
+}
+
+export type RenderableEntry = {
+	type: string;
+	id?: string;
+	timestamp?: string;
+	message?: unknown;
+	customType?: string;
+	content?: unknown;
+	summary?: unknown;
+};
+
+function renderCustomMessage(entry: RenderableEntry, options: { recallFormat: boolean }): string {
+	const time = options.recallFormat ? formatRecallTimestamp(entry.timestamp) : formatTimestamp(entry.timestamp);
+	const text = options.recallFormat
+		? textAndPlaceholders(entry.content)
+		: typeof entry.content === "string"
+			? entry.content
+			: Array.isArray(entry.content)
+				? (entry.content as Array<{ type?: string; text?: string }>)
+						.filter((b) => b?.type === "text" && typeof b.text === "string")
+						.map((b) => b.text as string)
+						.join("\n")
+				: "";
+	if (options.recallFormat) {
+		const origin = entry.customType ? `Custom message (${entry.customType})` : "Custom message";
+		return `[${origin} @ ${time}]: ${text}`;
+	}
+	const tag = entry.customType ? `Custom (${entry.customType})` : "Custom";
+	return `[${tag} @ ${time}]: ${text}`;
+}
+
+export function serializeBranchEntries(entries: RenderableEntry[]): string {
+	const blocks: string[] = [];
+	for (const entry of entries) {
+		if (entry.type === "message" && entry.message) {
+			const part = serializeConversation([entry.message as Message]);
+			if (part) blocks.push(part);
+			continue;
+		}
+		if (entry.type === "custom_message") {
+			blocks.push(renderCustomMessage(entry, { recallFormat: false }));
+			continue;
+		}
+		if (entry.type === "branch_summary" && typeof entry.summary === "string") {
+			const time = formatTimestamp(entry.timestamp);
+			blocks.push(`[Branch summary @ ${time}]: ${entry.summary}`);
+		}
+	}
+	return blocks.join("\n\n");
+}
+
+export type SourceAddressedSerialization = {
+	text: string;
+	sourceEntryIds: string[];
+	estimatedTokens: number;
+	truncatedSourceEntryIds: string[];
+};
+
+export type SourceAddressedSerializationOptions = {
+	/** Maximum estimated tokens in the final source-addressed text. */
+	maxTokens?: number;
+};
+
+const SOURCE_OMISSION_MARKER =
+	"\n\n[… middle omitted: source exceeds observer input budget; original source remains in the session ledger …]\n\n";
+
+function truncateSourceBlockToTokenBudget(label: string, rendered: string, maxTokens: number): string | undefined {
+	const required = `${label}\n${SOURCE_OMISSION_MARKER}`;
+	if (estimateStringTokens(required) > maxTokens) return undefined;
+	const full = `${label}\n${rendered}`;
+	if (estimateStringTokens(full) <= maxTokens) return full;
+	const maxChars = Math.max(1, maxTokens * 4);
+	const fixed = `${label}\n${SOURCE_OMISSION_MARKER}`;
+	const retainedChars = maxChars - fixed.length;
+	const headChars = Math.ceil(retainedChars / 2);
+	const tailChars = retainedChars - headChars;
+	return `${label}\n${rendered.slice(0, headChars)}${SOURCE_OMISSION_MARKER}${tailChars > 0 ? rendered.slice(-tailChars) : ""}`;
+}
+
+function isSourceRenderableEntry(entry: RenderableEntry): boolean {
+	return entry.type === "message" || entry.type === "custom_message" || entry.type === "branch_summary";
+}
+
+/**
+ * Serialize complete source entries up to the token budget. If the first entry
+ * alone exceeds the budget, include a clearly marked head/tail excerpt so one
+ * pathological tool result cannot permanently block observation coverage.
+ * The original ledger entry is never modified and remains recallable by id.
+ */
+export function serializeSourceAddressedBranchEntries(
+	entries: RenderableEntry[],
+	options: SourceAddressedSerializationOptions = {},
+): SourceAddressedSerialization {
+	const blocks: string[] = [];
+	const sourceEntryIds: string[] = [];
+	const truncatedSourceEntryIds: string[] = [];
+	let estimatedTokens = 0;
+
+	for (const entry of entries) {
+		if (!entry.id || !isSourceRenderableEntry(entry)) continue;
+		const rendered = serializeBranchEntries([entry]);
+		if (!rendered.trim()) continue;
+		const label = `[Source entry id: ${entry.id}]`;
+		const block = `${label}\n${rendered}`;
+		const separator = blocks.length > 0 ? "\n\n" : "";
+		const blockTokens = estimateStringTokens(`${separator}${block}`);
+		const maxTokens = options.maxTokens;
+
+		if (maxTokens !== undefined && estimatedTokens + blockTokens > maxTokens) {
+			if (blocks.length > 0) break;
+			const excerpt = truncateSourceBlockToTokenBudget(label, rendered, maxTokens);
+			if (!excerpt) break;
+			blocks.push(excerpt);
+			sourceEntryIds.push(entry.id);
+			truncatedSourceEntryIds.push(entry.id);
+			estimatedTokens = estimateStringTokens(excerpt);
+			break;
+		}
+
+		blocks.push(block);
+		sourceEntryIds.push(entry.id);
+		estimatedTokens += blockTokens;
+	}
+
+	const text = blocks.join("\n\n");
+	return { text, sourceEntryIds, estimatedTokens: estimateStringTokens(text), truncatedSourceEntryIds };
+}
+
+function renderRecallMessage(entry: RenderableEntry): string | null {
+	if (!entry.message || typeof entry.message !== "object") return null;
+	const msg = entry.message as Message;
+	const time = formatRecallTimestamp(msg.timestamp, entry.timestamp);
+	if (msg.role === "user") {
+		return `[User @ ${time}]: ${textAndPlaceholders(msg.content)}`;
+	}
+	if (msg.role === "assistant") {
+		const body = textAndPlaceholders(msg.content, {
+			includeThinking: true,
+			omitRedactedThinking: true,
+		})
+			.split("\n")
+			.filter(Boolean)
+			.join("\n");
+		if (!body) return null;
+		return `[Assistant @ ${time}]: ${body}`;
+	}
+	return `[Tool result: ${(msg as ToolResultMessage).toolName} @ ${time}]: ${textAndPlaceholders(msg.content)}`;
+}
+
+export function renderRecallSourceEntry(entry: RenderableEntry): string | null {
+	if (entry.type === "message") return renderRecallMessage(entry);
+	if (entry.type === "custom_message") return renderCustomMessage(entry, { recallFormat: true });
+	if (entry.type === "branch_summary" && typeof entry.summary === "string") {
+		const time = formatRecallTimestamp(entry.timestamp);
+		return `[Branch summary @ ${time}]: ${entry.summary}`;
+	}
+	return null;
+}
+
+export function renderRecallSourceEntries(entries: RenderableEntry[]): string {
+	return entries
+		.map(renderRecallSourceEntry)
+		.filter((block): block is string => block !== null && block.trim().length > 0)
+		.join("\n\n");
+}