@xopcai/xopc 0.0.222 → 0.0.224

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/run-for-session.js

@@ -8,6 +8,7 @@ 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>;

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

@@ -1,91 +1,70 @@
-import { createLogger } from "../../utils/logger/index.js";
-import { init_logger } from "../../utils/logger.js";
 //#region src/agent/embedded/runs.ts
-init_logger();
-const log = createLogger("EmbeddedRunRegistry");
-/**
-* 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.
-*/
+var EmbeddedRunConflictError = class extends Error {
+	constructor(sessionKey, activeRunId) {
+		super(`Session '${sessionKey}' already has active embedded run '${activeRunId}'`);
+		this.sessionKey = sessionKey;
+		this.activeRunId = activeRunId;
+		this.name = "EmbeddedRunConflictError";
+	}
+};
+/** Owns one process-local execution lease per session while leaving steer/abort on the control plane. */
 var EmbeddedRunRegistry = class {
 	bySessionKey = /* @__PURE__ */ new Map();
-	byRunId = /* @__PURE__ */ new Map();
-	/**
-	* 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) {
-		const previous = this.bySessionKey.get(handle.sessionKey);
-		if (previous && previous !== handle) {
-			log.warn({
-				sessionKey: handle.sessionKey,
-				previousRunId: previous.runId,
-				newRunId: handle.runId
-			}, "Replacing already-registered embedded run for sessionKey (caller did not unregister first)");
-			this.byRunId.delete(previous.runId);
-		}
-		this.bySessionKey.set(handle.sessionKey, handle);
-		this.byRunId.set(handle.runId, handle);
-	}
-	unregister(handle) {
-		if (this.bySessionKey.get(handle.sessionKey) === handle) this.bySessionKey.delete(handle.sessionKey);
-		this.byRunId.delete(handle.runId);
+	acquire(identity) {
+		const active = this.bySessionKey.get(identity.sessionKey);
+		if (active) throw new EmbeddedRunConflictError(identity.sessionKey, active.runId);
+		const entry = {
+			...identity,
+			abortController: new AbortController()
+		};
+		this.bySessionKey.set(identity.sessionKey, entry);
+		return {
+			signal: entry.abortController.signal,
+			attach: async (session, abort) => {
+				entry.handle = {
+					...identity,
+					session,
+					abort
+				};
+				if (entry.abortController.signal.aborted) await abort();
+			},
+			release: () => {
+				if (this.bySessionKey.get(identity.sessionKey) === entry) this.bySessionKey.delete(identity.sessionKey);
+			}
+		};
 	}
 	getBySessionKey(sessionKey) {
-		return this.bySessionKey.get(sessionKey);
-	}
-	getByRunId(runId) {
-		return this.byRunId.get(runId);
+		return this.bySessionKey.get(sessionKey)?.handle;
 	}
 	async abortBySessionKey(sessionKey) {
-		const handle = this.bySessionKey.get(sessionKey);
-		if (!handle) return false;
-		await handle.abort();
+		const entry = this.bySessionKey.get(sessionKey);
+		if (!entry) return false;
+		entry.abortController.abort(/* @__PURE__ */ new Error("Embedded run aborted"));
+		if (entry.handle) await entry.handle.abort();
 		return true;
 	}
 	async steerBySessionKey(sessionKey, text) {
-		const handle = this.bySessionKey.get(sessionKey);
+		const handle = this.getBySessionKey(sessionKey);
 		if (!handle) return false;
 		await handle.session.steer(text);
 		return true;
 	}
-	/** Test-only helper to drop all registrations without touching live sessions. */
-	resetForTest() {
-		this.bySessionKey.clear();
-		this.byRunId.clear();
-	}
 	size() {
 		return this.bySessionKey.size;
 	}
 };
-/**
-* 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.
-*/
-const defaultEmbeddedRunRegistry = new EmbeddedRunRegistry();
-function registerEmbeddedRun(handle) {
-	defaultEmbeddedRunRegistry.register(handle);
-}
-function unregisterEmbeddedRun(handle) {
-	defaultEmbeddedRunRegistry.unregister(handle);
+const embeddedRunRegistry = new EmbeddedRunRegistry();
+function acquireEmbeddedRunLease(identity) {
+	return embeddedRunRegistry.acquire(identity);
 }
 function getEmbeddedRunBySessionKey(sessionKey) {
-	return defaultEmbeddedRunRegistry.getBySessionKey(sessionKey);
-}
-function getEmbeddedRunByRunId(runId) {
-	return defaultEmbeddedRunRegistry.getByRunId(runId);
+	return embeddedRunRegistry.getBySessionKey(sessionKey);
 }
 function abortEmbeddedRun(sessionKey) {
-	return defaultEmbeddedRunRegistry.abortBySessionKey(sessionKey);
+	return embeddedRunRegistry.abortBySessionKey(sessionKey);
 }
 function queueEmbeddedSteer(sessionKey, text) {
-	return defaultEmbeddedRunRegistry.steerBySessionKey(sessionKey, text);
+	return embeddedRunRegistry.steerBySessionKey(sessionKey, text);
 }
 //#endregion
-export { EmbeddedRunRegistry, abortEmbeddedRun, defaultEmbeddedRunRegistry, getEmbeddedRunByRunId, getEmbeddedRunBySessionKey, queueEmbeddedSteer, registerEmbeddedRun, unregisterEmbeddedRun };
+export { EmbeddedRunConflictError, EmbeddedRunRegistry, abortEmbeddedRun, acquireEmbeddedRunLease, getEmbeddedRunBySessionKey, queueEmbeddedSteer };

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

@@ -2,6 +2,7 @@ import type { AgentMessage, AgentToolResult, ThinkingLevel } from '@earendil-wor
 import type { AssistantMessageEvent, Model, Api, ImageContent } from '@earendil-works/pi-ai';
 import type { SessionStore } from '../../session/store.js';
 import type { EmbeddedTranscriptRuntime } from './transcript-runtime.js';
+import type { AgentTurnPolicy } from '../orchestration/agent-turn-policy.js';
 export type EmbeddedStreamEvent = {
     type: 'agent_start';
     runId?: string;
@@ -97,6 +98,7 @@ export type RunXopcEmbeddedTurnParams = {
     sessionStore?: SessionStore;
     transcriptRuntime?: EmbeddedTranscriptRuntime;
     timeoutMs: number;
+    turnPolicy?: AgentTurnPolicy;
     abortSignal?: AbortSignal;
     onEvent?: (event: EmbeddedStreamEvent) => void;
     images?: ImageContent[];
@@ -105,6 +107,8 @@ export type RunXopcEmbeddedTurnParams = {
 };
 export type RunXopcEmbeddedTurnResult = {
     ok: boolean;
+    /** False for harness failures that must not trigger another model attempt. */
+    retryable?: boolean;
     errorMessage?: string;
     lastAssistantText?: string;
 };

package/dist/src/agent/orchestration/agent-run-supervisor.d.ts

@@ -0,0 +1,28 @@
+export type ModelAttemptPlan = {
+    ok: true;
+    timeoutMs: number;
+    remainingMs: number;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface AgentRunSupervisorOptions {
+    timeoutMs: number;
+    deadlineAtMs?: number;
+    parentSignal?: AbortSignal;
+    minimumFallbackMs?: number;
+}
+/** Minimal run-level coordination: root cancellation and per-attempt deadline planning. */
+export declare class AgentRunSupervisor {
+    readonly deadlineAtMs: number;
+    readonly signal: AbortSignal;
+    private readonly controller;
+    private readonly timeout;
+    private readonly forwardParentAbort;
+    private readonly timeoutMs;
+    private readonly minimumFallbackMs;
+    private readonly parentSignal?;
+    constructor(options: AgentRunSupervisorOptions);
+    planModelAttempt(isFallback: boolean): ModelAttemptPlan;
+    dispose(): void;
+}