@decaf-ts/as-graph 0.2.1 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +158 -2
- package/dist/as-graph.cjs +1 -1
- package/dist/as-graph.cjs.map +1 -1
- package/dist/as-graph.js +1 -1
- package/dist/as-graph.js.map +1 -1
- package/lib/cjs/dagster/DagsterGraphEventBridge.cjs +344 -0
- package/lib/cjs/dagster/DagsterGraphEventBridge.cjs.map +1 -0
- package/lib/cjs/dagster/DagsterGraphExecutionBackend.cjs +789 -0
- package/lib/cjs/dagster/DagsterGraphExecutionBackend.cjs.map +1 -0
- package/lib/cjs/dagster/DagsterResultMapper.cjs +56 -0
- package/lib/cjs/dagster/DagsterResultMapper.cjs.map +1 -0
- package/lib/cjs/dagster/DagsterTypes.cjs +4 -0
- package/lib/cjs/dagster/DagsterTypes.cjs.map +1 -0
- package/lib/cjs/dagster/capabilities.cjs +102 -0
- package/lib/cjs/dagster/capabilities.cjs.map +1 -0
- package/lib/cjs/dagster/constants.cjs +92 -0
- package/lib/cjs/dagster/constants.cjs.map +1 -0
- package/lib/cjs/dagster/index.cjs +32 -0
- package/lib/cjs/dagster/index.cjs.map +1 -0
- package/lib/cjs/engine/constants.cjs +6 -1
- package/lib/cjs/engine/constants.cjs.map +1 -1
- package/lib/cjs/engine/execution/GraphCodeMode.cjs +137 -0
- package/lib/cjs/engine/execution/GraphCodeMode.cjs.map +1 -0
- package/lib/cjs/engine/execution/GraphExecutionBackend.cjs +89 -0
- package/lib/cjs/engine/execution/GraphExecutionBackend.cjs.map +1 -0
- package/lib/cjs/engine/execution/GraphExecutionBackendRegistry.cjs +107 -0
- package/lib/cjs/engine/execution/GraphExecutionBackendRegistry.cjs.map +1 -0
- package/lib/cjs/engine/execution/GraphExecutionEngine.cjs +250 -733
- package/lib/cjs/engine/execution/GraphExecutionEngine.cjs.map +1 -1
- package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs +804 -0
- package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs.map +1 -0
- package/lib/cjs/engine/execution/index.cjs +4 -0
- package/lib/cjs/engine/execution/index.cjs.map +1 -1
- package/lib/cjs/engine/index.cjs +4 -0
- package/lib/cjs/engine/index.cjs.map +1 -1
- package/lib/cjs/engine/runs/GraphRunService.cjs +61 -0
- package/lib/cjs/engine/runs/GraphRunService.cjs.map +1 -1
- package/lib/cjs/engine/services/GraphWorkflowService.cjs +33 -14
- package/lib/cjs/engine/services/GraphWorkflowService.cjs.map +1 -1
- package/lib/cjs/mastra/MastraCapabilities.cjs +171 -0
- package/lib/cjs/mastra/MastraCapabilities.cjs.map +1 -0
- package/lib/cjs/mastra/MastraConditionBridge.cjs +39 -0
- package/lib/cjs/mastra/MastraConditionBridge.cjs.map +1 -0
- package/lib/cjs/mastra/MastraEventBridge.cjs +486 -0
- package/lib/cjs/mastra/MastraEventBridge.cjs.map +1 -0
- package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs +351 -0
- package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs.map +1 -0
- package/lib/cjs/mastra/MastraResumeGuard.cjs +127 -0
- package/lib/cjs/mastra/MastraResumeGuard.cjs.map +1 -0
- package/lib/cjs/mastra/MastraSchemaConverter.cjs +124 -0
- package/lib/cjs/mastra/MastraSchemaConverter.cjs.map +1 -0
- package/lib/cjs/mastra/MastraWorkflowCompiler.cjs +461 -0
- package/lib/cjs/mastra/MastraWorkflowCompiler.cjs.map +1 -0
- package/lib/cjs/mastra/MastraWorkflowManager.cjs +401 -0
- package/lib/cjs/mastra/MastraWorkflowManager.cjs.map +1 -0
- package/lib/cjs/mastra/index.cjs +35 -0
- package/lib/cjs/mastra/index.cjs.map +1 -0
- package/lib/cjs/mastra/types.cjs +34 -0
- package/lib/cjs/mastra/types.cjs.map +1 -0
- package/lib/cjs/nest/graph/GraphEngineCapabilityManifest.cjs +136 -0
- package/lib/cjs/nest/graph/GraphEngineCapabilityManifest.cjs.map +1 -0
- package/lib/cjs/nest/graph/GraphEngineCapabilityService.cjs +140 -0
- package/lib/cjs/nest/graph/GraphEngineCapabilityService.cjs.map +1 -0
- package/lib/cjs/nest/graph/GraphEngineController.cjs +227 -0
- package/lib/cjs/nest/graph/GraphEngineController.cjs.map +1 -0
- package/lib/cjs/nest/graph/GraphExecutionModule.cjs +30 -2
- package/lib/cjs/nest/graph/GraphExecutionModule.cjs.map +1 -1
- package/lib/cjs/nest/graph/index.cjs +3 -0
- package/lib/cjs/nest/graph/index.cjs.map +1 -1
- package/lib/cjs/nest/graph/main.cjs +54 -0
- package/lib/cjs/nest/graph/main.cjs.map +1 -0
- package/lib/cjs/nest/graph/servingErrors.cjs +3 -0
- package/lib/cjs/nest/graph/servingErrors.cjs.map +1 -1
- package/lib/cjs/node/utility/code/node.cjs +11 -3
- package/lib/cjs/node/utility/code/node.cjs.map +1 -1
- package/lib/cjs/shared/graph/catalog/GraphManifestCompiler.cjs +2 -3
- package/lib/cjs/shared/graph/catalog/GraphManifestCompiler.cjs.map +1 -1
- package/lib/cjs/shared/graph/constants.cjs +8 -0
- package/lib/cjs/shared/graph/constants.cjs.map +1 -1
- package/lib/cjs/shared/graph/index.cjs +2 -1
- package/lib/cjs/shared/graph/index.cjs.map +1 -1
- package/lib/cjs/shared/graph/layout/GraphWorkflowLayout.cjs +146 -0
- package/lib/cjs/shared/graph/layout/GraphWorkflowLayout.cjs.map +1 -0
- package/lib/cjs/shared/graph/layout/index.cjs +23 -0
- package/lib/cjs/shared/graph/layout/index.cjs.map +1 -0
- package/lib/cjs/shared/graph/layout/layout-options.cjs +93 -0
- package/lib/cjs/shared/graph/layout/layout-options.cjs.map +1 -0
- package/lib/cjs/shared/ui/index.cjs +8 -10
- package/lib/cjs/shared/ui/index.cjs.map +1 -1
- package/lib/esm/dagster/DagsterGraphEventBridge.js +339 -0
- package/lib/esm/dagster/DagsterGraphEventBridge.js.map +1 -0
- package/lib/esm/dagster/DagsterGraphExecutionBackend.js +781 -0
- package/lib/esm/dagster/DagsterGraphExecutionBackend.js.map +1 -0
- package/lib/esm/dagster/DagsterResultMapper.js +51 -0
- package/lib/esm/dagster/DagsterResultMapper.js.map +1 -0
- package/lib/esm/dagster/DagsterTypes.js +2 -0
- package/lib/esm/dagster/DagsterTypes.js.map +1 -0
- package/lib/esm/dagster/capabilities.js +97 -0
- package/lib/esm/dagster/capabilities.js.map +1 -0
- package/lib/esm/dagster/constants.js +88 -0
- package/lib/esm/dagster/constants.js.map +1 -0
- package/lib/esm/dagster/index.js +15 -0
- package/lib/esm/dagster/index.js.map +1 -0
- package/lib/esm/engine/constants.js +5 -0
- package/lib/esm/engine/constants.js.map +1 -1
- package/lib/esm/engine/execution/GraphCodeMode.js +132 -0
- package/lib/esm/engine/execution/GraphCodeMode.js.map +1 -0
- package/lib/esm/engine/execution/GraphExecutionBackend.js +83 -0
- package/lib/esm/engine/execution/GraphExecutionBackend.js.map +1 -0
- package/lib/esm/engine/execution/GraphExecutionBackendRegistry.js +102 -0
- package/lib/esm/engine/execution/GraphExecutionBackendRegistry.js.map +1 -0
- package/lib/esm/engine/execution/GraphExecutionEngine.js +232 -716
- package/lib/esm/engine/execution/GraphExecutionEngine.js.map +1 -1
- package/lib/esm/engine/execution/LocalGraphExecutionBackend.js +799 -0
- package/lib/esm/engine/execution/LocalGraphExecutionBackend.js.map +1 -0
- package/lib/esm/engine/execution/index.js +4 -0
- package/lib/esm/engine/execution/index.js.map +1 -1
- package/lib/esm/engine/index.js +4 -0
- package/lib/esm/engine/index.js.map +1 -1
- package/lib/esm/engine/runs/GraphRunService.js +62 -1
- package/lib/esm/engine/runs/GraphRunService.js.map +1 -1
- package/lib/esm/engine/services/GraphWorkflowService.js +33 -14
- package/lib/esm/engine/services/GraphWorkflowService.js.map +1 -1
- package/lib/esm/mastra/MastraCapabilities.js +164 -0
- package/lib/esm/mastra/MastraCapabilities.js.map +1 -0
- package/lib/esm/mastra/MastraConditionBridge.js +34 -0
- package/lib/esm/mastra/MastraConditionBridge.js.map +1 -0
- package/lib/esm/mastra/MastraEventBridge.js +481 -0
- package/lib/esm/mastra/MastraEventBridge.js.map +1 -0
- package/lib/esm/mastra/MastraGraphExecutionBackend.js +346 -0
- package/lib/esm/mastra/MastraGraphExecutionBackend.js.map +1 -0
- package/lib/esm/mastra/MastraResumeGuard.js +123 -0
- package/lib/esm/mastra/MastraResumeGuard.js.map +1 -0
- package/lib/esm/mastra/MastraSchemaConverter.js +119 -0
- package/lib/esm/mastra/MastraSchemaConverter.js.map +1 -0
- package/lib/esm/mastra/MastraWorkflowCompiler.js +456 -0
- package/lib/esm/mastra/MastraWorkflowCompiler.js.map +1 -0
- package/lib/esm/mastra/MastraWorkflowManager.js +396 -0
- package/lib/esm/mastra/MastraWorkflowManager.js.map +1 -0
- package/lib/esm/mastra/index.js +18 -0
- package/lib/esm/mastra/index.js.map +1 -0
- package/lib/esm/mastra/types.js +30 -0
- package/lib/esm/mastra/types.js.map +1 -0
- package/lib/esm/nest/graph/GraphEngineCapabilityManifest.js +129 -0
- package/lib/esm/nest/graph/GraphEngineCapabilityManifest.js.map +1 -0
- package/lib/esm/nest/graph/GraphEngineCapabilityService.js +131 -0
- package/lib/esm/nest/graph/GraphEngineCapabilityService.js.map +1 -0
- package/lib/esm/nest/graph/GraphEngineController.js +218 -0
- package/lib/esm/nest/graph/GraphEngineController.js.map +1 -0
- package/lib/esm/nest/graph/GraphExecutionModule.js +30 -2
- package/lib/esm/nest/graph/GraphExecutionModule.js.map +1 -1
- package/lib/esm/nest/graph/index.js +3 -0
- package/lib/esm/nest/graph/index.js.map +1 -1
- package/lib/esm/nest/graph/main.js +51 -0
- package/lib/esm/nest/graph/main.js.map +1 -0
- package/lib/esm/nest/graph/servingErrors.js +3 -0
- package/lib/esm/nest/graph/servingErrors.js.map +1 -1
- package/lib/esm/node/utility/code/node.js +11 -3
- package/lib/esm/node/utility/code/node.js.map +1 -1
- package/lib/esm/shared/graph/GraphExecutionStateMapper.js.map +1 -1
- package/lib/esm/shared/graph/catalog/GraphManifestCompiler.js +2 -3
- package/lib/esm/shared/graph/catalog/GraphManifestCompiler.js.map +1 -1
- package/lib/esm/shared/graph/constants.js +8 -0
- package/lib/esm/shared/graph/constants.js.map +1 -1
- package/lib/esm/shared/graph/index.js +2 -1
- package/lib/esm/shared/graph/index.js.map +1 -1
- package/lib/esm/shared/graph/layout/GraphWorkflowLayout.js +107 -0
- package/lib/esm/shared/graph/layout/GraphWorkflowLayout.js.map +1 -0
- package/lib/esm/shared/graph/layout/index.js +6 -0
- package/lib/esm/shared/graph/layout/index.js.map +1 -0
- package/lib/esm/shared/graph/layout/layout-options.js +96 -0
- package/lib/esm/shared/graph/layout/layout-options.js.map +1 -0
- package/lib/esm/shared/ui/index.js +8 -10
- package/lib/esm/shared/ui/index.js.map +1 -1
- package/lib/types/dagster/DagsterGraphEventBridge.d.cts +142 -0
- package/lib/types/dagster/DagsterGraphEventBridge.d.mts +142 -0
- package/lib/types/dagster/DagsterGraphExecutionBackend.d.cts +323 -0
- package/lib/types/dagster/DagsterGraphExecutionBackend.d.mts +323 -0
- package/lib/types/dagster/DagsterResultMapper.d.cts +50 -0
- package/lib/types/dagster/DagsterResultMapper.d.mts +50 -0
- package/lib/types/dagster/DagsterTypes.d.cts +355 -0
- package/lib/types/dagster/DagsterTypes.d.mts +355 -0
- package/lib/types/dagster/capabilities.d.cts +34 -0
- package/lib/types/dagster/capabilities.d.mts +34 -0
- package/lib/types/dagster/constants.d.cts +87 -0
- package/lib/types/dagster/constants.d.mts +87 -0
- package/lib/types/dagster/index.d.cts +14 -0
- package/lib/types/dagster/index.d.mts +14 -0
- package/lib/types/engine/constants.d.cts +5 -0
- package/lib/types/engine/constants.d.mts +5 -0
- package/lib/types/engine/execution/GraphCodeMode.d.cts +52 -0
- package/lib/types/engine/execution/GraphCodeMode.d.mts +52 -0
- package/lib/types/engine/execution/GraphExecutionBackend.d.cts +306 -0
- package/lib/types/engine/execution/GraphExecutionBackend.d.mts +306 -0
- package/lib/types/engine/execution/GraphExecutionBackendRegistry.d.cts +59 -0
- package/lib/types/engine/execution/GraphExecutionBackendRegistry.d.mts +59 -0
- package/lib/types/engine/execution/GraphExecutionEngine.d.cts +116 -135
- package/lib/types/engine/execution/GraphExecutionEngine.d.mts +116 -135
- package/lib/types/engine/execution/LocalGraphExecutionBackend.d.cts +232 -0
- package/lib/types/engine/execution/LocalGraphExecutionBackend.d.mts +232 -0
- package/lib/types/engine/execution/index.d.cts +4 -0
- package/lib/types/engine/execution/index.d.mts +4 -0
- package/lib/types/engine/index.d.cts +4 -0
- package/lib/types/engine/index.d.mts +4 -0
- package/lib/types/engine/runs/GraphRunService.d.cts +19 -0
- package/lib/types/engine/runs/GraphRunService.d.mts +19 -0
- package/lib/types/engine/services/GraphWorkflowService.d.cts +22 -0
- package/lib/types/engine/services/GraphWorkflowService.d.mts +22 -0
- package/lib/types/mastra/MastraCapabilities.d.cts +91 -0
- package/lib/types/mastra/MastraCapabilities.d.mts +91 -0
- package/lib/types/mastra/MastraConditionBridge.d.cts +38 -0
- package/lib/types/mastra/MastraConditionBridge.d.mts +38 -0
- package/lib/types/mastra/MastraEventBridge.d.cts +189 -0
- package/lib/types/mastra/MastraEventBridge.d.mts +189 -0
- package/lib/types/mastra/MastraGraphExecutionBackend.d.cts +119 -0
- package/lib/types/mastra/MastraGraphExecutionBackend.d.mts +119 -0
- package/lib/types/mastra/MastraResumeGuard.d.cts +58 -0
- package/lib/types/mastra/MastraResumeGuard.d.mts +58 -0
- package/lib/types/mastra/MastraSchemaConverter.d.cts +39 -0
- package/lib/types/mastra/MastraSchemaConverter.d.mts +39 -0
- package/lib/types/mastra/MastraWorkflowCompiler.d.cts +218 -0
- package/lib/types/mastra/MastraWorkflowCompiler.d.mts +218 -0
- package/lib/types/mastra/MastraWorkflowManager.d.cts +220 -0
- package/lib/types/mastra/MastraWorkflowManager.d.mts +220 -0
- package/lib/types/mastra/index.d.cts +17 -0
- package/lib/types/mastra/index.d.mts +17 -0
- package/lib/types/mastra/types.d.cts +222 -0
- package/lib/types/mastra/types.d.mts +222 -0
- package/lib/types/nest/graph/GraphEngineCapabilityManifest.d.cts +87 -0
- package/lib/types/nest/graph/GraphEngineCapabilityManifest.d.mts +87 -0
- package/lib/types/nest/graph/GraphEngineCapabilityService.d.cts +98 -0
- package/lib/types/nest/graph/GraphEngineCapabilityService.d.mts +98 -0
- package/lib/types/nest/graph/GraphEngineController.d.cts +74 -0
- package/lib/types/nest/graph/GraphEngineController.d.mts +74 -0
- package/lib/types/nest/graph/GraphExecutionModule.d.cts +8 -0
- package/lib/types/nest/graph/GraphExecutionModule.d.mts +8 -0
- package/lib/types/nest/graph/index.d.cts +3 -0
- package/lib/types/nest/graph/index.d.mts +3 -0
- package/lib/types/nest/graph/main.d.cts +1 -0
- package/lib/types/nest/graph/main.d.mts +1 -0
- package/lib/types/nest/graph/servingErrors.d.cts +3 -1
- package/lib/types/nest/graph/servingErrors.d.mts +3 -1
- package/lib/types/node/utility/code/node.d.cts +1 -1
- package/lib/types/node/utility/code/node.d.mts +1 -1
- package/lib/types/shared/graph/GraphExecutionStateMapper.d.cts +5 -5
- package/lib/types/shared/graph/GraphExecutionStateMapper.d.mts +5 -5
- package/lib/types/shared/graph/constants.d.cts +8 -0
- package/lib/types/shared/graph/constants.d.mts +8 -0
- package/lib/types/shared/graph/index.d.cts +2 -1
- package/lib/types/shared/graph/index.d.mts +2 -1
- package/lib/types/shared/graph/layout/GraphWorkflowLayout.d.cts +49 -0
- package/lib/types/shared/graph/layout/GraphWorkflowLayout.d.mts +49 -0
- package/lib/types/shared/graph/layout/index.d.cts +5 -0
- package/lib/types/shared/graph/layout/index.d.mts +5 -0
- package/lib/types/shared/graph/layout/layout-options.d.cts +46 -0
- package/lib/types/shared/graph/layout/layout-options.d.mts +46 -0
- package/lib/types/shared/graph/types.d.cts +4 -3
- package/lib/types/shared/graph/types.d.mts +4 -3
- package/lib/types/shared/ui/index.d.cts +8 -10
- package/lib/types/shared/ui/index.d.mts +8 -10
- package/package.json +49 -6
- package/lib/cjs/shared/ui/GraphNodeView.cjs +0 -114
- package/lib/cjs/shared/ui/GraphNodeView.cjs.map +0 -1
- package/lib/cjs/shared/ui/GraphRunView.cjs +0 -96
- package/lib/cjs/shared/ui/GraphRunView.cjs.map +0 -1
- package/lib/cjs/shared/ui/GraphWorkflowView.cjs +0 -78
- package/lib/cjs/shared/ui/GraphWorkflowView.cjs.map +0 -1
- package/lib/cjs/shared/ui/types.cjs +0 -4
- package/lib/cjs/shared/ui/types.cjs.map +0 -1
- package/lib/esm/shared/ui/GraphNodeView.js +0 -107
- package/lib/esm/shared/ui/GraphNodeView.js.map +0 -1
- package/lib/esm/shared/ui/GraphRunView.js +0 -90
- package/lib/esm/shared/ui/GraphRunView.js.map +0 -1
- package/lib/esm/shared/ui/GraphWorkflowView.js +0 -72
- package/lib/esm/shared/ui/GraphWorkflowView.js.map +0 -1
- package/lib/esm/shared/ui/types.js +0 -2
- package/lib/esm/shared/ui/types.js.map +0 -1
- package/lib/types/shared/ui/GraphNodeView.d.cts +0 -48
- package/lib/types/shared/ui/GraphNodeView.d.mts +0 -48
- package/lib/types/shared/ui/GraphRunView.d.cts +0 -88
- package/lib/types/shared/ui/GraphRunView.d.mts +0 -88
- package/lib/types/shared/ui/GraphWorkflowView.d.cts +0 -18
- package/lib/types/shared/ui/GraphWorkflowView.d.mts +0 -18
- package/lib/types/shared/ui/types.d.cts +0 -200
- package/lib/types/shared/ui/types.d.mts +0 -200
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module as-graph/mastra/MastraWorkflowCompiler
|
|
3
|
+
* @summary Compiles canonical workflow documents into Mastra workflows
|
|
4
|
+
* (SAA-196).
|
|
5
|
+
* @description The compiler translates the canonical document's topological
|
|
6
|
+
* order into Mastra builder calls: leaf nodes become steps via host-provided
|
|
7
|
+
* handlers, `if`/`switch` nodes become branches over shared condition
|
|
8
|
+
* predicates, loops nest a recursive sub-compilation, and human-approval nodes
|
|
9
|
+
* become suspending steps with validated resume schemas. Compiled workflows are
|
|
10
|
+
* cached by document id and fingerprint; translation fails closed on unsupported
|
|
11
|
+
* kinds and cyclic documents.
|
|
12
|
+
*/
|
|
13
|
+
import { z } from "zod";
|
|
14
|
+
import type { GraphWorkflowDocument } from "../shared/graph/document/GraphWorkflowDocument.d.cts";
|
|
15
|
+
import { type MastraBackendConfig, type MastraNodeStepHandler } from "./types.d.cts";
|
|
16
|
+
/** Document kind translated into a Mastra `if` branch. */
|
|
17
|
+
export declare const GRAPH_MASTRA_IF_KIND = "core.flow.if";
|
|
18
|
+
/** Document kind translated into a Mastra `switch` branch set. */
|
|
19
|
+
export declare const GRAPH_MASTRA_SWITCH_KIND = "core.flow.switch";
|
|
20
|
+
/** Document kind translated into a Mastra `foreach` loop. */
|
|
21
|
+
export declare const GRAPH_MASTRA_FOREACH_KIND = "graph-foreach-loop-node";
|
|
22
|
+
/** Document kind translated into a Mastra `do-while` loop. */
|
|
23
|
+
export declare const GRAPH_MASTRA_WHILE_KIND = "graph-while-loop-node";
|
|
24
|
+
/** Document kind translated into a Mastra `do-until` loop. */
|
|
25
|
+
export declare const GRAPH_MASTRA_UNTIL_KIND = "graph-until-loop-node";
|
|
26
|
+
/** Document kind translated into a Mastra suspending approval step. */
|
|
27
|
+
export declare const GRAPH_MASTRA_HUMAN_APPROVAL_KIND = "core.flow.humanApproval";
|
|
28
|
+
/**
|
|
29
|
+
* A compiled Mastra workflow plus everything resume and capability reporting
|
|
30
|
+
* need: the translated steps by node id, the validated resume schemas by
|
|
31
|
+
* suspendable node id, and the node ids whose output schemas degraded.
|
|
32
|
+
*/
|
|
33
|
+
export interface MastraCompiledWorkflow {
|
|
34
|
+
/** The canonical workflow id the workflow was compiled from. */
|
|
35
|
+
workflowId: string;
|
|
36
|
+
/** The document fingerprint the workflow was compiled from. */
|
|
37
|
+
fingerprint: string;
|
|
38
|
+
/** The cache key (`workflowId::fingerprint`) the compilation is stored under. */
|
|
39
|
+
cacheKey: string;
|
|
40
|
+
/** The committed Mastra workflow object. */
|
|
41
|
+
workflow: unknown;
|
|
42
|
+
/** The translated Mastra steps, keyed by document node id. */
|
|
43
|
+
steps: Map<string, unknown>;
|
|
44
|
+
/** Validated resume schemas, keyed by suspendable node id. */
|
|
45
|
+
resumeSchemas: Map<string, z.ZodTypeAny>;
|
|
46
|
+
/** Node ids whose declared output schema degraded during conversion. */
|
|
47
|
+
degradedSchemas: string[];
|
|
48
|
+
}
|
|
49
|
+
/** Options a {@link MastraWorkflowCompiler} is created with. */
|
|
50
|
+
export interface MastraWorkflowCompilerOptions {
|
|
51
|
+
/** Node-kind step handlers used to translate leaf nodes. */
|
|
52
|
+
stepHandlers?: MastraNodeStepHandler[];
|
|
53
|
+
/** Optional backend configuration (reserved for handler plumbing). */
|
|
54
|
+
config?: MastraBackendConfig;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Translates canonical documents into cached Mastra workflows. Leaf node
|
|
58
|
+
* translation is delegated entirely to host-provided step handlers, so the
|
|
59
|
+
* compiler has no node executors of its own and fails closed when a kind has no
|
|
60
|
+
* handler.
|
|
61
|
+
*/
|
|
62
|
+
export declare class MastraWorkflowCompiler {
|
|
63
|
+
/** Compiled workflows keyed by `workflowId::fingerprint`. */
|
|
64
|
+
private readonly cache;
|
|
65
|
+
/** Node-kind step handlers used for leaf translation. */
|
|
66
|
+
private readonly handlers;
|
|
67
|
+
/**
|
|
68
|
+
* Creates the compiler with an optional set of step handlers.
|
|
69
|
+
*
|
|
70
|
+
* @param options - Step handlers and optional backend configuration.
|
|
71
|
+
*/
|
|
72
|
+
constructor(options?: MastraWorkflowCompilerOptions);
|
|
73
|
+
/** Clears the compiled-workflow cache. */
|
|
74
|
+
clear(): void;
|
|
75
|
+
/**
|
|
76
|
+
* Whether a workflow is cached under the given cache key.
|
|
77
|
+
*
|
|
78
|
+
* @param cacheKey - The cache key to probe.
|
|
79
|
+
* @returns `true` when a compilation is cached.
|
|
80
|
+
*/
|
|
81
|
+
has(cacheKey: string): boolean;
|
|
82
|
+
/**
|
|
83
|
+
* Returns the cached compilation for a document, if any.
|
|
84
|
+
*
|
|
85
|
+
* @param document - The document whose compilation to look up.
|
|
86
|
+
* @returns The cached compilation, or `undefined` on a cache miss.
|
|
87
|
+
*/
|
|
88
|
+
get(document: GraphWorkflowDocument): MastraCompiledWorkflow | undefined;
|
|
89
|
+
/**
|
|
90
|
+
* Computes the compilation cache key of a document.
|
|
91
|
+
*
|
|
92
|
+
* @param document - The document to key.
|
|
93
|
+
* @returns The `workflowId::fingerprint` cache key.
|
|
94
|
+
*/
|
|
95
|
+
cacheKeyOf(document: GraphWorkflowDocument): string;
|
|
96
|
+
/**
|
|
97
|
+
* Compiles a document into a Mastra workflow, returning the cached
|
|
98
|
+
* compilation on a cache hit. Steps are applied in the document's topological
|
|
99
|
+
* order and the resulting builder is committed.
|
|
100
|
+
*
|
|
101
|
+
* @param document - The canonical document to compile.
|
|
102
|
+
* @returns The compiled workflow, steps, and resume-schema bookkeeping.
|
|
103
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_UNSUPPORTED_KIND} when the
|
|
104
|
+
* document is cyclic or a node kind has no step handler.
|
|
105
|
+
*/
|
|
106
|
+
compile(document: GraphWorkflowDocument): MastraCompiledWorkflow;
|
|
107
|
+
/**
|
|
108
|
+
* Applies one node to the builder, dispatching on its kind: branch, switch,
|
|
109
|
+
* loop, human approval, or leaf step.
|
|
110
|
+
*
|
|
111
|
+
* @param cursor - The builder position to extend.
|
|
112
|
+
* @param node - The document node to translate.
|
|
113
|
+
* @param document - The document being compiled.
|
|
114
|
+
* @param steps - Accumulated steps by node id.
|
|
115
|
+
* @param resumeSchemas - Accumulated resume schemas by node id.
|
|
116
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
117
|
+
* @returns The extended builder position.
|
|
118
|
+
*/
|
|
119
|
+
private applyNode;
|
|
120
|
+
/**
|
|
121
|
+
* Translates an `if` node into a Mastra branch over its `then` and optional
|
|
122
|
+
* `else` targets, guarded by the node's condition.
|
|
123
|
+
*
|
|
124
|
+
* @param cursor - The builder position to extend.
|
|
125
|
+
* @param node - The `if` node to translate.
|
|
126
|
+
* @param document - The document being compiled.
|
|
127
|
+
* @param steps - Accumulated steps by node id.
|
|
128
|
+
* @param resumeSchemas - Accumulated resume schemas by node id.
|
|
129
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
130
|
+
* @returns The extended builder position.
|
|
131
|
+
* @throws {GraphExecutionError} When the condition is missing or code-mode.
|
|
132
|
+
*/
|
|
133
|
+
private applyIf;
|
|
134
|
+
/**
|
|
135
|
+
* Translates a `switch` node into a Mastra branch set over its declared
|
|
136
|
+
* cases and optional default port; fails when no branch is translatable.
|
|
137
|
+
*
|
|
138
|
+
* @param cursor - The builder position to extend.
|
|
139
|
+
* @param node - The `switch` node to translate.
|
|
140
|
+
* @param document - The document being compiled.
|
|
141
|
+
* @param steps - Accumulated steps by node id.
|
|
142
|
+
* @param resumeSchemas - Accumulated resume schemas by node id.
|
|
143
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
144
|
+
* @returns The extended builder position.
|
|
145
|
+
* @throws {GraphExecutionError} When a case condition is untranslatable or
|
|
146
|
+
* no branch could be translated.
|
|
147
|
+
*/
|
|
148
|
+
private applySwitch;
|
|
149
|
+
/**
|
|
150
|
+
* Translates a loop node by recursively compiling its body document and
|
|
151
|
+
* applying it as a `foreach`, `do-while`, or `do-until` loop.
|
|
152
|
+
*
|
|
153
|
+
* @param cursor - The builder position to extend.
|
|
154
|
+
* @param node - The loop node to translate.
|
|
155
|
+
* @param document - The document being compiled.
|
|
156
|
+
* @param steps - Accumulated steps by node id.
|
|
157
|
+
* @param resumeSchemas - Accumulated resume schemas by node id.
|
|
158
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
159
|
+
* @returns The extended builder position.
|
|
160
|
+
* @throws {GraphExecutionError} When the loop has no body or the condition
|
|
161
|
+
* is untranslatable.
|
|
162
|
+
*/
|
|
163
|
+
private applyLoop;
|
|
164
|
+
/**
|
|
165
|
+
* Translates a human-approval node into a suspending Mastra step with a
|
|
166
|
+
* validated resume schema (C15); a non-approved resume is reported as a
|
|
167
|
+
* rejected outcome.
|
|
168
|
+
*
|
|
169
|
+
* @param cursor - The builder position to extend.
|
|
170
|
+
* @param node - The human-approval node to translate.
|
|
171
|
+
* @param steps - Accumulated steps by node id.
|
|
172
|
+
* @param resumeSchemas - Accumulated resume schemas by node id.
|
|
173
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
174
|
+
* @returns The extended builder position.
|
|
175
|
+
* @throws {GraphExecutionError} When the declared resume schema is unsafe.
|
|
176
|
+
*/
|
|
177
|
+
private applyHumanApproval;
|
|
178
|
+
/**
|
|
179
|
+
* Translates a leaf node through its registered step handler and records
|
|
180
|
+
* degraded output schemas.
|
|
181
|
+
*
|
|
182
|
+
* @param node - The leaf node to translate.
|
|
183
|
+
* @param steps - Accumulated steps by node id.
|
|
184
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
185
|
+
* @returns The created Mastra step.
|
|
186
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_UNSUPPORTED_KIND} when no
|
|
187
|
+
* handler is registered for the node kind.
|
|
188
|
+
*/
|
|
189
|
+
private buildLeafStep;
|
|
190
|
+
/**
|
|
191
|
+
* Resolves the Mastra step a control node's output port routes to, by
|
|
192
|
+
* following the first data edge leaving that port.
|
|
193
|
+
*
|
|
194
|
+
* @param nodeId - The control node id the port belongs to.
|
|
195
|
+
* @param port - The output port whose routing edge to follow.
|
|
196
|
+
* @param document - The document being compiled.
|
|
197
|
+
* @param steps - Accumulated steps by node id.
|
|
198
|
+
* @param resumeSchemas - Accumulated resume schemas by node id.
|
|
199
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
200
|
+
* @returns The target step, or `undefined` when the port routes nowhere.
|
|
201
|
+
*/
|
|
202
|
+
private targetStep;
|
|
203
|
+
/**
|
|
204
|
+
* Reads the canonical condition attached to a node's parameters.
|
|
205
|
+
*
|
|
206
|
+
* @param node - The node whose condition to read.
|
|
207
|
+
* @returns The condition, or `undefined` when none is declared.
|
|
208
|
+
*/
|
|
209
|
+
private conditionOf;
|
|
210
|
+
/**
|
|
211
|
+
* Resolves a switch node's case metadata, preferring node metadata and
|
|
212
|
+
* falling back to parameter-declared cases.
|
|
213
|
+
*
|
|
214
|
+
* @param node - The `switch` node to read.
|
|
215
|
+
* @returns The resolved switch metadata.
|
|
216
|
+
*/
|
|
217
|
+
private switchMetadataOf;
|
|
218
|
+
}
|
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module as-graph/mastra/MastraWorkflowCompiler
|
|
3
|
+
* @summary Compiles canonical workflow documents into Mastra workflows
|
|
4
|
+
* (SAA-196).
|
|
5
|
+
* @description The compiler translates the canonical document's topological
|
|
6
|
+
* order into Mastra builder calls: leaf nodes become steps via host-provided
|
|
7
|
+
* handlers, `if`/`switch` nodes become branches over shared condition
|
|
8
|
+
* predicates, loops nest a recursive sub-compilation, and human-approval nodes
|
|
9
|
+
* become suspending steps with validated resume schemas. Compiled workflows are
|
|
10
|
+
* cached by document id and fingerprint; translation fails closed on unsupported
|
|
11
|
+
* kinds and cyclic documents.
|
|
12
|
+
*/
|
|
13
|
+
import { z } from "zod";
|
|
14
|
+
import type { GraphWorkflowDocument } from "../shared/graph/document/GraphWorkflowDocument.d.mts";
|
|
15
|
+
import { type MastraBackendConfig, type MastraNodeStepHandler } from "./types.d.mts";
|
|
16
|
+
/** Document kind translated into a Mastra `if` branch. */
|
|
17
|
+
export declare const GRAPH_MASTRA_IF_KIND = "core.flow.if";
|
|
18
|
+
/** Document kind translated into a Mastra `switch` branch set. */
|
|
19
|
+
export declare const GRAPH_MASTRA_SWITCH_KIND = "core.flow.switch";
|
|
20
|
+
/** Document kind translated into a Mastra `foreach` loop. */
|
|
21
|
+
export declare const GRAPH_MASTRA_FOREACH_KIND = "graph-foreach-loop-node";
|
|
22
|
+
/** Document kind translated into a Mastra `do-while` loop. */
|
|
23
|
+
export declare const GRAPH_MASTRA_WHILE_KIND = "graph-while-loop-node";
|
|
24
|
+
/** Document kind translated into a Mastra `do-until` loop. */
|
|
25
|
+
export declare const GRAPH_MASTRA_UNTIL_KIND = "graph-until-loop-node";
|
|
26
|
+
/** Document kind translated into a Mastra suspending approval step. */
|
|
27
|
+
export declare const GRAPH_MASTRA_HUMAN_APPROVAL_KIND = "core.flow.humanApproval";
|
|
28
|
+
/**
|
|
29
|
+
* A compiled Mastra workflow plus everything resume and capability reporting
|
|
30
|
+
* need: the translated steps by node id, the validated resume schemas by
|
|
31
|
+
* suspendable node id, and the node ids whose output schemas degraded.
|
|
32
|
+
*/
|
|
33
|
+
export interface MastraCompiledWorkflow {
|
|
34
|
+
/** The canonical workflow id the workflow was compiled from. */
|
|
35
|
+
workflowId: string;
|
|
36
|
+
/** The document fingerprint the workflow was compiled from. */
|
|
37
|
+
fingerprint: string;
|
|
38
|
+
/** The cache key (`workflowId::fingerprint`) the compilation is stored under. */
|
|
39
|
+
cacheKey: string;
|
|
40
|
+
/** The committed Mastra workflow object. */
|
|
41
|
+
workflow: unknown;
|
|
42
|
+
/** The translated Mastra steps, keyed by document node id. */
|
|
43
|
+
steps: Map<string, unknown>;
|
|
44
|
+
/** Validated resume schemas, keyed by suspendable node id. */
|
|
45
|
+
resumeSchemas: Map<string, z.ZodTypeAny>;
|
|
46
|
+
/** Node ids whose declared output schema degraded during conversion. */
|
|
47
|
+
degradedSchemas: string[];
|
|
48
|
+
}
|
|
49
|
+
/** Options a {@link MastraWorkflowCompiler} is created with. */
|
|
50
|
+
export interface MastraWorkflowCompilerOptions {
|
|
51
|
+
/** Node-kind step handlers used to translate leaf nodes. */
|
|
52
|
+
stepHandlers?: MastraNodeStepHandler[];
|
|
53
|
+
/** Optional backend configuration (reserved for handler plumbing). */
|
|
54
|
+
config?: MastraBackendConfig;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Translates canonical documents into cached Mastra workflows. Leaf node
|
|
58
|
+
* translation is delegated entirely to host-provided step handlers, so the
|
|
59
|
+
* compiler has no node executors of its own and fails closed when a kind has no
|
|
60
|
+
* handler.
|
|
61
|
+
*/
|
|
62
|
+
export declare class MastraWorkflowCompiler {
|
|
63
|
+
/** Compiled workflows keyed by `workflowId::fingerprint`. */
|
|
64
|
+
private readonly cache;
|
|
65
|
+
/** Node-kind step handlers used for leaf translation. */
|
|
66
|
+
private readonly handlers;
|
|
67
|
+
/**
|
|
68
|
+
* Creates the compiler with an optional set of step handlers.
|
|
69
|
+
*
|
|
70
|
+
* @param options - Step handlers and optional backend configuration.
|
|
71
|
+
*/
|
|
72
|
+
constructor(options?: MastraWorkflowCompilerOptions);
|
|
73
|
+
/** Clears the compiled-workflow cache. */
|
|
74
|
+
clear(): void;
|
|
75
|
+
/**
|
|
76
|
+
* Whether a workflow is cached under the given cache key.
|
|
77
|
+
*
|
|
78
|
+
* @param cacheKey - The cache key to probe.
|
|
79
|
+
* @returns `true` when a compilation is cached.
|
|
80
|
+
*/
|
|
81
|
+
has(cacheKey: string): boolean;
|
|
82
|
+
/**
|
|
83
|
+
* Returns the cached compilation for a document, if any.
|
|
84
|
+
*
|
|
85
|
+
* @param document - The document whose compilation to look up.
|
|
86
|
+
* @returns The cached compilation, or `undefined` on a cache miss.
|
|
87
|
+
*/
|
|
88
|
+
get(document: GraphWorkflowDocument): MastraCompiledWorkflow | undefined;
|
|
89
|
+
/**
|
|
90
|
+
* Computes the compilation cache key of a document.
|
|
91
|
+
*
|
|
92
|
+
* @param document - The document to key.
|
|
93
|
+
* @returns The `workflowId::fingerprint` cache key.
|
|
94
|
+
*/
|
|
95
|
+
cacheKeyOf(document: GraphWorkflowDocument): string;
|
|
96
|
+
/**
|
|
97
|
+
* Compiles a document into a Mastra workflow, returning the cached
|
|
98
|
+
* compilation on a cache hit. Steps are applied in the document's topological
|
|
99
|
+
* order and the resulting builder is committed.
|
|
100
|
+
*
|
|
101
|
+
* @param document - The canonical document to compile.
|
|
102
|
+
* @returns The compiled workflow, steps, and resume-schema bookkeeping.
|
|
103
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_UNSUPPORTED_KIND} when the
|
|
104
|
+
* document is cyclic or a node kind has no step handler.
|
|
105
|
+
*/
|
|
106
|
+
compile(document: GraphWorkflowDocument): MastraCompiledWorkflow;
|
|
107
|
+
/**
|
|
108
|
+
* Applies one node to the builder, dispatching on its kind: branch, switch,
|
|
109
|
+
* loop, human approval, or leaf step.
|
|
110
|
+
*
|
|
111
|
+
* @param cursor - The builder position to extend.
|
|
112
|
+
* @param node - The document node to translate.
|
|
113
|
+
* @param document - The document being compiled.
|
|
114
|
+
* @param steps - Accumulated steps by node id.
|
|
115
|
+
* @param resumeSchemas - Accumulated resume schemas by node id.
|
|
116
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
117
|
+
* @returns The extended builder position.
|
|
118
|
+
*/
|
|
119
|
+
private applyNode;
|
|
120
|
+
/**
|
|
121
|
+
* Translates an `if` node into a Mastra branch over its `then` and optional
|
|
122
|
+
* `else` targets, guarded by the node's condition.
|
|
123
|
+
*
|
|
124
|
+
* @param cursor - The builder position to extend.
|
|
125
|
+
* @param node - The `if` node to translate.
|
|
126
|
+
* @param document - The document being compiled.
|
|
127
|
+
* @param steps - Accumulated steps by node id.
|
|
128
|
+
* @param resumeSchemas - Accumulated resume schemas by node id.
|
|
129
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
130
|
+
* @returns The extended builder position.
|
|
131
|
+
* @throws {GraphExecutionError} When the condition is missing or code-mode.
|
|
132
|
+
*/
|
|
133
|
+
private applyIf;
|
|
134
|
+
/**
|
|
135
|
+
* Translates a `switch` node into a Mastra branch set over its declared
|
|
136
|
+
* cases and optional default port; fails when no branch is translatable.
|
|
137
|
+
*
|
|
138
|
+
* @param cursor - The builder position to extend.
|
|
139
|
+
* @param node - The `switch` node to translate.
|
|
140
|
+
* @param document - The document being compiled.
|
|
141
|
+
* @param steps - Accumulated steps by node id.
|
|
142
|
+
* @param resumeSchemas - Accumulated resume schemas by node id.
|
|
143
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
144
|
+
* @returns The extended builder position.
|
|
145
|
+
* @throws {GraphExecutionError} When a case condition is untranslatable or
|
|
146
|
+
* no branch could be translated.
|
|
147
|
+
*/
|
|
148
|
+
private applySwitch;
|
|
149
|
+
/**
|
|
150
|
+
* Translates a loop node by recursively compiling its body document and
|
|
151
|
+
* applying it as a `foreach`, `do-while`, or `do-until` loop.
|
|
152
|
+
*
|
|
153
|
+
* @param cursor - The builder position to extend.
|
|
154
|
+
* @param node - The loop node to translate.
|
|
155
|
+
* @param document - The document being compiled.
|
|
156
|
+
* @param steps - Accumulated steps by node id.
|
|
157
|
+
* @param resumeSchemas - Accumulated resume schemas by node id.
|
|
158
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
159
|
+
* @returns The extended builder position.
|
|
160
|
+
* @throws {GraphExecutionError} When the loop has no body or the condition
|
|
161
|
+
* is untranslatable.
|
|
162
|
+
*/
|
|
163
|
+
private applyLoop;
|
|
164
|
+
/**
|
|
165
|
+
* Translates a human-approval node into a suspending Mastra step with a
|
|
166
|
+
* validated resume schema (C15); a non-approved resume is reported as a
|
|
167
|
+
* rejected outcome.
|
|
168
|
+
*
|
|
169
|
+
* @param cursor - The builder position to extend.
|
|
170
|
+
* @param node - The human-approval node to translate.
|
|
171
|
+
* @param steps - Accumulated steps by node id.
|
|
172
|
+
* @param resumeSchemas - Accumulated resume schemas by node id.
|
|
173
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
174
|
+
* @returns The extended builder position.
|
|
175
|
+
* @throws {GraphExecutionError} When the declared resume schema is unsafe.
|
|
176
|
+
*/
|
|
177
|
+
private applyHumanApproval;
|
|
178
|
+
/**
|
|
179
|
+
* Translates a leaf node through its registered step handler and records
|
|
180
|
+
* degraded output schemas.
|
|
181
|
+
*
|
|
182
|
+
* @param node - The leaf node to translate.
|
|
183
|
+
* @param steps - Accumulated steps by node id.
|
|
184
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
185
|
+
* @returns The created Mastra step.
|
|
186
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_UNSUPPORTED_KIND} when no
|
|
187
|
+
* handler is registered for the node kind.
|
|
188
|
+
*/
|
|
189
|
+
private buildLeafStep;
|
|
190
|
+
/**
|
|
191
|
+
* Resolves the Mastra step a control node's output port routes to, by
|
|
192
|
+
* following the first data edge leaving that port.
|
|
193
|
+
*
|
|
194
|
+
* @param nodeId - The control node id the port belongs to.
|
|
195
|
+
* @param port - The output port whose routing edge to follow.
|
|
196
|
+
* @param document - The document being compiled.
|
|
197
|
+
* @param steps - Accumulated steps by node id.
|
|
198
|
+
* @param resumeSchemas - Accumulated resume schemas by node id.
|
|
199
|
+
* @param degradedSchemas - Accumulated degraded-schema node ids.
|
|
200
|
+
* @returns The target step, or `undefined` when the port routes nowhere.
|
|
201
|
+
*/
|
|
202
|
+
private targetStep;
|
|
203
|
+
/**
|
|
204
|
+
* Reads the canonical condition attached to a node's parameters.
|
|
205
|
+
*
|
|
206
|
+
* @param node - The node whose condition to read.
|
|
207
|
+
* @returns The condition, or `undefined` when none is declared.
|
|
208
|
+
*/
|
|
209
|
+
private conditionOf;
|
|
210
|
+
/**
|
|
211
|
+
* Resolves a switch node's case metadata, preferring node metadata and
|
|
212
|
+
* falling back to parameter-declared cases.
|
|
213
|
+
*
|
|
214
|
+
* @param node - The `switch` node to read.
|
|
215
|
+
* @returns The resolved switch metadata.
|
|
216
|
+
*/
|
|
217
|
+
private switchMetadataOf;
|
|
218
|
+
}
|
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module as-graph/mastra/MastraWorkflowManager
|
|
3
|
+
* @summary Management surface over real `@mastra/core` workflows (SAA-346).
|
|
4
|
+
* @description The Mastra analogue of a workflow-authoring/management surface:
|
|
5
|
+
* it translates a canonical document into a real committed Mastra workflow (through
|
|
6
|
+
* {@link MastraWorkflowCompiler}) and registers, updates, deletes, lists, reads,
|
|
7
|
+
* and serializes it through the **real** `Mastra` instance methods
|
|
8
|
+
* (`addWorkflow`/`removeWorkflow`/`getWorkflow`/`listWorkflows`/
|
|
9
|
+
* `getWorkflowOrigin`). Every operation fails closed when the wired runtime does
|
|
10
|
+
* not expose the real method, and the operations the pinned library does not back
|
|
11
|
+
* are declared honestly: persistence is `NOT-SUPPORTED` (the real
|
|
12
|
+
* `addDynamicWorkflow` persists only agent/tool-referenced steps, while the
|
|
13
|
+
* canonical translation emits host code steps) and revision is an
|
|
14
|
+
* `EXTENSION-POINT` (Mastra has no native workflow version; the wrapper tracks
|
|
15
|
+
* the canonical document fingerprint).
|
|
16
|
+
*/
|
|
17
|
+
import type { Context, MaybeContextualArg } from "@decaf-ts/core";
|
|
18
|
+
import type { GraphWorkflowDocument } from "../shared/graph/document/GraphWorkflowDocument.d.cts";
|
|
19
|
+
import { type MastraSerializedWorkflow, type MastraWorkflowDescriptor, type MastraWorkflowManagerOptions } from "./types.d.cts";
|
|
20
|
+
/**
|
|
21
|
+
* Management surface over real `@mastra/core` workflows (SAA-346). Holds only the
|
|
22
|
+
* wired runtime reference and the canonical-document compiler; it never constructs a
|
|
23
|
+
* Mastra primitive itself and never synthesizes a method the pinned library does not
|
|
24
|
+
* expose. Every method validates the runtime surface it needs first and fails
|
|
25
|
+
* closed with {@link GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE} otherwise.
|
|
26
|
+
*/
|
|
27
|
+
export declare class MastraWorkflowManager {
|
|
28
|
+
private readonly options;
|
|
29
|
+
/** Canonical document revision (fingerprint) by managed workflow id. */
|
|
30
|
+
private readonly revisions;
|
|
31
|
+
/**
|
|
32
|
+
* Wrapper-managed provenance: the owner recorded when the wrapper created or
|
|
33
|
+
* updated a workflow. An id absent from this map is not wrapper-managed, so a
|
|
34
|
+
* host `origin: "code"` registration is protected from overwrite/delete (C3).
|
|
35
|
+
*/
|
|
36
|
+
private readonly owners;
|
|
37
|
+
/** Standalone compiler used when the host does not inject one. */
|
|
38
|
+
private readonly fallbackCompiler;
|
|
39
|
+
/**
|
|
40
|
+
* @param options - The wired runtime and optional shared compiler.
|
|
41
|
+
*/
|
|
42
|
+
constructor(options?: MastraWorkflowManagerOptions);
|
|
43
|
+
/** The wired real `@mastra/core` runtime, when any. */
|
|
44
|
+
get runtime(): unknown;
|
|
45
|
+
/**
|
|
46
|
+
* Registers a workflow translated from a canonical document on the real Mastra
|
|
47
|
+
* instance (real `addWorkflow`). This is the honest "create" operation: the
|
|
48
|
+
* pinned library registers live, it does not persist a translated code-step
|
|
49
|
+
* definition (see {@link persist}).
|
|
50
|
+
*
|
|
51
|
+
* @param document - The canonical document to translate and register.
|
|
52
|
+
* @returns The managed workflow descriptor.
|
|
53
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE}
|
|
54
|
+
* when the runtime exposes no `addWorkflow`.
|
|
55
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_UNSUPPORTED_KIND} when the
|
|
56
|
+
* document cannot be translated.
|
|
57
|
+
*/
|
|
58
|
+
create(document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<MastraWorkflowDescriptor>;
|
|
59
|
+
/**
|
|
60
|
+
* Edits a managed workflow by recompiling the updated canonical document and
|
|
61
|
+
* replacing the live registration (real `removeWorkflow` then `addWorkflow`). The
|
|
62
|
+
* pinned library documents `removeWorkflow` as the update/delete path so a
|
|
63
|
+
* subsequent save can re-register the same id cleanly.
|
|
64
|
+
*
|
|
65
|
+
* @param document - The updated canonical document.
|
|
66
|
+
* @returns The managed workflow descriptor with its new revision.
|
|
67
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE}
|
|
68
|
+
* when the runtime exposes no `addWorkflow`/`removeWorkflow`.
|
|
69
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_WORKFLOW_NOT_FOUND} when
|
|
70
|
+
* no workflow is registered under the document id.
|
|
71
|
+
*/
|
|
72
|
+
update(document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<MastraWorkflowDescriptor>;
|
|
73
|
+
/**
|
|
74
|
+
* Deletes a managed workflow from the live Mastra registry (real
|
|
75
|
+
* `removeWorkflow`).
|
|
76
|
+
*
|
|
77
|
+
* @param workflowId - The managed workflow id to remove.
|
|
78
|
+
* @returns `true` when a workflow was removed.
|
|
79
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE}
|
|
80
|
+
* when the runtime exposes no `removeWorkflow`.
|
|
81
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_WORKFLOW_NOT_FOUND} when no
|
|
82
|
+
* workflow is registered under the id.
|
|
83
|
+
*/
|
|
84
|
+
delete(workflowId: string, ...args: MaybeContextualArg<Context>): Promise<boolean>;
|
|
85
|
+
/**
|
|
86
|
+
* Lists the managed workflows registered on the real Mastra instance (real
|
|
87
|
+
* `listWorkflows`).
|
|
88
|
+
*
|
|
89
|
+
* @returns The managed workflow descriptors, in registry order.
|
|
90
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE}
|
|
91
|
+
* when the runtime exposes no `listWorkflows`.
|
|
92
|
+
*/
|
|
93
|
+
list(): Promise<MastraWorkflowDescriptor[]>;
|
|
94
|
+
/**
|
|
95
|
+
* Reads one managed workflow registered on the real Mastra instance (real
|
|
96
|
+
* `getWorkflow`).
|
|
97
|
+
*
|
|
98
|
+
* @param workflowId - The managed workflow id to read.
|
|
99
|
+
* @returns The managed workflow descriptor.
|
|
100
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE}
|
|
101
|
+
* when the runtime exposes no `getWorkflow`.
|
|
102
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_WORKFLOW_NOT_FOUND} when no
|
|
103
|
+
* workflow is registered under the id.
|
|
104
|
+
*/
|
|
105
|
+
get(workflowId: string): Promise<MastraWorkflowDescriptor>;
|
|
106
|
+
/**
|
|
107
|
+
* Serializes a managed workflow through the real Mastra
|
|
108
|
+
* `Workflow.serializedStepGraph` surface.
|
|
109
|
+
*
|
|
110
|
+
* @param workflowId - The managed workflow id to serialize.
|
|
111
|
+
* @returns The JSON-safe serialized workflow.
|
|
112
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE}
|
|
113
|
+
* when the runtime exposes no `getWorkflow`.
|
|
114
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_WORKFLOW_NOT_FOUND} when no
|
|
115
|
+
* workflow is registered under the id.
|
|
116
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_SERIALIZE_NOT_SUPPORTED}
|
|
117
|
+
* when the registered workflow exposes no serializable step graph.
|
|
118
|
+
*/
|
|
119
|
+
serialize(workflowId: string): Promise<MastraSerializedWorkflow>;
|
|
120
|
+
/**
|
|
121
|
+
* The canonical document revision (fingerprint) the wrapper tracks for a
|
|
122
|
+
* document. Mastra has no native workflow version, so this is the honest
|
|
123
|
+
* `EXTENSION-POINT` revision identity: it is computed from the canonical
|
|
124
|
+
* document alone and requires no runtime.
|
|
125
|
+
*
|
|
126
|
+
* @param document - The canonical document to fingerprint.
|
|
127
|
+
* @returns The stable revision fingerprint.
|
|
128
|
+
*/
|
|
129
|
+
revision(document: GraphWorkflowDocument): string;
|
|
130
|
+
/**
|
|
131
|
+
* Persists a translated workflow to Mastra storage. The pinned real
|
|
132
|
+
* `Mastra.addDynamicWorkflow` persists only agent/tool-referenced steps, while
|
|
133
|
+
* the canonical translation emits host code steps, so this operation is
|
|
134
|
+
* `NOT-SUPPORTED` and fails closed rather than faking a persisted definition.
|
|
135
|
+
*
|
|
136
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_PERSIST_NOT_SUPPORTED}
|
|
137
|
+
* always.
|
|
138
|
+
*/
|
|
139
|
+
persist(): Promise<never>;
|
|
140
|
+
/** The compiler the surface translates canonical documents with. */
|
|
141
|
+
private compilerOf;
|
|
142
|
+
/**
|
|
143
|
+
* Resolves the wired runtime after asserting it exposes every required real
|
|
144
|
+
* Mastra method.
|
|
145
|
+
*
|
|
146
|
+
* @param methods - The real method names the operation needs.
|
|
147
|
+
* @returns The wired runtime.
|
|
148
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE}
|
|
149
|
+
* when the runtime is unwired or omits a required method.
|
|
150
|
+
*/
|
|
151
|
+
private requireRuntime;
|
|
152
|
+
/**
|
|
153
|
+
* Fails closed when a management mutation targets a workflow the wrapper did not
|
|
154
|
+
* create (C3 complete mediation). A wrapper-managed id is writable; any
|
|
155
|
+
* pre-existing registration — including a host `origin: "code"` workflow — is
|
|
156
|
+
* protected from overwrite/delete, and an existing workflow whose provenance
|
|
157
|
+
* cannot be determined is refused rather than mutated.
|
|
158
|
+
*
|
|
159
|
+
* @param runtime - The validated runtime.
|
|
160
|
+
* @param workflowId - The managed workflow id.
|
|
161
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_WORKFLOW_FORBIDDEN} when the
|
|
162
|
+
* workflow is not wrapper-managed.
|
|
163
|
+
*/
|
|
164
|
+
private assertWritableProvenance;
|
|
165
|
+
/**
|
|
166
|
+
* Enforces the C23 ownership predicate on a wrapper-managed workflow before a
|
|
167
|
+
* management mutation, mirroring the backend's `canAccessGraphResource`
|
|
168
|
+
* enforcement. Owner-less workflows stay writable by every caller.
|
|
169
|
+
*
|
|
170
|
+
* @param workflowId - The managed workflow id.
|
|
171
|
+
* @param callerOwner - The caller owner resolved from the context.
|
|
172
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_WORKFLOW_FORBIDDEN} when the
|
|
173
|
+
* caller may not write the workflow.
|
|
174
|
+
*/
|
|
175
|
+
private assertOwnerAccess;
|
|
176
|
+
/**
|
|
177
|
+
* Reads how the runtime reports a workflow's registration origin.
|
|
178
|
+
*
|
|
179
|
+
* @param runtime - The validated runtime.
|
|
180
|
+
* @param workflowId - The workflow id.
|
|
181
|
+
* @returns The origin, or `undefined` when the runtime reports none.
|
|
182
|
+
*/
|
|
183
|
+
private originOf;
|
|
184
|
+
/**
|
|
185
|
+
* Whether the runtime already has a workflow registered under the id.
|
|
186
|
+
*
|
|
187
|
+
* @param runtime - The validated runtime.
|
|
188
|
+
* @param workflowId - The workflow id.
|
|
189
|
+
* @returns `true` when a workflow is registered under the id.
|
|
190
|
+
*/
|
|
191
|
+
private registered;
|
|
192
|
+
/**
|
|
193
|
+
* Reads a registered workflow, mapping the real not-found failure onto the
|
|
194
|
+
* canonical error code.
|
|
195
|
+
*
|
|
196
|
+
* @param runtime - The validated runtime.
|
|
197
|
+
* @param workflowId - The managed workflow id to read.
|
|
198
|
+
* @returns The registered workflow object.
|
|
199
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_WORKFLOW_NOT_FOUND} when no
|
|
200
|
+
* workflow is registered under the id.
|
|
201
|
+
*/
|
|
202
|
+
private registeredWorkflow;
|
|
203
|
+
/**
|
|
204
|
+
* Builds a managed workflow descriptor, reading the real registration origin
|
|
205
|
+
* and the wrapper-tracked revision when available.
|
|
206
|
+
*
|
|
207
|
+
* @param workflowId - The managed workflow id.
|
|
208
|
+
* @param workflow - The registered workflow object.
|
|
209
|
+
* @returns The managed workflow descriptor.
|
|
210
|
+
*/
|
|
211
|
+
private describeWorkflow;
|
|
212
|
+
/**
|
|
213
|
+
* Builds a descriptor for a workflow the wrapper has just registered or
|
|
214
|
+
* updated.
|
|
215
|
+
*
|
|
216
|
+
* @param workflowId - The managed workflow id.
|
|
217
|
+
* @returns The managed workflow descriptor.
|
|
218
|
+
*/
|
|
219
|
+
private describe;
|
|
220
|
+
}
|