@substrate-ai/factory 0.19.54

package/dist/handlers/subgraph.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Subgraph handler — executes a referenced .dot graph file as a nested sub-pipeline.
+ *
+ * Story 50-5.
+ *
+ * Reads:  `node.attrs['graph_file']` — relative or absolute path to a .dot file
+ * Reads:  `context.getNumber('subgraph._depth', 0)` — current nesting depth
+ * Writes: `subOutcome.contextUpdates` merged back into parent context
+ */
+import type { NodeHandler, IHandlerRegistry } from './types.js';
+import type { TypedEventBus } from '@substrate-ai/core';
+import type { FactoryEvents } from '../events.js';
+/**
+ * Configuration for `createSubgraphHandler`.
+ */
+export interface SubgraphHandlerOptions {
+    /** Registry used to resolve node handlers inside the subgraph. */
+    handlerRegistry: IHandlerRegistry;
+    /** Base directory for resolving relative graph_file paths. */
+    baseDir: string;
+    /** Maximum nested subgraph depth (inclusive). Default: 5. */
+    maxDepth?: number;
+    /**
+     * Injectable file loader for testability.
+     * Defaults to `(fp) => readFile(fp, 'utf-8')`.
+     */
+    graphFileLoader?: (filePath: string) => Promise<string>;
+    /**
+     * Root directory for sub-executor checkpoint files.
+     * Defaults to `os.tmpdir()`.
+     */
+    logsRoot?: string;
+    /** Optional event bus for emitting subgraph lifecycle events (story 50-9). */
+    eventBus?: TypedEventBus<FactoryEvents>;
+    /** Optional run identifier threaded to event payloads (story 50-9). */
+    runId?: string;
+}
+/**
+ * Factory function that creates a handler for `type="subgraph"` nodes.
+ *
+ * Each subgraph node references an external `.dot` file, loads and validates
+ * it, then executes it as a nested sub-pipeline. Parent context is seeded into
+ * the sub-executor and context updates from the subgraph are propagated back.
+ */
+export declare function createSubgraphHandler(options: SubgraphHandlerOptions): NodeHandler;
+//# sourceMappingURL=subgraph.d.ts.map

package/dist/handlers/subgraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subgraph.d.ts","sourceRoot":"","sources":["../../src/handlers/subgraph.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAMjD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,eAAe,EAAE,gBAAgB,CAAA;IACjC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAA;IACf,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACvD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;IACvC,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAyBD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,WAAW,CA2IlF"}

package/dist/handlers/subgraph.js

@@ -0,0 +1,178 @@
+/**
+ * Subgraph handler — executes a referenced .dot graph file as a nested sub-pipeline.
+ *
+ * Story 50-5.
+ *
+ * Reads:  `node.attrs['graph_file']` — relative or absolute path to a .dot file
+ * Reads:  `context.getNumber('subgraph._depth', 0)` — current nesting depth
+ * Writes: `subOutcome.contextUpdates` merged back into parent context
+ */
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { parseGraph } from '../graph/parser.js';
+import { createGraphExecutor } from '../graph/executor.js';
+import { createValidator } from '../graph/validator.js';
+import { parseStylesheet } from '../stylesheet/parser.js';
+// ---------------------------------------------------------------------------
+// Status conversion helper
+// ---------------------------------------------------------------------------
+/**
+ * Converts the sub-executor's `events.ts:StageStatus` back to the handler
+ * return type `types.ts:OutcomeStatus`.
+ *
+ * Mapping:
+ *   'SUCCESS'        → 'SUCCESS'
+ *   'PARTIAL_SUCCESS'→ 'PARTIAL_SUCCESS'
+ *   all others       → 'FAILURE'  (covers 'FAIL', 'RETRY', 'SKIPPED')
+ */
+function denormalizeStatus(status) {
+    if (status === 'SUCCESS')
+        return 'SUCCESS';
+    if (status === 'PARTIAL_SUCCESS')
+        return 'PARTIAL_SUCCESS';
+    return 'FAILURE';
+}
+// ---------------------------------------------------------------------------
+// createSubgraphHandler
+// ---------------------------------------------------------------------------
+/**
+ * Factory function that creates a handler for `type="subgraph"` nodes.
+ *
+ * Each subgraph node references an external `.dot` file, loads and validates
+ * it, then executes it as a nested sub-pipeline. Parent context is seeded into
+ * the sub-executor and context updates from the subgraph are propagated back.
+ */
+export function createSubgraphHandler(options) {
+    return async (node, context, graph) => {
+        // Step 1: Validate graph_file attribute
+        const graphFile = node.attrs?.['graph_file'];
+        if (!graphFile) {
+            return {
+                status: 'FAILURE',
+                failureReason: `Subgraph node "${node.id}" is missing required attribute graph_file`,
+            };
+        }
+        // Step 2: Depth guard
+        const currentDepth = context.getNumber('subgraph._depth', 0);
+        const maxDepth = options.maxDepth ?? 5;
+        if (currentDepth >= maxDepth) {
+            return {
+                status: 'FAILURE',
+                failureReason: `Subgraph depth limit exceeded (max ${maxDepth}): node "${node.id}"`,
+            };
+        }
+        // Step 3: Resolve file path
+        const filePath = path.isAbsolute(graphFile)
+            ? graphFile
+            : path.join(options.baseDir, graphFile);
+        // Step 4: Load file
+        const loader = options.graphFileLoader ?? ((fp) => readFile(fp, 'utf-8'));
+        let dotSource;
+        try {
+            dotSource = await loader(filePath);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                status: 'FAILURE',
+                failureReason: `Subgraph node "${node.id}": failed to load "${filePath}": ${msg}`,
+            };
+        }
+        // Step 5: Parse
+        let subgraph;
+        try {
+            subgraph = parseGraph(dotSource);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                status: 'FAILURE',
+                failureReason: `Subgraph node "${node.id}": failed to parse "${filePath}": ${msg}`,
+            };
+        }
+        // Step 6: Validate
+        try {
+            createValidator().validateOrRaise(subgraph);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+                status: 'FAILURE',
+                failureReason: `Subgraph node "${node.id}": validation failed for "${filePath}": ${msg}`,
+            };
+        }
+        // Read runId from context (written by executor, story 50-9 AC4)
+        const runId = context.getString('__runId', options.runId ?? 'unknown');
+        // Emit graph:subgraph-started before sub-executor runs (story 50-9 AC2)
+        options.eventBus?.emit('graph:subgraph-started', {
+            runId,
+            nodeId: node.id,
+            graphFile: filePath,
+            depth: currentDepth,
+        });
+        const subgraphStart = Date.now();
+        // Step 7: Execute
+        // Parse the parent graph's stylesheet to pass as inherited rules to the sub-executor.
+        // `graph` here is the parent graph (third argument of the NodeHandler signature).
+        const parentStylesheet = graph.modelStylesheet
+            ? parseStylesheet(graph.modelStylesheet)
+            : undefined;
+        const subConfig = {
+            runId: randomUUID(),
+            logsRoot: options.logsRoot ?? tmpdir(),
+            handlerRegistry: options.handlerRegistry,
+            initialContext: { ...context.snapshot(), 'subgraph._depth': currentDepth + 1 },
+            // Pass eventBus through so nested graph events flow on the same bus (story 50-9 AC2)
+            ...(options.eventBus !== undefined ? { eventBus: options.eventBus } : {}),
+            // Only include inheritedStylesheet when defined (exactOptionalPropertyTypes: true)
+            ...(parentStylesheet !== undefined ? { inheritedStylesheet: parentStylesheet } : {}),
+        };
+        let subOutcome;
+        try {
+            subOutcome = await createGraphExecutor().run(subgraph, subConfig);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            const durationMs = Date.now() - subgraphStart;
+            // Emit subgraph-completed on the failure/exception path (story 50-9 AC2)
+            options.eventBus?.emit('graph:subgraph-completed', {
+                runId,
+                nodeId: node.id,
+                graphFile: filePath,
+                depth: currentDepth,
+                status: 'FAIL',
+                durationMs,
+            });
+            return {
+                status: 'FAILURE',
+                failureReason: `Subgraph node "${node.id}": executor threw: ${msg}`,
+            };
+        }
+        const durationMs = Date.now() - subgraphStart;
+        // Emit graph:subgraph-completed after sub-executor returns (story 50-9 AC2)
+        options.eventBus?.emit('graph:subgraph-completed', {
+            runId,
+            nodeId: node.id,
+            graphFile: filePath,
+            depth: currentDepth,
+            status: subOutcome.status === 'SUCCESS' ? 'SUCCESS'
+                : subOutcome.status === 'PARTIAL_SUCCESS' ? 'PARTIAL_SUCCESS'
+                    : 'FAIL',
+            durationMs,
+        });
+        // Step 8: Merge context updates back to parent
+        if (subOutcome.contextUpdates) {
+            context.applyUpdates(subOutcome.contextUpdates);
+        }
+        // Step 9: Return translated outcome (only include optional fields when present)
+        return {
+            status: denormalizeStatus(subOutcome.status),
+            ...(subOutcome.contextUpdates !== undefined && { contextUpdates: subOutcome.contextUpdates }),
+            ...(subOutcome.notes !== undefined && { notes: subOutcome.notes }),
+            ...(subOutcome.failureReason !== undefined && { failureReason: subOutcome.failureReason }),
+        };
+    };
+}
+//# sourceMappingURL=subgraph.js.map

package/dist/handlers/subgraph.js.map

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

package/dist/handlers/tool.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tool handler — executes a shell command and returns stdout in context.
+ *
+ * AC1: Successful command → SUCCESS with stdout in context as `{node.id}.output`
+ * AC2: Failing command → FAILURE with stderr as failureReason
+ * AC3: Working directory resolved from context (falls back to defaultWorkingDir or cwd)
+ *
+ * Extended in story 44-5: if stdout is a valid ScenarioRunResult (detected via duck-typing),
+ * the handler computes a satisfaction score and writes `satisfaction_score` to context
+ * instead of `{node.id}.output`.
+ *
+ * Story 42-11, extended in story 44-5.
+ */
+import type { NodeHandler } from './types.js';
+/**
+ * Configuration options for the tool handler factory.
+ */
+export interface ToolHandlerOptions {
+    /** Override the default working directory (used when `workingDirectory` is absent from context). */
+    defaultWorkingDir?: string;
+    /** Override the satisfaction threshold passed to computeSatisfactionScore() (default 0.8 when omitted). */
+    satisfactionThreshold?: number;
+}
+/**
+ * Create a tool node handler that executes a shell command specified in
+ * `node.toolCommand` and captures the output into context.
+ *
+ * @param options - Optional configuration (defaultWorkingDir for testing).
+ * @returns A `NodeHandler` that:
+ *   1. Resolves the working directory from context (or falls back to defaultWorkingDir/cwd).
+ *   2. Spawns the shell command from `node.toolCommand`.
+ *   3. Returns SUCCESS with stdout trimmed and stored as `{node.id}.output`.
+ *   4. Returns FAILURE with stderr as `failureReason` on non-zero exit code.
+ */
+export declare function createToolHandler(options?: ToolHandlerOptions): NodeHandler;
+//# sourceMappingURL=tool.d.ts.map

package/dist/handlers/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/handlers/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AA6B7C;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,oGAAoG;IACpG,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,2GAA2G;IAC3G,qBAAqB,CAAC,EAAE,MAAM,CAAA;CAC/B;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAqD3E"}

package/dist/handlers/tool.js

@@ -0,0 +1,99 @@
+/**
+ * Tool handler — executes a shell command and returns stdout in context.
+ *
+ * AC1: Successful command → SUCCESS with stdout in context as `{node.id}.output`
+ * AC2: Failing command → FAILURE with stderr as failureReason
+ * AC3: Working directory resolved from context (falls back to defaultWorkingDir or cwd)
+ *
+ * Extended in story 44-5: if stdout is a valid ScenarioRunResult (detected via duck-typing),
+ * the handler computes a satisfaction score and writes `satisfaction_score` to context
+ * instead of `{node.id}.output`.
+ *
+ * Story 42-11, extended in story 44-5.
+ */
+import { spawn } from 'child_process';
+import { computeSatisfactionScore } from '../scenarios/scorer.js';
+// ---------------------------------------------------------------------------
+// ScenarioRunResult detection
+// ---------------------------------------------------------------------------
+/**
+ * Duck-typing guard: returns true if `parsed` conforms to the ScenarioRunResult
+ * shape (has summary.total and summary.passed as numbers).
+ *
+ * Detection is intentionally command-agnostic — it operates on the JSON shape
+ * alone, not on the value of `node.toolCommand`.
+ */
+function isScenarioRunResult(parsed) {
+    if (typeof parsed !== 'object' || parsed === null)
+        return false;
+    const p = parsed;
+    const summary = p['summary'];
+    return (typeof summary?.['total'] === 'number' &&
+        typeof summary?.['passed'] === 'number');
+}
+// ---------------------------------------------------------------------------
+// Handler factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a tool node handler that executes a shell command specified in
+ * `node.toolCommand` and captures the output into context.
+ *
+ * @param options - Optional configuration (defaultWorkingDir for testing).
+ * @returns A `NodeHandler` that:
+ *   1. Resolves the working directory from context (or falls back to defaultWorkingDir/cwd).
+ *   2. Spawns the shell command from `node.toolCommand`.
+ *   3. Returns SUCCESS with stdout trimmed and stored as `{node.id}.output`.
+ *   4. Returns FAILURE with stderr as `failureReason` on non-zero exit code.
+ */
+export function createToolHandler(options) {
+    return (node, context, _graph) => {
+        const command = node.toolCommand;
+        const cwd = context.getString('workingDirectory', options?.defaultWorkingDir ?? process.cwd());
+        return new Promise((resolve) => {
+            const child = spawn(command, [], { cwd, shell: true });
+            let stdoutBuf = '';
+            let stderrBuf = '';
+            child.stdout.on('data', (chunk) => {
+                stdoutBuf += chunk.toString();
+            });
+            child.stderr.on('data', (chunk) => {
+                stderrBuf += chunk.toString();
+            });
+            child.on('close', (code) => {
+                if (code === 0) {
+                    // Attempt to detect ScenarioRunResult JSON via duck-typing.
+                    // If detected, write satisfaction_score to context (not {node.id}.output).
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(stdoutBuf.trim());
+                    }
+                    catch {
+                        // Not JSON — fall through to default output handling
+                    }
+                    if (isScenarioRunResult(parsed)) {
+                        const scored = computeSatisfactionScore(parsed, options?.satisfactionThreshold);
+                        resolve({
+                            status: 'SUCCESS',
+                            contextUpdates: { satisfaction_score: scored.score },
+                        });
+                    }
+                    else {
+                        resolve({
+                            status: 'SUCCESS',
+                            contextUpdates: {
+                                [`${node.id}.output`]: stdoutBuf.trim(),
+                            },
+                        });
+                    }
+                }
+                else {
+                    resolve({
+                        status: 'FAILURE',
+                        failureReason: stderrBuf.trim() || `Command exited with code ${code}`,
+                    });
+                }
+            });
+        });
+    };
+}
+//# sourceMappingURL=tool.js.map

package/dist/handlers/tool.js.map

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

package/dist/handlers/types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Core type definitions for the handler registry.
+ * Story 42-9.
+ */
+import type { GraphNode, Graph, IGraphContext, Outcome } from '../graph/types.js';
+import type { TypedEventBus } from '@substrate-ai/core';
+import type { FactoryEvents } from '../events.js';
+/**
+ * A function that handles a single graph node during execution.
+ * Must be async — the executor always awaits handlers.
+ */
+export type NodeHandler = (node: GraphNode, context: IGraphContext, graph: Graph) => Promise<Outcome>;
+/**
+ * Interface for the handler registry that maps node types and shapes to
+ * handler functions. The executor uses this to dispatch nodes without being
+ * coupled to individual handler implementations.
+ */
+export interface IHandlerRegistry {
+    /**
+     * Register a handler for the given node type.
+     * Overwrites any previously registered handler for the same type.
+     */
+    register(type: string, handler: NodeHandler): void;
+    /**
+     * Register a shape-to-type mapping so that nodes lacking an explicit type
+     * can still be resolved via their DOT shape attribute.
+     * Overwrites any previously registered mapping for the same shape.
+     */
+    registerShape(shape: string, type: string): void;
+    /**
+     * Set the default handler, used when no type or shape match is found.
+     */
+    setDefault(handler: NodeHandler): void;
+    /**
+     * Resolve the handler for the given node using the 3-step priority chain:
+     * 1. Explicit type match
+     * 2. Shape-based fallback
+     * 3. Default handler (throws if not set)
+     */
+    resolve(node: GraphNode): NodeHandler;
+}
+/**
+ * Result of a single branch execution inside a parallel node.
+ * Written into `parallel.results` by the parallel handler; consumed by the
+ * fan-in handler (story 50-2) for candidate ranking.
+ */
+export interface ParallelBranchResult {
+    /** The branch start node ID (outgoing edge target from the parallel node). */
+    nodeId: string;
+    /** Outcome status returned by the branch handler. */
+    status: string;
+    /** Snapshot of the branch's isolated context after execution. */
+    contextSnapshot: Record<string, unknown>;
+    /** Populated when status is 'FAILURE' (or a failure-class string). */
+    failureReason?: string;
+}
+/**
+ * Canonical result type stored in `parallel.results` by the parallel handler.
+ * This is the cross-story contract between parallel.ts (producer) and
+ * fan-in.ts (consumer). The parallel handler bridges from the internal
+ * join-policy BranchResult format into this shape.
+ *
+ * Fields branch_id, status, context_updates, score, failure_reason are the
+ * fan-in consumer interface. Fields index, outcome, contextSnapshot, error
+ * are the join-policy producer fields preserved through the bridge.
+ */
+export interface FanInBranchResult {
+    /** Integer branch identifier assigned by the parallel handler. */
+    branch_id: number;
+    /** Terminal outcome status for this branch. */
+    status: string;
+    /** Context updates to merge when this branch wins. */
+    context_updates?: Record<string, unknown> | undefined;
+    /** Optional numeric quality score (higher is better). */
+    score?: number | undefined;
+    /** Human-readable failure description. */
+    failure_reason?: string | undefined;
+    /** Zero-based index (join-policy field, present when produced by parallel handler). */
+    index?: number | undefined;
+    /** Raw outcome from join-policy (present when produced by parallel handler). */
+    outcome?: string | undefined;
+    /** Shallow snapshot of branch context at completion. */
+    contextSnapshot?: Record<string, unknown> | undefined;
+    /** Error string from join-policy. */
+    error?: string | undefined;
+}
+/**
+ * Options for the parallel handler factory function.
+ */
+export interface ParallelHandlerOptions {
+    /** Registry used to resolve and invoke branch node handlers. */
+    handlerRegistry: IHandlerRegistry;
+    /** Optional event bus for emitting parallel lifecycle events (story 50-9). */
+    eventBus?: TypedEventBus<FactoryEvents>;
+    /** Optional run identifier threaded to event payloads (story 50-9). */
+    runId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/handlers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/handlers/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AACjF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AAErG;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;IAClD;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAChD;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;IACtC;;;;;OAKG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW,CAAA;CACtC;AAMD;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAA;IACd,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAA;IACjB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAA;IACd,sDAAsD;IACtD,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACrD,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,0CAA0C;IAC1C,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACrD,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,gEAAgE;IAChE,eAAe,EAAE,gBAAgB,CAAA;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;IACvC,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;CACf"}

package/dist/handlers/types.js

@@ -0,0 +1,6 @@
+/**
+ * Core type definitions for the handler registry.
+ * Story 42-9.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/handlers/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/handlers/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/handlers/wait-human.d.ts

@@ -0,0 +1,65 @@
+/**
+ * wait.human handler — pauses graph execution for human input at decision points.
+ *
+ * AC4: Accelerator key parsing from edge labels (`[Y] Yes` → `{ key: 'Y', label: 'Yes' }`)
+ * AC5: Returns SUCCESS with preferredLabel matching human selection and context update
+ *
+ * Story 42-11.
+ */
+import type { GraphNode, Graph } from '../graph/types.js';
+import type { NodeHandler } from './types.js';
+/**
+ * A single choice presented to the human at a wait.human gate.
+ */
+export interface Choice {
+    /** Single-character accelerator key (uppercased). */
+    key: string;
+    /** Human-readable label text (without the `[X]` prefix). */
+    label: string;
+}
+/**
+ * Configuration options for the wait.human handler factory.
+ */
+export interface WaitHumanHandlerOptions {
+    /**
+     * Inject a custom prompt function for testability.
+     * Receives the node label (question header) and the list of choices.
+     * Must resolve with the full edge label string (e.g., `"[Y] Yes"`).
+     * Defaults to a readline-based CLI prompt.
+     */
+    promptFn?: (nodeLabel: string, choices: Choice[]) => Promise<string>;
+}
+/**
+ * Parse an edge label into a `Choice` with an accelerator key.
+ *
+ * - Labels matching `/^\[([A-Za-z0-9])\]\s*(.*)$/` use the bracketed char as key
+ *   and the remaining text as the label.
+ * - Labels without the `[X]` prefix fall back to the first character of the label
+ *   (uppercased) as the key, and the full label string as the label text.
+ *
+ * @param edgeLabel - The raw edge label string from the DOT graph.
+ * @returns `{ key, label }` — key is always uppercased.
+ */
+export declare function parseAcceleratorKey(edgeLabel: string): Choice;
+/**
+ * Derive the list of choices for a wait.human node by inspecting outgoing edges.
+ *
+ * Filters `graph.edges` where `edge.fromNode === node.id` and `edge.label` is
+ * non-empty, then maps each edge label through `parseAcceleratorKey`.
+ *
+ * @param node  - The wait.human graph node.
+ * @param graph - The full graph (used to read edge labels).
+ * @returns Ordered array of choices derived from outgoing edge labels.
+ */
+export declare function deriveChoices(node: GraphNode, graph: Graph): Choice[];
+/**
+ * Create a wait.human node handler that pauses execution for human input.
+ *
+ * @param options - Optional configuration (inject `promptFn` for testing).
+ * @returns A `NodeHandler` that:
+ *   1. Derives choices from outgoing edge labels via `deriveChoices`.
+ *   2. Calls `promptFn(node.label, choices)` and awaits the selected label.
+ *   3. Returns `{ status: 'SUCCESS', preferredLabel, contextUpdates: { '{node.id}.choice': label } }`.
+ */
+export declare function createWaitHumanHandler(options?: WaitHumanHandlerOptions): NodeHandler;
+//# sourceMappingURL=wait-human.d.ts.map

package/dist/handlers/wait-human.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-human.d.ts","sourceRoot":"","sources":["../../src/handlers/wait-human.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAqC,MAAM,mBAAmB,CAAA;AAC5F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAM7C;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB,qDAAqD;IACrD,GAAG,EAAE,MAAM,CAAA;IACX,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;CACrE;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAY7D;AAMD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,CAIrE;AAwDD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,uBAAuB,GAAG,WAAW,CAkBrF"}