acpx 0.13.0 → 0.13.1

package/dist/runtime.js

@@ -1,7 +1,8 @@
-import { $ as createAtomicWriteTempPath, A as REQUESTED_MODEL_UNSUPPORTED_ERROR_CODE, D as applyLifecycleSnapshotToRecord, Dt as textPrompt, E as applyConversation, F as modelStateFromConfigOptions, Ft as resolveAgentArgv, Ht as extractAcpError, I as normalizeAgentCommandInput, It as resolveAgentCommand, Lt as resolveCanonicalAgentName, M as RequestedModelUnsupportedError, Mt as DEFAULT_AGENT_NAME, Nt as listBuiltInAgents, O as reconcileAgentSessionId, P as isRequestedModelUnsupportedError, Pt as normalizeAgentName, S as advertisedModelState, T as sessionOptionsFromRecord, Ut as isAcpResourceNotFoundError, Vt as normalizeOutputError, _ as createSessionConversation, a as applyRequestedModelIfAdvertised, b as recordSessionUpdate, c as setCurrentModelId, d as setDesiredModelId, et as assertPersistedKeyPolicy, f as syncAdvertisedModelState, g as cloneSessionConversation, h as cloneSessionAcpxState, i as connectAndLoadSession, j as REQUESTED_MODEL_UNSUPPORTED_REASONS, jt as withTimeout, k as AcpClient, l as setDesiredConfigOption, lt as parseSessionRecord, m as applyConfigOptionsToState, n as runPromptTurn, o as currentModelIdFromSetModelResponse, p as applyConfigOptionsToRecord, pt as defaultSessionEventLog, r as withConnectedSession, s as clearDesiredConfigOption, t as LiveSessionCheckpoint, u as setDesiredModeId, ut as serializeSessionRecordForDisk, v as recordClientOperation, w as persistSessionOptions, x as trimConversationForRuntime, y as recordPromptSubmission } from "./live-checkpoint-CBecfnSH.js";
+import { A as REQUESTED_MODEL_UNSUPPORTED_ERROR_CODE, D as applyLifecycleSnapshotToRecord, E as applyConversation, F as modelStateFromConfigOptions, Ft as normalizeAgentName, Ht as normalizeOutputError, I as normalizeAgentCommandInput, It as resolveAgentArgv, Lt as resolveAgentCommand, M as RequestedModelUnsupportedError, Mt as withTimeout, Nt as DEFAULT_AGENT_NAME, O as reconcileAgentSessionId, Ot as textPrompt, P as isRequestedModelUnsupportedError, Pt as listBuiltInAgents, Rt as resolveCanonicalAgentName, S as advertisedModelState, T as sessionOptionsFromRecord, Ut as extractAcpError, Wt as isAcpResourceNotFoundError, _ as createSessionConversation, a as applyRequestedModelIfAdvertised, b as recordSessionUpdate, c as setCurrentModelId, d as setDesiredModelId, dt as serializeSessionRecordForDisk, et as createAtomicWriteTempPath, f as syncAdvertisedModelState, g as cloneSessionConversation, h as cloneSessionAcpxState, i as connectAndLoadSession, j as REQUESTED_MODEL_UNSUPPORTED_REASONS, k as AcpClient, l as setDesiredConfigOption, m as applyConfigOptionsToState, mt as defaultSessionEventLog, n as runPromptTurn, o as currentModelIdFromSetModelResponse, p as applyConfigOptionsToRecord, r as withConnectedSession, s as clearDesiredConfigOption, t as LiveSessionCheckpoint, tt as assertPersistedKeyPolicy, u as setDesiredModeId, ut as parseSessionRecord, v as recordClientOperation, w as persistSessionOptions, x as trimConversationForRuntime, y as recordPromptSubmission } from "./live-checkpoint-BSIrfgVo.js";
 import path from "node:path";
 import fs from "node:fs/promises";
 import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 //#region src/runtime/public/errors.ts
 var AcpRuntimeError = class extends Error {
 	code;
@@ -107,7 +108,46 @@ function planStatusText(payload) {
 	const content = asTrimmedString((Array.isArray(payload.entries) ? payload.entries : []).find((entry) => isRecord(entry))?.content);
 	return content ? `plan: ${content}` : null;
 }
+/**
+* Documented allowlist for text_delta.meta origin fields.
+* Only these keys may be copied from ACP update `_meta`.
+* Unknown keys (including secret-like producer-controlled names) are dropped.
+*/
+const ORIGIN_META_KEYS = [
+	"origin",
+	"kind",
+	"source"
+];
+/**
+* Preserve a fail-closed subset of ACP update origin fields for text_delta
+* consumers. Empty or unusable values are omitted rather than inferred.
+*/
+function extractTextDeltaOrigin(payload) {
+	const messageId = asOptionalString(payload.messageId);
+	const meta = sanitizeOriginMeta(payload._meta);
+	return {
+		...messageId ? { messageId } : {},
+		...meta ? { meta } : {}
+	};
+}
+/**
+* Copy only allowlisted string origin keys from wire `_meta`.
+* Nested objects, arrays, non-strings, and unknown keys are dropped.
+*/
+function sanitizeOriginMeta(value) {
+	if (!isRecord(value)) return;
+	const out = {};
+	for (const key of ORIGIN_META_KEYS) {
+		const entry = value[key];
+		if (typeof entry !== "string") continue;
+		const trimmed = entry.trim();
+		if (!trimmed) continue;
+		out[key] = trimmed;
+	}
+	return Object.keys(out).length > 0 ? out : void 0;
+}
 function resolveTextChunk(params) {
+	const origin = extractTextDeltaOrigin(params.payload);
 	const contentRaw = params.payload.content;
 	if (isRecord(contentRaw)) {
 		const contentType = asTrimmedString(contentRaw.type);
@@ -117,7 +157,8 @@ function resolveTextChunk(params) {
 			type: "text_delta",
 			text,
 			stream: params.stream,
-			tag: params.tag
+			tag: params.tag,
+			...origin
 		};
 	}
 	const text = asString(params.payload.text);
@@ -126,7 +167,8 @@ function resolveTextChunk(params) {
 		type: "text_delta",
 		text,
 		stream: params.stream,
-		tag: params.tag
+		tag: params.tag,
+		...origin
 	};
 }
 function createTextDeltaEvent(params) {
@@ -461,9 +503,15 @@ function shouldReuseExistingRecord(record, params) {
 	if (record.acpx?.reset_on_next_ensure === true) return false;
 	if (path.resolve(record.cwd) !== path.resolve(params.cwd)) return false;
 	if (record.agentCommand !== params.agentCommand) return false;
+	if (!sameArgv(record.agentArgv, params.agentArgv)) return false;
 	if (params.resumeSessionId && record.acpSessionId !== params.resumeSessionId) return false;
 	return true;
 }
+function sameArgv(left, right) {
+	const leftValues = left ?? [];
+	const rightValues = right ?? [];
+	return leftValues.length === rightValues.length && leftValues.every((value, index) => value === rightValues[index]);
+}
 //#endregion
 //#region src/runtime/engine/manager.ts
 function createDeferred() {
@@ -478,6 +526,22 @@ function createDeferred() {
 		reject
 	};
 }
+async function settleAttempt(run) {
+	try {
+		return {
+			ok: true,
+			value: await run()
+		};
+	} catch (error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+}
+function firstFailedAttempt(attempts) {
+	return attempts.find((attempt) => !attempt.ok);
+}
 var AsyncEventQueue = class {
 	items = [];
 	waits = [];
@@ -738,7 +802,10 @@ var AcpRuntimeManager = class {
 	options;
 	deps;
 	activeControllers = /* @__PURE__ */ new Map();
-	pendingPersistentClients = /* @__PURE__ */ new Map();
+	retainedSessionOwners = /* @__PURE__ */ new Map();
+	pendingOneShotRecordIds = /* @__PURE__ */ new Map();
+	ensureSessionLocks = /* @__PURE__ */ new Map();
+	runtimeOperationLocks = /* @__PURE__ */ new Map();
 	closingActiveRecords = /* @__PURE__ */ new Set();
 	constructor(options, deps = {}) {
 		this.options = options;
@@ -747,22 +814,123 @@ var AcpRuntimeManager = class {
 	createClient(options) {
 		return this.deps.clientFactory?.(options) ?? new AcpClient(options);
 	}
-	async readPendingPersistentClient(record, options) {
-		const pendingClient = this.pendingPersistentClients.get(record.acpxRecordId);
-		if (!pendingClient) return;
-		if (!pendingClient.hasReusableSession(record.acpSessionId)) {
-			this.pendingPersistentClients.delete(record.acpxRecordId);
-			await pendingClient.close().catch(() => {});
+	createSessionOwner(input) {
+		const owner = {
+			...input,
+			bufferSessionUpdates: false,
+			pendingSessionUpdates: []
+		};
+		input.client.setEventHandlers({
+			onSessionUpdate: (notification) => this.routeOwnedSessionUpdate(owner, notification),
+			onClientOperation: (operation) => this.routeOwnedClientOperation(owner, operation)
+		});
+		return owner;
+	}
+	routeOwnedSessionUpdate(owner, notification) {
+		const active = owner.activeTurn;
+		if (active) {
+			const { task, turn } = active;
+			if (turn.connectionUpdates) {
+				turn.connectionUpdates.push(notification);
+				this.emitRuntimeTurnEvent(task, {
+					jsonrpc: "2.0",
+					method: "session/update",
+					params: notification
+				});
+				return;
+			}
+			turn.acpxState = recordSessionUpdate(turn.conversation, turn.acpxState, notification);
+			trimConversationForRuntime(turn.conversation);
+			turn.liveCheckpoint.request();
+			this.emitRuntimeTurnEvent(task, {
+				jsonrpc: "2.0",
+				method: "session/update",
+				params: notification
+			});
+			return;
+		}
+		if (owner.bufferSessionUpdates) {
+			owner.pendingSessionUpdates.push(notification);
+			return;
+		}
+		const projection = owner.projection;
+		if (!projection) {
+			owner.pendingSessionUpdates.push(notification);
 			return;
 		}
-		if (options.consume) this.pendingPersistentClients.delete(record.acpxRecordId);
-		return pendingClient;
+		projection.acpxState = recordSessionUpdate(projection.conversation, projection.acpxState, notification);
+		trimConversationForRuntime(projection.conversation);
+		projection.checkpoint.request();
+	}
+	routeOwnedClientOperation(owner, operation) {
+		const active = owner.activeTurn;
+		if (!active) return;
+		const { task, turn } = active;
+		turn.acpxState = recordClientOperation(turn.conversation, turn.acpxState, operation);
+		trimConversationForRuntime(turn.conversation);
+		turn.liveCheckpoint.request();
+		this.emitRuntimeTurnEvent(task, {
+			type: "client_operation",
+			...operation
+		});
 	}
-	async closePendingPersistentClient(recordId) {
-		const pendingClient = this.pendingPersistentClients.get(recordId);
-		if (!pendingClient) return;
-		this.pendingPersistentClients.delete(recordId);
-		await pendingClient.close().catch(() => {});
+	attachIdleProjection(owner, record, conversation = cloneSessionConversation(record), acpxState = cloneSessionAcpxState(record.acpx)) {
+		let projection;
+		projection = {
+			record,
+			conversation,
+			acpxState,
+			checkpoint: new LiveSessionCheckpoint({ save: async () => {
+				record.lastUsedAt = isoNow();
+				record.acpx = projection.acpxState;
+				applyConversation(record, projection.conversation);
+				applyLifecycleSnapshotToRecord(record, owner.client.getAgentLifecycleSnapshot());
+				await this.refreshClosedState(record);
+				await this.options.sessionStore.save(record);
+			} })
+		};
+		owner.projection = projection;
+		owner.activeTurn = void 0;
+		this.drainPendingSessionUpdates(owner);
+	}
+	drainPendingSessionUpdates(owner) {
+		for (const notification of owner.pendingSessionUpdates.splice(0)) this.routeOwnedSessionUpdate(owner, notification);
+	}
+	async flushSessionOwner(owner) {
+		await owner.client.waitForSessionUpdatesIdle?.().catch(() => {});
+		await owner.projection?.checkpoint.flush();
+	}
+	removeRetainedSessionOwner(owner) {
+		if (owner.recordId && this.retainedSessionOwners.get(owner.recordId) === owner) this.retainedSessionOwners.delete(owner.recordId);
+		if (owner.mode === "oneshot" && owner.recordId && this.pendingOneShotRecordIds.get(owner.sessionKey) === owner.recordId) this.pendingOneShotRecordIds.delete(owner.sessionKey);
+	}
+	async readRetainedSessionOwner(record, options) {
+		const owner = this.retainedSessionOwners.get(record.acpxRecordId);
+		if (!owner) return;
+		await this.flushSessionOwner(owner);
+		const projectedRecord = owner.projection?.record;
+		if (projectedRecord && projectedRecord !== record) Object.assign(record, structuredClone(projectedRecord));
+		if (!owner.client.hasReusableSession(record.acpSessionId)) {
+			this.removeRetainedSessionOwner(owner);
+			await this.stopSessionOwner(owner);
+			return;
+		}
+		if (options.consume) this.removeRetainedSessionOwner(owner);
+		return owner;
+	}
+	async closeRetainedSessionOwner(recordId) {
+		const owner = this.retainedSessionOwners.get(recordId);
+		if (!owner) return;
+		this.removeRetainedSessionOwner(owner);
+		await this.stopSessionOwner(owner);
+	}
+	async stopSessionOwner(owner) {
+		await this.flushSessionOwner(owner).catch(() => {});
+		await owner.client.close().catch(() => {});
+		await owner.projection?.checkpoint.flush().catch(() => {});
+		try {
+			owner.client.clearEventHandlers();
+		} catch {}
 	}
 	async refreshClosedState(record) {
 		if (!this.closingActiveRecords.has(record.acpxRecordId)) return record.closed === true;
@@ -775,32 +943,43 @@ var AcpRuntimeManager = class {
 		};
 		return true;
 	}
-	async retainPersistentClientAfterTurn(input) {
-		const { record, client } = input;
-		if (!!record.acpxRecordId.includes(":oneshot:") || record.closed || !client.hasReusableSession(record.acpSessionId)) return false;
-		const previousClient = this.pendingPersistentClients.get(record.acpxRecordId);
-		this.pendingPersistentClients.set(record.acpxRecordId, client);
-		if (previousClient && previousClient !== client) await previousClient.close().catch(() => {});
+	async retainPersistentSessionOwnerAfterTurn(input) {
+		const { record, owner, conversation, acpxState } = input;
+		if (!this.canRetainPersistentSessionOwner(owner, record)) {
+			owner.activeTurn = void 0;
+			return false;
+		}
+		this.attachIdleProjection(owner, record, conversation, acpxState);
+		const previousOwner = this.retainedSessionOwners.get(record.acpxRecordId);
+		this.retainedSessionOwners.set(record.acpxRecordId, owner);
+		if (previousOwner && previousOwner !== owner) {
+			this.removeRetainedSessionOwner(previousOwner);
+			await this.stopSessionOwner(previousOwner);
+		}
 		return true;
 	}
+	canRetainPersistentSessionOwner(owner, record) {
+		return owner.mode === "persistent" && !record.closed && !(owner.client.hasUnresolvedPrompt?.() ?? false) && owner.client.hasReusableSession(record.acpSessionId);
+	}
 	async withRuntimeControlSession(record, sessionMode, run) {
-		const pendingClient = await this.readPendingPersistentClient(record, { consume: false });
-		if (pendingClient) {
-			const value = await run({
-				client: pendingClient,
-				sessionId: record.acpSessionId,
-				record
-			});
-			record.lastUsedAt = isoNow();
-			record.closed = false;
-			record.closedAt = void 0;
-			record.protocolVersion = pendingClient.initializeResult?.protocolVersion;
-			record.agentCapabilities = pendingClient.initializeResult?.agentCapabilities;
-			applyLifecycleSnapshotToRecord(record, pendingClient.getAgentLifecycleSnapshot());
-			return {
-				value,
-				record
-			};
+		const owner = await this.readRetainedSessionOwner(record, { consume: false });
+		if (owner) {
+			const ownedRecord = owner.projection?.record ?? record;
+			owner.bufferSessionUpdates = true;
+			try {
+				const value = await run({
+					client: owner.client,
+					sessionId: ownedRecord.acpSessionId,
+					record: ownedRecord
+				});
+				this.refreshOwnedRecordLifecycle(owner, ownedRecord);
+				return {
+					value,
+					record: ownedRecord
+				};
+			} finally {
+				await this.finishBufferedOwnerControl(owner, ownedRecord);
+			}
 		}
 		const result = await withConnectedSession({
 			sessionRecordId: record.acpxRecordId,
@@ -810,7 +989,9 @@ var AcpRuntimeManager = class {
 			mcpServers: [...this.options.mcpServers ?? []],
 			permissionMode: this.options.permissionMode,
 			nonInteractivePermissions: this.options.nonInteractivePermissions,
+			permissionPolicy: this.options.permissionPolicy,
 			onPermissionRequest: this.options.onPermissionRequest,
+			elicitationModes: this.options.elicitationModes,
 			verbose: this.options.verbose,
 			timeoutMs: this.options.timeoutMs,
 			resumePolicy: resumePolicyForSessionMode(sessionMode),
@@ -821,21 +1002,98 @@ var AcpRuntimeManager = class {
 			record: result.record
 		};
 	}
+	refreshOwnedRecordLifecycle(owner, record) {
+		record.lastUsedAt = isoNow();
+		record.closed = false;
+		record.closedAt = void 0;
+		record.protocolVersion = owner.client.initializeResult?.protocolVersion;
+		record.agentCapabilities = owner.client.initializeResult?.agentCapabilities;
+		applyLifecycleSnapshotToRecord(record, owner.client.getAgentLifecycleSnapshot());
+	}
+	async finishBufferedOwnerControl(owner, record) {
+		const projection = owner.projection;
+		if (projection) projection.acpxState = cloneSessionAcpxState(record.acpx);
+		owner.bufferSessionUpdates = false;
+		this.drainPendingSessionUpdates(owner);
+		if (projection) {
+			record.acpx = projection.acpxState;
+			applyConversation(record, projection.conversation);
+			await projection.checkpoint.flush();
+		}
+	}
 	async ensureSession(input) {
+		return await this.withEnsureSessionLock(input, async () => this.ensureSessionWithOwnership(input));
+	}
+	async withEnsureSessionLock(input, run) {
+		const key = `${input.mode}\0${input.sessionKey}`;
+		return await this.withManagerLock(this.ensureSessionLocks, key, run);
+	}
+	async withManagerLock(locks, key, run) {
+		const previous = locks.get(key) ?? Promise.resolve();
+		let release;
+		const gate = new Promise((resolve) => {
+			release = resolve;
+		});
+		const tail = previous.then(() => gate);
+		locks.set(key, tail);
+		await previous;
+		try {
+			return await run();
+		} finally {
+			release();
+			if (locks.get(key) === tail) locks.delete(key);
+		}
+	}
+	async ensureSessionWithOwnership(input) {
 		const cwd = path.resolve(input.cwd?.trim() || this.options.cwd);
 		const { agentCommand, agentArgv } = normalizeAgentCommandInput(this.options.agentRegistry.resolve(input.agent));
-		const existing = await this.options.sessionStore.load(input.sessionKey);
-		if (input.mode === "persistent" && existing && shouldReuseExistingRecord(existing, {
+		const agent = {
 			cwd,
 			agentCommand,
-			resumeSessionId: input.resumeSessionId
-		})) {
-			existing.closed = false;
-			existing.closedAt = void 0;
-			this.closingActiveRecords.delete(existing.acpxRecordId);
-			await this.options.sessionStore.save(existing);
-			return existing;
+			agentArgv
+		};
+		const existing = await this.loadExistingRuntimeSession(input);
+		if (existing && this.canReuseRuntimeSession(input, agent, existing)) return await this.reuseRuntimeSession(existing.record);
+		await this.closeConflictingPersistentSession(input, existing?.owner);
+		return await this.createOwnedRuntimeSession(input, agent);
+	}
+	async loadExistingRuntimeSession(input) {
+		const existingRecordId = input.mode === "persistent" ? input.sessionKey : this.pendingOneShotRecordIds.get(input.sessionKey);
+		if (!existingRecordId) return;
+		let record = await this.options.sessionStore.load(existingRecordId);
+		if (!record) return;
+		const owner = this.retainedSessionOwners.get(record.acpxRecordId);
+		if (owner) {
+			await this.flushSessionOwner(owner);
+			record = owner.projection?.record ?? record;
 		}
+		return {
+			record,
+			owner
+		};
+	}
+	canReuseRuntimeSession(input, agent, existing) {
+		if (!shouldReuseExistingRecord(existing.record, {
+			cwd: agent.cwd,
+			agentCommand: agent.agentCommand,
+			agentArgv: agent.agentArgv,
+			resumeSessionId: input.resumeSessionId
+		})) return false;
+		if (input.mode === "persistent") return true;
+		return Boolean(existing.owner && isDeepStrictEqual(sessionOptionsFromRecord(existing.record), input.sessionOptions));
+	}
+	async reuseRuntimeSession(record) {
+		record.closed = false;
+		record.closedAt = void 0;
+		this.closingActiveRecords.delete(record.acpxRecordId);
+		await this.options.sessionStore.save(record);
+		return record;
+	}
+	async closeConflictingPersistentSession(input, owner) {
+		if (input.mode === "persistent" && owner?.recordId) await this.closeRetainedSessionOwner(owner.recordId);
+	}
+	async createOwnedRuntimeSession(input, agent) {
+		const { cwd, agentCommand, agentArgv } = agent;
 		const client = this.createClient({
 			agentCommand,
 			agentArgv,
@@ -843,11 +1101,18 @@ var AcpRuntimeManager = class {
 			mcpServers: [...this.options.mcpServers ?? []],
 			permissionMode: this.options.permissionMode,
 			nonInteractivePermissions: this.options.nonInteractivePermissions,
+			permissionPolicy: this.options.permissionPolicy,
 			onPermissionRequest: this.options.onPermissionRequest,
+			elicitationModes: this.options.elicitationModes,
 			verbose: this.options.verbose,
 			sessionOptions: input.sessionOptions
 		});
-		let keepClientOpen = false;
+		const owner = this.createSessionOwner({
+			client,
+			sessionKey: input.sessionKey,
+			mode: input.mode
+		});
+		let retained = false;
 		try {
 			await client.start();
 			const session = await createOrLoadRuntimeSession(client, input.resumeSessionId, cwd);
@@ -859,10 +1124,15 @@ var AcpRuntimeManager = class {
 				cwd,
 				session
 			});
-			keepClientOpen = await this.keepPersistentClient(input.mode, record.acpxRecordId, client);
+			this.attachIdleProjection(owner, record);
+			await this.retainInitializedSessionOwner(owner, record);
+			retained = true;
 			return record;
 		} finally {
-			if (!keepClientOpen) await client.close();
+			if (!retained) {
+				client.clearEventHandlers();
+				await client.close();
+			}
 		}
 	}
 	async createAndSaveRuntimeRecord(params) {
@@ -896,17 +1166,28 @@ var AcpRuntimeManager = class {
 		await this.options.sessionStore.save(record);
 		return record;
 	}
-	async keepPersistentClient(mode, recordId, client) {
-		if (mode !== "persistent") return false;
-		const previousClient = this.pendingPersistentClients.get(recordId);
-		this.pendingPersistentClients.set(recordId, client);
-		await previousClient?.close().catch(() => {});
-		return true;
+	async retainInitializedSessionOwner(owner, record) {
+		owner.recordId = record.acpxRecordId;
+		const previousOwner = this.retainedSessionOwners.get(record.acpxRecordId);
+		this.retainedSessionOwners.set(record.acpxRecordId, owner);
+		if (owner.mode === "oneshot") this.pendingOneShotRecordIds.set(owner.sessionKey, record.acpxRecordId);
+		if (previousOwner && previousOwner !== owner) {
+			this.removeRetainedSessionOwner(previousOwner);
+			await this.stopSessionOwner(previousOwner);
+		}
 	}
 	startTurn(input) {
-		const promptInput = toPromptInput(input.text, input.attachments);
+		let promptInput;
+		try {
+			promptInput = toPromptInput(input.text, input.attachments);
+		} catch (error) {
+			this.closeRetainedOneShotHandle(input.handle).catch(() => {});
+			throw error;
+		}
 		const queue = new AsyncEventQueue();
 		const result = createDeferred();
+		const promptStarted = createDeferred();
+		promptStarted.promise.catch(() => {});
 		const sessionReady = createDeferred();
 		sessionReady.promise.catch(() => {});
 		let resultSettled = false;
@@ -938,13 +1219,17 @@ var AcpRuntimeManager = class {
 		};
 		if (input.signal) {
 			if (input.signal.aborted) {
+				promptStarted.reject(/* @__PURE__ */ new Error("ACP turn cancelled before prompt submission."));
 				closeStream();
-				settleResult({
-					status: "cancelled",
-					stopReason: "cancelled"
+				this.closeRetainedOneShotHandle(input.handle).catch(() => {}).then(() => {
+					settleResult({
+						status: "cancelled",
+						stopReason: "cancelled"
+					});
 				});
 				return {
 					requestId: input.requestId,
+					promptStarted: promptStarted.promise,
 					events: queue.iterate(),
 					result: result.promise,
 					cancel: async () => {},
@@ -957,6 +1242,7 @@ var AcpRuntimeManager = class {
 			input,
 			promptInput,
 			queue,
+			promptStarted,
 			sessionReady,
 			state,
 			settleResult,
@@ -964,6 +1250,7 @@ var AcpRuntimeManager = class {
 		});
 		return {
 			requestId: input.requestId,
+			promptStarted: promptStarted.promise,
 			events: queue.iterate(),
 			result: result.promise,
 			cancel: async () => {
@@ -974,61 +1261,160 @@ var AcpRuntimeManager = class {
 			}
 		};
 	}
+	async closeRetainedOneShotHandle(handle) {
+		const recordId = handle.acpxRecordId ?? handle.sessionKey;
+		if (this.retainedSessionOwners.get(recordId)?.mode === "oneshot") await this.closeRetainedSessionOwner(recordId);
+	}
 	async runRuntimeTurnTask(task) {
 		let turn;
+		let terminalResult;
 		try {
 			turn = await this.prepareRuntimeTurn(task);
 			const { sessionId, resumed, loadError } = await this.connectRuntimeTurn(task, turn);
 			await this.resolveRuntimeTurnReady(task, turn, resumed, loadError);
-			if (this.cancelRuntimeTurnBeforePrompt(task)) return;
-			await this.applyPendingRuntimeTurnCancel(task, turn);
-			const response = await runPromptTurn({
+			if (this.cancelRuntimeTurnBeforePrompt(task)) terminalResult = {
+				status: "cancelled",
+				stopReason: "cancelled"
+			};
+			else {
+				await this.applyPendingRuntimeTurnCancel(task, turn);
+				const response = await this.runRuntimePrompt(task, turn, sessionId);
+				await this.saveCompletedRuntimeTurn(turn, response.stopReason);
+				terminalResult = {
+					status: response.stopReason === "cancelled" ? "cancelled" : "completed",
+					...response.stopReason ? { stopReason: response.stopReason } : {}
+				};
+			}
+		} catch (error) {
+			terminalResult = this.failRuntimeTurn(task, error);
+		}
+		try {
+			await this.finalizeRuntimeTurn(task, turn);
+		} catch (error) {
+			terminalResult = this.failRuntimeTurn(task, error);
+		}
+		task.settleResult(terminalResult);
+	}
+	async runRuntimePrompt(task, turn, sessionId) {
+		try {
+			return await runPromptTurn({
 				client: turn.client,
 				sessionId,
 				prompt: task.promptInput,
 				timeoutMs: task.input.timeoutMs ?? this.options.timeoutMs,
 				conversation: turn.conversation,
-				promptMessageId: turn.promptMessageId
-			});
-			await this.saveCompletedRuntimeTurn(turn, response.stopReason);
-			task.settleResult({
-				status: response.stopReason === "cancelled" ? "cancelled" : "completed",
-				...response.stopReason ? { stopReason: response.stopReason } : {}
+				promptMessageId: turn.promptMessageId,
+				onPromptRequestStarted: () => task.promptStarted.resolve(),
+				onElicitation: task.input.onElicitation
 			});
-		} catch (error) {
-			this.failRuntimeTurn(task, error);
 		} finally {
-			await this.finalizeRuntimeTurn(task, turn);
+			turn.client.endPromptElicitation?.(sessionId);
 		}
 	}
 	async prepareRuntimeTurn(task) {
-		const record = await this.requireRecord(task.input.handle.acpxRecordId ?? task.input.handle.sessionKey);
+		const recordId = task.input.handle.acpxRecordId ?? task.input.handle.sessionKey;
+		return await this.withManagerLock(this.runtimeOperationLocks, recordId, async () => this.prepareRuntimeTurnWithOwnership(task));
+	}
+	async prepareRuntimeTurnWithOwnership(task) {
+		const { record, retainedOwner, conversation, acpxState, promptMessageId } = await this.prepareRuntimeTurnState(task);
+		try {
+			const client = retainedOwner?.client ?? this.createTurnClient(record);
+			const owner = this.resolveRuntimeTurnOwner(task, record, client, retainedOwner);
+			const turn = this.createRunningRuntimeTurn({
+				record,
+				conversation,
+				acpxState,
+				client,
+				owner,
+				pendingClient: retainedOwner?.client,
+				promptMessageId
+			});
+			this.activateRuntimeTurn(task, turn);
+			return turn;
+		} catch (error) {
+			this.restoreBufferedSessionOwner(retainedOwner);
+			throw error;
+		}
+	}
+	async prepareRuntimeTurnState(task) {
+		const { record, retainedOwner } = await this.acquireRuntimeTurnState(task);
 		const conversation = cloneSessionConversation(record);
-		let acpxState = cloneSessionAcpxState(record.acpx);
-		const promptStartedAt = isoNow();
-		const promptMessageId = recordPromptSubmission(conversation, task.promptInput, promptStartedAt);
-		trimConversationForRuntime(conversation);
-		record.lastPromptAt = promptStartedAt;
-		record.lastUsedAt = promptStartedAt;
-		record.acpx = acpxState;
-		applyConversation(record, conversation);
-		await this.options.sessionStore.save(record);
-		const pendingClient = await this.readPendingPersistentClient(record, { consume: true });
-		const client = pendingClient ?? this.createTurnClient(record);
+		const acpxState = cloneSessionAcpxState(record.acpx);
+		try {
+			const promptStartedAt = isoNow();
+			const promptMessageId = recordPromptSubmission(conversation, task.promptInput, promptStartedAt);
+			trimConversationForRuntime(conversation);
+			record.lastPromptAt = promptStartedAt;
+			record.lastUsedAt = promptStartedAt;
+			record.acpx = acpxState;
+			applyConversation(record, conversation);
+			await this.options.sessionStore.save(record);
+			return {
+				record,
+				retainedOwner,
+				conversation,
+				acpxState,
+				promptMessageId
+			};
+		} catch (error) {
+			this.restoreBufferedSessionOwner(retainedOwner);
+			throw error;
+		}
+	}
+	async acquireRuntimeTurnState(task) {
+		const recordId = task.input.handle.acpxRecordId ?? task.input.handle.sessionKey;
+		let record = await this.requireRecord(recordId);
+		const retainedOwner = await this.readRetainedSessionOwner(record, { consume: false });
+		if (!retainedOwner) return { record };
+		const projection = retainedOwner.projection;
+		if (projection) record = structuredClone(projection.record);
+		retainedOwner.bufferSessionUpdates = true;
+		return {
+			record,
+			retainedOwner
+		};
+	}
+	restoreBufferedSessionOwner(owner) {
+		if (!owner) return;
+		owner.bufferSessionUpdates = false;
+		this.drainPendingSessionUpdates(owner);
+	}
+	resolveRuntimeTurnOwner(task, record, client, retainedOwner) {
+		return retainedOwner ?? this.createSessionOwner({
+			client,
+			sessionKey: record.name ?? task.input.handle.sessionKey,
+			mode: task.input.sessionMode
+		});
+	}
+	createRunningRuntimeTurn(input) {
+		const { record, conversation, acpxState, client, owner, pendingClient, promptMessageId } = input;
 		const turn = {
 			record,
 			conversation,
 			acpxState,
 			liveCheckpoint: this.createRuntimeTurnCheckpoint(record, conversation, () => turn.acpxState),
 			client,
+			owner,
 			pendingClient,
+			connectionUpdates: pendingClient ? void 0 : [],
 			promptMessageId,
 			activeSessionId: record.acpSessionId
 		};
+		return turn;
+	}
+	activateRuntimeTurn(task, turn) {
+		const { owner, record } = turn;
+		this.removeRetainedSessionOwner(owner);
+		owner.recordId = record.acpxRecordId;
 		task.state.activeController = this.buildRuntimeTurnController(task, turn);
 		this.activeControllers.set(record.acpxRecordId, task.state.activeController);
-		this.installRuntimeTurnEventHandlers(task, turn);
-		return turn;
+		owner.projection = void 0;
+		owner.activeTurn = {
+			task,
+			turn
+		};
+		owner.bufferSessionUpdates = false;
+		this.drainPendingSessionUpdates(owner);
 	}
 	createTurnClient(record) {
 		return this.createClient({
@@ -1038,7 +1424,9 @@ var AcpRuntimeManager = class {
 			mcpServers: [...this.options.mcpServers ?? []],
 			permissionMode: this.options.permissionMode,
 			nonInteractivePermissions: this.options.nonInteractivePermissions,
+			permissionPolicy: this.options.permissionPolicy,
 			onPermissionRequest: this.options.onPermissionRequest,
+			elicitationModes: this.options.elicitationModes,
 			verbose: this.options.verbose,
 			sessionOptions: sessionOptionsFromRecord(record)
 		});
@@ -1111,29 +1499,6 @@ var AcpRuntimeManager = class {
 		applyConfigOptionResponseToTurn(turn, response);
 		applyDesiredConfigOptionToTurn(turn, configId, value);
 	}
-	installRuntimeTurnEventHandlers(task, turn) {
-		turn.client.setEventHandlers({
-			onSessionUpdate: (notification) => {
-				turn.acpxState = recordSessionUpdate(turn.conversation, turn.acpxState, notification);
-				trimConversationForRuntime(turn.conversation);
-				turn.liveCheckpoint.request();
-				this.emitRuntimeTurnEvent(task, {
-					jsonrpc: "2.0",
-					method: "session/update",
-					params: notification
-				});
-			},
-			onClientOperation: (operation) => {
-				turn.acpxState = recordClientOperation(turn.conversation, turn.acpxState, operation);
-				trimConversationForRuntime(turn.conversation);
-				turn.liveCheckpoint.request();
-				this.emitRuntimeTurnEvent(task, {
-					type: "client_operation",
-					...operation
-				});
-			}
-		});
-	}
 	emitRuntimeTurnEvent(task, payload) {
 		const parsed = parsePromptEventLine(JSON.stringify(payload));
 		if (!parsed) return;
@@ -1145,9 +1510,17 @@ var AcpRuntimeManager = class {
 			resumed: false,
 			loadError: void 0
 		} : await this.connectRuntimeTurnClient(task, turn);
-		turn.acpxState = cloneSessionAcpxState(turn.record.acpx);
+		this.drainRuntimeConnectionUpdates(turn);
 		return loaded;
 	}
+	drainRuntimeConnectionUpdates(turn) {
+		if (!turn.connectionUpdates) return;
+		turn.acpxState = cloneSessionAcpxState(turn.record.acpx);
+		for (const notification of turn.connectionUpdates) turn.acpxState = recordSessionUpdate(turn.conversation, turn.acpxState, notification);
+		turn.connectionUpdates = void 0;
+		trimConversationForRuntime(turn.conversation);
+		turn.liveCheckpoint.request();
+	}
 	async connectRuntimeTurnClient(task, turn) {
 		return await connectAndLoadSession({
 			client: turn.client,
@@ -1188,10 +1561,7 @@ var AcpRuntimeManager = class {
 	cancelRuntimeTurnBeforePrompt(task) {
 		if (!task.state.pendingCancel && !task.input.signal?.aborted) return false;
 		task.state.pendingCancel = false;
-		task.settleResult({
-			status: "cancelled",
-			stopReason: "cancelled"
-		});
+		task.promptStarted.reject(/* @__PURE__ */ new Error("ACP turn cancelled before prompt submission."));
 		return true;
 	}
 	async applyPendingRuntimeTurnCancel(task, turn) {
@@ -1211,9 +1581,10 @@ var AcpRuntimeManager = class {
 		await this.options.sessionStore.save(turn.record);
 	}
 	failRuntimeTurn(task, error) {
+		task.promptStarted.reject(error);
 		task.sessionReady.reject(error);
 		const normalized = normalizeOutputError(error, { origin: "runtime" });
-		task.settleResult({
+		return {
 			status: "failed",
 			error: {
 				message: normalized.message,
@@ -1221,13 +1592,36 @@ var AcpRuntimeManager = class {
 				...normalized.detailCode ? { detailCode: normalized.detailCode } : {},
 				...normalized.retryable !== void 0 ? { retryable: normalized.retryable } : {}
 			}
-		});
+		};
 	}
 	async finalizeRuntimeTurn(task, turn) {
 		task.state.turnActive = false;
-		task.input.signal?.removeEventListener("abort", task.abortHandler);
-		turn?.client.clearEventHandlers();
-		if (!(turn ? await this.finalizeRuntimeTurnRecord(turn) : false)) await turn?.client.close().catch(() => {});
+		const abortHandlerAttempt = await settleAttempt(() => task.input.signal?.removeEventListener("abort", task.abortHandler));
+		const recordAttempt = await settleAttempt(async () => turn ? await this.finalizeRuntimeTurnRecord(turn) : false);
+		let failure = firstFailedAttempt([abortHandlerAttempt, recordAttempt]);
+		let pooled = recordAttempt.ok ? recordAttempt.value : false;
+		if (failure) {
+			this.discardRetainedRuntimeTurnOwner(turn);
+			pooled = false;
+		}
+		const closeAttempt = await settleAttempt(async () => this.closeRuntimeTurnClient(turn, pooled));
+		this.cleanupRuntimeTurn(task, turn);
+		failure ??= firstFailedAttempt([closeAttempt]);
+		if (failure) throw failure.error;
+	}
+	discardRetainedRuntimeTurnOwner(turn) {
+		if (turn) {
+			this.removeRetainedSessionOwner(turn.owner);
+			turn.owner.activeTurn = void 0;
+		}
+	}
+	async closeRuntimeTurnClient(turn, pooled) {
+		if (!turn || pooled) return;
+		turn.owner.activeTurn = void 0;
+		const failure = firstFailedAttempt([await settleAttempt(() => turn.client.clearEventHandlers()), await settleAttempt(async () => turn.client.close())]);
+		if (failure) throw failure.error;
+	}
+	cleanupRuntimeTurn(task, turn) {
 		if (turn) {
 			this.activeControllers.delete(turn.record.acpxRecordId);
 			this.closingActiveRecords.delete(turn.record.acpxRecordId);
@@ -1235,17 +1629,20 @@ var AcpRuntimeManager = class {
 		task.queue.close();
 	}
 	async finalizeRuntimeTurnRecord(turn) {
+		this.drainRuntimeConnectionUpdates(turn);
 		applyLifecycleSnapshotToRecord(turn.record, turn.client.getAgentLifecycleSnapshot());
 		turn.record.acpx = turn.acpxState;
 		applyConversation(turn.record, turn.conversation);
 		turn.record.lastUsedAt = isoNow();
-		await turn.liveCheckpoint.flush().catch(() => {});
+		await turn.liveCheckpoint.flush();
 		const closed = await this.refreshClosedState(turn.record);
-		await this.options.sessionStore.save(turn.record).catch(() => {});
+		await this.options.sessionStore.save(turn.record);
 		if (closed) return false;
-		return await this.retainPersistentClientAfterTurn({
+		return await this.retainPersistentSessionOwnerAfterTurn({
 			record: turn.record,
-			client: turn.client
+			owner: turn.owner,
+			conversation: turn.conversation,
+			acpxState: turn.acpxState
 		});
 	}
 	async *runTurn(input) {
@@ -1254,7 +1651,10 @@ var AcpRuntimeManager = class {
 		yield legacyTerminalEventFromTurnResult(await turn.result);
 	}
 	async getStatus(handle) {
-		const record = await this.requireRecord(handle.acpxRecordId ?? handle.sessionKey);
+		const recordId = handle.acpxRecordId ?? handle.sessionKey;
+		const owner = this.retainedSessionOwners.get(recordId);
+		if (owner) await this.flushSessionOwner(owner);
+		const record = await this.requireRecord(recordId);
 		return {
 			summary: statusSummary(record),
 			acpxRecordId: record.acpxRecordId,
@@ -1272,6 +1672,10 @@ var AcpRuntimeManager = class {
 		};
 	}
 	async setMode(handle, mode, sessionMode = "persistent") {
+		const recordId = handle.acpxRecordId ?? handle.sessionKey;
+		await this.withManagerLock(this.runtimeOperationLocks, recordId, async () => this.setModeWithOwnership(handle, mode, sessionMode));
+	}
+	async setModeWithOwnership(handle, mode, sessionMode) {
 		const record = await this.requireRecord(handle.acpxRecordId ?? handle.sessionKey);
 		const controller = this.activeControllers.get(record.acpxRecordId);
 		let targetRecord = record;
@@ -1283,6 +1687,10 @@ var AcpRuntimeManager = class {
 		await this.options.sessionStore.save(targetRecord);
 	}
 	async setConfigOption(handle, key, value, sessionMode = "persistent") {
+		const recordId = handle.acpxRecordId ?? handle.sessionKey;
+		await this.withManagerLock(this.runtimeOperationLocks, recordId, async () => this.setConfigOptionWithOwnership(handle, key, value, sessionMode));
+	}
+	async setConfigOptionWithOwnership(handle, key, value, sessionMode) {
 		const record = await this.requireRecord(handle.acpxRecordId ?? handle.sessionKey);
 		const controller = this.activeControllers.get(record.acpxRecordId);
 		if (controller) {
@@ -1303,43 +1711,80 @@ var AcpRuntimeManager = class {
 		await this.activeControllers.get(handle.acpxRecordId ?? handle.sessionKey)?.requestCancelActivePrompt();
 	}
 	async close(handle, options = {}) {
-		const record = await this.requireRecord(handle.acpxRecordId ?? handle.sessionKey);
-		if (this.activeControllers.has(record.acpxRecordId)) this.closingActiveRecords.add(record.acpxRecordId);
+		const recordId = handle.acpxRecordId ?? handle.sessionKey;
+		const record = await this.resolveRuntimeRecordForClose(recordId);
+		this.markActiveRuntimeRecordClosing(record);
 		await this.cancel(handle);
-		if (options.discardPersistentState) {
+		await this.closeRuntimeRecordOwnership(record, options.discardPersistentState === true);
+		record.closed = true;
+		record.closedAt = isoNow();
+		await this.options.sessionStore.save(record);
+	}
+	async resolveRuntimeRecordForClose(recordId) {
+		const retainedOwner = this.retainedSessionOwners.get(recordId);
+		if (retainedOwner) await this.flushSessionOwner(retainedOwner);
+		return retainedOwner?.projection?.record ?? await this.requireRecord(recordId);
+	}
+	markActiveRuntimeRecordClosing(record) {
+		if (this.activeControllers.has(record.acpxRecordId)) this.closingActiveRecords.add(record.acpxRecordId);
+	}
+	async closeRuntimeRecordOwnership(record, discardPersistentState) {
+		if (discardPersistentState) {
 			await this.closeBackendSession(record);
 			record.acpx = {
 				...record.acpx,
 				reset_on_next_ensure: true
 			};
-		} else await this.closePendingPersistentClient(record.acpxRecordId);
-		record.closed = true;
-		record.closedAt = isoNow();
-		await this.options.sessionStore.save(record);
+		} else await this.closeRetainedSessionOwner(record.acpxRecordId);
 	}
 	async closeBackendSession(record) {
-		const pendingClient = await this.readPendingPersistentClient(record, { consume: true });
-		const client = pendingClient ?? this.createClient({
+		const connection = await this.acquireBackendCloseConnection(record);
+		try {
+			await this.requestBackendSessionClose(record, connection);
+		} catch (error) {
+			this.handleBackendSessionCloseError(record, error);
+		} finally {
+			await this.finalizeBackendCloseConnection(connection);
+		}
+	}
+	async finalizeBackendCloseConnection(connection) {
+		const failure = firstFailedAttempt([
+			await settleAttempt(async () => {
+				if (connection.owner) await this.flushSessionOwner(connection.owner);
+			}),
+			await settleAttempt(() => connection.owner?.client.clearEventHandlers()),
+			await settleAttempt(async () => connection.client.close())
+		]);
+		if (failure) throw failure.error;
+	}
+	async acquireBackendCloseConnection(record) {
+		const owner = await this.readRetainedSessionOwner(record, { consume: true });
+		if (owner) return {
+			client: owner.client,
+			owner
+		};
+		return { client: this.createClient({
 			agentCommand: record.agentCommand,
 			agentArgv: record.agentArgv,
 			cwd: record.cwd,
 			mcpServers: [...this.options.mcpServers ?? []],
 			permissionMode: this.options.permissionMode,
 			nonInteractivePermissions: this.options.nonInteractivePermissions,
+			permissionPolicy: this.options.permissionPolicy,
 			onPermissionRequest: this.options.onPermissionRequest,
+			elicitationModes: this.options.elicitationModes,
 			verbose: this.options.verbose
-		});
-		try {
-			if (!pendingClient) await withTimeout(client.start(), this.options.timeoutMs);
-			if (!client.supportsCloseSession()) throw new AcpRuntimeError("ACP_BACKEND_UNSUPPORTED_CONTROL", `Agent does not support session/close for ${record.acpxRecordId}.`);
-			await withTimeout(client.closeSession(record.acpSessionId), this.options.timeoutMs);
-		} catch (error) {
-			if (isUnsupportedSessionCloseError(error)) throw new AcpRuntimeError("ACP_BACKEND_UNSUPPORTED_CONTROL", `Agent does not support session/close for ${record.acpxRecordId}.`, { cause: error });
-			if (isAcpResourceNotFoundError(error)) return;
-			throw error;
-		} finally {
-			await client.close().catch(() => {});
-		}
+		}) };
+	}
+	async requestBackendSessionClose(record, connection) {
+		if (!connection.owner) await withTimeout(connection.client.start(), this.options.timeoutMs);
+		if (!connection.client.supportsCloseSession()) throw new AcpRuntimeError("ACP_BACKEND_UNSUPPORTED_CONTROL", `Agent does not support session/close for ${record.acpxRecordId}.`);
+		await withTimeout(connection.client.closeSession(record.acpSessionId), this.options.timeoutMs);
+	}
+	handleBackendSessionCloseError(record, error) {
+		if (isAcpResourceNotFoundError(error)) return;
+		if (isUnsupportedSessionCloseError(error)) throw new AcpRuntimeError("ACP_BACKEND_UNSUPPORTED_CONTROL", `Agent does not support session/close for ${record.acpxRecordId}.`, { cause: error });
+		throw error;
 	}
 	async requireRecord(sessionId) {
 		const record = await this.options.sessionStore.load(sessionId);
@@ -1506,6 +1951,7 @@ function createProbeClient(options, agentCommand, deps) {
 		mcpServers: [...options.mcpServers ?? []],
 		permissionMode: options.permissionMode,
 		nonInteractivePermissions: options.nonInteractivePermissions,
+		permissionPolicy: options.permissionPolicy,
 		verbose: options.verbose
 	};
 	return deps.clientFactory?.(clientOptions) ?? new AcpClient(clientOptions);
@@ -1614,10 +2060,14 @@ var AcpxRuntime = class {
 			sessionMode: state.mode,
 			requestId: input.requestId,
 			timeoutMs: input.timeoutMs,
-			signal: input.signal
+			signal: input.signal,
+			onElicitation: input.onElicitation
 		}));
 		return {
 			requestId: input.requestId,
+			get promptStarted() {
+				return turnPromise.then((turn) => turn.promptStarted);
+			},
 			events: { async *[Symbol.asyncIterator]() {
 				yield* (await turnPromise).events;
 			} },
@@ -1642,7 +2092,8 @@ var AcpxRuntime = class {
 			sessionMode: state.mode,
 			requestId: input.requestId,
 			timeoutMs: input.timeoutMs,
-			signal: input.signal
+			signal: input.signal,
+			onElicitation: input.onElicitation
 		});
 	}
 	async getCapabilities(input) {