@xopcai/xopc 0.0.385 → 0.0.387

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/embedded/xopc-tools-bridge.js

@@ -1,5 +1,6 @@
 import { getXopcToolMetadata } from "./tool-metadata.js";
 import { withDataToolPermissions } from "../tools/dataBatch.js";
+import { recordPersonalPerformance } from "../../personal-agent/performance.js";
 //#region src/agent/embedded/xopc-tools-bridge.ts
 const APPLY_PATCH_BEGIN_MARKER = "*** Begin Patch";
 const APPLY_PATCH_END_MARKER = "*** End Patch";
@@ -49,7 +50,7 @@ function validateApplyPatchEnvelope(params) {
 		expected: APPLY_PATCH_BEGIN_MARKER,
 		retryHint: "Pass a patch string beginning with the exact marker `*** Begin Patch`."
 	};
-	const lines = patch.split(/\r?\n/);
+	const lines = patch.replace(/[\r\n]+$/, "").split(/\r?\n/);
 	const firstLine = lines[0] ?? "";
 	if (firstLine !== APPLY_PATCH_BEGIN_MARKER) return {
 		code: "invalid_patch_envelope",
@@ -111,7 +112,17 @@ function xopcToolsToDefinitions(tools) {
 			async execute(toolCallId, params, signal, onUpdate) {
 				if (tool.name === "apply_patch") {
 					const envelopeError = validateApplyPatchEnvelope(params);
-					if (envelopeError) return invalidApplyPatchEnvelopeResult(envelopeError);
+					if (envelopeError) {
+						recordPersonalPerformance({
+							phase: "tool",
+							tool: tool.name,
+							toolCallId,
+							durationMs: 0,
+							status: "error",
+							errorCode: "patch_envelope"
+						});
+						return invalidApplyPatchEnvelopeResult(envelopeError);
+					}
 				}
 				return withDataToolPermissions(new Set(tools.map((item) => item.name)), () => tool.execute(toolCallId, params, signal, onUpdate));
 			}

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

@@ -5,6 +5,7 @@ import { getConnectorAccount, init_connector_account_repository } from "../../st
 import { appendConnectorExecutionAudit, consumeConnectorApproval, createConnectorApproval, getConnectorApproval, getConnectorConnection, getConnectorInstallation, init_connector_repository } from "../../storage/sqlite/connector-repository.js";
 import { connectorObjectiveScope, init_connection_wait_repository, publishConnectionWait, requireSessionConnection } from "../../storage/sqlite/connection-wait-repository.js";
 import { init_sqlite } from "../../storage/sqlite/index.js";
+import { connectorPrincipalForSession } from "../../connectors/principal.js";
 import { CapabilityError } from "../../capabilities/runtime/errors.js";
 import { ExternalEffectNotAppliedError, executeExternalOperation } from "../../capabilities/runtime/external-operations.js";
 import "../../capabilities/runtime/dispatcher.js";
@@ -17,7 +18,6 @@ import { evaluateConnectorExecutionPolicy } from "../../connectors/policy.js";
 import { listConnectorInstances } from "../../connectors/instances.js";
 import { cliOwnerId, recoverCliExecutions } from "../../connectors/cli/store.js";
 import { describeCliAction, executeCliAction } from "../../connectors/cli/runtime.js";
-import { connectorPrincipalForSession } from "../../connectors/principal.js";
 import { externalToolRef, parseExternalToolRef } from "./refs.js";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";

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

@@ -5,17 +5,17 @@ import { getConnectorAccount } from "../../storage/sqlite/connector-account-repo
 import { consumeConnectorApproval, createConnectorApproval, getConnectorApproval, getConnectorConnection, getConnectorInstallation, listConnectorActionMetadata, listConnectorConnections, listConnectorInstallations, upsertConnectorActionMetadata, upsertConnectorInstallation } from "../../storage/sqlite/connector-repository.js";
 import { bindObjectiveAccount, connectionBinding, connectionBindings, connectorObjectiveScope, init_connection_wait_repository, publishConnectionWait, requireSessionConnection } from "../../storage/sqlite/connection-wait-repository.js";
 import { init_sqlite } from "../../storage/sqlite/index.js";
+import { canAccessConnectorAccount, currentAccountConnections } from "../../connectors/account-access.js";
+import { connectorPrincipalForSession } from "../../connectors/principal.js";
 import { CapabilityError } from "../../capabilities/runtime/errors.js";
 import { ExternalEffectNotAppliedError, executeExternalOperation } from "../../capabilities/runtime/external-operations.js";
 import { connectorArgumentsHash, connectorArgumentsPreview } from "../../connectors/approval.js";
-import { canAccessConnectorAccount, currentAccountConnections } from "../../connectors/account-access.js";
 import { connectorIdentitySummary } from "../../connectors/connector-identity.js";
 import { evaluateConnectorExecutionPolicy } from "../../connectors/policy.js";
 import { ComposioSessionsAdapter } from "../../connectors/composio-sessions.js";
 import { getComposioToolkitScope, getConfiguredComposioAuthConfigs, isComposioActionAllowedByCatalog, scopeForComposioAction } from "../../connectors/composio.js";
 import { getConnectorDefinition } from "../../connectors/catalog.js";
 import { listConnectorInstances } from "../../connectors/instances.js";
-import { connectorPrincipalForSession } from "../../connectors/principal.js";
 import { externalToolRef, parseExternalToolRef } from "./refs.js";
 import { isToolInputSchema } from "../../connectors/connection-capabilities.js";
 import { ExternalToolSearchError } from "./search-error.js";

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

@@ -1,7 +1,7 @@
-import { ExternalEffectNotAppliedError, executeExternalOperation } from "../../capabilities/runtime/external-operations.js";
-import { canonicalCapabilityJson } from "../../capabilities/runtime/dispatcher.js";
 import { init_src } from "../../../packages/computer-control-contract/src/index.js";
 import "../../../packages/browser-control-contract/src/index.js";
+import { ExternalEffectNotAppliedError, executeExternalOperation } from "../../capabilities/runtime/external-operations.js";
+import { canonicalCapabilityJson } from "../../capabilities/runtime/dispatcher.js";
 import { externalToolRef, parseExternalToolRef } from "./refs.js";
 import { extractDocumentText } from "../../document-understanding/extract.js";
 import { prepareImageForModel } from "../image/prepare-image-for-model.js";

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

@@ -5,8 +5,8 @@ import { getConnectorConnection, getConnectorInstallation, init_connector_reposi
 import { connectionBindings, getActiveConnectionWait, init_connection_wait_repository, publishConnectionWait, requireSessionConnection, reviseCurrentConnectionObjective } from "../../storage/sqlite/connection-wait-repository.js";
 import { getSessionMetadata } from "../../storage/sqlite/session-read-repository.js";
 import { init_session_repository } from "../../storage/sqlite/session-repository.js";
-import { listConnectorInstances } from "../../connectors/instances.js";
 import { connectorPrincipalForSession } from "../../connectors/principal.js";
+import { listConnectorInstances } from "../../connectors/instances.js";
 import { parseExternalToolRef } from "./refs.js";
 import { setXopcToolMetadata } from "../embedded/tool-metadata.js";
 import { getStoreConnectorInstallPlan, parseStoreConnectorCandidateRef, searchStoreConnectorInstallCandidates } from "../../capabilities/store-connector.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/inbound/attachment-pipeline.js

@@ -3,9 +3,9 @@ import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { extractProfileAgentId } from "../../config/agent-profile.js";
 import { readAgentMessageContent } from "../memory/agent-message-access.js";
 import { isPersonalConversation } from "../../personal-agent/repository.js";
-import { MODEL_IMAGE_MAX_BYTES, MODEL_IMAGE_SOURCE_MAX_BYTES, prepareImageForModel } from "../image/prepare-image-for-model.js";
 import { mimeTypeFromMediaPath } from "../../media/store.js";
 import { readMediaReference } from "../../media/media-reference.js";
+import { MODEL_IMAGE_MAX_BYTES, MODEL_IMAGE_SOURCE_MAX_BYTES, prepareImageForModel } from "../image/prepare-image-for-model.js";
 import { isImageInboundAttachment } from "../../channels/attachments/attachment-classifiers.js";
 import "../../channels/attachments/inbound-persist.js";
 import { expandAtFileMentionsInPlainText } from "../context/expand-at-file-mentions.js";

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;

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;