@xopcai/xopc 0.0.385 → 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/run-for-session.js

@@ -17,6 +17,7 @@ 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";
@@ -59,6 +60,7 @@ async function runEmbeddedTurnForSessionInner(params) {
 			...result,
 			ok: false,
 			retryable: false,
+			terminationReason: "deadline_exceeded",
 			errorMessage: supervisor.signal.reason.message
 		};
 		turnCompleted = result.ok && result.stopReason !== "connection_required" && result.stopReason !== "clarification_required";
@@ -138,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);
@@ -304,6 +306,7 @@ async function runEmbeddedTurnForSessionInner(params) {
 					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);
@@ -350,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,9 +10,10 @@ 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 { canResumeAfterModelFailure, completedRecoveryToolResult } from "../orchestration/turn-recovery.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";
@@ -360,6 +361,7 @@ async function runXopcEmbeddedTurnInner(params) {
 			await session.abort();
 			return {
 				ok: false,
+				terminationReason: resolveAgentAbortReason(runAbortSignal.reason),
 				errorMessage: "aborted"
 			};
 		}
@@ -650,7 +652,8 @@ async function runXopcEmbeddedTurnInner(params) {
 				"status",
 				"list"
 			].includes(String(context.args.action));
-			if (recoveringModel && !readOnly) {
+			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,
@@ -748,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({
@@ -765,7 +774,7 @@ async function runXopcEmbeddedTurnInner(params) {
 					display: false
 				}, { triggerTurn: true });
 				else if (params.recoveryMessage && !params.resumeLastUserMessage) {
-					if (!canResumeAfterModelFailure(session.agent.state.messages)) throw new Error("Cannot resume because a tool outcome is unconfirmed");
+					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,
@@ -840,7 +849,7 @@ async function runXopcEmbeddedTurnInner(params) {
 					await session.agent.waitForIdle();
 					await recoverSettledTurn();
 				}
-			}), timeoutMs);
+			}), timeoutMs, { timeoutExtensionMs: params.timeoutExtensionMs });
 			if (connectionStopped) runner.piSm.appendCustomEntry("connection_required", {
 				runId,
 				conversationId
@@ -858,11 +867,13 @@ async function runXopcEmbeddedTurnInner(params) {
 			if (runAbortSignal.aborted) return {
 				ok: false,
 				retryable: false,
+				terminationReason: resolveAgentAbortReason(runAbortSignal.reason),
 				errorMessage: "aborted"
 			};
 			if (isAssistantTurnAborted(session.agent)) return {
 				ok: false,
 				retryable: false,
+				terminationReason: "provider_error",
 				errorMessage: "aborted",
 				lastAssistantText: lastAssistantPlainText(session)
 			};
@@ -875,7 +886,8 @@ async function runXopcEmbeddedTurnInner(params) {
 			};
 			if (isAssistantTurnFailed(session.agent)) return {
 				ok: false,
-				retryable: canResumeAfterModelFailure(session.agent.state.messages),
+				retryable: canResumeAfterModelFailure(session.agent.state.messages, { allowFailedReadTools: ACCEPTANCE_REPAIR_READ_TOOLS }),
+				terminationReason: "provider_error",
 				errorMessage: getAssistantTurnErrorMessage(session.agent) ?? "Assistant turn failed",
 				lastAssistantText: lastAssistantPlainText(session)
 			};
@@ -935,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 };

package/dist/src/agent/embedded/session-runner.js

@@ -12,6 +12,7 @@ import { xopcToolsToDefinitions } from "./xopc-tools-bridge.js";
 import { createXopcCodemodeExtension } from "./codemode-extension.js";
 import { TOOL_DISCOVERY_STATE, createXopcToolSearchExtension } from "./tool-search-extension.js";
 import { getNativePiAgentDir } from "../mcp/native-mcp.js";
+import { AGENT_PROFILE_CONTEXT_STATE, createAgentProfileContextExtension } from "./agent-profile-context.js";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
 import { DefaultResourceLoader, SettingsManager, createAgentSession, createMcpExtension } from "@earendil-works/pi-coding-agent";
@@ -242,6 +243,7 @@ var EmbeddedSessionRunnerPool = class {
 				"coding_run_started",
 				"coding_verification",
 				"xopc.model-selection",
+				AGENT_PROFILE_CONTEXT_STATE,
 				"connection_required",
 				"clarification_required"
 			],
@@ -282,7 +284,8 @@ var EmbeddedSessionRunnerPool = class {
 				...mcp ? [createMcpExtension({
 					loadConfig: () => mcp,
 					logPath: join(getNativePiAgentDir(), "mcp.log")
-				})] : []
+				})] : [],
+				createAgentProfileContextExtension(runtimeId)
 			]
 		});
 		await resourceLoader.reload();
@@ -300,7 +303,7 @@ var EmbeddedSessionRunnerPool = class {
 		});
 		boundSession = session;
 		session.setActiveToolsByName(toolNames);
-		if (codemode || discovery || mcp) await session.bindExtensions({});
+		await session.bindExtensions({});
 		const baseStreamFn = wrapStreamFnForXopcExtensions(session.agent.streamFunction);
 		session.agent.streamFunction = baseStreamFn;
 		return {

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

@@ -88,6 +88,8 @@ export type RunXopcEmbeddedTurnParams = {
     sessionStore?: SessionStore;
     transcriptRuntime?: EmbeddedTranscriptRuntime;
     timeoutMs: number;
+    /** One bounded deadline extension for an already-dispatched budget handoff. */
+    timeoutExtensionMs?: () => number;
     turnPolicy?: AgentTurnPolicy;
     abortSignal?: AbortSignal;
     onEvent?: (event: EmbeddedStreamEvent) => void;
@@ -96,10 +98,12 @@ export type RunXopcEmbeddedTurnParams = {
     /** Continue from the persisted trailing user row instead of appending it again. */
     resumeLastUserMessage?: boolean;
     recoveryMessage?: string;
+    recoveryReason?: string;
     verifyChanges?: boolean;
     requireVisibleReply?: boolean;
 };
 export type RunXopcEmbeddedTurnResult = {
+    terminationReason?: import('../orchestration/run-termination.js').AgentTerminationReason;
     ok: boolean;
     stopReason?: 'connection_required' | 'clarification_required' | 'policy_limit' | 'response_truncated';
     /** False for harness failures that must not trigger another model attempt. */

package/dist/src/agent/external-tools/gateway-tools.js

@@ -97,7 +97,8 @@ function createExternalToolGatewayTools(providers, getContext, getConfig, getExe
 				...result,
 				connectionCandidates: candidates,
 				installCandidates,
-				...result.tools.length === 0 && (candidates.length > 0 || installCandidates.length > 0) ? { instruction: "The requested app is available but is not connected. Explain that connection is required, then call xopc_require_connection with an exact candidateRef from this result. Do not fall back to browser automation unless the user explicitly asked for browser use or skips the connection." } : {},
+				...result.tools.length === 0 && (candidates.length > 0 || installCandidates.length > 0) ? { instruction: "No executable tool matched this search. This alone does not prove the account is disconnected. Retry without restrictive sources and inspect the returned account state. If authorization or account selection is actually required, call xopc_require_connection with an exact candidateRef from this result; the host owns selection, authorization and automatic continuation. Do not ask the user whether to perform an already requested read, or to reply continue after authorization. Do not fall back to browser automation unless the user explicitly asked for browser use or skips the connection." } : {},
+				...result.tools.length > 0 ? { instruction: "Describe the relevant tool contracts and execute the requested read using the available authorized account. The user request already authorizes these reads; do not ask for another confirmation. Respect the exact contracts and host permission checks. Hand off to the user only when a required authorization, ambiguous account choice or essential missing decision cannot be resolved from existing context." } : {},
 				...installCatalogError ? { installCatalogError } : {},
 				...excludedSources.length ? { searchScope: {
 					excludedSources,
@@ -222,7 +223,7 @@ function createExternalToolGatewayTools(providers, getContext, getConfig, getExe
 		name: EXTERNAL_TOOL_NAMES.requireConnection,
 		label: "Connect app",
 		parameters: requireSchema,
-		description: "Request a connectionCandidates or installCandidates entry returned by xopc_tool_search. Explain the need once before calling. This pauses the current objective and displays one action area above the input. Never invent a candidate reference, return OAuth URLs, or repeat a skipped request. If another objective is waiting, ask the user to continue or cancel it first.",
+		description: "Use only when a requested read cannot proceed because authorization, installation or account selection is required. Available authorized tools should be executed directly without asking the user to confirm the read. Request an exact connectionCandidates or installCandidates entry returned by xopc_tool_search. Explain the verified need once before calling. This saves and pauses the objective, displays one action area above the input, and lets the host resume automatically after the required user action. Stop this turn after connection_required; never ask the user to reply continue after authorization. Never invent a candidate reference, return OAuth URLs, or repeat a skipped request. If another objective is waiting, do not create a duplicate objective.",
 		async execute(_id, params) {
 			const context = getContext?.();
 			if (!context) throw new Error("No active conversation.");
@@ -285,7 +286,10 @@ function createExternalToolGatewayTools(providers, getContext, getConfig, getExe
 				}))
 			});
 			publishConnectionWait(context.conversationId);
-			return textResult(result);
+			return textResult({
+				...result,
+				...result.status === "connection_required" ? { instruction: "The objective is saved and the host owns the connection or account-selection interaction. Stop this turn. After the required user action, the host will check readiness and continue automatically. Do not ask for another confirmation of this read or ask the user to reply continue." } : result.status === "objective_conflict" ? { instruction: "An objective is already waiting. Do not create another request or claim the account is disconnected. Inspect the existing objective before asking for a genuinely missing decision." } : {}
+			});
 		}
 	};
 	const reviseSchema = Type.Object({

package/dist/src/agent/orchestration/agent-run-supervisor.js

@@ -1,3 +1,4 @@
+import { AgentRunDeadlineError } from "./run-termination.js";
 //#region src/agent/orchestration/agent-run-supervisor.ts
 /** Minimal run-level coordination: root cancellation and per-attempt deadline planning. */
 var AgentRunSupervisor = class {
@@ -18,7 +19,7 @@ var AgentRunSupervisor = class {
 		this.forwardParentAbort = () => this.controller.abort(this.parentSignal?.reason);
 		if (this.parentSignal?.aborted) this.forwardParentAbort();
 		else this.parentSignal?.addEventListener("abort", this.forwardParentAbort, { once: true });
-		this.timeout = setTimeout(() => this.controller.abort(/* @__PURE__ */ new Error("Agent run deadline expired")), Math.max(0, this.deadlineAtMs - Date.now()));
+		this.timeout = setTimeout(() => this.controller.abort(new AgentRunDeadlineError()), Math.max(0, this.deadlineAtMs - Date.now()));
 	}
 	planModelAttempt(isFallback) {
 		if (this.signal.aborted) return {

package/dist/src/agent/orchestration/agent-turn-policy.js

@@ -1,5 +1,6 @@
 import { dataOperationCalls } from "../data-acquisition/schema.js";
 //#region src/agent/orchestration/agent-turn-policy.ts
+const expandedBatchContexts = /* @__PURE__ */ new WeakSet();
 /** One user-visible run policy. A fresh instance is created for every embedded run. */
 function createAgentTurnPolicy(options) {
 	const toolCalls = /* @__PURE__ */ new Map();
@@ -12,7 +13,10 @@ function createAgentTurnPolicy(options) {
 			assistantTurns = 0;
 		},
 		async beforeToolCall(context, signal) {
-			const contexts = context.toolCall.name === "data_batch" ? [context, ...dataOperationCalls(context.args).map((call, index) => ({
+			const wrapper = { ...context };
+			const expand = context.toolCall.name === "data_batch" && !expandedBatchContexts.has(context);
+			if (expand) expandedBatchContexts.add(wrapper);
+			const contexts = expand ? [wrapper, ...dataOperationCalls(context.args).map((call, index) => ({
 				...context,
 				args: call.args,
 				toolCall: {

package/dist/src/agent/orchestration/delegation-budget.d.ts

@@ -17,7 +17,7 @@ export declare const DELEGATION_BUDGETS: {
     };
 };
 export type DelegationBudgetTier = keyof typeof DELEGATION_BUDGETS;
-export type DelegationStopReason = 'completed' | 'tool_calls' | 'total_tokens' | 'model_turns' | 'tool_failures' | 'timeout' | 'cancelled' | 'parent_policy' | 'credit_budget' | 'runtime_error' | 'verification';
+export type DelegationStopReason = 'completed' | 'tool_calls' | 'total_tokens' | 'model_turns' | 'tool_failures' | 'timeout' | 'deadline_exceeded' | 'user_cancelled' | 'parent_cancelled' | 'provider_error' | 'cancelled' | 'parent_policy' | 'credit_budget' | 'runtime_error' | 'verification';
 export declare function resolveDelegationBudget(tier?: DelegationBudgetTier, maxIterations?: number, timeoutMs?: number): {
     tier: "light" | "standard" | "deep";
     limits: {
@@ -26,6 +26,7 @@ export declare function resolveDelegationBudget(tier?: DelegationBudgetTier, max
         maxModelTurns: number;
         maxToolFailures: number;
         timeoutMs: number;
+        handoffReserveMs: number;
     };
 };
 /** Reserve the last 20% for one tool-free handoff, without bypassing hard limits. */
@@ -34,6 +35,9 @@ export declare function createDelegationBudgetPolicy(budget: ReturnType<typeof r
     authorizeToolCall?: AgentTurnPolicyOptions['authorizeToolCall'];
 }, now?: () => number): {
     policy: AgentTurnPolicy;
+    requestHandoff: (reason: DelegationStopReason) => void;
+    remainingMs: () => number;
+    researchRemainingMs: () => number;
     addTokens(tokens: number): void;
     stop(reason: DelegationStopReason, message?: string): void;
     snapshot(): {
@@ -47,6 +51,7 @@ export declare function createDelegationBudgetPolicy(budget: ReturnType<typeof r
         stopReason: DelegationStopReason;
         stopMessage: string;
         handoffRequested: boolean;
+        handoffRequestStarted: boolean;
         handoffReason: DelegationStopReason;
         tier: "light" | "standard" | "deep";
         limits: {
@@ -55,6 +60,7 @@ export declare function createDelegationBudgetPolicy(budget: ReturnType<typeof r
             maxModelTurns: number;
             maxToolFailures: number;
             timeoutMs: number;
+            handoffReserveMs: number;
         };
     };
 };

package/dist/src/agent/orchestration/delegation-budget.js

@@ -25,7 +25,8 @@ function resolveDelegationBudget(tier = "standard", maxIterations, timeoutMs) {
 			maxTotalTokens: preset.maxTotalTokens,
 			maxModelTurns: Math.min(60, Math.max(1, Math.floor(maxIterations ?? preset.maxToolCalls))) + 1,
 			maxToolFailures: 5,
-			timeoutMs: Math.min(timeoutMs ?? preset.timeoutMs, preset.timeoutMs)
+			timeoutMs: Math.min(timeoutMs ?? preset.timeoutMs, preset.timeoutMs),
+			handoffReserveMs: Math.floor(Math.min(timeoutMs ?? preset.timeoutMs, preset.timeoutMs) * .2)
 		}
 	};
 }
@@ -53,6 +54,12 @@ function createDelegationBudgetPolicy(budget, options, now = Date.now) {
 		if (usage.modelTurns >= limits.maxModelTurns * ratio) return "model_turns";
 		if (usage.toolFailures >= limits.maxToolFailures * ratio) return "tool_failures";
 	};
+	const requestHandoff = (reason) => {
+		if (handoffRequested) return;
+		handoffReason = reason;
+		handoffRequested = true;
+		continuation = handoff();
+	};
 	const handoff = () => `Delegation budget is approaching its ${handoffReason} limit. Do not call more tools. Return a concise handoff now: findings with file/line or source evidence, incomplete work, and precise next steps (including unread ranges). Do not claim the task is complete.`;
 	return {
 		policy: {
@@ -87,11 +94,12 @@ function createDelegationBudgetPolicy(budget, options, now = Date.now) {
 						reason: `Sub-agent budget exhausted: ${hard}.`
 					};
 				}
-				if (handoffRequested) return {
+				if (now() - startedAt >= limits.timeoutMs * .8) requestHandoff("timeout");
+				if (handoffRequested && (context.toolCall.name !== "research_checkpoint" || handoffRequestStarted)) return {
 					block: true,
 					reason: handoff()
 				};
-				if (context.toolCall.name !== "data_batch") usage.toolCalls++;
+				if (context.toolCall.name !== "data_batch" && context.toolCall.name !== "research_checkpoint") usage.toolCalls++;
 				const decision = await options.authorizeToolCall?.(context, signal);
 				if (decision?.block && decision.terminate) {
 					stopReason = "parent_policy";
@@ -110,16 +118,12 @@ function createDelegationBudgetPolicy(budget, options, now = Date.now) {
 					stopReason ??= hard;
 					return true;
 				}
-				if (handoffRequested) {
+				if (handoffRequestStarted) {
 					stopReason = handoffReason;
 					return true;
 				}
 				const near = reasonAt(.8);
-				if (near && context.toolResults.length) {
-					handoffReason = near;
-					handoffRequested = true;
-					continuation = handoff();
-				}
+				if (near && context.toolResults.length) requestHandoff(near);
 				return false;
 			},
 			takeContinuationMessage() {
@@ -129,6 +133,9 @@ function createDelegationBudgetPolicy(budget, options, now = Date.now) {
 			},
 			stopReason: () => !stopReason && options.isComplete?.() ? "completed" : "limit"
 		},
+		requestHandoff,
+		remainingMs: () => Math.max(0, limits.timeoutMs - (now() - startedAt)),
+		researchRemainingMs: () => Math.max(0, limits.timeoutMs - limits.handoffReserveMs - (now() - startedAt)),
 		addTokens(tokens) {
 			usage.totalTokens += Math.max(0, tokens);
 		},
@@ -146,6 +153,7 @@ function createDelegationBudgetPolicy(budget, options, now = Date.now) {
 				stopReason,
 				stopMessage,
 				handoffRequested,
+				handoffRequestStarted,
 				handoffReason
 			};
 		}

package/dist/src/agent/orchestration/research-checkpoint.d.ts

@@ -0,0 +1,56 @@
+import { type Static } from '@sinclair/typebox';
+import type { SearchCacheEntry } from '../tools/search/cache.js';
+export declare const ResearchFindingSchema: import("@sinclair/typebox").TObject<{
+    id: import("@sinclair/typebox").TString;
+    subject: import("@sinclair/typebox").TString;
+    field: import("@sinclair/typebox").TString;
+    status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"confirmed">, import("@sinclair/typebox").TLiteral<"not_disclosed">, import("@sinclair/typebox").TLiteral<"conflicting">, import("@sinclair/typebox").TLiteral<"unverified">]>;
+    conclusion: import("@sinclair/typebox").TString;
+    sources: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        url: import("@sinclair/typebox").TString;
+        title: import("@sinclair/typebox").TString;
+        excerpt: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
+}>;
+export declare const ResearchCheckpointUpdateSchema: import("@sinclair/typebox").TObject<{
+    findings: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        id: import("@sinclair/typebox").TString;
+        subject: import("@sinclair/typebox").TString;
+        field: import("@sinclair/typebox").TString;
+        status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"confirmed">, import("@sinclair/typebox").TLiteral<"not_disclosed">, import("@sinclair/typebox").TLiteral<"conflicting">, import("@sinclair/typebox").TLiteral<"unverified">]>;
+        conclusion: import("@sinclair/typebox").TString;
+        sources: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            url: import("@sinclair/typebox").TString;
+            title: import("@sinclair/typebox").TString;
+            excerpt: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>>;
+    }>>;
+    nextSteps: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+}>;
+export type ResearchFinding = Static<typeof ResearchFindingSchema> & {
+    checkedAt: number;
+};
+export type ResearchCheckpointUpdate = Static<typeof ResearchCheckpointUpdateSchema>;
+export interface ResearchEvidence {
+    toolCallId: string;
+    runId?: string;
+    toolName: string;
+    isError: boolean;
+    excerpt: string;
+    recordedAt: number;
+}
+export interface ResearchCheckpoint {
+    findings: ResearchFinding[];
+    nextSteps: string[];
+    evidence: ResearchEvidence[];
+    searches?: SearchCacheEntry[];
+}
+export interface ResearchCheckpointSink {
+    read(): ResearchCheckpoint;
+    save(update: ResearchCheckpointUpdate): ResearchCheckpoint;
+    recordEvidence(evidence: ResearchEvidence): void;
+    recordSearch?(entry: SearchCacheEntry): void;
+}
+/** Findings are model assertions with source evidence, never host-certified facts. */
+export declare function mergeResearchCheckpoint(current: ResearchCheckpoint, update: ResearchCheckpointUpdate, now?: number): ResearchCheckpoint;
+export declare function researchResumeContext(checkpoint: ResearchCheckpoint): string;