agentflow-core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,370 @@
+/**
+ * Core type definitions for AgentFlow execution graphs.
+ *
+ * All public interfaces use `readonly` at every level.
+ * String literal unions are used instead of enums for clean ESM erasure.
+ * @module
+ */
+/** The kind of step an execution node represents. */
+type NodeType = 'agent' | 'tool' | 'subagent' | 'wait' | 'decision' | 'custom';
+/** Lifecycle status of an execution node. */
+type NodeStatus = 'running' | 'completed' | 'failed' | 'hung' | 'timeout';
+/** Relationship type between two nodes in the execution graph. */
+type EdgeType = 'spawned' | 'waited_on' | 'called' | 'retried' | 'branched';
+/** Aggregate status of the entire execution graph. */
+type GraphStatus = 'running' | 'completed' | 'failed';
+/**
+ * Event types emitted during execution.
+ * These map to framework-level lifecycle events for adapter compatibility.
+ */
+type TraceEventType = 'agent_start' | 'agent_end' | 'tool_start' | 'tool_end' | 'tool_error' | 'subagent_spawn' | 'decision' | 'timeout' | 'custom';
+/** A single step in the execution graph. */
+interface ExecutionNode {
+    readonly id: string;
+    readonly type: NodeType;
+    readonly name: string;
+    /** Epoch milliseconds (Date.now()). */
+    readonly startTime: number;
+    /** Epoch milliseconds. `null` while the node is still running. */
+    readonly endTime: number | null;
+    readonly status: NodeStatus;
+    /** `null` for the root node. */
+    readonly parentId: string | null;
+    /** IDs of child nodes spawned by this node. */
+    readonly children: readonly string[];
+    /** Arbitrary key-value data attached to this node. */
+    readonly metadata: Readonly<Record<string, unknown>>;
+    /** Mutable-at-build-time state snapshot for this node. */
+    readonly state: Readonly<Record<string, unknown>>;
+}
+/** A directed relationship between two execution nodes. */
+interface ExecutionEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly type: EdgeType;
+}
+/** A raw event recorded during execution, before graph construction. */
+interface TraceEvent {
+    readonly timestamp: number;
+    readonly eventType: TraceEventType;
+    readonly nodeId: string;
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/** The complete execution graph for one agent run. */
+interface ExecutionGraph {
+    readonly id: string;
+    readonly rootNodeId: string;
+    /** All nodes indexed by ID. */
+    readonly nodes: ReadonlyMap<string, ExecutionNode>;
+    readonly edges: readonly ExecutionEdge[];
+    readonly startTime: number;
+    /** `null` if the graph is still running. */
+    readonly endTime: number | null;
+    readonly status: GraphStatus;
+    readonly trigger: string;
+    readonly agentId: string;
+    /** Full ordered event log for auditability. */
+    readonly events: readonly TraceEvent[];
+}
+/**
+ * Configuration for AgentFlow.
+ *
+ * @example
+ * ```ts
+ * const builder = createGraphBuilder({
+ *   agentId: 'portfolio-recon',
+ *   trigger: 'user-request',
+ * });
+ * ```
+ */
+interface AgentFlowConfig {
+    /** Identifier for the agent whose execution is being traced. */
+    readonly agentId?: string;
+    /** What initiated this execution (e.g. "user-request", "cron-job"). */
+    readonly trigger?: string;
+    /** Display name for the execution graph. */
+    readonly name?: string;
+    /** Output writer for completed graphs. */
+    readonly writer?: Writer;
+    /** Framework adapters to install. */
+    readonly adapters?: readonly Adapter[];
+    /** Override the default counter-based ID generator. */
+    readonly idGenerator?: () => string;
+    /** Timeout configuration in milliseconds. */
+    readonly timeout?: {
+        readonly default?: number;
+        readonly tool?: number;
+        readonly agent?: number;
+    };
+    /** Custom logger (defaults to console.warn). */
+    readonly logger?: (message: string) => void;
+    /** Error callback for internal failures. */
+    readonly onError?: (error: unknown) => void;
+}
+/**
+ * Output adapter interface. Writers receive the completed execution graph
+ * and persist it to their target (console, file, etc.).
+ *
+ * @example
+ * ```ts
+ * const myWriter: Writer = {
+ *   write: async (graph) => { console.log(graph.id); },
+ * };
+ * ```
+ */
+interface Writer {
+    /** Write the execution graph to the output target. */
+    write(graph: ExecutionGraph): Promise<void>;
+}
+/**
+ * Framework adapter interface. Adapters hook into agent runtime lifecycle
+ * events and translate them into graph builder calls.
+ *
+ * @example
+ * ```ts
+ * const myAdapter: Adapter = {
+ *   name: 'my-framework',
+ *   attach: (builder) => { /* hook into runtime *\/ },
+ *   detach: () => { /* unhook *\/ },
+ * };
+ * ```
+ */
+interface Adapter {
+    /** Human-readable adapter name. */
+    readonly name: string;
+    /** Hook into the framework's lifecycle, calling builder methods on events. */
+    attach(builder: GraphBuilder): void;
+    /** Unhook from the framework (cleanup). */
+    detach(): void;
+}
+/** Options for starting a new execution node. */
+interface StartNodeOptions {
+    readonly type: NodeType;
+    readonly name: string;
+    /** Explicit parent node ID. If omitted, uses the `withParent` stack context. */
+    readonly parentId?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Mutable graph builder returned by `createGraphBuilder`.
+ *
+ * @example
+ * ```ts
+ * const builder = createGraphBuilder({ agentId: 'main' });
+ * const rootId = builder.startNode({ type: 'agent', name: 'main' });
+ * const toolId = builder.startNode({ type: 'tool', name: 'search', parentId: rootId });
+ * builder.endNode(toolId);
+ * builder.endNode(rootId);
+ * const graph = builder.build();
+ * ```
+ */
+interface GraphBuilder {
+    /** The graph's ID, available before `build()`. */
+    readonly graphId: string;
+    /** Start a new execution node. Returns the generated node ID. */
+    startNode(opts: StartNodeOptions): string;
+    /** End a node. Status defaults to `'completed'`. */
+    endNode(nodeId: string, status?: NodeStatus): void;
+    /** Mark a node as failed with an error. */
+    failNode(nodeId: string, error: Error | string): void;
+    /** Add an explicit edge between two nodes. */
+    addEdge(from: string, to: string, type: EdgeType): void;
+    /**
+     * Record a trace event. Timestamp is added automatically.
+     *
+     * @example
+     * ```ts
+     * builder.pushEvent({ eventType: 'custom', nodeId: rootId, data: { key: 'value' } });
+     * ```
+     */
+    pushEvent(event: Omit<TraceEvent, 'timestamp'>): void;
+    /** Shallow-merge state into a node's state object. */
+    updateState(nodeId: string, state: Record<string, unknown>): void;
+    /**
+     * Execute `fn` with an implicit parent context.
+     * Any `startNode` calls inside `fn` that omit `parentId`
+     * will automatically use `parentId` as their parent.
+     */
+    withParent<T>(parentId: string, fn: () => T): T;
+    /**
+     * Return a frozen snapshot of the current graph state without finalising.
+     * The builder remains usable after calling this.
+     */
+    getSnapshot(): ExecutionGraph;
+    /** Freeze and return the completed execution graph. Throws if no root node exists. */
+    build(): ExecutionGraph;
+}
+/** Aggregate statistics for an execution graph. */
+interface GraphStats {
+    readonly totalNodes: number;
+    readonly byStatus: Readonly<Record<NodeStatus, number>>;
+    readonly byType: Readonly<Record<NodeType, number>>;
+    readonly depth: number;
+    readonly duration: number;
+    readonly failureCount: number;
+    readonly hungCount: number;
+}
+/** @internal Mutable version of ExecutionNode used during graph construction. */
+interface MutableExecutionNode {
+    id: string;
+    type: NodeType;
+    name: string;
+    startTime: number;
+    endTime: number | null;
+    status: NodeStatus;
+    parentId: string | null;
+    children: string[];
+    metadata: Record<string, unknown>;
+    state: Record<string, unknown>;
+}
+
+/**
+ * Closure-based factory for constructing execution graphs.
+ *
+ * Zero dependencies. Counter-based IDs by default, injectable for testing.
+ *
+ * @example
+ * ```ts
+ * const builder = createGraphBuilder({ agentId: 'main', trigger: 'user-request' });
+ * const rootId = builder.startNode({ type: 'agent', name: 'main' });
+ * const toolId = builder.startNode({ type: 'tool', name: 'search', parentId: rootId });
+ * builder.endNode(toolId);
+ * builder.endNode(rootId);
+ * const graph = builder.build();
+ * ```
+ * @module
+ */
+
+/**
+ * Create a new execution graph builder.
+ *
+ * @param config - Optional configuration (agentId, trigger, custom ID generator, etc.).
+ * @returns A `GraphBuilder` with methods to construct the graph incrementally.
+ *
+ * @example
+ * ```ts
+ * const builder = createGraphBuilder({ agentId: 'portfolio-recon', trigger: 'cron' });
+ * const rootId = builder.startNode({ type: 'agent', name: 'recon' });
+ * builder.endNode(rootId);
+ * const graph = builder.build();
+ * ```
+ */
+declare function createGraphBuilder(config?: AgentFlowConfig): GraphBuilder;
+
+/**
+ * Pure query functions for interrogating a built `ExecutionGraph`.
+ * Every function takes a frozen graph and returns derived data without mutation.
+ * @module
+ */
+
+/**
+ * Find a node by its ID.
+ *
+ * @param graph - The execution graph to search.
+ * @param nodeId - The node ID to look up.
+ * @returns The node, or `undefined` if not found.
+ *
+ * @example
+ * ```ts
+ * const node = getNode(graph, 'node_002');
+ * if (node) console.log(node.name);
+ * ```
+ */
+declare function getNode(graph: ExecutionGraph, nodeId: string): ExecutionNode | undefined;
+/**
+ * Get the direct children of a node.
+ *
+ * @param graph - The execution graph to search.
+ * @param nodeId - The parent node ID.
+ * @returns Array of child nodes (may be empty).
+ *
+ * @example
+ * ```ts
+ * const children = getChildren(graph, rootId);
+ * ```
+ */
+declare function getChildren(graph: ExecutionGraph, nodeId: string): ExecutionNode[];
+/**
+ * Get the parent of a node.
+ *
+ * @param graph - The execution graph to search.
+ * @param nodeId - The child node ID.
+ * @returns The parent node, or `undefined` if root or not found.
+ *
+ * @example
+ * ```ts
+ * const parent = getParent(graph, toolId);
+ * ```
+ */
+declare function getParent(graph: ExecutionGraph, nodeId: string): ExecutionNode | undefined;
+/**
+ * Find all nodes with a failure-category status: `failed`, `hung`, or `timeout`.
+ *
+ * @param graph - The execution graph to search.
+ * @returns Array of nodes with failure statuses (may be empty).
+ */
+declare function getFailures(graph: ExecutionGraph): ExecutionNode[];
+/**
+ * Find all nodes that are still running (status `'running'`, no endTime).
+ *
+ * @param graph - The execution graph to search.
+ * @returns Array of running/hung nodes.
+ */
+declare function getHungNodes(graph: ExecutionGraph): ExecutionNode[];
+/**
+ * Find the critical path: the longest-duration path from the root to any leaf node.
+ * Uses node duration (endTime - startTime) as the weight.
+ * Running nodes use `Date.now()` as a provisional endTime.
+ *
+ * @param graph - The execution graph to analyse.
+ * @returns Nodes ordered from root to the deepest leaf on the longest path.
+ */
+declare function getCriticalPath(graph: ExecutionGraph): ExecutionNode[];
+/**
+ * Find what a node is waiting on.
+ * Returns nodes connected via `waited_on` edges where the given nodeId is the `from` side.
+ *
+ * @param graph - The execution graph to search.
+ * @param nodeId - The node that is doing the waiting.
+ * @returns Array of nodes that are being waited on.
+ */
+declare function findWaitingOn(graph: ExecutionGraph, nodeId: string): ExecutionNode[];
+/**
+ * Get all descendants of a node (children, grandchildren, etc.) in breadth-first order.
+ * The given node itself is NOT included.
+ *
+ * @param graph - The execution graph to search.
+ * @param nodeId - The ancestor node ID.
+ * @returns All descendant nodes in BFS order.
+ */
+declare function getSubtree(graph: ExecutionGraph, nodeId: string): ExecutionNode[];
+/**
+ * Total wall-clock duration of the graph in milliseconds.
+ * If the graph is still running, uses `Date.now()` as the provisional end.
+ *
+ * @param graph - The execution graph.
+ * @returns Duration in milliseconds.
+ */
+declare function getDuration(graph: ExecutionGraph): number;
+/**
+ * Maximum nesting depth of the graph. The root node is depth 0.
+ *
+ * @param graph - The execution graph.
+ * @returns The maximum depth (0 for a single-node graph, -1 for empty).
+ */
+declare function getDepth(graph: ExecutionGraph): number;
+/**
+ * Compute aggregate statistics for the execution graph.
+ *
+ * @param graph - The execution graph to analyse.
+ * @returns Statistics including node counts by type and status, depth, duration, and failure counts.
+ *
+ * @example
+ * ```ts
+ * const stats = getStats(graph);
+ * console.log(`${stats.totalNodes} nodes, ${stats.failureCount} failures`);
+ * ```
+ */
+declare function getStats(graph: ExecutionGraph): GraphStats;
+
+export { type Adapter, type AgentFlowConfig, type EdgeType, type ExecutionEdge, type ExecutionGraph, type ExecutionNode, type GraphBuilder, type GraphStats, type GraphStatus, type MutableExecutionNode, type NodeStatus, type NodeType, type StartNodeOptions, type TraceEvent, type TraceEventType, type Writer, createGraphBuilder, findWaitingOn, getChildren, getCriticalPath, getDepth, getDuration, getFailures, getHungNodes, getNode, getParent, getStats, getSubtree };