@codemation/core 0.0.1

package/src/orchestration/TriggerRuntimeService.ts

@@ -0,0 +1,260 @@
+import type {
+  ExecutionContextFactory,
+  Items,
+  JsonValue,
+  NodeDefinition,
+  NodeId,
+  NodeResolver,
+  RunDataFactory,
+  RunIdFactory,
+  TestableTriggerNode,
+  TriggerCleanupHandle,
+  TriggerInstanceId,
+  TriggerNode,
+  TriggerNodeConfig,
+  TriggerSetupContext,
+  TriggerSetupStateRepository,
+  TriggerRuntimeDiagnostics,
+  WorkflowActivationPolicy,
+  WorkflowDefinition,
+  WorkflowId,
+  WorkflowRepository,
+} from "../types";
+
+import { CredentialResolverFactory } from "../execution/CredentialResolverFactory";
+import type { NodeRunStateWriterFactory } from "../execution/NodeRunStateWriterFactory";
+import type { EngineExecutionLimitsPolicy } from "../policies/executionLimits/EngineExecutionLimitsPolicy";
+
+export interface TriggerEmitHandler {
+  emit(workflow: WorkflowDefinition, triggerNodeId: NodeId, items: Items): Promise<void>;
+}
+
+export class TriggerRuntimeService {
+  private readonly credentialResolverFactory: CredentialResolverFactory;
+  private readonly triggerCleanupHandlesByKey = new Map<string, TriggerCleanupHandle[]>();
+
+  constructor(
+    private readonly workflowRepository: WorkflowRepository,
+    private readonly workflowActivationPolicy: WorkflowActivationPolicy,
+    private readonly runIdFactory: RunIdFactory,
+    private readonly runDataFactory: RunDataFactory,
+    private readonly executionContextFactory: ExecutionContextFactory,
+    credentialResolverFactory: CredentialResolverFactory,
+    private readonly nodeExecutionStatePublisherFactory: NodeRunStateWriterFactory,
+    private readonly nodeResolver: NodeResolver,
+    private readonly triggerSetupStateRepository: TriggerSetupStateRepository,
+    private readonly emitHandler: TriggerEmitHandler,
+    private readonly executionLimitsPolicy: EngineExecutionLimitsPolicy,
+    private readonly diagnostics?: TriggerRuntimeDiagnostics,
+  ) {
+    this.credentialResolverFactory = credentialResolverFactory;
+  }
+
+  async startTriggers(): Promise<void> {
+    for (const wf of this.workflowRepository.list()) {
+      if (!this.workflowActivationPolicy.isActive(wf.id)) {
+        const summaries = this.formatTriggerSummaries(wf);
+        if (summaries.length > 0) {
+          this.logInfo(
+            `Workflow "${wf.name}" (${wf.id}) is inactive; skipping trigger setup — ${summaries.join("; ")}.`,
+          );
+        }
+        continue;
+      }
+      await this.startTriggersForWorkflow(wf);
+    }
+  }
+
+  async syncWorkflowTriggersForActivation(workflowId: WorkflowId): Promise<void> {
+    const wf = this.workflowRepository.get(workflowId);
+    if (!wf) {
+      return;
+    }
+    const summaries = this.formatTriggerSummaries(wf);
+    if (summaries.length > 0) {
+      this.logInfo(`Workflow "${wf.name}" (${wf.id}): stopping triggers — ${summaries.join("; ")}.`);
+    }
+    await this.stopTriggersForWorkflow(wf);
+    if (this.workflowActivationPolicy.isActive(workflowId)) {
+      if (summaries.length > 0) {
+        this.logInfo(`Workflow "${wf.name}" (${wf.id}): activation on; starting triggers — ${summaries.join("; ")}.`);
+      }
+      await this.startTriggersForWorkflow(wf);
+    } else {
+      this.logInfo(`Workflow "${wf.name}" (${wf.id}): activation off; triggers not started.`);
+    }
+  }
+
+  async stop(): Promise<void> {
+    for (const workflow of this.workflowRepository.list()) {
+      await this.stopTriggersForWorkflow(workflow);
+    }
+  }
+
+  async createTriggerTestItems(args: { workflow: WorkflowDefinition; nodeId: NodeId }): Promise<Items | undefined> {
+    const definition = args.workflow.nodes.find((node) => node.id === args.nodeId);
+    if (!definition) {
+      throw new Error(`Unknown trigger nodeId: ${args.nodeId}`);
+    }
+    if (definition.kind !== "trigger") {
+      throw new Error(`Node ${args.nodeId} is not a trigger`);
+    }
+    const node = this.nodeResolver.resolve(definition.type) as TriggerNode;
+    if (!this.isTestableTriggerNode(node)) {
+      return undefined;
+    }
+    const data = this.runDataFactory.create();
+    const runId = this.runIdFactory.makeRunId();
+    const trigger = { workflowId: args.workflow.id, nodeId: definition.id } as const;
+    const previousState = await this.triggerSetupStateRepository.load(trigger);
+    return await node.getTestItems({
+      ...this.createExecutionContext({
+        runId,
+        workflowId: args.workflow.id,
+        nodeId: definition.id,
+        data,
+      }),
+      trigger,
+      nodeId: definition.id,
+      config: definition.config as TriggerNodeConfig,
+      previousState: previousState?.state as never,
+    });
+  }
+
+  private async startTriggersForWorkflow(wf: WorkflowDefinition): Promise<void> {
+    for (const def of wf.nodes) {
+      if (def.kind !== "trigger") continue;
+      const node = this.nodeResolver.resolve(def.type) as TriggerNode;
+      const data = this.runDataFactory.create();
+      const triggerRunId = this.runIdFactory.makeRunId();
+      const trigger = { workflowId: wf.id, nodeId: def.id } as const;
+      await this.stopTrigger(trigger);
+      const previousState = await this.triggerSetupStateRepository.load(trigger);
+      let nextState: unknown;
+      try {
+        nextState = await node.setup({
+          ...this.createExecutionContext({
+            runId: triggerRunId,
+            workflowId: wf.id,
+            nodeId: def.id,
+            data,
+          }),
+          trigger,
+          config: def.config as TriggerNodeConfig,
+          previousState: previousState?.state as never,
+          registerCleanup: (cleanup) => {
+            this.registerTriggerCleanupHandle(trigger, cleanup);
+          },
+          emit: async (items) => {
+            await this.emitHandler.emit(wf, def.id, items);
+          },
+        } satisfies TriggerSetupContext<TriggerNodeConfig>);
+      } catch (triggerError: unknown) {
+        await this.stopTrigger(trigger);
+        const message = triggerError instanceof Error ? triggerError.message : String(triggerError);
+        this.logWarn(`Skipping trigger setup for workflow ${wf.id} node ${def.id}: ${message}`);
+        continue;
+      }
+      if (nextState === undefined) {
+        await this.triggerSetupStateRepository.delete(trigger);
+      } else {
+        await this.triggerSetupStateRepository.save({
+          trigger,
+          updatedAt: new Date().toISOString(),
+          state: nextState as JsonValue | undefined,
+        });
+      }
+    }
+  }
+
+  private async stopTriggersForWorkflow(workflow: WorkflowDefinition): Promise<void> {
+    for (const node of workflow.nodes) {
+      if (node.kind !== "trigger") {
+        continue;
+      }
+      await this.stopTrigger({
+        workflowId: workflow.id,
+        nodeId: node.id,
+      });
+    }
+  }
+
+  private createExecutionContext(args: {
+    runId: ReturnType<RunIdFactory["makeRunId"]>;
+    workflowId: string;
+    nodeId: NodeId;
+    data: ReturnType<RunDataFactory["create"]>;
+  }) {
+    const nodeState = this.nodeExecutionStatePublisherFactory.create(args.runId, args.workflowId, undefined);
+    const rootLimits = this.executionLimitsPolicy.createRootExecutionOptions();
+    return this.executionContextFactory.create({
+      runId: args.runId,
+      workflowId: args.workflowId,
+      parent: undefined,
+      subworkflowDepth: rootLimits.subworkflowDepth ?? 0,
+      engineMaxNodeActivations: rootLimits.maxNodeActivations!,
+      engineMaxSubworkflowDepth: rootLimits.maxSubworkflowDepth!,
+      data: args.data,
+      nodeState,
+      getCredential: this.credentialResolverFactory.create(args.workflowId, args.nodeId),
+    });
+  }
+
+  private registerTriggerCleanupHandle(trigger: TriggerInstanceId, cleanup: TriggerCleanupHandle): void {
+    const key = this.toTriggerKey(trigger);
+    const cleanups = this.triggerCleanupHandlesByKey.get(key) ?? [];
+    cleanups.push(cleanup);
+    this.triggerCleanupHandlesByKey.set(key, cleanups);
+  }
+
+  private async stopTrigger(trigger: TriggerInstanceId): Promise<void> {
+    const key = this.toTriggerKey(trigger);
+    const cleanups = this.triggerCleanupHandlesByKey.get(key) ?? [];
+    this.triggerCleanupHandlesByKey.delete(key);
+    for (const cleanup of [...cleanups].reverse()) {
+      await cleanup.stop();
+    }
+  }
+
+  private toTriggerKey(trigger: TriggerInstanceId): string {
+    return `${trigger.workflowId}:${trigger.nodeId}`;
+  }
+
+  private formatTriggerSummaries(wf: WorkflowDefinition): string[] {
+    const out: string[] = [];
+    for (const def of wf.nodes) {
+      if (def.kind !== "trigger") {
+        continue;
+      }
+      out.push(this.describeTriggerNode(def));
+    }
+    return out;
+  }
+
+  private describeTriggerNode(def: NodeDefinition): string {
+    const label = def.name !== undefined && def.name.trim().length > 0 ? def.name.trim() : String(def.id);
+    const cfg = def.config as { endpointKey?: unknown };
+    if (typeof cfg.endpointKey === "string" && cfg.endpointKey.trim().length > 0) {
+      return `${label} (webhook "${cfg.endpointKey.trim()}")`;
+    }
+    return label;
+  }
+
+  private logInfo(message: string): void {
+    if (this.diagnostics) {
+      this.diagnostics.info(message);
+    }
+  }
+
+  private logWarn(message: string): void {
+    if (this.diagnostics) {
+      this.diagnostics.warn(message);
+    } else {
+      console.warn(`[engine] ${message}`);
+    }
+  }
+
+  private isTestableTriggerNode(node: TriggerNode): node is TestableTriggerNode<TriggerNodeConfig> {
+    return typeof (node as Partial<TestableTriggerNode<TriggerNodeConfig>>).getTestItems === "function";
+  }
+}

package/src/orchestration/index.ts

@@ -0,0 +1,5 @@
+export { Engine } from "./Engine";
+export { EngineWaiters } from "./EngineWaiters";
+export { RunContinuationService } from "./RunContinuationService";
+export { RunStartService } from "./RunStartService";
+export { TriggerRuntimeService } from "./TriggerRuntimeService";

package/src/planning/CurrentStateFrontierPlanner.ts

@@ -0,0 +1,400 @@
+import type {
+  ExecutionFrontierPlan,
+  InputPortKey,
+  Items,
+  NodeId,
+  NodeOutputs,
+  OutputPortKey,
+  RunCurrentState,
+  PersistedMutableNodeState,
+  RunQueueEntry,
+  RunStateResetRequest,
+  RunStopCondition,
+  ConnectionInvocationRecord,
+} from "../types";
+
+import { ConnectionNodeIdFactory } from "../workflow/definition/ConnectionNodeIdFactory";
+import { WorkflowTopology } from "./WorkflowTopologyPlanner";
+
+export class CurrentStateFrontierPlanner {
+  constructor(private readonly topology: WorkflowTopology) {}
+
+  /** Composition-root-friendly factory (avoids `new` at orchestration call sites under ESLint manual-DI rules). */
+  static createFromTopology(topology: WorkflowTopology): CurrentStateFrontierPlanner {
+    return new CurrentStateFrontierPlanner(topology);
+  }
+
+  plan(args: {
+    currentState?: RunCurrentState;
+    stopCondition?: RunStopCondition;
+    reset?: RunStateResetRequest;
+    items?: Items;
+  }): ExecutionFrontierPlan {
+    const stopCondition = args.stopCondition ?? { kind: "workflowCompleted" as const };
+    const baseState = this.cloneCurrentState(args.currentState);
+    const normalizedState = this.overlayPinnedOutputs(baseState);
+    const resetResult = this.applyReset({ currentState: normalizedState, reset: args.reset });
+    const requiredNodeIds = this.collectRequiredNodeIds(stopCondition, resetResult.currentState);
+    const satisfiedNodeIds = this.collectSatisfiedNodeIds(resetResult.currentState);
+    const skippedNodeIds = [
+      ...new Set([
+        ...[...requiredNodeIds].filter((nodeId) => this.isNodeSatisfied(resetResult.currentState, nodeId)),
+        ...resetResult.preservedPinnedNodeIds.filter((nodeId) => requiredNodeIds.has(nodeId)),
+      ]),
+    ];
+    const frontierNodeIds = this.collectFrontierNodeIds(requiredNodeIds, resetResult.currentState);
+    const rootNodeIds = frontierNodeIds.filter(
+      (nodeId) => (this.topology.incomingByNode.get(nodeId) ?? []).length === 0,
+    );
+
+    if (rootNodeIds.length > 1) {
+      throw new Error(`Ambiguous execution frontier. Multiple root nodes require input: ${rootNodeIds.join(", ")}`);
+    }
+
+    if (frontierNodeIds.length === 0) {
+      return {
+        queue: [],
+        currentState: resetResult.currentState,
+        stopCondition,
+        satisfiedNodeIds,
+        skippedNodeIds,
+        clearedNodeIds: resetResult.clearedNodeIds,
+        preservedPinnedNodeIds: resetResult.preservedPinnedNodeIds,
+      };
+    }
+
+    if (rootNodeIds.length === 1) {
+      const rootNodeId = rootNodeIds[0]!;
+      const definition = this.topology.defsById.get(rootNodeId);
+      if (!definition) {
+        throw new Error(`Unknown frontier nodeId: ${rootNodeId}`);
+      }
+      return {
+        rootNodeId,
+        rootNodeInput: this.resolveRootNodeInput({ nodeKind: definition.kind, items: args.items }),
+        queue: [],
+        currentState: resetResult.currentState,
+        stopCondition,
+        satisfiedNodeIds,
+        skippedNodeIds,
+        clearedNodeIds: resetResult.clearedNodeIds,
+        preservedPinnedNodeIds: resetResult.preservedPinnedNodeIds,
+      };
+    }
+
+    const queue: RunQueueEntry[] = [];
+    for (const nodeId of frontierNodeIds) {
+      queue.push(...this.buildFrontierQueue(nodeId, resetResult.currentState));
+    }
+
+    return {
+      queue,
+      currentState: resetResult.currentState,
+      stopCondition,
+      satisfiedNodeIds,
+      skippedNodeIds,
+      clearedNodeIds: resetResult.clearedNodeIds,
+      preservedPinnedNodeIds: resetResult.preservedPinnedNodeIds,
+    };
+  }
+
+  private cloneCurrentState(currentState: RunCurrentState | undefined): RunCurrentState {
+    if (!currentState) {
+      return {
+        outputsByNode: {},
+        nodeSnapshotsByNodeId: {},
+        connectionInvocations: [],
+        mutableState: undefined,
+      };
+    }
+    return {
+      outputsByNode: { ...currentState.outputsByNode },
+      nodeSnapshotsByNodeId: { ...currentState.nodeSnapshotsByNodeId },
+      connectionInvocations: currentState.connectionInvocations ? [...currentState.connectionInvocations] : undefined,
+      mutableState: currentState.mutableState,
+    };
+  }
+
+  private overlayPinnedOutputs(currentState: RunCurrentState): RunCurrentState {
+    const outputsByNode: Record<NodeId, NodeOutputs> = { ...currentState.outputsByNode };
+    for (const [nodeId, nodeState] of Object.entries(currentState.mutableState?.nodesById ?? {}) as Array<
+      [NodeId, PersistedMutableNodeState]
+    >) {
+      const pinnedOutputs = nodeState.pinnedOutputsByPort;
+      if (!pinnedOutputs) {
+        continue;
+      }
+      outputsByNode[nodeId] = pinnedOutputs;
+    }
+    return {
+      outputsByNode,
+      nodeSnapshotsByNodeId: { ...currentState.nodeSnapshotsByNodeId },
+      connectionInvocations: currentState.connectionInvocations,
+      mutableState: currentState.mutableState,
+    };
+  }
+
+  private applyReset(args: { currentState: RunCurrentState; reset?: RunStateResetRequest }): Readonly<{
+    currentState: RunCurrentState;
+    clearedNodeIds: ReadonlyArray<NodeId>;
+    preservedPinnedNodeIds: ReadonlyArray<NodeId>;
+  }> {
+    if (!args.reset) {
+      return {
+        currentState: args.currentState,
+        clearedNodeIds: [],
+        preservedPinnedNodeIds: [],
+      };
+    }
+
+    const outputsByNode: Record<NodeId, NodeOutputs> = { ...args.currentState.outputsByNode };
+    const nodeSnapshotsByNodeId = { ...args.currentState.nodeSnapshotsByNodeId };
+    const clearedNodeIds: NodeId[] = [];
+    const preservedPinnedNodeIds: NodeId[] = [];
+    const descendants = this.collectDescendants(args.reset.clearFromNodeId);
+    const runtimeDescendants = this.collectRuntimeDescendants(args.currentState, descendants);
+    const clearedIdSet = new Set<NodeId>([...descendants, ...runtimeDescendants]);
+
+    for (const nodeId of [...descendants, ...runtimeDescendants]) {
+      const pinnedOutputs = this.getPinnedOutputs(args.currentState, nodeId);
+      if (pinnedOutputs) {
+        outputsByNode[nodeId] = pinnedOutputs;
+        delete nodeSnapshotsByNodeId[nodeId];
+        preservedPinnedNodeIds.push(nodeId);
+        continue;
+      }
+      delete outputsByNode[nodeId];
+      delete nodeSnapshotsByNodeId[nodeId];
+      clearedNodeIds.push(nodeId);
+    }
+
+    return {
+      currentState: {
+        outputsByNode,
+        nodeSnapshotsByNodeId,
+        connectionInvocations: this.filterConnectionInvocations(args.currentState.connectionInvocations, clearedIdSet),
+        mutableState: args.currentState.mutableState,
+      },
+      clearedNodeIds,
+      preservedPinnedNodeIds,
+    };
+  }
+
+  private collectSatisfiedNodeIds(currentState: RunCurrentState): ReadonlyArray<NodeId> {
+    const satisfiedNodeIds: NodeId[] = [];
+    for (const nodeId of this.topology.defsById.keys()) {
+      if (this.isNodeSatisfied(currentState, nodeId)) {
+        satisfiedNodeIds.push(nodeId);
+      }
+    }
+    return satisfiedNodeIds;
+  }
+
+  private collectFrontierNodeIds(
+    requiredNodeIds: ReadonlySet<NodeId>,
+    currentState: RunCurrentState,
+  ): ReadonlyArray<NodeId> {
+    const frontierNodeIds: NodeId[] = [];
+    for (const nodeId of this.topology.defsById.keys()) {
+      if (!requiredNodeIds.has(nodeId) || this.isNodeSatisfied(currentState, nodeId)) {
+        continue;
+      }
+      const incomingEdges = this.topology.incomingByNode.get(nodeId) ?? [];
+      const isFrontier = incomingEdges.every((edge) => this.isEdgeSatisfied(currentState, nodeId, edge.input));
+      if (isFrontier) {
+        frontierNodeIds.push(nodeId);
+      }
+    }
+    return frontierNodeIds;
+  }
+
+  private collectRequiredNodeIds(stopCondition: RunStopCondition, currentState: RunCurrentState): ReadonlySet<NodeId> {
+    const requiredNodeIds = new Set<NodeId>();
+    if (stopCondition.kind === "workflowCompleted") {
+      for (const nodeId of this.topology.defsById.keys()) {
+        if (!this.isNodeSatisfied(currentState, nodeId)) {
+          this.collectRequiredNode(requiredNodeIds, currentState, nodeId);
+        }
+      }
+      return requiredNodeIds;
+    }
+    if (!this.topology.defsById.has(stopCondition.nodeId)) {
+      throw new Error(`Unknown stop nodeId: ${stopCondition.nodeId}`);
+    }
+    this.collectRequiredNode(requiredNodeIds, currentState, stopCondition.nodeId);
+    return requiredNodeIds;
+  }
+
+  private collectRequiredNode(requiredNodeIds: Set<NodeId>, currentState: RunCurrentState, nodeId: NodeId): void {
+    if (requiredNodeIds.has(nodeId)) {
+      return;
+    }
+    if (this.isNodeSatisfied(currentState, nodeId) && !this.isNodeSatisfiedByOutputsOnly(currentState, nodeId)) {
+      return;
+    }
+    requiredNodeIds.add(nodeId);
+    for (const edge of this.topology.incomingByNode.get(nodeId) ?? []) {
+      if (
+        !this.isEdgeSatisfied(currentState, nodeId, edge.input) ||
+        this.isNodeSatisfiedByOutputsOnly(currentState, edge.from.nodeId)
+      ) {
+        this.collectRequiredNode(requiredNodeIds, currentState, edge.from.nodeId);
+      }
+    }
+  }
+
+  private buildFrontierQueue(nodeId: NodeId, currentState: RunCurrentState): ReadonlyArray<RunQueueEntry> {
+    const incomingEdges = this.topology.incomingByNode.get(nodeId) ?? [];
+    if (incomingEdges.length === 0) {
+      return [];
+    }
+    const expectedInputs = this.topology.expectedInputsByNode.get(nodeId) ?? [];
+    const usesCollect = expectedInputs.length !== 1 || expectedInputs[0] !== "in";
+    if (usesCollect) {
+      const received: Record<InputPortKey, Items> = {};
+      for (const input of expectedInputs) {
+        received[input] = this.resolveInput(currentState, nodeId, input);
+      }
+      return [
+        {
+          nodeId,
+          input: [],
+          batchId: "batch_1",
+          collect: {
+            expectedInputs,
+            received,
+          },
+        },
+      ];
+    }
+    const input = expectedInputs[0] ?? "in";
+    const incomingEdge = incomingEdges.find((edge) => edge.input === input);
+    return [
+      {
+        nodeId,
+        input: this.resolveInput(currentState, nodeId, input),
+        toInput: input,
+        batchId: "batch_1",
+        from: incomingEdge?.from,
+      },
+    ];
+  }
+
+  private resolveRootNodeInput(args: { nodeKind: "node" | "trigger"; items?: Items }): Items {
+    if (args.items) {
+      return args.items;
+    }
+    if (args.nodeKind === "trigger") {
+      return [];
+    }
+    return [{ json: {} }];
+  }
+
+  private isNodeSatisfied(currentState: RunCurrentState, nodeId: NodeId): boolean {
+    return this.hasOutputs(currentState, nodeId) || this.hasCompletedSnapshot(currentState, nodeId);
+  }
+
+  private isNodeSatisfiedByOutputsOnly(currentState: RunCurrentState, nodeId: NodeId): boolean {
+    return this.hasOutputs(currentState, nodeId) && !this.hasCompletedSnapshot(currentState, nodeId);
+  }
+
+  private isEdgeSatisfied(currentState: RunCurrentState, nodeId: NodeId, input: InputPortKey): boolean {
+    const incomingEdge = (this.topology.incomingByNode.get(nodeId) ?? []).find((edge) => edge.input === input);
+    if (!incomingEdge) {
+      return false;
+    }
+    return this.hasOutputPort(currentState, incomingEdge.from.nodeId, incomingEdge.from.output);
+  }
+
+  private resolveInput(currentState: RunCurrentState, nodeId: NodeId, input: InputPortKey): Items {
+    const incomingEdge = (this.topology.incomingByNode.get(nodeId) ?? []).find((edge) => edge.input === input);
+    if (!incomingEdge) {
+      return [];
+    }
+    return this.resolveOutputItems(currentState, incomingEdge.from.nodeId, incomingEdge.from.output);
+  }
+
+  private hasOutputs(currentState: RunCurrentState, nodeId: NodeId): boolean {
+    return Object.prototype.hasOwnProperty.call(currentState.outputsByNode, nodeId);
+  }
+
+  private hasCompletedSnapshot(currentState: RunCurrentState, nodeId: NodeId): boolean {
+    const snapshot = currentState.nodeSnapshotsByNodeId[nodeId];
+    return snapshot?.status === "completed" || snapshot?.status === "skipped";
+  }
+
+  private hasOutputPort(currentState: RunCurrentState, nodeId: NodeId, output: OutputPortKey): boolean {
+    const outputs = currentState.outputsByNode[nodeId];
+    if (!outputs) {
+      return false;
+    }
+    return Object.prototype.hasOwnProperty.call(outputs, output);
+  }
+
+  private resolveOutputItems(currentState: RunCurrentState, nodeId: NodeId, output: OutputPortKey): Items {
+    return currentState.outputsByNode[nodeId]?.[output] ?? [];
+  }
+
+  private getPinnedOutputs(currentState: RunCurrentState, nodeId: NodeId): NodeOutputs | undefined {
+    return currentState.mutableState?.nodesById?.[nodeId]?.pinnedOutputsByPort;
+  }
+
+  private filterConnectionInvocations(
+    invocations: ReadonlyArray<ConnectionInvocationRecord> | undefined,
+    clearedIdSet: ReadonlySet<NodeId>,
+  ): ReadonlyArray<ConnectionInvocationRecord> | undefined {
+    if (!invocations || invocations.length === 0) {
+      return invocations;
+    }
+    const kept = invocations.filter(
+      (invocation) => !clearedIdSet.has(invocation.parentAgentNodeId) && !clearedIdSet.has(invocation.connectionNodeId),
+    );
+    return kept.length === invocations.length ? invocations : kept;
+  }
+
+  private collectDescendants(startNodeId: NodeId): ReadonlyArray<NodeId> {
+    const pendingNodeIds: NodeId[] = [startNodeId];
+    const descendants = new Set<NodeId>();
+    while (pendingNodeIds.length > 0) {
+      const nodeId = pendingNodeIds.pop();
+      if (!nodeId || descendants.has(nodeId)) {
+        continue;
+      }
+      descendants.add(nodeId);
+      for (const edge of this.topology.outgoingByNode.get(nodeId) ?? []) {
+        pendingNodeIds.push(edge.to.nodeId);
+      }
+    }
+    return [...descendants];
+  }
+
+  private collectRuntimeDescendants(
+    currentState: RunCurrentState,
+    descendantNodeIds: ReadonlyArray<NodeId>,
+  ): ReadonlyArray<NodeId> {
+    const descendantSet = new Set(descendantNodeIds);
+    const runtimeNodeIds = new Set<NodeId>();
+    for (const nodeId of [
+      ...Object.keys(currentState.outputsByNode),
+      ...Object.keys(currentState.nodeSnapshotsByNodeId),
+      ...Object.keys(currentState.mutableState?.nodesById ?? {}),
+    ] as NodeId[]) {
+      if (this.isRuntimeDescendant(nodeId, descendantSet)) {
+        runtimeNodeIds.add(nodeId);
+      }
+    }
+    return [...runtimeNodeIds];
+  }
+
+  private isRuntimeDescendant(nodeId: NodeId, descendantNodeIds: ReadonlySet<NodeId>): boolean {
+    for (const descendantNodeId of descendantNodeIds) {
+      if (nodeId === descendantNodeId) {
+        return false;
+      }
+      if (ConnectionNodeIdFactory.isConnectionOwnedDescendantOf(descendantNodeId, nodeId)) {
+        return true;
+      }
+    }
+    return false;
+  }
+}