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

package/src/hindsight/config.ts

@@ -0,0 +1,175 @@
+/**
+ * Resolved Hindsight runtime configuration.
+ *
+ * Source of truth precedence (last wins):
+ *   1. Built-in defaults
+ *   2. Settings (`hindsight.*` schema entries via `Settings.get(...)`)
+ *   3. `HINDSIGHT_*` environment variables
+ *
+ * Env wins because operators frequently override per-shell (CI, prod) without
+ * touching the persisted settings file.
+ */
+
+import { logger } from "@oh-my-pi/pi-utils";
+import type { Settings } from "../config/settings";
+
+export type HindsightScoping = "global" | "per-project" | "per-project-tagged";
+
+export interface HindsightConfig {
+	hindsightApiUrl: string | null;
+	hindsightApiToken: string | null;
+
+	bankId: string | null;
+	bankIdPrefix: string;
+	scoping: HindsightScoping;
+	bankMission: string;
+	retainMission: string | null;
+
+	autoRecall: boolean;
+	autoRetain: boolean;
+
+	retainMode: "full-session" | "last-turn";
+	retainEveryNTurns: number;
+	retainOverlapTurns: number;
+	retainContext: string;
+
+	recallBudget: "low" | "mid" | "high";
+	recallMaxTokens: number;
+	recallTypes: string[];
+	recallContextTurns: number;
+	recallMaxQueryChars: number;
+	recallPromptPreamble: string;
+
+	debug: boolean;
+
+	mentalModelsEnabled: boolean;
+	mentalModelAutoSeed: boolean;
+	mentalModelRefreshIntervalMs: number;
+	mentalModelMaxRenderChars: number;
+}
+
+const VALID_RETAIN_MODES: HindsightConfig["retainMode"][] = ["full-session", "last-turn"];
+const VALID_BUDGETS: HindsightConfig["recallBudget"][] = ["low", "mid", "high"];
+const VALID_SCOPINGS: HindsightScoping[] = ["global", "per-project", "per-project-tagged"];
+
+const DEFAULT_PREAMBLE =
+	"Relevant memories from past conversations (prioritize recent when conflicting). " +
+	"Only use memories that are directly useful to continue this conversation; ignore the rest:";
+
+/** Coerce an env var value into a boolean using the OpenCode plugin's semantics. */
+function envBool(value: string | undefined): boolean | undefined {
+	if (value === undefined) return undefined;
+	return ["true", "1", "yes"].includes(value.toLowerCase());
+}
+
+/** Coerce an env var value into an int, returning undefined for non-numeric input. */
+function envInt(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	const n = Number.parseInt(value, 10);
+	return Number.isFinite(n) ? n : undefined;
+}
+
+function envString(value: string | undefined): string | undefined {
+	if (value === undefined) return undefined;
+	const trimmed = value.trim();
+	return trimmed.length === 0 ? undefined : trimmed;
+}
+
+function pickBudget(value: unknown): HindsightConfig["recallBudget"] | undefined {
+	return typeof value === "string" && (VALID_BUDGETS as string[]).includes(value)
+		? (value as HindsightConfig["recallBudget"])
+		: undefined;
+}
+
+function pickRetainMode(value: unknown): HindsightConfig["retainMode"] | undefined {
+	return typeof value === "string" && (VALID_RETAIN_MODES as string[]).includes(value)
+		? (value as HindsightConfig["retainMode"])
+		: undefined;
+}
+
+function pickScoping(value: unknown): HindsightScoping | undefined {
+	return typeof value === "string" && (VALID_SCOPINGS as string[]).includes(value)
+		? (value as HindsightScoping)
+		: undefined;
+}
+
+/**
+ * Load the resolved Hindsight config.
+ *
+ * Pure (no I/O) aside from reading from `process.env` and the supplied
+ * Settings instance. Tests can pass `Settings.isolated({...})` and stub
+ * `process.env` per case.
+ */
+export function loadHindsightConfig(settings: Settings, env: NodeJS.ProcessEnv = process.env): HindsightConfig {
+	const apiUrlEnv = envString(env.HINDSIGHT_API_URL);
+	const apiTokenEnv = envString(env.HINDSIGHT_API_TOKEN);
+	const bankIdEnv = envString(env.HINDSIGHT_BANK_ID);
+	const bankMissionEnv = envString(env.HINDSIGHT_BANK_MISSION);
+	const retainModeEnv = pickRetainMode(env.HINDSIGHT_RETAIN_MODE);
+	const recallBudgetEnv = pickBudget(env.HINDSIGHT_RECALL_BUDGET);
+	const autoRecallEnv = envBool(env.HINDSIGHT_AUTO_RECALL);
+	const autoRetainEnv = envBool(env.HINDSIGHT_AUTO_RETAIN);
+	const scopingEnv = pickScoping(env.HINDSIGHT_SCOPING);
+	const debugEnv = envBool(env.HINDSIGHT_DEBUG);
+	const recallMaxTokensEnv = envInt(env.HINDSIGHT_RECALL_MAX_TOKENS);
+	const recallContextTurnsEnv = envInt(env.HINDSIGHT_RECALL_CONTEXT_TURNS);
+	const recallMaxQueryCharsEnv = envInt(env.HINDSIGHT_RECALL_MAX_QUERY_CHARS);
+	const retainEveryNTurnsEnv = envInt(env.HINDSIGHT_RETAIN_EVERY_N_TURNS);
+
+	// Read from settings (each falls back to its schema default).
+	const settingsRetainMode = pickRetainMode(settings.get("hindsight.retainMode"));
+	if (settings.get("hindsight.retainMode") && !settingsRetainMode) {
+		logger.warn("Hindsight: invalid retainMode setting, falling back to full-session", {
+			value: settings.get("hindsight.retainMode"),
+		});
+	}
+	const settingsRecallBudget = pickBudget(settings.get("hindsight.recallBudget"));
+	const settingsScoping = pickScoping(settings.get("hindsight.scoping"));
+	if (settings.get("hindsight.scoping") && !settingsScoping) {
+		logger.warn("Hindsight: invalid scoping setting, falling back to per-project-tagged", {
+			value: settings.get("hindsight.scoping"),
+		});
+	}
+
+	const config: HindsightConfig = {
+		hindsightApiUrl: apiUrlEnv ?? settings.get("hindsight.apiUrl") ?? null,
+		hindsightApiToken: apiTokenEnv ?? settings.get("hindsight.apiToken") ?? null,
+
+		bankId: bankIdEnv ?? settings.get("hindsight.bankId") ?? null,
+		bankIdPrefix: settings.get("hindsight.bankIdPrefix") ?? "",
+		scoping: scopingEnv ?? settingsScoping ?? "per-project-tagged",
+		bankMission: bankMissionEnv ?? settings.get("hindsight.bankMission") ?? "",
+		retainMission: settings.get("hindsight.retainMission") ?? null,
+
+		autoRecall: autoRecallEnv ?? settings.get("hindsight.autoRecall"),
+		autoRetain: autoRetainEnv ?? settings.get("hindsight.autoRetain"),
+
+		retainMode: retainModeEnv ?? settingsRetainMode ?? "full-session",
+		retainEveryNTurns: retainEveryNTurnsEnv ?? settings.get("hindsight.retainEveryNTurns"),
+		retainOverlapTurns: settings.get("hindsight.retainOverlapTurns"),
+		retainContext: settings.get("hindsight.retainContext") ?? "omp",
+
+		recallBudget: recallBudgetEnv ?? settingsRecallBudget ?? "mid",
+		recallMaxTokens: recallMaxTokensEnv ?? settings.get("hindsight.recallMaxTokens"),
+		recallTypes: settings.get("hindsight.recallTypes") as string[],
+		recallContextTurns: recallContextTurnsEnv ?? settings.get("hindsight.recallContextTurns"),
+		recallMaxQueryChars: recallMaxQueryCharsEnv ?? settings.get("hindsight.recallMaxQueryChars"),
+		recallPromptPreamble: DEFAULT_PREAMBLE,
+
+		debug: debugEnv ?? settings.get("hindsight.debug"),
+
+		mentalModelsEnabled: settings.get("hindsight.mentalModelsEnabled"),
+		mentalModelAutoSeed: settings.get("hindsight.mentalModelAutoSeed"),
+		mentalModelRefreshIntervalMs: settings.get("hindsight.mentalModelRefreshIntervalMs"),
+		mentalModelMaxRenderChars: settings.get("hindsight.mentalModelMaxRenderChars"),
+	};
+
+	return config;
+}
+
+/** Whether the caller has enough config to talk to a Hindsight server. */
+export function isHindsightConfigured(
+	config: HindsightConfig,
+): config is HindsightConfig & { hindsightApiUrl: string } {
+	return typeof config.hindsightApiUrl === "string" && config.hindsightApiUrl.length > 0;
+}

package/src/hindsight/content.ts

@@ -0,0 +1,210 @@
+/**
+ * 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;
+const MENTAL_MODELS_REGEX = /<mental_models>[\s\S]*?<\/mental_models>/g;
+
+/**
+ * Strip `<memories>`, `<mental_models>`, and legacy memory blocks.
+ *
+ * Both `<memories>` (per-turn recall) and `<mental_models>` (curated semantic
+ * memory) are injected into the system prompt. If either leaks into the
+ * retention transcript, every retain becomes a tighter feedback loop —
+ * paraphrased memories feed the next consolidation, which feeds the next
+ * mental-model refresh, which feeds the next retain. Always strip before
+ * retaining.
+ */
+export function stripMemoryTags(content: string): string {
+	return content
+		.replace(MEMORIES_REGEX, "")
+		.replace(MENTAL_MODELS_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,8 @@
+export * from "./backend";
+export * from "./bank";
+export * from "./client";
+export * from "./config";
+export * from "./content";
+export * from "./mental-models";
+export * from "./state";
+export * from "./transcript";