@xopcai/xopc 0.0.384 → 0.0.385

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

@@ -21,6 +21,7 @@ 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 +46,21 @@ 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,
+			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 +99,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));
@@ -185,10 +193,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 +214,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 +289,21 @@ 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,
 					requireVisibleReply: params.requireVisibleReply
 				}), runId));
 				attempt.finish(turnResult.ok ? "success" : "error", turnResult.errorMessage);

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

@@ -12,10 +12,11 @@ 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 { isContextOverflowError } from "../orchestration/context-overflow.js";
+import { 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 +47,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 +228,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,
@@ -349,6 +366,7 @@ async function runXopcEmbeddedTurnInner(params) {
 		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 +584,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 +596,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 +612,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 +640,23 @@ 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));
+			if (recoveringModel && !readOnly) {
+				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 +701,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) {
@@ -721,7 +764,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)) 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 +780,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 +828,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,6 +838,7 @@ async function runXopcEmbeddedTurnInner(params) {
 						display: false
 					}, { triggerTurn: true });
 					await session.agent.waitForIdle();
+					await recoverSettledTurn();
 				}
 			}), timeoutMs);
 			if (connectionStopped) runner.piSm.appendCustomEntry("connection_required", {
@@ -787,11 +861,21 @@ async function runXopcEmbeddedTurnInner(params) {
 				errorMessage: "aborted"
 			};
 			if (isAssistantTurnAborted(session.agent)) return {
-				ok: true,
+				ok: false,
+				retryable: false,
+				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),
 				errorMessage: getAssistantTurnErrorMessage(session.agent) ?? "Assistant turn failed",
 				lastAssistantText: lastAssistantPlainText(session)
 			};

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

@@ -236,7 +236,15 @@ var EmbeddedSessionRunnerPool = class {
 		const settingsManager = createEmbeddedSettingsManager(workspaceDir);
 		const piSm = guardSessionManager(params.transcriptRuntime.openSessionManager(workspaceDir), {
 			conversationId: params.transcriptRuntime.persistent ? runtimeId : void 0,
-			persistCustomTypes: ["codemode-store", TOOL_DISCOVERY_STATE],
+			persistCustomTypes: [
+				"codemode-store",
+				TOOL_DISCOVERY_STATE,
+				"coding_run_started",
+				"coding_verification",
+				"xopc.model-selection",
+				"connection_required",
+				"clarification_required"
+			],
 			contextWindowTokens: model.contextWindow ?? 128e3,
 			transformMessageForPersistence: params.transcriptRuntime.persistent ? (message) => transformUserMessageForPersistence(runtimeId, message) : void 0
 		});

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

@@ -95,12 +95,13 @@ export type RunXopcEmbeddedTurnParams = {
     images?: ImageContent[];
     /** Continue from the persisted trailing user row instead of appending it again. */
     resumeLastUserMessage?: boolean;
+    recoveryMessage?: string;
     verifyChanges?: boolean;
     requireVisibleReply?: boolean;
 };
 export type RunXopcEmbeddedTurnResult = {
     ok: boolean;
-    stopReason?: 'connection_required' | 'clarification_required';
+    stopReason?: 'connection_required' | 'clarification_required' | 'policy_limit' | 'response_truncated';
     /** False for harness failures that must not trigger another model attempt. */
     retryable?: boolean;
     errorMessage?: string;

package/dist/src/agent/external-tools/cliProvider.d.ts

@@ -23,6 +23,7 @@ export declare class CliToolProvider implements ExternalToolProvider {
         title: string;
         summary: string;
         description: string;
+        readOnly: boolean;
         batchRead: boolean;
         inputSchema: {
             properties: {

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

@@ -120,6 +120,7 @@ var CliToolProvider = class {
 			title: action.id,
 			summary: action.description,
 			description: action.description,
+			readOnly: action.scope === "read",
 			batchRead: action.scope === "read",
 			inputSchema: {
 				...action.inputSchema,

package/dist/src/agent/external-tools/composio-provider.js

@@ -232,6 +232,7 @@ var ComposioToolProvider = class {
 			summary,
 			description: `${summary} Available accounts: ${JSON.stringify(accounts)}. Use xopcAccountId to select one; never guess when the user's intent is ambiguous.`,
 			inputSchema: actionInputSchema(action),
+			readOnly: action.scope === "read" && action.curated,
 			batchRead: accounts.length > 0 && action.scope === "read" && action.curated && BATCH_READ_ACTIONS.has(action.actionId)
 		};
 	}
@@ -313,6 +314,7 @@ var ComposioToolProvider = class {
 			confirmed = true;
 		}
 		const authorizeCurrent = () => {
+			context.authorize?.();
 			context.signal?.throwIfAborted();
 			const current = this.availableInstallations();
 			const installation = this.resolve(toolRef, current.installations)?.installation;

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

@@ -10,6 +10,7 @@ import { connectorPrincipalForSession } from "../../connectors/principal.js";
 import { parseExternalToolRef } from "./refs.js";
 import { setXopcToolMetadata } from "../embedded/tool-metadata.js";
 import { getStoreConnectorInstallPlan, parseStoreConnectorCandidateRef, searchStoreConnectorInstallCandidates } from "../../capabilities/store-connector.js";
+import { assertPersonalRequestAccountAccess } from "../../personal-agent/request-access.js";
 import { connectionCandidates, resolveConnectionCandidate } from "../../connectors/connection-candidates.js";
 import { ExternalToolService } from "./service.js";
 import { EXTERNAL_TOOL_SOURCES } from "./types.js";
@@ -143,6 +144,7 @@ function createExternalToolGatewayTools(providers, getContext, getConfig, getExe
 				const connectorId = composio ? getConnectorInstallation(composio.namespace)?.connectorId : cli && config ? listConnectorInstances(config).find((instance) => instance.instanceId === cli.namespace)?.connectorId : void 0;
 				if (connectorId !== request.connectorId) throw new Error("Use only the selected Personal request connector");
 				if (composio && !listConnectorActionMetadata(connectorId).some((action) => action.actionId === composio.toolName && action.scope === "read" && action.curated)) throw new Error("Personal requests permit only curated read operations");
+				assertPersonalRequestAccountAccess(request);
 				const account = getConnectorAccount(request.accountId);
 				const connection = account?.currentConnectionId ? getConnectorConnection(account.currentConnectionId) : void 0;
 				if (!connection || connection.status !== "active" || connection.expiresAt && Date.parse(connection.expiresAt) <= Date.now()) {
@@ -157,11 +159,15 @@ function createExternalToolGatewayTools(providers, getContext, getConfig, getExe
 			}
 			const result = await service.execute({
 				...params,
-				...request ? { readOnly: true } : {},
+				...request ? {
+					readOnly: void 0,
+					personalReadOnly: true
+				} : {},
 				context: {
 					toolCallId,
 					signal,
-					onUpdate
+					onUpdate,
+					...request ? { authorize: () => assertPersonalRequestAccountAccess(request) } : {}
 				}
 			});
 			return {

package/dist/src/agent/external-tools/service.d.ts

@@ -28,6 +28,7 @@ export declare class ExternalToolService {
         arguments?: Record<string, unknown>;
         approvalId?: string;
         readOnly?: boolean;
+        personalReadOnly?: boolean;
         context: ExternalToolExecutionContext;
     }): Promise<import("@earendil-works/pi-agent-core").AgentToolResult<Record<string, unknown>>>;
     private providerForRef;

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

@@ -137,10 +137,11 @@ var ExternalToolService = class {
 		const descriptor = await provider.describe(params.toolRef);
 		if (!descriptor) throw new Error(`External tool is unavailable: ${params.toolRef}`);
 		const current = versionDescriptor(descriptor);
+		if (params.personalReadOnly && current.readOnly !== true && current.batchRead !== true) throw new Error("This external operation has no host-curated read-only contract");
 		if (params.readOnly && current.batchRead !== true) throw new Error("This external operation is not approved for batch reads");
 		if (current.revision !== params.revision) throw new Error(`Tool contract changed. Describe ${params.toolRef} again before executing it.`);
 		const args = params.arguments ?? {};
-		if (params.readOnly && (provider.source === "composio" || provider.source === "cli") && (typeof args.xopcAccountId !== "string" || !args.xopcAccountId)) throw new Error("Batch connector reads require an explicit xopcAccountId");
+		if ((params.readOnly || params.personalReadOnly) && (provider.source === "composio" || provider.source === "cli") && (typeof args.xopcAccountId !== "string" || !args.xopcAccountId)) throw new Error("Batch connector reads require an explicit xopcAccountId");
 		let validate;
 		try {
 			validate = this.ajv.compile(current.inputSchema);
@@ -151,6 +152,7 @@ var ExternalToolService = class {
 			if (!validate(input)) throw new Error(`Arguments do not match ${params.toolRef}: ${this.ajv.errorsText(validate.errors)}`);
 		};
 		validateArguments(args);
+		params.context.authorize?.();
 		return provider.execute(params.toolRef, args, params.approvalId, {
 			...params.context,
 			contractRevision: current.contractRevision,

package/dist/src/agent/external-tools/types.d.ts

@@ -27,6 +27,8 @@ export interface ExternalToolDescriptor extends ExternalToolSearchHit {
     exposure?: import('@earendil-works/pi-coding-agent').ToolExposure;
     /** Host-curated contract; never copied from remote readOnlyHint annotations. */
     batchRead?: boolean;
+    /** Host-curated read scope; separate from eligibility for batch execution. */
+    readOnly?: boolean;
 }
 export interface VersionedExternalToolDescriptor extends ExternalToolDescriptor {
     revision: string;
@@ -36,6 +38,8 @@ export interface ExternalToolExecutionContext {
     signal?: AbortSignal;
     onUpdate?: AgentToolUpdateCallback<Record<string, unknown>>;
     contractRevision?: string;
+    /** Host authorization recheck immediately before remote dispatch. */
+    authorize?: () => void;
     validateArguments?: (args: Record<string, unknown>) => void;
 }
 export interface ExternalToolTurnContext {

package/dist/src/agent/orchestration/agent-turn-policy.d.ts

@@ -8,6 +8,7 @@ export interface AgentTurnPolicy {
     takeContinuationMessage?(): string | undefined;
     /** Recheck limits at dispatch, including requests made by recovery paths. */
     beforeModelRequest?(signal?: AbortSignal): string | undefined;
+    stopReason?(): 'completed' | 'limit';
 }
 export interface AgentTurnPolicyOptions {
     maxTurns?: number;

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

@@ -126,7 +126,8 @@ function createDelegationBudgetPolicy(budget, options, now = Date.now) {
 				const message = continuation;
 				continuation = void 0;
 				return message;
-			}
+			},
+			stopReason: () => !stopReason && options.isComplete?.() ? "completed" : "limit"
 		},
 		addTokens(tokens) {
 			usage.totalTokens += Math.max(0, tokens);

package/dist/src/agent/orchestration/llm-turn-retry.d.ts

@@ -26,6 +26,11 @@ export interface RetryTransientTurnOptions {
     baseDelayMs?: number;
     signal?: AbortSignal;
     conversationId: string;
+    onRetry?: () => void;
+    shouldRetry?: () => boolean;
+    budget?: {
+        continues: number;
+    };
     log: {
         warn: (obj: Record<string, unknown>, msg: string) => void;
     };

package/dist/src/agent/orchestration/llm-turn-retry.js

@@ -1,5 +1,6 @@
 import { isTransientProviderErrorMessage } from "../../providers/model-response.js";
 import { isContextOverflowError } from "./context-overflow.js";
+import { canResumeAfterModelFailure } from "./turn-recovery.js";
 //#region src/agent/orchestration/llm-turn-retry.ts
 function isTransientLlmErrorMessage(message) {
 	return isTransientProviderErrorMessage(message);
@@ -72,9 +73,9 @@ async function waitForRetryDelay(delayMs, signal) {
 */
 async function maybeRetryTurnAfterTransientLlmFailure(agent, options) {
 	const maxContinues = options.maxContinues ?? 2;
-	const baseDelayMs = Math.max(0, options.baseDelayMs ?? 300);
-	let continues = 0;
-	while (continues < maxContinues) {
+	const baseDelayMs = Math.max(0, options.baseDelayMs ?? 1e3);
+	const budget = options.budget ?? { continues: 0 };
+	while (budget.continues < maxContinues && options.shouldRetry?.() !== false) {
 		const last = getLastAssistantMessage(agent.state.messages);
 		if (!last) return;
 		if (last.stopReason !== "error") return;
@@ -88,8 +89,15 @@ async function maybeRetryTurnAfterTransientLlmFailure(agent, options) {
 			}, "Assistant turn ended with error (not retrying as transient)");
 			return;
 		}
-		continues += 1;
-		const retryDelayMs = baseDelayMs * 2 ** (continues - 1);
+		if (!canResumeAfterModelFailure(agent.state.messages)) {
+			options.log.warn({ conversationId: options.conversationId }, "Model recovery stopped because a tool outcome is unconfirmed");
+			return;
+		}
+		const continues = ++budget.continues;
+		const rateLimited = /429|rate.limit|too many requests/i.test(errMsg);
+		const serverDelay = /retry[- ]after\s*[:=]?\s*(\d+(?:\.\d+)?)\s*(ms|s|seconds)?/i.exec(errMsg);
+		const requestedDelay = serverDelay ? Number(serverDelay[1]) * (serverDelay[2] === "ms" ? 1 : 1e3) : 0;
+		const retryDelayMs = Math.min(6e4, Math.max(requestedDelay, (rateLimited && options.baseDelayMs === void 0 ? 5e3 : baseDelayMs) * 2 ** (continues - 1)));
 		options.log.warn({
 			conversationId: options.conversationId,
 			errorMessage: errMsg,
@@ -99,6 +107,8 @@ async function maybeRetryTurnAfterTransientLlmFailure(agent, options) {
 			retryDelayMs
 		}, "LLM request failed with a transient network error; retrying the same turn. If this persists, check outbound HTTPS to the provider API and HTTP(S)_PROXY.");
 		await waitForRetryDelay(retryDelayMs, options.signal);
+		options.signal?.throwIfAborted();
+		options.onRetry?.();
 		const trimmed = stripTrailingErrorAssistantMessages(agent.state.messages);
 		agent.state.messages = trimmed;
 		await agent.continue();

package/dist/src/agent/orchestration/turn-recovery.d.ts

@@ -0,0 +1,6 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+/** A model request can be resumed only after every issued tool has a confirmed result. */
+export declare function canResumeAfterModelFailure(rows: readonly unknown[]): boolean;
+export declare function recoveryToolKey(name: string, args: unknown): string;
+/** Prevent a recovering model from replaying an already confirmed operation with a new call ID. */
+export declare function completedRecoveryToolResult(messages: readonly AgentMessage[], name: string, args: unknown): string | undefined;

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

@@ -0,0 +1,29 @@
+//#region src/agent/orchestration/turn-recovery.ts
+/** A model request can be resumed only after every issued tool has a confirmed result. */
+function canResumeAfterModelFailure(rows) {
+	const messages = rows.filter((row) => !!row && typeof row === "object");
+	const pending = /* @__PURE__ */ new Set();
+	for (const message of messages.slice(Math.max(0, messages.findLastIndex((item) => item.role === "user")))) if (message.role === "assistant") {
+		if (message.stopReason === "aborted") return false;
+		if (message.stopReason === "error") continue;
+		for (const block of Array.isArray(message.content) ? message.content : []) if (block?.type === "toolCall" && typeof block.id === "string") pending.add(block.id);
+	} else if (message.role === "toolResult") {
+		const recordedReplay = Array.isArray(message.content) && message.content.some((block) => block?.type === "text" && typeof block.text === "string" && block.text.startsWith("This operation already completed before recovery."));
+		if (message.isError && !recordedReplay) return false;
+		if (typeof message.toolCallId === "string") pending.delete(message.toolCallId);
+	}
+	return pending.size === 0;
+}
+function recoveryToolKey(name, args) {
+	return JSON.stringify([name, args], (_key, value) => value && typeof value === "object" && !Array.isArray(value) ? Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b))) : value);
+}
+/** Prevent a recovering model from replaying an already confirmed operation with a new call ID. */
+function completedRecoveryToolResult(messages, name, args) {
+	const calls = /* @__PURE__ */ new Map();
+	const key = recoveryToolKey(name, args);
+	for (const message of messages.slice(Math.max(0, messages.findLastIndex((item) => item.role === "user")))) if (message.role === "assistant" && message.stopReason !== "error" && message.stopReason !== "aborted") {
+		for (const block of message.content) if (block.type === "toolCall") calls.set(block.id, recoveryToolKey(block.name, block.arguments));
+	} else if (message.role === "toolResult" && !message.isError && calls.get(message.toolCallId) === key) return `This operation already completed before recovery. Do not execute it again. Use its recorded result and continue the remaining work:\n${JSON.stringify(message.content).slice(0, 8e3)}`;
+}
+//#endregion
+export { canResumeAfterModelFailure, completedRecoveryToolResult, recoveryToolKey };