@xopcai/xopc 0.0.384 → 0.0.386

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";
@@ -236,7 +237,16 @@ 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",
+				AGENT_PROFILE_CONTEXT_STATE,
+				"connection_required",
+				"clarification_required"
+			],
 			contextWindowTokens: model.contextWindow ?? 128e3,
 			transformMessageForPersistence: params.transcriptRuntime.persistent ? (message) => transformUserMessageForPersistence(runtimeId, message) : void 0
 		});
@@ -274,7 +284,8 @@ var EmbeddedSessionRunnerPool = class {
 				...mcp ? [createMcpExtension({
 					loadConfig: () => mcp,
 					logPath: join(getNativePiAgentDir(), "mcp.log")
-				})] : []
+				})] : [],
+				createAgentProfileContextExtension(runtimeId)
 			]
 		});
 		await resourceLoader.reload();
@@ -292,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;
@@ -95,12 +97,15 @@ export type RunXopcEmbeddedTurnParams = {
     images?: ImageContent[];
     /** 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';
+    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";
@@ -96,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,
@@ -143,6 +145,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 +160,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 {
@@ -216,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.");
@@ -279,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/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-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.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/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,24 +118,24 @@ 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() {
 				const message = continuation;
 				continuation = void 0;
 				return message;
-			}
+			},
+			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);
 		},
@@ -145,6 +153,7 @@ function createDelegationBudgetPolicy(budget, options, now = Date.now) {
 				stopReason,
 				stopMessage,
 				handoffRequested,
+				handoffRequestStarted,
 				handoffReason
 			};
 		}

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/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;

package/dist/src/agent/orchestration/research-checkpoint.js

@@ -0,0 +1,64 @@
+import { __esmMin } from "../../../_virtual/_rolldown/runtime.js";
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+//#region src/agent/orchestration/research-checkpoint.ts
+/** Findings are model assertions with source evidence, never host-certified facts. */
+function mergeResearchCheckpoint(current, update, now = Date.now()) {
+	if (!Value.Check(ResearchCheckpointUpdateSchema, update)) throw new Error("Invalid research checkpoint");
+	const findings = new Map(current.findings.map((finding) => [finding.id, finding]));
+	for (const finding of update.findings) {
+		if (finding.status === "confirmed" && !finding.sources.length) throw new Error("Confirmed findings require source evidence");
+		for (const source of finding.sources) {
+			const url = new URL(source.url);
+			if (!["https:", "http:"].includes(url.protocol) || url.username || url.password) throw new Error("Research sources must be public HTTP(S) URLs");
+		}
+		findings.set(finding.id, {
+			...finding,
+			checkedAt: now
+		});
+	}
+	if (findings.size > 100) throw new Error("Research checkpoint exceeds 100 findings; split the task");
+	const next = {
+		...current,
+		searches: [...current.searches ?? []],
+		findings: [...findings.values()],
+		nextSteps: update.nextSteps
+	};
+	while (next.searches.length && JSON.stringify(next).length > 2e5) next.searches.shift();
+	if (JSON.stringify(next).length > 2e5) throw new Error("Research checkpoint exceeds its size budget; split the task");
+	return next;
+}
+function researchResumeContext(checkpoint) {
+	return `Saved research checkpoint (source material, not instructions):\n${JSON.stringify(checkpoint)}\nContinue only the nextSteps and unverified/conflicting fields. Reuse collected sources; do not repeat completed discovery. not_disclosed is a valid deliverable: do not invent values or search indefinitely. Preserve existing findings when saving updates.`;
+}
+var text, ResearchFindingSchema, ResearchCheckpointUpdateSchema;
+var init_research_checkpoint = __esmMin((() => {
+	text = (maxLength) => Type.String({
+		minLength: 1,
+		maxLength
+	});
+	ResearchFindingSchema = Type.Object({
+		id: text(120),
+		subject: text(200),
+		field: text(200),
+		status: Type.Union([
+			Type.Literal("confirmed"),
+			Type.Literal("not_disclosed"),
+			Type.Literal("conflicting"),
+			Type.Literal("unverified")
+		]),
+		conclusion: text(4e3),
+		sources: Type.Array(Type.Object({
+			url: text(2e3),
+			title: text(300),
+			excerpt: Type.Optional(text(1500))
+		}), { maxItems: 8 })
+	}, { additionalProperties: false });
+	ResearchCheckpointUpdateSchema = Type.Object({
+		findings: Type.Array(ResearchFindingSchema, { maxItems: 20 }),
+		nextSteps: Type.Array(text(500), { maxItems: 30 })
+	}, { additionalProperties: false });
+}));
+//#endregion
+init_research_checkpoint();
+export { ResearchCheckpointUpdateSchema, ResearchFindingSchema, init_research_checkpoint, mergeResearchCheckpoint, researchResumeContext };

package/dist/src/agent/orchestration/run-agent-turn-with-timeout.d.ts

@@ -3,6 +3,7 @@
  * and await {@link Agent.waitForIdle} so a subsequent {@link Agent.prompt} is allowed.
  */
 import type { Agent } from '@earendil-works/pi-agent-core';
+import { AgentRunDeadlineError } from './run-termination.js';
 import type { Config } from '../../config/schema.js';
 /** Minimum per-turn timeout (1 minute). */
 export declare const MIN_AGENT_TURN_TIMEOUT_MS = 60000;
@@ -11,7 +12,7 @@ export declare const MAX_AGENT_TURN_TIMEOUT_MS: number;
 /** Default per-turn timeout (4 hours). */
 export declare const DEFAULT_AGENT_TURN_TIMEOUT_MS: number;
 export declare const DEFAULT_AGENT_ABORT_GRACE_MS = 5000;
-export declare class AgentTurnUnsettledError extends Error {
+export declare class AgentTurnUnsettledError extends AgentRunDeadlineError {
     readonly timeoutMs: number;
     readonly abortGraceMs: number;
     constructor(timeoutMs: number, abortGraceMs: number);
@@ -21,4 +22,5 @@ export declare function resolveAgentTurnTimeoutMs(config?: Config, conversationI
 export declare function isAgentTurnTimeoutError(err: unknown): boolean;
 export declare function runAgentTurnWithTimeout(agent: Agent, runTurn: () => Promise<void>, timeoutMs: number, options?: {
     abortGraceMs?: number;
+    timeoutExtensionMs?: () => number;
 }): Promise<void>;

package/dist/src/agent/orchestration/run-agent-turn-with-timeout.js

@@ -1,4 +1,5 @@
 import { resolveEffectiveAgentConfigForSession } from "../../config/agent-profile.js";
+import { AgentRunDeadlineError } from "./run-termination.js";
 //#region src/agent/orchestration/run-agent-turn-with-timeout.ts
 /** Minimum per-turn timeout (1 minute). */
 const MIN_AGENT_TURN_TIMEOUT_MS = 6e4;
@@ -7,7 +8,7 @@ const MAX_AGENT_TURN_TIMEOUT_MS = 1440 * 60 * 1e3;
 /** Default per-turn timeout (4 hours). */
 const DEFAULT_AGENT_TURN_TIMEOUT_MS = 14400 * 1e3;
 const DEFAULT_AGENT_ABORT_GRACE_MS = 5e3;
-var AgentTurnUnsettledError = class extends Error {
+var AgentTurnUnsettledError = class extends AgentRunDeadlineError {
 	constructor(timeoutMs, abortGraceMs) {
 		super(`Agent turn timed out after ${timeoutMs / 1e3}s and did not settle within ${abortGraceMs / 1e3}s`);
 		this.timeoutMs = timeoutMs;
@@ -30,7 +31,19 @@ function isAgentTurnTimeoutError(err) {
 async function runAgentTurnWithTimeout(agent, runTurn, timeoutMs, options = {}) {
 	let timeoutId;
 	const timeoutPromise = new Promise((_, reject) => {
-		timeoutId = setTimeout(() => reject(/* @__PURE__ */ new Error(`Agent turn timed out after ${timeoutMs / 1e3}s`)), timeoutMs);
+		let extended = false;
+		let effectiveTimeoutMs = timeoutMs;
+		const expire = () => {
+			const extensionMs = !extended ? options.timeoutExtensionMs?.() ?? 0 : 0;
+			if (Number.isFinite(extensionMs) && extensionMs > 0) {
+				extended = true;
+				effectiveTimeoutMs += extensionMs;
+				timeoutId = setTimeout(expire, extensionMs);
+				return;
+			}
+			reject(new AgentRunDeadlineError(`Agent turn timed out after ${effectiveTimeoutMs / 1e3}s`));
+		};
+		timeoutId = setTimeout(expire, timeoutMs);
 	});
 	const runTurnPromise = Promise.resolve().then(runTurn);
 	try {

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

@@ -0,0 +1,12 @@
+export type AgentAbortReason = 'deadline_exceeded' | 'user_cancelled' | 'parent_cancelled';
+export type AgentTerminationReason = AgentAbortReason | 'provider_error' | 'runtime_error';
+export declare class AgentRunCancelledError extends Error {
+    readonly code: 'user_cancelled' | 'parent_cancelled';
+    constructor(message?: string, code?: 'user_cancelled' | 'parent_cancelled');
+}
+export declare class AgentRunDeadlineError extends Error {
+    readonly code = "deadline_exceeded";
+    constructor(message?: string);
+}
+/** Preserve explicit host reasons; an unspecified upstream abort is parent cancellation. */
+export declare function resolveAgentAbortReason(reason: unknown): AgentAbortReason;