@bastani/atomic 0.9.16-alpha.2 → 0.9.16-alpha.3

package/dist/builtin/workflows/src/engine/run-tool-control-registry.ts

@@ -1,187 +0,0 @@
-/**
- * Live tool-node control registry — runtime-only handle table keyed by
- * `runId + nodeId`.
- *
- * `ctx.tool` executions live inside `run()`, while `/workflow quit|interrupt`
- * runs elsewhere in the process. Store snapshots are JSON-cloneable and cannot
- * carry an `AbortController`, so the abort surface for an in-flight tool node
- * lives here, exactly as live stage chat handles live in the stage-control
- * registry.
- *
- * Tool handles are abort-only: they are never attachable chat targets.
- *
- * cross-ref: issue #2078; src/runs/foreground/stage-control-registry.ts
- */
-
-import { createSessionScopedSingleton } from "../shared/session-scoped-singleton.js";
-import type { WorkflowToolNodeIdentity } from "../shared/types.js";
-import type { ToolAdmissionBoundary } from "./run-tool-admission-boundary.js";
-import { WorkflowToolAbortError, type WorkflowToolAbortScope } from "./workflow-tool-abort.js";
-
-/**
- * Bounded wait for aborted tool callbacks to settle before quit abandons them
- * and records the durable paused transition. A callback that ignores its signal
- * must never pin quit, mirroring the failure path's abandonment policy.
- */
-export const TOOL_QUIT_SETTLEMENT_TIMEOUT_MS = 500;
-
-export interface ToolControlRegistration {
-	readonly runId: string;
-	readonly nodeId: string;
-	readonly name: string;
-	readonly controller: AbortController;
-	/** Resolves when the logical tool execution settles, however it settles. */
-	readonly settled: Promise<void>;
-}
-
-export interface ToolControlHandle {
-	readonly runId: string;
-	readonly nodeId: string;
-	readonly name: string;
-	readonly settled: Promise<void>;
-	readonly aborted: boolean;
-	abort(scope: WorkflowToolAbortScope): WorkflowToolAbortError;
-}
-
-export interface ToolControlRegistry {
-	/** Register an in-flight node; the returned disposer unregisters it. */
-	register(registration: ToolControlRegistration): () => void;
-	/** Resolve one in-flight node by owning run id and local node id. */
-	get(runId: string, nodeId: string): ToolControlHandle | undefined;
-	/** Every in-flight node for one run, in registration order. */
-	active(runId: string): readonly ToolControlHandle[];
-	/**
-	 * Publish the root-shared admission boundary under one run id. Nested runs
-	 * register the same instance, so quit can close the whole boundary from any
-	 * run id below it.
-	 */
-	registerAdmissionBoundary(runId: string, boundary: ToolAdmissionBoundary): () => void;
-	admissionBoundary(runId: string): ToolAdmissionBoundary | undefined;
-	/** Drop every registration. Used on session/store teardown and by tests. */
-	clear(): void;
-}
-
-export function createToolControlRegistry(): ToolControlRegistry {
-	const byRun = new Map<string, Map<string, ToolControlHandle>>();
-	const admissionByRun = new Map<string, ToolAdmissionBoundary>();
-
-	const makeHandle = (registration: ToolControlRegistration): ToolControlHandle => ({
-		runId: registration.runId,
-		nodeId: registration.nodeId,
-		name: registration.name,
-		settled: registration.settled,
-		get aborted(): boolean {
-			return registration.controller.signal.aborted;
-		},
-		abort(scope: WorkflowToolAbortScope): WorkflowToolAbortError {
-			const existing = registration.controller.signal.reason;
-			if (registration.controller.signal.aborted && existing instanceof WorkflowToolAbortError) return existing;
-			const reason = new WorkflowToolAbortError({
-				runId: registration.runId,
-				nodeId: registration.nodeId,
-				toolName: registration.name,
-				scope,
-			});
-			registration.controller.abort(reason);
-			return reason;
-		},
-	});
-
-	return {
-		register(registration: ToolControlRegistration): () => void {
-			let runMap = byRun.get(registration.runId);
-			if (runMap === undefined) {
-				runMap = new Map();
-				byRun.set(registration.runId, runMap);
-			}
-			const handle = makeHandle(registration);
-			runMap.set(registration.nodeId, handle);
-			return () => {
-				const existing = byRun.get(registration.runId);
-				if (existing === undefined) return;
-				if (existing.get(registration.nodeId) === handle) existing.delete(registration.nodeId);
-				if (existing.size === 0) byRun.delete(registration.runId);
-			};
-		},
-		get(runId: string, nodeId: string): ToolControlHandle | undefined {
-			return byRun.get(runId)?.get(nodeId);
-		},
-		active(runId: string): readonly ToolControlHandle[] {
-			const runMap = byRun.get(runId);
-			return runMap === undefined ? [] : [...runMap.values()];
-		},
-		registerAdmissionBoundary(runId: string, boundary: ToolAdmissionBoundary): () => void {
-			admissionByRun.set(runId, boundary);
-			return () => {
-				if (admissionByRun.get(runId) === boundary) admissionByRun.delete(runId);
-			};
-		},
-		admissionBoundary(runId: string): ToolAdmissionBoundary | undefined {
-			return admissionByRun.get(runId);
-		},
-		clear(): void {
-			byRun.clear();
-			admissionByRun.clear();
-		},
-	};
-}
-
-/**
- * Process-wide registry. Tests and embedders SHOULD prefer an explicit instance
- * through `RunOpts.toolControlRegistry`; the singleton is the default consumer
- * surface used by the extension factory.
- */
-const SESSION_KEY = "workflows:tool-control:v1";
-const singleton = createSessionScopedSingleton(SESSION_KEY, createToolControlRegistry);
-
-export const toolControlRegistry: ToolControlRegistry = singleton.facade;
-
-export function adoptToolControlRegistry(scope: object): ToolControlRegistry {
-	return singleton.adopt(scope);
-}
-
-/**
- * Await settlement of aborted tool handles up to `timeoutMs` and report the
- * identities that were still unsettled when the bound expired.
- *
- * Identity stays structured: nested child runs legitimately share a local
- * `tool:<argsHash>` id because the hash is local to each run, so only
- * `{runId, nodeId}` distinguishes them.
- */
-export async function settleAbortedToolNodes(
-	handles: readonly ToolControlHandle[],
-	timeoutMs: number,
-): Promise<readonly WorkflowToolNodeIdentity[]> {
-	if (handles.length === 0) return [];
-	let expire: (() => void) | undefined;
-	const deadline = new Promise<void>((resolve) => {
-		expire = resolve;
-	});
-	const timer = setTimeout(() => expire?.(), timeoutMs);
-	// Node's timer keeps the loop alive otherwise; quit must not extend process
-	// lifetime just because it is waiting on a callback that may never answer.
-	(timer as { unref?: () => void }).unref?.();
-	try {
-		const settled = await Promise.all(
-			handles.map((handle) =>
-				Promise.race([
-					handle.settled.then(
-						() => true,
-						() => true,
-					),
-					deadline.then(() => false),
-				]),
-			),
-		);
-		return handles.flatMap((handle, index) =>
-			settled[index] === true ? [] : [{ runId: handle.runId, nodeId: handle.nodeId }],
-		);
-	} finally {
-		clearTimeout(timer);
-	}
-}
-
-/** True when both identities name the same tool node in the same run. */
-export function sameToolNodeIdentity(left: WorkflowToolNodeIdentity, right: WorkflowToolNodeIdentity): boolean {
-	return left.runId === right.runId && left.nodeId === right.nodeId;
-}

package/dist/builtin/workflows/src/engine/run-tool-execution-tracker.ts

@@ -1,164 +0,0 @@
-export interface AdmittedToolFailure {
-	readonly admissionOrder: number;
-	readonly error: unknown;
-	readonly nodeId?: string;
-}
-
-export type AdmittedToolExecutionAdmission =
-	| { readonly accepted: true; bindNode(nodeId: string): void; noteCancelled(): void }
-	| { readonly accepted: false; readonly error: Error; bindNode(nodeId: string): void; noteCancelled(): void };
-
-export interface AdmittedToolExecutionTracker {
-	track<T>(execution: Promise<T>): AdmittedToolExecutionAdmission;
-	observeFailure(error: unknown, nodeId: string): void;
-	closeAndDrain(): Promise<void>;
-	abandonNonFailed(): readonly string[];
-	firstFailure(): AdmittedToolFailure | undefined;
-	uniqueFailureFor(error: unknown): AdmittedToolFailure | undefined;
-}
-
-export interface AdmittedToolExecutionTrackerOptions {
-	readonly onFailureObserved?: (failure: AdmittedToolFailure) => void;
-	readonly onFailureDuringDrain?: (failure: AdmittedToolFailure) => void;
-}
-
-/** Tracks each logical ctx.tool promise without changing the promise returned to authors. */
-export function createAdmittedToolExecutionTracker(
-	options: AdmittedToolExecutionTrackerOptions = {},
-): AdmittedToolExecutionTracker {
-	const inFlight = new Set<Promise<void>>();
-	const admissions: Array<{
-		readonly admissionOrder: number;
-		nodeId?: string;
-		failure?: AdmittedToolFailure;
-		cancelled: boolean;
-		settled: boolean;
-		observed?: Promise<void>;
-	}> = [];
-	const failures: AdmittedToolFailure[] = [];
-	let nextAdmissionOrder = 0;
-	let state: "OPEN" | "DRAINING" | "CLOSED" = "OPEN";
-	let closing: Promise<void> | undefined;
-	const abandonment = Promise.withResolvers<void>();
-	let abandoned = false;
-	let drainFailureReported = false;
-
-	const recordFailure = (admission: (typeof admissions)[number], error: unknown, nodeId?: string): void => {
-		if (admission.failure !== undefined) return;
-		const failure = { admissionOrder: admission.admissionOrder, error, ...(nodeId === undefined ? {} : { nodeId }) };
-		admission.failure = failure;
-		failures.push(failure);
-		options.onFailureObserved?.(failure);
-	};
-
-	const reportDrainFailure = (): void => {
-		const failure = failures[0];
-		if (state !== "DRAINING" || failure === undefined || drainFailureReported) return;
-		drainFailureReported = true;
-		options.onFailureDuringDrain?.(failure);
-	};
-
-	const drainRecordedFailures = (): Promise<unknown[]> =>
-		Promise.all(
-			admissions.flatMap((admission) =>
-				admission.failure !== undefined && admission.observed !== undefined ? [admission.observed] : [],
-			),
-		);
-
-	const closeAtFixedPoint = async (): Promise<void> => {
-		while (!abandoned) {
-			const current = [...inFlight];
-			if (current.length > 0) {
-				const drained = await Promise.race([
-					Promise.all(current).then(() => true),
-					abandonment.promise.then(() => false),
-				]);
-				if (!drained) break;
-			}
-			// Let author settlement continuations admit follow-up tools before the
-			// fixed-point check. The tracker observer is attached before return.
-			await Promise.resolve();
-			if (inFlight.size === 0) {
-				state = "CLOSED";
-				return;
-			}
-		}
-		await drainRecordedFailures();
-	};
-
-	return {
-		track<T>(execution: Promise<T>): AdmittedToolExecutionAdmission {
-			if (state === "CLOSED") {
-				const error = new Error("atomic-workflows: ctx.tool admission is closed for this run");
-				void execution.catch(() => undefined);
-				return { accepted: false, error, bindNode(): void {}, noteCancelled(): void {} };
-			}
-			const admission: (typeof admissions)[number] = {
-				admissionOrder: ++nextAdmissionOrder,
-				nodeId: undefined,
-				failure: undefined,
-				cancelled: false,
-				settled: false,
-			};
-			admissions.push(admission);
-			const observed = execution.then(
-				() => undefined,
-				(error: unknown) => {
-					// A cancelled node is not a run failure: it must never become the
-					// selected terminal failure nor abort the run controller on drain.
-					if (admission.cancelled) return;
-					recordFailure(admission, error, admission.nodeId);
-					reportDrainFailure();
-				},
-			);
-			admission.observed = observed;
-			inFlight.add(observed);
-			void observed.then(() => {
-				admission.settled = true;
-				inFlight.delete(observed);
-			});
-			return {
-				accepted: true,
-				bindNode(id: string): void {
-					admission.nodeId = id;
-				},
-				noteCancelled(): void {
-					admission.cancelled = true;
-				},
-			};
-		},
-		observeFailure(error: unknown, nodeId: string): void {
-			const admission = admissions.find((candidate) => candidate.nodeId === nodeId);
-			if (admission !== undefined) {
-				recordFailure(admission, error, nodeId);
-				reportDrainFailure();
-			}
-		},
-		closeAndDrain(): Promise<void> {
-			if (closing !== undefined) return closing;
-			state = "DRAINING";
-			reportDrainFailure();
-			closing = closeAtFixedPoint();
-			return closing;
-		},
-		abandonNonFailed(): readonly string[] {
-			if (!abandoned) {
-				abandoned = true;
-				state = "CLOSED";
-				abandonment.resolve();
-			}
-			return admissions.flatMap((admission) =>
-				!admission.settled && admission.failure === undefined && admission.nodeId !== undefined
-					? [admission.nodeId]
-					: [],
-			);
-		},
-		firstFailure(): AdmittedToolFailure | undefined {
-			return failures[0];
-		},
-		uniqueFailureFor(error: unknown): AdmittedToolFailure | undefined {
-			const matching = failures.filter((failure) => Object.is(failure.error, error));
-			return matching.length === 1 ? matching[0] : undefined;
-		},
-	};
-}

package/dist/builtin/workflows/src/engine/run-tool-node-lifecycle.ts

@@ -1,158 +0,0 @@
-import type { DurableWorkflowBackend } from "../durable/backend.js";
-import { type CreateToolPrimitiveInput, createToolPrimitive } from "../durable/tool-primitive.js";
-import { unknownErrorMessage } from "../runs/foreground/executor-abort.js";
-import type { Store } from "../shared/store.js";
-import type { RunSnapshot, ToolNodeSnapshot } from "../shared/store-types.js";
-import type { WorkflowToolPrimitive } from "../shared/types.js";
-import type { GraphFrontierTracker } from "./graph-inference.js";
-import type { RunBudgetController } from "./run-budget.js";
-import { durableRunTopology } from "./run-durable-topology.js";
-import type { RunTerminalEventArbiter } from "./run-terminal-event.js";
-import type { ToolAdmissionBoundary } from "./run-tool-admission-boundary.js";
-import type { ToolControlRegistry } from "./run-tool-control-registry.js";
-import { type AdmittedToolExecutionTracker, createAdmittedToolExecutionTracker } from "./run-tool-execution-tracker.js";
-import { isWorkflowToolAbortError, type WorkflowGracefulQuitSignal } from "./workflow-tool-abort.js";
-
-type ToolNodeLifecycle = Pick<
-	CreateToolPrimitiveInput,
-	"onNodeStart" | "onNodeRunning" | "onNodeEnd" | "onNodeSettle" | "runTopology"
->;
-
-export function createToolNodeLifecycle(input: {
-	readonly store: Store;
-	readonly tracker: GraphFrontierTracker;
-	readonly run: RunSnapshot;
-	readonly sourceToReplayedNodeIds: Map<string, string>;
-}): ToolNodeLifecycle {
-	const { store, tracker, run, sourceToReplayedNodeIds } = input;
-	/**
-	 * True while this executor's own run snapshot is the one the store holds.
-	 *
-	 * A resume relaunches under the *same* run id, so a stale callback abandoned
-	 * by quit could otherwise mutate the replacement run's tool node. Object
-	 * identity, not the id, decides which generation owns the store row. The
-	 * abandoned callback may still settle its own private graph tracker.
-	 */
-	const ownsCurrentRun = (): boolean => store.runs().some((candidate) => candidate === run);
-	return {
-		onNodeStart: (node) => {
-			const inferredParents = tracker.onSpawn(node.id, node.name);
-			const sourceParents =
-				node.replayed === true && node.topologyState !== "unavailable" ? node.parentIds : undefined;
-			const restored = sourceParents?.map((sourceId) => sourceToReplayedNodeIds.get(sourceId));
-			const parentIds = restored?.every((id): id is string => id !== undefined) ? restored : inferredParents;
-			tracker.replaceParents(node.id, parentIds);
-			(node as ToolNodeSnapshot & { parentIds: readonly string[] }).parentIds = Object.freeze([...parentIds]);
-			sourceToReplayedNodeIds.set(node.id, node.id);
-			if (ownsCurrentRun()) store.recordToolNodeStart(run.id, node);
-		},
-		onNodeRunning: (nodeId, startedAt) => {
-			if (ownsCurrentRun()) store.recordToolNodeRunning(run.id, nodeId, startedAt);
-		},
-		onNodeEnd: (nodeId, update) => {
-			if (ownsCurrentRun()) store.recordToolNodeEnd(run.id, nodeId, update);
-		},
-		onNodeSettle: (nodeId) => {
-			tracker.onSettle(nodeId);
-		},
-		runTopology: durableRunTopology(run),
-	};
-}
-
-/** Wire durable tool execution to terminal-event arbitration and graph state. */
-export function createTrackedToolPrimitive(input: {
-	readonly workflowId: string;
-	readonly backend: DurableWorkflowBackend;
-	readonly nextCheckpointId: () => string;
-	readonly controller: AbortController;
-	readonly terminalEvents: RunTerminalEventArbiter;
-	readonly store: Store;
-	readonly tracker: GraphFrontierTracker;
-	readonly run: RunSnapshot;
-	readonly sourceToReplayedNodeIds: Map<string, string>;
-	readonly toolControls: ToolControlRegistry;
-	readonly toolAdmission: ToolAdmissionBoundary;
-	readonly budget: RunBudgetController;
-}): {
-	readonly tool: WorkflowToolPrimitive;
-	readonly admittedTools: AdmittedToolExecutionTracker;
-	/** Abandon still-unsettled tool executions and publish them as cancelled. */
-	readonly abandonInFlightAsCancelled: (reason: unknown) => readonly string[];
-	/**
-	 * The whole-run quit this executor's own tool work observed, if any: a node
-	 * aborted with quit scope, or a call refused after quit closed admission.
-	 *
-	 * `run()` uses this rather than the boundary's closed state so a quit that
-	 * only paused stages (and was later resumed) can still complete normally,
-	 * while a caught tool cancellation cannot convert quit into completion.
-	 */
-	readonly observedQuitCancellation: () => WorkflowGracefulQuitSignal | undefined;
-} {
-	let observedQuit: WorkflowGracefulQuitSignal | undefined;
-	const admittedTools = createAdmittedToolExecutionTracker({
-		onFailureObserved: ({ error, nodeId }) => {
-			input.terminalEvents.selectFailure(error, nodeId);
-		},
-		onFailureDuringDrain: (failure) => {
-			if (input.terminalEvents.winner()?.kind === "failure") input.controller.abort(failure.error);
-		},
-	});
-	const lifecycle = createToolNodeLifecycle(input);
-	const budgetBoundary = input.budget.enabled
-		? (): Promise<void> => input.budget.stopAtBoundaryAsync(input.run.stages.at(-1)?.name)
-		: undefined;
-	const tool = createToolPrimitive({
-		workflowId: input.workflowId,
-		backend: input.backend,
-		onFailureObserved: admittedTools.observeFailure,
-		nextCheckpointId: input.nextCheckpointId,
-		throwIfCancelled: () => {
-			if (input.controller.signal.aborted) throw new Error("atomic-workflows: workflow cancelled");
-		},
-		signal: input.controller.signal,
-		trackExecution: admittedTools.track,
-		registerNodeControl: (registration) => {
-			registration.controller.signal.addEventListener(
-				"abort",
-				() => {
-					const reason: unknown = registration.controller.signal.reason;
-					if (isWorkflowToolAbortError(reason) && reason.scope === "quit") observedQuit ??= reason;
-				},
-				{ once: true },
-			);
-			return input.toolControls.register({
-				runId: input.run.id,
-				nodeId: registration.nodeId,
-				name: registration.name,
-				controller: registration.controller,
-				settled: registration.settled,
-			});
-		},
-		admitToolCall: () => {
-			const admission = input.toolAdmission.admit();
-			if (!admission.accepted) observedQuit ??= admission.error;
-			return admission;
-		},
-		...(budgetBoundary !== undefined ? { beforeToolCall: budgetBoundary, afterToolCall: budgetBoundary } : {}),
-		...lifecycle,
-	});
-	const abandonInFlightAsCancelled = (reason: unknown): readonly string[] => {
-		const endedAt = Date.now();
-		const error = unknownErrorMessage(reason);
-		const abandoned = admittedTools.abandonNonFailed();
-		for (const nodeId of abandoned) {
-			lifecycle.onNodeEnd?.(nodeId, { status: "cancelled", endedAt, error });
-			lifecycle.onNodeSettle?.(nodeId);
-		}
-		return abandoned;
-	};
-	input.controller.signal.addEventListener(
-		"abort",
-		() => {
-			if (input.terminalEvents.winner()?.kind !== "failure") return;
-			abandonInFlightAsCancelled(input.controller.signal.reason);
-		},
-		{ once: true },
-	);
-	return { tool, admittedTools, abandonInFlightAsCancelled, observedQuitCancellation: () => observedQuit };
-}