@igorjpimenta/manifold 0.0.0-stage → 2026.11.22-beta.3

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.
Files changed (210) hide show
  1. package/.migrations/ops/0000_futuristic_karma.sql +111 -0
  2. package/.migrations/ops/0001_low_maximus.sql +7 -0
  3. package/.migrations/ops/meta/0000_snapshot.json +763 -0
  4. package/.migrations/ops/meta/0001_snapshot.json +173 -0
  5. package/.migrations/ops/meta/_journal.json +20 -0
  6. package/.migrations/runtime/0000_real_boomer.sql +180 -0
  7. package/.migrations/runtime/0001_hot_dakota_north.sql +2 -0
  8. package/.migrations/runtime/0002_breezy_vertigo.sql +8 -0
  9. package/.migrations/runtime/0003_dashing_jack_flag.sql +5 -0
  10. package/.migrations/runtime/0004_panoramic_ego.sql +1 -0
  11. package/.migrations/runtime/0005_tidy_ben_grimm.sql +10 -0
  12. package/.migrations/runtime/0006_wet_nightmare.sql +57 -0
  13. package/.migrations/runtime/0007_ambiguous_chronomancer.sql +8 -0
  14. package/.migrations/runtime/0008_wealthy_thundra.sql +301 -0
  15. package/.migrations/runtime/0009_lying_shocker.sql +96 -0
  16. package/.migrations/runtime/0010_solid_phantom_reporter.sql +160 -0
  17. package/.migrations/runtime/0011_windy_demogoblin.sql +175 -0
  18. package/.migrations/runtime/0012_restore_harness_fks.sql +103 -0
  19. package/.migrations/runtime/meta/0000_snapshot.json +1181 -0
  20. package/.migrations/runtime/meta/0001_snapshot.json +1209 -0
  21. package/.migrations/runtime/meta/0002_snapshot.json +1261 -0
  22. package/.migrations/runtime/meta/0003_snapshot.json +1292 -0
  23. package/.migrations/runtime/meta/0004_snapshot.json +1240 -0
  24. package/.migrations/runtime/meta/0006_snapshot.json +1310 -0
  25. package/.migrations/runtime/meta/0007_snapshot.json +1362 -0
  26. package/.migrations/runtime/meta/0008_snapshot.json +1742 -0
  27. package/.migrations/runtime/meta/0009_snapshot.json +2413 -0
  28. package/.migrations/runtime/meta/0010_snapshot.json +2562 -0
  29. package/.migrations/runtime/meta/0011_snapshot.json +2812 -0
  30. package/.migrations/runtime/meta/0012_snapshot.json +2812 -0
  31. package/.migrations/runtime/meta/_journal.json +97 -0
  32. package/README.md +1583 -2
  33. package/RELEASING.md +89 -0
  34. package/agent/fleet.js +100 -0
  35. package/bin/cli.js +854 -0
  36. package/bin/manifold.js +4 -0
  37. package/boot/flow-revival.js +536 -0
  38. package/budget/index.js +495 -0
  39. package/budget/lib.js +59 -0
  40. package/dashboard/cost.js +528 -0
  41. package/dashboard/dist/assets/index-CUfp63sj.css +1 -0
  42. package/dashboard/dist/assets/index-Qy9JMpma.js +371 -0
  43. package/dashboard/dist/index.html +13 -0
  44. package/dashboard/event-log.js +267 -0
  45. package/dashboard/index.html +12 -0
  46. package/dashboard/package-lock.json +2877 -0
  47. package/dashboard/package.json +37 -0
  48. package/dashboard/pipeline-graph.js +131 -0
  49. package/dashboard/postcss.config.js +6 -0
  50. package/dashboard/search.js +183 -0
  51. package/dashboard/server.js +1015 -0
  52. package/dashboard/src/App.tsx +42 -0
  53. package/dashboard/src/api/client.ts +118 -0
  54. package/dashboard/src/api/types.ts +510 -0
  55. package/dashboard/src/api/ws.tsx +112 -0
  56. package/dashboard/src/components/CancelButton.tsx +63 -0
  57. package/dashboard/src/components/ClickToCopy.tsx +68 -0
  58. package/dashboard/src/components/CopyButton.tsx +61 -0
  59. package/dashboard/src/components/DailyCostTrend.tsx +85 -0
  60. package/dashboard/src/components/DailyTimeTrend.tsx +94 -0
  61. package/dashboard/src/components/Funnel.tsx +149 -0
  62. package/dashboard/src/components/GateForm.tsx +158 -0
  63. package/dashboard/src/components/GraphView.tsx +302 -0
  64. package/dashboard/src/components/GroupPathsSummary.tsx +47 -0
  65. package/dashboard/src/components/Histogram.tsx +292 -0
  66. package/dashboard/src/components/Layout.tsx +28 -0
  67. package/dashboard/src/components/NeedsAttention.tsx +98 -0
  68. package/dashboard/src/components/NodeContextCard.tsx +132 -0
  69. package/dashboard/src/components/PathTrail.tsx +35 -0
  70. package/dashboard/src/components/PipelineCostBreakdown.tsx +277 -0
  71. package/dashboard/src/components/RerunButton.tsx +46 -0
  72. package/dashboard/src/components/RunComparison.tsx +53 -0
  73. package/dashboard/src/components/Sparkline.tsx +94 -0
  74. package/dashboard/src/components/StatStrip.tsx +147 -0
  75. package/dashboard/src/components/StateTree.tsx +84 -0
  76. package/dashboard/src/components/StatusBadge.tsx +18 -0
  77. package/dashboard/src/components/SubflowPathPills.tsx +38 -0
  78. package/dashboard/src/components/SubflowSummary.tsx +24 -0
  79. package/dashboard/src/components/SubflowsCard.tsx +327 -0
  80. package/dashboard/src/components/TodayStrip.tsx +86 -0
  81. package/dashboard/src/components/TranscriptPane.tsx +99 -0
  82. package/dashboard/src/components/TranscriptRow.tsx +69 -0
  83. package/dashboard/src/components/ui/badge.tsx +38 -0
  84. package/dashboard/src/components/ui/button.tsx +28 -0
  85. package/dashboard/src/components/ui/card.tsx +42 -0
  86. package/dashboard/src/components/ui/skeleton.tsx +9 -0
  87. package/dashboard/src/components/ui/table.tsx +62 -0
  88. package/dashboard/src/index.css +26 -0
  89. package/dashboard/src/lib/anomaly.ts +42 -0
  90. package/dashboard/src/lib/format.ts +30 -0
  91. package/dashboard/src/lib/step-history.ts +13 -0
  92. package/dashboard/src/lib/subflow.ts +154 -0
  93. package/dashboard/src/lib/use-click-outside.ts +28 -0
  94. package/dashboard/src/lib/use-ignored-clusters.ts +67 -0
  95. package/dashboard/src/lib/utils.ts +6 -0
  96. package/dashboard/src/main.tsx +10 -0
  97. package/dashboard/src/types/shims.d.ts +4 -0
  98. package/dashboard/src/views/Home.tsx +478 -0
  99. package/dashboard/src/views/PipelineDetail.tsx +1185 -0
  100. package/dashboard/src/views/PipelinesList.tsx +111 -0
  101. package/dashboard/src/views/RunDetail.tsx +248 -0
  102. package/dashboard/src/views/Search.tsx +196 -0
  103. package/dashboard/stats.js +668 -0
  104. package/dashboard/tailwind.config.ts +43 -0
  105. package/dashboard/tree-stats.js +12 -0
  106. package/dashboard/tsconfig.json +25 -0
  107. package/dashboard/views.js +231 -0
  108. package/dashboard/vite.config.ts +34 -0
  109. package/drizzle.config.js +12 -0
  110. package/drizzle.config.ops.js +12 -0
  111. package/elevation.js +116 -0
  112. package/engine/admission-promotion-resume.js +127 -0
  113. package/engine/agent-dispatch.js +64 -0
  114. package/engine/child-resume-trigger.js +315 -0
  115. package/engine/executor-budget.js +87 -0
  116. package/engine/executor-cancel.js +83 -0
  117. package/engine/executor-errors.js +122 -0
  118. package/engine/executor-helpers.js +254 -0
  119. package/engine/executor-nodes.js +292 -0
  120. package/engine/executor-persist.js +212 -0
  121. package/engine/executor-subflow-children.js +275 -0
  122. package/engine/executor.js +1013 -0
  123. package/engine/global-concurrency.js +33 -0
  124. package/engine/loader.js +528 -0
  125. package/engine/needs-resolver.js +229 -0
  126. package/engine/pipelines-watcher.js +133 -0
  127. package/engine/result-replay.js +34 -0
  128. package/engine/revival-messages.js +11 -0
  129. package/engine/spawn-child.js +55 -0
  130. package/engine/wait-for-flow-settlement.js +109 -0
  131. package/events/catalog.js +26 -0
  132. package/events/emit.js +44 -0
  133. package/events/kinds.js +118 -0
  134. package/events/serve-ws.js +74 -0
  135. package/events/stream.js +35 -0
  136. package/events/ws-dialog.js +257 -0
  137. package/events/ws-frame.js +194 -0
  138. package/events/ws-run-events.js +70 -0
  139. package/events.js +32 -0
  140. package/gates/gate-resolver.js +576 -0
  141. package/gates/paused-flows.js +55 -0
  142. package/graphql/columns.js +67 -0
  143. package/graphql/schema.js +333 -0
  144. package/index.js +49 -0
  145. package/mcp/http.js +159 -0
  146. package/mcp/identity.js +94 -0
  147. package/mcp/stdio.js +80 -0
  148. package/mcp/tools.js +245 -0
  149. package/mcp/wire-ops.js +178 -0
  150. package/package.json +49 -4
  151. package/routes/bearer-auth.js +57 -0
  152. package/routes/discuss-audio.js +87 -0
  153. package/routes/discuss-component.js +39 -0
  154. package/routes/discuss-draft.js +159 -0
  155. package/routes/discuss-helpers.js +20 -0
  156. package/routes/discuss.js +848 -0
  157. package/routes/failures.js +104 -0
  158. package/routes/graphql.js +61 -0
  159. package/routes/health.js +54 -0
  160. package/routes/operator-discuss.js +193 -0
  161. package/routes/operator-resume.js +32 -0
  162. package/routes/operator-retry.js +301 -0
  163. package/routes/operator.js +539 -0
  164. package/routes/pipelines.js +118 -0
  165. package/routes/runs.js +1129 -0
  166. package/scripts/ci/import-check.mjs +50 -0
  167. package/scripts/link-core-self.mjs +31 -0
  168. package/scripts/with-guard.sh +24 -0
  169. package/server/app.js +503 -0
  170. package/server/registry.js +53 -0
  171. package/server/serve.js +163 -0
  172. package/state/admission-queue-store.js +325 -0
  173. package/state/attribution-registries.js +102 -0
  174. package/state/batch-writer.js +162 -0
  175. package/state/db-guard.js +63 -0
  176. package/state/db-health.js +27 -0
  177. package/state/db.js +122 -0
  178. package/state/discuss-store.js +299 -0
  179. package/state/failure-store.js +427 -0
  180. package/state/migrate.js +104 -0
  181. package/state/node-cost.js +67 -0
  182. package/state/node-executions.js +775 -0
  183. package/state/node-health-store.js +124 -0
  184. package/state/ops-merge.js +93 -0
  185. package/state/paths.js +146 -0
  186. package/state/pipeline-dirs.js +99 -0
  187. package/state/pipeline-registry.js +449 -0
  188. package/state/run-store.js +697 -0
  189. package/state/schema.js +438 -0
  190. package/state/schema.ops.js +44 -0
  191. package/state/session-index.js +177 -0
  192. package/state/session-keys.js +39 -0
  193. package/state/state-store.js +311 -0
  194. package/state/subflow-state.js +126 -0
  195. package/state/tool-handoff.js +169 -0
  196. package/telemetry/budget-alert.js +353 -0
  197. package/telemetry/cli.js +331 -0
  198. package/telemetry/grammar.js +119 -0
  199. package/telemetry/http-budget.js +132 -0
  200. package/telemetry/http-cost.js +670 -0
  201. package/telemetry/http-helpers.js +134 -0
  202. package/telemetry/http-tree.js +349 -0
  203. package/telemetry/http.js +44 -0
  204. package/telemetry/index.js +307 -0
  205. package/telemetry/ingest.js +134 -0
  206. package/telemetry/labels.js +115 -0
  207. package/telemetry/pricer.js +77 -0
  208. package/telemetry/resolver.js +314 -0
  209. package/telemetry/store.js +147 -0
  210. package/utils/run-patch.js +43 -0
@@ -0,0 +1,122 @@
1
+ export const REVISION_RETRY_LIMIT = 5;
2
+
3
+ // Always resolves null — core never reads harness homes, so callers fall
4
+ // back to their default detail.
5
+ export async function fetchSessionError(session) {
6
+ void session;
7
+ return null;
8
+ }
9
+
10
+ /**
11
+ * Thrown (or returned as sentinel) by a node when it detects it can't proceed
12
+ * due to missing info. The executor catches it and blocks the flow with
13
+ * retry-on-resume semantics.
14
+ */
15
+ export class NodeBlocked extends Error {
16
+ constructor({ reason, needed, hint } = {}) {
17
+ super(reason ?? "node blocked");
18
+ this.name = "NodeBlocked";
19
+ this._blocked = { reason, needed, hint };
20
+ }
21
+ }
22
+
23
+ /**
24
+ * Thrown internally when a node's agent dispatch hits
25
+ * `RequestScopedSubagentRuntimeError` — the executor is running outside a
26
+ * gateway request context and can't dispatch agents. The flow gets blocked
27
+ * with `wait_json.kind="needs-gateway-handoff"`.
28
+ *
29
+ * There is no automatic resume for this wait kind — confirmed nothing in
30
+ * this codebase (boot-time flow-revival, a periodic scan, or otherwise)
31
+ * ever re-enters a flow blocked this way. A flow that ends up here needs
32
+ * either the underlying scope gap fixed at its actual call site (see
33
+ * elevation.js for the loopback pattern gate resolution uses) or manual
34
+ * task-revival (patch state + flip status) once resumption would actually
35
+ * succeed.
36
+ */
37
+ export class GatewayHandoffNeeded extends Error {
38
+ constructor(originalMessage) {
39
+ super(`agent dispatch requires gateway context: ${originalMessage}`);
40
+ this.name = "GatewayHandoffNeeded";
41
+ }
42
+ }
43
+
44
+ /**
45
+ * Thrown by a cascade leg (a `flow.kind:"cascade"` node's own nodes, e.g.
46
+ * SUBMIT_CODE/ENSURE_LOGIN_CODE) to signal failure. `errorType` uses a
47
+ * fixed vocabulary (no new strings): "never_attempted" | "confirmed_absent"
48
+ * | "inconclusive" | "infra_unavailable" | "blocked".
49
+ *
50
+ * The engine's cascade-catch branch in executor.js reads `err.errorType`
51
+ * off this (via `instanceof NodeFailure`) and threads it to the next
52
+ * edge-function call as that edge's 2nd argument — see
53
+ * engine/executor-helpers.js's `resolveEdge`. A plain `Error` (or any
54
+ * non-`NodeFailure` throw) still works in a cascade — the edge just
55
+ * receives `errorType: null`.
56
+ */
57
+ export class NodeFailure extends Error {
58
+ constructor(message, { errorType = null } = {}) {
59
+ super(message);
60
+ this.name = "NodeFailure";
61
+ this.errorType = errorType;
62
+ }
63
+ }
64
+
65
+ // The gateway's startup refusal ("<method> unavailable during gateway
66
+ // startup") is deliberately NOT matched below: it is transient, and
67
+ // the harness's run-turn gate holds every call until the gateway is ready.
68
+ // Matching it would park flows in needs-gateway-handoff, which nothing ever
69
+ // resumes.
70
+ export function isRequestScopedSubagentError(err) {
71
+ if (!err) return false;
72
+ if (err.name === "RequestScopedSubagentRuntimeError") return true;
73
+ const msg = err.message ?? String(err);
74
+ if (msg.includes("only available during a gateway request")) return true;
75
+ if (msg.includes("requires a gateway request scope")) return true;
76
+ // An agent dispatch triggered from a detached continuation (e.g.
77
+ // executor.resume() firing via setImmediate after a gate resolves) has no
78
+ // live HTTP request to inherit operator scope from — the gateway RPC
79
+ // layer rejects it with "missing scope: operator.write", a differently-
80
+ // shaped error than the ones above but the exact same underlying cause
81
+ // (no live gateway-request context). Scoped to "operator.write"
82
+ // specifically, not a bare "missing scope:" match — this function is
83
+ // only ever consulted on errors from the three runtime calls a turn makes
84
+ // getSessionMessages calls in the harness's run-turn.js, never on unrelated
85
+ // RPC scope failures (operator.pairing, operator.admin, etc.) from
86
+ // elsewhere in the gateway, so a narrower-than-it-looks match is safe.
87
+ if (msg.includes("missing scope: operator.write")) return true;
88
+ return false;
89
+ }
90
+
91
+ // Errors that must NOT trip a node's breaker.
92
+ //
93
+ // A blocked node has no TTL: it stays blocked until an operator resets it.
94
+ // That is the right default for a symptom (an agent that times out, or a
95
+ // provider that rejects the request) — retrying is pointless and each
96
+ // attempt costs a call. It is the wrong default for a standing configuration
97
+ // fault, which no retry can clear and which would leave the node parked
98
+ // behind a condition only a human can fix, with the reset as the sole
99
+ // remedy.
100
+ //
101
+ // Matched on message text because these originate in different layers (tool
102
+ // permission resolution, the gateway handoff contract, the agent bridge)
103
+ // and share no error class. Deliberately narrow: an unrecognised error is
104
+ // treated as a symptom and DOES trip, so this list can only under-block,
105
+ // never silently swallow a genuine health signal.
106
+ const NON_TRIPPING_REASONS = [
107
+ // A tool scope the operator has not granted. Retrying cannot grant it.
108
+ /missing scope/i,
109
+ // The node kind requires a live gateway context that this flow does not
110
+ // provide — a structural mismatch, not a transient one.
111
+ /requires gateway context/i,
112
+ // Same family as GatewayHandoffNeeded, raised as plain text by the bridge
113
+ // rather than as that error class.
114
+ /needs-gateway-handoff/i,
115
+ ];
116
+
117
+ export function isBreakerTrippingFailure(err) {
118
+ if (err instanceof NodeBlocked) return false;
119
+ if (err instanceof GatewayHandoffNeeded) return false;
120
+ const msg = err?.message ?? String(err ?? "");
121
+ return !NON_TRIPPING_REASONS.some((re) => re.test(msg));
122
+ }
@@ -0,0 +1,254 @@
1
+ // Pure stateless helpers — no closure deps, no factory required.
2
+
3
+ import { getAllSubflowGroups } from "../state/subflow-state.js";
4
+ import { replayResults } from "./result-replay.js";
5
+
6
+ // Edge functions come in two modes, dispatched by declared arity (same
7
+ // technique this file's own usesNamedParams() uses elsewhere):
8
+ // - direct edge (1 param): (state) => nextNodeId | null — unchanged,
9
+ // every edge in the codebase before this mode existed.
10
+ // - edge function (2 params): (state, error) => nextNodeId | null — opts
11
+ // into receiving the node's thrown error (a {message, errorType}
12
+ // object, or null if the node succeeded / hasn't run) as its 2nd arg.
13
+ // Lets a cascade's edge decide retry-vs-fallback-vs-give-up from the
14
+ // REAL thrown error instead of a soft-returned state field, per the
15
+ // "Eradicate soft errors" push.
16
+ // CAVEAT: a default value on the 2nd param (`(state, error = null) =>`)
17
+ // or a rest param collapses fn.length back down and silently falls back
18
+ // to direct-edge mode — no error ever passed. Don't do that.
19
+ export function resolveEdge(edges, fromNode, state, ctx = null) {
20
+ const edge = edges[fromNode];
21
+ if (typeof edge === "string") return edge;
22
+ if (typeof edge === "function") {
23
+ try {
24
+ return edge.length >= 2 ? edge(state, ctx?.error ?? null) : edge(state);
25
+ } catch (err) {
26
+ ctx?.logger?.warn?.(`manifold [${(ctx?.flowId ?? "?").slice(0, 8)}] edge ${fromNode} threw: ${err?.message ?? err}`);
27
+ return null;
28
+ }
29
+ }
30
+ return null;
31
+ }
32
+
33
+ export function isTerminal(status) {
34
+ return status === "succeeded" || status === "failed" || status === "cancelled" || status === "skipped";
35
+ }
36
+
37
+ export function isBlocked(status) {
38
+ // Despite its name, setWaiting() always writes status='blocked' — it
39
+ // never actually writes "waiting" (confirmed repo-wide), so that's the
40
+ // only value checked here.
41
+ return status === "blocked";
42
+ }
43
+
44
+ // A flow waiting on an internal resource (a shared admission-pool slot —
45
+ // child-dispatch, flow-start — or a cross-process lock)
46
+ // rather than an operator decision. Distinct from
47
+ // isBlocked so callers that mean "waiting on a human" don't accidentally
48
+ // also match resource-queued flows, and vice versa.
49
+ export function isQueued(status) {
50
+ return status === "queued";
51
+ }
52
+
53
+ // Determines whether entering `nodeId` is a genuinely fresh pass through
54
+ // this node, or a continuation of the SAME dispatch (a retry, a reentrant
55
+ // loop-wait re-check) — feeds node-executions.js's
56
+ // write()/findOrCreateInvocation()'s forceNew param.
57
+ // `lastNodeId` must come from nodeExecutions.findCurrentStep(flowId)
58
+ // called BEFORE this node's own dispatch decision was made — never a
59
+ // value re-read after execution starts, since a concurrent mutation there
60
+ // would reflect something unrelated to what led to THIS dispatch.
61
+ // findCurrentStep always reflects the PREVIOUSLY entered node (this
62
+ // node's own row is only created once the dispatch decision below is
63
+ // made) — if it matches nodeId itself, we're re-entering the exact node
64
+ // we just came from (continuation, e.g. an operator retry that rewinds
65
+ // lastStep but never creates a new invocation for the failed node, or a
66
+ // reentrant loop-wait re-check); anything else, including no prior
67
+ // invocation at all (lastNodeId === null), is a fresh pass (a real
68
+ // loop-back edge, or the first-ever entry).
69
+ export function isFreshNodeEntry(lastNodeId, nodeId) {
70
+ return lastNodeId !== nodeId;
71
+ }
72
+
73
+ export function mergeForConflict(fresh, mine) {
74
+ // Cheap merge: prefer "my" values, but keep any slot-keyed objects that
75
+ // fresh already has and I don't. Good enough for slot-per-item parallel writes.
76
+ if (!fresh || typeof fresh !== "object") return mine;
77
+ const out = { ...fresh, ...mine };
78
+ for (const [k, v] of Object.entries(fresh)) {
79
+ if (v && typeof v === "object" && !Array.isArray(v)
80
+ && mine[k] && typeof mine[k] === "object" && !Array.isArray(mine[k])) {
81
+ out[k] = { ...v, ...mine[k] };
82
+ }
83
+ }
84
+ return out;
85
+ }
86
+
87
+ export function withEditableTextDefault(payload, branchData) {
88
+ if (!payload || typeof payload !== "object") return payload;
89
+ if (payload.editableText !== undefined) return payload;
90
+ if (!branchData || typeof branchData !== "object") return payload;
91
+ let candidate;
92
+ for (const v of Object.values(branchData)) {
93
+ if (v && typeof v === "object" && typeof v.text === "string" && v.text.length > 0) {
94
+ candidate = v.text;
95
+ }
96
+ }
97
+ if (candidate === undefined) return payload;
98
+ return { ...payload, editableText: candidate };
99
+ }
100
+
101
+ export function shortSummary(text) {
102
+ if (!text) return "";
103
+ const oneLine = String(text).split("\n")[0];
104
+ return oneLine.length > 240 ? oneLine.slice(0, 237) + "..." : oneLine;
105
+ }
106
+
107
+ export function deepClone(v) {
108
+ return JSON.parse(JSON.stringify(v));
109
+ }
110
+
111
+ // Fallback reason for a blocked node whose result is a plain returned
112
+ // waitJson (no blockedInfo/throw — see executor.js's own waitJson-persist
113
+ // branch). node.renderForOperator is checked first; since no pipeline in
114
+ // this codebase implements it, this kind-aware synthesis is what actually
115
+ // fires in practice. Every OTHER wait kind (resource-lock,
116
+ // needs-gateway-handoff, pipeline-load-pending, budget-gate-approval)
117
+ // already carries a real reason by construction and never reaches this —
118
+ // only human-gate and children-pending route through the generic waitJson
119
+ // path, so those are the two kinds worth a specific message here.
120
+ export function describeWaitFallback(waitJson, nodeId) {
121
+ switch (waitJson?.kind) {
122
+ case "human-gate": {
123
+ const n = waitJson.pending?.length ?? waitJson.items?.length ?? 0;
124
+ return `awaiting ${n} approval${n === 1 ? "" : "s"} at ${nodeId}`;
125
+ }
126
+ case "children-pending": {
127
+ const n = waitJson.childFlowIds?.length ?? 0;
128
+ return `awaiting ${n} child flow${n === 1 ? "" : "s"} at ${nodeId}`;
129
+ }
130
+ default:
131
+ return `blocked at ${nodeId}`;
132
+ }
133
+ }
134
+
135
+ // Fail-fast check for one waitJson batch's items — called right before any
136
+ // waitJson (root-level human-gate, branch-internal loop aggregate, or a
137
+ // node's own `_blocked.items`) gets persisted. Every gate must declare its
138
+ // own `requestPayload.layout` array — there is no auto-synthesis from
139
+ // editableFields/editableText/chatThread/references fields,
140
+ // so an author who forgets `layout` gets a loud error here instead of an
141
+ // empty gate on any client. A `layout` containing kind:"deck" must have that as
142
+ // its ONLY entry (mixing a deck with other components is ambiguous —
143
+ // GateDeckView pages the WHOLE gate, there's nowhere for sibling
144
+ // components to render), and each deck question must be a well-formed
145
+ // {question, hint?} pair. Throws rather than degrading silently — both of
146
+ // these are always pipeline-author bugs, never legitimate runtime data
147
+ // shapes, so they should fail the node loudly at the source instead of
148
+ // shipping broken content to the client.
149
+ export function validateGateLayout(items) {
150
+ if (!Array.isArray(items)) return;
151
+ for (const item of items) {
152
+ const layout = item?.requestPayload?.layout;
153
+ const label0 = item?.itemId ?? "?";
154
+ if (!Array.isArray(layout)) {
155
+ throw new Error(`item ${label0}: requestPayload.layout must be an array — every gate declares its own layout explicitly, there is no editableFields/editableText/chatThread/references auto-synthesis`);
156
+ }
157
+ const deckItems = layout.filter((li) => li?.kind === "deck");
158
+ if (deckItems.length === 0) continue;
159
+ const label = item?.itemId ?? "?";
160
+ if (layout.length > 1) {
161
+ throw new Error(`item ${label}: layout mixes kind:"deck" with ${layout.length - 1} other item(s) — a deck must be the only layout entry`);
162
+ }
163
+ const deck = deckItems[0];
164
+ if (!Array.isArray(deck.questions) || deck.questions.length === 0) {
165
+ throw new Error(`item ${label}: deck "${deck.id}" must have a non-empty questions array`);
166
+ }
167
+ deck.questions.forEach((q, i) => {
168
+ if (!q || typeof q.question !== "string" || !q.question.trim()) {
169
+ throw new Error(`item ${label}: deck "${deck.id}" question ${i} is missing a non-empty "question" string`);
170
+ }
171
+ if (q.hint != null && typeof q.hint !== "string") {
172
+ throw new Error(`item ${label}: deck "${deck.id}" question ${i} has a non-string "hint"`);
173
+ }
174
+ });
175
+ }
176
+ }
177
+
178
+ export function detectBlockedSentinel(result) {
179
+ if (result && typeof result === "object" && result._blocked && typeof result._blocked === "object") {
180
+ return result._blocked;
181
+ }
182
+ return null;
183
+ }
184
+
185
+ // Returns true when an `apply` function was written with a single destructured
186
+ // parameter — `apply({ state, item, output }) => ...` — rather than positional args.
187
+ // Detected by checking that the first char after `(` is `{`.
188
+ export function usesNamedParams(fn) {
189
+ if (typeof fn !== "function" || fn.length !== 1) return false;
190
+ const src = fn.toString();
191
+ const paren = src.indexOf("(");
192
+ return paren >= 0 && /^\s*\{/.test(src.slice(paren + 1));
193
+ }
194
+
195
+ export function detectSkippedSentinel(result) {
196
+ if (result && typeof result === "object" && result._skipped && typeof result._skipped === "object") {
197
+ return result._skipped;
198
+ }
199
+ return null;
200
+ }
201
+
202
+ // Reconstructs the working `state` a node would see, by replaying
203
+ // flow_node_invocations' resultJson rows ON TOP OF `baseState` (the flow's
204
+ // own current stateJson), instead of relying purely on the persisted
205
+ // accumulated blob.
206
+ //
207
+ // `baseState` matters: state_json carries a fixed list of entry/bookkeeping
208
+ // fields (pipelineId, args, runId, startedAt, cost, _display, approvedIds/
209
+ // rejectedIds/editedTexts/approvalPending/approvalResults, _cascadeError,
210
+ // triggeredBy) that NO node's own stateUpdate ever produces, so resultJson
211
+ // replay alone can never reproduce them. Every real call site needs these
212
+ // (e.g. dispatchSubflowChildren reads state.pipelineId to build
213
+ // childPipelineId, and clones the whole state into every spawned child) —
214
+ // passing baseState:{} (kept for the existing validation script/tests)
215
+ // silently drops them, which is fine for comparing node-output keys in
216
+ // isolation but would break real dispatch.
217
+ //
218
+ // The overlay is additive, not a behaviour change: every node-output key
219
+ // resultJson can contribute is already present in state_json, verified
220
+ // byte-for-byte against a real flow. So nothing here depends on the replay
221
+ // to fix a wrong value today — it isolates node contributions, and the
222
+ // reconstructed state currently matches the blob it was derived from.
223
+ //
224
+ // Replays each top-level node's own contributed stateUpdate in
225
+ // chronological order via the exact same shallow-merge applyUpdate already
226
+ // does today (`{...state, ...update}`) — it replays the run's own node
227
+ // contributions in order, not a lookup of "the value of state[nodeId]": a
228
+ // node's resultJson is
229
+ // whatever object it returned from run()/apply(), which by convention is
230
+ // almost always `{[itsOwnNodeId]: {...}}` but isn't a guaranteed shape, so
231
+ // this merges it exactly the way the live engine already merges it rather
232
+ // than assuming a per-node key.
233
+ //
234
+ // Two things this deliberately does NOT do:
235
+ // - It does not try to synthesize a merged/aggregate value for a
236
+ // subflow-kind node's own state[nodeId]. dispatchSubflowChildren
237
+ // (executor-subflow-children.js) always returns stateUpdate: {} —
238
+ // there is no such value today, so assembly doesn't fabricate one.
239
+ // - Subflow results are read exclusively through _subflowGroups,
240
+ // computed by the same getAllSubflowGroups call this function already
241
+ // makes — folded into this one function instead of a second call site.
242
+ //
243
+ // writeResult() (state/node-executions.js) does not cap results (see its
244
+ // own header comment) — a node's real value is always what lands here. A
245
+ // `{ _resultTooLarge: true, bytes }` marker at a node's own key surfaces
246
+ // only for a row whose resultJson is null and whose resultTooLargeBytes is
247
+ // set — a result that was never stored, and is not recoverable.
248
+ export async function assembleState(flowId, { runStore, nodeExecutionsStore, baseState = {} } = {}) {
249
+ const results = (await nodeExecutionsStore?.listResultsForFlow?.(flowId)) ?? [];
250
+ let state = replayResults(baseState, results);
251
+ const groups = await getAllSubflowGroups({ flowId, runStore, nodeExecutionsStore });
252
+ if (Object.keys(groups).length > 0) state._subflowGroups = groups;
253
+ return state;
254
+ }
@@ -0,0 +1,292 @@
1
+ import { mkdir, writeFile, readFile } from "node:fs/promises";
2
+ import path from "node:path";
3
+ import os from "node:os";
4
+ import { NodeBlocked, GatewayHandoffNeeded, isBreakerTrippingFailure } from "./executor-errors.js";
5
+ import { detectBlockedSentinel, detectSkippedSentinel, assembleState } from "./executor-helpers.js";
6
+ import { makeNeedsCtx } from "./needs-resolver.js";
7
+
8
+ /**
9
+ * Factory for the node-execution dispatcher: code, agent, subflow, human-gate.
10
+ * The subflow branch is delegated to `executeSubflowNode`, a thin wrapper around
11
+ * `dispatchSubflowChildren` (engine/executor-subflow-children.js) constructed in
12
+ * executor.js.
13
+ *
14
+ * `getNodeCtx` is a getter closure that returns the frozen nodeCtx object (defined
15
+ * in executor.js after start/runFlow). It reads the binding at call time so it's
16
+ * safe to construct this factory before nodeCtx is assigned.
17
+ */
18
+ export function createNodeRunner({
19
+ maybeBudgetGate,
20
+ dispatchAgentWithRetry,
21
+ executeSubflowNode,
22
+ getNodeCtx,
23
+ api,
24
+ config,
25
+ lineage,
26
+ pipelinesDir,
27
+ logger,
28
+ runStore,
29
+ nodeExecutionsStore,
30
+ nodeHealthStore,
31
+ pipelinesRef,
32
+ }) {
33
+ // Explicit params win; api is the fallback the adapter still
34
+ // supplies (tests construct with api only).
35
+ const _lineage = lineage ?? api?.runtime?.lineage ?? null;
36
+ const _pipelinesDir = pipelinesDir ?? config?.pipelinesDir ?? null;
37
+ // Shared by the plain "code" branch below and by cascade sub-nodes of
38
+ // kind "code" (cascade sub-nodes dispatch through the ordinary "code"/
39
+ // "agent" branches in executeNodeBody). Returns the RAW result from
40
+ // `entry.run(...)`;
41
+ // sentinel detection (_blocked/_skipped) and stateUpdate wrapping is the
42
+ // caller's job.
43
+ async function dispatchCodeEntry(entry, { state, flowId, nodeId }) {
44
+ const flowId8 = flowId.slice(0, 8);
45
+ const artifactDir = state.runId && state.pipelineId && _pipelinesDir
46
+ ? path.join(_pipelinesDir, state.pipelineId, "runs", state.runId)
47
+ : null;
48
+ // Same pattern as executeSubflowNode's selector call in executor.js:
49
+ // assembleState(baseState: state). Every kind:"code" node's run() goes
50
+ // through this one call.
51
+ const enrichedState = await assembleState(flowId, { runStore, nodeExecutionsStore, baseState: state });
52
+ return entry.run(enrichedState, {
53
+ ...getNodeCtx(),
54
+ flowId,
55
+ nodeId,
56
+ pipelineId: state.pipelineId ?? null,
57
+ log: {
58
+ info: (msg) => logger?.info?.(`[${flowId8}] ${nodeId}: ${msg}`),
59
+ warn: (msg) => logger?.warn?.(`[${flowId8}] ${nodeId}: ${msg}`),
60
+ error: (msg) => logger?.error?.(`[${flowId8}] ${nodeId}: ${msg}`),
61
+ },
62
+ artifact: async (name, content) => {
63
+ if (!artifactDir) throw new Error("ctx.artifact: state.runId or state.pipelineId not set");
64
+ await mkdir(artifactDir, { recursive: true });
65
+ return writeFile(path.join(artifactDir, name), content, "utf8");
66
+ },
67
+ readArtifact: async (name) => {
68
+ if (!artifactDir) throw new Error("ctx.readArtifact: state.runId or state.pipelineId not set");
69
+ return readFile(path.join(artifactDir, name), "utf8");
70
+ },
71
+ blocked: (reason, hint) => { throw new NodeBlocked({ reason, hint }); },
72
+ // "needs:" resolution is lazy, only resolved if this node's own code
73
+ // actually awaits ctx.needs(varName); a NodeBlocked thrown here propagates
74
+ // straight up (no try/catch around entry.run() in this "code" branch
75
+ // — see executeNodeBody below) to executor.js's own catch, same path
76
+ // every other NodeBlocked already uses.
77
+ needs: makeNeedsCtx({ node: entry, flowId, runStore, nodeExecutionsStore, pipelinesRef }),
78
+ });
79
+ }
80
+
81
+ // Shared by the plain "agent" branch below and by cascade sub-nodes of
82
+ // kind "agent". `nodeId` is the id used for session-key derivation,
83
+ // lineage, and budget-gate scoping.
84
+ //
85
+ // No admission here: the admission pool governs flow runs, and the run
86
+ // executing this node already holds its own slot (flow-start/child-
87
+ // dispatch) for as long as it's running. A run executes one node at a
88
+ // time, so the run cap already bounds concurrent agent dispatches — a
89
+ // second slot taken mid-node from the same pool is what made hold-and-
90
+ // wait deadlock (keeping the run slot) or churn (giving it back) possible.
91
+ //
92
+ // Circuit breaker: an agent node opts in via `entry.circuitBreaker: true`,
93
+ // checked here regardless of which kind of flow it's running inside —
94
+ // generalist, not flow-kind-aware. Fails fast before doing any work (no
95
+ // prompt build, no session spawn) when already blocked, naming the reset
96
+ // command because a block has no expiry.
97
+ //
98
+ // Which failures are allowed to trip it is decided by
99
+ // isBreakerTrippingFailure (engine/executor-errors.js) rather than
100
+ // inlined here, so the rule sits beside the error classes it inspects.
101
+ async function dispatchAgentEntry(entry, nodeId, { state, flowId, reviveMessage, invocationId }) {
102
+ const pipelineId = state?.pipelineId ?? null;
103
+ // Anonymous dispatch is refused loudly: every agent turn is keyed to
104
+ // its agent for session attribution and push wake. No default, ever.
105
+ if (!entry.agent) {
106
+ throw new Error(`manifold: refusing anonymous dispatch of node "${nodeId}" (no entry.agent)`);
107
+ }
108
+ if (entry.circuitBreaker && await nodeHealthStore?.isBlocked(pipelineId, nodeId)) {
109
+ throw new Error(
110
+ `unhealthy agent dispatch: "${nodeId}" is blocked after a prior failure — reset via "openclaw manifold node-health reset ${pipelineId} ${nodeId}" once the underlying issue is confirmed fixed`
111
+ );
112
+ }
113
+ const gate = await maybeBudgetGate({
114
+ flowId, nodeId, node: entry,
115
+ pipelineId, pipelineName: pipelineId,
116
+ itemCount: 1,
117
+ });
118
+ if (gate.skip) return {};
119
+ if (gate.pause) {
120
+ // NodeBlocked's constructor only keeps {reason, needed, hint} — budget
121
+ // gate pauses carry a _kind ("budget-gate-approval") that downstream
122
+ // wait_json routing depends on, so preserve the full object on top.
123
+ const err = new NodeBlocked(gate.blockedInfo ?? {});
124
+ err._blocked = { ...(gate.blockedInfo ?? {}) };
125
+ throw err;
126
+ }
127
+ // promptBuilder reads via assembleState(baseState: state) rather than
128
+ // raw state — that's what makes _subflowGroups visible to an agent
129
+ // node's promptBuilder. Same lazy ctx.needs(varName) accessor code
130
+ // nodes get, passed as promptBuilder's 2nd arg (a single-arg
131
+ // promptBuilder ignores it). A thrown NodeBlocked here propagates out
132
+ // of dispatchAgentEntry uncaught (this call is deliberately outside the
133
+ // try/catch below, same as the gate.pause throw above) to
134
+ // executeNodeBody's own "agent" branch catch, which converts
135
+ // NodeBlocked into blockedInfo.
136
+ const enrichedState = await assembleState(flowId, { runStore, nodeExecutionsStore, baseState: state });
137
+ const message = reviveMessage ?? await Promise.resolve(entry.promptBuilder(enrichedState, { needs: makeNeedsCtx({ node: entry, flowId, runStore, nodeExecutionsStore, pipelinesRef }) }));
138
+ // Session ids belong to the harness, not manifold: pass a declared
139
+ // entry.session / entry.sessionBuilder through verbatim, and
140
+ // refuse an agent node that declares neither — tool-handoff and the
141
+ // lineage ledger both key off this value, so inventing one here would
142
+ // silently diverge from the harness's own id.
143
+ const session = entry.session
144
+ ?? entry.sessionBuilder?.(state, flowId)
145
+ ?? null;
146
+ if (!session) {
147
+ throw new Error(`manifold: refusing dispatch of node "${nodeId}" with no session (set entry.session or entry.sessionBuilder)`);
148
+ }
149
+ _lineage?.recordSpawn?.({
150
+ childSession: session, flowId, nodeId,
151
+ pipelineId, agentId: entry.agent ?? null,
152
+ });
153
+
154
+ try {
155
+ return await dispatchAgentWithRetry({
156
+ node: entry, nodeId, session, initialMessage: message,
157
+ applyCtx: state, applyExtraArg: undefined, flowId,
158
+ applyMeta: { flowId, nodeId, invocationId },
159
+ // apply() gets the same lazy ctx.needs() accessor every other
160
+ // call site gets.
161
+ needsCtx: makeNeedsCtx({ node: entry, flowId, runStore, nodeExecutionsStore, pipelinesRef }),
162
+ });
163
+ } catch (err) {
164
+ // Which failures may park a node, and why the excluded ones must not,
165
+ // is documented once on isBreakerTrippingFailure — not restated here.
166
+ if (entry.circuitBreaker && isBreakerTrippingFailure(err)) {
167
+ await nodeHealthStore?.markUnhealthy(pipelineId, nodeId, { reason: err?.message ?? String(err), flowId });
168
+ }
169
+ throw err;
170
+ }
171
+ }
172
+
173
+ /**
174
+ * Run the node body. A node that declares `crossProcessLock` is refused:
175
+ * the option is no longer supported.
176
+ */
177
+ async function executeNode({ node, nodeId, state, flowId, reviveMessage, invocationId }) {
178
+ if (typeof node.crossProcessLock === "string" && node.crossProcessLock) {
179
+ throw new Error(`manifold: node "${nodeId}" declares crossProcessLock "${node.crossProcessLock}" — the lock mechanism was removed; drop the option from the pipeline`);
180
+ }
181
+ return executeNodeBody({ node, nodeId, state, flowId, reviveMessage, invocationId });
182
+ }
183
+
184
+ // `reviveMessage`, when set, is used in place of node.promptBuilder(state)
185
+ // for an "agent" node — boot revival's continuation prompt to an existing
186
+ // session (see engine/revival-messages.js), never a fresh re-dispatch of
187
+ // the original task.
188
+ async function executeNodeBody({ node, nodeId, state, flowId, reviveMessage, invocationId }) {
189
+ if (node.kind === "code") {
190
+ const update = await dispatchCodeEntry(node, { state, flowId, nodeId });
191
+ const blocked = detectBlockedSentinel(update);
192
+ if (blocked) return { blockedInfo: blocked };
193
+ const skipped = detectSkippedSentinel(update);
194
+ if (skipped) return { skippedInfo: skipped };
195
+ return { stateUpdate: update ?? {} };
196
+ }
197
+
198
+ if (node.kind === "agent") {
199
+ let update;
200
+ try {
201
+ update = await dispatchAgentEntry(node, nodeId, { state, flowId, reviveMessage, invocationId });
202
+ } catch (err) {
203
+ if (err instanceof NodeBlocked) return { blockedInfo: err._blocked };
204
+ throw err;
205
+ }
206
+ const blocked = detectBlockedSentinel(update);
207
+ if (blocked) return { blockedInfo: blocked };
208
+ const skipped = detectSkippedSentinel(update);
209
+ if (skipped) return { skippedInfo: skipped };
210
+ return { stateUpdate: update ?? {} };
211
+ }
212
+
213
+ if (node.kind === "subflow") {
214
+ return executeSubflowNode({ node, nodeId, flowId, state });
215
+ }
216
+
217
+ if (node.kind === "human-gate") {
218
+ // Both pendingSelector and approvalRequestBuilder read via
219
+ // assembleState(baseState: state) rather than raw state.
220
+ //
221
+ // The two INTERNAL checks below (existingGate, openedAt
222
+ // preservation) deliberately do NOT read gates off enrichedState —
223
+ // state.gates is written by every gate node via a full-snapshot
224
+ // embed of the WHOLE shared key (required by state_json's own
225
+ // shallow-merge accumulation), so an earlier gate's resultJson row
226
+ // can go stale relative to a later gate and silently erase it on
227
+ // replay. gate_records (state/node-executions.js) sidesteps this
228
+ // entirely — one row per (flowId, nodeId), no shared key, no
229
+ // replay, so a direct point lookup is always correct. This is
230
+ // engine-internal bookkeeping, not a pipeline-authored-code read.
231
+ const enrichedState = await assembleState(flowId, { runStore, nodeExecutionsStore, baseState: state });
232
+ const pending = await Promise.resolve(node.pendingSelector(enrichedState));
233
+ if (!Array.isArray(pending) || pending.length === 0) {
234
+ // Gate satisfied — stamp consumedAt so consumption is observable
235
+ // (diagnostics, revival) even after wait_json is cleared.
236
+ const existingGate = await nodeExecutionsStore.getGateRecord(flowId, nodeId);
237
+ if (existingGate && !existingGate.consumedAt) {
238
+ const updated = { ...existingGate, consumedAt: Date.now() };
239
+ await nodeExecutionsStore.writeGateRecord(flowId, nodeId, updated);
240
+ return { stateUpdate: {} };
241
+ }
242
+ return { stateUpdate: {} };
243
+ }
244
+ const items = await Promise.all(pending.map(async (itemId) => {
245
+ const requestPayload = await Promise.resolve(node.approvalRequestBuilder(enrichedState, itemId));
246
+ return { itemId, requestPayload };
247
+ }));
248
+ const now = Date.now();
249
+ // Write the full gate payload into gate_records only, never to
250
+ // stateJson.gates[nodeId]: routes/runs.js sources .gates exclusively
251
+ // from gate_records, and a full-extension grep confirmed nothing else
252
+ // reads state.gates off state_json. openedAt is preserved across
253
+ // re-entries (partial decisions) so the record always reflects when
254
+ // the gate batch was first created.
255
+ const existingBeforeOpen = await nodeExecutionsStore.getGateRecord(flowId, nodeId);
256
+ const gateRecord = {
257
+ nodeId,
258
+ kind: "human-gate",
259
+ pending: items.map((it) => it.itemId),
260
+ items,
261
+ openedAt: existingBeforeOpen?.openedAt ?? now,
262
+ lastOpenedAt: now,
263
+ };
264
+ await nodeExecutionsStore.writeGateRecord(flowId, nodeId, gateRecord);
265
+ const waitJson = {
266
+ kind: "human-gate",
267
+ nodeId,
268
+ pending: gateRecord.pending,
269
+ items,
270
+ renderedAt: now,
271
+ };
272
+ return {
273
+ stateUpdate: {},
274
+ waitJson,
275
+ // Without this, executor.js's waitJson-persist branch stamps
276
+ // lastStep to THIS node's own id (nextNodeId) instead of
277
+ // preserving the predecessor's — so a resume after a PARTIAL
278
+ // decision (pendingSelector still non-empty) would read lastStep
279
+ // as "already past this gate" and evaluate its outgoing edge
280
+ // instead of re-invoking pendingSelector, silently advancing
281
+ // past any still-undecided items. The children-pending path in
282
+ // executor-subflow-children.js sets the same flag for the same
283
+ // reason: neither has actually advanced past its own node.
284
+ reentrant: true,
285
+ };
286
+ }
287
+
288
+ throw new Error(`unknown node kind: ${node.kind}`);
289
+ }
290
+
291
+ return { executeNode, executeNodeBody };
292
+ }