@codemation/core 0.0.18 → 0.2.0

package/src/testing/PrefixedSequentialIdGenerator.ts

@@ -0,0 +1,17 @@
+/**
+ * Deterministic `run_1`, `act_1`-style ids for test harness factories.
+ */
+export class PrefixedSequentialIdGenerator {
+  private n = 0;
+
+  constructor(private readonly prefix: string) {}
+
+  next(): string {
+    this.n += 1;
+    return `${this.prefix}${this.n}`;
+  }
+
+  asFn(): () => string {
+    return () => this.next();
+  }
+}

package/src/testing/RegistrarEngineTestKit.types.ts

@@ -0,0 +1,76 @@
+import type { DependencyContainer, InjectionToken } from "tsyringe";
+
+import type { EngineExecutionLimitsPolicy } from "../policies";
+import type { Container } from "../di";
+import type { RunEventBus } from "../events/runEvents";
+import type {
+  CredentialSessionService,
+  ExecutionContextFactory,
+  Items,
+  NodeExecutionScheduler,
+  NodeOffloadPolicy,
+  ParentExecutionRef,
+  RunDataFactory,
+  RunResult,
+  TriggerSetupStateRepository,
+  WorkflowExecutionRepository,
+  WorkflowDefinition,
+} from "../types";
+import type { EngineRuntimeRegistrationOptions } from "../bootstrap/runtime/EngineRuntimeRegistration.types";
+import type { Engine } from "../orchestration/Engine";
+import type { InMemoryLiveWorkflowRepository } from "../runtime/InMemoryLiveWorkflowRepository";
+import type { EngineWorkflowRunnerService } from "../runtime/EngineWorkflowRunnerService";
+import type { RunIntentService } from "../runtime/RunIntentService";
+
+import type { CapturingScheduler } from "./CapturingScheduler";
+
+export type EngineTestKitOptions = Partial<{
+  container: Container;
+  providers: Map<InjectionToken<unknown>, unknown>;
+  credentialSessions: CredentialSessionService;
+  runStore: WorkflowExecutionRepository;
+  scheduler: NodeExecutionScheduler;
+  offloadPolicy: NodeOffloadPolicy;
+  runDataFactory: RunDataFactory;
+  executionContextFactory: ExecutionContextFactory;
+  eventBus: RunEventBus;
+  triggerSetupStateRepository: TriggerSetupStateRepository;
+  webhookBasePath: string;
+  makeRunId: () => string;
+  makeActivationId: () => string;
+  workflowRunner: EngineWorkflowRunnerService;
+  /** Passed to engine factory so integration tests can assert host-configured limits propagate. */
+  executionLimitsPolicy: EngineExecutionLimitsPolicy;
+}>;
+
+export type RegistrarEngineTestKitOptions = EngineTestKitOptions & {
+  /** Passed to {@link EngineRuntimeRegistrar.register}. */
+  registrarOptions?: EngineRuntimeRegistrationOptions;
+};
+
+export interface RegistrarEngineTestKitHandle {
+  readonly engine: Engine;
+  readonly runIntent: RunIntentService;
+  readonly liveWorkflowRepository: InMemoryLiveWorkflowRepository;
+  readonly runStore: WorkflowExecutionRepository;
+  readonly triggerSetupStateRepository: TriggerSetupStateRepository;
+  readonly scheduler: CapturingScheduler | NodeExecutionScheduler;
+  readonly offloadPolicy: NodeOffloadPolicy;
+  readonly workflowRunner: EngineWorkflowRunnerService;
+  readonly dependencyContainer: DependencyContainer;
+  start(workflows: ReadonlyArray<WorkflowDefinition>): Promise<void>;
+  runToCompletion(args: {
+    wf: WorkflowDefinition;
+    startAt: string;
+    items: Items;
+    parent?: ParentExecutionRef;
+  }): Promise<RunResult>;
+  runIntentStartToCompletion(args: {
+    wf: WorkflowDefinition;
+    startAt: string;
+    items: Items;
+    parent?: ParentExecutionRef;
+  }): Promise<RunResult>;
+  readonly makeRunId: () => string;
+  readonly makeActivationId: () => string;
+}

package/src/testing/RegistrarEngineTestKitFactory.ts

@@ -0,0 +1,154 @@
+import type { DependencyContainer, InjectionToken } from "tsyringe";
+import { container as tsyringeContainer } from "tsyringe";
+
+import type { WorkflowRunnerService } from "../contracts/runtimeTypes";
+import { CoreTokens } from "../di";
+import { InMemoryRunEventBus } from "../events/InMemoryRunEventBusRegistry";
+import { AllWorkflowsActiveWorkflowActivationPolicy } from "../contracts/workflowActivationPolicy";
+import { RunIntentService } from "../runtime/RunIntentService";
+import {
+  DefaultDrivingScheduler,
+  DefaultAsyncSleeper,
+  DefaultExecutionContextFactory,
+  Engine,
+  EngineRuntimeRegistrar,
+  EngineWorkflowRunnerService,
+  HintOnlyOffloadPolicy,
+  InProcessRetryRunner,
+  InMemoryRunDataFactory,
+  InMemoryWorkflowExecutionRepository,
+  InlineDrivingScheduler,
+  NodeExecutor,
+  NodeInstanceFactory,
+  PersistedWorkflowTokenRegistry,
+} from "../bootstrap/index";
+import { InMemoryLiveWorkflowRepository } from "../runtime/InMemoryLiveWorkflowRepository";
+import { EngineTestKitRunIdFactory } from "./EngineTestKitRunIdFactory";
+import { InMemoryTriggerSetupStateRepository } from "./InMemoryTriggerSetupStateRepository";
+import { RejectingCredentialSessionService } from "./RejectingCredentialSessionService";
+import { CapturingScheduler } from "./CapturingScheduler";
+import { PrefixedSequentialIdGenerator } from "./PrefixedSequentialIdGenerator";
+import type { RegistrarEngineTestKitHandle, RegistrarEngineTestKitOptions } from "./RegistrarEngineTestKit.types";
+import { SubWorkflowRunnerNode } from "./SubWorkflowRunnerTestNode";
+import { WorkflowTestHarnessManualTriggerNode } from "./WorkflowTestHarnessManualTrigger";
+
+export class RegistrarEngineTestKitFactory {
+  static create(options: RegistrarEngineTestKitOptions = {}): RegistrarEngineTestKitHandle {
+    const runStore = options.runStore ?? new InMemoryWorkflowExecutionRepository();
+    const scheduler = options.scheduler ?? new CapturingScheduler();
+    const offloadPolicy = options.offloadPolicy ?? new HintOnlyOffloadPolicy();
+    const runIdGen = new PrefixedSequentialIdGenerator("run_");
+    const activationIdGen = new PrefixedSequentialIdGenerator("act_");
+    const makeRunId = options.makeRunId ?? runIdGen.asFn();
+    const makeActivationId = options.makeActivationId ?? activationIdGen.asFn();
+    const credentialSessions = options.credentialSessions ?? new RejectingCredentialSessionService();
+    const eventBus = options.eventBus ?? new InMemoryRunEventBus();
+    const triggerSetupStateRepository =
+      options.triggerSetupStateRepository ?? new InMemoryTriggerSetupStateRepository();
+    const liveWorkflowRepository = new InMemoryLiveWorkflowRepository();
+    const runDataFactory = options.runDataFactory ?? new InMemoryRunDataFactory();
+    const executionContextFactory = options.executionContextFactory ?? new DefaultExecutionContextFactory();
+    const container = options.container ?? tsyringeContainer.createChildContainer();
+    const dependencyContainer = container as DependencyContainer;
+    const nodeResolver = container;
+    const nodeExecutor = new NodeExecutor(
+      new NodeInstanceFactory(nodeResolver),
+      new InProcessRetryRunner(new DefaultAsyncSleeper()),
+    );
+    const activationScheduler = new DefaultDrivingScheduler(
+      offloadPolicy,
+      scheduler,
+      new InlineDrivingScheduler(nodeExecutor),
+    );
+
+    for (const [token, value] of options.providers ?? new Map<InjectionToken<unknown>, unknown>()) {
+      dependencyContainer.registerInstance(token, value);
+    }
+
+    dependencyContainer.registerInstance(CoreTokens.CredentialSessionService, credentialSessions);
+    dependencyContainer.registerInstance(CoreTokens.LiveWorkflowRepository, liveWorkflowRepository);
+    dependencyContainer.registerInstance(CoreTokens.WorkflowRepository, liveWorkflowRepository);
+    dependencyContainer.registerInstance(CoreTokens.NodeResolver, nodeResolver);
+    dependencyContainer.registerInstance(
+      CoreTokens.RunIdFactory,
+      new EngineTestKitRunIdFactory(makeRunId, makeActivationId),
+    );
+    dependencyContainer.registerInstance(
+      CoreTokens.ActivationIdFactory,
+      new EngineTestKitRunIdFactory(makeRunId, makeActivationId),
+    );
+    dependencyContainer.registerInstance(CoreTokens.WebhookBasePath, options.webhookBasePath ?? "/webhooks");
+    dependencyContainer.registerInstance(CoreTokens.WorkflowExecutionRepository, runStore);
+    dependencyContainer.registerInstance(CoreTokens.TriggerSetupStateRepository, triggerSetupStateRepository);
+    dependencyContainer.registerInstance(CoreTokens.NodeActivationScheduler, activationScheduler);
+    dependencyContainer.registerInstance(CoreTokens.RunDataFactory, runDataFactory);
+    dependencyContainer.registerInstance(CoreTokens.ExecutionContextFactory, executionContextFactory);
+    dependencyContainer.registerInstance(CoreTokens.RunEventBus, eventBus);
+    dependencyContainer.registerInstance(
+      CoreTokens.PersistedWorkflowTokenRegistry,
+      new PersistedWorkflowTokenRegistry(),
+    );
+    dependencyContainer.registerInstance(
+      CoreTokens.WorkflowActivationPolicy,
+      new AllWorkflowsActiveWorkflowActivationPolicy(),
+    );
+
+    if (options.executionLimitsPolicy !== undefined) {
+      dependencyContainer.registerInstance(CoreTokens.EngineExecutionLimitsPolicy, options.executionLimitsPolicy);
+    }
+
+    new EngineRuntimeRegistrar().register(dependencyContainer, options.registrarOptions ?? {});
+
+    const engine = dependencyContainer.resolve(Engine);
+    const runIntent = dependencyContainer.resolve(RunIntentService);
+    const workflowRunner =
+      options.workflowRunner ??
+      (dependencyContainer.resolve(CoreTokens.WorkflowRunnerService) as EngineWorkflowRunnerService);
+    dependencyContainer.registerInstance(
+      SubWorkflowRunnerNode,
+      new SubWorkflowRunnerNode(workflowRunner as WorkflowRunnerService),
+    );
+    dependencyContainer.registerInstance(
+      WorkflowTestHarnessManualTriggerNode,
+      new WorkflowTestHarnessManualTriggerNode(),
+    );
+
+    const start = async (workflows: ReadonlyArray<import("../types").WorkflowDefinition>): Promise<void> => {
+      await engine.start([...workflows]);
+    };
+
+    const runToCompletion: RegistrarEngineTestKitHandle["runToCompletion"] = async (args) => {
+      const r0 = await engine.runWorkflow(args.wf, args.startAt, args.items, args.parent);
+      if (r0.status !== "pending") return r0;
+      return await engine.waitForCompletion(r0.runId);
+    };
+
+    const runIntentStartToCompletion: RegistrarEngineTestKitHandle["runIntentStartToCompletion"] = async (args) => {
+      const r0 = await runIntent.startWorkflow({
+        workflow: args.wf,
+        startAt: args.startAt,
+        items: args.items,
+        parent: args.parent,
+      });
+      if (r0.status !== "pending") return r0;
+      return await engine.waitForCompletion(r0.runId);
+    };
+
+    return {
+      engine,
+      runIntent,
+      liveWorkflowRepository,
+      runStore,
+      triggerSetupStateRepository,
+      scheduler: scheduler as CapturingScheduler | import("../types").NodeExecutionScheduler,
+      offloadPolicy,
+      workflowRunner,
+      dependencyContainer,
+      start,
+      runToCompletion,
+      runIntentStartToCompletion,
+      makeRunId,
+      makeActivationId,
+    };
+  }
+}

package/src/testing/SubWorkflowRunnerTestNode.ts

@@ -0,0 +1,83 @@
+/* eslint-disable codemation/single-class-per-file -- Runnable config and implementation share a TypeToken pairing. */
+import type { WorkflowRunnerService } from "../contracts/runtimeTypes";
+import type { TypeToken } from "../di";
+import type {
+  Item,
+  Items,
+  NodeExecutionContext,
+  NodeId,
+  NodeOutputs,
+  Node,
+  RunnableNodeConfig,
+  WorkflowId,
+} from "../types";
+
+/**
+ * Test harness subworkflow runner (mirrors integration patterns; lives under {@link "@codemation/core/testing"}).
+ */
+export class SubWorkflowRunnerConfig<TInputJson = unknown, TOutputJson = unknown> implements RunnableNodeConfig<
+  TInputJson,
+  TOutputJson
+> {
+  readonly kind = "node" as const;
+  readonly type: TypeToken<unknown> = SubWorkflowRunnerNode;
+
+  constructor(
+    public readonly name: string,
+    public readonly args: Readonly<{
+      workflowId: WorkflowId;
+      startAt?: NodeId;
+      id?: string;
+      execution?: Readonly<{ hint?: "local" | "worker"; queue?: string }>;
+    }>,
+  ) {}
+
+  get id(): string | undefined {
+    return this.args.id;
+  }
+
+  get execution(): Readonly<{ hint?: "local" | "worker"; queue?: string }> | undefined {
+    return this.args.execution;
+  }
+
+  get workflowId(): WorkflowId {
+    return this.args.workflowId;
+  }
+
+  get startAt(): NodeId | undefined {
+    return this.args.startAt;
+  }
+}
+
+export class SubWorkflowRunnerNode implements Node<SubWorkflowRunnerConfig<any, any>> {
+  readonly kind = "node" as const;
+  readonly outputPorts = ["main"] as const;
+
+  constructor(private readonly workflows: WorkflowRunnerService) {}
+
+  async execute(items: Items, ctx: NodeExecutionContext<SubWorkflowRunnerConfig<any, any>>): Promise<NodeOutputs> {
+    const out: Item[] = [];
+    for (let i = 0; i < items.length; i++) {
+      const current = items[i]!;
+      const result = await this.workflows.runById({
+        workflowId: ctx.config.workflowId,
+        startAt: ctx.config.startAt,
+        items: [current],
+        parent: {
+          runId: ctx.runId,
+          workflowId: ctx.workflowId,
+          nodeId: ctx.nodeId,
+          subworkflowDepth: ctx.subworkflowDepth,
+          engineMaxNodeActivations: ctx.engineMaxNodeActivations,
+          engineMaxSubworkflowDepth: ctx.engineMaxSubworkflowDepth,
+        },
+      });
+      if (result.status !== "completed") {
+        throw new Error(`Subworkflow ${ctx.config.workflowId} did not complete (status=${result.status})`);
+      }
+      out.push(...result.outputs);
+    }
+
+    return { main: out };
+  }
+}

package/src/testing/WorkflowTestHarnessManualTrigger.ts

@@ -0,0 +1,39 @@
+/* eslint-disable codemation/single-class-per-file -- Trigger config and implementation share a TypeToken pairing. */
+import type { TypeToken } from "../di";
+import type {
+  Items,
+  NodeExecutionContext,
+  NodeOutputs,
+  TriggerNode,
+  TriggerNodeConfig,
+  TriggerSetupContext,
+} from "../types";
+
+/**
+ * Minimal pass-through manual trigger for {@link WorkflowTestKit.runNode}; emits input items unchanged.
+ */
+export class WorkflowTestHarnessManualTriggerConfig implements TriggerNodeConfig<unknown> {
+  readonly kind = "trigger" as const;
+  readonly type: TypeToken<unknown> = WorkflowTestHarnessManualTriggerNode;
+
+  constructor(
+    public readonly name: string,
+    public readonly id?: string,
+  ) {}
+}
+
+export class WorkflowTestHarnessManualTriggerNode implements TriggerNode<WorkflowTestHarnessManualTriggerConfig> {
+  readonly kind = "trigger" as const;
+  readonly outputPorts = ["main"] as const;
+
+  async setup(_ctx: TriggerSetupContext<WorkflowTestHarnessManualTriggerConfig>): Promise<undefined> {
+    return undefined;
+  }
+
+  async execute(
+    items: Items,
+    _ctx: NodeExecutionContext<WorkflowTestHarnessManualTriggerConfig>,
+  ): Promise<NodeOutputs> {
+    return { main: items };
+  }
+}

package/src/testing/WorkflowTestKit.types.ts

@@ -0,0 +1,9 @@
+import type { TypeToken } from "../di";
+
+export type DefinedNodeRegistrationContext = {
+  registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void;
+};
+
+export type DefinedNodeRegistration = {
+  register(context: DefinedNodeRegistrationContext): void;
+};

package/src/testing/WorkflowTestKitBuilder.ts

@@ -0,0 +1,77 @@
+import type { DependencyContainer } from "tsyringe";
+
+import type { Items, NodeId, RunnableNodeConfig, RunResult, WorkflowDefinition, WorkflowId } from "../types";
+
+import { RegistrarEngineTestKitFactory } from "./RegistrarEngineTestKitFactory";
+import type { EngineTestKitOptions, RegistrarEngineTestKitHandle } from "./RegistrarEngineTestKit.types";
+import { WorkflowTestKitNodeRegistrationContextFactory } from "./WorkflowTestKitNodeRegistrationContextFactory";
+import type { DefinedNodeRegistration } from "./WorkflowTestKit.types";
+import { WorkflowTestKitRunNodeWorkflowFactory } from "./WorkflowTestKitRunNodeWorkflowFactory";
+
+export type { DefinedNodeRegistration, DefinedNodeRegistrationContext } from "./WorkflowTestKit.types";
+
+export type WorkflowTestKitOptions = EngineTestKitOptions;
+
+export class WorkflowTestKit {
+  private readonly handle: RegistrarEngineTestKitHandle;
+  private readonly runNodeWorkflowFactory = new WorkflowTestKitRunNodeWorkflowFactory();
+  private readonly nodeRegistrationContextFactory = new WorkflowTestKitNodeRegistrationContextFactory();
+
+  constructor(options: WorkflowTestKitOptions = {}) {
+    this.handle = RegistrarEngineTestKitFactory.create(options);
+  }
+
+  get dependencyContainer(): DependencyContainer {
+    return this.handle.dependencyContainer;
+  }
+
+  get engine(): RegistrarEngineTestKitHandle["engine"] {
+    return this.handle.engine;
+  }
+
+  get workflowRunner(): RegistrarEngineTestKitHandle["workflowRunner"] {
+    return this.handle.workflowRunner;
+  }
+
+  get liveWorkflowRepository(): RegistrarEngineTestKitHandle["liveWorkflowRepository"] {
+    return this.handle.liveWorkflowRepository;
+  }
+
+  get runStore(): RegistrarEngineTestKitHandle["runStore"] {
+    return this.handle.runStore;
+  }
+
+  /**
+   * Registers {@link import("../authoring/defineNode.types").DefinedNode} implementations on the same DI container used by the engine
+   * (same pattern as `plugin.register({ registerNode })` in the host).
+   */
+  registerDefinedNodes(definitions: ReadonlyArray<DefinedNodeRegistration>): void {
+    const ctx = this.nodeRegistrationContextFactory.create(this.handle.dependencyContainer);
+    for (const def of definitions) {
+      def.register(ctx);
+    }
+  }
+
+  async run(args: { workflow: WorkflowDefinition; items: Items; startAt?: NodeId }): Promise<RunResult> {
+    await this.handle.start([args.workflow]);
+    return await this.handle.workflowRunner.runById({
+      workflowId: args.workflow.id,
+      startAt: args.startAt,
+      items: args.items,
+    });
+  }
+
+  async runNode(args: {
+    node: RunnableNodeConfig;
+    items: Items;
+    workflowId?: WorkflowId;
+    workflowName?: string;
+  }): Promise<RunResult> {
+    const wf = this.runNodeWorkflowFactory.build(args);
+    return await this.run({
+      workflow: wf,
+      items: args.items,
+      startAt: this.runNodeWorkflowFactory.defaultStartNodeId(),
+    });
+  }
+}

package/src/testing/WorkflowTestKitNodeRegistrationContextFactory.ts

@@ -0,0 +1,17 @@
+import type { DependencyContainer } from "tsyringe";
+
+import type { TypeToken } from "../di";
+
+import type { DefinedNodeRegistrationContext } from "./WorkflowTestKit.types";
+
+export class WorkflowTestKitNodeRegistrationContextFactory {
+  create(dependencyContainer: DependencyContainer): DefinedNodeRegistrationContext {
+    return {
+      registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>) {
+        dependencyContainer.register(token, {
+          useClass: (implementation ?? token) as never,
+        });
+      },
+    };
+  }
+}

package/src/testing/WorkflowTestKitRunNodeWorkflowFactory.ts

@@ -0,0 +1,26 @@
+import type { RunnableNodeConfig, WorkflowDefinition, WorkflowId } from "../types";
+import { WorkflowBuilder } from "../workflow/dsl/WorkflowBuilder";
+
+import { WorkflowTestHarnessManualTriggerConfig } from "./WorkflowTestHarnessManualTrigger";
+
+const defaultInlineWorkflowId = "codemation.testing.workflowkit.inline" as WorkflowId;
+const defaultInlineWorkflowName = "WorkflowTestKit inline";
+
+/**
+ * Builds the minimal trigger → runnable workflow used by {@link import("./WorkflowTestKit").WorkflowTestKit.runNode}.
+ */
+export class WorkflowTestKitRunNodeWorkflowFactory {
+  build(args: { node: RunnableNodeConfig; workflowId?: WorkflowId; workflowName?: string }): WorkflowDefinition {
+    const workflowId = args.workflowId ?? defaultInlineWorkflowId;
+    const workflowName = args.workflowName ?? defaultInlineWorkflowName;
+    const trigger = new WorkflowTestHarnessManualTriggerConfig(
+      "WorkflowTestKit trigger",
+      "workflowkit.harness.trigger",
+    );
+    return new WorkflowBuilder({ id: workflowId, name: workflowName }).trigger(trigger).then(args.node).build();
+  }
+
+  defaultStartNodeId(): string {
+    return "workflowkit.harness.trigger";
+  }
+}

package/src/testing.ts

@@ -4,3 +4,22 @@
 export { InMemoryLiveWorkflowRepository } from "./runtime/InMemoryLiveWorkflowRepository";
 export { WorkflowSnapshotCodec as PersistedWorkflowSnapshotFactory } from "./workflowSnapshots/WorkflowSnapshotCodec";
 export { RejectingCredentialSessionService } from "./testing/RejectingCredentialSessionService";
+export { CapturingScheduler } from "./testing/CapturingScheduler";
+export { PrefixedSequentialIdGenerator } from "./testing/PrefixedSequentialIdGenerator";
+export {
+  type EngineTestKitOptions,
+  type RegistrarEngineTestKitHandle,
+  type RegistrarEngineTestKitOptions,
+} from "./testing/RegistrarEngineTestKit.types";
+export { RegistrarEngineTestKitFactory } from "./testing/RegistrarEngineTestKitFactory";
+export { SubWorkflowRunnerConfig, SubWorkflowRunnerNode } from "./testing/SubWorkflowRunnerTestNode";
+export {
+  WorkflowTestHarnessManualTriggerConfig,
+  WorkflowTestHarnessManualTriggerNode,
+} from "./testing/WorkflowTestHarnessManualTrigger";
+export {
+  type DefinedNodeRegistration,
+  type DefinedNodeRegistrationContext,
+  WorkflowTestKit,
+  type WorkflowTestKitOptions,
+} from "./testing/WorkflowTestKitBuilder";

package/src/types/index.ts

@@ -3,6 +3,7 @@ export * from "../contracts/NoRetryPolicy";
 export * from "../contracts/RetryPolicy";
 export * from "../contracts/ExpRetryPolicy";
 export * from "../contracts/credentialTypes";
+export * from "../contracts/executionPersistenceContracts";
 export * from "../contracts/runtimeTypes";
 export * from "../contracts/runFinishedAtFactory";
 export * from "../contracts/runTypes";

package/src/workflow/definition/ConnectionNodeIdFactory.ts

@@ -24,6 +24,34 @@ export class ConnectionNodeIdFactory {
     return nodeId.includes(`${this.connectionSegment}tool${this.connectionSegment}`);
   }
 
+  static parseLanguageModelConnectionNodeId(nodeId: NodeId): Readonly<{ parentNodeId: NodeId }> | undefined {
+    if (!this.isLanguageModelConnectionNodeId(nodeId)) {
+      return undefined;
+    }
+    const suffix = `${this.connectionSegment}llm`;
+    const parentNodeId = nodeId.slice(0, -suffix.length);
+    return parentNodeId ? { parentNodeId } : undefined;
+  }
+
+  static parseToolConnectionNodeId(
+    nodeId: NodeId,
+  ): Readonly<{ parentNodeId: NodeId; normalizedToolName: string }> | undefined {
+    if (!this.isToolConnectionNodeId(nodeId)) {
+      return undefined;
+    }
+    const marker = `${this.connectionSegment}tool${this.connectionSegment}`;
+    const idx = nodeId.lastIndexOf(marker);
+    if (idx < 0) {
+      return undefined;
+    }
+    const parentNodeId = nodeId.slice(0, idx);
+    const normalizedToolName = nodeId.slice(idx + marker.length);
+    if (!parentNodeId || !normalizedToolName) {
+      return undefined;
+    }
+    return { parentNodeId, normalizedToolName };
+  }
+
   /** True when `nodeId` is a connection-owned child of `parentNodeId` (LLM or tool slot). */
   static isConnectionOwnedDescendantOf(parentNodeId: NodeId, nodeId: NodeId): boolean {
     return nodeId.startsWith(`${parentNodeId}${this.connectionSegment}`);