@xopcai/xopc 0.0.312 → 0.0.314

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

@@ -5,6 +5,9 @@ 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 "../../storage/sqlite/index.js";
+import { CapabilityError } from "../../capabilities/runtime/errors.js";
+import { ExternalEffectNotAppliedError, executeExternalOperation } from "../../capabilities/runtime/external-operations.js";
+import "../../capabilities/runtime/dispatcher.js";
 import { connectorArgumentsHash, connectorArgumentsPreview } from "../../connectors/approval.js";
 import { selectConnectorAccount } from "../../connectors/account-selection.js";
 import { cliContextPath } from "../../connectors/cli/process.js";
@@ -163,15 +166,18 @@ var CliToolProvider = class {
 		validateActionInput(action, input);
 		const scopes = Array.isArray(connection.metadata.scopes) ? connection.metadata.scopes : [];
 		if (action.requiredScopes.some((scope) => !scopes.includes(scope))) throw new Error("CLI account is missing required scopes. Reauthorize this account.");
+		const descriptorDigest = connectorArgumentsHash({
+			action,
+			adapterVersion: item.adapter.version,
+			binaryVersion: item.adapter.binaryVersion
+		});
 		const argumentsHash = () => connectorArgumentsHash({
 			args: input,
 			exportResult,
 			instanceId: item.instance.instanceId,
 			accountId: connection.accountId,
 			connectionId: connection.id,
-			actionRevision: action.revision,
-			binaryVersion: item.adapter.binaryVersion,
-			adapterVersion: item.adapter.version,
+			descriptorDigest,
 			principalId: item.principal.principalId,
 			agentId: item.agentId,
 			conversationId,
@@ -230,87 +236,129 @@ var CliToolProvider = class {
 				instruction: "Approve this exact action in xopc, then retry with unchanged arguments and approvalId."
 			});
 		}
-		const executionId = randomUUID();
-		let authorized = false;
-		const beforeExecute = () => {
-			runSqliteWriteTransaction((db) => {
-				const hash = argumentsHash();
-				const freshPolicy = getConnectorInstallation(item.policy.id);
-				const freshConnection = getConnectorConnection(connection.id);
-				if (!freshPolicy || freshConnection?.status !== "active" || getConnectorAccount(connection.accountId)?.currentConnectionId !== connection.id || !selectConnectorAccount({
-					installation: freshPolicy,
-					agentId: item.agentId,
-					conversationId,
-					requestedAccountId: connection.accountId
-				}).connection || evaluateConnectorExecutionPolicy({
-					installation: freshPolicy,
-					action: {
-						scope: action.scope,
-						curated: true
-					},
-					accountId: connection.accountId,
-					agentId: item.agentId,
-					confirmed: Boolean(approvalId)
-				}).decision !== "allowed") throw new Error("Connector permission changed.");
-				if (approvalId) {
-					const approval = getConnectorApproval(approvalId);
-					if (!approval || approval.argumentsHash !== hash || !consumeConnectorApproval(approvalId, hash)) throw new Error("Approval is invalid, expired or already consumed.");
+		if (approvalId) {
+			const approval = getConnectorApproval(approvalId);
+			if (!approval || approval.argumentsHash !== argumentsHash() || !["approved", "consumed"].includes(approval.status) || approval.status === "approved" && Date.parse(approval.expiresAt) <= Date.now()) return result({
+				outcome: "failed",
+				error: {
+					kind: "approval",
+					message: "Approval is invalid, expired or belongs to a different operation."
 				}
-				db.prepare(`INSERT INTO connector_cli_executions (id,instance_id,account_id,connection_id,action_id,revision,arguments_hash,status,owner_id,started_at)
-          VALUES (?,?,?,?,?,?,?,'running',?,?)`).run(executionId, item.instance.instanceId, connection.accountId, connection.id, action.id, action.revision, hash, cliOwnerId, Date.now());
 			});
-			authorized = true;
+		}
+		const acceptedArgumentsHash = argumentsHash();
+		const authorizeCurrent = () => {
+			const freshPolicy = getConnectorInstallation(item.policy.id);
+			const freshConnection = getConnectorConnection(connection.id);
+			const currentConfig = this.deps.getConfig();
+			const enabled = currentConfig && listConnectorInstances(currentConfig).some((instance) => instance.instanceId === item.instance.instanceId && instance.enabled && instance.materialized.type === "cli");
+			const currentScopes = Array.isArray(freshConnection?.metadata.scopes) ? freshConnection.metadata.scopes : [];
+			if (!enabled || !freshPolicy || freshConnection?.status !== "active" || getConnectorAccount(connection.accountId)?.currentConnectionId !== connection.id || action.requiredScopes.some((scope) => !currentScopes.includes(scope)) || action.anyScopes?.length && !action.anyScopes.some((scope) => currentScopes.includes(scope)) || !selectConnectorAccount({
+				installation: freshPolicy,
+				agentId: item.agentId,
+				conversationId,
+				requestedAccountId: connection.accountId
+			}).connection || evaluateConnectorExecutionPolicy({
+				installation: freshPolicy,
+				action: {
+					scope: action.scope,
+					curated: true
+				},
+				accountId: connection.accountId,
+				agentId: item.agentId,
+				confirmed: Boolean(approvalId)
+			}).decision !== "allowed") throw new CapabilityError("FORBIDDEN", "Connector permission changed.");
+			if (argumentsHash() !== acceptedArgumentsHash) throw new CapabilityError("REVISION_CONFLICT", "Connector objective changed.");
 		};
-		const started = Date.now();
-		let output;
-		try {
-			output = await executeCliAction(item.config, item.instance.instanceId, connection, action, input, context.signal, beforeExecute);
-		} catch (error) {
-			output = {
-				outcome: authorized && action.scope !== "read" ? "unknown" : "failed",
-				error: {
-					kind: "runtime",
-					message: error instanceof Error ? error.message : "CLI failed."
-				}
+		const execute = async (executionId) => {
+			let authorized = false;
+			const beforeExecute = () => {
+				runSqliteWriteTransaction((db) => {
+					const hash = argumentsHash();
+					authorizeCurrent();
+					if (approvalId) {
+						const approval = getConnectorApproval(approvalId);
+						if (!approval || approval.argumentsHash !== hash || !consumeConnectorApproval(approvalId, hash)) throw new Error("Approval is invalid, expired or already consumed.");
+					}
+					db.prepare(`INSERT INTO connector_cli_executions (id,instance_id,account_id,connection_id,action_id,revision,arguments_hash,status,owner_id,started_at)
+            VALUES (?,?,?,?,?,?,?,'running',?,?)`).run(executionId, item.instance.instanceId, connection.accountId, connection.id, action.id, action.revision, hash, cliOwnerId, Date.now());
+				});
+				authorized = true;
 			};
-		}
-		getSqliteDatabase().prepare("UPDATE connector_cli_executions SET status = ?, error_kind = ?, finished_at = ? WHERE id = ?").run(output.outcome, output.error?.kind ?? null, Date.now(), executionId);
-		appendConnectorExecutionAudit({
-			installationId: item.policy.id,
-			connectionId: connection.id,
-			connectorId: item.instance.connectorId,
-			principalId: item.principal.principalId,
-			agentId: item.agentId,
-			conversationId,
-			actionId: action.id,
-			scope: action.scope,
-			decision: authorized ? "allowed" : "denied",
-			resultStatus: output.outcome === "success" ? "success" : "error",
-			errorCode: output.outcome === "unknown" ? "outcome_unknown" : output.error?.kind,
-			durationMs: Date.now() - started
-		});
-		let artifact;
-		if (exportResult && output.outcome === "success") try {
-			await writeFile(join(cliContextPath(String(connection.metadata.contextId)), "files", `${executionId}.json`), JSON.stringify(output.data ?? null, null, 2), {
-				mode: 384,
-				flag: "wx"
+			const started = Date.now();
+			let output;
+			try {
+				output = await executeCliAction(item.config, item.instance.instanceId, connection, action, input, context.signal, beforeExecute);
+			} catch (error) {
+				output = {
+					outcome: authorized && action.scope !== "read" ? "unknown" : "failed",
+					error: {
+						kind: "runtime",
+						message: error instanceof Error ? error.message : "CLI failed."
+					}
+				};
+			}
+			if (authorized && action.scope !== "read" && output.outcome === "failed" && output.error?.kind !== "startup") output = {
+				...output,
+				outcome: "unknown"
+			};
+			getSqliteDatabase().prepare("UPDATE connector_cli_executions SET status = ?, error_kind = ?, finished_at = ? WHERE id = ?").run(output.outcome, output.error?.kind ?? null, Date.now(), executionId);
+			appendConnectorExecutionAudit({
+				installationId: item.policy.id,
+				connectionId: connection.id,
+				connectorId: item.instance.connectorId,
+				principalId: item.principal.principalId,
+				agentId: item.agentId,
+				conversationId,
+				actionId: action.id,
+				scope: action.scope,
+				decision: authorized ? "allowed" : "denied",
+				resultStatus: output.outcome === "success" ? "success" : "error",
+				errorCode: output.outcome === "unknown" ? "outcome_unknown" : output.error?.kind,
+				durationMs: Date.now() - started
 			});
-			artifact = `/api/connectors/executions/${executionId}/artifact`;
-		} catch {
+			if (action.scope !== "read" && output.outcome !== "success") {
+				if (!authorized || output.error?.kind === "startup") throw new ExternalEffectNotAppliedError(output.error?.message ?? "CLI execution was rejected before spawning");
+				throw new Error(output.error?.message ?? "CLI write outcome could not be confirmed");
+			}
+			let artifact;
+			if (exportResult && output.outcome === "success") try {
+				await writeFile(join(cliContextPath(String(connection.metadata.contextId)), "files", `${executionId}.json`), JSON.stringify(output.data ?? null, null, 2), {
+					mode: 384,
+					flag: "wx"
+				});
+				artifact = `/api/connectors/executions/${executionId}/artifact`;
+			} catch {
+				return result({
+					executionId,
+					accountId: connection.accountId,
+					...output,
+					artifactError: "The action succeeded, but its JSON export could not be saved. Do not repeat the action to retry export."
+				});
+			}
 			return result({
-				executionId,
+				...authorized ? { executionId } : {},
+				artifact,
 				accountId: connection.accountId,
 				...output,
-				artifactError: "The action succeeded, but its JSON export could not be saved. Do not repeat the action to retry export."
+				...output.outcome === "unknown" ? { instruction: "The write may have succeeded. Inspect the provider using a read action; do not retry automatically." } : {}
 			});
-		}
-		return result({
-			...authorized ? { executionId } : {},
-			artifact,
-			accountId: connection.accountId,
-			...output,
-			...output.outcome === "unknown" ? { instruction: "The write may have succeeded. Inspect the provider using a read action; do not retry automatically." } : {}
-		});
+		};
+		context.signal?.throwIfAborted();
+		authorizeCurrent();
+		if (action.scope === "read") return execute(randomUUID());
+		return executeExternalOperation({
+			principalId: item.principal.principalId,
+			capabilityId: toolRef,
+			idempotencyKey: connectorArgumentsHash(approvalId ? { approvalId } : {
+				conversationId,
+				toolCallId: context.toolCallId
+			}),
+			requestDigest: acceptedArgumentsHash,
+			descriptorDigest,
+			surface: "agent",
+			recovery: "manual"
+		}, execute);
 	}
 };
 //#endregion

package/dist/src/agent/external-tools/composio-provider.d.ts

@@ -23,7 +23,7 @@ export declare class ComposioToolProvider implements ExternalToolProvider {
     constructor(deps: ComposioToolProviderDeps);
     search(query: string): Promise<ExternalToolSearchHit[]>;
     describe(toolRef: string): Promise<ExternalToolDescriptor | undefined>;
-    execute(toolRef: string, args: Record<string, unknown>, approvalId: string | undefined, _context: ExternalToolExecutionContext): Promise<AgentToolResult<Record<string, unknown>>>;
+    execute(toolRef: string, args: Record<string, unknown>, approvalId: string | undefined, context: ExternalToolExecutionContext): Promise<AgentToolResult<Record<string, unknown>>>;
     private availableInstallations;
     private resolve;
 }

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

@@ -5,9 +5,12 @@ 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 "../../storage/sqlite/index.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";
@@ -41,6 +44,10 @@ function textResult(value) {
 		details: {}
 	};
 }
+function actionDigest(action) {
+	const { cachedAt: _cachedAt, ...contract } = action;
+	return connectorArgumentsHash(contract);
+}
 function installedConfigToolkits(config) {
 	return Object.values(config?.connectors?.instances ?? {}).flatMap((record) => {
 		if (!record || typeof record !== "object" || Array.isArray(record)) return [];
@@ -227,7 +234,7 @@ var ComposioToolProvider = class {
 			batchRead: accounts.length > 0 && action.scope === "read" && action.curated && BATCH_READ_ACTIONS.has(action.actionId)
 		};
 	}
-	async execute(toolRef, args, approvalId, _context) {
+	async execute(toolRef, args, approvalId, context) {
 		const available = this.availableInstallations();
 		const resolved = this.resolve(toolRef, available.installations);
 		if (!resolved) return textResult("This connected app tool is not allowed for this user and agent.");
@@ -283,21 +290,47 @@ var ComposioToolProvider = class {
 		if (available.context && connection.accountId) bindObjectiveAccount(available.context.conversationId, resolved.installation.connectorId, connection.accountId);
 		const actionArgs = { ...executionArgs };
 		delete actionArgs[CONNECTION_ARGUMENT];
-		const argsHash = connectorArgumentsHash({
+		const descriptorDigest = actionDigest(action);
+		const argumentIdentity = () => connectorArgumentsHash({
 			args: actionArgs,
 			accountId: connection.accountId,
+			connectionId: connection.id,
+			descriptorDigest,
+			principalId: available.principalId,
+			agentId: available.agentId,
+			conversationId: available.context?.conversationId,
 			objective: available.context ? connectorObjectiveScope(available.context.conversationId) : void 0
 		});
+		const argsHash = argumentIdentity();
 		let confirmed = false;
 		if (approvalId) {
 			const pending = getConnectorApproval(approvalId);
-			if (!pending || pending.principalId !== available.principalId || pending.connectorId !== resolved.installation.connectorId || pending.actionId !== action.actionId || pending.conversationId !== available.context?.conversationId || pending.agentId !== available.agentId || !pending.connectionId || getConnectorConnection(pending.connectionId)?.accountId !== connection.accountId) return textResult("The connector approval is invalid for this session or action.");
-			confirmed = Boolean(consumeConnectorApproval(approvalId, argsHash));
-			if (!confirmed) return textResult("The connector approval is not approved, has expired, or was already used.");
+			if (!pending || pending.principalId !== available.principalId || pending.connectorId !== resolved.installation.connectorId || pending.actionId !== action.actionId || pending.conversationId !== available.context?.conversationId || pending.agentId !== available.agentId || pending.connectionId !== connection.id || pending.argumentsHash !== argsHash || !["approved", "consumed"].includes(pending.status) || pending.status === "approved" && Date.parse(pending.expiresAt) <= Date.now()) return textResult("The connector approval is invalid for this session or action.");
+			confirmed = true;
 		}
+		const authorizeCurrent = () => {
+			context.signal?.throwIfAborted();
+			const current = this.availableInstallations();
+			const installation = this.resolve(toolRef, current.installations)?.installation;
+			const active = getConnectorConnection(connection.id);
+			const contract = listConnectorActionMetadata(resolved.installation.connectorId).find((item) => item.actionId === action.actionId);
+			if (!installation || current.principalId !== available.principalId || current.agentId !== available.agentId || current.context?.conversationId !== available.context?.conversationId || !active || active.status !== "active" || active.accountId !== connection.accountId || active.providerConnectionId !== connection.providerConnectionId || getConnectorAccount(active.accountId)?.currentConnectionId !== active.id || !canAccessConnectorAccount(active, installation, current.agentId)) throw new CapabilityError("FORBIDDEN", "Connected account authorization changed");
+			if (!contract || actionDigest(contract) !== descriptorDigest || argumentIdentity() !== argsHash) throw new CapabilityError("REVISION_CONFLICT", "Action contract or objective changed");
+			const evaluation = evaluateConnectorExecutionPolicy({
+				installation,
+				action: contract,
+				agentId: current.agentId,
+				accountId: active.accountId,
+				confirmed
+			});
+			if (evaluation.decision === "denied") throw new CapabilityError("FORBIDDEN", evaluation.reason);
+			return evaluation;
+		};
+		const evaluation = authorizeCurrent();
 		let result;
 		try {
-			result = await this.adapter.executeWithPolicy({
+			const execute = async () => this.adapter.executeWithPolicy({
+				signal: context.signal,
 				context: {
 					principalId: available.principalId,
 					toolkits: [toolkit],
@@ -309,7 +342,36 @@ var ComposioToolProvider = class {
 				args: actionArgs,
 				agentId: available.agentId,
 				conversationId: available.context?.conversationId,
-				confirmed
+				confirmed,
+				beforeExecute: () => {
+					const current = authorizeCurrent();
+					if (current.decision !== "allowed") throw new ExternalEffectNotAppliedError(current.reason);
+					if (approvalId && !consumeConnectorApproval(approvalId, argsHash)) throw new ExternalEffectNotAppliedError("Approval is no longer available");
+				}
+			});
+			if (evaluation.decision === "confirmation_required") result = {
+				decision: "confirmation_required",
+				reason: evaluation.reason
+			};
+			else if (action.scope === "read") result = await execute();
+			else result = await executeExternalOperation({
+				principalId: available.principalId,
+				capabilityId: toolRef,
+				idempotencyKey: connectorArgumentsHash(approvalId ? { approvalId } : {
+					conversationId: available.context?.conversationId,
+					toolCallId: context.toolCallId
+				}),
+				requestDigest: argsHash,
+				descriptorDigest,
+				surface: "agent",
+				recovery: "manual"
+			}, async () => {
+				const outcome = await execute();
+				if (outcome.decision !== "allowed") throw new ExternalEffectNotAppliedError(outcome.reason);
+				return outcome;
+			}, (outcome) => {
+				if (outcome.result && typeof outcome.result === "object" && "successful" in outcome.result && outcome.result.successful === false) throw new Error("Provider reported an unsuccessful action without proving that no effect was applied");
+				return outcome;
 			});
 		} catch (error) {
 			if (action.scope === "read") {
@@ -342,11 +404,7 @@ var ComposioToolProvider = class {
 				conversationId: available.context?.conversationId,
 				actionId: action.actionId,
 				scope: action.scope,
-				argumentsHash: connectorArgumentsHash({
-					args: actionArgs,
-					accountId: connection.accountId,
-					objective: available.context ? connectorObjectiveScope(available.context.conversationId) : void 0
-				}),
+				argumentsHash: argumentIdentity(),
 				argumentsPreview: {
 					account: {
 						id: connection.accountId,

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

@@ -1,6 +1,9 @@
 import { COMPUTER_CONTROL_TOOL, init_src } from "../../../packages/computer-control-contract/src/index.js";
 import { BROWSER_CONTROL_ENDPOINT_TOOL_NAME } from "../../../packages/browser-control-contract/src/index.js";
+import { executeExternalOperation } from "../../capabilities/runtime/external-operations.js";
+import { canonicalCapabilityJson } from "../../capabilities/runtime/dispatcher.js";
 import { externalToolRef, parseExternalToolRef } from "./refs.js";
+import { createHash } from "node:crypto";
 //#region src/agent/external-tools/endpoint-provider.ts
 init_src();
 function contentText(content) {
@@ -40,7 +43,7 @@ var EndpointToolProvider = class {
 	async execute(toolRef, args, _approvalId, context) {
 		const resolved = this.resolve(toolRef);
 		if (!resolved) throw new Error(`Endpoint tool is unavailable for this turn: ${toolRef}`);
-		const result = await this.deps.runtime.invocations.invoke({
+		const invoke = () => this.deps.runtime.invocations.invoke({
 			endpointId: resolved.endpointId,
 			toolCallId: context.toolCallId,
 			toolName: resolved.tool.descriptor.name,
@@ -60,6 +63,15 @@ var EndpointToolProvider = class {
 				});
 			}
 		});
+		const result = resolved.tool.descriptor.effect === "read" ? await invoke() : await executeExternalOperation({
+			principalId: resolved.principalId,
+			capabilityId: toolRef,
+			idempotencyKey: createHash("sha256").update(`${this.deps.getCurrentContext()?.conversationId}:${context.toolCallId}`).digest("hex"),
+			requestDigest: createHash("sha256").update(canonicalCapabilityJson(args)).digest("hex"),
+			descriptorDigest: resolved.tool.revision,
+			surface: "agent",
+			recovery: "manual"
+		}, invoke);
 		const files = result.content.filter((item) => item.type === "file");
 		return {
 			content: result.content.map((item) => ({
@@ -92,6 +104,7 @@ var EndpointToolProvider = class {
 		if (tool && ["browser.control", "desktop.computer.control"].includes(tool.descriptor.name)) return void 0;
 		return tool ? {
 			endpointId: endpoint.endpointId,
+			principalId: endpoint.principalId,
 			displayName: endpoint.displayName,
 			tool
 		} : void 0;

package/dist/src/agent/inbound/turn-dispatcher.d.ts

@@ -25,6 +25,7 @@ import type { SessionStore } from '../../session/store.js';
 import type { SessionContext, SessionHydrator, SessionStateBag } from '../session/index.js';
 import type { InboundAttachmentInput, MediaRef } from '../../channels/attachments/inbound-persist.js';
 import { type ProcessDirectStreamEvent } from '../service/process-direct-streaming.js';
+import { type WebchatTtsResult } from '../service/webchat-tts.js';
 import type { AgentSourceContext, AgentSourceContextResolver } from '../source-context/types.js';
 export interface TurnDispatcherConfig {
     log: ContextualLogger;
@@ -76,6 +77,7 @@ export declare class TurnDispatcher {
         runId?: string;
         sourceContexts?: AgentSourceContext[];
         presentation?: 'voice';
+        onDeferredAudio?: (audio: WebchatTtsResult) => void;
     }): AsyncGenerator<ProcessDirectStreamEvent, void, unknown>;
     /** Push an out-of-band event into the live webchat stream for a session. */
     enqueueWebchatStreamEvent(conversationId: string, event: {

package/dist/src/agent/inbound/turn-dispatcher.js

@@ -35,7 +35,8 @@ var TurnDispatcher = class {
 			signal: options?.signal,
 			runId: options?.runId,
 			sourceContexts: options?.sourceContexts,
-			presentation: options?.presentation
+			presentation: options?.presentation,
+			onDeferredAudio: options?.onDeferredAudio
 		});
 	}
 	/** Push an out-of-band event into the live webchat stream for a session. */

package/dist/src/agent/memory/compaction-chunks.d.ts

@@ -7,12 +7,17 @@ export interface HandoverChunk {
     text: string;
     sourceThroughSeq: number;
 }
+export interface CompactionChunkCursorState {
+    index: number;
+    offset: number;
+}
 /** Consume source text in order, fitting each chunk against the current ledger. */
 export declare class CompactionChunkCursor {
     private readonly sources;
     private index;
     private offset;
-    constructor(sources: readonly CompactionSourceText[]);
+    constructor(sources: readonly CompactionSourceText[], state?: CompactionChunkCursorState);
     get done(): boolean;
+    checkpoint(): CompactionChunkCursorState;
     next(maxTokens: number, fits: (text: string) => boolean): HandoverChunk;
 }

package/dist/src/agent/memory/compaction-chunks.js

@@ -2,14 +2,27 @@ import { estimateTextTokens } from "./context-budget.js";
 //#region src/agent/memory/compaction-chunks.ts
 /** Consume source text in order, fitting each chunk against the current ledger. */
 var CompactionChunkCursor = class {
-	index = 0;
-	offset = 0;
-	constructor(sources) {
+	index;
+	offset;
+	constructor(sources, state = {
+		index: 0,
+		offset: 0
+	}) {
 		this.sources = sources;
+		const source = sources[state.index];
+		if (!Number.isInteger(state.index) || state.index < 0 || state.index > sources.length || !Number.isInteger(state.offset) || state.offset < 0 || (state.index === sources.length ? state.offset !== 0 : state.offset > source.text.length)) throw new Error("Invalid compaction chunk checkpoint");
+		this.index = state.index;
+		this.offset = state.offset;
 	}
 	get done() {
 		return this.index >= this.sources.length;
 	}
+	checkpoint() {
+		return {
+			index: this.index,
+			offset: this.offset
+		};
+	}
 	next(maxTokens, fits) {
 		const parts = [];
 		let sourceThroughSeq = 0;

package/dist/src/agent/memory/compaction-ledger.d.ts

@@ -1,11 +1,13 @@
 import { type CompactionHandover } from '../../session/compaction-types.js';
 import type { TranscriptSourceEntry } from '../../storage/sqlite/transcript-repository.js';
 export type { CompactionAudit, CompactionHandover, CompactionHandoverItem, HandoverItemKind, } from '../../session/compaction-types.js';
-export declare function parseCompactionHandover(params: {
+/** Apply a bounded model-produced delta to the trusted local handover. */
+export declare function applyCompactionHandoverDelta(params: {
     text: string;
     sourceThroughSeq: number;
     previousBoundaryId?: string;
     allowedSources: readonly TranscriptSourceEntry[];
+    current?: CompactionHandover;
 }): CompactionHandover;
 export declare function renderCompactionHandover(handover: CompactionHandover): string;
 export declare function handoverForPrompt(handover: CompactionHandover | undefined): object;

package/dist/src/agent/memory/compaction-ledger.js

@@ -3,18 +3,20 @@ import { createHash } from "node:crypto";
 import { z } from "zod";
 //#region src/agent/memory/compaction-ledger.ts
 init_compaction_types();
-const RawHandoverItemSchema = z.object({
+const MAX_HANDOVER_ITEMS = 120;
+const RawHandoverUpsertSchema = z.object({
+	id: z.string().min(1).max(64).optional(),
 	kind: z.enum(HANDOVER_ITEM_KINDS),
-	text: z.string().min(1),
+	text: z.string().trim().min(1).max(2e3),
 	status: z.enum([
 		"active",
 		"completed",
 		"superseded"
 	]),
 	sourceSeqs: z.array(z.number().int().positive()).min(1),
-	identifiers: z.array(z.string()).default([])
+	identifiers: z.array(z.string().max(256)).max(20).default([])
 }).strict();
-const RawHandoverSchema = z.object({ items: z.array(RawHandoverItemSchema).max(120) }).strict();
+const RawHandoverDeltaSchema = z.object({ upserts: z.array(RawHandoverUpsertSchema).max(MAX_HANDOVER_ITEMS) }).strict();
 function extractJsonObject(text) {
 	const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i)?.[1]?.trim();
 	if (fenced) return fenced;
@@ -26,34 +28,44 @@ function extractJsonObject(text) {
 function itemId(kind, text, seqs) {
 	return createHash("sha256").update(`${kind}\0${text.trim()}\0${[...seqs].sort((a, b) => a - b).join(",")}`).digest("hex").slice(0, 20);
 }
-function parseCompactionHandover(params) {
-	const parsed = RawHandoverSchema.parse(JSON.parse(extractJsonObject(params.text)));
-	const sourceBySeq = new Map(params.allowedSources.map((source) => [source.seq, source]));
-	const items = parsed.items.map((item) => {
+/** Apply a bounded model-produced delta to the trusted local handover. */
+function applyCompactionHandoverDelta(params) {
+	const parsed = RawHandoverDeltaSchema.parse(JSON.parse(extractJsonObject(params.text)));
+	const sourceBySeq = new Map(params.allowedSources.map((source) => [source.seq, {
+		entryId: source.entryId,
+		seq: source.seq
+	}]));
+	for (const item of params.current?.items ?? []) for (const source of item.sources) sourceBySeq.set(source.seq, source);
+	const items = new Map((params.current?.items ?? []).map((item) => [item.id, item]));
+	const seenIds = /* @__PURE__ */ new Set();
+	for (const item of parsed.upserts) {
 		const seqs = [...new Set(item.sourceSeqs)].sort((a, b) => a - b);
 		const sources = seqs.map((seq) => {
 			const source = sourceBySeq.get(seq);
 			if (!source || seq > params.sourceThroughSeq) throw new Error(`Compaction handover references unavailable source seq ${seq}`);
-			return {
-				entryId: source.entryId,
-				seq
-			};
+			return source;
 		});
 		const text = item.text.trim();
-		return {
-			id: itemId(item.kind, text, seqs),
+		const id = item.id ?? itemId(item.kind, text, seqs);
+		if (item.id && !items.has(item.id)) throw new Error(`Compaction handover updates unknown item ${item.id}`);
+		if (seenIds.has(id)) throw new Error(`Compaction handover repeats item ${id}`);
+		seenIds.add(id);
+		items.set(id, {
+			id,
 			kind: item.kind,
 			text,
 			status: item.status,
 			sources,
 			identifiers: [...new Set(item.identifiers.map((value) => value.trim()).filter(Boolean))]
-		};
-	});
+		});
+	}
+	const retained = [...items.values()].filter((item) => item.status !== "superseded");
+	if (retained.length > MAX_HANDOVER_ITEMS) throw new Error(`Compaction handover exceeds ${MAX_HANDOVER_ITEMS} durable items`);
 	return {
 		version: 1,
 		sourceThroughSeq: params.sourceThroughSeq,
 		...params.previousBoundaryId ? { previousBoundaryId: params.previousBoundaryId } : {},
-		items: [...new Map(items.map((item) => [item.id, item])).values()]
+		items: retained
 	};
 }
 const SUMMARY_GROUPS = [
@@ -104,6 +116,7 @@ function renderCompactionHandover(handover) {
 }
 function handoverForPrompt(handover) {
 	return { items: handover?.items.map((item) => ({
+		id: item.id,
 		kind: item.kind,
 		text: item.text,
 		status: item.status,
@@ -112,4 +125,4 @@ function handoverForPrompt(handover) {
 	})) ?? [] };
 }
 //#endregion
-export { handoverForPrompt, parseCompactionHandover, renderCompactionHandover };
+export { applyCompactionHandoverDelta, handoverForPrompt, renderCompactionHandover };

package/dist/src/agent/memory/compaction-request.d.ts

@@ -6,6 +6,8 @@ export declare class CompactionRequestError extends Error {
     constructor(kind: 'length' | 'empty' | 'budget' | 'provider' | 'timeout', message: string);
 }
 export declare function compactionOutputLimit(model: Model<Api>, configured: number): number;
+/** Start large prompts closer to their likely delta size while retaining room to double on truncation. */
+export declare function initialCompactionOutputLimit(systemPrompt: string, prompt: string, outputLimit: number): number;
 export declare function compactionPromptFits(model: Model<Api>, systemPrompt: string, prompt: string, outputLimit: number): boolean;
 /** Bound the final provider payload, including adapters that add a thinking budget. */
 export declare function compactionPayloadGuard(limit: number, onBudget: (actual: number) => void): NonNullable<SimpleStreamOptions['onPayload']>;

package/dist/src/agent/memory/compaction-request.js

@@ -12,6 +12,11 @@ var CompactionRequestError = class extends Error {
 function compactionOutputLimit(model, configured) {
 	return Math.min(configured, model.maxTokens > 0 ? model.maxTokens : configured);
 }
+/** Start large prompts closer to their likely delta size while retaining room to double on truncation. */
+function initialCompactionOutputLimit(systemPrompt, prompt, outputLimit) {
+	const estimated = Math.ceil((estimateTextTokens(systemPrompt) + estimateTextTokens(prompt)) * .2);
+	return Math.min(outputLimit, estimated > 4e3 ? 8e3 : 4e3);
+}
 function compactionPromptFits(model, systemPrompt, prompt, outputLimit) {
 	return estimateTextTokens(systemPrompt) + estimateTextTokens(prompt) + 32 + outputLimit + COMPACTION_CONTEXT_MARGIN <= (model.contextWindow || 128e3);
 }
@@ -69,4 +74,4 @@ function isPermanentCompactionError(error) {
 	return /(?:\b(?:400|401|403|404|422)\b|unauthorized|forbidden|invalid api key|no api key|token expired|context (?:length|window)|maximum context|unsupported parameter|budget cannot fit)/i.test(message);
 }
 //#endregion
-export { COMPACTION_CONTEXT_MARGIN, COMPACTION_REPAIR_RESERVE, CompactionRequestError, compactionOutputLimit, compactionPayloadGuard, compactionPromptFits, isPermanentCompactionError };
+export { COMPACTION_CONTEXT_MARGIN, COMPACTION_REPAIR_RESERVE, CompactionRequestError, compactionOutputLimit, compactionPayloadGuard, compactionPromptFits, initialCompactionOutputLimit, isPermanentCompactionError };