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

package/src/hindsight/content.ts

@@ -0,0 +1,205 @@
+/**
+ * Pure content utilities for the Hindsight backend.
+ *
+ * Ports the semantics of the upstream OpenCode plugin
+ * (vectorize-io/hindsight @ hindsight-integrations/opencode/src/content.ts):
+ *   - tag stripping for anti-feedback (a recalled <memories> block must
+ *     never end up retained as a new memory)
+ *   - recall query composition + truncation under a character budget
+ *   - retention transcript framing
+ */
+
+export interface HindsightMessage {
+	role: string;
+	content: string;
+}
+
+export interface RecallResultLike {
+	text: string;
+	type?: string | null;
+	mentioned_at?: string | null;
+}
+
+const MEMORIES_REGEX = /<memories>[\s\S]*?<\/memories>/g;
+const LEGACY_HINDSIGHT_MEMORIES_REGEX = /<hindsight_memories>[\s\S]*?<\/hindsight_memories>/g;
+const LEGACY_RELEVANT_MEMORIES_REGEX = /<relevant_memories>[\s\S]*?<\/relevant_memories>/g;
+
+/**
+ * Strip `<memories>` and legacy memory blocks.
+ *
+ * The recall path injects these tags into the system prompt; if they leak back
+ * into the retention transcript, every retain becomes a tighter feedback loop
+ * around the same memories. Always strip before retaining.
+ */
+export function stripMemoryTags(content: string): string {
+	return content
+		.replace(MEMORIES_REGEX, "")
+		.replace(LEGACY_HINDSIGHT_MEMORIES_REGEX, "")
+		.replace(LEGACY_RELEVANT_MEMORIES_REGEX, "");
+}
+
+/** Format recall results into a bullet list for context injection. */
+export function formatMemories(results: RecallResultLike[]): string {
+	if (results.length === 0) return "";
+	return results
+		.map(r => {
+			const typeStr = r.type ? ` [${r.type}]` : "";
+			const dateStr = r.mentioned_at ? ` (${r.mentioned_at})` : "";
+			return `- ${r.text}${typeStr}${dateStr}`;
+		})
+		.join("\n\n");
+}
+
+/** Format current UTC time for the recall preamble. */
+export function formatCurrentTime(now: Date = new Date()): string {
+	const y = now.getUTCFullYear();
+	const m = String(now.getUTCMonth() + 1).padStart(2, "0");
+	const d = String(now.getUTCDate()).padStart(2, "0");
+	const h = String(now.getUTCHours()).padStart(2, "0");
+	const min = String(now.getUTCMinutes()).padStart(2, "0");
+	return `${y}-${m}-${d} ${h}:${min}`;
+}
+
+/**
+ * Slice messages to the last N turns, where a turn boundary is a user message.
+ * Returns the trailing tail starting at the (N-th from the end) user message.
+ */
+export function sliceLastTurnsByUserBoundary(messages: HindsightMessage[], turns: number): HindsightMessage[] {
+	if (messages.length === 0 || turns <= 0) return [];
+
+	let userTurnsSeen = 0;
+	let startIndex = -1;
+
+	for (let i = messages.length - 1; i >= 0; i--) {
+		if (messages[i].role === "user") {
+			userTurnsSeen += 1;
+			if (userTurnsSeen >= turns) {
+				startIndex = i;
+				break;
+			}
+		}
+	}
+
+	return startIndex === -1 ? [...messages] : messages.slice(startIndex);
+}
+
+/**
+ * Compose a recall query from the latest user prompt plus optional prior context.
+ *
+ * When `recallContextTurns <= 1` the query is just the trimmed latest prompt.
+ * Otherwise we prepend a `Prior context:` block built from the trailing
+ * `recallContextTurns` user-bounded turns (memory tags stripped, latest prompt
+ * suppressed to avoid duplicating it inside the context block).
+ */
+export function composeRecallQuery(
+	latestQuery: string,
+	messages: HindsightMessage[],
+	recallContextTurns: number,
+): string {
+	const latest = latestQuery.trim();
+	if (recallContextTurns <= 1 || messages.length === 0) return latest;
+
+	const contextual = sliceLastTurnsByUserBoundary(messages, recallContextTurns);
+	const contextLines: string[] = [];
+
+	for (const msg of contextual) {
+		const content = stripMemoryTags(msg.content).trim();
+		if (!content) continue;
+		if (msg.role === "user" && content === latest) continue;
+		contextLines.push(`${msg.role}: ${content}`);
+	}
+
+	if (contextLines.length === 0) return latest;
+	return ["Prior context:", contextLines.join("\n"), latest].join("\n\n");
+}
+
+/**
+ * Truncate a composed recall query to `maxChars`.
+ *
+ * Always preserves the latest user message. Drops oldest context lines first
+ * and degrades gracefully when even the latest message exceeds the budget.
+ */
+export function truncateRecallQuery(query: string, latestQuery: string, maxChars: number): string {
+	if (maxChars <= 0 || query.length <= maxChars) return query;
+
+	const latest = latestQuery.trim();
+	const latestOnly = latest.length > maxChars ? latest.slice(0, maxChars) : latest;
+
+	if (!query.includes("Prior context:")) return latestOnly;
+
+	const contextMarker = "Prior context:\n\n";
+	const markerIndex = query.indexOf(contextMarker);
+	if (markerIndex === -1) return latestOnly;
+
+	const suffix = `\n\n${latest}`;
+	const suffixIndex = query.lastIndexOf(suffix);
+	if (suffixIndex === -1) return latestOnly;
+	if (suffix.length >= maxChars) return latestOnly;
+
+	const contextBody = query.slice(markerIndex + contextMarker.length, suffixIndex);
+	const contextLines = contextBody.split("\n").filter(Boolean);
+
+	const kept: string[] = [];
+	for (let i = contextLines.length - 1; i >= 0; i--) {
+		kept.unshift(contextLines[i]);
+		const candidate = `${contextMarker}${kept.join("\n")}${suffix}`;
+		if (candidate.length > maxChars) {
+			kept.shift();
+			break;
+		}
+	}
+
+	if (kept.length > 0) return `${contextMarker}${kept.join("\n")}${suffix}`;
+	return latestOnly;
+}
+
+export interface RetentionTranscript {
+	transcript: string | null;
+	messageCount: number;
+}
+
+/**
+ * Format messages into a retention transcript using `[role: ...]` markers.
+ *
+ * - When `retainFullWindow` is true, all messages are included (used when the
+ *   caller pre-sliced the window itself).
+ * - Otherwise, only the last user turn (last user message → end) is retained.
+ *
+ * Messages are tag-stripped before framing to break the recall→retain loop.
+ * Returns `{ transcript: null }` when nothing meaningful survives.
+ */
+export function prepareRetentionTranscript(
+	messages: HindsightMessage[],
+	retainFullWindow = false,
+): RetentionTranscript {
+	if (messages.length === 0) return { transcript: null, messageCount: 0 };
+
+	let targetMessages: HindsightMessage[];
+	if (retainFullWindow) {
+		targetMessages = messages;
+	} else {
+		let lastUserIdx = -1;
+		for (let i = messages.length - 1; i >= 0; i--) {
+			if (messages[i].role === "user") {
+				lastUserIdx = i;
+				break;
+			}
+		}
+		if (lastUserIdx === -1) return { transcript: null, messageCount: 0 };
+		targetMessages = messages.slice(lastUserIdx);
+	}
+
+	const parts: string[] = [];
+	for (const msg of targetMessages) {
+		const content = stripMemoryTags(msg.content).trim();
+		if (!content) continue;
+		parts.push(`[role: ${msg.role}]\n${content}\n[${msg.role}:end]`);
+	}
+
+	if (parts.length === 0) return { transcript: null, messageCount: 0 };
+
+	const transcript = parts.join("\n\n");
+	if (transcript.trim().length < 10) return { transcript: null, messageCount: 0 };
+
+	return { transcript, messageCount: parts.length };
+}

package/src/hindsight/index.ts

@@ -0,0 +1,6 @@
+export * from "./backend";
+export * from "./bank";
+export * from "./client";
+export * from "./config";
+export * from "./content";
+export * from "./transcript";

package/src/hindsight/retain-queue.ts

@@ -0,0 +1,166 @@
+/**
+ * Global, debounced batch queue for tool-initiated `retain` calls.
+ *
+ * The `retain` tool used to block on a single-item HTTP round trip per
+ * invocation. Now it pushes onto a per-session queue and returns immediately;
+ * a flush fires when:
+ *   1. the queue reaches `FLUSH_BATCH_SIZE`, or
+ *   2. `FLUSH_INTERVAL_MS` elapses since the queue first became non-empty.
+ *
+ * On batch failure we surface a UI-only notice via `session.emitNotice` —
+ * a single yellow "Hindsight: memory retention failed …" line in the TUI.
+ * The LLM is NOT told; the agent already received "Memory queued" and has
+ * moved on. This is purely so the user knows their facts didn't persist.
+ *
+ * Auto-retain (`retainSession` in backend.ts) is intentionally NOT routed
+ * through this queue — it submits a full transcript as one large item and
+ * already runs `async: true` server-side.
+ */
+
+import { logger } from "@oh-my-pi/pi-utils";
+import { getHindsightSessionState, type HindsightSessionState } from "./backend";
+import { ensureBankMission } from "./bank";
+import type { MemoryItemInput } from "./client";
+
+const FLUSH_BATCH_SIZE = 16;
+const FLUSH_INTERVAL_MS = 5_000;
+
+interface PendingItem {
+	content: string;
+	context?: string;
+}
+
+interface SessionQueue {
+	items: PendingItem[];
+	timer?: NodeJS.Timeout;
+	/** Currently in-flight flush; subsequent flushes await it before running. */
+	flushing?: Promise<void>;
+}
+
+const QUEUES = new Map<string, SessionQueue>();
+
+/** Push a memory item onto the session's retain queue. Returns immediately. */
+export function enqueueRetain(sessionId: string, content: string, context?: string): void {
+	const queue = QUEUES.get(sessionId) ?? createQueue(sessionId);
+	queue.items.push({ content, context });
+
+	if (queue.items.length >= FLUSH_BATCH_SIZE) {
+		void flushSessionQueue(sessionId);
+		return;
+	}
+	if (!queue.timer) {
+		queue.timer = setTimeout(() => {
+			void flushSessionQueue(sessionId);
+		}, FLUSH_INTERVAL_MS);
+		// Don't pin the event loop alive just for a pending retain flush.
+		queue.timer.unref?.();
+	}
+}
+
+/** Flush a single session's queue. Safe to call when empty or already in flight. */
+export async function flushSessionQueue(sessionId: string): Promise<void> {
+	const queue = QUEUES.get(sessionId);
+	if (!queue) return;
+
+	if (queue.timer) {
+		clearTimeout(queue.timer);
+		queue.timer = undefined;
+	}
+
+	if (queue.flushing) {
+		// Coalesce: wait for the in-flight flush, then drain anything that
+		// landed after it started so we don't strand items.
+		await queue.flushing;
+		if (queue.items.length > 0) {
+			await flushSessionQueue(sessionId);
+		}
+		return;
+	}
+
+	if (queue.items.length === 0) {
+		QUEUES.delete(sessionId);
+		return;
+	}
+
+	const items = queue.items.splice(0);
+	const flushPromise = doFlush(sessionId, items);
+	queue.flushing = flushPromise;
+	try {
+		await flushPromise;
+	} finally {
+		queue.flushing = undefined;
+		if (queue.items.length === 0 && !queue.timer) {
+			QUEUES.delete(sessionId);
+		}
+	}
+}
+
+/** Flush every pending session queue. Called from `clear`/`enqueue` backend hooks. */
+export async function flushAllRetainQueues(): Promise<void> {
+	const ids = [...QUEUES.keys()];
+	await Promise.all(ids.map(id => flushSessionQueue(id)));
+}
+
+/** Test helper: clear timers and pending items without triggering flushes. */
+export function clearRetainQueueForTest(): void {
+	for (const queue of QUEUES.values()) {
+		if (queue.timer) clearTimeout(queue.timer);
+	}
+	QUEUES.clear();
+}
+
+/** Test helper: peek at queued count for a session. */
+export function getRetainQueueDepthForTest(sessionId: string): number {
+	return QUEUES.get(sessionId)?.items.length ?? 0;
+}
+
+async function doFlush(sessionId: string, items: PendingItem[]): Promise<void> {
+	const state = getHindsightSessionState(sessionId);
+	if (!state) {
+		// Session went away before we could flush. We can't notify anyone, so
+		// log and drop — these are best-effort facts, not transactional writes.
+		logger.warn("Hindsight retain queue: session vanished, dropping batch", {
+			sessionId,
+			items: items.length,
+		});
+		return;
+	}
+
+	try {
+		await ensureBankMission(state.client, state.bankId, state.config, state.missionsSet);
+		const batch: MemoryItemInput[] = items.map(item => ({
+			content: item.content,
+			context: item.context ?? state.config.retainContext,
+			metadata: { session_id: sessionId },
+			tags: state.retainTags,
+		}));
+		await state.client.retainBatch(state.bankId, batch, { async: true });
+		if (state.config.debug) {
+			logger.debug("Hindsight retain queue: batch flushed", {
+				sessionId,
+				bankId: state.bankId,
+				items: items.length,
+			});
+		}
+	} catch (err) {
+		const errorText = err instanceof Error ? err.message : String(err);
+		logger.warn("Hindsight retain queue: batch flush failed", {
+			sessionId,
+			bankId: state.bankId,
+			items: items.length,
+			error: errorText,
+		});
+		notifyRetainFailure(state, items.length, errorText);
+	}
+}
+
+function notifyRetainFailure(state: HindsightSessionState, count: number, errorText: string): void {
+	const noun = count === 1 ? "memory" : "memories";
+	state.session.emitNotice("warning", `Memory retention failed for ${count} ${noun}: ${errorText}`, "Hindsight");
+}
+
+function createQueue(sessionId: string): SessionQueue {
+	const queue: SessionQueue = { items: [] };
+	QUEUES.set(sessionId, queue);
+	return queue;
+}

package/src/hindsight/transcript.ts

@@ -0,0 +1,71 @@
+/**
+ * Pull plain-text user/assistant messages out of a session manager.
+ *
+ * The Hindsight retain/recall API only takes flat `{role, content}` records,
+ * so we drop tool calls, tool results, bash execution wrappers, custom
+ * messages, and anything else that isn't a primary conversation turn. Each
+ * surviving message's `TextContent` parts are joined with newlines.
+ */
+
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import type { SessionEntry } from "../session/session-manager";
+import type { HindsightMessage } from "./content";
+
+export interface ReadonlySessionManagerLike {
+	getEntries(): SessionEntry[];
+}
+
+/**
+ * Walk session entries top-to-bottom, returning a flat user/assistant list.
+ *
+ * Implementation choices:
+ * - Skip entries whose type isn't `"message"` (compaction, branch_summary,
+ *   custom_message, tool exec records, ...). Those don't represent a
+ *   conversational turn, only the LLM's plain-text utterances do.
+ * - Skip messages whose role isn't `"user"` or `"assistant"`. We deliberately
+ *   ignore `toolResult`, `bashExecution`, `hookMessage`, etc. — they're noise
+ *   for memory purposes.
+ * - For assistant messages, only `text` blocks contribute. Thinking and
+ *   toolCall blocks are intentionally dropped: the user never saw them, so
+ *   retaining them would prime recall on internal monologue.
+ */
+export function extractMessages(sessionManager: ReadonlySessionManagerLike): HindsightMessage[] {
+	const messages: HindsightMessage[] = [];
+
+	for (const entry of sessionManager.getEntries()) {
+		if (entry.type !== "message") continue;
+		const msg = entry.message;
+		const role = msg.role;
+		if (role !== "user" && role !== "assistant") continue;
+
+		const text = role === "user" ? extractUserText(msg) : extractAssistantText(msg as AssistantMessage);
+		if (text.length === 0) continue;
+		messages.push({ role, content: text });
+	}
+
+	return messages;
+}
+
+function extractUserText(msg: { content: unknown }): string {
+	const content = msg.content;
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+
+	const parts: string[] = [];
+	for (const block of content) {
+		if (!block || typeof block !== "object") continue;
+		const maybeText = block as { type?: unknown; text?: unknown };
+		if (maybeText.type === "text" && typeof maybeText.text === "string") {
+			parts.push(maybeText.text);
+		}
+	}
+	return parts.join("\n");
+}
+
+function extractAssistantText(msg: AssistantMessage): string {
+	const parts: string[] = [];
+	for (const block of msg.content) {
+		if (block.type === "text" && block.text) parts.push(block.text);
+	}
+	return parts.join("\n");
+}

package/src/main.ts

@@ -11,9 +11,8 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { createInterface } from "node:readline/promises";
 import type { ImageContent } from "@oh-my-pi/pi-ai";
-import { $env, getConfigDirName, getProjectDir, logger, postmortem, setProjectDir, VERSION } from "@oh-my-pi/pi-utils";
+import { $env, getProjectDir, logger, postmortem, setProjectDir, VERSION } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
-import { invalidate as invalidateFsCache } from "./capability/fs";
 import type { Args } from "./cli/args";
 import { processFileArguments } from "./cli/file-processor";
 import { buildInitialMessage } from "./cli/initial-message";
@@ -25,7 +24,7 @@ import { resolveCliModel, resolveModelRoleValue, resolveModelScope, type ScopedM
 import { getDefault, type SettingPath, Settings, settings } from "./config/settings";
 import { initializeWithSettings } from "./discovery";
 import {
-	clearClaudePluginRootsCache,
+	clearPluginRootsAndCaches,
 	injectPluginDirRoots,
 	preloadPluginRoots,
 	resolveActiveProjectRegistryPath,
@@ -90,6 +89,10 @@ const RPC_DEFAULTED_SETTING_PATHS: SettingPath[] = [
 	"task.maxRecursionDepth",
 	"task.disabledAgents",
 	"task.agentModelOverrides",
+	// Memory subsystems are off-by-default for RPC hosts; embedders that want
+	// memory should opt in explicitly through their own settings layer.
+	"memory.backend",
+	"memories.enabled",
 ];
 
 function applyRpcDefaultSettingOverrides(): void {
@@ -758,13 +761,7 @@ export async function runRootCommand(parsed: Args, rawArgs: string[]): Promise<v
 					projectInstalledRegistryPath: (await resolveActiveProjectRegistryPath(getProjectDir())) ?? undefined,
 					marketplacesCacheDir: getMarketplacesCacheDir(),
 					pluginsCacheDir: getPluginsCacheDir(),
-					clearPluginRootsCache: (extraPaths?: readonly string[]) => {
-						const h = os.homedir();
-						invalidateFsCache(path.join(h, ".claude", "plugins", "installed_plugins.json"));
-						invalidateFsCache(path.join(h, getConfigDirName(), "plugins", "installed_plugins.json"));
-						for (const p of extraPaths ?? []) invalidateFsCache(p);
-						clearClaudePluginRootsCache();
-					},
+					clearPluginRootsCache: clearPluginRootsAndCaches,
 				});
 				await mgr.refreshStaleMarketplaces();
 				const updates = await mgr.checkForUpdates();

package/src/memories/index.ts

@@ -1077,7 +1077,7 @@ async function resolveMemoryModel(options: {
 
 function loadMemoryConfig(settings: Settings): MemoryRuntimeConfig {
 	return {
-		enabled: settings.get("memories.enabled") ?? DEFAULTS.enabled,
+		enabled: settings.get("memory.backend") === "local" || settings.get("memories.enabled") === true,
 		maxRolloutsPerStartup: settings.get("memories.maxRolloutsPerStartup") ?? DEFAULTS.maxRolloutsPerStartup,
 		maxRolloutAgeDays: settings.get("memories.maxRolloutAgeDays") ?? DEFAULTS.maxRolloutAgeDays,
 		minRolloutIdleHours: settings.get("memories.minRolloutIdleHours") ?? DEFAULTS.minRolloutIdleHours,

package/src/memory-backend/index.ts

@@ -0,0 +1,4 @@
+export * from "./local-backend";
+export * from "./off-backend";
+export * from "./resolve";
+export * from "./types";

package/src/memory-backend/local-backend.ts

@@ -0,0 +1,30 @@
+import {
+	buildMemoryToolDeveloperInstructions,
+	clearMemoryData,
+	enqueueMemoryConsolidation,
+	startMemoryStartupTask,
+} from "../memories";
+import type { MemoryBackend } from "./types";
+
+/**
+ * Wraps the existing `memories/` module as a `MemoryBackend`.
+ *
+ * No behavioural change — every call delegates to the legacy entry points so
+ * the local memory pipeline (rollout summarisation → SQLite → memory_summary.md)
+ * keeps working exactly as before.
+ */
+export const localBackend: MemoryBackend = {
+	id: "local",
+	start(options) {
+		startMemoryStartupTask(options);
+	},
+	async buildDeveloperInstructions(agentDir, settings) {
+		return buildMemoryToolDeveloperInstructions(agentDir, settings);
+	},
+	async clear(agentDir, cwd) {
+		await clearMemoryData(agentDir, cwd);
+	},
+	async enqueue(agentDir, cwd) {
+		enqueueMemoryConsolidation(agentDir, cwd);
+	},
+};

package/src/memory-backend/off-backend.ts

@@ -0,0 +1,16 @@
+import type { MemoryBackend } from "./types";
+
+/**
+ * No-op memory backend.
+ *
+ * Selected when `memory.backend` is `"off"`.
+ */
+export const offBackend: MemoryBackend = {
+	id: "off",
+	async start() {},
+	async buildDeveloperInstructions() {
+		return undefined;
+	},
+	async clear() {},
+	async enqueue() {},
+};

package/src/memory-backend/resolve.ts

@@ -0,0 +1,24 @@
+import type { Settings } from "../config/settings";
+import { hindsightBackend } from "../hindsight";
+import { localBackend } from "./local-backend";
+import { offBackend } from "./off-backend";
+import type { MemoryBackend } from "./types";
+
+/**
+ * Pick the active memory backend for a Settings instance.
+ *
+ * Selection rules (single source of truth — every memory consumer routes
+ * through this):
+ *   - `memory.backend === "hindsight"`  → Hindsight remote memory
+ *   - `memory.backend === "local"`      → local pipeline
+ *   - everything else                   → no-op
+ *
+ * `memories.enabled` remains accepted only as a legacy migration input. Once
+ * a config is loaded, `memory.backend` is the sole runtime selector.
+ */
+export function resolveMemoryBackend(settings: Settings): MemoryBackend {
+	const id = settings.get("memory.backend");
+	if (id === "hindsight") return hindsightBackend;
+	if (id === "local") return localBackend;
+	return offBackend;
+}

package/src/memory-backend/types.ts

@@ -0,0 +1,69 @@
+/**
+ * Memory backend abstraction.
+ *
+ * Backends are mutually exclusive — `resolveMemoryBackend(settings)` returns
+ * exactly one. Implementations MUST be self-contained: they own the per-session
+ * state they create in `start()` and tear it down on `clear()`.
+ */
+
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { ModelRegistry } from "../config/model-registry";
+import type { Settings } from "../config/settings";
+import type { AgentSession } from "../session/agent-session";
+
+export type MemoryBackendId = "off" | "local" | "hindsight";
+
+export interface MemoryBackendStartOptions {
+	session: AgentSession;
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	agentDir: string;
+	taskDepth: number;
+}
+
+export interface MemoryBackend {
+	readonly id: MemoryBackendId;
+
+	/**
+	 * Wire any background work or session subscriptions for this backend.
+	 *
+	 * Called once per agent session at startup. Implementations MUST be
+	 * non-throwing: failures should be logged and swallowed so a misconfigured
+	 * memory backend cannot break the agent loop.
+	 */
+	start(options: MemoryBackendStartOptions): void | Promise<void>;
+
+	/**
+	 * Markdown injected as the system-prompt append section.
+	 * Returned on every prompt rebuild via `refreshBaseSystemPrompt()`.
+	 */
+	buildDeveloperInstructions(agentDir: string, settings: Settings): Promise<string | undefined>;
+
+	/** Wipe all persisted state for this backend (slash `/memory clear`). */
+	clear(agentDir: string, cwd: string): Promise<void>;
+
+	/** Force consolidation/retain to happen now (slash `/memory enqueue`). */
+	enqueue(agentDir: string, cwd: string): Promise<void>;
+
+	/**
+	 * Optional hook to inject a backend-specific block into the current turn's
+	 * system prompt before the agent starts generating.
+	 *
+	 * This is the only place a backend can affect the very first answer of a
+	 * fresh session. The returned text is appended to the already-built base
+	 * system prompt for this turn only; callers may separately cache it and
+	 * surface it through `buildDeveloperInstructions()` on later rebuilds.
+	 */
+	beforeAgentStartPrompt?(session: AgentSession, promptText: string): Promise<string | undefined>;
+
+	/**
+	 * Optional hook to splice extra context into a compaction summarization.
+	 *
+	 * Called from the compaction call site before the LLM summary is requested.
+	 * Returning a string appends one entry to the compaction's `extraContext`
+	 * list (which becomes part of the summarization prompt). Return `undefined`
+	 * to inject nothing — the local backend takes this branch because its
+	 * summary is already part of the system prompt.
+	 */
+	preCompactionContext?(messages: AgentMessage[], settings: Settings): Promise<string | undefined>;
+}