@xopcai/xopc 0.0.221 → 0.0.223

package/dist/src/agent/agent-manager.js

@@ -4,17 +4,16 @@ import { init_logger } from "../utils/logger.js";
 import { getSessionMetadata } from "../storage/sqlite/session-repository.js";
 import { getSessionConfig } from "../storage/sqlite/config-repository.js";
 import "../storage/sqlite/index.js";
-import { checkBoundary } from "../agent-runtime/boundary-guard.js";
 import { getAgentDefaultModelRef, init_schema } from "../config/schema.js";
+import { applyConfigOverrides } from "../config/runtime-overrides.js";
 import { expandWorkspacePathString, init_workspace_path } from "../config/workspace-path.js";
 import { init_agent_scope, resolveAgentProfileDir } from "./agent-scope.js";
+import { resolveEffectiveAgentProfile, resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { init_paths, resolveBundledSkillsDir } from "../config/paths.js";
-import { CredentialResolver, init_credentials } from "../auth/credentials.js";
 import { init_sync_provider_auth, resolveProviderApiKeySync } from "../auth/sync-provider-auth.js";
+import { CredentialResolver, init_credentials } from "../auth/credentials.js";
 import { getApiKeySync, getDefaultModelSync, init_providers, resolveModel } from "../providers/index.js";
 import { createExtensionAwareStreamFn } from "../providers/extension-stream-bridge.js";
-import { applyConfigOverrides } from "../config/runtime-overrides.js";
-import { resolveEffectiveAgentProfile, resolveEffectiveAgentProfileForSession } from "../config/agent-profile.js";
 import { extractTextContent } from "./context/workspace.js";
 import { buildExecutionScopeContextForPrompt } from "./context/execution-scope.js";
 import { clearBootstrapSnapshot } from "./bootstrap/bootstrap-cache.js";
@@ -39,8 +38,10 @@ import { UserContextCoordinator } from "./memory/user-context-coordinator.js";
 import { WorkspaceRuntimeRegistry } from "./workspace-runtime/registry.js";
 import { BackgroundReviewCoordinator } from "./background-review/coordinator.js";
 import { maybeRequestChannelExecApproval } from "../channels/exec-approval-runtime.js";
+import { checkBoundary } from "../agent-runtime/boundary-guard.js";
 import { SkillFilesystemWatcher } from "./skills/filesystem-watcher.js";
 import { ProjectTrustStore, hasTrustRequiringProjectResources } from "../project-trust/trust-store.js";
+import { createAgentTurnPolicy } from "./orchestration/agent-turn-policy.js";
 import { basename, resolve, sep } from "node:path";
 import { Agent } from "@earendil-works/pi-agent-core";
 //#region src/agent/agent-manager.ts
@@ -728,6 +729,10 @@ var AgentManager = class {
 		}, "Created new agent instance");
 		return agent;
 	}
+	createAgentTurnPolicy(sessionKey) {
+		const profile = this.agents.get(sessionKey)?.effectiveProfile ?? resolveEffectiveAgentProfileForSession(this.config.config, sessionKey);
+		return this.buildAgentTurnPolicy(sessionKey, profile);
+	}
 	/**
 	* Get existing agent for a session (if any)
 	*/
@@ -893,7 +898,7 @@ var AgentManager = class {
 		});
 		const registeredToolNames = tools.map((t) => t.name);
 		const thinkingLevel = profile.thinkingDefault ?? this.config.thinkingLevel ?? "medium";
-		const toolCalls = /* @__PURE__ */ new Map();
+		const turnPolicy = this.buildAgentTurnPolicy(sessionKey, profile);
 		agent = new Agent({
 			initialState: {
 				systemPrompt: rt.systemPromptBuilder.build(contextFiles, {
@@ -917,25 +922,33 @@ var AgentManager = class {
 			toolExecution: "parallel",
 			streamFn: createExtensionAwareStreamFn(),
 			getApiKey: (provider) => this.resolveApiKeyWithCache(provider),
-			shouldStopAfterTurn: ({ newMessages, toolResults }) => {
-				const maxTurns = profile.manifest.runtime?.maxTurns;
-				const maxFailures = profile.manifest.runtime?.maxToolFailuresPerTurn;
-				const shouldStop = Boolean(maxTurns && newMessages.filter((message) => message.role === "assistant").length >= maxTurns || maxFailures && toolResults.filter((result) => result.isError).length >= maxFailures);
-				toolCalls.clear();
-				return shouldStop;
+			shouldStopAfterTurn: turnPolicy.shouldStopAfterTurn,
+			beforeToolCall: turnPolicy.beforeToolCall,
+			afterToolCall: turnPolicy.afterToolCall
+		});
+		agent.subscribe((event) => {
+			if (event.type === "agent_start") turnPolicy.reset();
+		});
+		return {
+			agent,
+			registeredToolNames
+		};
+	}
+	buildAgentTurnPolicy(sessionKey, profile) {
+		return createAgentTurnPolicy({
+			maxTurns: profile.manifest.runtime?.maxTurns,
+			maxToolFailures: profile.manifest.runtime?.maxToolFailuresPerTurn,
+			resolveToolLimit: (toolName, args) => {
+				const policy = this.resolveToolPolicy(profile, toolName, args);
+				const maxCalls = policy?.limits?.maxCallsPerTurn;
+				return policy && maxCalls ? {
+					id: policy.id,
+					maxCalls
+				} : void 0;
 			},
-			beforeToolCall: async ({ toolCall, args }) => {
+			authorizeToolCall: async ({ toolCall, args }) => {
 				const toolName = toolCall.name;
 				const policy = this.resolveToolPolicy(profile, toolName, args);
-				if (policy?.limits?.maxCallsPerTurn) {
-					const count = (toolCalls.get(policy.id) ?? 0) + 1;
-					toolCalls.set(policy.id, count);
-					if (count > policy.limits.maxCallsPerTurn) return {
-						block: true,
-						terminate: true,
-						reason: `${policy.id} exceeded its per-turn call limit.`
-					};
-				}
 				const detail = JSON.stringify(args ?? {});
 				const boundary = checkBoundary({
 					manifest: profile.manifest,
@@ -991,13 +1004,6 @@ var AgentManager = class {
 				};
 			}
 		});
-		agent.subscribe((event) => {
-			if (event.type === "agent_start") toolCalls.clear();
-		});
-		return {
-			agent,
-			registeredToolNames
-		};
 	}
 	resolveToolPolicy(profile, toolName, args) {
 		if (toolName !== "xopc_tool_execute") {

package/dist/src/agent/embedded/index.d.ts

@@ -9,5 +9,5 @@ export { acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, evictAllE
 export { DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS, resolveLiveToolResultMaxChars, truncateToolResultMessage, } from './tool-result-truncation.js';
 export { runXopcEmbeddedTurn, abortEmbeddedRun, queueEmbeddedSteer } from './run-turn.js';
 export { runEmbeddedTurnForSession } from './run-for-session.js';
-export { registerEmbeddedRun, getEmbeddedRunBySessionKey } from './runs.js';
+export { getEmbeddedRunBySessionKey } from './runs.js';
 export type { RunXopcEmbeddedTurnParams, RunXopcEmbeddedTurnResult, EmbeddedStreamEvent } from './types.js';

package/dist/src/agent/embedded/index.js

@@ -1,7 +1,7 @@
 import { DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS, resolveLiveToolResultMaxChars, truncateToolResultMessage } from "./tool-result-truncation.js";
 import { getRawSessionAppendMessage, guardSessionManager, installSessionToolResultGuard } from "./session-tool-result-guard.js";
 import { acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, isEmbeddedSessionRunnerEnabled, resetEmbeddedSessionRunnerForTest } from "./session-runner.js";
-import { abortEmbeddedRun, getEmbeddedRunBySessionKey, queueEmbeddedSteer, registerEmbeddedRun } from "./runs.js";
+import { abortEmbeddedRun, getEmbeddedRunBySessionKey, queueEmbeddedSteer } from "./runs.js";
 import { repairAssistantUsageInSessionManager } from "./session-manager-init.js";
 import { openSqliteHydratingSessionManager } from "./sqlite-hydrating-session-manager.js";
 import { InMemoryTranscriptRuntime, createSqliteTranscriptRuntime } from "./transcript-runtime.js";
@@ -9,4 +9,4 @@ import { runXopcEmbeddedTurn } from "./run-turn.js";
 import { getEmbeddedExecutionSession, runWithEmbeddedExecutionSession } from "./execution-context.js";
 import { runEmbeddedTurnForSession } from "./run-for-session.js";
 import { CURRENT_SESSION_VERSION, PiTranscriptManager } from "./pi-transcript.js";
-export { CURRENT_SESSION_VERSION, DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS, InMemoryTranscriptRuntime, PiTranscriptManager, abortEmbeddedRun, acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, createSqliteTranscriptRuntime, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedExecutionSession, getEmbeddedRunBySessionKey, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, getRawSessionAppendMessage, guardSessionManager, installSessionToolResultGuard, isEmbeddedSessionRunnerEnabled, openSqliteHydratingSessionManager, queueEmbeddedSteer, registerEmbeddedRun, repairAssistantUsageInSessionManager, resetEmbeddedSessionRunnerForTest, resolveLiveToolResultMaxChars, runEmbeddedTurnForSession, runWithEmbeddedExecutionSession, runXopcEmbeddedTurn, truncateToolResultMessage };
+export { CURRENT_SESSION_VERSION, DEFAULT_MAX_LIVE_TOOL_RESULT_CHARS, InMemoryTranscriptRuntime, PiTranscriptManager, abortEmbeddedRun, acquireEmbeddedSessionRunner, buildEmbeddedRunnerFingerprint, createSqliteTranscriptRuntime, evictAllEmbeddedSessionRunners, evictEmbeddedSessionRunner, getEmbeddedExecutionSession, getEmbeddedRunBySessionKey, getEmbeddedSessionRunnerIdleTtlMs, getEmbeddedSessionRunnerStats, getRawSessionAppendMessage, guardSessionManager, installSessionToolResultGuard, isEmbeddedSessionRunnerEnabled, openSqliteHydratingSessionManager, queueEmbeddedSteer, repairAssistantUsageInSessionManager, resetEmbeddedSessionRunnerForTest, resolveLiveToolResultMaxChars, runEmbeddedTurnForSession, runWithEmbeddedExecutionSession, runXopcEmbeddedTurn, truncateToolResultMessage };

package/dist/src/agent/embedded/model-runtime.js

@@ -1,6 +1,6 @@
 import { init_paths, resolveModelsJsonPath } from "../../config/paths.js";
-import { CredentialResolver, init_credentials } from "../../auth/credentials.js";
 import { init_sync_provider_auth, resolveProviderApiKeySync } from "../../auth/sync-provider-auth.js";
+import { CredentialResolver, init_credentials } from "../../auth/credentials.js";
 import { XopcModelCredentialStore, init_model_credential_store } from "../../auth/model-credential-store.js";
 import { init_register_bundled_oauth_flows, registerBundledOAuthFlows } from "../../providers/register-bundled-oauth-flows.js";
 import { init_register_runtime_providers, registerRuntimeProviders } from "../../providers/register-runtime-providers.js";

package/dist/src/agent/embedded/run-for-session.js

@@ -1,13 +1,14 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { init_providers, resolveModel } from "../../providers/index.js";
 import { resolveEffectiveAgentProfileForSession } from "../../config/agent-profile.js";
+import { init_providers, resolveModel } from "../../providers/index.js";
 import { resolveAgentTurnTimeoutMs } from "../orchestration/run-agent-turn-with-timeout.js";
 import { resolvePromptCachePolicy } from "../../providers/prompt-cache-plan.js";
 import { evaluateContextBudget } from "../memory/context-budget.js";
 import { resolveCompactionPolicy } from "../memory/compaction-policy.js";
 import { runXopcEmbeddedTurn } from "./run-turn.js";
 import { applyStartupContextToUserMessage } from "../reply/apply-turn-user-enrichment.js";
+import { AgentRunSupervisor } from "../orchestration/agent-run-supervisor.js";
 import crypto from "node:crypto";
 //#region src/agent/embedded/run-for-session.ts
 init_logger();
@@ -16,67 +17,93 @@ const log = createLogger("EmbeddedTurnForSession");
 async function runEmbeddedTurnForSession(params) {
 	const { sessionKey, agentManager, modelManager, sessionStore, userMessage } = params;
 	const runId = params.runId ?? crypto.randomUUID();
-	await params.beforeTurn?.();
-	const agent = agentManager.getOrCreateAgent(sessionKey);
-	const mm = modelManager;
-	const configuredModelRef = String(mm.getModelForSession(sessionKey));
-	const candidates = typeof mm.getFallbackCandidatesForSession === "function" ? mm.getFallbackCandidatesForSession(sessionKey) : [];
-	const candidateModelRefs = candidates.length > 0 ? candidates.map((candidate) => `${candidate.provider}/${candidate.model}`) : [configuredModelRef];
-	const resolvedCandidates = [];
-	for (const [index, ref] of candidateModelRefs.entries()) try {
-		const resolved = index === 0 && typeof mm.getResolvedModelForSession === "function" ? mm.getResolvedModelForSession(sessionKey) : resolveModel(ref);
-		resolvedCandidates.push({
-			ref,
-			model: resolved
-		});
-	} catch (err) {
-		log.warn({
-			err,
-			sessionKey,
-			runId,
-			modelRef: ref
-		}, "Skipping unavailable model candidate");
-	}
-	const primary = resolvedCandidates[0];
-	if (!primary) throw new Error(`No available model candidates for '${configuredModelRef}'`);
-	const modelRef = primary.ref;
-	const model = primary.model;
-	if (typeof mm.applyResolvedModel === "function") mm.applyResolvedModel(agent, model, modelRef);
-	else await mm.applyModelForSession(agent, sessionKey);
-	agentManager.setModelForSession(sessionKey, modelRef);
-	const tools = agent.state.tools;
-	const systemPrompt = agent.state.systemPrompt ?? "";
-	const thinkingLevel = params.thinkingOverride ?? agent.state.thinkingLevel;
-	const workspaceDir = agentManager.getResolvedWorkspaceForSession(sessionKey);
 	const config = params.getConfig?.();
-	const promptCachePolicy = resolvePromptCachePolicy(config ? resolveEffectiveAgentProfileForSession(config, sessionKey).manifest.runtime?.promptCache : void 0);
-	const configuredTurnTimeoutMs = resolveAgentTurnTimeoutMs(config, sessionKey);
-	const turnTimeoutMs = params.deadlineAtMs === void 0 ? configuredTurnTimeoutMs : Math.max(1, Math.min(configuredTurnTimeoutMs, params.deadlineAtMs - Date.now()));
-	let userMessageForTurn = userMessage;
-	if (params.applyStartupContext !== false) userMessageForTurn = await applyStartupContextToUserMessage({
-		userMessage,
-		sessionKey,
-		workspaceDir,
-		cfg: config,
-		sessionStore,
-		startupAction: params.startupAction,
-		force: params.forceStartupContext
+	const supervisor = new AgentRunSupervisor({
+		timeoutMs: resolveAgentTurnTimeoutMs(config, sessionKey),
+		deadlineAtMs: params.deadlineAtMs,
+		parentSignal: params.abortSignal
 	});
-	return await (async () => {
-		await maybeAutoCompactBeforeTurn({
-			sessionKey,
-			sessionStore,
-			agentManager,
-			model,
-			config,
-			systemPrompt,
-			userMessage: userMessageForTurn,
-			tools,
-			imageCount: params.llmImages?.length ?? 0,
-			fallbackModels: resolvedCandidates.slice(1).map((candidate) => candidate.model),
-			abortSignal: params.abortSignal,
-			onEvent: params.onEvent
-		});
+	try {
+		await params.beforeTurn?.();
+		if (supervisor.signal.aborted) return {
+			ok: false,
+			errorMessage: "aborted"
+		};
+		const agent = agentManager.getOrCreateAgent(sessionKey);
+		const mm = modelManager;
+		const configuredModelRef = String(mm.getModelForSession(sessionKey));
+		const candidates = typeof mm.getFallbackCandidatesForSession === "function" ? mm.getFallbackCandidatesForSession(sessionKey) : [];
+		const candidateModelRefs = candidates.length > 0 ? candidates.map((candidate) => `${candidate.provider}/${candidate.model}`) : [configuredModelRef];
+		const resolvedCandidates = [];
+		for (const [index, ref] of candidateModelRefs.entries()) try {
+			const resolved = index === 0 && typeof mm.getResolvedModelForSession === "function" ? mm.getResolvedModelForSession(sessionKey) : resolveModel(ref);
+			resolvedCandidates.push({
+				ref,
+				model: resolved
+			});
+		} catch (err) {
+			log.warn({
+				err,
+				sessionKey,
+				runId,
+				modelRef: ref
+			}, "Skipping unavailable model candidate");
+		}
+		const primary = resolvedCandidates[0];
+		if (!primary) throw new Error(`No available model candidates for '${configuredModelRef}'`);
+		const modelRef = primary.ref;
+		const model = primary.model;
+		if (typeof mm.applyResolvedModel === "function") mm.applyResolvedModel(agent, model, modelRef);
+		else await mm.applyModelForSession(agent, sessionKey);
+		agentManager.setModelForSession(sessionKey, modelRef);
+		const tools = agent.state.tools;
+		const turnPolicy = agentManager.createAgentTurnPolicy(sessionKey);
+		const systemPrompt = agent.state.systemPrompt ?? "";
+		const thinkingLevel = params.thinkingOverride ?? agent.state.thinkingLevel;
+		const workspaceDir = agentManager.getResolvedWorkspaceForSession(sessionKey);
+		const promptCachePolicy = resolvePromptCachePolicy(config ? resolveEffectiveAgentProfileForSession(config, sessionKey).manifest.runtime?.promptCache : void 0);
+		let userMessageForTurn = userMessage;
+		if (params.applyStartupContext !== false) {
+			userMessageForTurn = await applyStartupContextToUserMessage({
+				userMessage,
+				sessionKey,
+				workspaceDir,
+				cfg: config,
+				sessionStore,
+				startupAction: params.startupAction,
+				force: params.forceStartupContext
+			});
+			if (supervisor.signal.aborted) return {
+				ok: false,
+				errorMessage: "aborted"
+			};
+		}
+		try {
+			await maybeAutoCompactBeforeTurn({
+				sessionKey,
+				sessionStore,
+				agentManager,
+				model,
+				config,
+				systemPrompt,
+				userMessage: userMessageForTurn,
+				tools,
+				imageCount: params.llmImages?.length ?? 0,
+				fallbackModels: resolvedCandidates.slice(1).map((candidate) => candidate.model),
+				abortSignal: supervisor.signal,
+				onEvent: params.onEvent
+			});
+		} catch (err) {
+			if (supervisor.signal.aborted) return {
+				ok: false,
+				errorMessage: "aborted"
+			};
+			throw err;
+		}
+		if (supervisor.signal.aborted) return {
+			ok: false,
+			errorMessage: "aborted"
+		};
 		log.info({
 			sessionKey,
 			runId,
@@ -94,6 +121,14 @@ async function runEmbeddedTurnForSession(params) {
 			const isFallbackAttempt = i > 0;
 			const candidateModel = candidate.model;
 			const hasNextCandidate = i + 1 < resolvedCandidates.length;
+			const attemptPlan = supervisor.planModelAttempt(isFallbackAttempt);
+			if (attemptPlan.ok === false) {
+				lastResult = {
+					ok: false,
+					errorMessage: attemptPlan.reason
+				};
+				break;
+			}
 			const rowsBeforeAttempt = hasNextCandidate ? await sessionStore.loadTranscriptRows(sessionKey) : void 0;
 			if (typeof mm.applyResolvedModel === "function") mm.applyResolvedModel(agent, candidateModel, candidateModelRef);
 			agentManager.setModelForSession(sessionKey, candidateModelRef);
@@ -119,8 +154,9 @@ async function runEmbeddedTurnForSession(params) {
 					promptCachePolicy,
 					workspaceDir,
 					sessionStore,
-					timeoutMs: turnTimeoutMs,
-					abortSignal: params.abortSignal,
+					timeoutMs: attemptPlan.timeoutMs,
+					turnPolicy,
+					abortSignal: supervisor.signal,
 					onEvent: params.onEvent,
 					resumeLastUserMessage
 				});
@@ -136,6 +172,7 @@ async function runEmbeddedTurnForSession(params) {
 					return turnResult;
 				}
 				lastResult = turnResult;
+				if (supervisor.signal.aborted || turnResult.retryable === false) break;
 				log.warn({
 					sessionKey,
 					runId,
@@ -179,7 +216,9 @@ async function runEmbeddedTurnForSession(params) {
 			ok: false,
 			errorMessage: "No model candidates available"
 		};
-	})();
+	} finally {
+		supervisor.dispose();
+	}
 }
 function serializedTranscriptBytes(messages) {
 	return Buffer.byteLength(JSON.stringify(messages), "utf8");

package/dist/src/agent/embedded/run-turn.js

@@ -1,17 +1,17 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
-import { resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
+import { isAgentTurnUnsettledError, resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
 import { resolvePromptCachePolicy } from "../../providers/prompt-cache-plan.js";
 import { wrapStreamFnForXopcExtensions } from "./xopc-stream-bridge.js";
-import { acquireEmbeddedSessionRunner } from "./session-runner.js";
+import { acquireEmbeddedSessionRunner, evictEmbeddedSessionRunner } from "./session-runner.js";
+import { isContextOverflowError } from "../orchestration/context-overflow.js";
 import { getAssistantTurnErrorMessage, isAssistantTurnAborted, isAssistantTurnFailed, maybeRetryTurnAfterTransientLlmFailure, stripTrailingErrorAssistantMessages } from "../orchestration/llm-turn-retry.js";
 import { projectContextForModel } from "../memory/context-budget.js";
-import { abortEmbeddedRun, queueEmbeddedSteer, registerEmbeddedRun, unregisterEmbeddedRun } from "./runs.js";
+import { EmbeddedRunConflictError, abortEmbeddedRun, acquireEmbeddedRunLease, queueEmbeddedSteer } from "./runs.js";
 import { lastAssistantPlainText, subscribeEmbeddedSessionEvents } from "./subscribe-session.js";
 import { detectToolLoops } from "../orchestration/loop-guard.js";
 import { tryApplySessionTranscriptHygiene } from "../transcript/transcript-hygiene.js";
 import { createSqliteTranscriptRuntime } from "./transcript-runtime.js";
-import { isContextOverflowError } from "../orchestration/context-overflow.js";
 import { buildPromptCacheSnapshot, observePromptCacheSnapshot } from "../../providers/prompt-cache-observability.js";
 import { isPromptCacheExpired, recordPromptCacheTouch } from "../../providers/prompt-cache-lifecycle.js";
 //#region src/agent/embedded/run-turn.ts
@@ -83,9 +83,10 @@ async function maybeRecoverContextOverflow(params) {
 		type: "compaction",
 		status: "started"
 	});
-	const result = await params.transcriptRuntime.compact(messages, params.model, "Preserve the current pending user request verbatim and retain every fact needed to answer it.", true);
+	const result = await params.transcriptRuntime.compact(messages, params.model, "Preserve the current pending user request verbatim and retain every fact needed to answer it.", true, { signal: params.abortSignal });
 	if (!result.compacted) throw new Error(`Context overflow recovery could not find a safe compaction range: ${errorMessage}`);
 	params.agent.state.messages = await params.transcriptRuntime.loadMessages();
+	params.abortSignal?.throwIfAborted();
 	params.onEvent?.({
 		type: "compaction",
 		status: "completed",
@@ -109,7 +110,14 @@ async function runXopcEmbeddedTurn(params) {
 	if (!transcriptRuntime) throw new Error("Embedded run requires a transcript runtime");
 	let runner;
 	let unsubscribe;
+	let quarantineRunner = false;
+	let runLease;
 	try {
+		runLease = acquireEmbeddedRunLease({
+			sessionKey,
+			sessionId: transcriptRuntime.sessionId,
+			runId
+		});
 		runner = await acquireEmbeddedSessionRunner({
 			runtimeId: transcriptRuntime.runtimeId,
 			sessionId: transcriptRuntime.sessionId,
@@ -122,6 +130,15 @@ async function runXopcEmbeddedTurn(params) {
 			transcriptRuntime
 		});
 		const { session, reused } = runner;
+		await runLease.attach(session, async () => session.abort());
+		const runAbortSignal = params.abortSignal ? AbortSignal.any([runLease.signal, params.abortSignal]) : runLease.signal;
+		if (runAbortSignal.aborted) {
+			await session.abort();
+			return {
+				ok: false,
+				errorMessage: "aborted"
+			};
+		}
 		runner.piSm.setActiveTurnId?.(runId);
 		const streamFnWithXopcExtensions = wrapStreamFnForXopcExtensions(session.agent.streamFunction, params.promptCachePolicy);
 		const loggingStreamFn = (streamModel, context, options) => {
@@ -197,6 +214,10 @@ async function runXopcEmbeddedTurn(params) {
 			return streamFnWithXopcExtensions(streamModel, effectiveContext, { ...options });
 		};
 		session.agent.streamFunction = loggingStreamFn;
+		params.turnPolicy?.reset();
+		session.agent.beforeToolCall = params.turnPolicy?.beforeToolCall;
+		session.agent.afterToolCall = params.turnPolicy?.afterToolCall;
+		session.agent.shouldStopAfterTurn = params.turnPolicy?.shouldStopAfterTurn;
 		unsubscribe = subscribeEmbeddedSessionEvents(session, (event) => {
 			if (event.type === "message_end" && event.message.role === "assistant") recordPromptCacheTouch(sessionKey, resolvedModel, event.message.usage);
 			onEvent?.({
@@ -204,29 +225,10 @@ async function runXopcEmbeddedTurn(params) {
 				runId
 			});
 		});
-		const handle = {
-			sessionKey,
-			sessionId: transcriptRuntime.sessionId,
-			runId,
-			session,
-			abort: async () => {
-				await session.abort();
-			}
-		};
-		registerEmbeddedRun(handle);
 		const abortListener = () => {
 			session.abort();
 		};
-		if (params.abortSignal) {
-			if (params.abortSignal.aborted) {
-				await session.abort();
-				return {
-					ok: false,
-					errorMessage: "aborted"
-				};
-			}
-			params.abortSignal.addEventListener("abort", abortListener, { once: true });
-		}
+		runAbortSignal.addEventListener("abort", abortListener, { once: true });
 		try {
 			await runAgentTurnWithTimeout(session.agent, async () => {
 				if (params.resumeLastUserMessage) await session.agent.continue();
@@ -238,16 +240,22 @@ async function runXopcEmbeddedTurn(params) {
 				await session.agent.waitForIdle();
 				await maybeRetryTurnAfterTransientLlmFailure(session.agent, {
 					sessionKey,
-					log
+					log,
+					signal: runAbortSignal
 				});
 				await maybeRecoverContextOverflow({
 					agent: session.agent,
 					model: resolvedModel,
 					sessionKey,
 					transcriptRuntime,
+					abortSignal: runAbortSignal,
 					onEvent
 				});
 			}, timeoutMs);
+			if (runAbortSignal.aborted) return {
+				ok: false,
+				errorMessage: "aborted"
+			};
 			if (isAssistantTurnAborted(session.agent)) return {
 				ok: true,
 				lastAssistantText: lastAssistantPlainText(session)
@@ -262,10 +270,28 @@ async function runXopcEmbeddedTurn(params) {
 				lastAssistantText: lastAssistantPlainText(session)
 			};
 		} finally {
-			params.abortSignal?.removeEventListener("abort", abortListener);
-			unregisterEmbeddedRun(handle);
+			runAbortSignal.removeEventListener("abort", abortListener);
 		}
 	} catch (err) {
+		if (err instanceof EmbeddedRunConflictError) {
+			const em = err.message;
+			log.warn({
+				sessionKey,
+				runId,
+				activeRunId: err.activeRunId
+			}, `Embedded run rejected: ${em}`);
+			onEvent?.({
+				type: "error",
+				content: em,
+				runId
+			});
+			return {
+				ok: false,
+				retryable: false,
+				errorMessage: em
+			};
+		}
+		quarantineRunner = isAgentTurnUnsettledError(err);
 		const em = err instanceof Error ? err.message : String(err);
 		log.error({
 			err,
@@ -282,11 +308,13 @@ async function runXopcEmbeddedTurn(params) {
 			errorMessage: em
 		};
 	} finally {
+		runLease?.release();
 		unsubscribe?.();
 		try {
 			runner?.piSm.flushPendingToolResults?.();
 		} catch {}
 		runner?.piSm.setActiveTurnId?.(null);
+		if (quarantineRunner) evictEmbeddedSessionRunner(transcriptRuntime.runtimeId, "unsettled_after_timeout");
 		runner?.release();
 	}
 }

package/dist/src/agent/embedded/runs.d.ts

@@ -1,46 +1,33 @@
 import type { AgentSession } from '@earendil-works/pi-coding-agent';
-export type EmbeddedRunHandle = {
+export type EmbeddedRunIdentity = {
     sessionKey: string;
     sessionId: string;
     runId: string;
+};
+export type EmbeddedRunHandle = EmbeddedRunIdentity & {
     session: AgentSession;
     abort: () => Promise<void>;
 };
-/**
- * Tracks in-flight embedded agent turns so we can abort/steer them by sessionKey or runId.
- *
- * The previous implementation used two module-level Maps; this class is the supported
- * single-instance state, while {@link defaultEmbeddedRunRegistry} preserves the previous
- * free-function API for callers that have not yet been moved to dependency injection.
- */
+export declare class EmbeddedRunConflictError extends Error {
+    readonly sessionKey: string;
+    readonly activeRunId: string;
+    constructor(sessionKey: string, activeRunId: string);
+}
+export type EmbeddedRunLease = {
+    signal: AbortSignal;
+    attach(session: AgentSession, abort: () => Promise<void>): Promise<void>;
+    release(): void;
+};
+/** Owns one process-local execution lease per session while leaving steer/abort on the control plane. */
 export declare class EmbeddedRunRegistry {
     private readonly bySessionKey;
-    private readonly byRunId;
-    /**
-     * Register a new in-flight run. If a run is already registered for the same
-     * sessionKey we drop the stale handle (the new run takes ownership). The caller
-     * is responsible for aborting the previous run before re-registering if needed —
-     * we warn loudly so this does not happen silently.
-     */
-    register(handle: EmbeddedRunHandle): void;
-    unregister(handle: EmbeddedRunHandle): void;
+    acquire(identity: EmbeddedRunIdentity): EmbeddedRunLease;
     getBySessionKey(sessionKey: string): EmbeddedRunHandle | undefined;
-    getByRunId(runId: string): EmbeddedRunHandle | undefined;
     abortBySessionKey(sessionKey: string): Promise<boolean>;
     steerBySessionKey(sessionKey: string, text: string): Promise<boolean>;
-    /** Test-only helper to drop all registrations without touching live sessions. */
-    resetForTest(): void;
     size(): number;
 }
-/**
- * Process-wide default registry. Prefer constructing a dedicated `EmbeddedRunRegistry`
- * and injecting it; the module-level singleton stays so the existing free functions
- * keep working until every caller has been migrated.
- */
-export declare const defaultEmbeddedRunRegistry: EmbeddedRunRegistry;
-export declare function registerEmbeddedRun(handle: EmbeddedRunHandle): void;
-export declare function unregisterEmbeddedRun(handle: EmbeddedRunHandle): void;
+export declare function acquireEmbeddedRunLease(identity: EmbeddedRunIdentity): EmbeddedRunLease;
 export declare function getEmbeddedRunBySessionKey(sessionKey: string): EmbeddedRunHandle | undefined;
-export declare function getEmbeddedRunByRunId(runId: string): EmbeddedRunHandle | undefined;
 export declare function abortEmbeddedRun(sessionKey: string): Promise<boolean>;
 export declare function queueEmbeddedSteer(sessionKey: string, text: string): Promise<boolean>;