@ghchinoy/litflow 0.2.7 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 2025-12-26
+- Implement M3-styled Controls component (litflow-qwm)
+- Style lit-handle with Material 3 (litflow-rip)
+- Style lit-node with Material 3 (litflow-clx)
+- Example: Static Documentation Display (litflow-l52)
+- Packaging and Distribution (litflow-b9b)
+- Example: Subflows (Parent/Child) (litflow-2lt)
+- Example: Custom Edges (Step/SmoothStep) (litflow-8zz)
+- Implement manual edge connections (litflow-ycn)
+- Establish Material 3 Design System (litflow-m7y)
+- Investigate and fix node jumping on subsequent drags (litflow-v7y)
+- Example: Custom Nodes with Lit templates (litflow-aop)
+- Implement Controls and MiniMap components (litflow-04c)
+- Example: Dynamic Interactivity (Add/Remove) (litflow-4bd)
+- Implement SignalWatcher in lit-node and lit-edge (litflow-lu1)
+- Integrate Lit Signals for state management (litflow-txd)
+- Refactor store.ts to use @lit-labs/signals (litflow-jdv)
+- Migrate from npm to pnpm (litflow-ytd)
+- Example: Multiple Handles/Ports (litflow-e6c)
+- Example: Basic Flow (litflow-xzk)
+- Setup examples/ directory and base runner (litflow-8oj)
+
+## 2025-12-27
+- Implement Advanced FitView (litflow-w6a)
+- Example: Gemini AI Nodes (Prompt & Image) (litflow-ln0)
+- Implement Keyboard Interactivity (litflow-d81)
+- Validate and Debug Marquee Selection reliability (litflow-cc1)
+- Example: Overview (litflow-59h)
+- Implement Marquee Selection (litflow-ucl)
+- Investigate and implement Edge Labels (litflow-3z2)
+- Implement Edge Markers (Arrowheads) (litflow-c56)
+- Configurable Node Naming on Drop (litflow-8ku)
+- Create Drag & Drop Guide (litflow-w6v)
+- Example: Drag & Drop (litflow-lyd)
+- Implement M3-styled Sidebar for Drag & Drop (litflow-kyi)
+- Implement project method in LitFlow (litflow-ypx)
+- Investigate and implement Edge Labels (litflow-1ed)
+- Tutorial: Building Static Documentation with LitFlow (litflow-vgd)
+- Project Documentation System (Eleventy + Diataxis + gh-pages) (litflow-46j)
+- Draft Welcome Landing Page (litflow-46j.5)
+- Configure GitHub Actions Deployment (litflow-46j.4)
+- Implement Live Example integration (litflow-46j.3)
+- Migrate and structure docs using Diataxis (litflow-46j.2)
+- Initialize Eleventy project in docs/ (litflow-46j.1)
+- Example: Graphviz to LitFlow (litflow-48p)
+
+## 2025-12-29
+- Implement Real LitFlowRunner (litflow-wmj)
+- Implement Mock Runner (litflow-wjn)
+- Implement LitSchemaNode (litflow-ztw)
+- Analysis: Phase 3 - GenAI & Gemini Integration (litflow-9ms)
+- Analysis: Phase 2 - Graph Execution (The Core) (litflow-i81)
+- Designer: Integrate Drag & Drop Palette (litflow-aa8)
+- Example: Inspector Designer with live JSON sync (litflow-0i5)
+

package/dist/breadboard/data/common.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { CodeExecutionResultPart, ExecutableCodePart, FileDataPart, FunctionCallCapabilityPart, FunctionResponseCapabilityPart, InlineDataCapabilityPart, JSONPart, ListPart, LLMContent, OutputValues, StoredDataCapabilityPart, TextCapabilityPart } from "@breadboard-ai/types";
+import { Chunk, DataCapability, DataPartTransformer, DataPartTransformType, Outcome } from "@breadboard-ai/types";
+import { isStoredData } from "@breadboard-ai/utils";
+export { isCodeExecutionResultPart, isExecutableCodePart, isStoredData };
+export declare function isImageURL(nodeValue: unknown): nodeValue is {
+    image_url: string;
+};
+export declare function isTextCapabilityPart(part: unknown): part is TextCapabilityPart;
+export declare function isFileDataCapabilityPart(part: unknown): part is FileDataPart;
+export declare function isFunctionCallCapabilityPart(part: unknown): part is FunctionCallCapabilityPart;
+export declare function isFunctionResponseCapabilityPart(part: unknown): part is FunctionResponseCapabilityPart;
+export declare function isJSONPart(part: unknown): part is JSONPart;
+export declare function isListPart(part: unknown): part is ListPart;
+export declare function isLLMContent(nodeValue: unknown): nodeValue is LLMContent;
+export declare function isLLMContentArray(nodeValue: unknown): nodeValue is LLMContent[];
+export declare function isMetadataEntry(nodeValue: LLMContent): boolean;
+export declare const isDataCapability: (value: unknown) => value is DataCapability;
+export declare const asBlob: (part: InlineDataCapabilityPart | StoredDataCapabilityPart | Chunk) => Promise<Blob>;
+export declare const isChunk: (value: unknown) => value is Chunk;
+export declare const isInlineData: (value: unknown) => value is InlineDataCapabilityPart;
+declare function isCodeExecutionResultPart(value: unknown): value is CodeExecutionResultPart;
+declare function isExecutableCodePart(value: unknown): value is ExecutableCodePart;
+export declare const isSerializedData: (value: unknown) => value is InlineDataCapabilityPart;
+export declare function asBase64(file: File | Blob): Promise<string>;
+export declare function asBase64DataUrl(blob: Blob): Promise<string>;
+export declare function retrieveAsBlob(part: StoredDataCapabilityPart, graphUrl?: URL): Promise<Blob>;
+export declare function toInlineDataPart(part: StoredDataCapabilityPart, graphUrl?: URL): Promise<InlineDataCapabilityPart>;
+export declare function toStoredDataPart(part: InlineDataCapabilityPart | StoredDataCapabilityPart | Blob): Promise<StoredDataCapabilityPart>;
+export declare function transformDataParts(graphUrl: URL, contents: LLMContent[], to: DataPartTransformType, transformer: DataPartTransformer): Promise<Outcome<LLMContent[]>>;
+export declare function convertStoredPartsToAbsoluteUrls(values: OutputValues | undefined, graphUrl?: string): OutputValues;

package/dist/breadboard/engine/loader/capability.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { GraphLoaderResult, NodeHandlerContext, NodeValue, OutputValues } from "@breadboard-ai/types";
+import { BreadboardCapability, GraphDescriptorBoardCapability, ResolvedURLBoardCapability, UnresolvedPathBoardCapability } from "@breadboard-ai/types/legacy.js";
+export declare const isBreadboardCapability: (o: unknown) => o is BreadboardCapability;
+export declare const isGraphDescriptorCapability: (capability: BreadboardCapability) => capability is GraphDescriptorBoardCapability;
+export declare const isResolvedURLBoardCapability: (capability: BreadboardCapability) => capability is ResolvedURLBoardCapability;
+export declare const isUnresolvedPathBoardCapability: (capability: BreadboardCapability) => capability is UnresolvedPathBoardCapability;
+export declare const graphDescriptorFromCapability: (capability: BreadboardCapability, context?: NodeHandlerContext) => Promise<GraphLoaderResult>;
+export declare const getGraphDescriptor: (board: unknown, context?: NodeHandlerContext) => Promise<GraphLoaderResult>;
+/**
+ * Resolves any BreadboardCapability instances that are
+ * `UnresolvedPathBoardCapability` to `ResolvedURLBoardCapability`.
+ * This must happen at run-time, at the earliest moment when
+ * the inputs are received by the BoardRunner.
+ */
+export declare const resolveBoardCapabilities: (outputs: OutputValues, context: NodeHandlerContext, url?: string) => Promise<OutputValues>;
+export declare const resolveBoardCapabilitiesInInputs: (values: Record<string, NodeValue>, context: NodeHandlerContext, url?: string) => Record<string, NodeValue>;

package/dist/breadboard/engine/loader/loader.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { GraphDescriptor, GraphLoader, GraphLoaderContext, GraphLoaderResult, GraphProvider, GraphToRun } from "@breadboard-ai/types";
+export declare const SENTINEL_BASE_URL: URL;
+export { getGraphUrl, getGraphUrlComponents, resolveGraph, urlComponentsFromString, };
+declare function getGraphUrl(path: string, context: GraphLoaderContext): URL;
+declare function getGraphUrlComponents(url: URL): {
+    mainGraphUrl: string;
+    graphId: string;
+    moduleId?: string;
+};
+declare function resolveGraph(graphToRun: GraphToRun): GraphDescriptor;
+export declare const removeHash: (url: URL) => URL;
+export declare const sameWithoutHash: (a: URL, b: URL) => boolean;
+export declare const baseURLFromString: (urlString: string | undefined) => URL | null;
+export declare const baseURLFromContext: (context: GraphLoaderContext) => URL;
+declare function urlComponentsFromString(urlString: string, context?: GraphLoaderContext): {
+    mainGraphUrl: string;
+    graphId: string;
+    moduleId?: string;
+};
+export declare class Loader implements GraphLoader {
+    #private;
+    constructor(graphProviders: GraphProvider[]);
+    load(path: string, context: GraphLoaderContext): Promise<GraphLoaderResult>;
+}

package/dist/breadboard/engine/loader/resolve-graph-urls.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { GraphToRun } from "@breadboard-ai/types";
+export { resolveGraphUrls };
+/**
+ * Walks over the GraphDescriptor specified in GraphToRun and resolves all
+ * relative URLs in the GraphDescriptor to be absolute. Returns a new
+ * instance of a GraphToRun and a new instance of the GraphDescriptor.
+ *
+ * @param graphToRun an instance of GraphToRun
+ * @returns a new instance of GraphToRun
+ */
+declare function resolveGraphUrls(graphToRun: GraphToRun): GraphToRun;

package/dist/breadboard/engine/runtime/bubble.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { GraphInlineMetadata, InputValues, NodeDescriptor, NodeHandlerContext, OutputValues, RunArguments, Schema, TraversalResult } from "@breadboard-ai/types";
+import { RunResult } from "./run.js";
+export declare const createErrorMessage: (inputName: string | string[], metadata: GraphInlineMetadata | undefined, required: boolean) => string;
+export declare const bubbleUpInputsIfNeeded: (metadata: GraphInlineMetadata, context: NodeHandlerContext, descriptor: NodeDescriptor, result: TraversalResult, path: number[]) => Promise<void>;
+export declare const createBubbleHandler: (metadata: GraphInlineMetadata, context: NodeHandlerContext, descriptor: NodeDescriptor) => (propertiesSchema: Schema, path: number[]) => Promise<OutputValues>;
+export type InputSchemaHandler = (schema: Schema, path: number[]) => Promise<OutputValues>;
+export declare class InputSchemaReader {
+    #private;
+    constructor(currentOutputs: OutputValues, inputs: InputValues, path: number[]);
+    read(handler: InputSchemaHandler): Promise<OutputValues>;
+}
+export declare class RequestedInputsManager {
+    #private;
+    constructor(args: RunArguments);
+    createHandler(next: (result: RunResult) => Promise<void>, result: TraversalResult): NodeHandlerContext["requestInput"];
+}
+export declare const bubbleUpOutputsIfNeeded: (outputs: OutputValues, descriptor: NodeDescriptor, context: NodeHandlerContext, path: number[]) => Promise<boolean>;
+export declare const createOutputProvider: (next: (result: RunResult) => Promise<void>, result: TraversalResult, context: NodeHandlerContext) => (outputs: OutputValues, descriptor: NodeDescriptor, path: number[]) => Promise<void>;

package/dist/breadboard/engine/runtime/graph-based-node-handler.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { GraphToRun, InputValues, NodeDescriberContext, NodeDescriberResult, NodeHandlerContext, NodeHandlerMetadata, NodeHandlerObject, NodeTypeIdentifier, Schema } from "@breadboard-ai/types";
+export { describerResultToNodeHandlerMetadata, GraphBasedNodeHandler, toNodeHandlerMetadata, };
+declare class GraphBasedNodeHandler implements NodeHandlerObject {
+    #private;
+    constructor(graph: GraphToRun, type: NodeTypeIdentifier);
+    invoke(inputs: InputValues, context: NodeHandlerContext): Promise<import("@breadboard-ai/types").OutputValues>;
+    describe(inputs?: InputValues, inputSchema?: Schema, outputSchema?: Schema, context?: NodeDescriberContext): Promise<NodeDescriberResult>;
+    get metadata(): NodeHandlerMetadata | undefined;
+}
+declare function describerResultToNodeHandlerMetadata(result: NodeDescriberResult, updating: boolean): NodeHandlerMetadata;
+declare function toNodeHandlerMetadata(graphToRun: GraphToRun, url: NodeTypeIdentifier, updating: boolean): NodeHandlerMetadata | undefined;

package/dist/breadboard/engine/runtime/handler.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { InputValues, Kit, MutableGraph, NodeHandler, NodeHandlerContext, NodeHandlerObject, NodeHandlers, NodeTypeIdentifier, OutputValues } from "@breadboard-ai/types";
+export declare const callHandler: (handler: NodeHandler, inputs: InputValues, context: NodeHandlerContext) => Promise<OutputValues | void>;
+export declare const handlersFromKits: (kits: Kit[]) => NodeHandlers;
+/**
+ * The single entry point for getting a handler for a node type.
+ * The handler can be one of the two types:
+ * - A graph-based handler, where the `type` is actually a
+ *   URL-like string that points to a graph.
+ * - A kit-based handler, where the `type` is a string that
+ *   corresponds to a node type in a kit.
+ *
+ * The function throws an error if no handler is found for the
+ * given node type.
+ *
+ * @param type    -- The node type to get a handler for.
+ * @param context -- The context in which the handler is
+ *                   being requested.
+ * @returns       -- The handler for the node type.
+ */
+export declare function getHandler(type: NodeTypeIdentifier, context: NodeHandlerContext): Promise<NodeHandler>;
+export declare function getGraphHandlerFromMutableGraph(type: NodeTypeIdentifier, mutable: MutableGraph): Promise<NodeHandlerObject | undefined>;
+export declare function getGraphHandler(type: NodeTypeIdentifier, context: NodeHandlerContext, allow3PModules?: boolean): Promise<NodeHandlerObject | undefined>;

package/dist/breadboard/engine/runtime/harness/events.d.ts

@@ -0,0 +1,145 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Edge, EdgeLifecycleState, End, ErrorResponse, GraphEndProbeData, GraphStartProbeData, HarnessRunResult, InputResponse, InputValues, NodeEndResponse, NodeIdentifier, NodeLifecycleState, NodeStartResponse, NodeValue, OutputResponse, RunEdgeStateChangeEvent, RunEndEvent, RunErrorEvent, RunGraphEndEvent, RunGraphStartEvent, RunInputEvent, RunLifecycleEvent, RunNextEvent, RunNodeEndEvent, RunNodeStartEvent, RunNodeStateChangeEvent, RunOutputEvent, RunSkipEvent, SkipProbeMessage, TraversalResult } from "@breadboard-ai/types";
+export declare class PendingEvent extends Event {
+    data: {
+        timestamp: number;
+    };
+    static readonly eventName = "pending";
+    constructor(data: {
+        timestamp: number;
+    });
+}
+export declare class InputEvent extends Event implements RunInputEvent {
+    readonly running: boolean;
+    data: InputResponse;
+    static readonly eventName = "input";
+    constructor(running: boolean, data: InputResponse);
+}
+export declare class OutputEvent extends Event implements RunOutputEvent {
+    data: OutputResponse;
+    static readonly eventName = "output";
+    readonly running = true;
+    constructor(data: OutputResponse);
+}
+export declare class RunnerErrorEvent extends Event implements RunErrorEvent {
+    data: ErrorResponse;
+    static readonly eventName = "error";
+    readonly running = false;
+    constructor(data: ErrorResponse);
+}
+export declare class EndEvent extends Event implements RunEndEvent {
+    data: End;
+    static readonly eventName = "end";
+    readonly running = false;
+    constructor(data: End);
+}
+export declare class SkipEvent extends Event implements RunSkipEvent {
+    data: SkipProbeMessage["data"];
+    static readonly eventName = "skip";
+    readonly running = true;
+    constructor(data: SkipProbeMessage["data"]);
+}
+export declare class GraphStartEvent extends Event implements RunGraphStartEvent {
+    data: GraphStartProbeData;
+    static readonly eventName = "graphstart";
+    readonly running = true;
+    constructor(data: GraphStartProbeData);
+}
+export declare class GraphEndEvent extends Event implements RunGraphEndEvent {
+    data: GraphEndProbeData;
+    static readonly eventName = "graphend";
+    readonly running = true;
+    constructor(data: GraphEndProbeData);
+}
+export declare class NodeStartEvent extends Event implements RunNodeStartEvent {
+    data: NodeStartResponse;
+    result?: TraversalResult | undefined;
+    static readonly eventName = "nodestart";
+    readonly running = true;
+    constructor(data: NodeStartResponse, result?: TraversalResult | undefined);
+}
+export declare class NodeEndEvent extends Event implements RunNodeEndEvent {
+    data: NodeEndResponse;
+    static readonly eventName = "nodeend";
+    readonly running = true;
+    constructor(data: NodeEndResponse);
+}
+export declare class PauseEvent extends Event implements RunLifecycleEvent {
+    running: boolean;
+    data: {
+        timestamp: number;
+    };
+    static readonly eventName = "pause";
+    constructor(running: boolean, data: {
+        timestamp: number;
+    });
+}
+export declare class ResumeEvent extends Event implements RunLifecycleEvent {
+    data: {
+        timestamp: number;
+        inputs?: InputValues;
+    };
+    static readonly eventName = "resume";
+    readonly running = true;
+    constructor(data: {
+        timestamp: number;
+        inputs?: InputValues;
+    });
+}
+export declare class StartEvent extends Event implements RunLifecycleEvent {
+    data: {
+        timestamp: number;
+        inputs?: InputValues;
+    };
+    static readonly eventName = "start";
+    readonly running = true;
+    constructor(data: {
+        timestamp: number;
+        inputs?: InputValues;
+    });
+}
+export declare class StopEvent extends Event implements RunLifecycleEvent {
+    running: boolean;
+    data: {
+        timestamp: number;
+    };
+    static readonly eventName = "stop";
+    constructor(running: boolean, data: {
+        timestamp: number;
+    });
+}
+export declare class NextEvent extends Event implements RunNextEvent {
+    data: HarnessRunResult | void;
+    static readonly eventName = "next";
+    constructor(data: HarnessRunResult | void);
+}
+export declare class NodeStateChangeEvent extends Event implements RunNodeStateChangeEvent {
+    data: {
+        id: NodeIdentifier;
+        state: NodeLifecycleState;
+        message: NodeValue;
+    };
+    static readonly eventName = "nodestatechange";
+    readonly running = true;
+    constructor(data: {
+        id: NodeIdentifier;
+        state: NodeLifecycleState;
+        message: NodeValue;
+    });
+}
+export declare class EdgeStateChangeEvent extends Event implements RunEdgeStateChangeEvent {
+    data: {
+        edges: Edge[];
+        state: EdgeLifecycleState;
+    };
+    static readonly eventName = "edgestatechange";
+    readonly running = true;
+    constructor(data: {
+        edges: Edge[];
+        state: EdgeLifecycleState;
+    });
+}

package/dist/breadboard/engine/runtime/harness/local.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { ProbeMessage } from "@breadboard-ai/types";
+import { BreadboardRunResult, HarnessRunResult } from "@breadboard-ai/types";
+export { fromRunnerResult, fromProbe };
+declare function fromProbe<Probe extends ProbeMessage>(probe: Probe): HarnessRunResult;
+declare function fromRunnerResult<Result extends BreadboardRunResult>(result: Result): HarnessRunResult;

package/dist/breadboard/engine/runtime/harness/plan-runner.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { GraphDescriptor, HarnessRunner, HarnessRunResult, InputValues, NodeIdentifier, OrchestratorState, Outcome, RunConfig, RunEventTarget } from "@breadboard-ai/types";
+import { SignalMap } from "signal-utils/map";
+export { PlanRunner };
+declare const PlanRunner_base: RunEventTarget;
+declare class PlanRunner extends PlanRunner_base implements HarnessRunner {
+    #private;
+    readonly config: RunConfig;
+    running(): boolean;
+    run(inputs?: InputValues, interactiveMode?: boolean): Promise<boolean>;
+    get state(): OrchestratorState;
+    get plan(): OrchestrationPlan;
+    get waiting(): Map<any, any>;
+    accessor breakpoints: SignalMap<string, BreakpointSpec>;
+    constructor(config: RunConfig);
+    runNode(id: NodeIdentifier): Promise<Outcome<void>>;
+    runFrom(id: NodeIdentifier): Promise<Outcome<void>>;
+    stop(id: NodeIdentifier): Promise<Outcome<void>>;
+    protected getGenerator(interactiveMode?: boolean): AsyncGenerator<HarnessRunResult, void, unknown>;
+    updateGraph(graph: GraphDescriptor): Promise<void>;
+}

package/dist/breadboard/engine/runtime/run/invoke-graph.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { GraphToRun, InputValues, OutputValues, RunArguments, TraversalResult } from "@breadboard-ai/types";
+/**
+ * Runs a graph in "run as component" mode. See
+ * https://breadboard-ai.github.io/breadboard/docs/reference/runtime-semantics/#run-as-component-mode
+ * for more details.
+ */
+export declare function invokeGraph(graphToRun: GraphToRun, inputs: InputValues, context?: RunArguments, resumeFrom?: TraversalResult): Promise<OutputValues>;

package/dist/breadboard/engine/runtime/run/node-invoker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { GraphToRun, OutputValues, RunArguments, TraversalResult } from "@breadboard-ai/types";
+import { RunResult } from "../run.js";
+export declare class NodeInvoker {
+    #private;
+    constructor(args: RunArguments, graph: GraphToRun, next: (result: RunResult) => Promise<void>);
+    invokeNode(result: TraversalResult, invocationPath: number[]): Promise<OutputValues>;
+}

package/dist/breadboard/engine/runtime/run/run-graph.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2024 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BreadboardRunResult, GraphToRun, RunArguments, TraversalResult } from "@breadboard-ai/types";
+/**
+ * Runs a graph in "run" mode. See
+ * https://breadboard-ai.github.io/breadboard/docs/reference/runtime-semantics/#run-mode
+ * for more details.
+ */
+export declare function runGraph(graphToRun: GraphToRun, args?: RunArguments, resumeFrom?: TraversalResult): AsyncGenerator<BreadboardRunResult>;

package/dist/breadboard/engine/runtime/run.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { BreadboardRunResult, InputValues, NodeDescriptor, OutputValues, RunResultType, TraversalResult } from "@breadboard-ai/types";
+export declare class RunResult implements BreadboardRunResult {
+    #private;
+    constructor(state: TraversalResult, type: RunResultType, invocationId: number, path: number[]);
+    get invocationId(): number;
+    get path(): number[];
+    get type(): RunResultType;
+    get node(): NodeDescriptor;
+    get inputArguments(): InputValues;
+    set inputs(inputs: InputValues);
+    get outputs(): OutputValues;
+    get state(): TraversalResult;
+    get timestamp(): number;
+    isAtExitNode(): boolean;
+}
+export declare class InputStageResult extends RunResult {
+    constructor(state: TraversalResult, invocationId: number, path: number[]);
+    get outputs(): OutputValues;
+}
+export declare class OutputStageResult extends RunResult {
+    constructor(state: TraversalResult, invocationId: number, path: number[]);
+    get inputArguments(): InputValues;
+    set inputs(_inputs: InputValues);
+}

package/dist/breadboard/engine/runtime/sandbox/capabilities-manager.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { NodeHandlerContext } from "@breadboard-ai/types";
+import { CapabilitiesManager, CapabilitySpec } from "@breadboard-ai/types/sandbox.js";
+export { CapabilitiesManagerImpl };
+declare class CapabilitiesManagerImpl implements CapabilitiesManager {
+    #private;
+    readonly context?: NodeHandlerContext | undefined;
+    constructor(context?: NodeHandlerContext | undefined);
+    createSpec(): CapabilitySpec;
+    static dummies(): CapabilitySpec;
+}

package/dist/breadboard/engine/runtime/sandbox/file-system-handler-factory.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Capability } from "@breadboard-ai/types/sandbox.js";
+import { FileSystem } from "@breadboard-ai/types";
+export { FileSystemHandlerFactory };
+declare class FileSystemHandlerFactory {
+    readonly fs?: FileSystem | undefined;
+    constructor(fs?: FileSystem | undefined);
+    query(): Capability;
+    read(): Capability;
+    write(): Capability;
+}

package/dist/breadboard/engine/runtime/sandbox/invoke-describer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { GraphDescriptor, InputValues, ModuleIdentifier, MutableGraph, NodeDescriberResult, NodeHandlerContext, Schema } from "@breadboard-ai/types";
+import { CapabilitiesManager } from "@breadboard-ai/types/sandbox.js";
+export { invokeDescriber, invokeMainDescriber };
+declare function invokeDescriber(context: NodeHandlerContext, moduleId: ModuleIdentifier, mutable: MutableGraph, graph: GraphDescriptor, inputs: InputValues, inputSchema?: Schema, outputSchema?: Schema, capabilities?: CapabilitiesManager, asType?: boolean): Promise<NodeDescriberResult | undefined>;
+declare function invokeMainDescriber(context: NodeHandlerContext, mutable: MutableGraph, graph: GraphDescriptor, inputs: InputValues, inputSchema?: Schema, outputSchema?: Schema, capabilities?: CapabilitiesManager, asType?: boolean): Promise<NodeDescriberResult | undefined | false>;

package/dist/breadboard/engine/runtime/static/create-plan.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { GraphDescriptor, OrchestrationPlan } from "@breadboard-ai/types";
+export { createPlan };
+/**
+ * Creates an execution plan from the provided GraphDescription.
+ * The graph is guaranteed to be condensed (no cycles), and each
+ * strongly connected component is represented with a single node
+ * that has a "folded" tag.
+ */
+declare function createPlan(graph: GraphDescriptor): OrchestrationPlan;

package/dist/breadboard/engine/runtime/static/orchestrator.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { NodeIdentifier, Outcome, OutputValues, OrchestrationPlan, OrchestratorProgress, Task, OrchestrationNodeInfo, OrchestratorState, OrchestratorCallbacks, OrchestratorNodeState } from "@breadboard-ai/types";
+export { Orchestrator };
+/**
+ * The Orchestrator acts as the state machine for running a graph.
+ * Its primary responsibilities are:
+ *
+ * 1.  Lifecycle Management: Starting, resetting, and managing the overall
+ * progress of a run from beginning to end.
+ * 2.  Task Coordination: Determining which nodes are ready to be invoked
+ * based on dependencies.
+ * 3.  State Persistence: Receiving results of node invocation and persisting
+ * the state workflow.
+ * 4.  Inspection and Debugging: Providing methods to observe the current state
+ * of a run, inspect cached results, and control execution flow.
+ *
+ * It breaks down the process into three distinct parts:
+ * - the planning -- determining the static sequence of a run
+ * - the orchestration -- managing execution results that can be dynamic
+ * - actual node invocation
+ */
+declare class Orchestrator {
+    #private;
+    readonly plan: OrchestrationPlan;
+    readonly callbacks: OrchestratorCallbacks;
+    constructor(plan: OrchestrationPlan, callbacks: OrchestratorCallbacks);
+    /**
+     * Returns current progress of the orchestration.
+     */
+    get progress(): OrchestratorProgress;
+    get working(): boolean;
+    get allWorking(): unknown[];
+    get allWaiting(): unknown[];
+    get failed(): boolean;
+    getNodeState(id: NodeIdentifier): OrchestratorNodeState | null;
+    /**
+     * Bring the orchestrator to the initial state.
+     */
+    reset(): Outcome<void>;
+    restartAtCurrentStage(): Outcome<void>;
+    restartAtStage(stage: number): Outcome<void>;
+    restartAtNode(id: NodeIdentifier): Outcome<void>;
+    setWorking(id: NodeIdentifier): Outcome<void>;
+    setWaiting(id: NodeIdentifier): Outcome<void>;
+    setInterrupted(id: NodeIdentifier): Outcome<void>;
+    fullState(): OrchestratorState;
+    /**
+     * Provides a way to inspect the current state of nodes as they are being
+     * orchestrated.
+     * @returns a map representing current state of all nodes
+     */
+    state(): ReadonlyMap<NodeIdentifier, OrchestrationNodeInfo>;
+    /**
+     * Creates a new task to invoke a node, given a node id
+     * @param id -- node id
+     */
+    taskFromId(id: NodeIdentifier): Outcome<Task>;
+    /**
+     * Creates a list of current tasks: nodes to be invoked next, along
+     * with their inputs, according to the current state of the orchestrator.
+     */
+    currentTasks(): Outcome<Task[]>;
+    update(old: Orchestrator): void;
+    /**
+     * Submit results of a node invocation. Also updates the current state.
+     */
+    provideOutputs(id: NodeIdentifier, outputs: OutputValues): Outcome<OrchestratorProgress>;
+}

package/dist/breadboard/engine/runtime/traversal/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Edge, InputValues, NodeDescriptor, NodeIdentifier } from "@breadboard-ai/types";
+/**
+ * This class holds important parts of the graph traversal algorithm.
+ */
+export declare class Traversal {
+    /**
+     * Computes the missing inputs for a node. A missing input is an input that is
+     * required by the node, but is not (yet) available in the current state.
+     * @param heads All the edges that point to the node.
+     * @param inputs The input values that will be passed to the node
+     * @param current The node that is being visited.
+     * @returns Array of missing input names.
+     */
+    static computeMissingInputs(heads: Edge[], inputs: InputValues, current: NodeDescriptor, start?: NodeIdentifier): string[];
+}

package/dist/breadboard/engine/runtime/traversal/iterator.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2023 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { GraphRepresentation, TraversalResult } from "@breadboard-ai/types";
+export declare class TraversalMachineIterator implements AsyncIterator<TraversalResult> {
+    #private;
+    graph: GraphRepresentation;
+    constructor(graph: GraphRepresentation, result: TraversalResult);
+    next(): Promise<IteratorResult<TraversalResult>>;
+}