@framers/agentos 0.1.69 → 0.1.70

package/dist/orchestration/runtime/LoopController.d.ts

@@ -0,0 +1,173 @@
+/**
+ * @file LoopController.ts
+ * @description Reusable, configurable ReAct (Reason + Act) loop controller for AgentOS.
+ *
+ * Extracted from the GMI implementation to provide a generic orchestration primitive
+ * that supports parallel/sequential tool dispatch, configurable failure modes, and
+ * iteration limits. Yields structured {@link LoopEvent}s for observability.
+ *
+ * @example
+ * ```typescript
+ * const controller = new LoopController();
+ * for await (const event of controller.execute(config, context)) {
+ *   if (event.type === 'text_delta') process.stdout.write(event.content);
+ * }
+ * ```
+ */
+/**
+ * Configuration that governs a single LoopController execution.
+ */
+export interface LoopConfig {
+    /** Maximum number of ReAct iterations before the loop is forcibly terminated. */
+    maxIterations: number;
+    /**
+     * When `true`, all tool calls within a single iteration are dispatched in
+     * parallel via `Promise.allSettled`. When `false`, they execute sequentially.
+     */
+    parallelTools: boolean;
+    /**
+     * Determines how tool errors are handled:
+     * - `'fail_open'`  — emit a `tool_error` event and continue the loop.
+     * - `'fail_closed'` — throw immediately, aborting the loop.
+     */
+    failureMode: 'fail_open' | 'fail_closed';
+    /**
+     * Optional per-loop timeout in milliseconds. Currently reserved for
+     * future implementation via AbortController; not enforced in v1.
+     */
+    timeout?: number;
+}
+/**
+ * Execution context provided to the LoopController by the caller.
+ * Abstracts away the underlying LLM/GMI implementation so the loop logic
+ * remains provider-agnostic.
+ */
+export interface LoopContext {
+    /**
+     * Async generator that streams chunks during a single LLM inference pass.
+     * Must return a {@link LoopOutput} as its generator return value (the value
+     * passed to the final `done: true` result from `.next()`).
+     */
+    generateStream: () => AsyncGenerator<LoopChunk, LoopOutput, undefined>;
+    /**
+     * Execute a single tool call and return its result.
+     * Implementations should never throw — instead return a result with
+     * `success: false` and a populated `error` field.
+     */
+    executeTool: (toolCall: ToolCallRequest) => Promise<ToolCallResult>;
+    /**
+     * Feed tool results back into the conversation so the next `generateStream`
+     * call has access to them. Typically appends tool messages to the message list.
+     */
+    addToolResults: (results: ToolCallResult[]) => void;
+}
+/**
+ * A single tool invocation requested by the LLM.
+ */
+export interface ToolCallRequest {
+    /** Unique identifier for this tool call within a response (matches the tool result). */
+    id: string;
+    /** Name of the tool to invoke. */
+    name: string;
+    /** Parsed arguments to pass to the tool. */
+    arguments: Record<string, unknown>;
+}
+/**
+ * The outcome of executing a {@link ToolCallRequest}.
+ */
+export interface ToolCallResult {
+    /** Matches the originating {@link ToolCallRequest.id}. */
+    id: string;
+    /** Name of the tool that was called. */
+    name: string;
+    /** Whether the tool executed without error. */
+    success: boolean;
+    /** Serialisable output returned by the tool on success. */
+    output?: unknown;
+    /** Human-readable error message when `success` is `false`. */
+    error?: string;
+}
+/**
+ * A single chunk emitted by `generateStream` during inference.
+ * Each chunk carries either a text fragment or a set of tool call requests.
+ */
+export interface LoopChunk {
+    /**
+     * - `'text_delta'` — incremental text from the assistant.
+     * - `'tool_call_request'` — the LLM has decided to call one or more tools.
+     */
+    type: 'text_delta' | 'tool_call_request';
+    /** Present when `type === 'text_delta'`. */
+    content?: string;
+    /** Present when `type === 'tool_call_request'`. */
+    toolCalls?: ToolCallRequest[];
+}
+/**
+ * The final return value of `generateStream` (carried in the generator's
+ * `return` slot, i.e. `{ done: true, value: LoopOutput }`).
+ */
+export interface LoopOutput {
+    /** Accumulated assistant text for this iteration. */
+    responseText: string;
+    /**
+     * All tool calls requested in this iteration. An empty array signals that
+     * the LLM is done and the loop should terminate.
+     */
+    toolCalls: ToolCallRequest[];
+    /**
+     * The LLM finish reason (e.g. `'stop'`, `'tool_calls'`, `'length'`).
+     * Informational; not used for loop-control decisions.
+     */
+    finishReason: string;
+}
+/**
+ * Discriminated union of all events emitted by {@link LoopController.execute}.
+ * Consumers can switch on `event.type` to handle each case.
+ */
+export type LoopEvent = {
+    type: 'text_delta';
+    content: string;
+} | {
+    type: 'tool_call_request';
+    toolCalls: ToolCallRequest[];
+} | {
+    type: 'tool_result';
+    toolName: string;
+    result: ToolCallResult;
+} | {
+    type: 'tool_error';
+    toolName: string;
+    error: string;
+} | {
+    type: 'max_iterations_reached';
+    iteration: number;
+} | {
+    type: 'loop_complete';
+    totalIterations: number;
+};
+/**
+ * Configurable ReAct loop controller.
+ *
+ * Drives a generate → act → observe cycle, delegating LLM inference and
+ * tool execution to the caller-provided {@link LoopContext}. The loop
+ * terminates when:
+ *
+ * 1. The LLM returns no tool calls (natural stop), or
+ * 2. `maxIterations` is exceeded, or
+ * 3. A tool fails and `failureMode` is `'fail_closed'`.
+ *
+ * All intermediate events are yielded so callers can stream output to the
+ * user or record an audit trace.
+ */
+export declare class LoopController {
+    /**
+     * Execute the ReAct loop and yield {@link LoopEvent}s.
+     *
+     * @param config - Loop behaviour configuration.
+     * @param context - Callbacks to the underlying LLM/tool layer.
+     * @yields {LoopEvent} Structured events for each phase of the loop.
+     * @throws {Error} Only when `failureMode === 'fail_closed'` and a tool fails.
+     */
+    execute(config: LoopConfig, context: LoopContext): AsyncGenerator<LoopEvent>;
+}
+//# sourceMappingURL=LoopController.d.ts.map

package/dist/orchestration/runtime/LoopController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoopController.d.ts","sourceRoot":"","sources":["../../../src/orchestration/runtime/LoopController.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iFAAiF;IACjF,aAAa,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,aAAa,EAAE,OAAO,CAAC;IAEvB;;;;OAIG;IACH,WAAW,EAAE,WAAW,GAAG,aAAa,CAAC;IAEzC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,cAAc,EAAE,MAAM,cAAc,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IAEvE;;;;OAIG;IACH,WAAW,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAEpE;;;OAGG;IACH,cAAc,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,IAAI,CAAC;CACrD;AAMD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wFAAwF;IACxF,EAAE,EAAE,MAAM,CAAC;IAEX,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IAEb,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IAEX,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IAEb,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IAEjB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAMD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,IAAI,EAAE,YAAY,GAAG,mBAAmB,CAAC;IAEzC,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,mDAAmD;IACnD,SAAS,CAAC,EAAE,eAAe,EAAE,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,qDAAqD;IACrD,YAAY,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,SAAS,EAAE,eAAe,EAAE,CAAC;IAE7B;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAMD;;;GAGG;AACH,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACvC;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,SAAS,EAAE,eAAe,EAAE,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,eAAe,EAAE,MAAM,CAAA;CAAE,CAAC;AAMvD;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAc;IACzB;;;;;;;OAOG;IACI,OAAO,CACZ,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,WAAW,GACnB,cAAc,CAAC,SAAS,CAAC;CAuG7B"}

package/dist/orchestration/runtime/LoopController.js

@@ -0,0 +1,130 @@
+/**
+ * @file LoopController.ts
+ * @description Reusable, configurable ReAct (Reason + Act) loop controller for AgentOS.
+ *
+ * Extracted from the GMI implementation to provide a generic orchestration primitive
+ * that supports parallel/sequential tool dispatch, configurable failure modes, and
+ * iteration limits. Yields structured {@link LoopEvent}s for observability.
+ *
+ * @example
+ * ```typescript
+ * const controller = new LoopController();
+ * for await (const event of controller.execute(config, context)) {
+ *   if (event.type === 'text_delta') process.stdout.write(event.content);
+ * }
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// LoopController
+// ---------------------------------------------------------------------------
+/**
+ * Configurable ReAct loop controller.
+ *
+ * Drives a generate → act → observe cycle, delegating LLM inference and
+ * tool execution to the caller-provided {@link LoopContext}. The loop
+ * terminates when:
+ *
+ * 1. The LLM returns no tool calls (natural stop), or
+ * 2. `maxIterations` is exceeded, or
+ * 3. A tool fails and `failureMode` is `'fail_closed'`.
+ *
+ * All intermediate events are yielded so callers can stream output to the
+ * user or record an audit trace.
+ */
+export class LoopController {
+    /**
+     * Execute the ReAct loop and yield {@link LoopEvent}s.
+     *
+     * @param config - Loop behaviour configuration.
+     * @param context - Callbacks to the underlying LLM/tool layer.
+     * @yields {LoopEvent} Structured events for each phase of the loop.
+     * @throws {Error} Only when `failureMode === 'fail_closed'` and a tool fails.
+     */
+    async *execute(config, context) {
+        let iteration = 0;
+        while (iteration < config.maxIterations) {
+            iteration++;
+            // ------------------------------------------------------------------
+            // Generate phase: consume the streaming generator chunk by chunk,
+            // yielding events as they arrive.  The final LoopOutput is captured
+            // from the generator's return value (done === true).
+            // ------------------------------------------------------------------
+            const gen = context.generateStream();
+            let gmiOutput;
+            while (true) {
+                const { value, done } = await gen.next();
+                if (done) {
+                    // The generator's return value is the LoopOutput summary.
+                    gmiOutput = value;
+                    break;
+                }
+                // Yield chunk events to the caller.
+                const chunk = value;
+                if (chunk.type === 'text_delta' && chunk.content) {
+                    yield { type: 'text_delta', content: chunk.content };
+                }
+                if (chunk.type === 'tool_call_request' && chunk.toolCalls) {
+                    yield { type: 'tool_call_request', toolCalls: chunk.toolCalls };
+                }
+            }
+            // Natural termination: no tool calls requested.
+            if (!gmiOutput || gmiOutput.toolCalls.length === 0) {
+                yield { type: 'loop_complete', totalIterations: iteration };
+                return;
+            }
+            // ------------------------------------------------------------------
+            // Act phase: execute tool calls (parallel or sequential).
+            // ------------------------------------------------------------------
+            const toolCalls = gmiOutput.toolCalls;
+            let results;
+            if (config.parallelTools) {
+                // Dispatch all tool calls simultaneously; collect all outcomes even
+                // if some reject, so we can still feed partial results back.
+                const settled = await Promise.allSettled(toolCalls.map((tc) => context.executeTool(tc)));
+                results = settled.map((s, i) => {
+                    if (s.status === 'fulfilled')
+                        return s.value;
+                    // Convert a rejected promise into a failed ToolCallResult so
+                    // downstream handling is uniform.
+                    return {
+                        id: toolCalls[i].id,
+                        name: toolCalls[i].name,
+                        success: false,
+                        error: String(s.reason),
+                    };
+                });
+            }
+            else {
+                // Sequential execution — preserves order and stops early on
+                // fail_closed errors (handled in the yield loop below).
+                results = [];
+                for (const tc of toolCalls) {
+                    const result = await context.executeTool(tc);
+                    results.push(result);
+                }
+            }
+            // ------------------------------------------------------------------
+            // Observe phase: yield results, handle failures per failureMode.
+            // ------------------------------------------------------------------
+            for (const result of results) {
+                if (result.success) {
+                    yield { type: 'tool_result', toolName: result.name, result };
+                }
+                else {
+                    const errorMsg = result.error ?? 'unknown error';
+                    yield { type: 'tool_error', toolName: result.name, error: errorMsg };
+                    if (config.failureMode === 'fail_closed') {
+                        throw new Error(`Tool ${result.name} failed (fail_closed): ${errorMsg}`);
+                    }
+                    // fail_open: continue — the error is already yielded above.
+                }
+            }
+            // Feed all results (successes and failures) back into the conversation
+            // so the LLM has full context on the next iteration.
+            context.addToolResults(results);
+        }
+        // Exceeded maxIterations without a natural stop.
+        yield { type: 'max_iterations_reached', iteration: config.maxIterations };
+    }
+}
+//# sourceMappingURL=LoopController.js.map

package/dist/orchestration/runtime/LoopController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoopController.js","sourceRoot":"","sources":["../../../src/orchestration/runtime/LoopController.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/runtime/NodeExecutor.d.ts

@@ -0,0 +1,206 @@
+/**
+ * @file NodeExecutor.ts
+ * @description Dispatches execution to the appropriate handler based on `GraphNode.executorConfig.type`.
+ *
+ * The executor is intentionally thin — it contains no retry logic (handled by `GraphRuntime`),
+ * no state mutation (handled by `StateManager`), and no event emission (handled by the caller).
+ * Each private method maps one-to-one with a `NodeExecutorConfig` variant.
+ *
+ * Execution flow:
+ *   `execute()` → optional timeout race → `executeNode()` → variant handler
+ *
+ * Placeholders for `gmi`, `extension`, and `subgraph` nodes are wired in `GraphRuntime`
+ * after the `LoopController` and extension managers are available.
+ */
+import type { GraphNode, GraphState } from '../ir/types.js';
+import type { GraphEvent } from '../events/GraphEvent.js';
+/**
+ * The normalised result returned by every `NodeExecutor.execute()` call regardless
+ * of which executor variant was dispatched.
+ *
+ * The runtime inspects these fields to decide the next graph step:
+ * - `success`          — whether the node completed without error.
+ * - `output`           — arbitrary payload produced by the node (tool result, LLM response, etc.).
+ * - `error`            — human-readable error message; only present when `success` is `false`.
+ * - `routeTarget`      — next node id determined by a `router` or `guardrail` node.
+ * - `scratchUpdate`    — partial object merged into `GraphState.scratch` by `StateManager`.
+ * - `artifactsUpdate`  — partial object merged into `GraphState.artifacts` by `StateManager`.
+ * - `events`           — additional `GraphEvent` values the executor wants the runtime to emit.
+ * - `interrupt`        — when `true`, the runtime suspends the run and waits for human input.
+ */
+export interface NodeExecutionResult {
+    /** Whether the node completed successfully. */
+    success: boolean;
+    /** Arbitrary output produced by the node. */
+    output?: unknown;
+    /** Human-readable error description; populated only when `success` is `false`. */
+    error?: string;
+    /** Target node id returned by `router` or guardrail rerouting. */
+    routeTarget?: string;
+    /** Partial update to merge into `GraphState.scratch`. */
+    scratchUpdate?: Record<string, unknown>;
+    /** Partial update to merge into `GraphState.artifacts`. */
+    artifactsUpdate?: Record<string, unknown>;
+    /** Extra runtime events the executor wants to surface to callers. */
+    events?: GraphEvent[];
+    /** When `true`, the runtime must suspend and await human resolution. */
+    interrupt?: boolean;
+}
+/**
+ * External dependencies injected into `NodeExecutor` at construction time.
+ *
+ * Using an interface rather than concrete types keeps the executor decoupled from
+ * the full `ToolOrchestrator` and `GuardrailEngine` implementations and makes the
+ * unit-test surface minimal.
+ *
+ * GMI / extension / subgraph managers are omitted here and wired by `GraphRuntime`
+ * once those subsystems are available.
+ */
+export interface NodeExecutorDeps {
+    /**
+     * Routes tool-call requests to registered `ITool` implementations.
+     * When absent, any `tool` node will resolve with `success: false`.
+     */
+    toolOrchestrator?: {
+        /**
+         * Process a single tool call and return its result.
+         *
+         * @param details - Wrapper containing `toolCallRequest.toolName` and `toolCallRequest.arguments`.
+         * @returns Promise resolving to an object with at least `output` and `isError` / `success`.
+         */
+        processToolCall(details: {
+            toolCallRequest: {
+                toolName: string;
+                arguments: Record<string, unknown>;
+            };
+        }): Promise<{
+            success?: boolean;
+            isError?: boolean;
+            output?: unknown;
+            error?: string;
+        }>;
+    };
+    /**
+     * Evaluates one or more named guardrails against a content payload.
+     * When absent, guardrail nodes are treated as always-passing.
+     */
+    guardrailEngine?: {
+        /**
+         * Run all listed guardrails against `content` and return a combined verdict.
+         *
+         * @param content      - The payload to evaluate (typically `GraphState.scratch`).
+         * @param guardrailIds - Ordered list of guardrail identifiers to run.
+         * @returns Aggregated result with `passed` flag and per-guardrail `results`.
+         */
+        evaluate(content: unknown, guardrailIds: string[]): Promise<{
+            passed: boolean;
+            results: unknown[];
+        }>;
+    };
+}
+/**
+ * Stateless executor that dispatches a `GraphNode` to the appropriate handler.
+ *
+ * One `NodeExecutor` instance is typically shared across the lifetime of a `GraphRuntime`
+ * and reused for every node invocation within every run. All state is passed through
+ * `GraphState` and returned via `NodeExecutionResult`.
+ *
+ * @example
+ * ```ts
+ * const executor = new NodeExecutor({ toolOrchestrator, guardrailEngine });
+ * const result = await executor.execute(node, graphState);
+ * if (!result.success) console.error(result.error);
+ * ```
+ */
+export declare class NodeExecutor {
+    private readonly deps;
+    /**
+     * @param deps - External service adapters. All fields are optional; missing services
+     *               cause graceful degradation rather than hard failures.
+     */
+    constructor(deps: NodeExecutorDeps);
+    /**
+     * Execute `node` against the provided `state`, optionally racing against a timeout.
+     *
+     * If `node.timeout` is set, execution races against a timer that resolves with a
+     * `success: false` result after the specified number of milliseconds.
+     *
+     * @param node  - Immutable node descriptor from the compiled graph IR.
+     * @param state - Current (partial) graph state threaded from the runtime.
+     * @returns A `NodeExecutionResult` describing the outcome.
+     */
+    execute(node: GraphNode, state: Partial<GraphState>): Promise<NodeExecutionResult>;
+    /**
+     * Dispatches to the correct private handler based on `executorConfig.type`.
+     *
+     * Each branch receives only the narrowed config type it needs, keeping handler
+     * signatures precise and avoiding accidental access to unrelated fields.
+     */
+    private executeNode;
+    /**
+     * Invokes a registered `ITool` via `ToolOrchestrator.processToolCall()`.
+     *
+     * Static args from `config.args` are merged into the call. The orchestrator
+     * is responsible for argument validation and schema enforcement.
+     *
+     * @param config - `{ type: 'tool'; toolName: string; args?: Record<string, unknown> }`
+     * @param state  - Current graph state (not used directly but available for future extension).
+     */
+    private executeTool;
+    /**
+     * Evaluates a `GraphCondition` and returns the resolved target node id as `routeTarget`.
+     *
+     * Two condition strategies are supported:
+     * - `function` — calls the runtime-registered TypeScript `fn` directly.
+     * - `expression` — delegates to `evaluateExpression()` for DSL string evaluation.
+     *
+     * @param config - `{ type: 'router'; condition: GraphCondition }`
+     * @param state  - Current graph state passed to the condition function/evaluator.
+     */
+    private executeRouter;
+    /**
+     * Evaluates a set of guardrails against `state.scratch` and either passes through
+     * or triggers the configured violation action.
+     *
+     * When no `guardrailEngine` is configured, the node always passes (permissive default).
+     * Violation handling currently supports `'reroute'`; `'block'`, `'warn'`, and `'sanitize'`
+     * are propagated via `success: false` for the runtime to handle.
+     *
+     * @param config - Guardrail node config with `guardrailIds`, `onViolation`, and optional `rerouteTarget`.
+     * @param state  - Current graph state; `state.scratch` is passed to the engine as the content payload.
+     */
+    private executeGuardrail;
+    /**
+     * Suspends execution and surfaces a prompt to a human operator.
+     *
+     * The runtime must treat `interrupt: true` as a signal to persist state, emit an
+     * `interrupt` event, and halt the current run until the operator provides a response.
+     *
+     * @param config - `{ type: 'human'; prompt: string }`
+     */
+    private executeHuman;
+    /**
+     * Minimal DSL expression evaluator for `{ type: 'expression' }` routing conditions.
+     *
+     * Current implementation is a stub that returns the expression string unchanged.
+     * A full implementation would parse `"scratch.confidence > 0.8 ? 'approve' : 'review'"`
+     * using a sandboxed interpreter with dot-path access to `state` fields.
+     *
+     * @param expr  - The DSL expression string from `GraphConditionExpr`.
+     * @param state - Current graph state (available for a real implementation to traverse).
+     * @returns The resolved target node id (or the raw expression until the evaluator is complete).
+     *
+     * @todo Implement a sandboxed expression interpreter (tracked separately).
+     */
+    private evaluateExpression;
+    /**
+     * Builds a `Promise` that resolves with a timeout-failure result after `ms` milliseconds.
+     *
+     * Races against `executeNode()` inside `execute()` to enforce `GraphNode.timeout`.
+     *
+     * @param ms     - Timeout duration in milliseconds.
+     * @param nodeId - Node id included in the error message for debugging.
+     */
+    private buildTimeoutPromise;
+}
+//# sourceMappingURL=NodeExecutor.d.ts.map

package/dist/orchestration/runtime/NodeExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeExecutor.d.ts","sourceRoot":"","sources":["../../../src/orchestration/runtime/NodeExecutor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAkB,MAAM,gBAAgB,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAM1D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,mBAAmB;IAClC,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yDAAyD;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,qEAAqE;IACrE,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,gBAAgB,CAAC,EAAE;QACjB;;;;;WAKG;QACH,eAAe,CAAC,OAAO,EAAE;YACvB,eAAe,EAAE;gBAAE,QAAQ,EAAE,MAAM,CAAC;gBAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;aAAE,CAAC;SAC3E,GAAG,OAAO,CAAC;YAAE,OAAO,CAAC,EAAE,OAAO,CAAC;YAAC,OAAO,CAAC,EAAE,OAAO,CAAC;YAAC,MAAM,CAAC,EAAE,OAAO,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACzF,CAAC;IAEF;;;OAGG;IACH,eAAe,CAAC,EAAE;QAChB;;;;;;WAMG;QACH,QAAQ,CACN,OAAO,EAAE,OAAO,EAChB,YAAY,EAAE,MAAM,EAAE,GACrB,OAAO,CAAC;YAAE,MAAM,EAAE,OAAO,CAAC;YAAC,OAAO,EAAE,OAAO,EAAE,CAAA;SAAE,CAAC,CAAC;KACrD,CAAC;CACH;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,YAAY;IAKX,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC;;;OAGG;gBAC0B,IAAI,EAAE,gBAAgB;IAMnD;;;;;;;;;OASG;IACG,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAcxF;;;;;OAKG;YACW,WAAW;IAsCzB;;;;;;;;OAQG;YACW,WAAW;IAyBzB;;;;;;;;;OASG;YACW,aAAa;IAiB3B;;;;;;;;;;OAUG;YACW,gBAAgB;IAgC9B;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAepB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,kBAAkB;IAI1B;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;CAQ5B"}