@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,189 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module as-graph/mastra/MastraEventBridge
|
|
3
|
+
* @summary Bridges Mastra's `fullStream` events onto the facade event sink
|
|
4
|
+
* (SAA-196).
|
|
5
|
+
* @description The bridge consumes the async event stream a Mastra run emits,
|
|
6
|
+
* translates workflow/step/log lifecycle events into canonical
|
|
7
|
+
* {@link GraphExecutionEvent} emissions, and mirrors node/edge visual-state and
|
|
8
|
+
* routed edge values so the canvas renders a Mastra run exactly like a local
|
|
9
|
+
* one. Unrecognised events are ignored unless they look like log entries.
|
|
10
|
+
*/
|
|
11
|
+
import type { GraphWorkflowDocument } from "../shared/graph/document/GraphWorkflowDocument.d.mts";
|
|
12
|
+
import type { GraphExecutionEventSink } from "../engine/execution/GraphExecutionBackend.d.mts";
|
|
13
|
+
/** Options a {@link MastraEventBridge} is created with. */
|
|
14
|
+
export interface MastraEventBridgeOptions {
|
|
15
|
+
/** The canonical run id the bridged events belong to. */
|
|
16
|
+
runId: string;
|
|
17
|
+
/** The parent run id, when the run is a nested execution. */
|
|
18
|
+
parentRunId?: string;
|
|
19
|
+
/** The canonical workflow id the bridged events belong to. */
|
|
20
|
+
workflowId: string;
|
|
21
|
+
/** The canonical document the Mastra workflow was compiled from. */
|
|
22
|
+
document: GraphWorkflowDocument;
|
|
23
|
+
/** The frame-aware facade event sink every event is emitted onto. */
|
|
24
|
+
sink: GraphExecutionEventSink;
|
|
25
|
+
/** The node path prefix events are reported under. */
|
|
26
|
+
path?: string[];
|
|
27
|
+
}
|
|
28
|
+
/** One raw Mastra `fullStream` event; shape is runtime-defined. */
|
|
29
|
+
export type MastraFullStreamEvent = Record<string, unknown>;
|
|
30
|
+
/**
|
|
31
|
+
* Translates Mastra `fullStream` events into canonical facade events. The
|
|
32
|
+
* bridge indexes the document's data edges by node endpoint so step results can
|
|
33
|
+
* be routed as edge values and step lifecycles can drive node/edge visual
|
|
34
|
+
* states. Log events (`log`, `writer`, `console`) are surfaced as
|
|
35
|
+
* `GRAPH_RUN_LOG` entries with a known log level.
|
|
36
|
+
*/
|
|
37
|
+
export declare class MastraEventBridge {
|
|
38
|
+
private readonly options;
|
|
39
|
+
/** Data edges leaving each node, keyed by source node id. */
|
|
40
|
+
private readonly outgoing;
|
|
41
|
+
/** Data edges entering each node, keyed by target node id. */
|
|
42
|
+
private readonly incoming;
|
|
43
|
+
/**
|
|
44
|
+
* Creates the bridge and indexes the document's node-scoped data edges.
|
|
45
|
+
*
|
|
46
|
+
* @param options - Run identity, document, and event sink options.
|
|
47
|
+
*/
|
|
48
|
+
constructor(options: MastraEventBridgeOptions);
|
|
49
|
+
/**
|
|
50
|
+
* Consumes a Mastra run's full event stream until it ends.
|
|
51
|
+
*
|
|
52
|
+
* @param stream - The async iterable of Mastra `fullStream` events.
|
|
53
|
+
* @returns Resolves when the stream is exhausted.
|
|
54
|
+
*/
|
|
55
|
+
attach(stream: AsyncIterable<MastraFullStreamEvent>): Promise<void>;
|
|
56
|
+
/**
|
|
57
|
+
* Translates one raw Mastra event and emits the matching canonical events.
|
|
58
|
+
* Unrecognised event types are ignored unless they look like log entries.
|
|
59
|
+
*
|
|
60
|
+
* @param event - The raw Mastra `fullStream` event.
|
|
61
|
+
* @returns Resolves once the derived events have been emitted.
|
|
62
|
+
*/
|
|
63
|
+
handle(event: MastraFullStreamEvent): Promise<void>;
|
|
64
|
+
/**
|
|
65
|
+
* Emits the node-started lifecycle, node visual state, and running edge
|
|
66
|
+
* states for the incoming data edges of a started step.
|
|
67
|
+
*
|
|
68
|
+
* @param event - The raw `workflow-step-start` event.
|
|
69
|
+
* @returns Resolves once the derived events have been emitted.
|
|
70
|
+
*/
|
|
71
|
+
private onStepStart;
|
|
72
|
+
/**
|
|
73
|
+
* Emits the step's incremental output as a node-output event.
|
|
74
|
+
*
|
|
75
|
+
* @param event - The raw `workflow-step-output` event.
|
|
76
|
+
* @returns Resolves once the derived events have been emitted.
|
|
77
|
+
*/
|
|
78
|
+
private onStepOutput;
|
|
79
|
+
/**
|
|
80
|
+
* Emits one loop-iteration progress event for a foreach/while step.
|
|
81
|
+
*
|
|
82
|
+
* @param event - The raw `workflow-step-progress` event.
|
|
83
|
+
* @returns Resolves once the derived events have been emitted.
|
|
84
|
+
*/
|
|
85
|
+
private onStepProgress;
|
|
86
|
+
/**
|
|
87
|
+
* Emits the terminal lifecycle of a finished step: failure, suspension
|
|
88
|
+
* block, or completion (including routed outgoing edge values).
|
|
89
|
+
*
|
|
90
|
+
* @param event - The raw `workflow-step-result` event.
|
|
91
|
+
* @returns Resolves once the derived events have been emitted.
|
|
92
|
+
*/
|
|
93
|
+
private onStepResult;
|
|
94
|
+
/**
|
|
95
|
+
* Emits the suspension state of a suspended step and the workflow-suspended
|
|
96
|
+
* event carrying Mastra's suspend payload.
|
|
97
|
+
*
|
|
98
|
+
* @param event - The raw `workflow-step-suspended` event.
|
|
99
|
+
* @returns Resolves once the derived events have been emitted.
|
|
100
|
+
*/
|
|
101
|
+
private onStepSuspended;
|
|
102
|
+
/**
|
|
103
|
+
* Emits the terminal workflow event: failed, cancelled, or completed with
|
|
104
|
+
* the final workflow result.
|
|
105
|
+
*
|
|
106
|
+
* @param event - The raw `workflow-finish` event.
|
|
107
|
+
* @returns Resolves once the derived events have been emitted.
|
|
108
|
+
*/
|
|
109
|
+
private onWorkflowFinish;
|
|
110
|
+
/**
|
|
111
|
+
* Emits a run-log entry for a bridged log event; unknown levels are dropped.
|
|
112
|
+
*
|
|
113
|
+
* @param event - The raw log/writer/console event.
|
|
114
|
+
* @returns Resolves once the log entry has been emitted.
|
|
115
|
+
*/
|
|
116
|
+
private onLog;
|
|
117
|
+
/**
|
|
118
|
+
* Heuristic check whether an unrecognised event is a log entry.
|
|
119
|
+
*
|
|
120
|
+
* @param event - The raw Mastra event.
|
|
121
|
+
* @returns `true` when the event carries a level and a message.
|
|
122
|
+
*/
|
|
123
|
+
private looksLikeLog;
|
|
124
|
+
/**
|
|
125
|
+
* Routes one finished node's output values along its outgoing data edges,
|
|
126
|
+
* emitting edge-value and edge-state events per routed edge.
|
|
127
|
+
*
|
|
128
|
+
* @param nodeId - The finished node id.
|
|
129
|
+
* @param output - The node's output record.
|
|
130
|
+
* @param path - The node path the events are reported under.
|
|
131
|
+
* @returns Resolves once the routed edge events have been emitted.
|
|
132
|
+
*/
|
|
133
|
+
private routeEdges;
|
|
134
|
+
/**
|
|
135
|
+
* Emits a node visual-state change for the bridged run.
|
|
136
|
+
*
|
|
137
|
+
* @param nodeId - The node whose state changed.
|
|
138
|
+
* @param state - The new visual state.
|
|
139
|
+
* @param path - The node path the event is reported under.
|
|
140
|
+
* @returns Resolves once the event has been emitted.
|
|
141
|
+
*/
|
|
142
|
+
private emitNodeState;
|
|
143
|
+
/**
|
|
144
|
+
* Emits an edge visual-state change for the bridged run.
|
|
145
|
+
*
|
|
146
|
+
* @param edge - The edge whose state changed.
|
|
147
|
+
* @param state - The new visual state.
|
|
148
|
+
* @param status - The execution status carried by the event.
|
|
149
|
+
* @returns Resolves once the event has been emitted.
|
|
150
|
+
*/
|
|
151
|
+
private emitEdgeState;
|
|
152
|
+
/**
|
|
153
|
+
* Maps a visual state to the execution status its event carries.
|
|
154
|
+
*
|
|
155
|
+
* @param state - The node visual state.
|
|
156
|
+
* @returns The matching execution status.
|
|
157
|
+
*/
|
|
158
|
+
private statusFor;
|
|
159
|
+
/**
|
|
160
|
+
* Resolves the Mastra step id of an event (the canonical node id).
|
|
161
|
+
*
|
|
162
|
+
* @param event - The raw Mastra event.
|
|
163
|
+
* @returns The step id, or `undefined` when the event has none.
|
|
164
|
+
*/
|
|
165
|
+
private stepId;
|
|
166
|
+
/**
|
|
167
|
+
* Extracts an event's payload record, tolerating missing or non-object
|
|
168
|
+
* payloads.
|
|
169
|
+
*
|
|
170
|
+
* @param event - The raw Mastra event.
|
|
171
|
+
* @returns The payload record, or an empty record.
|
|
172
|
+
*/
|
|
173
|
+
private payloadOf;
|
|
174
|
+
/**
|
|
175
|
+
* Normalises an arbitrary error into the canonical error payload shape.
|
|
176
|
+
*
|
|
177
|
+
* @param error - The thrown error or value.
|
|
178
|
+
* @returns The normalised name/message/code payload.
|
|
179
|
+
*/
|
|
180
|
+
private errorPayload;
|
|
181
|
+
/**
|
|
182
|
+
* Forwards one canonical event onto the configured facade event sink.
|
|
183
|
+
*
|
|
184
|
+
* @param partial - The event to emit (run identity fields are supplied by
|
|
185
|
+
* the sink's frame awareness).
|
|
186
|
+
* @returns Resolves once the sink accepted the event.
|
|
187
|
+
*/
|
|
188
|
+
private emit;
|
|
189
|
+
}
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module as-graph/mastra/MastraGraphExecutionBackend
|
|
3
|
+
* @summary `@mastra/core`-translated graph execution backend (SAA-196).
|
|
4
|
+
* @description The Mastra analogue of the backend seam: translates the canonical
|
|
5
|
+
* document into a Mastra workflow, runs it through the injected Mastra runtime,
|
|
6
|
+
* bridges the run's `fullStream` onto the facade event sink, and enforces the
|
|
7
|
+
* SAA-193 resume guard conditions for suspended runs. The backend registers
|
|
8
|
+
* itself under the `mastra` flavour on construction and never probes remote
|
|
9
|
+
* engines.
|
|
10
|
+
*/
|
|
11
|
+
import type { Context, MaybeContextualArg } from "@decaf-ts/core";
|
|
12
|
+
import type { GraphWorkflowDocument } from "../shared/graph/document/GraphWorkflowDocument.d.cts";
|
|
13
|
+
import type { GraphBackendExecutionRequest, GraphBackendWorkflowSummary, GraphExecutionBackend } from "../engine/execution/GraphExecutionBackend.d.cts";
|
|
14
|
+
import type { GraphExecutionResult, GraphRunId } from "../engine/types.d.cts";
|
|
15
|
+
import { MastraWorkflowManager } from "./MastraWorkflowManager.d.cts";
|
|
16
|
+
import { type MastraBackendCapabilities } from "./MastraCapabilities.d.cts";
|
|
17
|
+
import { type MastraBackendConfig, type MastraResumeAudit, type MastraResumeRequest } from "./types.d.cts";
|
|
18
|
+
/**
|
|
19
|
+
* `@mastra/core`-translated execution backend (SAA-196). Translates the
|
|
20
|
+
* canonical document into a Mastra workflow, runs it through the injected Mastra
|
|
21
|
+
* runtime, bridges Mastra's `fullStream` onto the facade event sink, and enforces
|
|
22
|
+
* the SAA-193 resume guard conditions. Code-mode surfaces are not executed:
|
|
23
|
+
* `codeMode` is `unsupported`, so the facade fails closed before delegating.
|
|
24
|
+
*/
|
|
25
|
+
export declare class MastraGraphExecutionBackend implements GraphExecutionBackend<MastraBackendConfig> {
|
|
26
|
+
/** Translated backend: never executes in-process. */
|
|
27
|
+
readonly local = false;
|
|
28
|
+
/** Code-mode surfaces are rejected by the facade gate (C3). */
|
|
29
|
+
readonly codeMode: "unsupported";
|
|
30
|
+
private compiler;
|
|
31
|
+
private readonly documents;
|
|
32
|
+
private readonly runWorkflows;
|
|
33
|
+
private runtime?;
|
|
34
|
+
private managementManager?;
|
|
35
|
+
private suspendStateReader?;
|
|
36
|
+
private maxResumeBytes;
|
|
37
|
+
private initialized;
|
|
38
|
+
private _config?;
|
|
39
|
+
constructor();
|
|
40
|
+
initialize(config: MastraBackendConfig): Promise<void>;
|
|
41
|
+
get capabilities(): MastraBackendCapabilities;
|
|
42
|
+
/**
|
|
43
|
+
* The workflow-management surface over the wired real `@mastra/core` runtime
|
|
44
|
+
* (SAA-346). The manager translates canonical documents through the same
|
|
45
|
+
* compiler the backend executes with, so a created/updated workflow is the one
|
|
46
|
+
* `execute` runs. Every operation fails closed when the wired runtime exposes
|
|
47
|
+
* no real Mastra method.
|
|
48
|
+
*/
|
|
49
|
+
get management(): MastraWorkflowManager;
|
|
50
|
+
/**
|
|
51
|
+
* Lists the translated workflows visible to the requesting caller (C23). The
|
|
52
|
+
* catalogue is ownership-filtered with the same
|
|
53
|
+
* {@link canAccessGraphResource} predicate the service layer uses: a document
|
|
54
|
+
* executed by a named owner is visible only to that owner, an owner-less
|
|
55
|
+
* document stays visible to every caller, and an anonymous caller sees only
|
|
56
|
+
* owner-less documents. The caller owner is resolved from the forwarded
|
|
57
|
+
* contextual arguments; a missing context denies foreign-owner rows.
|
|
58
|
+
*
|
|
59
|
+
* @param args - Optional decaf contextual arguments carrying the caller principal.
|
|
60
|
+
* @returns Workflow summaries visible to the caller.
|
|
61
|
+
*/
|
|
62
|
+
listWorkflows(...args: MaybeContextualArg<Context>): Promise<GraphBackendWorkflowSummary[]>;
|
|
63
|
+
/**
|
|
64
|
+
* Reads a single translated workflow document, enforcing the C23 ownership
|
|
65
|
+
* predicate. An unknown id and a foreign-owner id both fail closed: an unknown
|
|
66
|
+
* id keeps the backend's existing translated-catalogue error, and a foreign-owner
|
|
67
|
+
* id is denied with a constant `NotFoundError` that maps to `404` and never
|
|
68
|
+
* carries `GraphExecutionError.details`, so a foreign caller cannot read
|
|
69
|
+
* another owner's canonical document.
|
|
70
|
+
*
|
|
71
|
+
* @param workflowId - The canonical workflow id to read.
|
|
72
|
+
* @param args - Optional decaf contextual arguments carrying the caller principal.
|
|
73
|
+
* @returns The canonical workflow document.
|
|
74
|
+
* @throws {GraphExecutionError} when no translated workflow exists for the id.
|
|
75
|
+
* @throws {NotFoundError} when the workflow is owned by another user.
|
|
76
|
+
*/
|
|
77
|
+
getWorkflow(workflowId: string, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
|
|
78
|
+
execute(request: GraphBackendExecutionRequest, ...args: MaybeContextualArg<Context>): Promise<GraphExecutionResult>;
|
|
79
|
+
/**
|
|
80
|
+
* Resumes a suspended Mastra run after enforcing the SAA-193 resume guard
|
|
81
|
+
* (C13/C15/C16/C17/C18). The Mastra run snapshot is authoritative for the
|
|
82
|
+
* suspended state; the current document fingerprint must match the snapshot
|
|
83
|
+
* (C17). Returns the C18 audit record, never the raw `resumeData`.
|
|
84
|
+
*/
|
|
85
|
+
resume(runId: GraphRunId, request: MastraResumeRequest, ..._args: MaybeContextualArg<Context>): Promise<MastraResumeAudit>;
|
|
86
|
+
/**
|
|
87
|
+
* Resolves the owner recorded for a run (C23). The facade-resolved principal
|
|
88
|
+
* bound onto `options.auth` is authoritative; when absent (a direct backend call)
|
|
89
|
+
* the owner is resolved from the forwarded contextual arguments. Returns
|
|
90
|
+
* `undefined` for owner-less runs, matching the service-layer owner-less
|
|
91
|
+
* visibility rule.
|
|
92
|
+
*
|
|
93
|
+
* @param request - The execution request carrying the facade-resolved options.
|
|
94
|
+
* @param args - The forwarded contextual arguments.
|
|
95
|
+
* @returns The run's owner, or `undefined` when owner-less.
|
|
96
|
+
*/
|
|
97
|
+
private callerOwnerOf;
|
|
98
|
+
/**
|
|
99
|
+
* Releases the per-run catalogue state (C23). Removes the run's workflow
|
|
100
|
+
* association and drops the translated document once no other live run still
|
|
101
|
+
* references it, so the process-lifetime catalogue cannot grow unbounded and
|
|
102
|
+
* widen the BOLA surface over time.
|
|
103
|
+
*
|
|
104
|
+
* @param runId - The completed run whose resources are released.
|
|
105
|
+
*/
|
|
106
|
+
release(runId: GraphRunId): Promise<void>;
|
|
107
|
+
dispose(): Promise<void>;
|
|
108
|
+
/**
|
|
109
|
+
* The configuration most recently resolved by {@link initialize}. Exposed so
|
|
110
|
+
* `GraphExecutionEngine.initialize` can merge its facade-owned collaborators
|
|
111
|
+
* over the host's keys (`mastra`, `stepHandlers`, `suspendStateReader`, ...)
|
|
112
|
+
* instead of dropping them when it re-initializes the backend at boot.
|
|
113
|
+
*/
|
|
114
|
+
get config(): MastraBackendConfig | undefined;
|
|
115
|
+
/** Whether {@link initialize} has resolved. */
|
|
116
|
+
get ready(): boolean;
|
|
117
|
+
private loadRun;
|
|
118
|
+
private errorPayload;
|
|
119
|
+
}
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module as-graph/mastra/MastraGraphExecutionBackend
|
|
3
|
+
* @summary `@mastra/core`-translated graph execution backend (SAA-196).
|
|
4
|
+
* @description The Mastra analogue of the backend seam: translates the canonical
|
|
5
|
+
* document into a Mastra workflow, runs it through the injected Mastra runtime,
|
|
6
|
+
* bridges the run's `fullStream` onto the facade event sink, and enforces the
|
|
7
|
+
* SAA-193 resume guard conditions for suspended runs. The backend registers
|
|
8
|
+
* itself under the `mastra` flavour on construction and never probes remote
|
|
9
|
+
* engines.
|
|
10
|
+
*/
|
|
11
|
+
import type { Context, MaybeContextualArg } from "@decaf-ts/core";
|
|
12
|
+
import type { GraphWorkflowDocument } from "../shared/graph/document/GraphWorkflowDocument.d.mts";
|
|
13
|
+
import type { GraphBackendExecutionRequest, GraphBackendWorkflowSummary, GraphExecutionBackend } from "../engine/execution/GraphExecutionBackend.d.mts";
|
|
14
|
+
import type { GraphExecutionResult, GraphRunId } from "../engine/types.d.mts";
|
|
15
|
+
import { MastraWorkflowManager } from "./MastraWorkflowManager.d.mts";
|
|
16
|
+
import { type MastraBackendCapabilities } from "./MastraCapabilities.d.mts";
|
|
17
|
+
import { type MastraBackendConfig, type MastraResumeAudit, type MastraResumeRequest } from "./types.d.mts";
|
|
18
|
+
/**
|
|
19
|
+
* `@mastra/core`-translated execution backend (SAA-196). Translates the
|
|
20
|
+
* canonical document into a Mastra workflow, runs it through the injected Mastra
|
|
21
|
+
* runtime, bridges Mastra's `fullStream` onto the facade event sink, and enforces
|
|
22
|
+
* the SAA-193 resume guard conditions. Code-mode surfaces are not executed:
|
|
23
|
+
* `codeMode` is `unsupported`, so the facade fails closed before delegating.
|
|
24
|
+
*/
|
|
25
|
+
export declare class MastraGraphExecutionBackend implements GraphExecutionBackend<MastraBackendConfig> {
|
|
26
|
+
/** Translated backend: never executes in-process. */
|
|
27
|
+
readonly local = false;
|
|
28
|
+
/** Code-mode surfaces are rejected by the facade gate (C3). */
|
|
29
|
+
readonly codeMode: "unsupported";
|
|
30
|
+
private compiler;
|
|
31
|
+
private readonly documents;
|
|
32
|
+
private readonly runWorkflows;
|
|
33
|
+
private runtime?;
|
|
34
|
+
private managementManager?;
|
|
35
|
+
private suspendStateReader?;
|
|
36
|
+
private maxResumeBytes;
|
|
37
|
+
private initialized;
|
|
38
|
+
private _config?;
|
|
39
|
+
constructor();
|
|
40
|
+
initialize(config: MastraBackendConfig): Promise<void>;
|
|
41
|
+
get capabilities(): MastraBackendCapabilities;
|
|
42
|
+
/**
|
|
43
|
+
* The workflow-management surface over the wired real `@mastra/core` runtime
|
|
44
|
+
* (SAA-346). The manager translates canonical documents through the same
|
|
45
|
+
* compiler the backend executes with, so a created/updated workflow is the one
|
|
46
|
+
* `execute` runs. Every operation fails closed when the wired runtime exposes
|
|
47
|
+
* no real Mastra method.
|
|
48
|
+
*/
|
|
49
|
+
get management(): MastraWorkflowManager;
|
|
50
|
+
/**
|
|
51
|
+
* Lists the translated workflows visible to the requesting caller (C23). The
|
|
52
|
+
* catalogue is ownership-filtered with the same
|
|
53
|
+
* {@link canAccessGraphResource} predicate the service layer uses: a document
|
|
54
|
+
* executed by a named owner is visible only to that owner, an owner-less
|
|
55
|
+
* document stays visible to every caller, and an anonymous caller sees only
|
|
56
|
+
* owner-less documents. The caller owner is resolved from the forwarded
|
|
57
|
+
* contextual arguments; a missing context denies foreign-owner rows.
|
|
58
|
+
*
|
|
59
|
+
* @param args - Optional decaf contextual arguments carrying the caller principal.
|
|
60
|
+
* @returns Workflow summaries visible to the caller.
|
|
61
|
+
*/
|
|
62
|
+
listWorkflows(...args: MaybeContextualArg<Context>): Promise<GraphBackendWorkflowSummary[]>;
|
|
63
|
+
/**
|
|
64
|
+
* Reads a single translated workflow document, enforcing the C23 ownership
|
|
65
|
+
* predicate. An unknown id and a foreign-owner id both fail closed: an unknown
|
|
66
|
+
* id keeps the backend's existing translated-catalogue error, and a foreign-owner
|
|
67
|
+
* id is denied with a constant `NotFoundError` that maps to `404` and never
|
|
68
|
+
* carries `GraphExecutionError.details`, so a foreign caller cannot read
|
|
69
|
+
* another owner's canonical document.
|
|
70
|
+
*
|
|
71
|
+
* @param workflowId - The canonical workflow id to read.
|
|
72
|
+
* @param args - Optional decaf contextual arguments carrying the caller principal.
|
|
73
|
+
* @returns The canonical workflow document.
|
|
74
|
+
* @throws {GraphExecutionError} when no translated workflow exists for the id.
|
|
75
|
+
* @throws {NotFoundError} when the workflow is owned by another user.
|
|
76
|
+
*/
|
|
77
|
+
getWorkflow(workflowId: string, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
|
|
78
|
+
execute(request: GraphBackendExecutionRequest, ...args: MaybeContextualArg<Context>): Promise<GraphExecutionResult>;
|
|
79
|
+
/**
|
|
80
|
+
* Resumes a suspended Mastra run after enforcing the SAA-193 resume guard
|
|
81
|
+
* (C13/C15/C16/C17/C18). The Mastra run snapshot is authoritative for the
|
|
82
|
+
* suspended state; the current document fingerprint must match the snapshot
|
|
83
|
+
* (C17). Returns the C18 audit record, never the raw `resumeData`.
|
|
84
|
+
*/
|
|
85
|
+
resume(runId: GraphRunId, request: MastraResumeRequest, ..._args: MaybeContextualArg<Context>): Promise<MastraResumeAudit>;
|
|
86
|
+
/**
|
|
87
|
+
* Resolves the owner recorded for a run (C23). The facade-resolved principal
|
|
88
|
+
* bound onto `options.auth` is authoritative; when absent (a direct backend call)
|
|
89
|
+
* the owner is resolved from the forwarded contextual arguments. Returns
|
|
90
|
+
* `undefined` for owner-less runs, matching the service-layer owner-less
|
|
91
|
+
* visibility rule.
|
|
92
|
+
*
|
|
93
|
+
* @param request - The execution request carrying the facade-resolved options.
|
|
94
|
+
* @param args - The forwarded contextual arguments.
|
|
95
|
+
* @returns The run's owner, or `undefined` when owner-less.
|
|
96
|
+
*/
|
|
97
|
+
private callerOwnerOf;
|
|
98
|
+
/**
|
|
99
|
+
* Releases the per-run catalogue state (C23). Removes the run's workflow
|
|
100
|
+
* association and drops the translated document once no other live run still
|
|
101
|
+
* references it, so the process-lifetime catalogue cannot grow unbounded and
|
|
102
|
+
* widen the BOLA surface over time.
|
|
103
|
+
*
|
|
104
|
+
* @param runId - The completed run whose resources are released.
|
|
105
|
+
*/
|
|
106
|
+
release(runId: GraphRunId): Promise<void>;
|
|
107
|
+
dispose(): Promise<void>;
|
|
108
|
+
/**
|
|
109
|
+
* The configuration most recently resolved by {@link initialize}. Exposed so
|
|
110
|
+
* `GraphExecutionEngine.initialize` can merge its facade-owned collaborators
|
|
111
|
+
* over the host's keys (`mastra`, `stepHandlers`, `suspendStateReader`, ...)
|
|
112
|
+
* instead of dropping them when it re-initializes the backend at boot.
|
|
113
|
+
*/
|
|
114
|
+
get config(): MastraBackendConfig | undefined;
|
|
115
|
+
/** Whether {@link initialize} has resolved. */
|
|
116
|
+
get ready(): boolean;
|
|
117
|
+
private loadRun;
|
|
118
|
+
private errorPayload;
|
|
119
|
+
}
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { type MastraResumeAudit, type MastraResumeRequest } from "./types.d.cts";
|
|
2
|
+
/**
|
|
3
|
+
* Mastra-authoritative snapshot a suspended run resumes from. Mastra owns the
|
|
4
|
+
* execution state for a suspended workflow (gap-1): this snapshot is the single
|
|
5
|
+
* source of truth for resume, never `GraphRunStore`.
|
|
6
|
+
*/
|
|
7
|
+
export interface MastraResumeSnapshot {
|
|
8
|
+
/** Canonical run id. */
|
|
9
|
+
runId: string;
|
|
10
|
+
/** Canonical workflow id. */
|
|
11
|
+
workflowId: string;
|
|
12
|
+
/** Fingerprint of the document the run was launched from. */
|
|
13
|
+
documentFingerprint: string;
|
|
14
|
+
/** Mastra run status; resume is only legal from `suspended`. */
|
|
15
|
+
status: string;
|
|
16
|
+
/** Mastra step id the run suspended on. */
|
|
17
|
+
step: string;
|
|
18
|
+
/** Per-iteration index when the suspension happened inside a `foreach`. */
|
|
19
|
+
forEachIndex?: number;
|
|
20
|
+
/** Total iteration count when the suspension happened inside a `foreach`. */
|
|
21
|
+
forEachCount?: number;
|
|
22
|
+
/** Mastra serialized execution state (opaque, engine-authoritative). */
|
|
23
|
+
state: unknown;
|
|
24
|
+
}
|
|
25
|
+
export interface MastraResumeGuardOptions {
|
|
26
|
+
/** Maximum serialised size, in bytes, of accepted `resumeData`. */
|
|
27
|
+
maxResumeBytes: number;
|
|
28
|
+
/** Node ids the current document declares as resumable. */
|
|
29
|
+
allowlistedSteps: readonly string[];
|
|
30
|
+
/** Fingerprint of the current document. */
|
|
31
|
+
documentFingerprint: string;
|
|
32
|
+
/**
|
|
33
|
+
* Declared resume schema of the suspended node. When present, `resumeData`
|
|
34
|
+
* must validate against it (C15).
|
|
35
|
+
*/
|
|
36
|
+
resumeSchema?: {
|
|
37
|
+
safeParse(value: unknown): {
|
|
38
|
+
success: boolean;
|
|
39
|
+
};
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Validates an untrusted resume request against the Mastra-authoritative
|
|
44
|
+
* snapshot and the current document, enforcing C13/C15/C16/C17 before any state
|
|
45
|
+
* is handed back to Mastra. On success it returns the C18 audit record; the raw
|
|
46
|
+
* `resumeData` is never logged or echoed.
|
|
47
|
+
*
|
|
48
|
+
* @param request - The untrusted resume request to validate.
|
|
49
|
+
* @param snapshot - The Mastra-authoritative suspended-run snapshot.
|
|
50
|
+
* @param options - Document-derived validation options (byte cap, allowlist,
|
|
51
|
+
* fingerprint, and the suspended step's resume schema).
|
|
52
|
+
* @returns The C18 audit record for the accepted resume.
|
|
53
|
+
* @throws {GraphExecutionError} `GRAPH_MASTRA_RESUME_INVALID` for non-JSON-safe or
|
|
54
|
+
* oversized `resumeData`; `GRAPH_MASTRA_RESUME_STEP_UNKNOWN` when the suspended
|
|
55
|
+
* step or iteration is not allowlisted; `GRAPH_MASTRA_RESUME_STATE_INVALID`
|
|
56
|
+
* when the snapshot is not suspended or its fingerprint does not match.
|
|
57
|
+
*/
|
|
58
|
+
export declare function assertMastraResumeAllowed(request: MastraResumeRequest, snapshot: MastraResumeSnapshot, options: MastraResumeGuardOptions): MastraResumeAudit;
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { type MastraResumeAudit, type MastraResumeRequest } from "./types.d.mts";
|
|
2
|
+
/**
|
|
3
|
+
* Mastra-authoritative snapshot a suspended run resumes from. Mastra owns the
|
|
4
|
+
* execution state for a suspended workflow (gap-1): this snapshot is the single
|
|
5
|
+
* source of truth for resume, never `GraphRunStore`.
|
|
6
|
+
*/
|
|
7
|
+
export interface MastraResumeSnapshot {
|
|
8
|
+
/** Canonical run id. */
|
|
9
|
+
runId: string;
|
|
10
|
+
/** Canonical workflow id. */
|
|
11
|
+
workflowId: string;
|
|
12
|
+
/** Fingerprint of the document the run was launched from. */
|
|
13
|
+
documentFingerprint: string;
|
|
14
|
+
/** Mastra run status; resume is only legal from `suspended`. */
|
|
15
|
+
status: string;
|
|
16
|
+
/** Mastra step id the run suspended on. */
|
|
17
|
+
step: string;
|
|
18
|
+
/** Per-iteration index when the suspension happened inside a `foreach`. */
|
|
19
|
+
forEachIndex?: number;
|
|
20
|
+
/** Total iteration count when the suspension happened inside a `foreach`. */
|
|
21
|
+
forEachCount?: number;
|
|
22
|
+
/** Mastra serialized execution state (opaque, engine-authoritative). */
|
|
23
|
+
state: unknown;
|
|
24
|
+
}
|
|
25
|
+
export interface MastraResumeGuardOptions {
|
|
26
|
+
/** Maximum serialised size, in bytes, of accepted `resumeData`. */
|
|
27
|
+
maxResumeBytes: number;
|
|
28
|
+
/** Node ids the current document declares as resumable. */
|
|
29
|
+
allowlistedSteps: readonly string[];
|
|
30
|
+
/** Fingerprint of the current document. */
|
|
31
|
+
documentFingerprint: string;
|
|
32
|
+
/**
|
|
33
|
+
* Declared resume schema of the suspended node. When present, `resumeData`
|
|
34
|
+
* must validate against it (C15).
|
|
35
|
+
*/
|
|
36
|
+
resumeSchema?: {
|
|
37
|
+
safeParse(value: unknown): {
|
|
38
|
+
success: boolean;
|
|
39
|
+
};
|
|
40
|
+
};
|
|
41
|
+
}
|
|
42
|
+
/**
|
|
43
|
+
* Validates an untrusted resume request against the Mastra-authoritative
|
|
44
|
+
* snapshot and the current document, enforcing C13/C15/C16/C17 before any state
|
|
45
|
+
* is handed back to Mastra. On success it returns the C18 audit record; the raw
|
|
46
|
+
* `resumeData` is never logged or echoed.
|
|
47
|
+
*
|
|
48
|
+
* @param request - The untrusted resume request to validate.
|
|
49
|
+
* @param snapshot - The Mastra-authoritative suspended-run snapshot.
|
|
50
|
+
* @param options - Document-derived validation options (byte cap, allowlist,
|
|
51
|
+
* fingerprint, and the suspended step's resume schema).
|
|
52
|
+
* @returns The C18 audit record for the accepted resume.
|
|
53
|
+
* @throws {GraphExecutionError} `GRAPH_MASTRA_RESUME_INVALID` for non-JSON-safe or
|
|
54
|
+
* oversized `resumeData`; `GRAPH_MASTRA_RESUME_STEP_UNKNOWN` when the suspended
|
|
55
|
+
* step or iteration is not allowlisted; `GRAPH_MASTRA_RESUME_STATE_INVALID`
|
|
56
|
+
* when the snapshot is not suspended or its fingerprint does not match.
|
|
57
|
+
*/
|
|
58
|
+
export declare function assertMastraResumeAllowed(request: MastraResumeRequest, snapshot: MastraResumeSnapshot, options: MastraResumeGuardOptions): MastraResumeAudit;
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module as-graph/mastra/MastraSchemaConverter
|
|
3
|
+
* @summary Converts canonical {@link GraphValueSchema} declarations into Zod
|
|
4
|
+
* schemas for the Mastra backend (SAA-196).
|
|
5
|
+
* @description Mastra workflows are built on Zod schemas. The converter maps
|
|
6
|
+
* every canonical schema shape to its closest Zod equivalent, tracking whether
|
|
7
|
+
* the conversion degraded (or collapsed to `any`), so suspendable steps can be
|
|
8
|
+
* required to declare a strict, non-degraded resume schema before translation.
|
|
9
|
+
*/
|
|
10
|
+
import { z } from "zod";
|
|
11
|
+
import type { GraphValueSchema } from "../shared/graph/catalog/GraphValueSchema.d.cts";
|
|
12
|
+
/** Result of converting one canonical schema into a Zod schema. */
|
|
13
|
+
export interface MastraZodConversion {
|
|
14
|
+
/** The converted Zod schema (an `any` schema when degraded). */
|
|
15
|
+
schema: z.ZodTypeAny;
|
|
16
|
+
/** Whether any part of the canonical schema could not be represented. */
|
|
17
|
+
degraded: boolean;
|
|
18
|
+
/** Whether the whole conversion collapsed to a permissive `any` schema. */
|
|
19
|
+
any: boolean;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Converts a canonical schema (or the absence of one) into a Zod schema.
|
|
23
|
+
* A missing schema converts to a degraded `any` schema.
|
|
24
|
+
*
|
|
25
|
+
* @param schema - The canonical schema to convert, if declared.
|
|
26
|
+
* @returns The conversion result with its degradation flags.
|
|
27
|
+
*/
|
|
28
|
+
export declare function toMastraZodSchema(schema: GraphValueSchema | undefined): MastraZodConversion;
|
|
29
|
+
/**
|
|
30
|
+
* Requires that a suspendable Mastra step declares a strict resume schema: the
|
|
31
|
+
* conversion must be neither degraded nor collapsed to `any`, otherwise resume
|
|
32
|
+
* payloads could not be validated (C15).
|
|
33
|
+
*
|
|
34
|
+
* @param schema - The declared resume schema of the suspended step.
|
|
35
|
+
* @returns The validated Zod resume schema.
|
|
36
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_RESUME_SCHEMA_UNSAFE} when
|
|
37
|
+
* the schema is missing, degraded, or collapsed to `any`.
|
|
38
|
+
*/
|
|
39
|
+
export declare function assertMastraResumeSchemaSafe(schema: GraphValueSchema | undefined): z.ZodTypeAny;
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module as-graph/mastra/MastraSchemaConverter
|
|
3
|
+
* @summary Converts canonical {@link GraphValueSchema} declarations into Zod
|
|
4
|
+
* schemas for the Mastra backend (SAA-196).
|
|
5
|
+
* @description Mastra workflows are built on Zod schemas. The converter maps
|
|
6
|
+
* every canonical schema shape to its closest Zod equivalent, tracking whether
|
|
7
|
+
* the conversion degraded (or collapsed to `any`), so suspendable steps can be
|
|
8
|
+
* required to declare a strict, non-degraded resume schema before translation.
|
|
9
|
+
*/
|
|
10
|
+
import { z } from "zod";
|
|
11
|
+
import type { GraphValueSchema } from "../shared/graph/catalog/GraphValueSchema.d.mts";
|
|
12
|
+
/** Result of converting one canonical schema into a Zod schema. */
|
|
13
|
+
export interface MastraZodConversion {
|
|
14
|
+
/** The converted Zod schema (an `any` schema when degraded). */
|
|
15
|
+
schema: z.ZodTypeAny;
|
|
16
|
+
/** Whether any part of the canonical schema could not be represented. */
|
|
17
|
+
degraded: boolean;
|
|
18
|
+
/** Whether the whole conversion collapsed to a permissive `any` schema. */
|
|
19
|
+
any: boolean;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Converts a canonical schema (or the absence of one) into a Zod schema.
|
|
23
|
+
* A missing schema converts to a degraded `any` schema.
|
|
24
|
+
*
|
|
25
|
+
* @param schema - The canonical schema to convert, if declared.
|
|
26
|
+
* @returns The conversion result with its degradation flags.
|
|
27
|
+
*/
|
|
28
|
+
export declare function toMastraZodSchema(schema: GraphValueSchema | undefined): MastraZodConversion;
|
|
29
|
+
/**
|
|
30
|
+
* Requires that a suspendable Mastra step declares a strict resume schema: the
|
|
31
|
+
* conversion must be neither degraded nor collapsed to `any`, otherwise resume
|
|
32
|
+
* payloads could not be validated (C15).
|
|
33
|
+
*
|
|
34
|
+
* @param schema - The declared resume schema of the suspended step.
|
|
35
|
+
* @returns The validated Zod resume schema.
|
|
36
|
+
* @throws {GraphExecutionError} {@link GRAPH_MASTRA_RESUME_SCHEMA_UNSAFE} when
|
|
37
|
+
* the schema is missing, degraded, or collapsed to `any`.
|
|
38
|
+
*/
|
|
39
|
+
export declare function assertMastraResumeSchemaSafe(schema: GraphValueSchema | undefined): z.ZodTypeAny;
|