@decaf-ts/integrations 0.3.9 → 0.3.11

package/lib/types/graph/engine/execution/CodeGraphNodeExecutor.d.cts

@@ -0,0 +1,65 @@
+/**
+ * @module integrations/graph/execution/CodeGraphNodeExecutor
+ * @summary Executor for the Code flow-control node (DECAF-32 §22.4, DECAF-34 §7.5).
+ * @description Executes user-authored JS/TS in a restricted sandbox via the
+ * pluggable {@link CodeSandboxEvaluator}. The sandbox enforces the Code Node
+ * restrictions: no imports, no requires, pure functions only (no system API
+ * access). The executor reads the code, language, and timeout from the node's
+ * graph metadata, resolves the sandbox context from the node's input values
+ * and execution context, invokes the evaluator, and returns the result on the
+ * `result` output port.
+ */
+import type { GraphNodeExecutor } from "./GraphNodeExecutor.d.cts";
+import type { GraphExecutionContext } from "./GraphExecutionContext.d.cts";
+import type { CodeSandboxEvaluator } from "./CodeSandboxEvaluator.d.cts";
+import type { GraphExecutionValues } from "../types.d.cts";
+/**
+ * Executor for `core.flow.code` nodes.
+ *
+ * The Code Node runs user-authored JS/TS in a restricted sandbox. The engine
+ * does not implement the sandbox directly (§22.4); instead it delegates to the
+ * pluggable {@link CodeSandboxEvaluator} registered on the engine config. When
+ * no evaluator is registered, the executor throws
+ * `GRAPH_CODE_SANDBOX_NOT_CONFIGURED`.
+ *
+ * The sandbox context exposes:
+ * - `$input` — the value on the node's `input` port (or the full input object
+ *   as a fallback when no `input` port is present).
+ * - `$vars` — workflow variables (sourced from `context.metadata.vars` when
+ *   the engine populates it).
+ * - `$item` / `$index` — current loop item and index (sourced from
+ *   `context.metadata` when the node executes inside a foreach body).
+ * - `$node` — outputs of upstream nodes (sourced from
+ *   `context.metadata.nodes` when available).
+ * - `$output` — the current draft output (sourced from
+ *   `context.metadata.output`).
+ *
+ * The evaluator's return value is forwarded verbatim on the `result` output
+ * port.
+ */
+export declare class CodeGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine?;
+    /**
+     * @param engine - The graph execution engine (or any object exposing the
+     *   optional `codeSandboxEvaluator`). This mirrors the pattern used by
+     *   {@link SwitchGraphNodeExecutor} for code conditions.
+     */
+    constructor(engine?: {
+        codeSandboxEvaluator?: CodeSandboxEvaluator;
+    } | undefined);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    /**
+     * Builds the {@link CodeSandboxContext} from the executor input and the
+     * graph execution context.
+     *
+     * The `$input` value is resolved from the node's `input` port. When the node
+     * has no explicit `input` port, the full input values object is used as
+     * `$input` so the code can still access every resolved port value.
+     *
+     * The `$vars`, `$item`, `$index`, `$node`, and `$output` values are sourced
+     * from `context.metadata` — the engine (or a wrapping loop executor) may
+     * populate these when the Code node runs inside a loop body or a workflow
+     * with variables.
+     */
+    private buildSandboxContext;
+}

package/lib/types/graph/engine/execution/CodeGraphNodeExecutor.d.mts

@@ -0,0 +1,65 @@
+/**
+ * @module integrations/graph/execution/CodeGraphNodeExecutor
+ * @summary Executor for the Code flow-control node (DECAF-32 §22.4, DECAF-34 §7.5).
+ * @description Executes user-authored JS/TS in a restricted sandbox via the
+ * pluggable {@link CodeSandboxEvaluator}. The sandbox enforces the Code Node
+ * restrictions: no imports, no requires, pure functions only (no system API
+ * access). The executor reads the code, language, and timeout from the node's
+ * graph metadata, resolves the sandbox context from the node's input values
+ * and execution context, invokes the evaluator, and returns the result on the
+ * `result` output port.
+ */
+import type { GraphNodeExecutor } from "./GraphNodeExecutor.d.mts";
+import type { GraphExecutionContext } from "./GraphExecutionContext.d.mts";
+import type { CodeSandboxEvaluator } from "./CodeSandboxEvaluator.d.mts";
+import type { GraphExecutionValues } from "../types.d.mts";
+/**
+ * Executor for `core.flow.code` nodes.
+ *
+ * The Code Node runs user-authored JS/TS in a restricted sandbox. The engine
+ * does not implement the sandbox directly (§22.4); instead it delegates to the
+ * pluggable {@link CodeSandboxEvaluator} registered on the engine config. When
+ * no evaluator is registered, the executor throws
+ * `GRAPH_CODE_SANDBOX_NOT_CONFIGURED`.
+ *
+ * The sandbox context exposes:
+ * - `$input` — the value on the node's `input` port (or the full input object
+ *   as a fallback when no `input` port is present).
+ * - `$vars` — workflow variables (sourced from `context.metadata.vars` when
+ *   the engine populates it).
+ * - `$item` / `$index` — current loop item and index (sourced from
+ *   `context.metadata` when the node executes inside a foreach body).
+ * - `$node` — outputs of upstream nodes (sourced from
+ *   `context.metadata.nodes` when available).
+ * - `$output` — the current draft output (sourced from
+ *   `context.metadata.output`).
+ *
+ * The evaluator's return value is forwarded verbatim on the `result` output
+ * port.
+ */
+export declare class CodeGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine?;
+    /**
+     * @param engine - The graph execution engine (or any object exposing the
+     *   optional `codeSandboxEvaluator`). This mirrors the pattern used by
+     *   {@link SwitchGraphNodeExecutor} for code conditions.
+     */
+    constructor(engine?: {
+        codeSandboxEvaluator?: CodeSandboxEvaluator;
+    } | undefined);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    /**
+     * Builds the {@link CodeSandboxContext} from the executor input and the
+     * graph execution context.
+     *
+     * The `$input` value is resolved from the node's `input` port. When the node
+     * has no explicit `input` port, the full input values object is used as
+     * `$input` so the code can still access every resolved port value.
+     *
+     * The `$vars`, `$item`, `$index`, `$node`, and `$output` values are sourced
+     * from `context.metadata` — the engine (or a wrapping loop executor) may
+     * populate these when the Code node runs inside a loop body or a workflow
+     * with variables.
+     */
+    private buildSandboxContext;
+}

package/lib/types/graph/engine/execution/IsolatedVmCodeSandboxEvaluator.d.cts

@@ -0,0 +1,45 @@
+import type { CodeSandboxEvaluator, CodeSandboxContext } from "./CodeSandboxEvaluator.d.cts";
+/**
+ * `isolated-vm`-backed {@link CodeSandboxEvaluator} (ALFRED-5 §7.18).
+ *
+ * This evaluator provides a truly isolated V8 sandbox — the code runs in a
+ * separate isolate with its own heap, separate from the host process. The
+ * sandbox context exposes only the data variables (`$input`, `$vars`, `$item`,
+ * `$index`, `$node`, `$output`); no host globals are available.
+ *
+ * Execution pipeline:
+ * 1. **Transpile** — TypeScript code is transpiled to JavaScript via
+ *    `typescript.transpileModule` (ALFRED-5 §7.4).
+ * 2. **Validate** — the JavaScript code is parsed with `acorn` and walked with
+ *    `acorn-walk` to reject imports, exports, blocked identifiers, `eval()`,
+ *    and `new Function()` (ALFRED-5 §7.11).
+ * 3. **Isolate** — a new `isolated-vm` `Isolate` is created with a memory
+ *    limit. A context is created and the data variables are copied into the
+ *    isolate's heap via `ExternalCopy`.
+ * 4. **Compile & run** — the wrapped code is compiled and executed with a
+ *    timeout. The result is copied back to the host heap.
+ * 5. **Dispose** — the isolate is always disposed in a `finally` block.
+ *
+ * The user code is wrapped in a strict-mode async function:
+ *
+ * ```js
+ * "use strict";
+ * async function __userFunction($input, $vars, $item, $index, $node, $output) {
+ *   <user code>
+ * }
+ * __userFunction($input, $vars, $item, $index, $node, $output);
+ * ```
+ *
+ * When the code has no `return` statement it is treated as a single expression
+ * and wrapped in `return (...)`.
+ */
+export declare class IsolatedVmCodeSandboxEvaluator implements CodeSandboxEvaluator {
+    private readonly defaultTimeoutMs;
+    private readonly defaultMemoryMb;
+    /**
+     * @param defaultTimeoutMs - Default execution timeout in milliseconds.
+     * @param defaultMemoryMb - Default isolate memory limit in MB.
+     */
+    constructor(defaultTimeoutMs?: number, defaultMemoryMb?: number);
+    evaluate(ctx: CodeSandboxContext): Promise<unknown>;
+}

package/lib/types/graph/engine/execution/IsolatedVmCodeSandboxEvaluator.d.mts

@@ -0,0 +1,45 @@
+import type { CodeSandboxEvaluator, CodeSandboxContext } from "./CodeSandboxEvaluator.d.mts";
+/**
+ * `isolated-vm`-backed {@link CodeSandboxEvaluator} (ALFRED-5 §7.18).
+ *
+ * This evaluator provides a truly isolated V8 sandbox — the code runs in a
+ * separate isolate with its own heap, separate from the host process. The
+ * sandbox context exposes only the data variables (`$input`, `$vars`, `$item`,
+ * `$index`, `$node`, `$output`); no host globals are available.
+ *
+ * Execution pipeline:
+ * 1. **Transpile** — TypeScript code is transpiled to JavaScript via
+ *    `typescript.transpileModule` (ALFRED-5 §7.4).
+ * 2. **Validate** — the JavaScript code is parsed with `acorn` and walked with
+ *    `acorn-walk` to reject imports, exports, blocked identifiers, `eval()`,
+ *    and `new Function()` (ALFRED-5 §7.11).
+ * 3. **Isolate** — a new `isolated-vm` `Isolate` is created with a memory
+ *    limit. A context is created and the data variables are copied into the
+ *    isolate's heap via `ExternalCopy`.
+ * 4. **Compile & run** — the wrapped code is compiled and executed with a
+ *    timeout. The result is copied back to the host heap.
+ * 5. **Dispose** — the isolate is always disposed in a `finally` block.
+ *
+ * The user code is wrapped in a strict-mode async function:
+ *
+ * ```js
+ * "use strict";
+ * async function __userFunction($input, $vars, $item, $index, $node, $output) {
+ *   <user code>
+ * }
+ * __userFunction($input, $vars, $item, $index, $node, $output);
+ * ```
+ *
+ * When the code has no `return` statement it is treated as a single expression
+ * and wrapped in `return (...)`.
+ */
+export declare class IsolatedVmCodeSandboxEvaluator implements CodeSandboxEvaluator {
+    private readonly defaultTimeoutMs;
+    private readonly defaultMemoryMb;
+    /**
+     * @param defaultTimeoutMs - Default execution timeout in milliseconds.
+     * @param defaultMemoryMb - Default isolate memory limit in MB.
+     */
+    constructor(defaultTimeoutMs?: number, defaultMemoryMb?: number);
+    evaluate(ctx: CodeSandboxContext): Promise<unknown>;
+}

package/lib/types/graph/engine/execution/index.d.cts

@@ -10,3 +10,5 @@ export * from "./GraphExecutionFrame.d.cts";
 export * from "./GraphExecutionEngine.d.cts";
 export * from "./CodeSandboxEvaluator.d.cts";
 export * from "./SwitchGraphNodeExecutor.d.cts";
+export * from "./CodeGraphNodeExecutor.d.cts";
+export * from "./IsolatedVmCodeSandboxEvaluator.d.cts";

package/lib/types/graph/engine/execution/index.d.mts

@@ -10,3 +10,5 @@ export * from "./GraphExecutionFrame.d.mts";
 export * from "./GraphExecutionEngine.d.mts";
 export * from "./CodeSandboxEvaluator.d.mts";
 export * from "./SwitchGraphNodeExecutor.d.mts";
+export * from "./CodeGraphNodeExecutor.d.mts";
+export * from "./IsolatedVmCodeSandboxEvaluator.d.mts";

package/lib/types/graph/engine/index.d.cts

@@ -31,6 +31,8 @@ export * from "./execution/GraphExecutionResult.d.cts";
 export * from "./execution/GraphExecutionEngine.d.cts";
 export * from "./execution/CodeSandboxEvaluator.d.cts";
 export * from "./execution/SwitchGraphNodeExecutor.d.cts";
+export * from "./execution/CodeGraphNodeExecutor.d.cts";
+export * from "./execution/IsolatedVmCodeSandboxEvaluator.d.cts";
 export * from "./registry/GraphNodeExecutorRegistry.d.cts";
 export * from "./registry/GraphNodeExecutorResolver.d.cts";
 export * from "./store/GraphValueKey.d.cts";

package/lib/types/graph/engine/index.d.mts

@@ -31,6 +31,8 @@ export * from "./execution/GraphExecutionResult.d.mts";
 export * from "./execution/GraphExecutionEngine.d.mts";
 export * from "./execution/CodeSandboxEvaluator.d.mts";
 export * from "./execution/SwitchGraphNodeExecutor.d.mts";
+export * from "./execution/CodeGraphNodeExecutor.d.mts";
+export * from "./execution/IsolatedVmCodeSandboxEvaluator.d.mts";
 export * from "./registry/GraphNodeExecutorRegistry.d.mts";
 export * from "./registry/GraphNodeExecutorResolver.d.mts";
 export * from "./store/GraphValueKey.d.mts";

package/lib/types/graph/engine/types.d.cts

@@ -4,11 +4,14 @@
  * @description Engine-private type aliases and interfaces. Frontend-safe
  * types (`ExprValue`, `ConditionExpression`, `CodeCondition`,
  * `SwitchCaseCondition`, `SwitchCase`, `SwitchNodeMetadata`,
- * `NodeMetadataChange`) live in `../shared/types`; engine modules import
- * shared symbols from there and engine-private symbols from here.
+ * `NodeMetadataChange`, `GraphExecutionEvent`, `GraphExecutionErrorPayload`)
+ * live in `../shared/types`; engine modules import shared symbols from there
+ * and engine-private symbols from here.
  */
 import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionEventType, GraphExecutionStatus } from "../shared/constants.d.cts";
+import type { GraphExecutionStatus } from "../shared/constants.d.cts";
+import type { GraphExecutionErrorPayload, GraphExecutionEvent } from "../shared/types.d.cts";
+export type { GraphExecutionErrorPayload, GraphExecutionEvent, } from "../shared/types.d.cts";
 /**
  * Unique identifier for a single graph execution run.
  */
@@ -47,37 +50,6 @@ export interface GraphExecutionOptions {
     writeThroughCache?: boolean;
     metadata?: Record<string, unknown>;
 }
-/**
- * Serialized error payload included in execution events and results.
- */
-export interface GraphExecutionErrorPayload {
-    name: string;
-    message: string;
-    stack?: string;
-    code?: string;
-    details?: unknown;
-}
-/**
- * A single event emitted during graph execution.
- */
-export interface GraphExecutionEvent {
-    id: string;
-    sequence: number;
-    runId: GraphRunId;
-    parentRunId?: GraphRunId;
-    workflowId: GraphWorkflowId;
-    type: GraphExecutionEventType;
-    timestamp: Date;
-    nodeId?: GraphNodeId;
-    edgeId?: string;
-    port?: GraphPortName;
-    iteration?: number;
-    path: string[];
-    status?: GraphExecutionStatus;
-    payload?: unknown;
-    error?: GraphExecutionErrorPayload;
-    metadata?: Record<string, unknown>;
-}
 /**
  * Result of executing a single node.
  */

package/lib/types/graph/engine/types.d.mts

@@ -4,11 +4,14 @@
  * @description Engine-private type aliases and interfaces. Frontend-safe
  * types (`ExprValue`, `ConditionExpression`, `CodeCondition`,
  * `SwitchCaseCondition`, `SwitchCase`, `SwitchNodeMetadata`,
- * `NodeMetadataChange`) live in `../shared/types`; engine modules import
- * shared symbols from there and engine-private symbols from here.
+ * `NodeMetadataChange`, `GraphExecutionEvent`, `GraphExecutionErrorPayload`)
+ * live in `../shared/types`; engine modules import shared symbols from there
+ * and engine-private symbols from here.
  */
 import type { GraphNodeDefinition, GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
-import type { GraphExecutionEventType, GraphExecutionStatus } from "../shared/constants.d.mts";
+import type { GraphExecutionStatus } from "../shared/constants.d.mts";
+import type { GraphExecutionErrorPayload, GraphExecutionEvent } from "../shared/types.d.mts";
+export type { GraphExecutionErrorPayload, GraphExecutionEvent, } from "../shared/types.d.mts";
 /**
  * Unique identifier for a single graph execution run.
  */
@@ -47,37 +50,6 @@ export interface GraphExecutionOptions {
     writeThroughCache?: boolean;
     metadata?: Record<string, unknown>;
 }
-/**
- * Serialized error payload included in execution events and results.
- */
-export interface GraphExecutionErrorPayload {
-    name: string;
-    message: string;
-    stack?: string;
-    code?: string;
-    details?: unknown;
-}
-/**
- * A single event emitted during graph execution.
- */
-export interface GraphExecutionEvent {
-    id: string;
-    sequence: number;
-    runId: GraphRunId;
-    parentRunId?: GraphRunId;
-    workflowId: GraphWorkflowId;
-    type: GraphExecutionEventType;
-    timestamp: Date;
-    nodeId?: GraphNodeId;
-    edgeId?: string;
-    port?: GraphPortName;
-    iteration?: number;
-    path: string[];
-    status?: GraphExecutionStatus;
-    payload?: unknown;
-    error?: GraphExecutionErrorPayload;
-    metadata?: Record<string, unknown>;
-}
 /**
  * Result of executing a single node.
  */

package/lib/types/graph/shared/nodes/flow-control.d.cts

@@ -94,13 +94,14 @@ export declare class ReturnFlowNode extends Model {
     result: unknown;
 }
 /**
- * Code — sandboxed JS/TS code execution (ALFRED-5 §7).
+ * Code — sandboxed JS/TS code execution (ALFRED-5 §7, DECAF-32 §22.4).
  *
- * The engine does not implement the sandbox directly (§22.4). A future
- * executor may wrap the `CodeSandbox` contract (ALFRED-5 §7.17) as a
- * pluggable executor. The placeholder syntax (`{{ $input }}`, `{{ $item }}`,
- * `{{ $index }}`, `{{ $vars }}`, `{{ $node["Name"].output }}`) is Mastra-
- * agnostic and lives in the downstream project's `modules/core` (ALFRED-6).
+ * The engine's {@link CodeGraphNodeExecutor} delegates to the pluggable
+ * {@link CodeSandboxEvaluator}. The default
+ * `IsolatedVmCodeSandboxEvaluator` (backed by `isolated-vm`) enforces the
+ * Code Node restrictions: no imports, no requires, pure functions only. The
+ * sandbox context exposes `$input`, `$vars`, `$item`, `$index`, `$node`, and
+ * `$output` as data variables. TypeScript is supported via transpilation.
  */
 export declare class CodeFlowNode extends Model {
     input: unknown;

package/lib/types/graph/shared/nodes/flow-control.d.mts

@@ -94,13 +94,14 @@ export declare class ReturnFlowNode extends Model {
     result: unknown;
 }
 /**
- * Code — sandboxed JS/TS code execution (ALFRED-5 §7).
+ * Code — sandboxed JS/TS code execution (ALFRED-5 §7, DECAF-32 §22.4).
  *
- * The engine does not implement the sandbox directly (§22.4). A future
- * executor may wrap the `CodeSandbox` contract (ALFRED-5 §7.17) as a
- * pluggable executor. The placeholder syntax (`{{ $input }}`, `{{ $item }}`,
- * `{{ $index }}`, `{{ $vars }}`, `{{ $node["Name"].output }}`) is Mastra-
- * agnostic and lives in the downstream project's `modules/core` (ALFRED-6).
+ * The engine's {@link CodeGraphNodeExecutor} delegates to the pluggable
+ * {@link CodeSandboxEvaluator}. The default
+ * `IsolatedVmCodeSandboxEvaluator` (backed by `isolated-vm`) enforces the
+ * Code Node restrictions: no imports, no requires, pure functions only. The
+ * sandbox context exposes `$input`, `$vars`, `$item`, `$index`, `$node`, and
+ * `$output` as data variables. TypeScript is supported via transpilation.
  */
 export declare class CodeFlowNode extends Model {
     input: unknown;

package/lib/types/graph/shared/types.d.cts

@@ -3,10 +3,12 @@
  * @summary Frontend-safe graph type declarations.
  * @description Type aliases and interfaces that are safe to import from a
  * frontend bundle. These types describe declarative graph metadata (loop
- * condition DSL, switch cases, node metadata patches) consumed by the
- * renderer and the node CRUD screens — no engine runtime dependency.
+ * condition DSL, switch cases, node metadata patches) and the execution-event
+ * data contract consumed by the frontend via SSE — no engine runtime
+ * dependency.
  */
 import type { GraphPortDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionEventType, GraphExecutionStatus } from "./constants.d.cts";
 /**
  * A value reference inside a {@link ConditionExpression}.
  *
@@ -119,3 +121,42 @@ export interface NodeMetadataChange {
     };
     dataPatch: Record<string, unknown>;
 }
+/**
+ * Serialized error payload included in execution events and results.
+ *
+ * Frontend-safe: the frontend receives this over SSE when a node or workflow
+ * fails and needs to render the error details.
+ */
+export interface GraphExecutionErrorPayload {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+    details?: unknown;
+}
+/**
+ * A single event emitted during graph execution.
+ *
+ * Frontend-safe: the frontend consumes these events over the SSE endpoint
+ * (`GET /graph/events`) and maps them to UI state updates via
+ * `GraphExecutionStateMapper`. The `timestamp` is serialised as an ISO string
+ * over the wire; the frontend deserialises it back to a `Date` when mapping.
+ */
+export interface GraphExecutionEvent {
+    id: string;
+    sequence: number;
+    runId: string;
+    parentRunId?: string;
+    workflowId: string;
+    type: GraphExecutionEventType;
+    timestamp: Date;
+    nodeId?: string;
+    edgeId?: string;
+    port?: string;
+    iteration?: number;
+    path: string[];
+    status?: GraphExecutionStatus;
+    payload?: unknown;
+    error?: GraphExecutionErrorPayload;
+    metadata?: Record<string, unknown>;
+}

package/lib/types/graph/shared/types.d.mts

@@ -3,10 +3,12 @@
  * @summary Frontend-safe graph type declarations.
  * @description Type aliases and interfaces that are safe to import from a
  * frontend bundle. These types describe declarative graph metadata (loop
- * condition DSL, switch cases, node metadata patches) consumed by the
- * renderer and the node CRUD screens — no engine runtime dependency.
+ * condition DSL, switch cases, node metadata patches) and the execution-event
+ * data contract consumed by the frontend via SSE — no engine runtime
+ * dependency.
  */
 import type { GraphPortDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionEventType, GraphExecutionStatus } from "./constants.d.mts";
 /**
  * A value reference inside a {@link ConditionExpression}.
  *
@@ -119,3 +121,42 @@ export interface NodeMetadataChange {
     };
     dataPatch: Record<string, unknown>;
 }
+/**
+ * Serialized error payload included in execution events and results.
+ *
+ * Frontend-safe: the frontend receives this over SSE when a node or workflow
+ * fails and needs to render the error details.
+ */
+export interface GraphExecutionErrorPayload {
+    name: string;
+    message: string;
+    stack?: string;
+    code?: string;
+    details?: unknown;
+}
+/**
+ * A single event emitted during graph execution.
+ *
+ * Frontend-safe: the frontend consumes these events over the SSE endpoint
+ * (`GET /graph/events`) and maps them to UI state updates via
+ * `GraphExecutionStateMapper`. The `timestamp` is serialised as an ISO string
+ * over the wire; the frontend deserialises it back to a `Date` when mapping.
+ */
+export interface GraphExecutionEvent {
+    id: string;
+    sequence: number;
+    runId: string;
+    parentRunId?: string;
+    workflowId: string;
+    type: GraphExecutionEventType;
+    timestamp: Date;
+    nodeId?: string;
+    edgeId?: string;
+    port?: string;
+    iteration?: number;
+    path: string[];
+    status?: GraphExecutionStatus;
+    payload?: unknown;
+    error?: GraphExecutionErrorPayload;
+    metadata?: Record<string, unknown>;
+}

package/lib/types/index.d.cts

@@ -6,6 +6,6 @@
 export * from "./utils.d.cts";
 export * from "./namespaces/index.d.cts";
 export declare const VERSION: string;
-export declare const COMMIT = "3e877de";
-export declare const FULL_VERSION = "0.3.8-3e877de";
+export declare const COMMIT = "857014d";
+export declare const FULL_VERSION = "0.3.10-857014d";
 export declare const PACKAGE_NAME: string;

package/lib/types/index.d.mts

@@ -6,6 +6,6 @@
 export * from "./utils.d.mts";
 export * from "./namespaces/index.d.mts";
 export declare const VERSION: string;
-export declare const COMMIT = "3e877de";
-export declare const FULL_VERSION = "0.3.8-3e877de";
+export declare const COMMIT = "857014d";
+export declare const FULL_VERSION = "0.3.10-857014d";
 export declare const PACKAGE_NAME: string;

package/lib/types/nest/graph/GraphExecutorRegistryFactory.d.cts

@@ -1,17 +1,52 @@
 /**
  * @module integrations/nest/graph/GraphExecutorRegistryFactory
  * @summary Factory that builds a populated {@link GraphNodeExecutorRegistry}.
- * @description Creates a registry pre-loaded with the demo executors (`math.add`, `math.multiply`) used by the graph execution backend's sample workflows. Additional executors can be registered on the returned registry before it is handed to the {@link GraphExecutionEngine}.
+ * @description Creates a registry pre-loaded with the demo executors used by
+ * the graph execution backend's sample workflows. The executors cover the
+ * publishing-workflow node tags, the flow-control kinds, the agent kind, and
+ * the loop kinds. Additional executors can be registered on the returned
+ * registry before it is handed to the {@link GraphExecutionEngine}.
  */
-import { GraphNodeExecutorRegistry } from "../../graph/index.d.cts";
-import type { GraphNodeExecutor } from "../../graph/index.d.cts";
+import { GraphNodeExecutorRegistry, GraphExecutionEngine, type GraphNodeExecutor, IsolatedVmCodeSandboxEvaluator } from "../../graph/index.d.cts";
 /**
  * Builds a {@link GraphNodeExecutorRegistry} populated with the demo executors.
  *
+ * Executors are registered by **node kind** (the same key the engine uses to
+ * resolve executors at runtime). The for-angular demo nodes use the kind as
+ * their tag, so the same key works for both dispatch-by-kind and
+ * dispatch-by-tag.
+ *
  * Registered kinds:
- * - `math.add` — sums `a` and `b` into `sum`.
- * - `math.multiply` — multiplies `x` by 2 into `product`.
+ * - `math.add`, `math.multiply` — arithmetic demo executors.
+ * - `graph-intake-workflow`, `graph-planning-pipeline`, `graph-draft-node`,
+ *   `graph-review-node`, `graph-publish-workflow` — publishing workflow demo.
+ * - `core.flow.*` — flow-control kinds (map, delay, return, merge, if, switch,
+ *   parallel, errorBoundary, humanApproval). The `core.flow.code` kind is
+ *   registered in `onEngineCreated` via the real {@link CodeGraphNodeExecutor}
+ *   because it needs the engine's `codeSandboxEvaluator`.
+ * - `core.agent` — agent node.
+ * - `core.loop.foreach`, `core.loop.while`, `core.loop.until` — loop executors
+ *   (registered after the engine is created via `onEngineCreated`).
  *
+ * @param extra - Additional executors to merge into the registry.
  * @returns A populated registry ready for use with {@link GraphExecutionEngine}.
  */
 export declare function createGraphExecutorRegistry(extra?: Record<string, GraphNodeExecutor>): GraphNodeExecutorRegistry;
+/**
+ * Builds a {@link GraphExecutionEngineConfig} populated with all demo executors
+ * including loop executors that need a back-reference to the engine and the
+ * Code node executor that needs the engine's `codeSandboxEvaluator`.
+ *
+ * The config wires an {@link IsolatedVmCodeSandboxEvaluator} (backed by
+ * `isolated-vm`) so the Code Node runs in a truly isolated V8 sandbox.
+ *
+ * @returns A config object ready for `new GraphExecutionEngine(config)`.
+ */
+export declare function createDemoEngineConfig(): {
+    registry: GraphNodeExecutorRegistry;
+    defaultOptions: {
+        failFast: boolean;
+    };
+    codeSandboxEvaluator: IsolatedVmCodeSandboxEvaluator;
+    onEngineCreated: (engine: GraphExecutionEngine) => void;
+};