@exellix/graph-engine 6.0.0

package/dist/src/runtime/ExellixGraphRuntime.d.ts

@@ -0,0 +1,263 @@
+import type { GraphEngineFactory } from "./GraphEngine.js";
+import type { ExecutionStep } from "@exellix/ai-tasks";
+import type { Graph, GraphModelObject, GraphNode, GraphAiModelConfig, GraphModelAliasConfig, TaskNodeRuntimeObject } from "../types/refs.js";
+import type { RunLogEntry } from "../types/runLog.js";
+import type { RunTaskDiagnostics } from "../types/options.js";
+import type { ExecutionStepOption, HostExecuteGraphRunOptions, SkillKeyResolutionOptions } from "../types/options.js";
+import type { PlaygroundReporter } from "../playground/PlaygroundReporter.js";
+import type { CreateRunxOptions, RunxClient } from "@x12i/runx";
+import type { ModelConfigSelection } from "../types/refs.js";
+import { type EventEmitter } from "./events.js";
+import type { NodeTraceEntry } from "../types/results.js";
+import type { ExecuteGraphStepResponse } from "../types/results.js";
+export type RunTaskRequest = {
+    skillKey: string;
+    /** Execution pipeline (pre → main → post). When omitted, defaults to [{ phase: "main", type: "direct" }]. */
+    executionPipeline?: ExecutionStep[];
+    /** When true, task receives synthesized/context in prompt (e.g. for synthesized-context PRE step). */
+    includeContextInPrompt?: boolean;
+    input?: any;
+    variables?: Record<string, any>;
+    jobMemory?: any;
+    taskMemory?: any;
+    executionMemory?: any;
+    prevNodeId?: string;
+    jobId?: string;
+    taskId?: string;
+    agentId?: string;
+    skillId?: string;
+    masterSkillId?: string;
+    masterSkillActivityId?: string;
+    jobContext?: any;
+    modelConfig?: GraphAiModelConfig;
+    outputValidation?: {
+        schema: Record<string, unknown>;
+        mode?: "fail" | "warn";
+        validateWhenMissing?: boolean;
+    };
+    diagnostics?: RunTaskDiagnostics;
+    llmCall?: Record<string, unknown>;
+    identity?: Record<string, unknown>;
+    executionMode?: "default" | "trace";
+    taskKind?: "decision" | "utility" | "content";
+    autoValidateDecisionOutput?: boolean;
+};
+export type RunTaskResponse = {
+    ok: boolean;
+    rawContent?: string;
+    parsed?: any;
+    error?: any;
+    diagnostics?: any;
+    jobMemory?: any;
+    taskMemory?: any;
+    execution?: any;
+    /** Synthesis / observability / run-log passthrough from @exellix/ai-tasks. */
+    metadata?: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+};
+export interface TasksClientLike {
+    runTask(req: RunTaskRequest): Promise<RunTaskResponse>;
+}
+export interface GraphLoader {
+    loadGraph(graphId: string): Promise<any>;
+}
+/**
+ * Dynamic state and run-scoped options for one graph execution.
+ * Static graph shape belongs on {@link GraphExecutionRequest.model}; this object
+ * is the per-run state that may be populated and mutated during execution.
+ */
+export interface GraphRuntimeObject extends HostExecuteGraphRunOptions {
+    /** Host correlation id (mandatory). Merged onto `job.id` / `job.jobId` before node execution. */
+    jobId: string;
+    /** Host job envelope (`agentId`, `jobType`, `input`, etc.). */
+    job: any;
+    /** Active input for this execution. Mirrored to `runtime.executionMemory.input`. */
+    input?: Record<string, unknown>;
+    /** Caller / graph-entry bag. Mirrored to `runtime.executionMemory.inputs` (dual root with `input`). */
+    inputs?: Record<string, unknown>;
+    /** Temporary task/node-scoped runtime memory. */
+    taskMemory?: any;
+    /** Graph-run-level runtime memory initialized at execution start. */
+    jobMemory?: any;
+    /** Task-visible execution state. This is forwarded to task execution as `executionMemory`. */
+    executionMemory?: any;
+    /** Graph-engine-owned output state. `outputMapping` writes here; it is never sent to task execution. */
+    outputsMemory?: any;
+    /** Graph-scoped variable overrides → `executionMemory.variables`. */
+    variables?: Record<string, any>;
+    /** Job-scoped overrides → `executionMemory.jobVariables`. */
+    jobVariables?: Record<string, unknown>;
+    /** Task-scoped overrides for the active node → `executionMemory.taskVariables`. */
+    taskVariables?: Record<string, unknown>;
+    /** Runtime default model selection (`cases`); overrides GraphModelObject.modelConfig. */
+    modelConfig?: ModelConfigSelection;
+    /** Runtime alias map used to resolve modelConfig values before runTask. */
+    aliasConfig?: GraphModelAliasConfig;
+    /** Task-node runtime overrides keyed by node id. */
+    nodes?: Record<string, TaskNodeRuntimeObject>;
+    mode?: "forward" | "backward" | "hybrid";
+    goalNodeId?: string;
+    dimension?: string;
+    initialState?: any;
+    initialVariables?: Record<string, any>;
+    /** Include per-node trace on `ExecuteGraphResult.debug`. */
+    debugMode?: boolean;
+    /** Per-invocation playground reporter; overrides constructor default. */
+    playgroundReporter?: PlaygroundReporter;
+    /** Per-invocation event emitter; overrides constructor default. */
+    eventEmitter?: EventEmitter;
+}
+/** Required public graph execution request shape. */
+export interface GraphExecutionRequest {
+    model: GraphModelObject;
+    runtime: GraphRuntimeObject;
+}
+/** Canonical public execution request shape for `runtime.executeGraph(...)`. */
+export type ExecuteGraphInput = GraphExecutionRequest;
+/** Per-node trace entry surfaced on `ExecuteGraphResult.debug.nodes` when `debugMode: true`. */
+export interface ExecuteGraphDebugNodeEntry extends NodeTraceEntry {
+    nodeId: string;
+}
+export interface ExecuteGraphResult {
+    jobId: string;
+    /** Per-invocation UUID — same as every `runTask.taskId` for this graph run. */
+    taskId: string;
+    graphId: string;
+    status: "completed" | "failed";
+    outputsByNodeId: Record<string, any>;
+    /** Aggregated responses for executed non-finalizer steps, shaped by `metadata.graphExecution`. */
+    stepsResponses: ExecuteGraphStepResponse[];
+    engineSnapshot: any;
+    /** Canonical business output resolved from root `graph.response`. */
+    finalOutput?: any;
+    finalizerNodeId?: string;
+    finalizerType?: string;
+    errors?: Array<{
+        nodeId?: string;
+        error: any;
+    }>;
+    /** Final execution object (includes `_trace.nodes` for per-node timing). */
+    execution?: unknown;
+    /** Final graph-engine-owned output memory accumulated from finalizer `outputMapping` writes. */
+    outputsMemory?: unknown;
+    runLog?: RunLogEntry[];
+    runLogTruncated?: boolean;
+    runLogOmittedCount?: number;
+    logxerCorrelationId?: string;
+    /** Populated only when `executeGraph(input)` was called with `debugMode: true`. */
+    debug?: {
+        nodes: ExecuteGraphDebugNodeEntry[];
+    };
+    /**
+     * Audit fingerprint of the supplied graph model.
+     * Hosts (e.g. execution matrix) may persist this with catalog `graphVersion` for replay forensics.
+     */
+    graphAudit?: {
+        source: 'model';
+        contentSha256: string;
+    };
+}
+export type GraphKnowledgeResolverContext = {
+    model: GraphModelObject;
+    runtime: GraphRuntimeObject;
+    graphId: string;
+    jobId: string;
+    taskId: string;
+    node?: GraphNode;
+};
+export type GraphKnowledgeResolver = (refs: string[], context: GraphKnowledgeResolverContext) => Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
+export interface ExellixGraphRuntimeOptions extends HostExecuteGraphRunOptions {
+    graphLoader: GraphLoader;
+    tasksClient: TasksClientLike;
+    engineFactory: GraphEngineFactory;
+    /** Resolves model.jobKnowledge refs for outbound RunTaskRequest.jobMemory.knowledge. */
+    resolveJobKnowledge?: GraphKnowledgeResolver;
+    /** Resolves per-node taskKnowledge refs for outbound RunTaskRequest.taskMemory.knowledge. */
+    resolveTaskKnowledge?: GraphKnowledgeResolver;
+    /** Runx client for `jsConditionFunction`, `aiCondition`, and conditional modelConfig cases that need it. */
+    runx?: RunxClient;
+    /** Lazy `createRunx` when nodes require runx and `runx` is omitted. */
+    runxCreateOptions?: CreateRunxOptions;
+    concurrency?: number;
+    /** Default playground reporter for each `executeGraph` call; per-call {@link GraphRuntimeObject.playgroundReporter} wins. */
+    playgroundReporter?: PlaygroundReporter;
+    /**
+     * Default event emitter for graph + node lifecycle events. Per-invocation
+     * {@link GraphRuntimeObject.eventEmitter} overrides this when set.
+     * Subscribers receive `graph:start`, `graph:complete`, `graph:fail`,
+     * `node:start`, `node:complete`, `node:fail`.
+     */
+    eventEmitter?: EventEmitter;
+}
+export declare function createExellixGraphRuntime(opts: ExellixGraphRuntimeOptions): {
+    executeGraph: (input: ExecuteGraphInput) => Promise<ExecuteGraphResult>;
+    executeNode: (input: {
+        graphId: string;
+        graph?: Graph;
+        /** Same UUID for every `runTask` in this `executeGraph` invocation; omitted → new UUID per direct `executeNode` call. */
+        graphRunTaskId?: string;
+        node: any;
+        job: any;
+        jobMemory?: any;
+        taskMemory?: any;
+        execution?: any;
+        outputsMemory?: any;
+        variables?: Record<string, any>;
+        /** Per-node task-scope overrides → `executionMemory.taskVariables`. */
+        taskVariables?: Record<string, unknown>;
+        prevNodeId?: string;
+        /** Overrides graph-level / runtime default for this node only. */
+        modelConfig?: GraphAiModelConfig;
+        llmCall?: Record<string, unknown>;
+        runTaskIdentity?: Record<string, unknown>;
+        runTaskExecutionMode?: "default" | "trace";
+        runTaskDiagnostics?: RunTaskDiagnostics;
+        /** Resolved model jobKnowledge, applied only to outbound RunTaskRequest.jobMemory. */
+        jobKnowledgePatch?: Record<string, unknown>;
+        /** Resolved per-node taskKnowledge, applied only to outbound RunTaskRequest.taskMemory. */
+        taskKnowledgePatch?: Record<string, unknown>;
+        /** Graph-run default pipeline; node / `execution.executionPipeline` override per executeNode rules. */
+        graphExecutionPipeline?: ExecutionStepOption[];
+        skillKeyResolution?: SkillKeyResolutionOptions;
+        nodeTimeoutMs?: number;
+        clearSynthesizedContextPerNode?: boolean;
+        stepRetryPolicy?: import("../types/options.js").StepRetryPolicy;
+        /** Caller (`executeGraph`) supplies an emitter so node-level events fire with the parent's run identity. */
+        eventEmitter?: EventEmitter;
+        /** Caller jobCorrelation (currently `{ jobType }`) forwarded into node lifecycle events. */
+        jobCorrelation?: {
+            jobType?: string;
+        };
+        mainReadinessPolicy?: import("../types/options.js").MainReadinessPolicy;
+    }) => Promise<{
+        nodeId: string;
+        skillKey: string;
+        output: {
+            rawContent?: any;
+            parsed: any;
+        };
+        execution: any;
+        outputsMemory: any;
+    } | {
+        nodeId: any;
+        skillKey: "scoped-answer-writer" | "scoped-data-reader" | "deterministic-rule" | "scoped-answer-assembler";
+        output: {
+            parsed: Record<string, unknown>;
+        };
+        execution: any;
+        outputsMemory: Record<string, unknown>;
+    } | {
+        aiTasksObservability: Record<string, unknown>;
+        logxerCorrelationId?: string | undefined;
+        taskRunLog?: RunLogEntry[] | undefined;
+        nodeId: any;
+        skillKey: string;
+        output: {
+            rawContent: any;
+            parsed: any;
+        };
+        execution: any;
+        outputsMemory: Record<string, unknown>;
+        request: RunTaskRequest;
+    }>;
+};