@oh-my-pi/pi-coding-agent 17.0.9 → 17.1.1

package/src/session/session-memory.ts

@@ -0,0 +1,222 @@
+/** Session memory backend lifecycle and transcript resets. */
+
+import type { Agent, AgentTool } from "@oh-my-pi/pi-agent-core";
+import { logger } from "@oh-my-pi/pi-utils";
+import type { ModelRegistry } from "../config/model-registry";
+import type { Settings } from "../config/settings";
+import type { HindsightSessionState } from "../hindsight/state";
+import { resolveMemoryBackend } from "../memory-backend/resolve";
+import type { MemoryBackendStartOptions } from "../memory-backend/types";
+import type { MnemopiSessionState } from "../mnemopi/state";
+
+/** Capabilities borrowed from the owning AgentSession. */
+export interface SessionMemoryHost {
+	agent: Agent;
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	isDisposed(): boolean;
+	memoryBackendSession(): MemoryBackendStartOptions["session"];
+	getHindsightSessionState(): HindsightSessionState | undefined;
+	setHindsightSessionState(state: HindsightSessionState | undefined): void;
+	getMnemopiSessionState(): MnemopiSessionState | undefined;
+	takeMnemopiSessionState(): MnemopiSessionState | undefined;
+	setBaseSystemPrompt(prompt: string[]): void;
+	refreshBaseSystemPrompt(): Promise<void>;
+	replaceMemoryTools(tools: AgentTool[]): Promise<void>;
+}
+
+/** Owns memory backend transitions and transcript-scoped memory state. */
+export class SessionMemory {
+	readonly #host: SessionMemoryHost;
+	readonly #memoryAgentDir: string | undefined;
+	readonly #memoryTaskDepth: number;
+	readonly #createMemoryTools: (() => Promise<AgentTool[]>) | undefined;
+	#memoryBackendTransition: Promise<void> = Promise.resolve();
+	#localMemoryStartupAbort: AbortController | undefined;
+	#baseSystemPromptBeforeMemoryPromotion: string[] | undefined;
+
+	constructor(
+		host: SessionMemoryHost,
+		options: {
+			memoryAgentDir?: string;
+			memoryTaskDepth?: number;
+			createMemoryTools?: () => Promise<AgentTool[]>;
+		},
+	) {
+		this.#host = host;
+		this.#memoryAgentDir = options.memoryAgentDir;
+		this.#memoryTaskDepth = options.memoryTaskDepth ?? 0;
+		this.#createMemoryTools = options.createMemoryTools;
+	}
+
+	/** Current serialized backend transition, used by prompt and disposal drains. */
+	get transition(): Promise<void> {
+		return this.#memoryBackendTransition;
+	}
+
+	/** Base prompt captured before a per-turn memory promotion. */
+	get promotionSnapshot(): string[] | undefined {
+		return this.#baseSystemPromptBeforeMemoryPromotion;
+	}
+
+	/** Clears the per-turn memory promotion after a canonical prompt rebuild. */
+	clearPromotionSnapshot(): void {
+		this.#baseSystemPromptBeforeMemoryPromotion = undefined;
+	}
+
+	/** Captures the canonical prompt before the first per-turn memory promotion. */
+	capturePromotionSnapshot(prompt: string[]): void {
+		this.#baseSystemPromptBeforeMemoryPromotion ??= prompt;
+	}
+
+	/** Restores a promotion snapshot while rolling back a failed session switch. */
+	restorePromotionSnapshot(prompt: string[] | undefined): void {
+		this.#baseSystemPromptBeforeMemoryPromotion = prompt;
+	}
+	/** Rekeys every active memory backend to the current provider session. */
+	rekeyForCurrentSessionId(): void {
+		this.#rekeyHindsightMemoryForCurrentSessionId();
+		this.#rekeyMnemopiMemoryForCurrentSessionId();
+	}
+
+	#rekeyHindsightMemoryForCurrentSessionId(): void {
+		if (this.#host.settings.get("memory.backend") !== "hindsight") return;
+		const sid = this.#host.agent.sessionId;
+		if (!sid) return;
+		this.#host.getHindsightSessionState()?.setSessionId(sid);
+	}
+
+	#rekeyMnemopiMemoryForCurrentSessionId(): void {
+		if (this.#host.settings.get("memory.backend") !== "mnemopi") return;
+		const sid = this.#host.agent.sessionId;
+		if (!sid) return;
+		this.#host.getMnemopiSessionState()?.setSessionId(sid);
+	}
+
+	/** New session file: reset auto-recall / retain-threshold counters for the new transcript. */
+	#resetHindsightConversationTrackingIfHindsight(): boolean {
+		if (this.#host.settings.get("memory.backend") !== "hindsight") return false;
+		const state = this.#host.getHindsightSessionState();
+		if (!state || state.aliasOf) return false;
+		state.resetConversationTracking();
+		return true;
+	}
+
+	#resetMnemopiConversationTrackingIfMnemopi(): boolean {
+		if (this.#host.settings.get("memory.backend") !== "mnemopi") return false;
+		const state = this.#host.getMnemopiSessionState();
+		if (!state || state.aliasOf) return false;
+		state.resetConversationTracking();
+		return true;
+	}
+
+	/** Resets transcript-scoped memory counters and removes a promoted prompt. */
+	async resetContextForNewTranscript(): Promise<void> {
+		const hadPromotedMemoryPrompt = this.#baseSystemPromptBeforeMemoryPromotion !== undefined;
+		const resetHindsight = this.#resetHindsightConversationTrackingIfHindsight();
+		const resetMnemopi = this.#resetMnemopiConversationTrackingIfMnemopi();
+		if (hadPromotedMemoryPrompt) {
+			this.#host.setBaseSystemPrompt(this.#baseSystemPromptBeforeMemoryPromotion!);
+			this.#baseSystemPromptBeforeMemoryPromotion = undefined;
+		}
+		if (resetHindsight || resetMnemopi || hadPromotedMemoryPrompt) {
+			await this.#host.refreshBaseSystemPrompt();
+		}
+	}
+
+	/** Cancel the local rollout-memory startup owned by this session. */
+	cancelLocalMemoryStartup(): void {
+		this.#localMemoryStartupAbort?.abort();
+		this.#localMemoryStartupAbort = undefined;
+	}
+
+	/** Start a new local rollout-memory generation and cancel its predecessor. */
+	beginLocalMemoryStartup(): AbortSignal {
+		this.cancelLocalMemoryStartup();
+		const controller = new AbortController();
+		this.#localMemoryStartupAbort = controller;
+		return controller.signal;
+	}
+
+	/** Release the local startup slot if `signal` still owns it. */
+	endLocalMemoryStartup(signal: AbortSignal): void {
+		if (this.#localMemoryStartupAbort?.signal === signal) this.#localMemoryStartupAbort = undefined;
+	}
+
+	async #disposeMemoryBackendState(consolidateMnemopi = true): Promise<void> {
+		this.cancelLocalMemoryStartup();
+		const hindsight = this.#host.getHindsightSessionState();
+		if (hindsight) {
+			try {
+				await hindsight.flushRetainQueue();
+			} catch (error) {
+				logger.warn("Memory lifecycle: Hindsight flush failed", { error: String(error) });
+			}
+			this.#host.setHindsightSessionState(undefined);
+			hindsight.dispose();
+		}
+
+		const mnemopi = this.#host.takeMnemopiSessionState();
+		if (mnemopi) {
+			try {
+				await mnemopi.dispose({ consolidate: consolidateMnemopi });
+			} catch (error) {
+				logger.warn("Memory lifecycle: Mnemopi dispose failed", { error: String(error) });
+			}
+		}
+	}
+
+	/**
+	 * Apply the selected memory backend to runtime state, tools, and prompt.
+	 * Concurrent settings changes run in order and settle before the next turn.
+	 */
+	async applyMemoryBackend(): Promise<void> {
+		if (this.#host.isDisposed()) return;
+		const transition = this.#memoryBackendTransition.then(() => this.#applyMemoryBackend());
+		this.#memoryBackendTransition = transition.then(
+			() => undefined,
+			() => undefined,
+		);
+		await transition;
+	}
+
+	async #applyMemoryBackend(): Promise<void> {
+		if (this.#host.isDisposed()) return;
+		try {
+			await this.#disposeMemoryBackendState();
+			if (this.#memoryAgentDir && this.#memoryTaskDepth === 0 && !this.#host.isDisposed()) {
+				const backend = await resolveMemoryBackend(this.#host.settings);
+				await backend.start({
+					session: this.#host.memoryBackendSession(),
+					settings: this.#host.settings,
+					modelRegistry: this.#host.modelRegistry,
+					agentDir: this.#memoryAgentDir,
+					taskDepth: this.#memoryTaskDepth,
+				});
+			}
+			if (this.#host.isDisposed()) return;
+			await this.#refreshMemoryTools();
+			if (this.#host.isDisposed()) return;
+			await this.#host.refreshBaseSystemPrompt();
+		} catch (error) {
+			await this.#disposeMemoryBackendState(false);
+			if (!this.#host.isDisposed()) {
+				await this.#replaceMemoryTools([]).catch(refreshError => {
+					logger.warn("Failed to remove memory tools after backend apply error", {
+						error: String(refreshError),
+					});
+				});
+			}
+			throw error;
+		}
+	}
+
+	async #refreshMemoryTools(): Promise<void> {
+		const tools = (await this.#createMemoryTools?.()) ?? [];
+		await this.#replaceMemoryTools(tools);
+	}
+
+	#replaceMemoryTools(tools: AgentTool[]): Promise<void> {
+		return this.#host.replaceMemoryTools(tools);
+	}
+}

package/src/session/session-provider-boundary.ts

@@ -0,0 +1,307 @@
+/** Provider-facing message, image, secret, and stream normalization for a session. */
+
+import type { Agent, AgentMessage } from "@oh-my-pi/pi-agent-core";
+import type { CompactionPreparation } from "@oh-my-pi/pi-agent-core/compaction";
+import type { AssistantMessage, ImageContent, Message, Model, SimpleStreamOptions, TextContent } from "@oh-my-pi/pi-ai";
+import { isRecord, logger } from "@oh-my-pi/pi-utils";
+import * as snapcompact from "@oh-my-pi/snapcompact";
+import type { ModelRegistry } from "../config/model-registry";
+import { formatModelString } from "../config/model-resolver";
+import type { Settings } from "../config/settings";
+import { validateProviderMaxInFlightRequests } from "../config/settings";
+import type { LocalProtocolOptions } from "../internal-urls";
+import {
+	deobfuscateSessionContext,
+	obfuscateMessages,
+	type SecretObfuscator,
+	stripPendingSecretPlaceholderSuffix,
+} from "../secrets/obfuscator";
+import { normalizeModelContextImages } from "../utils/image-loading";
+import { describeAttachedImagesForTextModel } from "../utils/image-vision-fallback";
+import { type CustomMessage, convertToLlm } from "./messages";
+import { IMAGE_ATTACHMENT_DESCRIPTION_TYPE } from "./queued-messages";
+import type { BuildSessionContextOptions, SessionContext } from "./session-context";
+import type { SessionManager } from "./session-manager";
+
+type NormalizableContentBlock = AssistantMessage["content"][number] | TextContent | ImageContent;
+
+/** Capabilities borrowed from the owning AgentSession. */
+export interface SessionProviderBoundaryHost {
+	agent: Agent;
+	sessionManager: SessionManager;
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	model(): Model | undefined;
+	sessionId(): string;
+	localProtocolOptions(): LocalProtocolOptions;
+	transformContext(messages: AgentMessage[], signal?: AbortSignal): AgentMessage[] | Promise<AgentMessage[]>;
+	convertToLlm(messages: AgentMessage[]): Message[] | Promise<Message[]>;
+	onPayload: SimpleStreamOptions["onPayload"] | undefined;
+	onResponse: SimpleStreamOptions["onResponse"] | undefined;
+	onSseEvent: SimpleStreamOptions["onSseEvent"] | undefined;
+	obfuscator: SecretObfuscator | undefined;
+}
+
+/** Owns the transformations at the session/provider boundary. */
+export class SessionProviderBoundary {
+	readonly #host: SessionProviderBoundaryHost;
+
+	constructor(host: SessionProviderBoundaryHost) {
+		this.#host = host;
+	}
+
+	/** Latest image attachments addressable by tools as `Image #N` or `attachment://N`. */
+	getImageAttachments(): { label: string; uri: string; image: ImageContent }[] {
+		for (let i = this.#host.agent.state.messages.length - 1; i >= 0; i--) {
+			const message = this.#host.agent.state.messages[i];
+			if (!message || (message.role !== "user" && message.role !== "developer") || !Array.isArray(message.content)) {
+				continue;
+			}
+			const images = message.content.filter((part): part is ImageContent => part.type === "image");
+			if (images.length === 0) continue;
+			return images.map((image, index) => ({
+				label: `Image #${index + 1}`,
+				uri: `attachment://${index + 1}`,
+				image,
+			}));
+		}
+		return [];
+	}
+
+	/** Builds the current deobfuscated context for agent display and replay. */
+	buildDisplaySessionContext(): SessionContext {
+		return deobfuscateSessionContext(this.#host.sessionManager.buildSessionContext(), this.#host.obfuscator);
+	}
+
+	/** Builds the full display-only transcript context. */
+	buildTranscriptSessionContext(
+		options?: Pick<BuildSessionContextOptions, "collapseCompactedHistory" | "keepDanglingToolCalls">,
+	): SessionContext {
+		return deobfuscateSessionContext(
+			this.#host.sessionManager.buildSessionContext({
+				transcript: true,
+				collapseCompactedHistory: options?.collapseCompactedHistory,
+				keepDanglingToolCalls: options?.keepDanglingToolCalls,
+			}),
+			this.#host.obfuscator,
+			true,
+		);
+	}
+
+	/** Obfuscates optional plaintext before a provider request. */
+	obfuscateText(text: string | undefined): string | undefined {
+		if (!text || !this.#host.obfuscator?.hasSecrets()) return text;
+		return this.#host.obfuscator.obfuscate(text);
+	}
+
+	/** Obfuscates summaries and snapcompact plaintext carried into compaction. */
+	obfuscateCompactionPreparation(preparation: CompactionPreparation): CompactionPreparation {
+		if (!this.#host.obfuscator?.hasSecrets()) return preparation;
+		const previousSummary = this.obfuscateText(preparation.previousSummary);
+		const previousPreserveData = this.#obfuscatePreservedArchiveText(preparation.previousPreserveData);
+		if (
+			previousSummary === preparation.previousSummary &&
+			previousPreserveData === preparation.previousPreserveData
+		) {
+			return preparation;
+		}
+		return { ...preparation, previousSummary, previousPreserveData };
+	}
+
+	/** Deobfuscates provider text before exposing it to the session. */
+	deobfuscateText(text: string): string {
+		if (!this.#host.obfuscator?.hasSecrets()) return text;
+		return this.#host.obfuscator.deobfuscate(text);
+	}
+
+	/** Deobfuscates a streamed delta and removes an incomplete secret placeholder suffix. */
+	deobfuscateDelta(text: string): string {
+		const deobfuscated = this.deobfuscateText(text);
+		if (!this.#host.obfuscator?.hasSecrets()) return deobfuscated;
+		return stripPendingSecretPlaceholderSuffix(deobfuscated);
+	}
+
+	/** Converts side-request messages through the session's secret boundary. */
+	convertToLlmForSideRequest(messages: AgentMessage[]): Message[] {
+		const converted = convertToLlm(messages);
+		return this.#host.obfuscator?.hasSecrets() ? obfuscateMessages(this.#host.obfuscator, converted) : converted;
+	}
+
+	/** Converts session messages using the configured pre-LLM pipeline. */
+	async convertMessagesToLlm(messages: AgentMessage[], signal?: AbortSignal): Promise<Message[]> {
+		const transformedMessages = await this.#host.transformContext(messages, signal);
+		return await this.#host.convertToLlm(transformedMessages);
+	}
+
+	/** Applies session-level stream hooks and provider defaults to a side request. */
+	prepareSimpleStreamOptions(options: SimpleStreamOptions, provider = "anthropic"): SimpleStreamOptions {
+		const sessionOnPayload = this.#host.onPayload;
+		const sessionOnResponse = this.#host.onResponse;
+		const sessionMetadata = this.#host.agent.metadataForProvider(provider);
+		const sessionOnSseEvent = this.#host.onSseEvent;
+		const openrouterRoutingPreset =
+			provider === "openrouter" ? this.#host.settings.get("providers.openrouterVariant") : "default";
+		const openrouterVariant =
+			openrouterRoutingPreset !== "default" && options.openrouterVariant === undefined
+				? openrouterRoutingPreset
+				: undefined;
+		const antigravityEndpointMode =
+			provider === "google-antigravity" ? this.#host.settings.get("providers.antigravityEndpoint") : undefined;
+
+		const preparedOptions: SimpleStreamOptions = {
+			...options,
+			...(openrouterVariant !== undefined && { openrouterVariant }),
+			...(antigravityEndpointMode !== undefined && { antigravityEndpointMode }),
+			maxInFlightRequests: validateProviderMaxInFlightRequests(
+				options.maxInFlightRequests ?? this.#host.settings.get("providers.maxInFlightRequests"),
+			),
+			loopGuard: {
+				enabled: this.#host.settings.get("model.loopGuard.enabled"),
+				checkAssistantContent: this.#host.settings.get("model.loopGuard.checkAssistantContent"),
+				...options.loopGuard,
+			},
+		};
+
+		if (sessionMetadata && !options.metadata) {
+			preparedOptions.metadata = sessionMetadata;
+		}
+
+		if (sessionOnPayload) {
+			if (!options.onPayload) {
+				preparedOptions.onPayload = sessionOnPayload;
+			} else {
+				const requestOnPayload = options.onPayload;
+				preparedOptions.onPayload = async (payload, model) => {
+					const sessionPayload = await sessionOnPayload(payload, model);
+					const sessionResolvedPayload = sessionPayload ?? payload;
+					const requestPayload = await requestOnPayload(sessionResolvedPayload, model);
+					return requestPayload ?? sessionResolvedPayload;
+				};
+			}
+		}
+
+		if (sessionOnResponse) {
+			if (!options.onResponse) {
+				preparedOptions.onResponse = sessionOnResponse;
+			} else {
+				const requestOnResponse = options.onResponse;
+				preparedOptions.onResponse = async (response, model) => {
+					await sessionOnResponse(response, model);
+					await requestOnResponse(response, model);
+				};
+			}
+		}
+
+		if (sessionOnSseEvent) {
+			if (!options.onSseEvent) {
+				preparedOptions.onSseEvent = sessionOnSseEvent;
+			} else {
+				const requestOnSseEvent = options.onSseEvent;
+				preparedOptions.onSseEvent = (event, model) => {
+					sessionOnSseEvent(event, model);
+					requestOnSseEvent(event, model);
+				};
+			}
+		}
+
+		return preparedOptions;
+	}
+
+	/** Normalizes image payloads for the active model. */
+	normalizeImagesForModel(images: ImageContent[] | undefined): Promise<ImageContent[] | undefined> {
+		return normalizeModelContextImages(images, { model: this.#host.model() });
+	}
+
+	/** Builds a hidden vision-model description for attachments sent to a text-only model. */
+	async buildImageDescriptionNotice(
+		normalizedImages: ImageContent[],
+		signal?: AbortSignal,
+	): Promise<CustomMessage | undefined> {
+		const model = this.#host.model();
+		const shouldDescribe =
+			!!model &&
+			!model.input.includes("image") &&
+			!this.#host.settings.get("images.blockImages") &&
+			this.#host.settings.get("images.describeForTextModels");
+		if (!shouldDescribe || !model) return undefined;
+
+		let blocks: TextContent[];
+		try {
+			blocks = await describeAttachedImagesForTextModel(
+				normalizedImages,
+				{
+					activeModel: model,
+					modelRegistry: this.#host.modelRegistry,
+					settings: this.#host.settings,
+					localProtocolOptions: this.#host.localProtocolOptions(),
+					activeModelString: formatModelString(model),
+					telemetryConfig: this.#host.agent.telemetry,
+					sessionId: this.#host.sessionId(),
+				},
+				signal,
+			);
+		} catch (error) {
+			logger.warn("image attachment vision fallback failed; image left undescribed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return undefined;
+		}
+		if (blocks.length === 0) return undefined;
+		return {
+			role: "custom",
+			customType: IMAGE_ATTACHMENT_DESCRIPTION_TYPE,
+			content: blocks,
+			display: false,
+			attribution: "user",
+			timestamp: Date.now(),
+		};
+	}
+
+	/** Normalizes every image embedded in an agent message. */
+	async normalizeAgentMessageImages<T extends AgentMessage>(message: T): Promise<T> {
+		if (!("content" in message)) return message;
+		const content = message.content;
+		if (typeof content !== "string" && !Array.isArray(content)) return message;
+		const normalized = await this.#normalizeMessageContentImages(content);
+		if (normalized === content) return message;
+		return Object.assign({}, message, { content: normalized });
+	}
+
+	async #normalizeMessageContentImages(
+		content: string | NormalizableContentBlock[],
+	): Promise<string | NormalizableContentBlock[]> {
+		if (typeof content === "string") return content;
+		const images = content.filter((part): part is ImageContent => part.type === "image");
+		if (images.length === 0) return content;
+		const normalizedImages = await this.normalizeImagesForModel(images);
+		if (!normalizedImages) return content;
+		let imageIndex = 0;
+		return content.map(part => (part.type === "image" ? normalizedImages[imageIndex++]! : part));
+	}
+
+	#obfuscatePreservedArchiveText(
+		preserveData: Record<string, unknown> | undefined,
+	): Record<string, unknown> | undefined {
+		const obfuscator = this.#host.obfuscator;
+		const slot = preserveData?.[snapcompact.PRESERVE_KEY];
+		if (
+			!obfuscator?.hasSecrets() ||
+			!preserveData ||
+			!isRecord(slot) ||
+			!snapcompact.getPreservedArchive(preserveData)
+		) {
+			return preserveData;
+		}
+		const obfuscated: Record<string, unknown> = { ...slot };
+		let changed = false;
+		for (const key of ["text", "textHead", "textTail"] as const) {
+			const value = slot[key];
+			if (typeof value !== "string" || value.length === 0) continue;
+			const next = obfuscator.obfuscate(value);
+			if (next === value) continue;
+			obfuscated[key] = next;
+			changed = true;
+		}
+		return changed ? { ...preserveData, [snapcompact.PRESERVE_KEY]: obfuscated } : preserveData;
+	}
+}