@particle-academy/fancy-flow 0.65.1 → 0.66.0

package/dist/types-B-Syk9-M.d.cts

@@ -0,0 +1,620 @@
+import { Node, Edge } from '@xyflow/react';
+
+/**
+ * Host capabilities — the services core nodes need but must never depend on.
+ *
+ * A node that imports a provider SDK forces every consumer to install it: a
+ * workflow app that never calls a model should not inherit an LLM dependency.
+ * So core declares the CONTRACT and the host supplies the implementation, the
+ * same arrangement `renderDocumentField` already uses for documents.
+ *
+ * That keeps opinionated nodes in core without their opinions: `llm_branch`
+ * ships the routing semantics, port derivation and config UI, while whichever
+ * client the host registers — Prism, an OpenAI SDK, a local model, a fake in a
+ * test — decides how the question actually gets asked.
+ *
+ * Registration is deliberately explicit and typed per capability rather than a
+ * stringly-keyed bag, so a missing one is a clear error at the seam instead of
+ * an undefined somewhere downstream.
+ */
+type LlmRoute = {
+    port: string;
+    description?: string;
+};
+type LlmRouteRequest = {
+    /** Optional framing for the decision. */
+    system?: string;
+    /** What the model is deciding about. */
+    prompt: string;
+    /** The ports it must choose between. */
+    routes: LlmRoute[];
+    provider?: string;
+    model?: string;
+    /** Host-resolved credential reference, never a raw key. */
+    credential?: string;
+};
+type LlmRouteChoice = {
+    /** Must be one of the requested route ports. */
+    port: string;
+    /** Why — carried down the chosen port so a run is explainable afterwards. */
+    reason?: string;
+};
+/**
+ * The only thing core asks of an LLM: given routes, pick one.
+ *
+ * Deliberately not a general chat interface. A narrow contract is one a host
+ * can satisfy in a few lines over any SDK, and it keeps the choice
+ * machine-checkable — an implementation should constrain the model to the
+ * declared ports (structured output / enum) rather than parsing prose.
+ */
+type LlmClient = {
+    chooseRoute: (request: LlmRouteRequest) => Promise<LlmRouteChoice> | LlmRouteChoice;
+};
+/** Install the host's LLM client. Returns an unregister function. */
+declare function registerLlmClient(client: LlmClient): () => void;
+declare function getLlmClient(): LlmClient | null;
+/** What to launch. Omit `command` for the host's default shell. */
+type TerminalSessionSpec = {
+    command?: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+    cols?: number;
+    rows?: number;
+};
+type TerminalExit = {
+    exitCode: number;
+    signal?: string;
+};
+/**
+ * One live terminal, owned by the host for as long as the run needs it.
+ *
+ * Output arrives by SUBSCRIPTION rather than a `read()` the engine calls. A TUI
+ * emits continuously and on its own schedule — repainting, streaming a reply,
+ * redrawing a spinner — so a polled read either misses bytes between calls or
+ * has to buffer them anyway, and every host would invent that buffer
+ * differently.
+ */
+type TerminalSession = {
+    id: string;
+    write: (data: string) => void | Promise<void>;
+    /** Subscribe to output. Returns an unsubscribe. */
+    onData: (listener: (chunk: string) => void) => () => void;
+    /**
+     * Resolves when the process exits.
+     *
+     * A promise rather than an `exited` flag the engine polls, so "the agent
+     * quit" and "the agent has not answered yet" are distinguishable while
+     * waiting. Without it a node awaiting output cannot tell a slow reply from a
+     * dead process, and waits out its timeout either way.
+     */
+    exited: Promise<TerminalExit>;
+    close: () => void | Promise<void>;
+};
+/**
+ * The only thing core asks of a terminal: open one.
+ *
+ * ## Why the contract stops at the PTY
+ *
+ * There is deliberately no `waitForOutput(pattern)` here, though every terminal
+ * node needs one. Matching is derivable from `onData`, so putting it in the
+ * contract would mean every host implements it — and two implementations of one
+ * agreed rule is precisely how a week of registry defects happened: both sides
+ * agreed output matching should work, and would have disagreed on whether a
+ * pattern spans chunk boundaries, whether ANSI escapes are stripped first, and
+ * what a timeout returns.
+ *
+ * So core owns the matching and the host owns the process. A host satisfies
+ * this in a few lines over `node-pty`; nothing about how a run interprets the
+ * bytes is up to it.
+ *
+ * ## Why this exists at all
+ *
+ * A terminal cannot live in the engine. `node-pty` is a native addon, so
+ * importing it would break every browser build of this package and force the
+ * dependency on consumers who never run a terminal node — the same reason the
+ * LLM client is a contract rather than an SDK import. The desktop app that CAN
+ * spawn a PTY registers one; everyone else never notices the capability exists.
+ */
+type TerminalHost = {
+    open: (spec: TerminalSessionSpec) => Promise<TerminalSession> | TerminalSession;
+};
+/** Install the host's terminal. Returns an unregister function. */
+declare function registerTerminalHost(host: TerminalHost): () => void;
+declare function getTerminalHost(): TerminalHost | null;
+/**
+ * Why a workflow reference could not be resolved.
+ *
+ * `missing` and `version-mismatch` are deliberately distinct. Collapsing them
+ * into a bare null makes "no such workflow" indistinguishable from "that
+ * workflow exists, but it is not the one you pinned" — and the second wants an
+ * error naming both versions, because it is the interesting failure.
+ */
+type WorkflowResolutionFailure = {
+    reason: "missing" | "version-mismatch";
+    /** The version the host actually holds, when it holds one. */
+    available?: number;
+    message?: string;
+};
+type WorkflowResolution = FlowGraph | WorkflowResolutionFailure | null;
+/**
+ * Resolve a workflow reference to a runnable graph.
+ *
+ * `subflow` names another workflow rather than embedding it, so the host owns
+ * where workflows live — a database, a file, an API.
+ *
+ * ## Why `version` is here
+ *
+ * A workflow another workflow depends on is an INTERFACE, and interfaces need
+ * pins. Without a version, a parent goes on calling `invoice-triage`, someone
+ * edits that child, and the parent now runs different logic having reported
+ * success the whole time — correct-looking, no error, wrong behaviour. The same
+ * failure family as the 0.9.0 routing divergence.
+ *
+ * The parameter lives on the resolver rather than being encoded into the ref
+ * string (`invoice-triage@3`) because a stringly-typed protocol is one every
+ * host invents differently — the "three vocabularies for one node" problem.
+ *
+ * Raised by the MOIC Suite consumer, whose `workflow_ref` pins versions and
+ * fails loudly on mismatch. Their point: a host COULD NOT implement pinning
+ * before this, because the node had no way to ask and the resolver no way to
+ * receive.
+ *
+ * Returning `null` still means "no such workflow". Return a
+ * {@link WorkflowResolutionFailure} to distinguish a version mismatch.
+ */
+type WorkflowResolver = (ref: string, version?: number) => Promise<WorkflowResolution> | WorkflowResolution;
+/** Narrow a resolver's return value to an explicit failure. */
+declare function isResolutionFailure(value: WorkflowResolution): value is WorkflowResolutionFailure;
+/** Install the host's workflow resolver. Returns an unregister function. */
+declare function registerWorkflowResolver(resolver: WorkflowResolver): () => void;
+declare function getWorkflowResolver(): WorkflowResolver | null;
+type CapabilityId = "llm" | "workflow_resolver" | "document" | "terminal";
+/**
+ * Which capabilities are currently satisfied.
+ *
+ * Exists so a host (or the CLI, or an agent over MCP) can answer "what does
+ * this graph need that I haven't wired?" BEFORE a run fails halfway through.
+ */
+declare function capabilityStatus(): Record<CapabilityId, boolean>;
+
+/**
+ * What a terminal has said, in a form a node can wait on.
+ *
+ * A raw `onData` stream is not something a workflow can match against, for
+ * three reasons that all fail the same way — intermittently, and usually only
+ * once there is real output moving:
+ *
+ *  1. **Chunks are arbitrary.** A PTY splits wherever it splits, so `Ready >`
+ *     can arrive as `Rea` + `dy >`. Testing each chunk on its own finds the
+ *     pattern when output is small enough to land in one write and misses it
+ *     when it is not. So matching runs against an ACCUMULATED buffer, never a
+ *     chunk.
+ *
+ *  2. **Output arrives before anyone is listening.** A node that types at a
+ *     process and a node that waits for its reply are two steps, and anything
+ *     printed between them is gone if the buffer starts when the wait does.
+ *     So the transcript is attached when the SESSION opens, and a wait reads
+ *     what has already accumulated before it subscribes to anything new.
+ *
+ *  3. **Escape sequences are everywhere and they also straddle.** An agent TUI
+ *     writes `Ready` as `ESC[32m Ready ESC[0m`, so matching raw bytes fails on
+ *     text a person can plainly read. Stripping per chunk reintroduces problem
+ *     1 in a second guise — `ESC[3` + `2mReady` strips to `ESC[32mReady` with
+ *     the escape now INSIDE the text. So an incomplete trailing sequence is
+ *     held back until the rest of it arrives.
+ *
+ * Text is consumed through a match, so two waits for the same pattern do not
+ * both resolve on the first occurrence — which would let a loop appear to make
+ * progress while reading one old line forever.
+ */
+type TranscriptWaitResult = {
+    status: "matched";
+    text: string;
+    match: RegExpMatchArray;
+} | {
+    status: "timeout";
+    text: string;
+} | {
+    status: "exited";
+    text: string;
+    exitCode: number;
+    signal?: string;
+};
+declare class TerminalTranscript {
+    /** Stripped, complete text not yet consumed by a wait. */
+    private text;
+    /** Raw bytes held back because they may be the start of an escape sequence. */
+    private tail;
+    private readonly waiters;
+    /** Feed raw terminal output in. Safe to call with any chunking. */
+    append(chunk: string): void;
+    /**
+     * How much of `tail` can be stripped now.
+     *
+     * Everything, unless the final `ESC` has not yet been terminated — in which
+     * case processing stops there and resumes when the rest arrives.
+     */
+    private safeLength;
+    /** Unconsumed output, escape sequences removed. */
+    peek(): string;
+    /** Drop everything currently buffered — used before typing a new command. */
+    clear(): void;
+    /**
+     * Wait until `pattern` matches the unconsumed text.
+     *
+     * Checks what has ALREADY arrived before subscribing, because the common case
+     * is that the process answered while the previous node was still finishing.
+     *
+     * `exited` is raced deliberately. Without it, a shell that dies reports as
+     * "timed out waiting for X" — sending whoever reads it to lengthen a timeout
+     * for a process that is not running. Naming the exit is the difference
+     * between a diagnosis and a wrong lead.
+     */
+    waitFor(pattern: RegExp, options: {
+        timeoutMs: number;
+        exited?: Promise<{
+            exitCode: number;
+            signal?: string;
+        }>;
+    }): Promise<TranscriptWaitResult>;
+}
+
+/**
+ * Who is running, which step this is, and how many times it has been tried.
+ *
+ * ## Why an engine needs this at all
+ *
+ * A node that WRITES to somebody else's system — charge a card, send a message,
+ * open a pull request — can only survive a retry if the retry carries the same
+ * idempotency key the first attempt did. Otherwise the provider treats the
+ * second call as a new request and the customer is charged twice.
+ *
+ * Until this existed the executor context was `{ node, inputs, emit, abort }`,
+ * which is not enough to derive one. Both obvious fallbacks are worse than
+ * sending no key at all:
+ *
+ * - **the node id alone** is stable across retries, and also across RUNS — two
+ *   legitimate payments share a key and the provider silently collapses the
+ *   second into the first. A payment that never happened, reported as success;
+ * - **a fresh random value** is unique per run, and also per ATTEMPT — a retry
+ *   creates a second charge, which is the thing being avoided.
+ *
+ * ## What actually identifies a step
+ *
+ * Not `(run, node)`. A node legitimately executes more than once inside one
+ * run: once per subflow invocation, once per iteration of a loop an executor
+ * drives itself. `(run, node)` would give every one of those the same key, and
+ * a provider would honour exactly one of them.
+ *
+ * So a step is identified by the **path of invocations that led to it**, plus
+ * an optional **occurrence** for repetition at the same level:
+ *
+ * ```text
+ * runKey ":" segment ("/" segment)*        segment := escape(id) ["#" occurrence]
+ * ```
+ *
+ * And the part that is easy to get backwards: **`attempt` is NOT in the key.**
+ * It is carried here for logging and for {@link RunIdentity.isReplaySafe}, and
+ * putting it in the key would restore the exact bug the key exists to prevent.
+ *
+ * Pinned cross-runtime by `shared/flow-run-identity` in
+ * `@particle-academy/fancy-conformance`.
+ */
+/** The wire shape — what a queue job payload carries. */
+type RunIdentityJson = {
+    runKey: string;
+    path?: string[];
+    attempt?: number;
+    firstAttemptAt?: string;
+};
+/**
+ * Escape one segment so the composition is injective.
+ *
+ * `%` FIRST, or the escaping is not reversible: escaping `/` before `%` turns a
+ * literal `a%2Fb` into the same text as the escaped form of `a/b`, which is the
+ * collision this exists to prevent, reintroduced by its own fix.
+ */
+declare function escapeSegment(value: string): string;
+/**
+ * A run, a position inside it, and how many times this position has been tried.
+ *
+ * Immutable. {@link descend} returns a new identity rather than mutating, so an
+ * executor cannot change what its siblings see.
+ */
+declare class RunIdentity {
+    /** Stable for the whole run: same across retries, resumes, workers and hosts. */
+    readonly runKey: string;
+    /**
+     * Enclosing invocation segments, outermost first, ALREADY RENDERED.
+     *
+     * Empty at the top level. A subflow pushes the invoking node's id; an
+     * executor that loops pushes `id#i`.
+     */
+    readonly path: readonly string[];
+    /**
+     * 1-based attempt of THIS logical step. Never part of the key.
+     *
+     * The durable driver sets it from the node's claim row, which is exact. A
+     * plain in-process `runFlow` gets whatever the host passed, which is
+     * run-scoped and therefore conservative — see `isReplaySafe`.
+     */
+    readonly attempt: number;
+    /** ISO-8601 UTC instant of attempt 1 of this step. */
+    readonly firstAttemptAt: string;
+    constructor(runKey: string, path?: readonly string[], attempt?: number, firstAttemptAt?: string);
+    /**
+     * The identity of one execution of one node — stable across retries of that
+     * execution, distinct from every other execution of the same node.
+     *
+     * Pass `occurrence` when an executor runs the same node more than once at the
+     * same level (a loop body, one item of a fan-out it drives itself).
+     */
+    stepKey(nodeId: string, occurrence?: number | null): string;
+    /**
+     * A child identity for work nested inside this step.
+     *
+     * `subflow` pushes the invoking node's id, so a node inside the child graph
+     * cannot collide with a same-named node in the parent. Attempt and
+     * `firstAttemptAt` are carried down unchanged: the nested work happens inside
+     * this step's attempt, and shares its clock.
+     */
+    descend(segment: string, occurrence?: number | null): RunIdentity;
+    /** A copy on a different attempt, first-attempt clock preserved. */
+    withAttempt(attempt: number, firstAttemptAt?: string): RunIdentity;
+    /**
+     * May this attempt reuse the step key and still be deduplicated?
+     *
+     * Providers forget idempotency keys — Stripe after 24 hours. Past that
+     * window, resending the key creates a second charge and sending a fresh one
+     * creates a second charge, so **the caller must refuse rather than pick
+     * between them**: a loud stuck run beats a silent double write.
+     *
+     * `true` on attempt 1 whatever the elapsed time — nothing was sent on an
+     * earlier attempt, so there is nothing for the provider to have forgotten.
+     * That is what lets a run park on a human gate for a week and then write.
+     *
+     * `windowSeconds: null` means the provider does not expire keys. `0` means
+     * it does not dedupe at all, so no retry may reuse a key — it is a real
+     * window, not an absent one, and the two must not be conflated: reading `0`
+     * as `null` turns "this provider does not dedupe" into "this provider
+     * dedupes forever", which is the more dangerous of the two by a distance.
+     */
+    isReplaySafe(windowSeconds: number | null | undefined, now?: Date | string): boolean;
+    toJSON(): Required<RunIdentityJson>;
+    /** Rebuild from a queue payload. */
+    static from(value: RunIdentity | RunIdentityJson | string): RunIdentity;
+}
+
+type FlowNodeKind = "trigger" | "action" | "decision" | "output" | "note" | "subgraph";
+/** Status surfaced on the node while a run is in progress. */
+type NodeRunStatus = "idle" | "queued" | "running" | "done" | "error";
+/** Port description on a node. Ports are visual handles xyflow can connect. */
+type PortDescriptor = {
+    id: string;
+    label?: string;
+    /** Optional logical type for hosts that want to validate connections. */
+    type?: string;
+};
+/** Common shape every kit node carries in its `data` slot. */
+type BaseNodeData = {
+    label: string;
+    description?: string;
+    /** Free-form configuration the host owns (form values, code, parameters). */
+    config?: Record<string, unknown>;
+    /** Set by the runner; hosts shouldn't edit this directly. */
+    status?: NodeRunStatus;
+    /** Optional human-readable status detail (e.g. error message, current step). */
+    statusText?: string;
+    /**
+     * Announced to a person just BEFORE this node runs — "Starting the deep
+     * analysis". Authored on the node, so a graph narrates itself without the
+     * host writing any per-node reporting code.
+     *
+     * Optional on purpose. Most nodes in a real graph are plumbing, and a run
+     * that narrates all of them buries the two or three steps anyone follows.
+     */
+    startingMsg?: string;
+    /**
+     * Announced AFTER this node finishes — "Analysis complete".
+     *
+     * Emitted only when the node SUCCEEDS. A completion message printed after a
+     * failure tells a human the opposite of what happened, in the part of the UI
+     * they trust most; failures report through `node-status` and `log`.
+     */
+    stoppingMsg?: string;
+    /** Per-node accent override, e.g. for theming a custom subclass. */
+    color?: string;
+    /** Input ports rendered on the node. Defaults vary by kind. */
+    inputs?: PortDescriptor[];
+    /** Output ports rendered on the node. Defaults vary by kind. */
+    outputs?: PortDescriptor[];
+};
+type TriggerNodeData = BaseNodeData & {
+    kind: "trigger";
+};
+type ActionNodeData = BaseNodeData & {
+    kind: "action";
+};
+type DecisionNodeData = BaseNodeData & {
+    kind: "decision";
+};
+type OutputNodeData = BaseNodeData & {
+    kind: "output";
+};
+type NoteNodeData = BaseNodeData & {
+    kind: "note";
+    body?: string;
+};
+type SubgraphNodeData = BaseNodeData & {
+    kind: "subgraph";
+    /** Ids of the nodes contained in this subgraph. */
+    childIds?: string[];
+    /** Whether the subgraph is shown collapsed (default true — children hidden). */
+    collapsed?: boolean;
+};
+type FlowNodeData = TriggerNodeData | ActionNodeData | DecisionNodeData | OutputNodeData | NoteNodeData | SubgraphNodeData;
+type FlowNode = Node<FlowNodeData>;
+type FlowEdge = Edge;
+/**
+ * One value a workflow DECLARES that it accepts at run start.
+ *
+ * The declaration is the point. Before this existed, a caller passed
+ * `initialInputs` keyed BY NODE ID — so they had to know the trigger happened
+ * to be called `t`, and renaming that node broke every caller while the graph
+ * itself stayed valid. Nothing reported it.
+ *
+ * And nothing said what a workflow accepted at all: no names, no types, no
+ * defaults. An agent composing a call had nothing to read, and a misspelled key
+ * did not fail — the value simply sat unused while the run reported success.
+ */
+type WorkflowInput = {
+    /** What a caller passes it as. */
+    name: string;
+    /**
+     * Optional. Omitting it means "I am not asserting a shape", which must not
+     * degrade into "nothing is allowed" — an undeclared type accepts anything.
+     */
+    type?: "string" | "number" | "boolean" | "object" | "array";
+    /**
+     * The run needs a value. Satisfied by a `default`, so `required` means
+     * "this must resolve to something" rather than "the caller must type it".
+     */
+    required?: boolean;
+    /** Used when the caller omits the key. An explicit value always wins. */
+    default?: unknown;
+    description?: string;
+};
+/** A serializable graph — what hosts persist, what agents read/write. */
+type FlowGraph = {
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+    /**
+     * What this workflow accepts. Callers pass a flat object BY NAME.
+     *
+     * Omitted entirely when a graph takes none, so existing saved graphs are
+     * unchanged byte for byte and every diff stays readable.
+     */
+    inputs?: WorkflowInput[];
+};
+/** Per-node executor signature. Inputs are keyed by input-port id. */
+type NodeExecutor<TIn = Record<string, unknown>, TOut = unknown> = (ctx: {
+    node: FlowNode;
+    inputs: TIn;
+    /** Stops the run if called. */
+    abort: (reason?: string) => never;
+    /** Lets the executor stream status updates and partial outputs. */
+    emit: (event: RunEvent) => void;
+    /**
+     * The registry THIS run is executing against.
+     *
+     * Handed down so an executor that starts a NESTED run gives the child the
+     * same executors as the parent. `subflow` previously ran its child against
+     * `config.executors ?? {}` — an empty registry unless the graph happened to
+     * carry one — so a host kind resolved at top level and vanished one level
+     * down, and a host that had REPLACED a builtin got the package's version in
+     * the child. Same graph, different behaviour by nesting depth, reported
+     * against the PHP twin as fancy-flow-php#7.
+     *
+     * Inheriting from the context rather than from a parameter is what makes it
+     * unforgettable: any future nesting executor gets it without opting in.
+     */
+    executors?: ExecutorRegistry;
+    /**
+     * How deep this run is nested. 0 for a top-level run; `subflow` passes
+     * depth + 1 to its child, so runaway recursion can be reported by name
+     * rather than as a stack overflow.
+     */
+    depth?: number;
+    /**
+     * Who is running, and which attempt of which step this is.
+     *
+     * `ctx.run.stepKey(ctx.node.id)` is the idempotency key for a node that
+     * writes to somebody else's system — stable across retries of this step,
+     * distinct for every other execution of the same node.
+     *
+     * `undefined` when the host supplied no identity, and that is a real
+     * answer: a write with no key must decline or accept one attempt, never
+     * invent a key. See `RunIdentity`.
+     */
+    run?: RunIdentity;
+    /**
+     * The terminal this node's lane owns, if it is inside a terminal lane.
+     *
+     * `session()` is a FUNCTION, not an open session, and that is the whole
+     * lifetime rule in one shape: the terminal opens on first USE. A node that
+     * sits inside a terminal lane and never calls this never spawns a process,
+     * so drawing a lane around nodes that mostly do other things costs nothing.
+     * Every node in the lane gets the SAME session, which is what makes `cd`
+     * persist and an agent TUI still be running with its conversation intact.
+     *
+     * `undefined` when the node is not inside a terminal lane, and that is a
+     * real answer rather than a missing one — a terminal node outside a lane
+     * must say so rather than quietly opening a shell of its own, because one
+     * unmanaged process per node is exactly what the lane exists to prevent.
+     */
+    terminal?: {
+        session: () => Promise<TerminalSession>;
+        /**
+         * What the terminal has said, accumulated and matchable.
+         *
+         * Separate from `session()` because reading and writing are genuinely
+         * different jobs with different hazards. `session()` hands over the raw
+         * process; this hands over a buffer that already survived arbitrary
+         * chunking, escape sequences that straddle chunks, and output that
+         * arrived before any node was listening — none of which a node should be
+         * asked to get right on its own, and all of which fail intermittently
+         * when it doesn't.
+         *
+         * Opening the session is implied: a transcript with nothing feeding it
+         * would silently never match.
+         */
+        transcript: () => Promise<TerminalTranscript>;
+    };
+}) => Promise<TOut> | TOut;
+type ExecutorRegistry = Partial<Record<FlowNodeKind | string, NodeExecutor>>;
+type RunEvent = {
+    type: "node-status";
+    nodeId: string;
+    status: NodeRunStatus;
+    text?: string;
+}
+/**
+ * A human-facing announcement a node makes around its own execution, from
+ * `data.startingMsg` / `data.stoppingMsg`. Opt-in per node: most nodes in a
+ * real graph are plumbing, and narrating all of them buries the few steps a
+ * person cares about.
+ *
+ * Deliberately NOT folded into `node-status.text`, which already carries
+ * "skipped", "resumed", "lane", "annotation" and raw error strings. Those are
+ * diagnostics; these are addressed to a person. A consumer rendering a
+ * progress feed cannot be asked to guess which is which — that is how an
+ * error string ends up shown to a user as a status update.
+ */
+ | {
+    type: "node-message";
+    nodeId: string;
+    phase: "start" | "end";
+    message: string;
+} | {
+    type: "node-output";
+    nodeId: string;
+    portId: string;
+    value: unknown;
+} | {
+    type: "log";
+    nodeId?: string;
+    level: "info" | "warn" | "error";
+    message: string;
+    detail?: unknown;
+} | {
+    type: "run-start";
+} | {
+    type: "run-end";
+    ok: boolean;
+} | {
+    type: "run-error";
+    error: string;
+};
+
+export { type ActionNodeData as A, type BaseNodeData as B, type CapabilityId as C, type DecisionNodeData as D, type ExecutorRegistry as E, type FlowGraph as F, type WorkflowInput as G, type LlmClient as L, type NodeExecutor as N, type OutputNodeData as O, type PortDescriptor as P, type RunEvent as R, type SubgraphNodeData as S, type TerminalHost as T, type WorkflowResolver as W, type FlowNode as a, type LlmRouteRequest as b, RunIdentity as c, type RunIdentityJson as d, type FlowEdge as e, type FlowNodeData as f, type FlowNodeKind as g, type NodeRunStatus as h, type NoteNodeData as i, type TriggerNodeData as j, escapeSegment as k, type LlmRoute as l, type LlmRouteChoice as m, type TerminalExit as n, type TerminalSession as o, type TerminalSessionSpec as p, type WorkflowResolution as q, type WorkflowResolutionFailure as r, capabilityStatus as s, getLlmClient as t, getTerminalHost as u, getWorkflowResolver as v, isResolutionFailure as w, registerLlmClient as x, registerTerminalHost as y, registerWorkflowResolver as z };