footprintjs 9.9.0 → 9.10.0

package/dist/esm/lib/builder/FlowChartBuilder.d.ts

@@ -0,0 +1,475 @@
+/**
+ * FlowChartBuilder — Fluent API for constructing flowchart execution graphs.
+ *
+ * Builds StageNode trees and SerializedPipelineStructure (JSON) in tandem.
+ * Zero dependencies on old code — only imports from local types.
+ *
+ * The builder creates two parallel structures:
+ * 1. StageNode tree — runtime graph with embedded functions
+ * 2. SerializedPipelineStructure — JSON-safe structure for visualization
+ *
+ * The execute() convenience method is intentionally omitted —
+ * it belongs in the runner layer (Phase 5).
+ */
+import type { ScopeFactory } from '../engine/types.js';
+import type { PausableHandler } from '../pause/types.js';
+import type { TypedScope } from '../reactive/types.js';
+import { type RunnableFlowChart } from '../runner/RunnableChart.js';
+import type { StructureEdgeKind, StructureRecorder } from './structure/StructureRecorder.js';
+import { StructureRecorderDispatcher } from './structure/StructureRecorderDispatcher.js';
+import { type TypedStageFunction } from './typedFlowChart.js';
+import type { FlowChart, FlowChartOptions, FlowChartSpec, ILogger, SerializedPipelineStructure, SimplifiedParallelSpec, StageFunction, StageNode, StreamLifecycleHandler, StreamTokenHandler, SubflowMountOptions } from './types.js';
+/**
+ * Fluent helper returned by addDeciderFunction to add branches.
+ * `end()` sets `deciderFn = true` — the fn IS the decider.
+ */
+export declare class DeciderList<TOut = any, TScope = any> {
+    private readonly b;
+    private readonly curNode;
+    private readonly curSpec;
+    private readonly branchIds;
+    private defaultId?;
+    private readonly parentDescriptionParts;
+    private readonly parentStageDescriptions;
+    private readonly reservedStepNumber;
+    private readonly deciderDescription?;
+    private readonly branchDescInfo;
+    constructor(builder: FlowChartBuilder<TOut, TScope>, curNode: StageNode<TOut, TScope>, curSpec: SerializedPipelineStructure, parentDescriptionParts?: string[], parentStageDescriptions?: Map<string, string>, reservedStepNumber?: number, deciderDescription?: string);
+    addFunctionBranch(id: string, name: string, fn?: StageFunction<TOut, TScope>, description?: string, 
+    /** `{ loopTo }` declares this branch loops back to an already-declared
+     *  stage — the loop is SOURCED FROM THIS BRANCH (not the decider). */
+    options?: {
+        readonly loopTo?: string;
+    }): DeciderList<TOut, TScope>;
+    /**
+     * Add a pausable stage as a decider branch.
+     *
+     * When this branch is chosen, the handler's `execute` runs. If it returns
+     * data, the pipeline pauses. On resume, `handler.resume` runs with the
+     * human's input. If `execute` returns void, the stage continues normally
+     * (conditional pause).
+     */
+    addPausableFunctionBranch(id: string, name: string, handler: PausableHandler<TScope>, description?: string, 
+    /** `{ loopTo }` declares this branch loops back to an already-declared
+     *  stage — the loop is SOURCED FROM THIS BRANCH (not the decider). */
+    options?: {
+        readonly loopTo?: string;
+    }): DeciderList<TOut, TScope>;
+    addSubFlowChartBranch(id: string, subflow: FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): DeciderList<TOut, TScope>;
+    addLazySubFlowChartBranch(id: string, resolver: () => FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): DeciderList<TOut, TScope>;
+    addBranchList(branches: Array<{
+        id: string;
+        name: string;
+        fn?: StageFunction<TOut, TScope>;
+    }>): DeciderList<TOut, TScope>;
+    setDefault(id: string): DeciderList<TOut, TScope>;
+    /**
+     * Attach a loop-back edge to the LAST-added branch, so the loop is sourced
+     * from THAT branch node (e.g. `'tool-calls' → loopTo('context')`) rather than
+     * from the decider. The chart then reads honestly: the decider splits into a
+     * looping branch `[ToolCalls → back to Context]` and a terminating branch
+     * `[Final → end]`, instead of a single loop hanging off the decider.
+     *
+     * No engine change is needed: the runtime runs the chosen branch and then
+     * follows that branch node's OWN `next` — and a `next` flagged `isLoopRef`
+     * routes back to the target exactly like the decider's own loop does. This
+     * method just lets the builder express what the engine already supports.
+     *
+     * Targets the branch added immediately before this call (chain it right after
+     * the branch's `addFunctionBranch`/`addPausableFunctionBranch`/
+     * `addSubFlowChartBranch`). Mirrors `FlowChartBuilder.loopTo` validation.
+     *
+     * Works on a SUBFLOW branch too: the branch node carries both its subflow
+     * resolver AND the loop-back `next` — they coexist safely (the runtime runs
+     * the subflow, then follows the loop ref). The target must be a stage already
+     * declared BEFORE the decider (e.g. an upstream `context`); branch ids and the
+     * synthetic `'default'` clone are NOT valid loop targets.
+     */
+    loopTo(stageId: string): DeciderList<TOut, TScope>;
+    /**
+     * Decorate ONE branch node/spec with a loop-back edge to `stageId`. Shared by
+     * the positional `loopTo()` (which targets the last-added branch) AND the
+     * per-branch `{ loopTo }` option on `addFunctionBranch` /
+     * `addPausableFunctionBranch` / `addSubFlowChartBranch`. Either way the loop
+     * SOURCE is the branch — so visualizers read `tool-calls → context`, never
+     * `Route → context`. Validates the target is a stage declared BEFORE the
+     * decider (branch ids / the synthetic 'default' clone are not valid targets).
+     */
+    private _applyBranchLoop;
+    end(): FlowChartBuilder<TOut, TScope>;
+}
+export declare class SelectorFnList<TOut = any, TScope = any> {
+    private readonly b;
+    private readonly curNode;
+    private readonly curSpec;
+    private readonly branchIds;
+    private readonly parentDescriptionParts;
+    private readonly parentStageDescriptions;
+    private readonly reservedStepNumber;
+    private readonly selectorDescription?;
+    private readonly branchDescInfo;
+    constructor(builder: FlowChartBuilder<TOut, TScope>, curNode: StageNode<TOut, TScope>, curSpec: SerializedPipelineStructure, parentDescriptionParts?: string[], parentStageDescriptions?: Map<string, string>, reservedStepNumber?: number, selectorDescription?: string);
+    addFunctionBranch(id: string, name: string, fn?: StageFunction<TOut, TScope>, description?: string): SelectorFnList<TOut, TScope>;
+    /**
+     * Add a pausable stage as a selector branch.
+     *
+     * When this branch is selected, the handler's `execute` runs. If it returns
+     * data, the pipeline pauses. On resume, `handler.resume` runs with the
+     * human's input. If `execute` returns void, the stage continues normally.
+     */
+    addPausableFunctionBranch(id: string, name: string, handler: PausableHandler<TScope>, description?: string): SelectorFnList<TOut, TScope>;
+    addSubFlowChartBranch(id: string, subflow: FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): SelectorFnList<TOut, TScope>;
+    addLazySubFlowChartBranch(id: string, resolver: () => FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): SelectorFnList<TOut, TScope>;
+    addBranchList(branches: Array<{
+        id: string;
+        name: string;
+        fn?: StageFunction<TOut, TScope>;
+    }>): SelectorFnList<TOut, TScope>;
+    end(): FlowChartBuilder<TOut, TScope>;
+}
+export declare class FlowChartBuilder<TOut = any, TScope = any> {
+    private _root?;
+    private _rootSpec?;
+    private _cursor?;
+    private _cursorSpec?;
+    private _stageMap;
+    _subflowDefs: Map<string, {
+        root: StageNode<TOut, TScope>;
+    }>;
+    private _streamHandlers;
+    /**
+     * L7.3 — Build-time observer fan-out. Owned by the builder so every
+     * `addX()` method can fire `StructureRecorder` events at the natural
+     * moment of the corresponding mutation. Dispatcher is allocated
+     * lazily on first attach to keep the zero-recorder path allocation-
+     * free.
+     */
+    private _structureDispatcher?;
+    /**
+     * L7.3 — Sealed-after-build flag (Panel 2 phase invariant). Flips
+     * to `true` when `.build()` returns; subsequent `attachStructureRecorder`
+     * throws. Prevents the footgun where a consumer attaches a recorder
+     * mid-execution and gets partial structure data (missed every event
+     * already fired during construction).
+     */
+    private _sealed;
+    private _enableNarrative;
+    private _logger?;
+    private _descriptionParts;
+    private _stepCounter;
+    private _stageDescriptions;
+    private _stageStepMap;
+    private _knownStageIds;
+    private _inputSchema?;
+    private _outputSchema?;
+    private _outputMapper?;
+    private _scopeFactory?;
+    /**
+     * Attach a `StructureRecorder` for build-phase observation. Multiple
+     * recorders coexist (same id allowed; iteration order = attach
+     * order). Throws if called after `.build()` — the chart is sealed at
+     * that point and any recorder attached late would miss every event
+     * fired during construction.
+     *
+     * **Seed replay**: when this is called AFTER `start()` has already
+     * fired (i.e., after the `flowChart()` factory returns), the
+     * just-attached recorder receives a one-time `onStageAdded` for the
+     * root stage so it observes the seed. Only the new recorder sees
+     * the replay; already-attached recorders are not re-fired.
+     *
+     * **Mid-chain attach caveat**: a recorder attached AFTER one or more
+     * `addX()` calls receives the seed replay but MISSES every
+     * intermediate event. Attach BEFORE the first `addX()` for complete
+     * capture.
+     *
+     * Public for now to enable direct attach in tests + early consumers.
+     * L7.4 will wire `flowChart(..., { structureRecorders: [...] })` as
+     * an additional registration site; this method will remain.
+     */
+    attachStructureRecorder(recorder: StructureRecorder): this;
+    /**
+     * Inspect accumulated `StructureBuildError`s. Returns empty array
+     * when no recorders attached OR no errors occurred. Returns a
+     * defensive copy — caller mutations do not affect subsequent calls.
+     *
+     * **Call on the BUILDER, not the chart returned by `.build()`.**
+     * Capture the builder reference before `.build()` if you need
+     * post-build access:
+     * ```ts
+     * const builder = flowChart(...).attachStructureRecorder(rec);
+     * const chart = builder.build();
+     * const errors = builder.getStructureBuildErrors();
+     * ```
+     */
+    getStructureBuildErrors(): ReturnType<StructureRecorderDispatcher['getErrors']>;
+    private _fireStageAdded;
+    private _fireEdgeAdded;
+    private _fireLoopEdgeAdded;
+    /**
+     * Fire the `next` edge(s) from a parent spec to a freshly-added
+     * node — with convergence expansion when the parent is a
+     * fork / decider / selector with branches.
+     *
+     * A fork at `parent` is semantically `parent ──fork-branch──► child[i]`
+     * for each child, and the chained `.addFunction(X)` continues
+     * AFTER the fork converges. The runtime semantics are that each
+     * child INDEPENDENTLY feeds `X` (parallel completion → join). The
+     * literal "edge from parent to X" would misrepresent this —
+     * visualizers and topological algorithms would see one edge where
+     * there should be N convergence edges.
+     *
+     * Fix: when `parentSpec` has branch children (fork or branched
+     * decider/selector), fire one `next` edge from EACH child to the
+     * target. Otherwise fire the single edge from `parentSpec` itself.
+     *
+     * Loop-reference children (synthetic spec nodes created by
+     * `.loopTo()`) are excluded — they're back-edge markers, not
+     * convergence sources. A branch that carries an OWN loop-back `next`
+     * (a branch-sourced `loopTo`) is likewise skipped — it loops, it does
+     * not converge at the linear next stage.
+     *
+     * A branch carrying `convergeAt` is REDIRECTED: its single convergence
+     * edge fires to its named target instead of `targetId` — expressing an
+     * unequal-depth merge (e.g. `tools → call-llm`, bypassing `message-api`).
+     * The named target is a forward stage, so it is NOT validated here.
+     *
+     * Call ORDER constraint: must be called BEFORE the cursor advances
+     * to the new target. The caller passes the PRE-ADVANCE parent spec.
+     */
+    private _fireNextEdgeFromParent;
+    private _fireDeciderComplete;
+    private _fireSubflowMounted;
+    /** Sub-builder access (`.b._fireXxx`) is needed by DeciderList /
+     *  SelectorFnList; expose the dispatcher through internal helpers
+     *  that go through the same no-op-when-absent guard.
+     *
+     *  @internal — these methods are exposed because TypeScript `private`
+     *  doesn't traverse class boundaries. Consumer code MUST NOT call
+     *  them; calling them post-construction lets a hostile caller
+     *  fabricate structure events and corrupt downstream visualizations
+     *  or audit trails. The `_` prefix is intentional convention. */
+    _fireEdgeAddedFromSubBuilder(from: string, to: string, kind: StructureEdgeKind, label?: string): void;
+    /** @internal — see `_fireEdgeAddedFromSubBuilder`. */
+    _fireStageAddedFromSubBuilder(spec: SerializedPipelineStructure): void;
+    /** @internal — see `_fireEdgeAddedFromSubBuilder`. */
+    _fireDeciderCompleteFromSubBuilder(decider: string, type: 'decider' | 'selector', branchIds: string[], defaultBranch?: string): void;
+    /** @internal — see `_fireEdgeAddedFromSubBuilder`. */
+    _fireSubflowMountedFromSubBuilder(subflowId: string, subflowName: string, rootStageId: string, isLazy?: boolean, subflowSpec?: SerializedPipelineStructure, subflowPath?: string): void;
+    /** @internal — see `_fireEdgeAddedFromSubBuilder`. Used by `DeciderList.loopTo`
+     *  to validate a branch-sourced loop target against the known stage ids
+     *  (mirrors `FlowChartBuilder.loopTo`'s `_knownStageIds.has` guard). */
+    _knownStageIdsHas(id: string): boolean;
+    /** @internal — see `_fireEdgeAddedFromSubBuilder`. Used by `DeciderList.loopTo`
+     *  to fire a loop back-edge SOURCED FROM A BRANCH node (not the decider). */
+    _fireLoopEdgeAddedFromSubBuilder(from: string, to: string): void;
+    private _appendDescriptionLine;
+    private _appendSubflowDescription;
+    setLogger(logger: ILogger): this;
+    /**
+     * Declare the API contract — input validation, output shape, and output mapper.
+     * Replaces setInputSchema() + setOutputSchema() + setOutputMapper() in a single call.
+     *
+     * If a contract with input schema is declared, chart.run() validates input automatically.
+     * Contract data is used by chart.toOpenAPI() and chart.toMCPTool().
+     */
+    contract(opts: {
+        input?: unknown;
+        output?: unknown;
+        mapper?: (finalScope: Record<string, unknown>) => unknown;
+    }): this;
+    start(name: string, fn: StageFunction<TOut, TScope> | PausableHandler<TScope>, id: string, description?: string): this;
+    /**
+     * Start a chart whose ROOT stage IS a selector — it runs first (reading
+     * args, seeding state, returning the chosen branch ids via `select()`),
+     * and its branches attach directly to the root. Mirrors `start()` for the
+     * root-node setup, then returns a `SelectorFnList` bound to the root so
+     * `.addFunctionBranch()` / `.addSubFlowChartBranch()` / `.end()` work
+     * exactly as they do after `addSelectorFunction()`.
+     *
+     * Use when the first thing a chart does is choose among branches — e.g. a
+     * `Context` selector that inits + picks which context slots to engineer,
+     * with no separate seed stage before it.
+     */
+    startSelector(name: string, fn: StageFunction<any, TScope>, id: string, description?: string, options?: {
+        failFast?: boolean;
+    }): SelectorFnList<TOut, TScope>;
+    addFunction(name: string, fn: StageFunction<TOut, TScope>, id: string, description?: string): this;
+    addStreamingFunction(name: string, fn: StageFunction<TOut, TScope>, id: string, streamId?: string, description?: string): this;
+    /**
+     * Add a pausable stage — can pause execution and resume later with input.
+     *
+     * The handler has two phases:
+     * - `execute`: runs first time. Return any non-void value to pause (it becomes
+     *   the checkpoint's `pauseData`); return void/undefined to continue normally.
+     * - `resume`: runs when the flowchart is resumed with input.
+     *
+     * @example
+     * ```typescript
+     * .addPausableFunction('ApproveOrder', {
+     *   execute: async (scope) => {
+     *     scope.orderId = '123';
+     *     return { question: 'Approve?' };
+     *   },
+     *   resume: async (scope, input) => {
+     *     scope.approved = input.approved;
+     *   },
+     * }, 'approve-order', 'Manager approval gate')
+     * ```
+     */
+    addPausableFunction(name: string, handler: PausableHandler<TScope>, id: string, description?: string): this;
+    /**
+     * Add a stage that fires a child flowchart on the given driver and
+     * DISCARDS the handle. Pure fire-and-forget — useful for telemetry
+     * exports, audit log shipping, cache warm-up.
+     *
+     * @param id Stable id for this stage (also the stageMap key).
+     * @param child The child flowchart to detach.
+     * @param options.driver The driver to schedule on (e.g. `microtaskBatchDriver`).
+     * @param options.inputMapper Maps the parent's scope to the child's input.
+     *   Defaults to passing `undefined`.
+     * @param options.mountName Display name; defaults to `id`.
+     * @param options.description Stage description for narrative + tools.
+     *
+     * @example
+     * ```ts
+     * import { microtaskBatchDriver } from 'footprintjs/detach';
+     *
+     * flowChart('process', processFn, 'process')
+     *   .addDetachAndForget('telemetry', telemetryChart, {
+     *     driver: microtaskBatchDriver,
+     *     inputMapper: (scope) => ({ event: 'processed', orderId: scope.orderId }),
+     *   })
+     *   .addFunction('next', nextFn, 'next')
+     *   .build();
+     * ```
+     */
+    addDetachAndForget(id: string, child: import('./types.js').FlowChart<any, any>, options: {
+        driver: import('../detach/types.js').DetachDriver;
+        inputMapper?: (scope: TScope) => unknown;
+        mountName?: string;
+        description?: string;
+    }): this;
+    /**
+     * Add a stage that fires a child flowchart on the given driver and
+     * delivers the resulting `DetachHandle` to a consumer-supplied
+     * `onHandle` callback. The handle CANNOT be stored in shared state
+     * — `StageContext.setValue` calls `structuredClone` which drops
+     * class prototypes (and therefore the handle's `.wait()` method).
+     *
+     * The callback pattern is the explicit alternative: keep handles in
+     * a closure-local array (or whatever shape suits) and have a
+     * downstream stage `await Promise.all(...)` over them.
+     *
+     * @example
+     * ```ts
+     * import { microtaskBatchDriver } from 'footprintjs/detach';
+     * import type { DetachHandle } from 'footprintjs/detach';
+     *
+     * const handles: DetachHandle[] = [];
+     *
+     * const chart = flowChart('seed', seedFn, 'seed')
+     *   .addDetachAndJoinLater('eval-a', evalChart, {
+     *     driver: microtaskBatchDriver,
+     *     inputMapper: (scope) => scope.configA,
+     *     onHandle: (h) => handles.push(h),
+     *   })
+     *   .addDetachAndJoinLater('eval-b', evalChart, {
+     *     driver: microtaskBatchDriver,
+     *     inputMapper: (scope) => scope.configB,
+     *     onHandle: (h) => handles.push(h),
+     *   })
+     *   .addFunction('join', async (scope) => {
+     *     const settled = await Promise.all(handles.map((h) => h.wait()));
+     *     scope.results = settled;
+     *   }, 'join')
+     *   .build();
+     * ```
+     *
+     * Note: putting `handles` in a module-level closure is fine for
+     * single-run scripts. For server code that runs the same chart
+     * concurrently across requests, allocate a new closure per run
+     * (e.g., wrap chart construction in a factory function) so handles
+     * from different runs don't bleed into each other.
+     */
+    addDetachAndJoinLater(id: string, child: import('./types.js').FlowChart<any, any>, options: {
+        driver: import('../detach/types.js').DetachDriver;
+        onHandle: (handle: import('../detach/types.js').DetachHandle) => void;
+        inputMapper?: (scope: TScope) => unknown;
+        mountName?: string;
+        description?: string;
+    }): this;
+    addDeciderFunction(name: string, fn: StageFunction<any, TScope>, id: string, description?: string): DeciderList<TOut, TScope>;
+    addSelectorFunction(name: string, fn: StageFunction<any, TScope>, id: string, description?: string, options?: {
+        failFast?: boolean;
+    }): SelectorFnList<TOut, TScope>;
+    addListOfFunction(children: SimplifiedParallelSpec<TOut, TScope>[], options?: {
+        failFast?: boolean;
+    }): this;
+    addSubFlowChart(id: string, subflow: FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): this;
+    addLazySubFlowChart(id: string, resolver: () => FlowChart<TOut, TScope>, mountName?: string, options?: SubflowMountOptions): this;
+    addLazySubFlowChartNext(id: string, resolver: () => FlowChart<TOut, TScope>, mountName?: string, options?: SubflowMountOptions): this;
+    addSubFlowChartNext(id: string, subflow: FlowChart<any, any>, mountName?: string, options?: SubflowMountOptions): this;
+    loopTo(stageId: string): this;
+    onStream(handler: StreamTokenHandler): this;
+    onStreamStart(handler: StreamLifecycleHandler): this;
+    onStreamEnd(handler: StreamLifecycleHandler): this;
+    build(): RunnableFlowChart<TOut, TScope>;
+    /** Override the scope factory. Rarely needed — auto-embeds TypedScope by default. */
+    setScopeFactory(factory: ScopeFactory<TScope>): this;
+    toSpec<TResult = SerializedPipelineStructure>(): TResult;
+    toMermaid(): string;
+    private _needCursor;
+    private _needCursorSpec;
+    /**
+     * Advance the spec cursor. Retained as a method so call sites stay
+     * one-liners and future cursor-related side effects have a hook.
+     */
+    private _advanceCursorSpec;
+    _stageMapHas(key: string): boolean;
+    _addToMap(id: string, fn: StageFunction<TOut, TScope>): void;
+    _mergeStageMap(other: Map<string, StageFunction<TOut, TScope>>, prefix?: string): void;
+    _prefixNodeTree(node: StageNode<TOut, TScope>, prefix: string): StageNode<TOut, TScope>;
+    _mergeSubflows(subflows: Record<string, {
+        root: StageNode<TOut, TScope>;
+    }> | undefined, prefix: string): void;
+}
+/**
+ * Start a flowchart with its first stage; returns a fluent builder.
+ *
+ * Chain `.addFunction()` / `.addDeciderFunction()` / `.addSelectorFunction()` /
+ * `.addSubFlowChart()` etc. to add more stages, then finish with `.build()`.
+ *
+ * @param name    Human-readable display label for the stage (shown in the narrative/trace).
+ * @param fn      The stage's work — a `(scope) => …` function, or a `PausableHandler` for human-in-the-loop pauses.
+ * @param id      Stable stage id used in traces, the commit log, and `runtimeStageId`. Keep it unique within the chart.
+ * @param options Optional `{ description?, structureRecorders? }`.
+ *
+ * @example
+ * const chart = flowChart<State>('FetchUser', async (scope) => {
+ *   scope.user = await getUser();
+ * }, 'fetch-user')
+ *   .addFunction('Process', processFn, 'process')
+ *   .build();
+ *
+ * const trace = narrative();
+ * const result = await chart.recorder(trace).run();
+ * console.log(trace.getEntries().map((e) => e.text).join('\n'));
+ */
+export declare function flowChart<TState extends object>(name: string, fn: TypedStageFunction<TState> | PausableHandler<TypedScope<TState>>, id: string, options?: FlowChartOptions): FlowChartBuilder<any, TypedScope<TState>>;
+export declare function flowChart<TOut = any, TScope = any>(name: string, fn: StageFunction<TOut, TScope> | PausableHandler<TScope>, id: string, options?: FlowChartOptions): FlowChartBuilder<TOut, TScope>;
+/**
+ * Like `flowChart()`, but the ROOT stage is a SELECTOR — it runs first and
+ * its branches attach directly to it (no separate seed stage). Returns a
+ * `SelectorFnList`; declare branches then call `.end()` to get the builder
+ * back for any subsequent stages.
+ *
+ * @example
+ *   flowChartSelector<MyState>('Context', contextSelectorFn, 'context')
+ *     .addSubFlowChartBranch('sf-system-prompt', sysSlot, 'System Prompt', {...})
+ *     .addSubFlowChartBranch('sf-messages', msgSlot, 'Messages', {...})
+ *     .end()
+ *     .addFunction('messageAPI', assembleFn, 'message-api')
+ *     .build();
+ */
+export declare function flowChartSelector<TOut = any, TScope = any>(name: string, fn: StageFunction<any, TScope>, id: string, options?: FlowChartOptions): SelectorFnList<TOut, TScope>;
+export declare function specToStageNode(spec: FlowChartSpec): StageNode<any, any>;