@librechat/agents 3.4.1 → 3.4.2

package/dist/esm/tools/subagent/SubagentExecutionRegistry.mjs

@@ -0,0 +1,597 @@
+import { SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY, getSubagentResumeManifest } from "./SubagentReplay.mjs";
+//#region src/tools/subagent/SubagentExecutionRegistry.ts
+const SUBAGENT_THREAD_ID_PREFIX = "subagent:";
+const SUBAGENT_EXECUTION_INVALIDATED_MESSAGE = "Subagent execution was invalidated.";
+function getPreparationResourceKey(kind, identity) {
+	return JSON.stringify([kind, identity]);
+}
+function attachRollbackError(cause, rollbackError) {
+	if (!(cause instanceof Error)) return;
+	try {
+		Object.defineProperty(cause, "rollbackError", {
+			configurable: true,
+			value: rollbackError
+		});
+	} catch {
+		return;
+	}
+}
+var PreparationLease = class {
+	owners;
+	token;
+	checkpointKey;
+	approvalKey;
+	constructor(owners, token, checkpointKey, approvalKey) {
+		this.owners = owners;
+		this.token = token;
+		this.checkpointKey = checkpointKey;
+		this.approvalKey = approvalKey;
+	}
+	get ownsCheckpoint() {
+		return this.owns(this.checkpointKey);
+	}
+	get ownsCreatedCheckpoint() {
+		return this.isCreated(this.checkpointKey);
+	}
+	get ownsApprovalScope() {
+		return this.owns(this.approvalKey);
+	}
+	get ownsCreatedApprovalScope() {
+		return this.isCreated(this.approvalKey);
+	}
+	assertOwned() {
+		if (!this.owns(this.checkpointKey) || !this.owns(this.approvalKey)) throw new SubagentExecutionInvalidatedError();
+	}
+	markCheckpointCreated(cleanup) {
+		this.markCreated(this.checkpointKey, cleanup);
+	}
+	markApprovalScopeCreated(cleanup) {
+		this.markCreated(this.approvalKey, cleanup);
+	}
+	release() {
+		this.releaseResource(this.checkpointKey);
+		this.releaseResource(this.approvalKey);
+	}
+	async rollback(cause, cleanup) {
+		let rollbackError;
+		let rollbackFailed = false;
+		try {
+			await cleanup?.(this);
+		} catch (error) {
+			rollbackError = error;
+			rollbackFailed = true;
+		}
+		const resourceRollback = await this.rollbackOwnedResources();
+		if (!rollbackFailed && resourceRollback.failed) {
+			rollbackError = resourceRollback.error;
+			rollbackFailed = true;
+		}
+		try {
+			if (rollbackFailed) attachRollbackError(cause, rollbackError);
+		} finally {
+			this.release();
+		}
+		throw cause;
+	}
+	owns(key) {
+		const owner = this.owners.get(key);
+		return owner?.status === "owned" && owner.token === this.token;
+	}
+	isCreated(key) {
+		const owner = this.owners.get(key);
+		return owner?.status === "owned" && owner.token === this.token && owner.created;
+	}
+	markCreated(key, cleanup) {
+		const owner = this.owners.get(key);
+		if (owner?.status !== "owned" || owner.token !== this.token) throw new SubagentExecutionInvalidatedError();
+		owner.created = true;
+		owner.cleanup = cleanup;
+	}
+	async rollbackOwnedResources() {
+		const cleanups = [];
+		for (const key of [this.checkpointKey, this.approvalKey]) {
+			const owner = this.owners.get(key);
+			if (owner?.status !== "owned" || owner.token !== this.token) continue;
+			if (!owner.created || owner.cleanup == null) {
+				this.owners.delete(key);
+				continue;
+			}
+			const state = {
+				status: "cleaning",
+				token: this.token
+			};
+			this.owners.set(key, state);
+			cleanups.push({
+				key,
+				state,
+				cleanup: owner.cleanup
+			});
+		}
+		return (await Promise.all(cleanups.map(({ key, state, cleanup }) => this.cleanResource(key, state, cleanup)))).find((result) => result.failed) ?? { failed: false };
+	}
+	async cleanResource(key, state, cleanup) {
+		try {
+			await cleanup();
+			return { failed: false };
+		} catch (error) {
+			return {
+				failed: true,
+				error
+			};
+		} finally {
+			if (this.owners.get(key) === state) this.owners.delete(key);
+		}
+	}
+	releaseResource(key) {
+		const owner = this.owners.get(key);
+		if (owner?.status === "owned" && owner.token === this.token) this.owners.delete(key);
+	}
+};
+function getConfigurable(config) {
+	return config?.configurable;
+}
+function getConfigurableString(configurable, key) {
+	const value = configurable?.[key];
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function encodeThreadIdentity(identity) {
+	return `${SUBAGENT_THREAD_ID_PREFIX}${Buffer.from(JSON.stringify(identity)).toString("base64url")}`;
+}
+function assertSameIdentity(current, next) {
+	if (current.childRunId === next.childRunId && current.childThreadId === next.childThreadId && current.approvalExecutionScope === next.approvalExecutionScope) return;
+	throw new Error("Subagent execution identity cannot change after binding.");
+}
+function assertCompatibleResumeExecution(current, next) {
+	if (current.parentToolCallId === next.parentToolCallId && current.childRunId === next.childRunId && current.subagentType === next.subagentType && current.configId === next.configId) return;
+	throw new Error("Subagent resume source cannot change after binding.");
+}
+function assertSameInvocation(current, next) {
+	if (current.description === next.description && current.subagentType === next.subagentType && current.configId === next.configId) return;
+	throw new SubagentInvocationBindingError();
+}
+function assertSameSettlement(current, next) {
+	if (current.definitionAuthority === next.definitionAuthority && current.fingerprint === next.fingerprint && current.subagentType === next.subagentType && current.configId === next.configId) return;
+	throw new SubagentSettlementBindingError();
+}
+function getAbortReason(signal) {
+	return signal.reason ?? /* @__PURE__ */ new Error("Subagent execution aborted.");
+}
+function getSubagentApprovalExecutionScope(childRunId, resumeAttemptId) {
+	return `subagent-approval:${Buffer.from(JSON.stringify([childRunId, resumeAttemptId])).toString("base64url")}`;
+}
+var SubagentExecutionInvalidatedError = class extends Error {
+	constructor() {
+		super(SUBAGENT_EXECUTION_INVALIDATED_MESSAGE);
+		this.name = "SubagentExecutionInvalidatedError";
+	}
+};
+var SubagentDefinitionBindingError = class extends Error {
+	constructor() {
+		super("Subagent effective definition binding cannot change.");
+		this.name = "SubagentDefinitionBindingError";
+	}
+};
+var SubagentInvocationBindingError = class extends Error {
+	constructor() {
+		super("Subagent invocation binding cannot change.");
+		this.name = "SubagentInvocationBindingError";
+	}
+};
+var SubagentSettlementBindingError = class extends Error {
+	constructor() {
+		super("Subagent settlement binding cannot change.");
+		this.name = "SubagentSettlementBindingError";
+	}
+};
+/** In-process source of truth for one Durable Subagent Execution. */
+var SubagentExecutionRecord = class {
+	address;
+	identityValue;
+	bindingValue;
+	bindingAuthority;
+	invocationValue;
+	settlementValue;
+	settledOutputValue;
+	resumeExecutionValue;
+	activeRunValue;
+	completedResultValue;
+	resolvedConfigValue;
+	pendingIdentityResolution;
+	pendingConfigResolution;
+	pendingExecution;
+	pendingSettlement;
+	phaseValue = "registered";
+	startedValue = false;
+	completedValue = false;
+	settledValue = false;
+	constructor(address, resumeExecution) {
+		this.address = address;
+		this.resumeExecutionValue = resumeExecution;
+	}
+	get snapshot() {
+		return {
+			address: this.address,
+			phase: this.phaseValue,
+			...this.identityValue == null ? {} : { identity: this.identityValue },
+			...this.bindingValue == null ? {} : { binding: this.bindingValue },
+			...this.invocationValue == null ? {} : { invocation: this.invocationValue },
+			...this.settlementValue == null ? {} : { settlement: this.settlementValue },
+			...this.resumeExecutionValue == null ? {} : { resumeExecution: this.resumeExecutionValue },
+			...this.activeRunValue == null ? {} : { activeRun: this.activeRunValue },
+			...this.completedResultValue == null ? {} : { completedResult: this.completedResultValue },
+			...this.resolvedConfigValue == null ? {} : { resolvedConfig: this.resolvedConfigValue },
+			started: this.startedValue,
+			completed: this.completedValue,
+			resolvingIdentity: this.pendingIdentityResolution != null,
+			resolving: this.pendingConfigResolution != null,
+			executing: this.pendingExecution != null,
+			settling: this.pendingSettlement != null,
+			settled: this.settledValue
+		};
+	}
+	get identity() {
+		return this.identityValue;
+	}
+	get binding() {
+		return this.bindingValue;
+	}
+	get resumeExecution() {
+		return this.resumeExecutionValue;
+	}
+	get invocation() {
+		return this.invocationValue;
+	}
+	get activeRun() {
+		return this.activeRunValue;
+	}
+	get settlement() {
+		return this.settlementValue;
+	}
+	get settledOutput() {
+		return this.settledOutputValue;
+	}
+	get completedResult() {
+		return this.completedResultValue;
+	}
+	get resolvedConfig() {
+		return this.resolvedConfigValue;
+	}
+	get started() {
+		return this.startedValue;
+	}
+	get completed() {
+		return this.completedValue;
+	}
+	assertUsable(signal) {
+		if (signal?.aborted === true) throw getAbortReason(signal);
+		if (this.phaseValue === "invalidated") throw new SubagentExecutionInvalidatedError();
+	}
+	attachResumeExecution(resumeExecution) {
+		if (resumeExecution == null) return;
+		if (this.resumeExecutionValue != null) {
+			assertCompatibleResumeExecution(this.resumeExecutionValue, resumeExecution);
+			return;
+		}
+		this.resumeExecutionValue = resumeExecution;
+	}
+	bindIdentity(identity) {
+		this.assertUsable();
+		if (this.identityValue != null) {
+			assertSameIdentity(this.identityValue, identity);
+			return;
+		}
+		this.identityValue = Object.freeze({ ...identity });
+	}
+	resolveIdentity(resolve) {
+		this.assertUsable();
+		if (this.identityValue != null) return Promise.resolve(this.identityValue);
+		if (this.pendingIdentityResolution != null) return this.pendingIdentityResolution;
+		const pending = Promise.resolve().then(() => {
+			this.assertCurrentIdentityResolution(pending);
+			return resolve();
+		}).then(async (resolution) => {
+			try {
+				this.assertCurrentIdentityResolution(pending);
+				resolution.lease.assertOwned();
+				resolution.commit?.(resolution.lease);
+				this.assertCurrentIdentityResolution(pending);
+				resolution.lease.assertOwned();
+				this.bindIdentity(resolution.identity);
+				const boundIdentity = this.identityValue;
+				if (boundIdentity == null) throw new SubagentExecutionInvalidatedError();
+				resolution.lease.release();
+				return boundIdentity;
+			} catch (error) {
+				return resolution.lease.rollback(error, async (lease) => {
+					await resolution.rollback?.(lease);
+				});
+			}
+		}).finally(() => {
+			if (this.pendingIdentityResolution === pending) this.pendingIdentityResolution = void 0;
+		});
+		this.pendingIdentityResolution = pending;
+		return pending;
+	}
+	bindDefinition(binding, authority) {
+		this.assertUsable();
+		if (this.bindingAuthority === "effective") {
+			if (authority === "provisional") return;
+			if (this.bindingValue?.subagentType !== binding.subagentType || this.bindingValue?.configId !== binding.configId) throw new SubagentDefinitionBindingError();
+			return;
+		}
+		if (authority === "provisional" && this.bindingValue != null) return;
+		this.bindingValue = Object.freeze({ ...binding });
+		this.bindingAuthority = authority;
+	}
+	resolveConfig(resolve, signal) {
+		this.assertUsable(signal);
+		if (this.resolvedConfigValue != null) return Promise.resolve(this.resolvedConfigValue);
+		if (this.pendingConfigResolution != null) return this.pendingConfigResolution;
+		const pending = Promise.resolve().then(resolve).then((resolvedConfig) => {
+			this.assertUsable(signal);
+			if (this.pendingConfigResolution !== pending) throw new SubagentExecutionInvalidatedError();
+			this.resolvedConfigValue = resolvedConfig;
+			return resolvedConfig;
+		}).finally(() => {
+			if (this.pendingConfigResolution === pending) this.pendingConfigResolution = void 0;
+		});
+		this.pendingConfigResolution = pending;
+		return pending;
+	}
+	execute(invocation, execute) {
+		this.bindDefinition({
+			subagentType: invocation.subagentType,
+			...invocation.configId == null ? {} : { configId: invocation.configId }
+		}, "effective");
+		this.bindInvocation(invocation);
+		if (this.pendingExecution != null) return this.pendingExecution;
+		const pending = Promise.resolve().then(execute).finally(() => {
+			if (this.pendingExecution === pending) this.pendingExecution = void 0;
+		});
+		this.pendingExecution = pending;
+		return pending;
+	}
+	settle(settlement, settledOutput, persist) {
+		this.bindDefinition({
+			...settlement.subagentType == null ? {} : { subagentType: settlement.subagentType },
+			...settlement.configId == null ? {} : { configId: settlement.configId }
+		}, settlement.definitionAuthority);
+		this.bindInvocation(settlement.invocation);
+		if (this.settlementValue != null) assertSameSettlement(this.settlementValue, settlement);
+		else this.settlementValue = Object.freeze({
+			...settlement,
+			invocation: Object.freeze({ ...settlement.invocation })
+		});
+		if (this.settledValue) return Promise.resolve();
+		if (this.pendingSettlement != null) return this.pendingSettlement;
+		const pending = Promise.resolve().then(persist).then(() => {
+			this.assertUsable();
+			if (this.pendingSettlement !== pending) throw new SubagentExecutionInvalidatedError();
+			this.settledValue = true;
+			this.settledOutputValue = settledOutput;
+			this.activeRunValue = void 0;
+			this.completedResultValue = void 0;
+			this.resolvedConfigValue = void 0;
+		}).finally(() => {
+			if (this.pendingSettlement === pending) this.pendingSettlement = void 0;
+		});
+		this.pendingSettlement = pending;
+		return pending;
+	}
+	activate(activeRun) {
+		this.transitionTo("active", [
+			"registered",
+			"active",
+			"interrupted",
+			"failed"
+		]);
+		if (this.activeRunValue != null) return this.activeRunValue;
+		this.activeRunValue = activeRun;
+		return activeRun;
+	}
+	markStarted() {
+		this.assertUsable();
+		if (this.phaseValue === "completed") throw new Error("Completed subagent execution cannot start again.");
+		this.startedValue = true;
+	}
+	markInterrupted() {
+		this.transitionTo("interrupted", ["active", "interrupted"]);
+	}
+	markFailed() {
+		this.transitionTo("failed", [
+			"registered",
+			"active",
+			"interrupted",
+			"failed"
+		]);
+		this.activeRunValue = void 0;
+		this.resolvedConfigValue = void 0;
+	}
+	markCompleted(result) {
+		this.transitionTo("completed", ["active"]);
+		this.completedValue = true;
+		this.completedResultValue = result;
+		this.resolvedConfigValue = void 0;
+	}
+	releaseActiveRun() {
+		const activeRun = this.activeRunValue;
+		this.activeRunValue = void 0;
+		return activeRun;
+	}
+	releaseResolvedConfig() {
+		this.resolvedConfigValue = void 0;
+	}
+	invalidate() {
+		this.phaseValue = "invalidated";
+		this.identityValue = void 0;
+		this.bindingValue = void 0;
+		this.bindingAuthority = void 0;
+		this.invocationValue = void 0;
+		this.settlementValue = void 0;
+		this.settledOutputValue = void 0;
+		this.resumeExecutionValue = void 0;
+		this.activeRunValue = void 0;
+		this.completedResultValue = void 0;
+		this.resolvedConfigValue = void 0;
+		this.pendingIdentityResolution = void 0;
+		this.pendingConfigResolution = void 0;
+		this.pendingExecution = void 0;
+		this.pendingSettlement = void 0;
+		this.startedValue = false;
+		this.completedValue = false;
+		this.settledValue = false;
+	}
+	bindInvocation(invocation) {
+		if (this.invocationValue != null) {
+			assertSameInvocation(this.invocationValue, invocation);
+			return;
+		}
+		this.invocationValue = Object.freeze({ ...invocation });
+	}
+	assertCurrentIdentityResolution(pending) {
+		this.assertUsable();
+		if (this.pendingIdentityResolution !== pending) throw new SubagentExecutionInvalidatedError();
+	}
+	transitionTo(next, allowed) {
+		this.assertUsable();
+		if (!allowed.includes(this.phaseValue)) throw new Error(`Cannot transition subagent execution from ${this.phaseValue} to ${next}.`);
+		this.phaseValue = next;
+	}
+};
+/** Owns canonical addressing, record selection, and invalidation. */
+var SubagentExecutionRegistry = class {
+	options;
+	recordsByAddress = /* @__PURE__ */ new Map();
+	checkpointThreadIds = /* @__PURE__ */ new Set();
+	preparationResourceOwners = /* @__PURE__ */ new Map();
+	nextPreparationToken = 0;
+	constructor(options) {
+		this.options = options;
+	}
+	open(input) {
+		const address = this.createAddress(input);
+		const resumeExecution = getSubagentResumeManifest(input.parentConfigurable)?.executions.find((execution) => execution.parentToolCallId === input.parentToolCallId);
+		const current = this.recordsByAddress.get(address.key);
+		if (current != null) {
+			current.attachResumeExecution(resumeExecution);
+			return current;
+		}
+		const record = new SubagentExecutionRecord(address, resumeExecution);
+		this.recordsByAddress.set(address.key, record);
+		return record;
+	}
+	remove(record) {
+		if (this.recordsByAddress.get(record.address.key) !== record) return;
+		this.recordsByAddress.delete(record.address.key);
+		record.invalidate();
+	}
+	beginIdentityPreparation(record, identity) {
+		record.assertUsable();
+		if (this.recordsByAddress.get(record.address.key) !== record) throw new SubagentExecutionInvalidatedError();
+		const checkpointKey = getPreparationResourceKey("checkpoint", identity.childThreadId);
+		const approvalKey = getPreparationResourceKey("approval", identity.approvalExecutionScope);
+		const resourceKeys = [checkpointKey, approvalKey];
+		if (resourceKeys.map((key) => this.preparationResourceOwners.get(key)).some((resource) => resource != null)) throw new SubagentExecutionInvalidatedError();
+		this.nextPreparationToken += 1;
+		const token = this.nextPreparationToken;
+		for (let i = 0; i < resourceKeys.length; i++) {
+			const key = resourceKeys[i];
+			this.preparationResourceOwners.set(key, {
+				status: "owned",
+				token,
+				created: false
+			});
+		}
+		return new PreparationLease(this.preparationResourceOwners, token, checkpointKey, approvalKey);
+	}
+	selectForResume(selection = {}) {
+		if (selection.config != null) return this.selectScopedRecords(selection);
+		const counts = /* @__PURE__ */ new Map();
+		const candidates = [];
+		for (const record of this.recordsByAddress.values()) {
+			if (record.identity == null) continue;
+			const parentToolCallId = record.address.parentToolCallId;
+			if (selection.parentToolCallIds != null && !selection.parentToolCallIds.has(parentToolCallId)) continue;
+			candidates.push(record);
+			counts.set(parentToolCallId, (counts.get(parentToolCallId) ?? 0) + 1);
+		}
+		return candidates.filter((record) => counts.get(record.address.parentToolCallId) === 1);
+	}
+	rememberCheckpointThread(...threadIds) {
+		for (const threadId of threadIds) this.checkpointThreadIds.add(threadId);
+	}
+	getCheckpointThreadIds(getNestedThreadIds) {
+		const threadIds = new Set(this.checkpointThreadIds);
+		if (getNestedThreadIds == null) return [...threadIds];
+		for (const record of this.recordsByAddress.values()) {
+			if (record.activeRun == null) continue;
+			for (const threadId of getNestedThreadIds(record.activeRun)) threadIds.add(threadId);
+		}
+		return [...threadIds];
+	}
+	resetCheckpointThreadIds() {
+		this.checkpointThreadIds.clear();
+	}
+	retireResumeSources(current, sourceThreadIds, retire) {
+		for (const record of this.recordsByAddress.values()) {
+			if (record === current || record.identity == null || !sourceThreadIds.has(record.identity.childThreadId)) continue;
+			try {
+				retire(record);
+			} finally {
+				this.remove(record);
+			}
+		}
+	}
+	clear(dispose) {
+		for (const record of this.recordsByAddress.values()) {
+			dispose?.(record);
+			record.invalidate();
+		}
+		this.recordsByAddress.clear();
+	}
+	selectScopedRecords(selection) {
+		const parentConfigurable = getConfigurable(selection.config);
+		const threadId = getConfigurableString(parentConfigurable, "thread_id");
+		const parentToolCallIds = selection.parentToolCallIds ?? new Set([...this.recordsByAddress.values()].map((record) => record.address.parentToolCallId));
+		const records = [];
+		for (const parentToolCallId of parentToolCallIds) {
+			const address = this.createAddress({
+				threadId,
+				parentToolCallId,
+				parentConfigurable
+			});
+			const record = this.recordsByAddress.get(address.key);
+			if (record?.identity != null) records.push(record);
+		}
+		return records;
+	}
+	createAddress(input) {
+		const durableParentId = input.threadId ?? this.options.parentRunId;
+		const parentFork = getConfigurableString(input.parentConfigurable, "checkpoint_id") ?? "root";
+		const parentBatch = getConfigurableString(input.parentConfigurable, "__librechat_subagent_parent_batch") ?? "batch";
+		const configuredResumeAttemptId = getConfigurableString(input.parentConfigurable, SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY);
+		const resumeAttemptId = configuredResumeAttemptId ?? this.options.parentRunId;
+		const identity = [
+			durableParentId,
+			parentFork,
+			this.options.parentAgentId ?? "agent",
+			input.parentToolCallId,
+			parentBatch
+		];
+		const baseChildThreadId = encodeThreadIdentity(identity);
+		const branchChildThreadId = this.options.durable ? encodeThreadIdentity([...identity, resumeAttemptId]) : baseChildThreadId;
+		return Object.freeze({
+			key: branchChildThreadId,
+			baseChildThreadId,
+			branchChildThreadId,
+			currentChildRunId: `${this.options.parentRunId}_sub_${baseChildThreadId.slice(9)}`,
+			explicitResumeAttempt: configuredResumeAttemptId != null,
+			parentToolCallId: input.parentToolCallId,
+			resumeAttemptId
+		});
+	}
+};
+//#endregion
+export { SubagentDefinitionBindingError, SubagentExecutionRegistry, SubagentInvocationBindingError, SubagentSettlementBindingError, getSubagentApprovalExecutionScope };
+
+//# sourceMappingURL=SubagentExecutionRegistry.mjs.map