@decaf-ts/as-graph 0.5.0 → 0.6.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 +59 -13
- 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/DagsterGraphExecutionBackend.cjs +102 -11
- package/lib/cjs/dagster/DagsterGraphExecutionBackend.cjs.map +1 -1
- package/lib/cjs/engine/execution/GraphExecutionEngine.cjs +7 -0
- package/lib/cjs/engine/execution/GraphExecutionEngine.cjs.map +1 -1
- package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs +39 -0
- package/lib/cjs/engine/execution/LocalGraphExecutionBackend.cjs.map +1 -1
- package/lib/cjs/engine/index.cjs +1 -0
- package/lib/cjs/engine/index.cjs.map +1 -1
- package/lib/cjs/engine/services/GraphNodeModelService.cjs +129 -0
- package/lib/cjs/engine/services/GraphNodeModelService.cjs.map +1 -0
- package/lib/cjs/engine/services/GraphWorkflowService.cjs +33 -0
- package/lib/cjs/engine/services/GraphWorkflowService.cjs.map +1 -1
- package/lib/cjs/mastra/MastraDefaultStepHandlers.cjs +217 -0
- package/lib/cjs/mastra/MastraDefaultStepHandlers.cjs.map +1 -0
- package/lib/cjs/mastra/MastraEventBridge.cjs +10 -3
- package/lib/cjs/mastra/MastraEventBridge.cjs.map +1 -1
- package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs +111 -13
- package/lib/cjs/mastra/MastraGraphExecutionBackend.cjs.map +1 -1
- package/lib/cjs/mastra/MastraWorkflowCompiler.cjs +3 -3
- package/lib/cjs/mastra/MastraWorkflowCompiler.cjs.map +1 -1
- package/lib/cjs/mastra/index.cjs +1 -0
- package/lib/cjs/mastra/index.cjs.map +1 -1
- package/lib/cjs/mastra/types.cjs +5 -1
- package/lib/cjs/mastra/types.cjs.map +1 -1
- package/lib/cjs/nest/graph/GraphBackendHost.cjs +105 -19
- package/lib/cjs/nest/graph/GraphBackendHost.cjs.map +1 -1
- package/lib/cjs/nest/graph/GraphExecutionModule.cjs +37 -1
- package/lib/cjs/nest/graph/GraphExecutionModule.cjs.map +1 -1
- package/lib/cjs/nest/graph/main.cjs +16 -1
- package/lib/cjs/nest/graph/main.cjs.map +1 -1
- package/lib/cjs/ram/GraphNodeRepository.cjs +40 -0
- package/lib/cjs/ram/GraphNodeRepository.cjs.map +1 -0
- package/lib/cjs/ram/index.cjs +1 -0
- package/lib/cjs/ram/index.cjs.map +1 -1
- package/lib/cjs/shared/graph/GraphNodeConverters.cjs +43 -0
- package/lib/cjs/shared/graph/GraphNodeConverters.cjs.map +1 -0
- package/lib/cjs/shared/graph/GraphNodeModel.cjs +74 -0
- package/lib/cjs/shared/graph/GraphNodeModel.cjs.map +1 -0
- package/lib/cjs/shared/graph/index.cjs +2 -0
- package/lib/cjs/shared/graph/index.cjs.map +1 -1
- package/lib/esm/dagster/DagsterGraphExecutionBackend.js +102 -11
- package/lib/esm/dagster/DagsterGraphExecutionBackend.js.map +1 -1
- package/lib/esm/engine/execution/GraphExecutionBackend.js.map +1 -1
- package/lib/esm/engine/execution/GraphExecutionEngine.js +7 -0
- package/lib/esm/engine/execution/GraphExecutionEngine.js.map +1 -1
- package/lib/esm/engine/execution/LocalGraphExecutionBackend.js +39 -0
- package/lib/esm/engine/execution/LocalGraphExecutionBackend.js.map +1 -1
- package/lib/esm/engine/index.js +1 -0
- package/lib/esm/engine/index.js.map +1 -1
- package/lib/esm/engine/services/GraphNodeModelService.js +120 -0
- package/lib/esm/engine/services/GraphNodeModelService.js.map +1 -0
- package/lib/esm/engine/services/GraphWorkflowService.js +34 -1
- package/lib/esm/engine/services/GraphWorkflowService.js.map +1 -1
- package/lib/esm/mastra/MastraDefaultStepHandlers.js +212 -0
- package/lib/esm/mastra/MastraDefaultStepHandlers.js.map +1 -0
- package/lib/esm/mastra/MastraEventBridge.js +10 -3
- package/lib/esm/mastra/MastraEventBridge.js.map +1 -1
- package/lib/esm/mastra/MastraGraphExecutionBackend.js +112 -14
- package/lib/esm/mastra/MastraGraphExecutionBackend.js.map +1 -1
- package/lib/esm/mastra/MastraWorkflowCompiler.js +3 -3
- package/lib/esm/mastra/MastraWorkflowCompiler.js.map +1 -1
- package/lib/esm/mastra/index.js +1 -0
- package/lib/esm/mastra/index.js.map +1 -1
- package/lib/esm/mastra/types.js +4 -0
- package/lib/esm/mastra/types.js.map +1 -1
- package/lib/esm/nest/graph/GraphBackendHost.js +69 -18
- package/lib/esm/nest/graph/GraphBackendHost.js.map +1 -1
- package/lib/esm/nest/graph/GraphExecutionModule.js +38 -2
- package/lib/esm/nest/graph/GraphExecutionModule.js.map +1 -1
- package/lib/esm/nest/graph/main.js +17 -2
- package/lib/esm/nest/graph/main.js.map +1 -1
- package/lib/esm/ram/GraphNodeRepository.js +31 -0
- package/lib/esm/ram/GraphNodeRepository.js.map +1 -0
- package/lib/esm/ram/index.js +1 -0
- package/lib/esm/ram/index.js.map +1 -1
- package/lib/esm/shared/graph/GraphNodeConverters.js +38 -0
- package/lib/esm/shared/graph/GraphNodeConverters.js.map +1 -0
- package/lib/esm/shared/graph/GraphNodeModel.js +65 -0
- package/lib/esm/shared/graph/GraphNodeModel.js.map +1 -0
- package/lib/esm/shared/graph/index.js +2 -0
- package/lib/esm/shared/graph/index.js.map +1 -1
- package/lib/types/dagster/DagsterGraphExecutionBackend.d.cts +40 -4
- package/lib/types/dagster/DagsterGraphExecutionBackend.d.mts +40 -4
- package/lib/types/engine/execution/GraphExecutionBackend.d.cts +27 -0
- package/lib/types/engine/execution/GraphExecutionBackend.d.mts +27 -0
- package/lib/types/engine/execution/GraphExecutionEngine.d.cts +9 -0
- package/lib/types/engine/execution/GraphExecutionEngine.d.mts +9 -0
- package/lib/types/engine/execution/LocalGraphExecutionBackend.d.cts +14 -0
- package/lib/types/engine/execution/LocalGraphExecutionBackend.d.mts +14 -0
- package/lib/types/engine/index.d.cts +1 -0
- package/lib/types/engine/index.d.mts +1 -0
- package/lib/types/engine/services/GraphNodeModelService.d.cts +54 -0
- package/lib/types/engine/services/GraphNodeModelService.d.mts +54 -0
- package/lib/types/engine/services/GraphWorkflowService.d.cts +21 -0
- package/lib/types/engine/services/GraphWorkflowService.d.mts +21 -0
- package/lib/types/mastra/MastraDefaultStepHandlers.d.cts +74 -0
- package/lib/types/mastra/MastraDefaultStepHandlers.d.mts +74 -0
- package/lib/types/mastra/MastraGraphExecutionBackend.d.cts +29 -0
- package/lib/types/mastra/MastraGraphExecutionBackend.d.mts +29 -0
- package/lib/types/mastra/MastraWorkflowCompiler.d.cts +3 -3
- package/lib/types/mastra/MastraWorkflowCompiler.d.mts +3 -3
- package/lib/types/mastra/index.d.cts +1 -0
- package/lib/types/mastra/index.d.mts +1 -0
- package/lib/types/mastra/types.d.cts +12 -0
- package/lib/types/mastra/types.d.mts +12 -0
- package/lib/types/nest/graph/GraphBackendHost.d.cts +52 -0
- package/lib/types/nest/graph/GraphBackendHost.d.mts +52 -0
- package/lib/types/nest/graph/GraphExecutionModule.d.cts +11 -0
- package/lib/types/nest/graph/GraphExecutionModule.d.mts +11 -0
- package/lib/types/ram/GraphNodeRepository.d.cts +13 -0
- package/lib/types/ram/GraphNodeRepository.d.mts +13 -0
- package/lib/types/ram/index.d.cts +1 -0
- package/lib/types/ram/index.d.mts +1 -0
- package/lib/types/shared/graph/GraphNodeConverters.d.cts +15 -0
- package/lib/types/shared/graph/GraphNodeConverters.d.mts +15 -0
- package/lib/types/shared/graph/GraphNodeModel.d.cts +24 -0
- package/lib/types/shared/graph/GraphNodeModel.d.mts +24 -0
- package/lib/types/shared/graph/index.d.cts +2 -0
- package/lib/types/shared/graph/index.d.mts +2 -0
- package/package.json +9 -3
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import { ModelService, type Context, type MaybeContextualArg } from "@decaf-ts/core";
|
|
2
|
+
import { GraphNodeModel } from "../../shared/graph/index.d.cts";
|
|
3
|
+
import type { GraphNodeManifest } from "../../shared/graph/index.d.cts";
|
|
4
|
+
import type { GraphNodeCatalogue } from "../catalog/GraphNodeCatalogue.d.cts";
|
|
5
|
+
/**
|
|
6
|
+
* Model-backed node catalogue: persists {@link GraphNodeManifest} rows as
|
|
7
|
+
* {@link GraphNodeModel} via the Decaf {@link ModelService}.
|
|
8
|
+
*/
|
|
9
|
+
export declare class GraphNodeModelService extends ModelService<GraphNodeModel> {
|
|
10
|
+
constructor();
|
|
11
|
+
/**
|
|
12
|
+
* Upserts a single node-kind manifest as a {@link GraphNodeModel} row,
|
|
13
|
+
* updating the mirror columns and manifest when the row already exists.
|
|
14
|
+
*
|
|
15
|
+
* @param {GraphNodeManifest} manifest - Node-kind manifest to persist.
|
|
16
|
+
* @param args - An optional decaf `Context` forwarded to the model service.
|
|
17
|
+
* @return {Promise<GraphNodeModel>} The persisted row.
|
|
18
|
+
*/
|
|
19
|
+
upsertManifest(manifest: GraphNodeManifest, ...args: MaybeContextualArg<Context>): Promise<GraphNodeModel>;
|
|
20
|
+
/**
|
|
21
|
+
* Synchronises the whole catalogue into persistence, upserting every listed
|
|
22
|
+
* manifest so listing/CRUD works out of the box for the engine driver.
|
|
23
|
+
*
|
|
24
|
+
* @param {GraphNodeCatalogue} catalogue - Catalogue to mirror into persistence.
|
|
25
|
+
* @param args - An optional decaf `Context` forwarded to the model service.
|
|
26
|
+
* @return {Promise<GraphNodeModel[]>} The persisted rows, in catalogue order.
|
|
27
|
+
*/
|
|
28
|
+
syncFromCatalogue(catalogue: GraphNodeCatalogue, ...args: MaybeContextualArg<Context>): Promise<GraphNodeModel[]>;
|
|
29
|
+
/**
|
|
30
|
+
* Lists every persisted node-kind row, ordered by kind.
|
|
31
|
+
*
|
|
32
|
+
* A store failure propagates instead of being swallowed as `[]` (SAA-93 F4).
|
|
33
|
+
*
|
|
34
|
+
* @param args - An optional decaf `Context` forwarded to the model service.
|
|
35
|
+
* @return {Promise<GraphNodeModel[]>} The persisted rows.
|
|
36
|
+
*/
|
|
37
|
+
listNodes(...args: MaybeContextualArg<Context>): Promise<GraphNodeModel[]>;
|
|
38
|
+
/**
|
|
39
|
+
* Lists every persisted node-kind manifest, ordered by kind.
|
|
40
|
+
*
|
|
41
|
+
* @param args - An optional decaf `Context` forwarded to the model service.
|
|
42
|
+
* @return {Promise<GraphNodeManifest[]>} The persisted manifests.
|
|
43
|
+
*/
|
|
44
|
+
listManifests(...args: MaybeContextualArg<Context>): Promise<GraphNodeManifest[]>;
|
|
45
|
+
/**
|
|
46
|
+
* Reads the persisted row for a node kind.
|
|
47
|
+
*
|
|
48
|
+
* @param {string} kind - Registered node kind to read.
|
|
49
|
+
* @param args - An optional decaf `Context` forwarded to the model service.
|
|
50
|
+
* @return {Promise<GraphNodeModel>} The persisted row.
|
|
51
|
+
* @throws {NotFoundError} When no row exists for `kind`.
|
|
52
|
+
*/
|
|
53
|
+
getNode(kind: string, ...args: MaybeContextualArg<Context>): Promise<GraphNodeModel>;
|
|
54
|
+
}
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import { ModelService, type Context, type MaybeContextualArg } from "@decaf-ts/core";
|
|
2
|
+
import { GraphNodeModel } from "../../shared/graph/index.d.mts";
|
|
3
|
+
import type { GraphNodeManifest } from "../../shared/graph/index.d.mts";
|
|
4
|
+
import type { GraphNodeCatalogue } from "../catalog/GraphNodeCatalogue.d.mts";
|
|
5
|
+
/**
|
|
6
|
+
* Model-backed node catalogue: persists {@link GraphNodeManifest} rows as
|
|
7
|
+
* {@link GraphNodeModel} via the Decaf {@link ModelService}.
|
|
8
|
+
*/
|
|
9
|
+
export declare class GraphNodeModelService extends ModelService<GraphNodeModel> {
|
|
10
|
+
constructor();
|
|
11
|
+
/**
|
|
12
|
+
* Upserts a single node-kind manifest as a {@link GraphNodeModel} row,
|
|
13
|
+
* updating the mirror columns and manifest when the row already exists.
|
|
14
|
+
*
|
|
15
|
+
* @param {GraphNodeManifest} manifest - Node-kind manifest to persist.
|
|
16
|
+
* @param args - An optional decaf `Context` forwarded to the model service.
|
|
17
|
+
* @return {Promise<GraphNodeModel>} The persisted row.
|
|
18
|
+
*/
|
|
19
|
+
upsertManifest(manifest: GraphNodeManifest, ...args: MaybeContextualArg<Context>): Promise<GraphNodeModel>;
|
|
20
|
+
/**
|
|
21
|
+
* Synchronises the whole catalogue into persistence, upserting every listed
|
|
22
|
+
* manifest so listing/CRUD works out of the box for the engine driver.
|
|
23
|
+
*
|
|
24
|
+
* @param {GraphNodeCatalogue} catalogue - Catalogue to mirror into persistence.
|
|
25
|
+
* @param args - An optional decaf `Context` forwarded to the model service.
|
|
26
|
+
* @return {Promise<GraphNodeModel[]>} The persisted rows, in catalogue order.
|
|
27
|
+
*/
|
|
28
|
+
syncFromCatalogue(catalogue: GraphNodeCatalogue, ...args: MaybeContextualArg<Context>): Promise<GraphNodeModel[]>;
|
|
29
|
+
/**
|
|
30
|
+
* Lists every persisted node-kind row, ordered by kind.
|
|
31
|
+
*
|
|
32
|
+
* A store failure propagates instead of being swallowed as `[]` (SAA-93 F4).
|
|
33
|
+
*
|
|
34
|
+
* @param args - An optional decaf `Context` forwarded to the model service.
|
|
35
|
+
* @return {Promise<GraphNodeModel[]>} The persisted rows.
|
|
36
|
+
*/
|
|
37
|
+
listNodes(...args: MaybeContextualArg<Context>): Promise<GraphNodeModel[]>;
|
|
38
|
+
/**
|
|
39
|
+
* Lists every persisted node-kind manifest, ordered by kind.
|
|
40
|
+
*
|
|
41
|
+
* @param args - An optional decaf `Context` forwarded to the model service.
|
|
42
|
+
* @return {Promise<GraphNodeManifest[]>} The persisted manifests.
|
|
43
|
+
*/
|
|
44
|
+
listManifests(...args: MaybeContextualArg<Context>): Promise<GraphNodeManifest[]>;
|
|
45
|
+
/**
|
|
46
|
+
* Reads the persisted row for a node kind.
|
|
47
|
+
*
|
|
48
|
+
* @param {string} kind - Registered node kind to read.
|
|
49
|
+
* @param args - An optional decaf `Context` forwarded to the model service.
|
|
50
|
+
* @return {Promise<GraphNodeModel>} The persisted row.
|
|
51
|
+
* @throws {NotFoundError} When no row exists for `kind`.
|
|
52
|
+
*/
|
|
53
|
+
getNode(kind: string, ...args: MaybeContextualArg<Context>): Promise<GraphNodeModel>;
|
|
54
|
+
}
|
|
@@ -69,6 +69,27 @@ export declare class GraphWorkflowService extends ModelService<GraphWorkflowMode
|
|
|
69
69
|
* @throws {GraphWorkflowDocumentRejectedError} When boundary validation fails.
|
|
70
70
|
*/
|
|
71
71
|
saveDocument(workflowId: string, document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel>;
|
|
72
|
+
/**
|
|
73
|
+
* Boot-seed write of a canonical workflow document (F2 availability fix):
|
|
74
|
+
* behaves exactly like {@link saveDocument} except that an ownership conflict
|
|
75
|
+
* on an existing foreign-owned row is treated as a skip-and-log instead of a
|
|
76
|
+
* hard failure. A durable store that already holds a user-owned row for a
|
|
77
|
+
* fixture id therefore cannot fail host bootstrap, while the security posture
|
|
78
|
+
* is unchanged: the foreign-owned row is never overwritten and the engine's own
|
|
79
|
+
* catalogue seed still serves the fixture.
|
|
80
|
+
*
|
|
81
|
+
* This is the boot seeding surface only. Request-path writes MUST keep using
|
|
82
|
+
* {@link saveDocument} / {@link saveSnapshot}, which stay fail-closed on a
|
|
83
|
+
* foreign-owned overwrite (SAA-105 R3).
|
|
84
|
+
*
|
|
85
|
+
* @param {string} workflowId - Workflow id from the fixture registry.
|
|
86
|
+
* @param {GraphWorkflowDocument} document - Canonical document to seed (its `id` must equal `workflowId`).
|
|
87
|
+
* @param args - An optional decaf `Context` carrying the owning principal.
|
|
88
|
+
* @return {Promise<GraphWorkflowModel | null>} The persisted row, or `null` when the seed was skipped because the existing row is owned by another user.
|
|
89
|
+
* @throws {ValidationError} When the payload shape or the document/path id match is invalid.
|
|
90
|
+
* @throws {GraphWorkflowDocumentRejectedError} When boundary validation fails.
|
|
91
|
+
*/
|
|
92
|
+
seedDocument(workflowId: string, document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel | null>;
|
|
72
93
|
/**
|
|
73
94
|
* Reads a workflow's canonical document, enforcing the DECAF-48 ownership
|
|
74
95
|
* tuple. Legacy definition/state snapshots are no longer served.
|
|
@@ -69,6 +69,27 @@ export declare class GraphWorkflowService extends ModelService<GraphWorkflowMode
|
|
|
69
69
|
* @throws {GraphWorkflowDocumentRejectedError} When boundary validation fails.
|
|
70
70
|
*/
|
|
71
71
|
saveDocument(workflowId: string, document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel>;
|
|
72
|
+
/**
|
|
73
|
+
* Boot-seed write of a canonical workflow document (F2 availability fix):
|
|
74
|
+
* behaves exactly like {@link saveDocument} except that an ownership conflict
|
|
75
|
+
* on an existing foreign-owned row is treated as a skip-and-log instead of a
|
|
76
|
+
* hard failure. A durable store that already holds a user-owned row for a
|
|
77
|
+
* fixture id therefore cannot fail host bootstrap, while the security posture
|
|
78
|
+
* is unchanged: the foreign-owned row is never overwritten and the engine's own
|
|
79
|
+
* catalogue seed still serves the fixture.
|
|
80
|
+
*
|
|
81
|
+
* This is the boot seeding surface only. Request-path writes MUST keep using
|
|
82
|
+
* {@link saveDocument} / {@link saveSnapshot}, which stay fail-closed on a
|
|
83
|
+
* foreign-owned overwrite (SAA-105 R3).
|
|
84
|
+
*
|
|
85
|
+
* @param {string} workflowId - Workflow id from the fixture registry.
|
|
86
|
+
* @param {GraphWorkflowDocument} document - Canonical document to seed (its `id` must equal `workflowId`).
|
|
87
|
+
* @param args - An optional decaf `Context` carrying the owning principal.
|
|
88
|
+
* @return {Promise<GraphWorkflowModel | null>} The persisted row, or `null` when the seed was skipped because the existing row is owned by another user.
|
|
89
|
+
* @throws {ValidationError} When the payload shape or the document/path id match is invalid.
|
|
90
|
+
* @throws {GraphWorkflowDocumentRejectedError} When boundary validation fails.
|
|
91
|
+
*/
|
|
92
|
+
seedDocument(workflowId: string, document: GraphWorkflowDocument, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowModel | null>;
|
|
72
93
|
/**
|
|
73
94
|
* Reads a workflow's canonical document, enforcing the DECAF-48 ownership
|
|
74
95
|
* tuple. Legacy definition/state snapshots are no longer served.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import { type MastraNodeStepHandler } from "./types.d.cts";
|
|
2
|
+
/**
|
|
3
|
+
* The built-in leaf node kinds covered by the default handler set: the
|
|
4
|
+
* plain-data, flow-utility, trigger, and utility kinds that compile as opaque
|
|
5
|
+
* steps. Structural kinds (`core.flow.if`/`core.flow.switch`, the
|
|
6
|
+
* `core.loop.*` loops, and `core.flow.humanApproval`) are translated by the
|
|
7
|
+
* compiler itself and are deliberately absent.
|
|
8
|
+
*/
|
|
9
|
+
export declare const MASTRA_DEFAULT_STEP_HANDLER_KINDS: readonly ["value", "result", "core.agent", "core.flow.break", "core.flow.delay", "core.flow.errorBoundary", "core.flow.log", "core.trigger.chat", "core.trigger.event", "core.trigger.form", "core.trigger.manual", "core.trigger.schedule", "core.trigger.webhook", "core.utility.code", "core.utility.log", "core.utility.map"];
|
|
10
|
+
/** Any built-in leaf node kind covered by {@link MASTRA_DEFAULT_STEP_HANDLER_KINDS}. */
|
|
11
|
+
export type MastraDefaultStepHandlerKind = (typeof MASTRA_DEFAULT_STEP_HANDLER_KINDS)[number];
|
|
12
|
+
/**
|
|
13
|
+
* Largest delay `setTimeout` accepts before Node overflows and collapses the
|
|
14
|
+
* wait to ~1ms (`2^31 - 1`). {@link createMastraDefaultStepHandlers} clamps a
|
|
15
|
+
* delay node's `timeoutMs` to this value *before* scheduling, so a hostile or
|
|
16
|
+
* oversized declared delay can never hit the overflow degenerate path.
|
|
17
|
+
*/
|
|
18
|
+
export declare const MASTRA_MAX_SET_TIMEOUT_MS = 2147483647;
|
|
19
|
+
/**
|
|
20
|
+
* Default host-configurable ceiling, in milliseconds, for a `core.flow.delay`
|
|
21
|
+
* node's `timeoutMs` (60s). The declared value is clamped to this ceiling, never
|
|
22
|
+
* rejected, so an oversized document cannot pin a run slot for up to
|
|
23
|
+
* `MASTRA_MAX_SET_TIMEOUT_MS` (~24.8 days) per node.
|
|
24
|
+
*/
|
|
25
|
+
export declare const DEFAULT_MASTRA_DELAY_MAX_MS = 60000;
|
|
26
|
+
/**
|
|
27
|
+
* Reserved key under which a default-handler result records that the node was
|
|
28
|
+
* not fully executed. `core.agent` returns its forwarded input plus this key so
|
|
29
|
+
* a caller can tell a declared-but-inert agent step apart from a real one; the
|
|
30
|
+
* key never collides with a canonical data port.
|
|
31
|
+
*/
|
|
32
|
+
export declare const MASTRA_DEGRADED_OUTPUT_KEY = "__mastraDegraded";
|
|
33
|
+
/** Details recorded under {@link MASTRA_DEGRADED_OUTPUT_KEY}. */
|
|
34
|
+
export interface MastraDegradedOutput {
|
|
35
|
+
/** The node kind whose declared capability was not executed. */
|
|
36
|
+
kind: string;
|
|
37
|
+
/** The node id the degraded result belongs to. */
|
|
38
|
+
nodeId: string;
|
|
39
|
+
/** Human-readable reason the node degraded to a pass-through. */
|
|
40
|
+
reason: string;
|
|
41
|
+
}
|
|
42
|
+
/** Options {@link createMastraDefaultStepHandlers} is created with. */
|
|
43
|
+
export interface MastraDefaultStepHandlerOptions {
|
|
44
|
+
/**
|
|
45
|
+
* Optional sink for the log kinds' messages (the default is silent).
|
|
46
|
+
*
|
|
47
|
+
* The sink receives **untrusted** data: `message` is the document's
|
|
48
|
+
* `node.parameters.message` verbatim and `meta` carries in-flight node data. A
|
|
49
|
+
* logger implementation must treat both arguments as untrusted, JSON-serialize
|
|
50
|
+
* `meta`, and never interpolate either into a line-oriented log (the pattern
|
|
51
|
+
* `nest/graph/servingErrors.ts` already mandates) — otherwise a crafted
|
|
52
|
+
* document enables log forging or CRLF injection.
|
|
53
|
+
*/
|
|
54
|
+
logger?: (message: string, meta?: Record<string, unknown>) => void;
|
|
55
|
+
/**
|
|
56
|
+
* Host-configurable ceiling, in milliseconds, for a `core.flow.delay` node's
|
|
57
|
+
* `timeoutMs`. The declared value is clamped to this ceiling (never rejected)
|
|
58
|
+
* and additionally bounded by {@link MASTRA_MAX_SET_TIMEOUT_MS}; defaults to
|
|
59
|
+
* {@link DEFAULT_MASTRA_DELAY_MAX_MS}.
|
|
60
|
+
*/
|
|
61
|
+
maxDelayMs?: number;
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Builds the default {@link MastraNodeStepHandler} set: one handler per
|
|
65
|
+
* {@link MastraDefaultStepHandlerKind}. Each handler creates a
|
|
66
|
+
* schema-agnostic Mastra step (`z.any()` input and output schemas) whose
|
|
67
|
+
* execution coerces the runtime's input data to a record and delegates to the
|
|
68
|
+
* kind's executor, so untyped document parameters never break the runtime.
|
|
69
|
+
*
|
|
70
|
+
* @param options - Optional handler-set options (logger and delay ceiling).
|
|
71
|
+
* @returns One {@link MastraNodeStepHandler} per entry of
|
|
72
|
+
* {@link MASTRA_DEFAULT_STEP_HANDLER_KINDS}.
|
|
73
|
+
*/
|
|
74
|
+
export declare function createMastraDefaultStepHandlers(options?: MastraDefaultStepHandlerOptions): MastraNodeStepHandler[];
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
import { type MastraNodeStepHandler } from "./types.d.mts";
|
|
2
|
+
/**
|
|
3
|
+
* The built-in leaf node kinds covered by the default handler set: the
|
|
4
|
+
* plain-data, flow-utility, trigger, and utility kinds that compile as opaque
|
|
5
|
+
* steps. Structural kinds (`core.flow.if`/`core.flow.switch`, the
|
|
6
|
+
* `core.loop.*` loops, and `core.flow.humanApproval`) are translated by the
|
|
7
|
+
* compiler itself and are deliberately absent.
|
|
8
|
+
*/
|
|
9
|
+
export declare const MASTRA_DEFAULT_STEP_HANDLER_KINDS: readonly ["value", "result", "core.agent", "core.flow.break", "core.flow.delay", "core.flow.errorBoundary", "core.flow.log", "core.trigger.chat", "core.trigger.event", "core.trigger.form", "core.trigger.manual", "core.trigger.schedule", "core.trigger.webhook", "core.utility.code", "core.utility.log", "core.utility.map"];
|
|
10
|
+
/** Any built-in leaf node kind covered by {@link MASTRA_DEFAULT_STEP_HANDLER_KINDS}. */
|
|
11
|
+
export type MastraDefaultStepHandlerKind = (typeof MASTRA_DEFAULT_STEP_HANDLER_KINDS)[number];
|
|
12
|
+
/**
|
|
13
|
+
* Largest delay `setTimeout` accepts before Node overflows and collapses the
|
|
14
|
+
* wait to ~1ms (`2^31 - 1`). {@link createMastraDefaultStepHandlers} clamps a
|
|
15
|
+
* delay node's `timeoutMs` to this value *before* scheduling, so a hostile or
|
|
16
|
+
* oversized declared delay can never hit the overflow degenerate path.
|
|
17
|
+
*/
|
|
18
|
+
export declare const MASTRA_MAX_SET_TIMEOUT_MS = 2147483647;
|
|
19
|
+
/**
|
|
20
|
+
* Default host-configurable ceiling, in milliseconds, for a `core.flow.delay`
|
|
21
|
+
* node's `timeoutMs` (60s). The declared value is clamped to this ceiling, never
|
|
22
|
+
* rejected, so an oversized document cannot pin a run slot for up to
|
|
23
|
+
* `MASTRA_MAX_SET_TIMEOUT_MS` (~24.8 days) per node.
|
|
24
|
+
*/
|
|
25
|
+
export declare const DEFAULT_MASTRA_DELAY_MAX_MS = 60000;
|
|
26
|
+
/**
|
|
27
|
+
* Reserved key under which a default-handler result records that the node was
|
|
28
|
+
* not fully executed. `core.agent` returns its forwarded input plus this key so
|
|
29
|
+
* a caller can tell a declared-but-inert agent step apart from a real one; the
|
|
30
|
+
* key never collides with a canonical data port.
|
|
31
|
+
*/
|
|
32
|
+
export declare const MASTRA_DEGRADED_OUTPUT_KEY = "__mastraDegraded";
|
|
33
|
+
/** Details recorded under {@link MASTRA_DEGRADED_OUTPUT_KEY}. */
|
|
34
|
+
export interface MastraDegradedOutput {
|
|
35
|
+
/** The node kind whose declared capability was not executed. */
|
|
36
|
+
kind: string;
|
|
37
|
+
/** The node id the degraded result belongs to. */
|
|
38
|
+
nodeId: string;
|
|
39
|
+
/** Human-readable reason the node degraded to a pass-through. */
|
|
40
|
+
reason: string;
|
|
41
|
+
}
|
|
42
|
+
/** Options {@link createMastraDefaultStepHandlers} is created with. */
|
|
43
|
+
export interface MastraDefaultStepHandlerOptions {
|
|
44
|
+
/**
|
|
45
|
+
* Optional sink for the log kinds' messages (the default is silent).
|
|
46
|
+
*
|
|
47
|
+
* The sink receives **untrusted** data: `message` is the document's
|
|
48
|
+
* `node.parameters.message` verbatim and `meta` carries in-flight node data. A
|
|
49
|
+
* logger implementation must treat both arguments as untrusted, JSON-serialize
|
|
50
|
+
* `meta`, and never interpolate either into a line-oriented log (the pattern
|
|
51
|
+
* `nest/graph/servingErrors.ts` already mandates) — otherwise a crafted
|
|
52
|
+
* document enables log forging or CRLF injection.
|
|
53
|
+
*/
|
|
54
|
+
logger?: (message: string, meta?: Record<string, unknown>) => void;
|
|
55
|
+
/**
|
|
56
|
+
* Host-configurable ceiling, in milliseconds, for a `core.flow.delay` node's
|
|
57
|
+
* `timeoutMs`. The declared value is clamped to this ceiling (never rejected)
|
|
58
|
+
* and additionally bounded by {@link MASTRA_MAX_SET_TIMEOUT_MS}; defaults to
|
|
59
|
+
* {@link DEFAULT_MASTRA_DELAY_MAX_MS}.
|
|
60
|
+
*/
|
|
61
|
+
maxDelayMs?: number;
|
|
62
|
+
}
|
|
63
|
+
/**
|
|
64
|
+
* Builds the default {@link MastraNodeStepHandler} set: one handler per
|
|
65
|
+
* {@link MastraDefaultStepHandlerKind}. Each handler creates a
|
|
66
|
+
* schema-agnostic Mastra step (`z.any()` input and output schemas) whose
|
|
67
|
+
* execution coerces the runtime's input data to a record and delegates to the
|
|
68
|
+
* kind's executor, so untyped document parameters never break the runtime.
|
|
69
|
+
*
|
|
70
|
+
* @param options - Optional handler-set options (logger and delay ceiling).
|
|
71
|
+
* @returns One {@link MastraNodeStepHandler} per entry of
|
|
72
|
+
* {@link MASTRA_DEFAULT_STEP_HANDLER_KINDS}.
|
|
73
|
+
*/
|
|
74
|
+
export declare function createMastraDefaultStepHandlers(options?: MastraDefaultStepHandlerOptions): MastraNodeStepHandler[];
|
|
@@ -34,6 +34,7 @@ export declare class MastraGraphExecutionBackend implements GraphExecutionBacken
|
|
|
34
34
|
private managementManager?;
|
|
35
35
|
private suspendStateReader?;
|
|
36
36
|
private maxResumeBytes;
|
|
37
|
+
private terminalTimeoutMs;
|
|
37
38
|
private initialized;
|
|
38
39
|
private _config?;
|
|
39
40
|
constructor();
|
|
@@ -75,7 +76,35 @@ export declare class MastraGraphExecutionBackend implements GraphExecutionBacken
|
|
|
75
76
|
* @throws {NotFoundError} when the workflow is owned by another user.
|
|
76
77
|
*/
|
|
77
78
|
getWorkflow(workflowId: string, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
|
|
79
|
+
/**
|
|
80
|
+
* Seeds canonical workflow documents into the translated-workflow catalogue so
|
|
81
|
+
* they are served by {@link listWorkflows}/{@link getWorkflow} exactly like a
|
|
82
|
+
* document recorded by {@link execute}. Seeded entries are owner-less, so the
|
|
83
|
+
* C23 filter keeps them visible to every caller (the owner-less visibility
|
|
84
|
+
* rule). Fails closed when the backend has not been initialized.
|
|
85
|
+
*
|
|
86
|
+
* @param documents - The canonical documents to register.
|
|
87
|
+
* @returns The seeded workflow summaries.
|
|
88
|
+
* @throws {GraphExecutionError} when the backend is not initialized.
|
|
89
|
+
*/
|
|
90
|
+
seedWorkflows(documents: readonly GraphWorkflowDocument[]): Promise<GraphBackendWorkflowSummary[]>;
|
|
78
91
|
execute(request: GraphBackendExecutionRequest, ...args: MaybeContextualArg<Context>): Promise<GraphExecutionResult>;
|
|
92
|
+
/**
|
|
93
|
+
* Bounds the translated run's terminal wait by the backend's run-level
|
|
94
|
+
* `terminalTimeoutMs` and the caller's cancellation signal, mirroring the
|
|
95
|
+
* Dagster observation bound. Exceeding the timeout fails closed with
|
|
96
|
+
* {@link GRAPH_MASTRA_EXECUTE_TIMEOUT}; an abort fails closed with
|
|
97
|
+
* {@link GRAPH_MASTRA_EXECUTE_ABORTED}. The underlying run is not force-killed
|
|
98
|
+
* (Mastra owns run lifecycle), but the backend stops awaiting it so the run
|
|
99
|
+
* slot and event bridge are released and the run cannot pin the process.
|
|
100
|
+
*
|
|
101
|
+
* @param execution - The in-flight run/stream/result promise.
|
|
102
|
+
* @param signal - The caller's cancellation signal, when supplied.
|
|
103
|
+
* @param workflowId - The workflow id the run belongs to (for error details).
|
|
104
|
+
* @returns Resolves once the run terminates normally.
|
|
105
|
+
* @throws {GraphExecutionError} on timeout or abort.
|
|
106
|
+
*/
|
|
107
|
+
private awaitTerminal;
|
|
79
108
|
/**
|
|
80
109
|
* Resumes a suspended Mastra run after enforcing the SAA-193 resume guard
|
|
81
110
|
* (C13/C15/C16/C17/C18). The Mastra run snapshot is authoritative for the
|
|
@@ -34,6 +34,7 @@ export declare class MastraGraphExecutionBackend implements GraphExecutionBacken
|
|
|
34
34
|
private managementManager?;
|
|
35
35
|
private suspendStateReader?;
|
|
36
36
|
private maxResumeBytes;
|
|
37
|
+
private terminalTimeoutMs;
|
|
37
38
|
private initialized;
|
|
38
39
|
private _config?;
|
|
39
40
|
constructor();
|
|
@@ -75,7 +76,35 @@ export declare class MastraGraphExecutionBackend implements GraphExecutionBacken
|
|
|
75
76
|
* @throws {NotFoundError} when the workflow is owned by another user.
|
|
76
77
|
*/
|
|
77
78
|
getWorkflow(workflowId: string, ...args: MaybeContextualArg<Context>): Promise<GraphWorkflowDocument>;
|
|
79
|
+
/**
|
|
80
|
+
* Seeds canonical workflow documents into the translated-workflow catalogue so
|
|
81
|
+
* they are served by {@link listWorkflows}/{@link getWorkflow} exactly like a
|
|
82
|
+
* document recorded by {@link execute}. Seeded entries are owner-less, so the
|
|
83
|
+
* C23 filter keeps them visible to every caller (the owner-less visibility
|
|
84
|
+
* rule). Fails closed when the backend has not been initialized.
|
|
85
|
+
*
|
|
86
|
+
* @param documents - The canonical documents to register.
|
|
87
|
+
* @returns The seeded workflow summaries.
|
|
88
|
+
* @throws {GraphExecutionError} when the backend is not initialized.
|
|
89
|
+
*/
|
|
90
|
+
seedWorkflows(documents: readonly GraphWorkflowDocument[]): Promise<GraphBackendWorkflowSummary[]>;
|
|
78
91
|
execute(request: GraphBackendExecutionRequest, ...args: MaybeContextualArg<Context>): Promise<GraphExecutionResult>;
|
|
92
|
+
/**
|
|
93
|
+
* Bounds the translated run's terminal wait by the backend's run-level
|
|
94
|
+
* `terminalTimeoutMs` and the caller's cancellation signal, mirroring the
|
|
95
|
+
* Dagster observation bound. Exceeding the timeout fails closed with
|
|
96
|
+
* {@link GRAPH_MASTRA_EXECUTE_TIMEOUT}; an abort fails closed with
|
|
97
|
+
* {@link GRAPH_MASTRA_EXECUTE_ABORTED}. The underlying run is not force-killed
|
|
98
|
+
* (Mastra owns run lifecycle), but the backend stops awaiting it so the run
|
|
99
|
+
* slot and event bridge are released and the run cannot pin the process.
|
|
100
|
+
*
|
|
101
|
+
* @param execution - The in-flight run/stream/result promise.
|
|
102
|
+
* @param signal - The caller's cancellation signal, when supplied.
|
|
103
|
+
* @param workflowId - The workflow id the run belongs to (for error details).
|
|
104
|
+
* @returns Resolves once the run terminates normally.
|
|
105
|
+
* @throws {GraphExecutionError} on timeout or abort.
|
|
106
|
+
*/
|
|
107
|
+
private awaitTerminal;
|
|
79
108
|
/**
|
|
80
109
|
* Resumes a suspended Mastra run after enforcing the SAA-193 resume guard
|
|
81
110
|
* (C13/C15/C16/C17/C18). The Mastra run snapshot is authoritative for the
|
|
@@ -18,11 +18,11 @@ export declare const GRAPH_MASTRA_IF_KIND = "core.flow.if";
|
|
|
18
18
|
/** Document kind translated into a Mastra `switch` branch set. */
|
|
19
19
|
export declare const GRAPH_MASTRA_SWITCH_KIND = "core.flow.switch";
|
|
20
20
|
/** Document kind translated into a Mastra `foreach` loop. */
|
|
21
|
-
export declare const GRAPH_MASTRA_FOREACH_KIND = "
|
|
21
|
+
export declare const GRAPH_MASTRA_FOREACH_KIND = "core.loop.foreach";
|
|
22
22
|
/** Document kind translated into a Mastra `do-while` loop. */
|
|
23
|
-
export declare const GRAPH_MASTRA_WHILE_KIND = "
|
|
23
|
+
export declare const GRAPH_MASTRA_WHILE_KIND = "core.loop.while";
|
|
24
24
|
/** Document kind translated into a Mastra `do-until` loop. */
|
|
25
|
-
export declare const GRAPH_MASTRA_UNTIL_KIND = "
|
|
25
|
+
export declare const GRAPH_MASTRA_UNTIL_KIND = "core.loop.until";
|
|
26
26
|
/** Document kind translated into a Mastra suspending approval step. */
|
|
27
27
|
export declare const GRAPH_MASTRA_HUMAN_APPROVAL_KIND = "core.flow.humanApproval";
|
|
28
28
|
/**
|
|
@@ -18,11 +18,11 @@ export declare const GRAPH_MASTRA_IF_KIND = "core.flow.if";
|
|
|
18
18
|
/** Document kind translated into a Mastra `switch` branch set. */
|
|
19
19
|
export declare const GRAPH_MASTRA_SWITCH_KIND = "core.flow.switch";
|
|
20
20
|
/** Document kind translated into a Mastra `foreach` loop. */
|
|
21
|
-
export declare const GRAPH_MASTRA_FOREACH_KIND = "
|
|
21
|
+
export declare const GRAPH_MASTRA_FOREACH_KIND = "core.loop.foreach";
|
|
22
22
|
/** Document kind translated into a Mastra `do-while` loop. */
|
|
23
|
-
export declare const GRAPH_MASTRA_WHILE_KIND = "
|
|
23
|
+
export declare const GRAPH_MASTRA_WHILE_KIND = "core.loop.while";
|
|
24
24
|
/** Document kind translated into a Mastra `do-until` loop. */
|
|
25
|
-
export declare const GRAPH_MASTRA_UNTIL_KIND = "
|
|
25
|
+
export declare const GRAPH_MASTRA_UNTIL_KIND = "core.loop.until";
|
|
26
26
|
/** Document kind translated into a Mastra suspending approval step. */
|
|
27
27
|
export declare const GRAPH_MASTRA_HUMAN_APPROVAL_KIND = "core.flow.humanApproval";
|
|
28
28
|
/**
|
|
@@ -12,6 +12,7 @@ export * from "./MastraSchemaConverter.d.cts";
|
|
|
12
12
|
export * from "./MastraConditionBridge.d.cts";
|
|
13
13
|
export * from "./MastraEventBridge.d.cts";
|
|
14
14
|
export * from "./MastraWorkflowCompiler.d.cts";
|
|
15
|
+
export * from "./MastraDefaultStepHandlers.d.cts";
|
|
15
16
|
export * from "./MastraWorkflowManager.d.cts";
|
|
16
17
|
export * from "./MastraResumeGuard.d.cts";
|
|
17
18
|
export * from "./MastraGraphExecutionBackend.d.cts";
|
|
@@ -12,6 +12,7 @@ export * from "./MastraSchemaConverter.d.mts";
|
|
|
12
12
|
export * from "./MastraConditionBridge.d.mts";
|
|
13
13
|
export * from "./MastraEventBridge.d.mts";
|
|
14
14
|
export * from "./MastraWorkflowCompiler.d.mts";
|
|
15
|
+
export * from "./MastraDefaultStepHandlers.d.mts";
|
|
15
16
|
export * from "./MastraWorkflowManager.d.mts";
|
|
16
17
|
export * from "./MastraResumeGuard.d.mts";
|
|
17
18
|
export * from "./MastraGraphExecutionBackend.d.mts";
|
|
@@ -29,6 +29,10 @@ export declare const GRAPH_MASTRA_RESUME_STATE_INVALID = "GRAPH_MASTRA_RESUME_ST
|
|
|
29
29
|
export declare const GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE = "GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE";
|
|
30
30
|
/** No Mastra agent is available for an agent-backed node. */
|
|
31
31
|
export declare const GRAPH_MASTRA_AGENT_UNAVAILABLE = "GRAPH_MASTRA_AGENT_UNAVAILABLE";
|
|
32
|
+
/** The Mastra execute path did not terminate within its run-level timeout. */
|
|
33
|
+
export declare const GRAPH_MASTRA_EXECUTE_TIMEOUT = "GRAPH_MASTRA_EXECUTE_TIMEOUT";
|
|
34
|
+
/** The Mastra execute path was aborted by the caller's cancellation signal. */
|
|
35
|
+
export declare const GRAPH_MASTRA_EXECUTE_ABORTED = "GRAPH_MASTRA_EXECUTE_ABORTED";
|
|
32
36
|
/** The wired Mastra runtime exposes no workflow-management surface. */
|
|
33
37
|
export declare const GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE = "GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE";
|
|
34
38
|
/** A managed workflow id has no workflow registered on the runtime. */
|
|
@@ -102,6 +106,14 @@ export interface MastraBackendConfig extends Record<string, unknown> {
|
|
|
102
106
|
suspendStateReader?: MastraSuspendStateReader;
|
|
103
107
|
/** Maximum accepted serialised `resumeData` size, in bytes. */
|
|
104
108
|
maxResumeBytes?: number;
|
|
109
|
+
/**
|
|
110
|
+
* Run-level terminal timeout, in milliseconds, for {@link MastraGraphExecutionBackend.execute}.
|
|
111
|
+
* A translated run that has not terminated within this bound fails closed with
|
|
112
|
+
* {@link GRAPH_MASTRA_EXECUTE_TIMEOUT} instead of pinning the run slot and event
|
|
113
|
+
* stream indefinitely; mirrors the Dagster `terminalTimeoutMs` bound. Defaults
|
|
114
|
+
* to five minutes when omitted.
|
|
115
|
+
*/
|
|
116
|
+
terminalTimeoutMs?: number;
|
|
105
117
|
}
|
|
106
118
|
/**
|
|
107
119
|
* Mastra-authoritative snapshot of a suspended run as exposed by the host's
|
|
@@ -29,6 +29,10 @@ export declare const GRAPH_MASTRA_RESUME_STATE_INVALID = "GRAPH_MASTRA_RESUME_ST
|
|
|
29
29
|
export declare const GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE = "GRAPH_MASTRA_TRANSLATION_JSON_UNSAFE";
|
|
30
30
|
/** No Mastra agent is available for an agent-backed node. */
|
|
31
31
|
export declare const GRAPH_MASTRA_AGENT_UNAVAILABLE = "GRAPH_MASTRA_AGENT_UNAVAILABLE";
|
|
32
|
+
/** The Mastra execute path did not terminate within its run-level timeout. */
|
|
33
|
+
export declare const GRAPH_MASTRA_EXECUTE_TIMEOUT = "GRAPH_MASTRA_EXECUTE_TIMEOUT";
|
|
34
|
+
/** The Mastra execute path was aborted by the caller's cancellation signal. */
|
|
35
|
+
export declare const GRAPH_MASTRA_EXECUTE_ABORTED = "GRAPH_MASTRA_EXECUTE_ABORTED";
|
|
32
36
|
/** The wired Mastra runtime exposes no workflow-management surface. */
|
|
33
37
|
export declare const GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE = "GRAPH_MASTRA_MANAGEMENT_UNAVAILABLE";
|
|
34
38
|
/** A managed workflow id has no workflow registered on the runtime. */
|
|
@@ -102,6 +106,14 @@ export interface MastraBackendConfig extends Record<string, unknown> {
|
|
|
102
106
|
suspendStateReader?: MastraSuspendStateReader;
|
|
103
107
|
/** Maximum accepted serialised `resumeData` size, in bytes. */
|
|
104
108
|
maxResumeBytes?: number;
|
|
109
|
+
/**
|
|
110
|
+
* Run-level terminal timeout, in milliseconds, for {@link MastraGraphExecutionBackend.execute}.
|
|
111
|
+
* A translated run that has not terminated within this bound fails closed with
|
|
112
|
+
* {@link GRAPH_MASTRA_EXECUTE_TIMEOUT} instead of pinning the run slot and event
|
|
113
|
+
* stream indefinitely; mirrors the Dagster `terminalTimeoutMs` bound. Defaults
|
|
114
|
+
* to five minutes when omitted.
|
|
115
|
+
*/
|
|
116
|
+
terminalTimeoutMs?: number;
|
|
105
117
|
}
|
|
106
118
|
/**
|
|
107
119
|
* Mastra-authoritative snapshot of a suspended run as exposed by the host's
|
|
@@ -1,3 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @module as-graph/nest/graph/GraphBackendHost
|
|
3
|
+
* @summary Boot-time engine-variant selection for the graph backend host (SAA-706).
|
|
4
|
+
* @description Resolves which of the three pluggable graph engines — the built-in
|
|
5
|
+
* local reference interpreter, the `@mastra/core` translated backend, or the
|
|
6
|
+
* read-only Dagster backend — a host boots, constructs and registers that
|
|
7
|
+
* backend, and assembles the {@link GraphExecutionModule} options that make the
|
|
8
|
+
* Nest host serve the matching C20 capability manifest (`graph/engines`) and the
|
|
9
|
+
* per-engine workflow catalogue (`graph/engines/{engineId}/workflows`).
|
|
10
|
+
*
|
|
11
|
+
* The host never stubs an engine: each variant constructs the real backend. A
|
|
12
|
+
* translated/remote backend whose host wiring is absent (no Mastra runtime, no
|
|
13
|
+
* Dagster client) still boots and serves the manifest; its catalogue then reports
|
|
14
|
+
* the engine's honest `NOT_SUPPORTED` verdict through the engine facade, exactly
|
|
15
|
+
* as `GraphEngineController` maps it to `501`. The variant is chosen at boot by
|
|
16
|
+
* the `GRAPH_BACKEND_ENGINE` environment variable, so switching engines is a
|
|
17
|
+
* configuration change, never a code change.
|
|
18
|
+
*/
|
|
19
|
+
import type { GraphWorkflowDocument } from "../../shared/graph/index.d.cts";
|
|
1
20
|
import type { GraphExecutionBackend } from "../../engine/execution/GraphExecutionBackend.d.cts";
|
|
2
21
|
import { type MastraBackendConfig } from "../../mastra/types.d.cts";
|
|
3
22
|
import type { DagsterClient } from "../../dagster/DagsterTypes.d.cts";
|
|
@@ -32,6 +51,20 @@ export declare function parseGraphEngineVariant(value: string | undefined, fallb
|
|
|
32
51
|
* @returns The resolved engine variant.
|
|
33
52
|
*/
|
|
34
53
|
export declare function graphEngineVariantFromEnv(env?: NodeJS.ProcessEnv): GraphEngineVariant;
|
|
54
|
+
/** Environment variable gating boot-time demo-workflow seeding (F5 hardening). */
|
|
55
|
+
export declare const GRAPH_SEED_DEMO_ENV = "GRAPH_SEED_DEMO";
|
|
56
|
+
/**
|
|
57
|
+
* Resolves whether the standalone host seeds the demo workflow fixture registry
|
|
58
|
+
* at boot (F5 hardening). Seeding is enabled by default so a source checkout
|
|
59
|
+
* keeps its fixtures; a production host sets `GRAPH_SEED_DEMO=off` (also accepts
|
|
60
|
+
* `false` / `0` / `no` / `disabled`, case-insensitive) to suppress owner-less
|
|
61
|
+
* demo seeding without a code change. An unset or empty value keeps the default
|
|
62
|
+
* (enabled), so existing hosts are unaffected.
|
|
63
|
+
*
|
|
64
|
+
* @param env - The environment to read from (defaults to `process.env`).
|
|
65
|
+
* @returns `true` when boot-time demo seeding is enabled.
|
|
66
|
+
*/
|
|
67
|
+
export declare function graphDemoSeedEnabledFromEnv(env?: NodeJS.ProcessEnv): boolean;
|
|
35
68
|
/** Host wiring for the Dagster variant: the client port plus its gate options. */
|
|
36
69
|
export interface GraphDagsterHostOptions {
|
|
37
70
|
/**
|
|
@@ -59,6 +92,13 @@ export interface GraphBackendHostOptions {
|
|
|
59
92
|
mastra?: MastraBackendConfig;
|
|
60
93
|
/** Host wiring for the Dagster variant. */
|
|
61
94
|
dagster?: GraphDagsterHostOptions;
|
|
95
|
+
/**
|
|
96
|
+
* Canonical workflow documents seeded into the selected engine's catalogue at
|
|
97
|
+
* boot (the host's fixture registry). Forwarded to the module options so the
|
|
98
|
+
* per-engine workflow catalogue serves the fixture set for whichever variant
|
|
99
|
+
* the host booted. The seed stays engine-dependent and read-only for Dagster.
|
|
100
|
+
*/
|
|
101
|
+
seedWorkflows?: readonly GraphWorkflowDocument[];
|
|
62
102
|
/**
|
|
63
103
|
* Existing module options to extend. The host overrides only `backend` and
|
|
64
104
|
* `engines.defaultEngineId`, so a caller keeps its auth, limits, adapter, and
|
|
@@ -96,5 +136,17 @@ export interface GraphBackendHost {
|
|
|
96
136
|
* @returns The resolved host, including the module options to boot.
|
|
97
137
|
*/
|
|
98
138
|
export declare function createGraphBackendHost(options: GraphBackendHostOptions): Promise<GraphBackendHost>;
|
|
139
|
+
/**
|
|
140
|
+
* Loads the host's demo workflow fixture registry for boot-time seeding. This is
|
|
141
|
+
* the engine driver's seeding path (R4): the fixture registry is imported only
|
|
142
|
+
* by tests and by this loader. Because the registry is excluded from release
|
|
143
|
+
* packaging, the loader is best-effort — it returns the fixture documents when
|
|
144
|
+
* the registry is present (a source checkout or development install) and an
|
|
145
|
+
* empty set when it is absent (a published package), never failing the boot.
|
|
146
|
+
*
|
|
147
|
+
* @returns The canonical documents to seed, or an empty array when the registry
|
|
148
|
+
* is unavailable.
|
|
149
|
+
*/
|
|
150
|
+
export declare function loadGraphDemoWorkflows(): Promise<readonly GraphWorkflowDocument[]>;
|
|
99
151
|
/** The allowlisted engine id for a variant (the backend flavour). */
|
|
100
152
|
export declare function graphEngineIdOf(variant: GraphEngineVariant): string;
|