@xopcai/xopc 0.0.384 → 0.0.386

package/dist/src/agent/embedded/agent-profile-context.js

@@ -0,0 +1,92 @@
+import { isXopcDatabaseOpen } from "../../storage/sqlite/connection.js";
+import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
+import { getSessionConfig } from "../../storage/sqlite/config-repository.js";
+import { init_sqlite } from "../../storage/sqlite/index.js";
+import { AgentCatalogRepository, init_repository } from "../../agent-catalog/repository.js";
+import { createHash } from "node:crypto";
+import { getCurrentTools } from "@earendil-works/pi-ai";
+//#region src/agent/embedded/agent-profile-context.ts
+init_repository();
+init_sqlite();
+const AGENT_PROFILE_CONTEXT_STATE = "xopc.agent-profile-context";
+const AGENT_PROFILE_UPDATE_EVENT = "xopc.agent-profile-update";
+function agentProfileContextFingerprint(agentId, profile, responseLanguage) {
+	return createHash("sha256").update(JSON.stringify({
+		agentId,
+		responseLanguage: responseLanguage ?? "auto",
+		name: profile?.name,
+		description: profile?.description,
+		creature: profile?.creature,
+		style: profile?.style,
+		language: profile?.language,
+		instructions: profile?.instructions
+	})).digest("hex");
+}
+/** Keep profile transitions separate from user messages and model-authored conversation. */
+function createAgentProfileContextExtension(conversationId) {
+	return (pi) => {
+		const snapshotForTurn = (context) => {
+			if (!isXopcDatabaseOpen()) return;
+			const agentId = getSessionMetadata(conversationId)?.agentId;
+			if (!agentId) return;
+			const profile = new AgentCatalogRepository().get(agentId)?.profile;
+			const responseLanguage = getSessionConfig(conversationId)?.responseLanguage ?? "auto";
+			const fingerprint = agentProfileContextFingerprint(agentId, profile, responseLanguage);
+			const configuration = {
+				agentId,
+				name: profile?.name ?? agentId,
+				role: profile?.description || null,
+				type: profile?.creature || null,
+				style: profile?.style || null,
+				primaryLanguage: profile?.language || null,
+				responseLanguageOverride: responseLanguage
+			};
+			const previous = context.sessionManager.getBranch().findLast((entry) => entry.type === "custom" && entry.customType === "xopc.agent-profile-context");
+			const data = previous?.type === "custom" ? previous.data : void 0;
+			const changed = data?.fingerprint !== fingerprint || JSON.stringify(data?.configuration) !== JSON.stringify(configuration);
+			if (changed) pi.appendEntry(AGENT_PROFILE_CONTEXT_STATE, {
+				fingerprint,
+				configuration
+			});
+			const changedFields = Object.keys(configuration).filter((key) => configuration[key] !== data?.configuration?.[key]);
+			const updates = Object.fromEntries(changedFields.map((key) => [key, {
+				previous: data?.configuration?.[key] ?? null,
+				current: configuration[key] ?? null
+			}]));
+			return {
+				role: "custom",
+				timestamp: Date.now(),
+				customType: AGENT_PROFILE_UPDATE_EVENT,
+				content: JSON.stringify({
+					event: changed ? "agent_configuration_updated" : "agent_configuration_current",
+					source: "xopc-runtime",
+					...changed ? {
+						changedFields: changedFields.length ? changedFields : ["instructions"],
+						updates
+					} : {},
+					current: configuration
+				}),
+				display: false
+			};
+		};
+		let snapshot;
+		pi.on("before_agent_start", (_event, context) => {
+			snapshot = snapshotForTurn(context);
+		});
+		pi.on("context_with_system", (event, context) => {
+			snapshot ??= snapshotForTurn(context);
+			if (!snapshot) return;
+			const messages = event.messages.filter((message) => message.role !== "system" && !(message.role === "custom" && message.customType === "xopc.agent-profile-update"));
+			const inputIndex = messages.findLastIndex((message) => message.role === "user" || message.role === "custom");
+			messages.splice(inputIndex < 0 ? messages.length : inputIndex, 0, snapshot);
+			return { messages: [{
+				role: "system",
+				content: context.getSystemPrompt(),
+				toolsAdded: getCurrentTools(event.messages),
+				timestamp: Date.now()
+			}, ...messages] };
+		});
+	};
+}
+//#endregion
+export { AGENT_PROFILE_CONTEXT_STATE, AGENT_PROFILE_UPDATE_EVENT, agentProfileContextFingerprint, createAgentProfileContextExtension };

package/dist/src/agent/embedded/execution-tool-policy.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool } from '@earendil-works/pi-agent-core';
-export declare const PERSONAL_REQUEST_TOOL_IDS: readonly ["xopc_tool_search", "xopc_tool_describe", "xopc_tool_execute", "personal_request_result", "personal_request_connection"];
+export declare const PERSONAL_REQUEST_TOOL_IDS: readonly ["xopc_tool_search", "xopc_tool_describe", "xopc_tool_execute", "personal_request_result", "personal_request_connection", "task_collaboration"];
 export type ExecutionToolPolicy = Readonly<{
     surface: 'agent' | 'personal_main' | 'personal_request_worker';
     nativeMcp: boolean;

package/dist/src/agent/embedded/execution-tool-policy.js

@@ -13,7 +13,8 @@ const PERSONAL_REQUEST_TOOL_IDS = [
 	"xopc_tool_describe",
 	"xopc_tool_execute",
 	"personal_request_result",
-	"personal_request_connection"
+	"personal_request_connection",
+	"task_collaboration"
 ];
 /** Resolve from persisted execution identity, never from tool names or model input. */
 function resolveExecutionToolPolicy(conversationId) {
@@ -27,7 +28,7 @@ function resolveExecutionToolPolicy(conversationId) {
 		externalMaterialization: configured,
 		discovery: configured,
 		codemode: configured,
-		revision: "personal-tool-boundaries-v1"
+		revision: "personal-tool-boundaries-v2"
 	};
 }
 function allowsExecutionTool(policy, name) {

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

@@ -17,10 +17,12 @@ import { assessContext, recoverContext as recoverContext$1 } from "../memory/con
 import { resolveCompactionPolicy } from "../memory/compaction-policy.js";
 import { runXopcEmbeddedTurn } from "./run-turn.js";
 import { projectTurnOutcome } from "../../session/turn-outcome-projector.js";
+import { connectionObjectiveContext } from "../context/connection-objective-context.js";
 import { voicePresentationPrompt } from "../prompt/voice-presentation.js";
 import { applyStartupContextToUserMessage } from "../reply/apply-turn-user-enrichment.js";
 import { AgentRunSupervisor } from "../orchestration/agent-run-supervisor.js";
 import { materializeNativeExternalTools } from "./external-tool-discovery.js";
+import { getTaskContinuation, getTaskExecutionDeadline } from "../../tasks/task-continuation.js";
 import crypto from "node:crypto";
 //#region src/agent/embedded/run-for-session.ts
 init_src();
@@ -45,14 +47,22 @@ async function runEmbeddedTurnForSessionInner(params) {
 	let idleJob;
 	let turnCompleted = false;
 	const runId = params.runId ?? crypto.randomUUID();
+	const taskContinuation = getTaskContinuation(conversationId, runId);
 	const config = params.getConfig?.();
 	if (config) setTraceIdentity({ agentId: resolveEffectiveAgentProfileForSession(conversationId).agentId });
 	const supervisor = new AgentRunSupervisor({
 		timeoutMs: resolveAgentTurnTimeoutMs(config, conversationId),
-		deadlineAtMs: params.deadlineAtMs,
+		deadlineAtMs: params.deadlineAtMs ?? getTaskExecutionDeadline(conversationId, runId),
 		parentSignal: params.abortSignal
 	});
 	const finish = async (result) => {
+		if (supervisor.signal.aborted && supervisor.signal.reason instanceof Error && supervisor.signal.reason.message === "Agent run deadline expired") result = {
+			...result,
+			ok: false,
+			retryable: false,
+			terminationReason: "deadline_exceeded",
+			errorMessage: supervisor.signal.reason.message
+		};
 		turnCompleted = result.ok && result.stopReason !== "connection_required" && result.stopReason !== "clarification_required";
 		if (result.stopReason === "connection_required" || result.stopReason === "clarification_required") return result;
 		try {
@@ -91,15 +101,15 @@ async function runEmbeddedTurnForSessionInner(params) {
 	};
 	try {
 		await params.beforeTurn?.();
-		if (supervisor.signal.aborted) return {
+		if (supervisor.signal.aborted) return await finish({
 			ok: false,
 			errorMessage: "aborted"
-		};
+		});
 		await agentManager.ensureMemoryReadyForSession?.(conversationId);
-		if (supervisor.signal.aborted) return {
+		if (supervisor.signal.aborted) return await finish({
 			ok: false,
 			errorMessage: "aborted"
-		};
+		});
 		const agent = agentManager.getOrCreateAgent(conversationId);
 		const mm = modelManager;
 		const configuredModelRef = String(mm.getModelForSession(conversationId));
@@ -130,7 +140,7 @@ async function runEmbeddedTurnForSessionInner(params) {
 		const executionToolPolicy = resolveExecutionToolPolicy(conversationId);
 		const tools = filterExecutionTools(executionToolPolicy, agent.state.tools);
 		const turnPolicy = agentManager.createAgentTurnPolicy(conversationId);
-		const systemPrompt = appendDynamicPromptSection([agent.state.systemPrompt ?? "", params.presentation === "voice" ? voicePresentationPrompt : ""].filter(Boolean).join("\n\n"), params.dynamicSystemContext ?? "");
+		const systemPrompt = appendDynamicPromptSection([agent.state.systemPrompt ?? "", params.presentation === "voice" ? voicePresentationPrompt : ""].filter(Boolean).join("\n\n"), [params.dynamicSystemContext, connectionObjectiveContext(conversationId)].filter(Boolean).join("\n\n"));
 		const idlePolicy = resolveCompactionPolicy(config);
 		if (personal && idlePolicy.enabled && idlePolicy.personalIdle.enabled) idleJob = async (signal, isCurrent) => {
 			const messages = await sessionStore.load(conversationId);
@@ -185,10 +195,10 @@ async function runEmbeddedTurnForSessionInner(params) {
 				startupAction: params.startupAction,
 				force: params.forceStartupContext
 			});
-			if (supervisor.signal.aborted) return {
+			if (supervisor.signal.aborted) return await finish({
 				ok: false,
 				errorMessage: "aborted"
-			};
+			});
 		}
 		try {
 			await maybeAutoCompactBeforeTurn({
@@ -206,16 +216,16 @@ async function runEmbeddedTurnForSessionInner(params) {
 				onEvent: params.onEvent
 			});
 		} catch (err) {
-			if (supervisor.signal.aborted) return {
+			if (supervisor.signal.aborted) return await finish({
 				ok: false,
 				errorMessage: "aborted"
-			};
+			});
 			throw err;
 		}
-		if (supervisor.signal.aborted) return {
+		if (supervisor.signal.aborted) return await finish({
 			ok: false,
 			errorMessage: "aborted"
-		};
+		});
 		log.info({
 			conversationId,
 			runId,
@@ -281,9 +291,22 @@ async function runEmbeddedTurnForSessionInner(params) {
 					timeoutMs: attemptPlan.timeoutMs,
 					turnPolicy,
 					abortSignal: supervisor.signal,
-					onEvent: params.onEvent,
+					onEvent: (event) => {
+						if (event.type === "error") {
+							log.warn({
+								conversationId,
+								runId,
+								modelRef: candidateModelRef,
+								errorMessage: event.content
+							}, "Model attempt failed");
+							return;
+						}
+						params.onEvent?.(event);
+					},
 					onAgentEvent: (event) => agentManager.emitRuntimeEvent(conversationId, event),
 					resumeLastUserMessage,
+					recoveryMessage: taskContinuation?.message,
+					recoveryReason: taskContinuation?.reason,
 					requireVisibleReply: params.requireVisibleReply
 				}), runId));
 				attempt.finish(turnResult.ok ? "success" : "error", turnResult.errorMessage);
@@ -330,7 +353,7 @@ async function runEmbeddedTurnForSessionInner(params) {
 				}, hasNextCandidate ? "Agent model call threw, trying fallback" : "Agent model call threw, no fallback remains");
 			}
 			if (hasNextCandidate && rowsBeforeAttempt) {
-				const preparation = await sessionStore.prepareModelFallback(conversationId, rowsBeforeAttempt);
+				const preparation = await sessionStore.prepareModelFallback(conversationId, rowsBeforeAttempt, { resumeTaskContinuation: Boolean(taskContinuation?.message) });
 				if (preparation === "unsafe") {
 					log.warn({
 						conversationId,

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

@@ -10,12 +10,14 @@ import { resolveEffectiveAgentConfigForSession } from "../../config/agent-profil
 import { setTraceIdentity, traceOperation, traceRun, traceTools } from "../../observability/runtime.js";
 import { continuesAfterTool, trackAiUsageStream } from "../../usage/recorder.js";
 import { cloudCreditBudgetStopMessage, isCloudCreditBudgetExhausted, reportCloudCreditError, withCloudCreditBudget } from "../../providers/xopc-cloud-credit-budget.js";
-import { isAgentTurnUnsettledError, resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
+import { resolveAgentAbortReason } from "../orchestration/run-termination.js";
+import { isAgentTurnTimeoutError, isAgentTurnUnsettledError, resolveAgentTurnTimeoutMs, runAgentTurnWithTimeout } from "../orchestration/run-agent-turn-with-timeout.js";
 import { isContextOverflowError } from "../orchestration/context-overflow.js";
+import { ACCEPTANCE_REPAIR_READ_TOOLS, canResumeAfterModelFailure, completedRecoveryToolResult } from "../orchestration/turn-recovery.js";
 import { getAssistantTurnErrorMessage, isAssistantTurnAborted, isAssistantTurnFailed, maybeRetryTurnAfterTransientLlmFailure, stripTrailingErrorAssistantMessages } from "../orchestration/llm-turn-retry.js";
 import { allowsExecutionTool, filterExecutionTools, resolveExecutionToolPolicy } from "./execution-tool-policy.js";
 import { runWithEmbeddedExecutionSession } from "./execution-context.js";
-import { externalPolicyContext } from "./tool-metadata.js";
+import { externalPolicyContext, getXopcToolMetadata } from "./tool-metadata.js";
 import { isComputerControlActive, isComputerLeaseTool, stopComputerControl } from "../../computer/control-guard.js";
 import { EmbeddedRunConflictError, abortEmbeddedRun, acquireEmbeddedRunLease, queueEmbeddedSteer } from "./runs.js";
 import { lastAssistantPlainText, subscribeEmbeddedSessionEvents } from "./subscribe-session.js";
@@ -46,6 +48,17 @@ init_sqlite();
 init_session_repository();
 const log = createLogger("EmbeddedRun");
 const LOG_PREVIEW_MAX_CHARS = 300;
+const RECOVERY_READ_TOOLS = new Set([
+	"read_file",
+	"find",
+	"grep",
+	"list_dir",
+	"tool_manual",
+	"tool_search",
+	"review_workspace",
+	"language_diagnostics",
+	"session_status"
+]);
 function truncateForLog(value, maxChars = LOG_PREVIEW_MAX_CHARS) {
 	return value.length > maxChars ? `${value.slice(0, maxChars)}…` : value;
 }
@@ -216,6 +229,11 @@ async function maybeRecoverInterruptedContext(params) {
 	const overflow = !!errorMessage && isContextOverflowError(errorMessage);
 	const recoverableLength = !!assistant && isRecoverableLengthForModel(assistant, params.model);
 	if (!overflow && !recoverableLength) return false;
+	const discardedCalls = new Set(recoverableLength && assistant ? discardedAttempt(assistant).toolCallIds : []);
+	if (!canResumeAfterModelFailure(params.agent.state.messages.filter((message) => !recoverableLength || message !== assistant && !(message.role === "toolResult" && discardedCalls.has(message.toolCallId))))) {
+		log.warn({ conversationId: params.conversationId }, "Context recovery stopped because a tool outcome is unconfirmed");
+		return false;
+	}
 	if (recoverableLength && (!params.policy.enabled || params.recoveryState.interruptedAttempts >= 1)) {
 		log.warn({
 			conversationId: params.conversationId,
@@ -343,12 +361,14 @@ async function runXopcEmbeddedTurnInner(params) {
 			await session.abort();
 			return {
 				ok: false,
+				terminationReason: resolveAgentAbortReason(runAbortSignal.reason),
 				errorMessage: "aborted"
 			};
 		}
 		session.agent.state.messages = stripTrailingErrorAssistantMessages(await transcriptRuntime.loadMessages());
 		runner.piSm.setActiveTurnId?.(runId);
 		const recoveryState = { interruptedAttempts: 0 };
+		const requestRetryBudget = { continues: 0 };
 		let useAuthoritativeProjection = false;
 		const basePrepareNextTurn = session.agent.prepareNextTurnWithContext;
 		const inTurnPrepareNextTurn = async (turn, signal) => {
@@ -566,10 +586,11 @@ async function runXopcEmbeddedTurnInner(params) {
 		session.agent.streamFunction = loggingStreamFn;
 		const verification = await RunVerification.open(workspaceDir);
 		const checkpoints = runner.piSm.getBranch?.() ?? [];
+		const recoveryTurn = params.resumeLastUserMessage === true || Boolean(params.recoveryMessage);
 		const lastStart = checkpoints.findLastIndex((entry) => entry.type === "custom" && entry.customType === "coding_run_started");
 		const lastSummary = checkpoints.findLastIndex((entry) => entry.type === "custom" && entry.customType === "coding_verification");
-		const checkpoint = checkpoints[params.resumeLastUserMessage && lastSummary >= lastStart ? lastSummary : lastStart];
-		if (checkpoint?.type === "custom" && (params.resumeLastUserMessage || lastStart > lastSummary)) verification.restore(checkpoint.data, params.resumeLastUserMessage === true && lastSummary >= lastStart);
+		const checkpoint = checkpoints[recoveryTurn && lastSummary >= lastStart ? lastSummary : lastStart];
+		if (checkpoint?.type === "custom" && (recoveryTurn || lastStart > lastSummary)) verification.restore(checkpoint.data, recoveryTurn && lastSummary >= lastStart);
 		runner.piSm.appendCustomEntry("coding_run_started", {
 			runId,
 			workspace: workspaceDir,
@@ -577,6 +598,11 @@ async function runXopcEmbeddedTurnInner(params) {
 			...await verification.summary()
 		});
 		let policyStopped = false;
+		let policyCompleted = false;
+		let recoveringModel = params.resumeLastUserMessage === true || Boolean(params.recoveryMessage);
+		let recoveryMessages = [...session.agent.state.messages];
+		let policyStopReason;
+		let lengthRecoveryExhausted = false;
 		let connectionStopped = false;
 		let clarificationStopped = false;
 		let sentVisibleMessage = false;
@@ -588,6 +614,7 @@ async function runXopcEmbeddedTurnInner(params) {
 			};
 			if (executionToolPolicy.surface !== "agent" && resolveExecutionToolPolicy(toolPolicyConversationId).surface !== executionToolPolicy.surface) {
 				policyStopped = true;
+				policyStopReason = "Execution identity changed during the run";
 				quarantineRunner = true;
 				return {
 					block: true,
@@ -615,8 +642,24 @@ async function runXopcEmbeddedTurnInner(params) {
 			const decision = await params.turnPolicy?.beforeToolCall(externalPolicyContext(context, tools), signal);
 			if (decision?.block) {
 				policyStopped ||= decision.terminate === true;
+				if (decision.terminate) policyStopReason = decision.reason;
 				return decision;
 			}
+			const tool = tools.find((candidate) => candidate.name === context.toolCall.name);
+			const metadata = tool && getXopcToolMetadata(tool);
+			const readOnly = RECOVERY_READ_TOOLS.has(context.toolCall.name) || metadata?.external?.readOnly === true || metadata?.annotations?.readOnlyHint === true || context.toolCall.name === "task_collaboration" && context.args.command === "get" || context.toolCall.name === "managed_job" && [
+				"wait",
+				"status",
+				"list"
+			].includes(String(context.args.action));
+			const repairPublication = ["acceptance_repair", "model_failure"].includes(params.recoveryReason ?? "") && ["publish_artifacts", "publish_task_result"].includes(context.toolCall.name);
+			if (recoveringModel && !readOnly && !repairPublication) {
+				const recorded = completedRecoveryToolResult(recoveryMessages, context.toolCall.name, context.args);
+				if (recorded) return {
+					block: true,
+					reason: recorded
+				};
+			}
 			if (context.toolCall.name !== "read_file") {
 				const scoped = await instructions.forTool(context.toolCall.name, context.args);
 				if (scoped) return {
@@ -661,9 +704,12 @@ async function runXopcEmbeddedTurnInner(params) {
 					conversationId,
 					runId
 				}, "Stopping after the bounded truncated-response recovery attempt");
+				lengthRecoveryExhausted = true;
 				return { action: "end" };
 			}
 			policyStopped ||= params.turnPolicy?.shouldStopAfterTurn(context) ?? false;
+			policyCompleted ||= policyStopped && params.turnPolicy?.stopReason?.() === "completed";
+			if (policyStopped) policyStopReason ??= "Agent execution policy stopped before completion";
 			if (policyStopped || connectionStopped || clarificationStopped) return { action: "end" };
 			const continuation = params.turnPolicy?.takeContinuationMessage?.();
 			if (continuation) {
@@ -705,10 +751,16 @@ async function runXopcEmbeddedTurnInner(params) {
 		};
 		runAbortSignal.addEventListener("abort", abortListener, { once: true });
 		try {
+			if (runAbortSignal.aborted) return {
+				ok: false,
+				terminationReason: resolveAgentAbortReason(runAbortSignal.reason),
+				errorMessage: "aborted"
+			};
 			await runAgentTurnWithTimeout(session.agent, () => withDelegationScope({
 				tools,
 				authorizeToolCall: params.turnPolicy ? (context, signal) => runWithEmbeddedExecutionSession(conversationId, () => params.turnPolicy.beforeToolCall(context, signal), runId) : void 0
 			}, async () => {
+				if (runAbortSignal.aborted) return;
 				const connectionResume = getConnectionResumeInput(conversationId, runId);
 				const clarificationResume = getClarificationResumeInput(conversationId, runId);
 				if (connectionResume) await session.sendCustomMessage({
@@ -721,7 +773,14 @@ async function runXopcEmbeddedTurnInner(params) {
 					content: clarificationResume.content,
 					display: false
 				}, { triggerTurn: true });
-				else if (params.resumeLastUserMessage) await session.agent.continue();
+				else if (params.recoveryMessage && !params.resumeLastUserMessage) {
+					if (!canResumeAfterModelFailure(session.agent.state.messages, ["acceptance_repair", "model_failure"].includes(params.recoveryReason ?? "") ? { allowFailedReadTools: ACCEPTANCE_REPAIR_READ_TOOLS } : void 0)) throw new Error("Cannot resume because a tool outcome is unconfirmed");
+					await session.sendCustomMessage({
+						customType: "task_continuation",
+						content: params.recoveryMessage,
+						display: false
+					}, { triggerTurn: true });
+				} else if (params.resumeLastUserMessage) await session.agent.continue();
 				else {
 					const text = userMessageToPromptText(userMessage);
 					const images = params.images ?? [];
@@ -730,25 +789,47 @@ async function runXopcEmbeddedTurnInner(params) {
 				await session.agent.waitForIdle();
 				clarificationStopped ||= isClarificationSuspended(conversationId, runId);
 				if (connectionStopped || clarificationStopped) return;
-				await maybeRetryTurnAfterTransientLlmFailure(session.agent, {
-					conversationId,
-					log,
-					signal: runAbortSignal
-				});
-				await maybeRecoverInterruptedContext({
-					agent: session.agent,
-					model: resolvedModel,
-					conversationId,
-					transcriptRuntime,
-					policy: compactionPolicy,
-					systemPrompt: [systemPrompt, rootInstructions].filter(Boolean).join("\n\n"),
-					abortSignal: runAbortSignal,
-					onEvent,
-					recoveryState,
-					onContextRecovered: () => {
-						useAuthoritativeProjection = true;
-					}
-				});
+				const recoverSettledTurn = async () => {
+					if (policyStopped || connectionStopped || clarificationStopped) return;
+					await maybeRetryTurnAfterTransientLlmFailure(session.agent, {
+						conversationId,
+						log,
+						signal: runAbortSignal,
+						budget: requestRetryBudget,
+						shouldRetry: () => !policyStopped && !connectionStopped && !clarificationStopped,
+						onRetry: () => {
+							recoveringModel = true;
+							recoveryMessages = [...session.agent.state.messages];
+						}
+					});
+					if (policyStopped || connectionStopped || clarificationStopped) return;
+					if (await maybeRecoverInterruptedContext({
+						agent: session.agent,
+						model: resolvedModel,
+						conversationId,
+						transcriptRuntime,
+						policy: compactionPolicy,
+						systemPrompt: [systemPrompt, rootInstructions].filter(Boolean).join("\n\n"),
+						abortSignal: runAbortSignal,
+						onEvent,
+						recoveryState,
+						onContextRecovered: () => {
+							useAuthoritativeProjection = true;
+							recoveringModel = true;
+						}
+					})) await maybeRetryTurnAfterTransientLlmFailure(session.agent, {
+						conversationId,
+						log,
+						signal: runAbortSignal,
+						budget: requestRetryBudget,
+						shouldRetry: () => !policyStopped && !connectionStopped && !clarificationStopped,
+						onRetry: () => {
+							recoveringModel = true;
+							recoveryMessages = [...session.agent.state.messages];
+						}
+					});
+				};
+				await recoverSettledTurn();
 				if (params.requireVisibleReply && !sentVisibleMessage && !policyStopped && !runAbortSignal.aborted && !isAssistantTurnFailed(session.agent) && !isAssistantTurnAborted(session.agent) && lastAssistantPlainText(session).trim() === "NO_REPLY") {
 					await session.sendCustomMessage({
 						customType: "visible_reply_required",
@@ -756,6 +837,7 @@ async function runXopcEmbeddedTurnInner(params) {
 						display: false
 					}, { triggerTurn: true });
 					await session.agent.waitForIdle();
+					await recoverSettledTurn();
 				}
 				const pending = await verification.pendingContext();
 				if ((params.verifyChanges ?? false) && pending && !policyStopped && !runAbortSignal.aborted && !isAssistantTurnFailed(session.agent) && !isAssistantTurnAborted(session.agent)) {
@@ -765,8 +847,9 @@ async function runXopcEmbeddedTurnInner(params) {
 						display: false
 					}, { triggerTurn: true });
 					await session.agent.waitForIdle();
+					await recoverSettledTurn();
 				}
-			}), timeoutMs);
+			}), timeoutMs, { timeoutExtensionMs: params.timeoutExtensionMs });
 			if (connectionStopped) runner.piSm.appendCustomEntry("connection_required", {
 				runId,
 				conversationId
@@ -784,14 +867,27 @@ async function runXopcEmbeddedTurnInner(params) {
 			if (runAbortSignal.aborted) return {
 				ok: false,
 				retryable: false,
+				terminationReason: resolveAgentAbortReason(runAbortSignal.reason),
 				errorMessage: "aborted"
 			};
 			if (isAssistantTurnAborted(session.agent)) return {
-				ok: true,
+				ok: false,
+				retryable: false,
+				terminationReason: "provider_error",
+				errorMessage: "aborted",
+				lastAssistantText: lastAssistantPlainText(session)
+			};
+			if (policyStopped && !policyCompleted || lengthRecoveryExhausted || lastAssistantMessage(session.agent.state.messages)?.stopReason === "length") return {
+				ok: false,
+				retryable: false,
+				errorMessage: policyStopReason ?? "Assistant response was truncated before completion",
+				stopReason: policyStopped ? "policy_limit" : "response_truncated",
 				lastAssistantText: lastAssistantPlainText(session)
 			};
 			if (isAssistantTurnFailed(session.agent)) return {
 				ok: false,
+				retryable: canResumeAfterModelFailure(session.agent.state.messages, { allowFailedReadTools: ACCEPTANCE_REPAIR_READ_TOOLS }),
+				terminationReason: "provider_error",
 				errorMessage: getAssistantTurnErrorMessage(session.agent) ?? "Assistant turn failed",
 				lastAssistantText: lastAssistantPlainText(session)
 			};
@@ -851,6 +947,7 @@ async function runXopcEmbeddedTurnInner(params) {
 		});
 		return {
 			ok: false,
+			terminationReason: isAgentTurnTimeoutError(err) ? "deadline_exceeded" : params.abortSignal?.aborted ? resolveAgentAbortReason(params.abortSignal.reason) : "runtime_error",
 			errorMessage: em
 		};
 	} finally {

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

@@ -18,16 +18,23 @@ export type EmbeddedRunLease = {
     attach(session: AgentSession, abort: () => Promise<void>): Promise<void>;
     release(): void;
 };
+export type EmbeddedRunCancellation = {
+    signal: AbortSignal;
+    release(): void;
+};
 /** Owns one process-local execution lease per session while leaving steer/abort on the control plane. */
 export declare class EmbeddedRunRegistry {
     private readonly byConversationId;
+    private readonly prepared;
+    reserveCancellation(identity: Pick<EmbeddedRunIdentity, 'conversationId' | 'runId'>): EmbeddedRunCancellation;
     acquire(identity: EmbeddedRunIdentity): EmbeddedRunLease;
     getByConversationId(conversationId: string): EmbeddedRunHandle | undefined;
-    abortByConversationId(conversationId: string): Promise<boolean>;
+    abortByConversationId(conversationId: string, reason?: 'user_cancelled' | 'parent_cancelled', expectedRunId?: string): Promise<boolean>;
     steerByConversationId(conversationId: string, text: string): Promise<boolean>;
     size(): number;
 }
 export declare function acquireEmbeddedRunLease(identity: EmbeddedRunIdentity): EmbeddedRunLease;
+export declare function reserveEmbeddedRunCancellation(identity: Pick<EmbeddedRunIdentity, 'conversationId' | 'runId'>): EmbeddedRunCancellation;
 export declare function getEmbeddedRunByConversationId(conversationId: string): EmbeddedRunHandle | undefined;
-export declare function abortEmbeddedRun(conversationId: string): Promise<boolean>;
+export declare function abortEmbeddedRun(conversationId: string, reason?: 'user_cancelled' | 'parent_cancelled', expectedRunId?: string): Promise<boolean>;
 export declare function queueEmbeddedSteer(conversationId: string, text: string): Promise<boolean>;

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

@@ -1,3 +1,4 @@
+import { AgentRunCancelledError } from "../orchestration/run-termination.js";
 //#region src/agent/embedded/runs.ts
 var EmbeddedRunConflictError = class extends Error {
 	constructor(conversationId, activeRunId) {
@@ -10,12 +11,26 @@ var EmbeddedRunConflictError = class extends Error {
 /** Owns one process-local execution lease per session while leaving steer/abort on the control plane. */
 var EmbeddedRunRegistry = class {
 	byConversationId = /* @__PURE__ */ new Map();
+	prepared = /* @__PURE__ */ new Map();
+	reserveCancellation(identity) {
+		const key = JSON.stringify([identity.conversationId, identity.runId]);
+		if (this.prepared.has(key)) throw new EmbeddedRunConflictError(identity.conversationId, identity.runId);
+		const controller = new AbortController();
+		this.prepared.set(key, controller);
+		return {
+			signal: controller.signal,
+			release: () => {
+				if (this.prepared.get(key) === controller) this.prepared.delete(key);
+			}
+		};
+	}
 	acquire(identity) {
 		const active = this.byConversationId.get(identity.conversationId);
 		if (active) throw new EmbeddedRunConflictError(identity.conversationId, active.runId);
+		const controller = this.prepared.get(JSON.stringify([identity.conversationId, identity.runId]));
 		const entry = {
 			...identity,
-			abortController: new AbortController()
+			abortController: controller ?? new AbortController()
 		};
 		this.byConversationId.set(identity.conversationId, entry);
 		return {
@@ -36,10 +51,15 @@ var EmbeddedRunRegistry = class {
 	getByConversationId(conversationId) {
 		return this.byConversationId.get(conversationId)?.handle;
 	}
-	async abortByConversationId(conversationId) {
+	async abortByConversationId(conversationId, reason = "parent_cancelled", expectedRunId) {
 		const entry = this.byConversationId.get(conversationId);
-		if (!entry) return false;
-		entry.abortController.abort(/* @__PURE__ */ new Error("Embedded run aborted"));
+		if (!entry || expectedRunId !== void 0 && entry.runId !== expectedRunId) {
+			const prepared = expectedRunId === void 0 ? void 0 : this.prepared.get(JSON.stringify([conversationId, expectedRunId]));
+			if (!prepared) return false;
+			prepared.abort(new AgentRunCancelledError("Embedded run aborted", reason));
+			return true;
+		}
+		entry.abortController.abort(new AgentRunCancelledError("Embedded run aborted", reason));
 		if (entry.handle) await entry.handle.abort();
 		return true;
 	}
@@ -57,14 +77,17 @@ const embeddedRunRegistry = new EmbeddedRunRegistry();
 function acquireEmbeddedRunLease(identity) {
 	return embeddedRunRegistry.acquire(identity);
 }
+function reserveEmbeddedRunCancellation(identity) {
+	return embeddedRunRegistry.reserveCancellation(identity);
+}
 function getEmbeddedRunByConversationId(conversationId) {
 	return embeddedRunRegistry.getByConversationId(conversationId);
 }
-function abortEmbeddedRun(conversationId) {
-	return embeddedRunRegistry.abortByConversationId(conversationId);
+function abortEmbeddedRun(conversationId, reason = "parent_cancelled", expectedRunId) {
+	return embeddedRunRegistry.abortByConversationId(conversationId, reason, expectedRunId);
 }
 function queueEmbeddedSteer(conversationId, text) {
 	return embeddedRunRegistry.steerByConversationId(conversationId, text);
 }
 //#endregion
-export { EmbeddedRunConflictError, EmbeddedRunRegistry, abortEmbeddedRun, acquireEmbeddedRunLease, getEmbeddedRunByConversationId, queueEmbeddedSteer };
+export { EmbeddedRunConflictError, EmbeddedRunRegistry, abortEmbeddedRun, acquireEmbeddedRunLease, getEmbeddedRunByConversationId, queueEmbeddedSteer, reserveEmbeddedRunCancellation };