@oh-my-pi/pi-coding-agent 15.9.1 → 15.9.3

package/src/hindsight/backend.ts

@@ -9,10 +9,10 @@
 
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import { logger } from "@oh-my-pi/pi-utils";
-import type { Settings } from "../config/settings";
+import { onHindsightScopeChanged, type Settings } from "../config/settings";
 import type { MemoryBackend, MemoryBackendStartOptions } from "../memory-backend/types";
 import type { AgentSession } from "../session/agent-session";
-import { computeBankScope } from "./bank";
+import { type BankScope, computeBankScope } from "./bank";
 import { createHindsightClient } from "./client";
 import { isHindsightConfigured, loadHindsightConfig } from "./config";
 import type { HindsightMessage } from "./content";
@@ -60,12 +60,16 @@ export const hindsightBackend: MemoryBackend = {
 					recallTagsMatch: parent.recallTagsMatch,
 					config: parent.config,
 					session,
-					missionsSet: parent.missionsSet,
+					banksSet: parent.banksSet,
 					lastRetainedTurn: 0,
 					hasRecalledForFirstTurn: true,
 					aliasOf: parent,
 				}),
 			);
+			// Aliases don't run auto-recall/auto-retain, so any pending retain
+			// queue belongs to the previous alias and is safe to drop after a
+			// best-effort flush (`flushRetainQueue` is no-op when empty).
+			await previous?.flushRetainQueue();
 			previous?.dispose();
 			return;
 		}
@@ -76,38 +80,7 @@ export const hindsightBackend: MemoryBackend = {
 			return;
 		}
 
-		const client = createHindsightClient(config);
-		const scope = computeBankScope(config, session.sessionManager.getCwd());
-
-		const state = new HindsightSessionState({
-			sessionId,
-			client,
-			bankId: scope.bankId,
-			retainTags: scope.retainTags,
-			recallTags: scope.recallTags,
-			recallTagsMatch: scope.recallTagsMatch,
-			config,
-			session,
-			missionsSet: new Set(),
-			lastRetainedTurn: 0,
-			hasRecalledForFirstTurn: false,
-		});
-
-		// Cleanup any stale state for this session (defensive — prevents leaks
-		// when a session is reused without going through dispose).
-		const previous = session.setHindsightSessionState(state);
-		previous?.dispose();
-		state.attachSessionListeners();
-
-		// Kick off mental-model bootstrap. Resolves asynchronously; the first
-		// turn races and is covered in `beforeAgentStartPrompt` via
-		// `mentalModelsLoadPromise`. Subsequent turns see the populated cache
-		// because `runMentalModelLoad` calls `refreshBaseSystemPrompt`.
-		if (config.mentalModelsEnabled) {
-			state.mentalModelsLoadPromise = state.runMentalModelLoad(scope).catch(err => {
-				logger.debug("Hindsight: mental-model bootstrap failed", { bankId: state.bankId, error: String(err) });
-			});
-		}
+		await installPrimaryState(session, settings, new Set());
 	},
 
 	async buildDeveloperInstructions(_agentDir, settings, session): Promise<string | undefined> {
@@ -173,6 +146,182 @@ export const hindsightBackend: MemoryBackend = {
 		return await state.recallForCompaction(flat);
 	},
 };
+interface PrimaryRebuildTask {
+	pending: boolean;
+}
+
+const primaryRebuildTasks = new WeakMap<AgentSession, PrimaryRebuildTask>();
+
+/**
+ * Coalesce and serialize live scope rebuilds for one session. Cwd reloads fire
+ * all settings hooks synchronously; running every callback immediately would
+ * let multiple rebuilds capture the same old state and leak the fresh states
+ * installed by earlier continuations.
+ */
+function schedulePrimaryStateRebuild(session: AgentSession): void {
+	const task = primaryRebuildTasks.get(session);
+	if (task) {
+		task.pending = true;
+		return;
+	}
+
+	const nextTask: PrimaryRebuildTask = { pending: true };
+	primaryRebuildTasks.set(session, nextTask);
+	void Promise.resolve()
+		.then(async () => {
+			while (nextTask.pending) {
+				nextTask.pending = false;
+				try {
+					await rebuildPrimaryStateOnScopeChange(session);
+				} catch (err) {
+					logger.warn("Hindsight: scope rebuild failed", { error: String(err) });
+				}
+			}
+		})
+		.finally(() => {
+			if (primaryRebuildTasks.get(session) === nextTask) {
+				primaryRebuildTasks.delete(session);
+			}
+		});
+}
+
+/**
+ * Build (or rebuild) the primary `HindsightSessionState` for `session` from
+ * the current settings and install it. Disposes any previous primary state
+ * after flushing its retain queue so in-flight tool-initiated retains land in
+ * the bank that was selected when they were enqueued, not in the new bank.
+ *
+ * The created state takes ownership of the `onHindsightScopeChanged`
+ * subscription so subsequent `hindsight.bankId` / `bankIdPrefix` / `scoping`
+ * edits trigger another rebuild from the same wiring.
+ */
+async function installPrimaryState(
+	session: AgentSession,
+	settings: Settings,
+	banksSet: Set<string>,
+): Promise<HindsightSessionState | undefined> {
+	const sessionId = session.sessionId;
+	if (!sessionId) return undefined;
+
+	const config = loadHindsightConfig(settings);
+	if (!isHindsightConfigured(config)) return undefined;
+
+	const client = createHindsightClient(config);
+	const scope = computeBankScope(config, session.sessionManager.getCwd());
+
+	// Cleanup any stale state for this session (defensive — prevents leaks
+	// when a session is reused without going through dispose). Flush the
+	// previous state's retain queue BEFORE clearing it, otherwise
+	// `HindsightRetainQueue.#doFlush` sees `session.getHindsightSessionState()
+	// !== state` and drops the batch. Re-read after the await so a concurrent
+	// owner cannot leave the actual current state undisposed.
+	let previous = session.getHindsightSessionState();
+	if (previous) {
+		await previous.flushRetainQueue();
+	}
+	const latest = session.getHindsightSessionState();
+	if (latest && latest !== previous) {
+		previous?.dispose();
+		previous = latest;
+		await previous.flushRetainQueue();
+	}
+
+	const state = new HindsightSessionState({
+		sessionId,
+		client,
+		bankId: scope.bankId,
+		retainTags: scope.retainTags,
+		recallTags: scope.recallTags,
+		recallTagsMatch: scope.recallTagsMatch,
+		config,
+		session,
+		banksSet,
+		lastRetainedTurn: 0,
+		hasRecalledForFirstTurn: false,
+	});
+
+	// Subscribe BEFORE installing: if the operator manages to flip another
+	// setting between install and subscribe, we'd miss the edge.
+	state.unsubscribeScope = onHindsightScopeChanged(() => {
+		schedulePrimaryStateRebuild(session);
+	});
+
+	const displaced = session.setHindsightSessionState(state);
+	if (displaced && displaced !== previous) {
+		await displaced.flushRetainQueue();
+		displaced.dispose();
+	}
+	previous?.dispose();
+	state.attachSessionListeners();
+
+	// Kick off mental-model bootstrap. Resolves asynchronously; the first
+	// turn races and is covered in `beforeAgentStartPrompt` via
+	// `mentalModelsLoadPromise`. Subsequent turns see the populated cache
+	// because `runMentalModelLoad` calls `refreshBaseSystemPrompt`.
+	if (config.mentalModelsEnabled) {
+		state.mentalModelsLoadPromise = state.runMentalModelLoad(scope).catch(err => {
+			logger.debug("Hindsight: mental-model bootstrap failed", { bankId: state.bankId, error: String(err) });
+		});
+	}
+
+	return state;
+}
+
+/**
+ * `onHindsightScopeChanged` handler: re-evaluate the bank scope from current
+ * settings and rebuild the primary state when it has actually drifted. No-op
+ * when the scope is unchanged or the session is no longer hosting a primary
+ * state (e.g. it was wiped to `undefined`, or this is a subagent alias).
+ */
+async function rebuildPrimaryStateOnScopeChange(session: AgentSession): Promise<void> {
+	const current = session.getHindsightSessionState();
+	if (!current || current.aliasOf) return;
+
+	const settings = session.settings;
+	const config = loadHindsightConfig(settings);
+	if (!isHindsightConfigured(config)) {
+		// Hindsight effectively unwired mid-session. Flush before clearing so
+		// queued retains don't get dropped by `HindsightRetainQueue.#doFlush`.
+		await current.flushRetainQueue();
+		const previous = session.setHindsightSessionState(undefined);
+		previous?.dispose();
+		return;
+	}
+
+	const next = computeBankScope(config, session.sessionManager.getCwd());
+	if (bankScopesEqual(next, current)) return;
+
+	// Preserve the banksSet so we don't re-PUT banks we've already confirmed.
+	await installPrimaryState(session, settings, current.banksSet);
+}
+
+/** Tag-array equality: order matters because we never reorder on the way in. */
+function stringArraysEqual(a: string[] | undefined, b: string[] | undefined): boolean {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) {
+		if (a[i] !== b[i]) return false;
+	}
+	return true;
+}
+
+/**
+ * Structural compare of a freshly resolved `BankScope` against a live state's
+ * bank routing. Used by the scope-change handler to skip rebuilds that don't
+ * actually move the bank or its tag filters.
+ */
+function bankScopesEqual(
+	scope: BankScope,
+	state: Pick<HindsightSessionState, "bankId" | "retainTags" | "recallTags" | "recallTagsMatch">,
+): boolean {
+	return (
+		scope.bankId === state.bankId &&
+		stringArraysEqual(scope.retainTags, state.retainTags) &&
+		stringArraysEqual(scope.recallTags, state.recallTags) &&
+		scope.recallTagsMatch === state.recallTagsMatch
+	);
+}
 
 /** Reduce arbitrary AgentMessages into the Hindsight flat-text shape. */
 function flattenMessagesForRecall(messages: AgentMessage[]): HindsightMessage[] {

package/src/hindsight/bank.ts

@@ -1,5 +1,5 @@
 /**
- * Bank ID derivation, project-tag scoping, and first-use mission setup.
+ * Bank ID derivation, project-tag scoping, and first-use bank setup.
  *
  * Three scoping modes (`HindsightConfig.scoping`):
  *   - `global`              — single shared bank, no per-project filter.
@@ -11,10 +11,13 @@
  * The base bank id is `bankIdPrefix-bankId` (default `omp`). Per-project mode
  * appends `-<project>`; tagged mode leaves the bank untouched and uses tags.
  *
- * Mission setup is idempotent at module level — a missionsSet keeps track of
- * banks we've already POSTed to so each session boundary doesn't fire a fresh
- * `createBank` call. Failures are swallowed: missions are an optimisation, not
- * a precondition for retain/recall.
+ * Bank existence is idempotent at module level — a banksSet keeps track of
+ * banks we've already PUT so each session boundary doesn't fire a fresh
+ * `createBank` call. The PUT is idempotent server-side, so re-firing on a hot
+ * path would only burn round-trips. Failures are swallowed: missing the
+ * mission patch is an optimisation, but the bank ITSELF must exist before
+ * mental-model bootstrap or the first retain, otherwise the very first POST
+ * lands against a missing bank.
  */
 
 import * as path from "node:path";
@@ -93,39 +96,46 @@ export function deriveBankId(config: HindsightConfig, directory: string): string
 }
 
 /**
- * Ensure a bank's reflect/retain mission is set, exactly once per process.
+ * Ensure a bank exists, and patch its reflect/retain mission on first use.
  *
- * Tracked via the supplied set; on overflow we drop the oldest half so the set
- * cannot grow unboundedly across long-lived processes.
+ * Idempotent: skips the PUT when the bank id is already in the supplied set.
+ * The mission body is optional — when `bankMission` is blank we still PUT to
+ * make sure the bank itself is created, so mental-model bootstrap and the
+ * first retain don't land against a non-existent bank.
+ *
+ * The set is capped; on overflow we drop the oldest half so it cannot grow
+ * unboundedly across long-lived processes.
  */
-export async function ensureBankMission(
+export async function ensureBankExists(
 	client: HindsightApi,
 	bankId: string,
 	config: HindsightConfig,
-	missionsSet: Set<string>,
+	banksSet: Set<string>,
 ): Promise<void> {
+	if (banksSet.has(bankId)) return;
+
 	const mission = config.bankMission?.trim();
-	if (!mission) return;
-	if (missionsSet.has(bankId)) return;
+	const retainMission = config.retainMission?.trim();
 
 	try {
 		await client.createBank(bankId, {
-			reflectMission: mission,
-			retainMission: config.retainMission?.trim() || undefined,
+			reflectMission: mission || undefined,
+			retainMission: retainMission || undefined,
 		});
-		missionsSet.add(bankId);
-		if (missionsSet.size > MISSION_SET_CAP) {
-			const keys = [...missionsSet].sort();
+		banksSet.add(bankId);
+		if (banksSet.size > MISSION_SET_CAP) {
+			const keys = [...banksSet].sort();
 			for (const key of keys.slice(0, keys.length >> 1)) {
-				missionsSet.delete(key);
+				banksSet.delete(key);
 			}
 		}
 		if (config.debug) {
-			logger.debug("Hindsight: set mission for bank", { bankId });
+			logger.debug("Hindsight: ensured bank", { bankId, mission: Boolean(mission) });
 		}
 	} catch (err) {
-		// Mission set is best-effort; the bank may not exist yet, or the API may
-		// reject the call. Either way, retain/recall still work, so swallow.
-		logger.debug("Hindsight: ensureBankMission failed", { bankId, error: String(err) });
+		// Bank creation is best-effort; the server may already have it, or the
+		// API may reject the call. Either way, downstream retain/recall calls
+		// will surface a clearer error if the bank really is missing.
+		logger.debug("Hindsight: ensureBankExists failed", { bankId, error: String(err) });
 	}
 }

package/src/hindsight/mental-models.ts

@@ -112,7 +112,7 @@ function dedupe<T>(items: T[]): T[] {
  * Idempotently create any seed mental models that don't already exist on the
  * bank. Best-effort: a list/create failure does not throw — mental models are
  * an optimization, not a precondition for retain/recall, and we mirror the
- * swallow-on-failure pattern used by `ensureBankMission`.
+ * swallow-on-failure pattern used by `ensureBankExists`.
  *
  * Existing models are NEVER modified. See module docstring.
  */

package/src/hindsight/state.ts

@@ -1,6 +1,6 @@
 import { logger } from "@oh-my-pi/pi-utils";
 import type { AgentSession } from "../session/agent-session";
-import { type BankScope, ensureBankMission } from "./bank";
+import { type BankScope, ensureBankExists } from "./bank";
 import type { HindsightApi, MemoryItemInput } from "./client";
 import type { HindsightConfig } from "./config";
 import {
@@ -45,12 +45,12 @@ export interface HindsightSessionStateOptions {
 	recallTagsMatch?: "any" | "all" | "any_strict" | "all_strict";
 	config: HindsightConfig;
 	session: AgentSession;
-	missionsSet: Set<string>;
+	banksSet: Set<string>;
 	lastRetainedTurn?: number;
 	hasRecalledForFirstTurn?: boolean;
 	/**
 	 * When set, this entry is a subagent alias that reuses the parent's bank,
-	 * scope, config, client, and missionsSet. Aliases skip auto-recall and
+	 * scope, config, client, and banksSet. Aliases skip auto-recall and
 	 * auto-retain — those run on the parent only — but the recall/retain/reflect
 	 * tools resolve via the alias so they persist to the same bank as the parent.
 	 */
@@ -148,7 +148,7 @@ export class HindsightRetainQueue {
 		}
 
 		try {
-			await ensureBankMission(state.client, state.bankId, state.config, state.missionsSet);
+			await ensureBankExists(state.client, state.bankId, state.config, state.banksSet);
 			const batch: MemoryItemInput[] = items.map(item => ({
 				content: item.content,
 				context: item.context ?? state.config.retainContext,
@@ -198,7 +198,7 @@ export class HindsightSessionState {
 	recallTagsMatch?: "any" | "all" | "any_strict" | "all_strict";
 	config: HindsightConfig;
 	session: AgentSession;
-	missionsSet: Set<string>;
+	banksSet: Set<string>;
 	lastRetainedTurn: number;
 	hasRecalledForFirstTurn: boolean;
 	lastRecallSnippet?: string;
@@ -213,6 +213,12 @@ export class HindsightSessionState {
 	 */
 	mentalModelsLoadPromise?: Promise<void>;
 	unsubscribe?: () => void;
+	/**
+	 * Releases the `onHindsightScopeChanged` subscription that drives live
+	 * rebuilds when `hindsight.bankId` / `bankIdPrefix` / `scoping` change.
+	 * Only set on primary states; aliases inherit the parent's subscription.
+	 */
+	unsubscribeScope?: () => void;
 	/** Alias states delegate persistence config to a primary parent state. */
 	aliasOf?: HindsightSessionState;
 	readonly retainQueue: HindsightRetainQueue;
@@ -226,7 +232,7 @@ export class HindsightSessionState {
 		this.recallTagsMatch = options.recallTagsMatch;
 		this.config = options.config;
 		this.session = options.session;
-		this.missionsSet = options.missionsSet;
+		this.banksSet = options.banksSet;
 		this.lastRetainedTurn = options.lastRetainedTurn ?? 0;
 		this.hasRecalledForFirstTurn = options.hasRecalledForFirstTurn ?? false;
 		this.aliasOf = options.aliasOf;
@@ -291,7 +297,7 @@ export class HindsightSessionState {
 		const { transcript } = prepareRetentionTranscript(target, true);
 		if (!transcript) return;
 
-		await ensureBankMission(this.client, this.bankId, this.config, this.missionsSet);
+		await ensureBankExists(this.client, this.bankId, this.config, this.banksSet);
 		await this.client.retain(this.bankId, transcript, {
 			documentId,
 			context: this.config.retainContext,
@@ -398,6 +404,12 @@ export class HindsightSessionState {
 	async runMentalModelLoad(scope: BankScope): Promise<void> {
 		if (!this.config.mentalModelsEnabled) return;
 
+		// Create/ensure the bank BEFORE the first mental-model POST so we don't
+		// land `createMentalModel` against a bank the server has never seen —
+		// that surfaces as a FK / 404 on Hindsight's side. `ensureBankExists`
+		// is idempotent (PUT) and skips after the first call via `banksSet`.
+		await ensureBankExists(this.client, this.bankId, this.config, this.banksSet);
+
 		// Seeding is opt-in (`hindsight.mentalModelAutoSeed`). Default behaviour is
 		// read-only: we surface whatever models the operator has curated on the
 		// bank, but we do NOT POST to create new ones unless they explicitly
@@ -456,6 +468,8 @@ export class HindsightSessionState {
 	dispose(): void {
 		this.unsubscribe?.();
 		this.unsubscribe = undefined;
+		this.unsubscribeScope?.();
+		this.unsubscribeScope = undefined;
 		this.retainQueue.dispose();
 	}