@oh-my-pi/pi-coding-agent 15.10.11 → 15.11.0

package/src/memory-backend/index.ts

@@ -14,4 +14,5 @@ export type {
 export * from "./local-backend";
 export * from "./off-backend";
 export * from "./resolve";
+export * from "./runtime";
 export * from "./types";

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

@@ -27,4 +27,13 @@ export const localBackend: MemoryBackend = {
 	async enqueue(agentDir, cwd) {
 		enqueueMemoryConsolidation(agentDir, cwd);
 	},
+	async status() {
+		return {
+			backend: "local" as const,
+			active: true,
+			writable: false,
+			searchable: false,
+			message: "Local rollout-summary memory is active; structured search/save is not available.",
+		};
+	},
 };

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

@@ -13,4 +13,13 @@ export const offBackend: MemoryBackend = {
 	},
 	async clear() {},
 	async enqueue() {},
+	async status() {
+		return {
+			backend: "off" as const,
+			active: false,
+			writable: false,
+			searchable: false,
+			message: "Memory backend is off.",
+		};
+	},
 };

package/src/memory-backend/runtime.ts

@@ -0,0 +1,66 @@
+import type { AgentSession } from "../session/agent-session";
+import { resolveMemoryBackend } from "./resolve";
+import type {
+	MemoryBackendId,
+	MemoryBackendOperationContext,
+	MemoryBackendSaveInput,
+	MemoryBackendSearchOptions,
+	MemoryRuntimeContext,
+} from "./types";
+export function createMemoryRuntimeContext(context: MemoryBackendOperationContext): MemoryRuntimeContext {
+	const settings = context.session?.settings;
+	return {
+		async status() {
+			if (!settings) {
+				return {
+					backend: "off" as const,
+					active: false,
+					writable: false,
+					searchable: false,
+					message: "No active agent session.",
+				};
+			}
+			const backend = await resolveMemoryBackend(settings);
+			return backend.status
+				? await backend.status(context)
+				: {
+						backend: backend.id,
+						active: backend.id !== "off",
+						writable: false,
+						searchable: false,
+						message: "This memory backend does not expose structured status.",
+					};
+		},
+		async search(query: string, options?: MemoryBackendSearchOptions) {
+			if (!settings) return unavailableSearch("off", query, "No active agent session.");
+			const backend = await resolveMemoryBackend(settings);
+			return backend.search
+				? await backend.search(context, query, options)
+				: unavailableSearch(backend.id, query, `Memory search is not available for the ${backend.id} backend.`);
+		},
+		async save(input: string | MemoryBackendSaveInput) {
+			if (!settings) return unavailableSave("off", "No active agent session.");
+			const backend = await resolveMemoryBackend(settings);
+			const normalized = typeof input === "string" ? { content: input } : input;
+			return backend.save
+				? await backend.save(context, normalized)
+				: unavailableSave(backend.id, `Memory save is not available for the ${backend.id} backend.`);
+		},
+	};
+}
+
+export function createSessionMemoryRuntimeContext(
+	session: AgentSession,
+	agentDir: string,
+	cwd: string,
+): MemoryRuntimeContext {
+	return createMemoryRuntimeContext({ agentDir, cwd, session });
+}
+
+function unavailableSearch(backend: MemoryBackendId, query: string, message: string) {
+	return { backend, query, count: 0, items: [], message };
+}
+
+function unavailableSave(backend: MemoryBackendId, message: string) {
+	return { backend, stored: 0, message };
+}

package/src/memory-backend/types.ts

@@ -1,7 +1,7 @@
 /**
  * Memory backend abstraction.
  *
- * Backends are mutually exclusive — `await resolveMemoryBackend(settings)` resolves
+ * Backends are mutually exclusive — `await 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()`.
  */
@@ -15,6 +15,73 @@ import type { AgentSession } from "../session/agent-session";
 
 export type MemoryBackendId = "off" | "local" | "hindsight" | "mnemopi";
 
+export interface MemoryBackendStatus {
+	backend: MemoryBackendId;
+	active: boolean;
+	writable: boolean;
+	searchable: boolean;
+	scope?: string;
+	retainBank?: string;
+	recallBanks?: string[];
+	workingCount?: number;
+	episodicCount?: number;
+	tripleCount?: number;
+	lastMemory?: string;
+	lastRecall?: boolean;
+	database?: string;
+	message?: string;
+	error?: string;
+}
+
+export interface MemoryBackendSearchOptions {
+	limit?: number;
+	/** Best-effort abort signal. Backends may only observe it before/after an underlying recall call. */
+	signal?: AbortSignal;
+}
+
+export interface MemoryBackendSearchItem {
+	id?: string;
+	content: string;
+	source?: string;
+	timestamp?: string;
+	score?: number;
+}
+
+export interface MemoryBackendSearchResult {
+	backend: MemoryBackendId;
+	query: string;
+	count: number;
+	items: MemoryBackendSearchItem[];
+	message?: string;
+}
+
+export interface MemoryBackendSaveInput {
+	content: string;
+	context?: string;
+	source?: string;
+	importance?: number;
+}
+
+export interface MemoryBackendSaveResult {
+	backend: MemoryBackendId;
+	stored: number;
+	ids?: string[];
+	queued?: boolean;
+	message?: string;
+}
+
+export interface MemoryBackendOperationContext {
+	agentDir: string;
+	cwd: string;
+	session?: AgentSession;
+}
+
+export interface MemoryRuntimeContext {
+	status(): Promise<MemoryBackendStatus>;
+	search(query: string, options?: MemoryBackendSearchOptions): Promise<MemoryBackendSearchResult>;
+	save(input: string | MemoryBackendSaveInput): Promise<MemoryBackendSaveResult>;
+}
+
 export interface MemoryBackendStartOptions {
 	session: AgentSession;
 	settings: Settings;
@@ -53,6 +120,19 @@ export interface MemoryBackend {
 	/** Force consolidation/retain to happen now (slash `/memory enqueue`). */
 	enqueue(agentDir: string, cwd: string, session?: AgentSession): Promise<void>;
 
+	/** Structured state for UI, slash commands, and extensions. */
+	status?(context: MemoryBackendOperationContext): Promise<MemoryBackendStatus>;
+
+	/** Explicit user-facing semantic/lexical search. */
+	search?(
+		context: MemoryBackendOperationContext,
+		query: string,
+		options?: MemoryBackendSearchOptions,
+	): Promise<MemoryBackendSearchResult>;
+
+	/** Explicit user-facing save operation. */
+	save?(context: MemoryBackendOperationContext, input: MemoryBackendSaveInput): Promise<MemoryBackendSaveResult>;
+
 	/** Render backend-specific memory statistics as markdown (`/memory stats`). */
 	stats?(agentDir: string, cwd: string, session?: AgentSession): Promise<string | undefined>;
 

package/src/mnemopi/backend.ts

@@ -5,10 +5,15 @@ import type { Mnemopi } from "@oh-my-pi/pi-mnemopi";
 import type * as MnemopiDiagnoseNs from "@oh-my-pi/pi-mnemopi/diagnose";
 import type { DiagnosticSummary } from "@oh-my-pi/pi-mnemopi/diagnose";
 import { logger } from "@oh-my-pi/pi-utils";
-
 import type { ModelRegistry } from "../config/model-registry";
 import { resolveRoleSelection } from "../config/model-resolver";
-import type { MemoryBackend, MemoryBackendStartOptions } from "../memory-backend/types";
+import type {
+	MemoryBackend,
+	MemoryBackendSaveInput,
+	MemoryBackendSearchItem,
+	MemoryBackendStartOptions,
+	MemoryBackendStatus,
+} from "../memory-backend/types";
 import memoryConsolidationPrompt from "../prompts/system/memory-consolidation-system.md" with { type: "text" };
 import memoryExtractionPrompt from "../prompts/system/memory-extraction-system.md" with { type: "text" };
 import type { AgentSession } from "../session/agent-session";
@@ -166,6 +171,101 @@ export const mnemopiBackend: MemoryBackend = {
 		return renderMnemopiDiagnostics(summaries);
 	},
 
+	async status({ agentDir, session }): Promise<MemoryBackendStatus> {
+		const state = getMnemopiSessionState(session);
+		const primary = state?.aliasOf ?? state;
+		if (!primary) {
+			return {
+				backend: "mnemopi",
+				active: false,
+				writable: false,
+				searchable: false,
+				message: "Mnemopi backend is not initialised for this session.",
+			};
+		}
+
+		const { targets, owned } = createStatsTargets(agentDir, session);
+		try {
+			if (targets.length === 0) {
+				return {
+					backend: "mnemopi",
+					active: false,
+					writable: false,
+					searchable: false,
+					message: "Mnemopi backend is configured but not initialised for this session.",
+				};
+			}
+			return summarizeMnemopiStatus(targets, session);
+		} finally {
+			for (const memory of owned) memory.close();
+		}
+	},
+
+	async search({ session }, query, options) {
+		const state = getMnemopiSessionState(session);
+		const primary = state?.aliasOf ?? state;
+		if (!primary) {
+			return {
+				backend: "mnemopi",
+				query,
+				count: 0,
+				items: [],
+				message: "Mnemopi backend is not initialised for this session.",
+			};
+		}
+		if (options?.signal?.aborted) {
+			return { backend: "mnemopi", query, count: 0, items: [], message: "Search aborted." };
+		}
+		const limit = clampLimit(options?.limit);
+		const results = (await primary.recallResultsScoped(query)).slice(0, limit);
+		if (options?.signal?.aborted) {
+			return { backend: "mnemopi", query, count: 0, items: [], message: "Search aborted." };
+		}
+		const items: MemoryBackendSearchItem[] = results.map(result => ({
+			id: result.id,
+			content: result.content,
+			source: result.source ?? undefined,
+			timestamp: result.timestamp ?? undefined,
+			score: result.score,
+		}));
+		return { backend: "mnemopi", query, count: items.length, items };
+	},
+
+	async save({ cwd, session }, input: MemoryBackendSaveInput) {
+		const state = getMnemopiSessionState(session);
+		const primary = state?.aliasOf ?? state;
+		if (!primary) {
+			return {
+				backend: "mnemopi",
+				stored: 0,
+				message: "Mnemopi backend is not initialised for this session.",
+			};
+		}
+		const content = input.content.trim();
+		if (!content) return { backend: "mnemopi", stored: 0, message: "Memory content is empty." };
+		const id = primary.rememberScoped(content, {
+			source: input.source || "coding-agent-memory-command",
+			importance: normalizeImportance(input.importance),
+			metadata: {
+				session_id: primary.sessionId,
+				cwd,
+				context: input.context ?? null,
+				operation: "memory.save",
+			},
+			scope: "bank",
+			extract: true,
+			extractEntities: true,
+			veracity: "user",
+			memoryType: "fact",
+		});
+		return {
+			backend: "mnemopi",
+			stored: id ? 1 : 0,
+			ids: id ? [id] : [],
+			message: id ? undefined : "Mnemopi did not return a stored memory id.",
+		};
+	},
+
 	async preCompactionContext(messages, _settings, session): Promise<string | undefined> {
 		const state = getMnemopiSessionState(session);
 		return await state?.recallForCompaction(messages);
@@ -247,6 +347,52 @@ function renderMnemopiStats(targets: readonly MnemopiStatsTarget[]): string {
 	return lines.join("\n");
 }
 
+function summarizeMnemopiStatus(
+	targets: readonly MnemopiStatsTarget[],
+	session: AgentSession | undefined,
+): MemoryBackendStatus {
+	let workingCount = 0;
+	let episodicCount = 0;
+	let tripleCount = 0;
+	let lastMemory: string | undefined;
+	let database: string | undefined;
+	for (const target of targets) {
+		const stats = target.memory.getStats();
+		workingCount += statCount(stats.beam.working_memory);
+		episodicCount += statCount(stats.beam.episodic_memory);
+		tripleCount += stats.beam.triples.total;
+		lastMemory ??= stats.last_memory ?? undefined;
+		database ??= stats.database ? shortenPath(stats.database) : undefined;
+	}
+	const state = getMnemopiSessionState(session);
+	const primary = state?.aliasOf ?? state;
+	return {
+		backend: "mnemopi",
+		active: true,
+		writable: true,
+		searchable: true,
+		scope: primary?.config.scoping,
+		retainBank: primary?.getScopedRetainTarget().bank ?? targets[0]?.bank,
+		recallBanks: primary?.getScopedRecallTargets().map(target => target.bank) ?? targets.map(target => target.bank),
+		workingCount,
+		episodicCount,
+		tripleCount,
+		lastMemory,
+		lastRecall: Boolean(primary?.lastRecallSnippet),
+		database,
+	};
+}
+
+function clampLimit(limit: number | undefined): number {
+	if (!Number.isFinite(limit)) return 10;
+	return Math.max(1, Math.min(50, Math.trunc(limit ?? 10)));
+}
+
+function normalizeImportance(value: number | undefined): number {
+	if (!Number.isFinite(value)) return 0.75;
+	return Math.max(0, Math.min(1, value ?? 0.75));
+}
+
 function renderMnemopiDiagnostics(entries: readonly { bank: string; summary: DiagnosticSummary }[]): string {
 	const lines = [
 		"# Mnemopi Memory Diagnostics",
@@ -343,8 +489,8 @@ async function resolveMnemopiProviderOptions(
 		return {
 			...base,
 			llm: async (prompt, opts) => {
-				const apiKey = await modelRegistry.getApiKey(model, sessionId);
-				if (!apiKey) {
+				const hasApiKey = await modelRegistry.getApiKey(model, sessionId);
+				if (!hasApiKey) {
 					logger.warn("Mnemopi: smol completion requested but no current API key is available.", {
 						provider: model.provider,
 						model: model.id,
@@ -360,6 +506,7 @@ async function resolveMnemopiProviderOptions(
 						apiKey: modelRegistry.resolver(model.provider, {
 							sessionId,
 							baseUrl: model.baseUrl,
+							modelId: model.id,
 						}),
 						maxTokens: opts?.maxTokens,
 						temperature: opts?.temperature,

package/src/modes/acp/acp-agent.ts

@@ -71,7 +71,12 @@ import {
 	type SessionInfo as StoredSessionInfo,
 	type UsageStatistics,
 } from "../../session/session-manager";
-import { ACP_BUILTIN_SLASH_COMMANDS, executeAcpBuiltinSlashCommand } from "../../slash-commands/acp-builtins";
+import {
+	ACP_BUILTIN_RESERVED_NAMES,
+	ACP_BUILTIN_SLASH_COMMANDS,
+	executeAcpBuiltinSlashCommand,
+	isAcpBuiltinShadowedName,
+} from "../../slash-commands/acp-builtins";
 import { AUTO_THINKING, parseConfiguredThinkingLevel } from "../../thinking";
 import { normalizeLocalScheme } from "../../tools/path-utils";
 import { runResolveInvocation } from "../../tools/resolve";
@@ -117,6 +122,7 @@ type PromptQueueState = {
 	promise: Promise<void>;
 	release: (() => void) | undefined;
 };
+type PromptLifecycleError = Error & { readonly code: "ACP_SESSION_CLOSED" };
 
 type PromptTurnState = {
 	userMessageId: string;
@@ -158,6 +164,9 @@ type ManagedSessionRecord = {
 	// Installed inside `#scheduleBootstrapUpdates` (post-race-guard); released
 	// in `#disposeSessionRecord`. Lives independent of any prompt turn.
 	lifetimeUnsubscribe: (() => void) | undefined;
+	closedError: PromptLifecycleError | undefined;
+	promptEventHandlers: Set<Promise<void>>;
+	extensionUserMessageTasks: Set<Promise<void>>;
 };
 
 type ReplayableMessage = {
@@ -594,7 +603,23 @@ export class AcpAgent implements Agent {
 		const record = this.#getSessionRecord(params.sessionId);
 		const activeTurn = record.promptTurn;
 		if (activeTurn && !activeTurn.settled && record.session.isStreaming) {
-			throw new Error("ACP prompt already in progress for this session");
+			// New prompt arrived while the previous turn is still in-flight (e.g. the
+			// client sent a message immediately after pressing stop, before or without
+			// a preceding session/cancel notification). Implicitly cancel the running
+			// turn so the new prompt can queue behind the abort cleanup — identical to
+			// what cancel() does when called explicitly. #beginCancelCleanup is
+			// idempotent, so a concurrent session/cancel notification is harmless.
+			// Mirror cancel()'s timeout handling: if abort() hangs past the cleanup
+			// timeout, close the managed session instead of leaving it registered
+			// with a still-streaming AgentSession. The queued prompt below observes
+			// the same cleanup rejection and fails accordingly.
+			this.#beginCancelCleanup(record, activeTurn).catch(async (error: unknown) => {
+				logger.warn("ACP cancel cleanup timed out; closing session", {
+					sessionId: record.session.sessionId,
+					error,
+				});
+				await this.#closeManagedSession(params.sessionId, record);
+			});
 		}
 		return await this.#queuePrompt(record, async () => {
 			const previousTurn = record.promptTurn;
@@ -607,6 +632,7 @@ export class AcpAgent implements Agent {
 				await previousTurn.promise.catch(() => undefined);
 				await previousTurn.cleanup;
 			}
+			this.#throwIfRecordClosed(record);
 
 			const converted = this.#convertPromptBlocks(params.prompt);
 			const pendingPrompt = Promise.withResolvers<PromptResponse>();
@@ -623,7 +649,7 @@ export class AcpAgent implements Agent {
 			};
 
 			record.promptTurn.unsubscribe = record.session.subscribe(event => {
-				void this.#handlePromptEvent(record, event);
+				this.#trackPromptEvent(record, event);
 			});
 
 			this.#runPromptOrCommand(record, converted.text, converted.images).catch((error: unknown) => {
@@ -643,6 +669,7 @@ export class AcpAgent implements Agent {
 			release: releaseQueue,
 		};
 		await previousQueue.promise;
+		this.#throwIfRecordClosed(record);
 		try {
 			return await run();
 		} finally {
@@ -653,6 +680,55 @@ export class AcpAgent implements Agent {
 		}
 	}
 
+	#throwIfRecordClosed(record: ManagedSessionRecord): void {
+		if (record.closedError) {
+			throw record.closedError;
+		}
+	}
+
+	#createPromptLifecycleError(message: string): PromptLifecycleError {
+		return Object.assign(new Error(message), { code: "ACP_SESSION_CLOSED" as const });
+	}
+
+	#trackPromptEvent(record: ManagedSessionRecord, event: AgentSessionEvent): void {
+		const handling = this.#handlePromptEvent(record, event).catch((error: unknown) => {
+			logger.warn("ACP prompt event handler failed", { error });
+		});
+		record.promptEventHandlers.add(handling);
+		void handling.finally(() => {
+			record.promptEventHandlers.delete(handling);
+		});
+	}
+
+	async #waitForPromptEventHandlers(record: ManagedSessionRecord): Promise<void> {
+		while (record.promptEventHandlers.size > 0) {
+			await Promise.allSettled(Array.from(record.promptEventHandlers));
+		}
+	}
+
+	#trackExtensionUserMessage(record: ManagedSessionRecord, task: Promise<void>): void {
+		const tracked = task.catch((error: unknown) => {
+			logger.warn("ACP extension sendUserMessage failed", { error });
+		});
+		record.extensionUserMessageTasks.add(tracked);
+		void tracked.finally(() => {
+			record.extensionUserMessageTasks.delete(tracked);
+		});
+	}
+
+	async #waitForExtensionUserMessages(
+		record: ManagedSessionRecord,
+		baseline: ReadonlySet<Promise<void>>,
+	): Promise<void> {
+		while (true) {
+			const pending = Array.from(record.extensionUserMessageTasks).filter(task => !baseline.has(task));
+			if (pending.length === 0) {
+				return;
+			}
+			await Promise.allSettled(pending);
+		}
+	}
+
 	async #runPromptOrCommand(record: ManagedSessionRecord, text: string, images: AgentImageContent[]): Promise<void> {
 		const skillResult = await this.#tryRunSkillCommand(record, text);
 		if (skillResult) {
@@ -699,7 +775,18 @@ export class AcpAgent implements Agent {
 			return;
 		}
 
-		await record.session.prompt(text, { images });
+		const extensionPromptBaseline = new Set(record.extensionUserMessageTasks);
+		const agentInvoked = await record.session.prompt(text, { images });
+		// Extension and custom-TS commands are handled locally inside session.prompt().
+		// An ACP extension command can still call pi.sendUserMessage(), which starts
+		// an async nested prompt through the extension runtime. Keep the ACP turn
+		// subscribed until those scheduled prompts and their event handlers drain;
+		// only then is `false` proof that the slash command was purely local.
+		if (!agentInvoked) {
+			await this.#waitForExtensionUserMessages(record, extensionPromptBaseline);
+			await this.#waitForPromptEventHandlers(record);
+			this.#finishPrompt(record, { stopReason: "end_turn" });
+		}
 	}
 
 	async #tryRunSkillCommand(record: ManagedSessionRecord, text: string): Promise<boolean> {
@@ -991,6 +1078,9 @@ export class AcpAgent implements Agent {
 			liveMessageProgress: undefined,
 			toolArgsById: new Map(),
 			extensionsConfigured: false,
+			closedError: undefined,
+			promptEventHandlers: new Set(),
+			extensionUserMessageTasks: new Set(),
 			lifetimeUnsubscribe: undefined,
 		};
 	}
@@ -1582,10 +1672,12 @@ export class AcpAgent implements Agent {
 			commands.push(command);
 		};
 
-		// Advertise in the order dispatch resolves them: ACP builtins first
-		// (so core commands like `/model`, `/mcp`, `/todo` cannot be shadowed),
-		// then skills, then custom/user commands, then file-based slash
-		// commands. `appendCommand` dedupes by name so earlier entries win.
+		// Advertise in the order dispatch resolves them (mirrors AgentSession
+		// dispatch: builtins → skills → extensions → custom TS → file-based).
+		// `appendCommand` dedupes by name so earlier entries win; extension
+		// commands therefore correctly shadow custom TS commands of the same
+		// name, matching the runtime behaviour of #tryExecuteExtensionCommand
+		// running before #tryExecuteCustomCommand.
 		for (const command of ACP_BUILTIN_SLASH_COMMANDS) {
 			appendCommand(command);
 		}
@@ -1600,6 +1692,20 @@ export class AcpAgent implements Agent {
 			}
 		}
 
+		for (const command of session.extensionRunner?.getRegisteredCommands(ACP_BUILTIN_RESERVED_NAMES) ?? []) {
+			// Reserved-set filtering in getRegisteredCommands only covers exact
+			// names; colon-namespaced names whose prefix is a builtin (e.g.
+			// `model:foo`) would still dispatch to the builtin in ACP.
+			if (isAcpBuiltinShadowedName(command.name)) {
+				continue;
+			}
+			appendCommand({
+				name: command.name,
+				description: command.description ?? "(extension command)",
+				input: { hint: "arguments" },
+			});
+		}
+
 		for (const command of session.customCommands) {
 			appendCommand({
 				name: command.command.name,
@@ -2069,9 +2175,7 @@ export class AcpAgent implements Agent {
 					});
 				},
 				sendUserMessage: (content, options) => {
-					record.session.sendUserMessage(content, options).catch((error: unknown) => {
-						logger.warn("ACP extension sendUserMessage failed", { error });
-					});
+					this.#trackExtensionUserMessage(record, record.session.sendUserMessage(content, options));
 				},
 				appendEntry: (customType, data) => {
 					record.session.sessionManager.appendCustomEntry(customType, data);
@@ -2224,6 +2328,7 @@ export class AcpAgent implements Agent {
 	}
 
 	async #closeManagedSession(sessionId: string, record: ManagedSessionRecord): Promise<void> {
+		record.closedError ??= this.#createPromptLifecycleError("ACP session closed before queued prompt could run");
 		this.#sessions.delete(sessionId);
 		await this.#cancelPromptForClose(record);
 		await this.#disposeSessionRecord(record);
@@ -2279,6 +2384,9 @@ export class AcpAgent implements Agent {
 			await Promise.all(
 				records.map(async ([sessionId, record]) => {
 					try {
+						record.closedError ??= this.#createPromptLifecycleError(
+							"ACP agent disposed before queued prompt could run",
+						);
 						await this.#cancelPromptForClose(record);
 						await this.#disposeSessionRecord(record);
 					} catch (error) {