@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
package/README.md CHANGED
@@ -1,3 +1,1584 @@
1
- # Temporary Holding Version
1
+ # manifold
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ LangGraph-style pipeline runtime. The engine runs as its own process
4
+ (`manifold serve`: HTTP API, executor, dashboard, plus an MCP server for
5
+ tools); the openclaw adapter (`plugins/openclaw/manifold`) starts it,
6
+ supervises it, and bridges agent turns back into the gateway. This README is written
7
+ for LLM agents doing engineering work in this plugin or building new
8
+ pipelines that target it.
9
+
10
+ **Source and install.** Install/update a release with
11
+ `openclaw plugins install npm:@igorjpimenta/manifold-openclaw@<version> --force --accept-capabilities`
12
+ (see `RELEASING.md` for the release process).
13
+ Development clone: `~/.dev/job/igorpimenta/manifold`. Story worktrees are
14
+ created at `<clone>/.doppler/worktrees/<story>`, and each story ships as its
15
+ own PR (base `feat/plugin`).
16
+
17
+ ## Public API
18
+
19
+ Consumers (oc-config, and later stories) install this repo as the
20
+ `@igorjpimenta/manifold` git dependency and import **only** through these
21
+ subpaths. Deep file paths are not a contract — only this table is.
22
+
23
+ | Subpath | Exports | Consumed by |
24
+ | --- | --- | --- |
25
+ | `@igorjpimenta/manifold` | plugin entry (default) | openclaw runtime |
26
+ | `…/errors` | `NodeFailure`, `NodeBlocked`, `GatewayHandoffNeeded`, error classifiers | oc-config |
27
+ | `…/elevation` | `invokeElevated` | oc-config |
28
+ | `…/digest` | `sendDigestPush`, `configureApi` | oc-config |
29
+ | `…/tool-handoff` | structured result rendezvous (`writePendingResult`, `readPendingResult`, `clearPendingResult`, `waitForToolResult`) | oc-config |
30
+ | `…/routes/bearer-auth` | `authorizeBearerRequest`, `sendUnauthorized` (MANIFOLD_BEARER, winch-style) | sibling extension |
31
+ | `…/state/db` | `openDb`, `getSharedDb`, `withSharedWrite`, `isSqliteBusy` | sibling extension (shared `runtime.sqlite`) |
32
+ | `…/state/batch-writer` | `enqueue`, `enqueueRaw`, `flush`, `flushAll` | sibling extension |
33
+ | `…/state/schema` | drizzle tables (`flowRuns`, `flowNodeExecutions`, …) | sibling extension |
34
+
35
+ The map is pinned by `test/unit/api/public-exports.test.js`; adding or
36
+ removing an entry is a breaking change for the consumers above.
37
+
38
+ Two companion docs hold deep-dive material split out of this file to keep
39
+ it focused on orientation and quick reference:
40
+
41
+
42
+ ## Index
43
+
44
+ - [Quick orientation](#quick-orientation)
45
+ - [Glossary](#glossary)
46
+ - [Run lifetime](#run-lifetime)
47
+ - [Pipeline schema (canonical)](#pipeline-schema-canonical)
48
+ - [Common author mistakes](#common-author-mistakes-read-this-before-writing-a-pipeline)
49
+ - [Node kinds](#node-kinds)
50
+ - [Subflow nodes (childFlows)](#subflow-nodes-childflows)
51
+ - [Node authoring reference](#node-authoring-reference)
52
+ - [Groups (compound parents in the dashboard)](#groups-compound-parents-in-the-dashboard)
53
+ - [Conventions](#conventions-and-what-breaks-if-you-violate-them)
54
+ - [Session keys (agent nodes dispatched by manifold)](#session-keys-agent-nodes-dispatched-by-manifold)
55
+ - [State conventions](#state-conventions)
56
+ - [Status transitions](#status-transitions)
57
+ - [CLI](#cli)
58
+ - [Tool surface (agent-facing)](#tool-surface-agent-facing)
59
+ - [Dashboard](#dashboard)
60
+ - [Declared views (embed-view pattern)](#declared-views-embed-view-pattern)
61
+ - [Common tasks](#common-tasks)
62
+ - [If you see…](#if-you-see)
63
+ - [Operational quirks](#operational-quirks)
64
+ - [Plugin config (default values)](#plugin-config-default-values)
65
+ - [SQLite shape (for direct queries / surgery)](#sqlite-shape-for-direct-queries--surgery)
66
+
67
+ ## Quick orientation
68
+
69
+ > **One-line model:** A `Pipeline` is `{ nodes, edges, state }` loaded
70
+ > from a JS module. A `Flow` is one persistent run of a pipeline. The
71
+ > `Executor` walks nodes by id, applies their `stateUpdate`, picks the
72
+ > next id from `edges[currentId](state)`, persists every revision to
73
+ > sqlite, and exits the loop on terminal/blocked status.
74
+
75
+ | You need… | Look at |
76
+ | --------------------------------------- | ---------------------------------------------- |
77
+ | Plugin entry (wires everything) | `index.js` |
78
+ | Run loop / node dispatch | `executor.js: runFlow`, `runStep` |
79
+ | Pipeline file discovery + validation | `loader.js` |
80
+ | sqlite persistence (`flow_runs` table) | `state-store.js` |
81
+ | CLI command implementations | `cli.js` |
82
+ | Agent-facing tools | `tool.js` |
83
+ | Approval helpers (CLI + dashboard) | `gates.js` |
84
+ | Dashboard server | `dashboard/server.js` |
85
+ | Dashboard frontend | `dashboard/src/` |
86
+ | Plugin manifest (tools + config schema) | `openclaw.plugin.json` |
87
+
88
+ ## Glossary
89
+
90
+ | Term | Meaning |
91
+ | --------------- | ------------------------------------------------------------------------------------ |
92
+ | **pipeline** | Static definition: `{ id, goal, state, nodes, edges, groups? }` exported by a module. |
93
+ | **node** | One unit of work. Identified by its key in `pipeline.nodes`. Has a `kind`. |
94
+ | **edge** | `(state) => nextNodeId`. Lives in `pipeline.edges[fromNodeId]`. Pure function. |
95
+ | **flow** | One persistent run of a pipeline. Identified by `flowId` (UUID). |
96
+ | **state** | Mutable JSON for a single flow. Persisted with every revision. |
97
+ | **revision** | Monotonic counter. Increments every time a node returns a `stateUpdate`. |
98
+ | **wait** | `flow.waitJson` is set; flow is `blocked` or `waiting`. Resumed by external action. |
99
+ | **session** | One agent conversation. Owned by a harness agent. See *Session keys* below. |
100
+ | **item key** | Slug identifying one item inside a `subflow` fan-out. |
101
+
102
+ ## Run lifetime
103
+
104
+
105
+ A flow is created `running` at `__start__` (`store.create`). The executor
106
+ loop repeatedly resolves `edges[lastStep](state)` to the next node id,
107
+ dispatches it per its `kind` (`code` runs `node.run`; `agent` builds a
108
+ prompt and dispatches an agent turn; `subflow` fans `.selector(state)` out
109
+ into real child `flow_runs`, one per item, and blocks until every sibling
110
+ is terminal; `human-gate` builds `waitJson` and blocks), and persists the
111
+ outcome — a `stateUpdate` advances and loops again, a thrown error or
112
+ `_error` sentinel fails/blocks the flow, `__end__` runs `runAudit` and
113
+ writes the terminal status (`succeeded`/`failed`/`skipped`). Blocked flows
114
+ resume via `POST /manifold/resume-from-gate`; any non-terminal flow can be
115
+ cancelled by an operator.
116
+
117
+ ## Pipeline schema (canonical)
118
+
119
+ ```js
120
+ // ~/.openclaw/workspace/.pipelines/<pipelineId>/index.js
121
+ export default {
122
+ id: "my-pipeline", // string, file-system safe
123
+ goal: "one-line description", // shown in the dashboard
124
+ state: { /* initial state shape */ }, // merged with args at start
125
+ nodes: {
126
+ NODE_A: { kind: "code", run: (state) => ({ /* stateUpdate */ }) },
127
+ NODE_B: {
128
+ kind: "agent",
129
+ agent: "scout",
130
+ promptBuilder: (state) => "…", // string returned to the agent
131
+ applyResult: (state, output) => ({ /* stateUpdate */ }),
132
+ },
133
+ },
134
+ edges: {
135
+ __start__: () => "NODE_A", // first hop, always required
136
+ NODE_A: (s) => s.cond ? "NODE_B" : "__end__",
137
+ NODE_B: () => "__end__",
138
+ },
139
+ // Optional. Logical groupings the dashboard renders as compound parents.
140
+ groups: {
141
+ SCAN: { label: "scan", kind: "pair",
142
+ members: ["SCAN_CODE", "SCAN_AGENT"] },
143
+ },
144
+ // Optional. Pipeline-declared dashboard surfaces (see "Declared views" below).
145
+ views: [
146
+ { id: "outcomes", kind: "funnel", label: "outcomes (last 30d)",
147
+ source: { kind: "frontmatter-dir", path: SENT_DIR, timeField: "sent-at" },
148
+ stages: [
149
+ { id: "sent", label: "sent" },
150
+ { id: "replied", label: "replied", outcomeIn: ["replied", "won"] },
151
+ { id: "won", label: "won", outcomeEq: "won" },
152
+ ] },
153
+ ],
154
+ };
155
+ ```
156
+
157
+ **Required exports:** `id`, `state`, `nodes`, `edges`. Validation rules
158
+ in `loader.js:80-130`.
159
+
160
+ **Reserved node ids:** `__start__`, `__end__`. Never appear in `nodes`;
161
+ must appear in `edges` (at least `__start__`).
162
+
163
+ ### Optional: `kind: "cascade"` — retry-on-failure as a flow characteristic
164
+
165
+ A flow-level (not node-level) `kind`, orthogonal to node `kind`. Declared
166
+ either directly on a top-level pipeline (`export default { id, kind:
167
+ "cascade", ... }`) or on a `subflow` node's `.flow.kind` — the loader
168
+ copies it onto the synthesized child pipeline exactly like it copies
169
+ `nodes`/`edges`, so a single step of a bigger pipeline can be isolated
170
+ into its own cascade-kind subflow.
171
+
172
+ The mechanic (`executor.js`'s catch block): in a cascade-kind flow, ANY
173
+ throw is treated like a completed dispatch, not a failure. `lastStep`
174
+ advances to the node that just threw (the failure itself is still
175
+ durably recorded via the normal execution-write path), and the loop
176
+ `continue`s — so on the very next pass it's **that node's own edge
177
+ function** that decides what happens next, exactly the way it would
178
+ after a success (typically by checking presence/absence of its own
179
+ output in `state`). There is no separate "retry from start" reset and no
180
+ engine-level "terminal" check: an edge function that has exhausted every
181
+ option it wants to try simply returns no next node, which the
182
+ existing `!nextNodeId` → `persistFailRetrying` path already handles
183
+ — giving up is just an ordinary edge decision, not a special case.
184
+
185
+ ```js
186
+ // A minimal cascade: CODE_LOGIN throws once, its own edge escalates to
187
+ // AGENT_LOGIN; if AGENT_LOGIN also throws, its edge gives up (returns
188
+ // no next node) and the flow fails normally.
189
+ export default {
190
+ id: "ensure-login",
191
+ kind: "cascade",
192
+ state: {},
193
+ nodes: { CODE_LOGIN, AGENT_LOGIN },
194
+ edges: {
195
+ __start__: (state) => (state.AGENT_LOGIN ? "__end__" : "CODE_LOGIN"),
196
+ CODE_LOGIN: (state) => (state.CODE_LOGIN ? "__end__" : "AGENT_LOGIN"),
197
+ AGENT_LOGIN: (state) => (state.AGENT_LOGIN ? "__end__" : null), // give up
198
+ },
199
+ };
200
+ ```
201
+
202
+ Author-side responsibilities: exhaustion (when to stop trying and let
203
+ the flow fail) and any retry-count cap are entirely up to the edge
204
+ functions — nothing bespoke is needed since `state/node-executions.js`'s
205
+ `queryErrorsByFlow`/`queryByNode` already let an edge consult prior
206
+ attempts on this flow if it needs more than presence/absence in `state`.
207
+
208
+ **`NodeFailure` and 2-arg edge functions** (`engine/executor-errors.js`,
209
+ `engine/executor-helpers.js`'s `resolveEdge` — "Eradicate soft errors"):
210
+ a cascade node's own `run()`/`apply()`
211
+ throws `NodeFailure(message, { errorType })` instead of soft-returning
212
+ `{ok: false, error_type}` on failure — `errorType` reuses the existing
213
+ vocabulary (`never_attempted | confirmed_absent | inconclusive |
214
+ infra_unavailable | blocked`, or `null` for classification-less failures).
215
+ Any plain `Error` works too; `errorType` is just `null` in that case.
216
+
217
+ An edge function may opt into receiving that thrown error as a **second
218
+ parameter** — `resolveEdge` dispatches on `fn.length`: a 2-arg edge
219
+ `(state, error) => next` gets `{message, errorType}` (or `null` on a
220
+ successful dispatch); a 1-arg edge `(state) => next` is unaffected, the
221
+ default and still the overwhelming majority of edges in this codebase.
222
+ This is purely additive — no existing edge needed to change.
223
+
224
+ ```js
225
+ // CODE's own edge routes on the REAL thrown error, not a soft field —
226
+ // give up immediately on a genuine confirmed-absent/inconclusive outcome,
227
+ // fall through to an agent-fallback leg for anything else.
228
+ edges: {
229
+ CODE: (state, error) => {
230
+ if (state.CODE?.ok) return "__end__";
231
+ if (error?.errorType === "inconclusive") return null;
232
+ if (error?.errorType === "infra_unavailable") return "ENSURE_INFRA";
233
+ return "AGENT_FALLBACK";
234
+ },
235
+ },
236
+ ```
237
+
238
+ **Caveat — a real footgun**: a default value (`(state, error = null) => ...`)
239
+ or a rest param collapses `fn.length` back down, silently falling to
240
+ 1-arg mode with no error at all. Declare the parameter plainly.
241
+
242
+ **Attempt counting across dispatches**: there is no supported built-in way
243
+ to do this today. `_stepHistory` is not a `state_json` field, and nothing
244
+ provides it for pipeline-author use (`ctx` exposes no execution-count
245
+ accessor, and `assembleState()` never adds one to `state`). A
246
+ `NodeFailure` throw also never merges `state[nodeId]`, so a self-tracked
247
+ counter on the throwing node's own output can't survive a failing attempt
248
+ either — the same "no room for an arbitrary counter" problem this section
249
+ already calls out. An `infra_unavailable` failure ends a cascade
250
+ directly, same as any other failure class, and the operator retries
251
+ manually via the flow's own Retry action once infra is actually healthy.
252
+ If a pipeline genuinely needs a bounded automatic retry count, the only
253
+ sound pattern is a sibling `code` node in the same cascade that never
254
+ throws and always merges into `state` on every pass — have *that* node's
255
+ own `run()` increment its own attempts field, and have the throwing
256
+ node's edge read that (capped) instead of trying to count its own
257
+ dispatches or looping unconditionally.
258
+
259
+ **Generalized engine-wide**: every `kind:"agent"` node's `node.retry`
260
+ config is inert — `dispatchAgentWithRetry` (`engine/agent-dispatch.js`)
261
+ does not retry, for any agent dispatch, anywhere. Every agent node is a
262
+ single attempt; a failure throws immediately, records as a normal failure
263
+ event, and the operator retries manually — no exceptions, no per-node
264
+ opt-out. Any `retry: {...}` left on a node definition is ignored.
265
+
266
+ **Presence-check pattern for a single-outcome leg**: when a leg either
267
+ throws or returns real payload data with no need to classify *why* it
268
+ failed (an agent-fallback entry whose own `apply()` throws rather than
269
+ soft-returning an error field, say), its edge collapses to a presence
270
+ check: `(state) => (state.AGENT_ID !== undefined ? "__end__" : null)` — a
271
+ throw never merges `state[nodeId]`, so presence alone (any shape) is the
272
+ success signal.
273
+
274
+ ### Optional: `recoveryActions`
275
+
276
+ Pipelines can declare custom operator-recovery actions surfaced on the
277
+ operator Failures inbox. Each entry is a `kind` (URL slug + dispatch
278
+ key) → descriptor + handler. The framework merges these with three
279
+ always-on defaults (`retry`, `ignore`, `unignore`) and exposes the
280
+ result per failure row as `available_actions[]`; clients render verbatim,
281
+ no pipeline-id awareness.
282
+
283
+ ```js
284
+ recoveryActions: {
285
+ skip: {
286
+ label: "Skip",
287
+ icon: "tray.and.arrow.down.fill", // SF Symbol — rendered verbatim by clients that support them
288
+ tint: "danger", // info | warning | danger | neutral
289
+ destructive: true, // optional; UI may confirm before firing
290
+ requiresBranch: true, // optional; hides on flow-level failures
291
+ appliesTo: ["skip-only", "redraft", "investigate"], // recovery_hint filter
292
+ handler: async ({ failure, body, api, logger }) => {
293
+ // failure : the failure_events row (see SQLite shape below)
294
+ // body : parsed JSON POST body (e.g. { via?, reason? })
295
+ // returns : { ok: true, ...arbitrary } or throws
296
+ },
297
+ },
298
+ },
299
+ ```
300
+
301
+ **Kinds reserved for the framework:** `retry`, `ignore`, `unignore`.
302
+ Pipelines that declare these are silently dropped from the merge — use
303
+ custom kinds (`skip`, `archive`, `mark-spam`, whatever your pipeline's
304
+ semantic is).
305
+
306
+ **Auto-resolve:** after a custom handler succeeds, the framework
307
+ resolves any open failure rows for the same `(pipeline_id,
308
+ branch_item_id)` tuple with `resolved_via = "auto:operator-<kind>"` —
309
+ pipelines don't have to touch the failure store themselves.
310
+
311
+ Live example: `freelance_workana-proposal/index.js`'s `skip` handler
312
+ writes `workspace/.shared/freelance/workana/skipped/<jobId>.md` so
313
+ future FILTER passes exclude the listing. Implementation lives in
314
+ `recovery-actions.js` (descriptor merge + handler lookup); HTTP
315
+ dispatch in `index.js: /manifold/failures/<id>/action/<kind>`.
316
+
317
+ ## Common author mistakes (read this before writing a pipeline)
318
+
319
+ If you've written pipelines for other graph runtimes (LangGraph, n8n, Airflow, etc.), some of manifold's names and call conventions will not be what you expect. The loader catches the structural mistakes; the runtime catches the rest. Skim this table first — every row below has been hit by a real author shipping a real pipeline.
320
+
321
+ | Wrong | Right | What breaks |
322
+ |---|---|---|
323
+ | `initialState: () => ({...})` | `state: { ...staticShape }` | Loader error: `missing .state`. Runtime fills `runId`, `startedAt`, etc. itself — your static shape is merged with run args at flow start. |
324
+ | `subflow: { subgraph: { nodes, edges } }` | `subflow: { flow: { nodes, edges } }` | Loader error: `node X (subflow) missing .flow`. |
325
+ | `description: "..."` (top-level) | `goal: "..."` | Silently ignored — dashboard renders `goal`. Cosmetic only, but the pipeline list looks empty. |
326
+ | `buildBrief: ({ state, item }) => "string"` | `promptBuilder: (state) => "string"` | Runtime calls `node.promptBuilder(state)` positionally, always single-arg — your function gets `state` not `{state, item}`. Subagent receives garbage. Inside a `subflow` sub-node, the item is `state.item`, not a second argument. |
327
+ | `apply: ({ state, output }) => ({...})` (object destructure) | `apply: (state, output) => ({...})` | Same as above — runtime calls positionally, always `(state, output)`, whether the node is top-level or a `subflow` sub-node (`applyResult` also accepted for `agent` kind). There is no `subCtx` and no 3-arg form — a `subflow` sub-node is dispatched exactly like a top-level node; the item lives at `state.item`. |
328
+ | Gate node with `apply: …`, `buildPayload: …`, `delivery: …`, `buttons: […]` | Gate node with `approvalRequestBuilder: (state, itemId) => ({title, description})` only | Gate's apply path is owned by `gate-resolver.js` (a consumer bridge wires the callback). A decision lands in `state.approvedIds`/`state.rejectedIds` (or `state.approvalPending[itemId]` mid-flight) — read it in your edge function, e.g. `edges.GATE: (state) => state.approvedIds?.includes(state.item?.id) ? "STAMP" : "STAMP_REJECT"`. |
329
+ | Edge function reads `flow.data` or a `subCtx` argument inside a `subflow` sub-node | Edge function reads `state` directly — same as top-level | There is no `subCtx`. Inside a subflow sub-node: `edges.GATE: (state) => state.GATE?.decision === "approve" ? "STAMP" : "__end__"` (or read `state.approvedIds`, per the row above) — the subflow item is `state.item`. |
330
+ | Fallback pair declared via naming convention only | Add a `groups:` entry tying the pair | The dashboard won't render them as a compound parent. See *Groups (compound parents in the dashboard)* below. |
331
+ | Node id with hyphen (`send-cr`) | Node id with underscore/upper (`SEND_CR`) | See *Node IDs are token-style — no hyphens* below. |
332
+
333
+ ### What the validator catches (loader.js)
334
+
335
+ These are hard-stops at pipeline load time — the gateway log shows `manifold loader: <id>/ failed to load: <reason>`:
336
+
337
+ | Loader error | Fix |
338
+ |---|---|
339
+ | `pipeline must export an object` | `export default { ... }` — not a class, not a function. |
340
+ | `missing .id` | Add `id: "team_name"` at the top of the export. |
341
+ | `missing .state` | Use `state: { ...staticShape }`, not `initialState`. |
342
+ | `missing .nodes` | Provide `nodes: { ... }` even for one-node pipelines. |
343
+ | `missing .edges` | Provide `edges: { __start__: (s) => "FIRST_NODE", ... }`. |
344
+ | `edges must define __start__` | Always wire `__start__` to your first node. |
345
+ | `node "X" has unknown kind "Y"` | Use one of: `code`, `agent`, `subflow`, `human-gate`. |
346
+ | `node "X" (subflow) missing .flow` | Use `flow: { nodes, edges }`, NOT `subgraph:`. |
347
+ | `node "X" .flow.edges must define __start__` | Inner flow needs its own `__start__` edge — wire it to the first per-item sub-node. |
348
+
349
+ ### What only the runtime catches
350
+
351
+ Past the loader, these only surface during a real flow:
352
+
353
+ - **`approvalRequestBuilder` returning a non-object** — runtime can't serialize it for delivery. Return `{ title, description }` at minimum.
354
+ - **`promptBuilder` returning a non-string** — the agent will see `[object Object]`. Stringify your inputs into a prompt.
355
+ - **`apply` returning a non-object** — runtime expects a `stateUpdate`, wrapped under your own node id, whether the node is top-level or a `subflow` sub-node (see *Subflow nodes (childFlows)*). Returning `null` or `undefined` is fine (no update). Returning a number / string throws.
356
+ - **`pendingSelector` for `gate`/`human-gate` returning items that don't match what the operator's decision keys against** — gate-resolver can't map decisions back to items. For a `subflow`'s own gate sub-node, this means returning something other than `state.item?.id` (a childFlows child is always exactly one item).
357
+ - **Forgetting `itemKey` on `subflow` when the item's natural key isn't `.id`/`.listingId`** — `deriveSubflowKey` falls through to `String(item)`, which is almost never what you want for an object. See *Deriving `subflowKey`*.
358
+
359
+ ### Two gotchas that *look* like bugs but aren't
360
+
361
+ These cost an authoring session each. Worth knowing.
362
+
363
+ #### Edge functions: dashboard parses the source, not the runtime value
364
+
365
+ The dashboard graph view (`dashboard/pipeline-graph.js`) extracts edge targets by **regex-matching literal node-id strings in the edge function source code**. It cannot follow closure variables, imported constants, or template-string interpolation. If you write:
366
+
367
+ ```js
368
+ // Closure variable — invisible to dashboard
369
+ import { buildPrimeNodes } from "./lib/prime-nodes.js";
370
+ const nextNodeId = "ENSURE_LOGIN_CODE";
371
+ const edges = {
372
+ PRIME_SCAN: (state) => state.done ? "PRIME_FILL" : nextNodeId, // ← dashboard sees PRIME_FILL only
373
+ };
374
+ ```
375
+
376
+ …only the `"PRIME_FILL"` literal is detected — the closure variable disappears. The runtime still routes correctly, but the dashboard graph shows the edge as a dead end (or as `→ ?`).
377
+
378
+ **Fix:** keep both target ids as literal strings in the edge function body:
379
+
380
+ ```js
381
+ const edges = {
382
+ PRIME_SCAN: (state) => state.done ? "PRIME_FILL" : "ENSURE_LOGIN_CODE", // ← both visible
383
+ };
384
+ ```
385
+
386
+ Factories that compute targets should return only nodes; let each pipeline define its own edges so the literals live in the pipeline source.
387
+
388
+ #### Pipeline reload only refreshes `index.js`, not its `file:///` imports
389
+
390
+ The pipelines-watcher reloads each pipeline's `index.js` via a `data:` URL (forces a fresh import per the comment in `loader.js`). But the pipeline's `import { ... } from "file:///.../lib/foo.js"` statements go through Node's normal ESM loader — and **Node caches modules by URL forever within a process**. Edits to shared `lib/` files used by pipelines won't take effect until you restart the gateway.
391
+
392
+ **Fix:** restart the gateway after editing any `lib/` file:
393
+
394
+ ```sh
395
+ launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
396
+ launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist
397
+ ```
398
+
399
+ If you only edit a pipeline's own `index.js`, the watcher handles the reload — no restart needed.
400
+
401
+ ### Recommended skeleton (copy this and modify)
402
+
403
+ ```js
404
+ import path from "node:path";
405
+ import os from "node:os";
406
+
407
+ const ROOT = path.join(os.homedir(), ".openclaw");
408
+
409
+ export default {
410
+ id: "myteam_my-flow",
411
+ goal: "one-line description shown in the dashboard",
412
+ // Identity surfaces wherever the pipeline shows up in operator UIs.
413
+ // emoji — dashboard headers, consumer notifications, Live Activity widgets
414
+ // sfSymbol — Inbox pipeline-row icon (any valid SF Symbol name; see
415
+ // Apple's SF Symbols app). Falls back to "tray.fill" when
416
+ // omitted, so this field is optional but recommended.
417
+ // displayName — human label used everywhere a pipeline is named.
418
+ identity: { emoji: "🧩", sfSymbol: "puzzlepiece.fill", displayName: "My flow" },
419
+ schedule: ["0 9 * * *"], // optional cron(s), GMT-3 if your gateway is in BR
420
+
421
+ // Static state shape. Merged with run args at flow start. Don't add an
422
+ // `errors` array here — errors are never a stateJson field; every node
423
+ // failure is recorded to flow_node_executions and served as the
424
+ // top-level errorEntries[] (see State conventions below).
425
+ state: {
426
+ items: [],
427
+ parallel: {},
428
+ },
429
+
430
+ nodes: {
431
+ PRIME: {
432
+ kind: "code",
433
+ run: async (state) => ({ primedAt: Date.now() }),
434
+ },
435
+ SCAN: {
436
+ kind: "agent",
437
+ agent: "marketplace-scout",
438
+ skill: "scan-some-source",
439
+ promptBuilder: (state) => `Scan and return JSON. Context: ${state.runId}`,
440
+ apply: (state, output) => ({ items: JSON.parse(output.text) }),
441
+ },
442
+ // subflow nodes fan out into real child flows — see "Subflow nodes
443
+ // (childFlows)" below for the full authoring guide. Never set
444
+ // .groupId; it's always the node's own id ("PROCESS" here).
445
+ PROCESS: {
446
+ kind: "subflow",
447
+ itemKey: "id",
448
+ selector: (state) => state.items ?? [],
449
+ flow: {
450
+ nodes: {
451
+ WRITE: {
452
+ kind: "agent",
453
+ agent: "content-writer",
454
+ promptBuilder: (state) => `Process item ${state.item?.id}.`,
455
+ apply: (state, output) => ({ WRITE: { ...state.item, result: output.text } }),
456
+ },
457
+ },
458
+ edges: {
459
+ __start__: "WRITE",
460
+ WRITE: "__end__",
461
+ },
462
+ },
463
+ },
464
+ },
465
+
466
+ edges: {
467
+ __start__: () => "PRIME",
468
+ PRIME: "SCAN",
469
+ SCAN: (state) => (state.items?.length ? "PROCESS" : "__end__"),
470
+ PROCESS: "__end__",
471
+ },
472
+
473
+ // Optional. Tie code+agent pairs together for the dashboard.
474
+ groups: {
475
+ SCAN_GROUP: { label: "scan", kind: "pair", members: ["SCAN", "SCAN_AGENT"] },
476
+ },
477
+
478
+ // Optional. Run-summary writer.
479
+ runAudit: {
480
+ runsDir: path.join(ROOT, "workspace", ".pipelines", "myteam_my-flow", "runs"),
481
+ summarize: (state) => ({
482
+ runId: state.runId,
483
+ items: state.items?.length ?? 0,
484
+ processed: state.processed?.length ?? 0,
485
+ }),
486
+ },
487
+ };
488
+ ```
489
+
490
+ ## Node kinds
491
+
492
+ | `kind` | Required fields | Returns | Exits to |
493
+ | ------------------- | ------------------------------------------------------------------------------------ | ---------------------- | ----------------------------------------- |
494
+ | `code` | `run(state, ctx) => stateUpdate \| Promise<stateUpdate>` — `ctx` exposes `invokePipeline` (see below) | `stateUpdate` | normal edge |
495
+ | `agent` | `agent`, `promptBuilder(state)`, `applyResult(state, output)`. Optional `circuitBreaker: true` — see *Circuit breaker* below. | `stateUpdate` | normal edge |
496
+ | `subflow` | `selector(state) => Item[]`, `flow: { nodes, edges }` (required — no other shape). Never set `.groupId` — it's always the node's own id; the loader throws if you set it. See *Subflow nodes (childFlows)* below for the full authoring guide. | one real child `flow_runs` per item; parent blocks (`waitJson.kind:"children-pending"`) until every sibling child is terminal, then auto-resumes **if `mode` is satisfied** — otherwise the parent is failed directly, with a real retryable `failure_events` row | normal edge, once all children terminal and `mode` satisfied |
497
+ | `human-gate` | `pendingSelector(state) => Item[]`. Each item is `string` *or* `{ id: string, reason?, hint?, text?, editable? }` — see *Human-gate pending item shape* below | sets `waitJson`; flow → `blocked` | resumes via CLI `approve` / `respond` *or* dashboard GateForm |
498
+ | `gate` | `pendingSelector` + `approvalRequestBuilder`. Channel-agnostic per-item gate. Delivery is consumer-side: the gateway broadcasts `manifold.gate.opened` / `manifold.gate.closed` over WS with the full payload, and each consumer decides how to surface it (inbox, Live Activity, …). Optional `discuss: { agent, promptBuilder }` opts the gate into a discuss surface — see *Per-gate discuss opt-in*. | sets `waitJson` (`pending: string[]`, `items: [{itemId, requestPayload}]`) | resumes via any channel's resolver call into `gate-resolver.recordItemDecision` |
499
+
500
+ A `code`-then-`agent` fallback (deterministic primary path, LLM-driven
501
+ recovery leg) is not a distinct node kind — author it as a
502
+ single-item `subflow` node (`selector: () => [{ id: "only" }]`) whose own
503
+ `flow.kind: "cascade"` child flow routes between an ordinary `code` entry
504
+ and an ordinary `agent` entry via hand-authored edges, with `mode: "all"`
505
+ so the engine fails the parent automatically if neither leg succeeds. See
506
+ *Optional: `kind: "cascade"`* above for the underlying mechanic and a
507
+ worked `CODE_LOGIN`/`AGENT_LOGIN` example.
508
+
509
+ Detailed dispatch logic: `executor.js` lines 380–730.
510
+
511
+ ## Subflow nodes (childFlows)
512
+
513
+
514
+ A `subflow` node fans a `.selector(state)` array out into one real,
515
+ independent flow per item — each item's own `flow_runs` row, driven by the
516
+ exact same executor as any top-level flow. This is the ONLY subflow shape;
517
+ there is no simple/inline mode, and the loader rejects `.groupId` (it's
518
+ always the node's own id). Sub-nodes inside `flow.nodes`/`flow.edges` are
519
+ dispatched **identically** to root-level nodes — same `run`/`promptBuilder`/
520
+ `apply`/`pendingSelector` signatures, no `subCtx`, every return wrapped
521
+ under its own node-id key. Outside the subflow, read a child's results at
522
+ `state._subflowGroups[groupId][subflowKey]`.
523
+
524
+ ## Node authoring reference
525
+
526
+ General node-authoring mechanics that apply to any node kind, at any
527
+ level (top-level or a subflow's sub-node) — none of this is
528
+ subflow-specific, even though earlier revisions of this doc nested it
529
+ under *Subflow nodes*.
530
+
531
+ ### Circuit breaker (`node.circuitBreaker`)
532
+
533
+ An opt-in flag on any `kind:"agent"` node — top-level, or a cascade
534
+ sub-node inside a `flow.kind:"cascade"` subflow's own `flow.nodes` — that
535
+ fails fast instead of repeatedly dispatching an agent that's known to be
536
+ broken:
537
+
538
+ ```js
539
+ FLAKY_AGENT: {
540
+ kind: "agent",
541
+ agent: "flaky-thing",
542
+ circuitBreaker: true, // opt-in; default false/absent = no-op
543
+ promptBuilder: (state) => "…",
544
+ applyResult: (state, output) => ({ FLAKY_AGENT: output }),
545
+ }
546
+ ```
547
+
548
+ Implemented entirely inside `dispatchAgentEntry` (`engine/executor-nodes.js`)
549
+ — the single dispatch path every `kind:"agent"` node goes through,
550
+ regardless of whether it's a top-level node or a cascade sub-node running
551
+ inside its own child flow. Before doing any work — before the budget gate, before building the
552
+ prompt, before spawning a session — it checks
553
+ `nodeHealthStore.isBlocked(pipelineId, nodeId)` and throws immediately if
554
+ blocked, with a message that includes the exact reset command:
555
+
556
+ ```
557
+ unhealthy agent dispatch: "<nodeId>" is blocked after a prior failure —
558
+ reset via "openclaw manifold node-health reset <pipelineId> <nodeId>"
559
+ once the underlying issue is confirmed fixed
560
+ ```
561
+
562
+ On a genuine dispatch failure it calls `nodeHealthStore.markUnhealthy(...)`
563
+ before re-throwing, which blocks every future dispatch of that
564
+ `(pipelineId, nodeId)` pair until an operator resets it — see *CLI*
565
+ below (`openclaw manifold node-health status|reset`). Deliberately does
566
+ **not** mark unhealthy for `NodeBlocked` (an ordinary budget-gate pause,
567
+ not a dispatch failure) or `GatewayHandoffNeeded` (the agent runtime
568
+ being unreachable in the current context, not evidence the agent itself
569
+ is broken).
570
+
571
+ Gated purely on the flag — a node that never sets `circuitBreaker` is a
572
+ complete no-op through this whole path, so plain agent nodes are
573
+ unaffected unless they opt in. Every cascade sub-node needs this flag set
574
+ explicitly — see `ensure-login-node.js` factories and `submit-agent.js`
575
+ files under `workspace/.pipelines/` and `workspace/.shared/` for worked
576
+ examples.
577
+
578
+ ### Gate `approvalRequestBuilder` — editable surfaces
579
+
580
+ `approvalRequestBuilder(ctx, item)` returns the payload the gate UI renders. Standard fields:
581
+
582
+ | Field | Surface |
583
+ |---|---|
584
+ | `title` | Card header on the operator Inbox |
585
+ | `description` | Card body — verbose; can include layout markers |
586
+ | `editableText` | Prose body the edit-sheet pre-fills with AND the preview card shows. The free-form content the operator commits if they hit Approve unchanged. Body-only — no structured metadata. |
587
+ | `editableFields` | Optional `[ { id, label, type, value, options?, prefix?, helper? } ]` — pipeline-declared structured fields rendered as tappable chips above the prose body. Clients pick input UI from `type`. |
588
+ | `references` | Array of `{ id, label, body }` chips on the gate row + DiscussView |
589
+
590
+ **Prose body (`editableText`)**: pipelines with a free-form editable surface (workana-reply, touch-cadence, workana-proposal's prose) set this. The full-prose edit sheet renders + commits its content. If omitted (`undefined`), the executor auto-fills from the subflow's prior code-node outputs — the last `{ ..., text: "…" }` shape wins. Set `editableText: ""` explicitly to opt OUT.
591
+
592
+ **Structured fields (`editableFields`)**: pipelines that store metadata alongside the prose (workana-proposal's frontmatter: budget / timeframe / language) parse it once at builder time and expose each value as one entry. Clients render a chip per entry; tap → focused single-field editor matching `type`; save → `apply-draft` `fields:` payload → server's `persistRevisedMeta` writes back. Pipelines without structured metadata omit the array.
593
+
594
+ Field-entry shape:
595
+
596
+ | Key | Required | Notes |
597
+ |---|---|---|
598
+ | `id` | yes | Frontmatter key on disk (or any persistence key the pipeline understands) |
599
+ | `label` | yes | Display label for the chip + sheet header |
600
+ | `type` | yes | `text` / `multiline` / `money` / `enum`. Unknown types degrade to `text` on client. |
601
+ | `value` | yes | Current value as a string. Clients render display formatting per type (e.g. `money` gets thousand-separated). |
602
+ | `options` | for `enum` | Array of allowed string values. Renders as segmented control (≤4) or picker (>4). |
603
+ | `prefix` | optional | For `money`: rendered before the value on both chip + input (e.g. `"R$"`). |
604
+ | `helper` | optional | Footer hint shown in the single-field editor. No hardcoded copy on clients — pipelines own the wording. |
605
+ | `editable` | optional, default `true` | When `false`, the chip renders read-only (no tap target, muted styling). Useful for display-only context fields the operator should see but not edit (e.g. `source-listing`, `drafted-at`). |
606
+
607
+ Example (workana-proposal):
608
+
609
+ ```js
610
+ return {
611
+ title: `Proposal for ${listing.id} (score ${listing.score})`,
612
+ description: body, // long blob with markers
613
+ editableText: prose, // body-only
614
+ editableFields: [
615
+ { id: "budget", label: "Budget", type: "money", prefix: "R$", value: fm.budget,
616
+ helper: "Numeric BRL the bid form receives." },
617
+ { id: "timeframe", label: "Timeframe", type: "text", value: fm.timeframe,
618
+ helper: "Delivery duration in the draft's language." },
619
+ { id: "language", label: "Language", type: "enum", value: fm.language,
620
+ options: ["pt-BR", "en", "es"],
621
+ helper: "Language code for the draft body." },
622
+ // Read-only context — operator sees it, can't tap to edit.
623
+ { id: "drafted-at", label: "Drafted", type: "text", value: fm["drafted-at"], editable: false },
624
+ ],
625
+ references,
626
+ };
627
+ ```
628
+
629
+ ### Code-node `ctx` argument
630
+
631
+ `code`-kind nodes receive a `ctx` object as the LAST positional argument — always `run(state, ctx)`, whether the node is top-level or a `subflow` sub-node (the subflow item, if any, is `state.item` — not a separate positional arg). Existing nodes that ignore the trailing arg keep working unchanged.
632
+
633
+ `ctx` exposes:
634
+
635
+ | `ctx.invokePipeline(targetPipelineId, args)` | Start a fresh flow of another pipeline and drive it in the background. Returns immediately. |
636
+ | `ctx.flowId` / `ctx.nodeId` / `ctx.pipelineId` | This dispatch's own identifiers, for logging/artifact paths — same values threaded into `log`/`artifact` below, exposed directly too. |
637
+ | `ctx.log.info(msg)` / `.warn(msg)` / `.error(msg)` | Logs with the flow/node prefix already applied — prefer this over a bare `console.log` so log lines are attributable. |
638
+ | `ctx.artifact(name, content)` | Writes a file under this run's own artifact directory (`workspace/.pipelines/<pipelineId>/runs/<runId>/<name>`). Throws if `state.runId`/`state.pipelineId` aren't set yet (i.e. before `start()` has stamped them). |
639
+ | `ctx.readArtifact(name)` | Reads a file back from the same directory. Same throw condition as `ctx.artifact`. |
640
+ | `ctx.blocked(reason, hint)` | Throws `NodeBlocked({reason, hint})`. **Despite the name and the class's own doc comment ("blocks the flow with retry-on-resume semantics"), this actually fails the flow, not pauses it** — verified directly against `executor.js`'s own catch logic: a `NodeBlocked` reaches a real wait/pause only if its `_blocked._kind` is set, and `ctx.blocked()` never sets one (`internal/needs-resolver.js`'s `needs:` mechanism does, by explicitly stamping `_kind: "needs-not-ready"` before throwing — that's the one real example of the pause path firing). Calling `ctx.blocked(reason, hint)` today is equivalent to `throw new Error(reason)` with a slightly different message shape, not a way to pause a node — this looks like a real gap between the helper's intent and its actual behavior, not a documented design choice. |
641
+ | `ctx.needs(varName)` | Resolves a `needs:` declaration — see below. Only present/meaningful if the node itself declares `needs:`. |
642
+
643
+ Return shape of `ctx.invokePipeline`:
644
+
645
+ ```js
646
+ { invoked: true, target, flowId } // started
647
+ { invoked: false, reason: "singleton-busy", target } // target's own singleton guard rejected
648
+ ```
649
+
650
+ Any other `start()` error propagates (e.g., unknown `pipelineId`). Use this when the parent should fan out to another pipeline without blocking on its lifecycle — e.g., a fast scraper triggering a long-running operator-approval flow. The two pipelines retain independent singletons, so the target can park at a gate without affecting the parent's cron cadence.
651
+
652
+ #### `needs:` — reaching an ancestor flow's data (subflow children only)
653
+
654
+ A subflow child's own `state` is deliberately narrow — just `item`/`itemIndex`/`parentItem` (see *Subflow nodes*'s "What a sub-node's state actually contains"), no full clone of the parent. When a node genuinely needs something from an ancestor flow beyond that, declare `needs:` on the node itself:
655
+
656
+ ```js
657
+ CHILD_NODE: {
658
+ kind: "code",
659
+ needs: {
660
+ // local variable name → what to fetch
661
+ parentScan: { hops: 1, nodeId: "SCAN" }, // a parent's own node output
662
+ rootRunId: { hops: 2, entry: "runId" }, // an ancestor's entry/bookkeeping field
663
+ scoreFields: { hops: 1, nodeId: "SCORE", fields: ["score", "reasons"] }, // pick a subset
664
+ },
665
+ run: async (state, ctx) => {
666
+ const scan = await ctx.needs("parentScan"); // throws NodeBlocked (pauses, not fails) if not ready yet
667
+ // ...
668
+ },
669
+ },
670
+ ```
671
+
672
+ - `hops` counts levels up the subflow-spawn chain (`1` = immediate parent, `2` = grandparent, etc.) — this is the number of times the CHILD's own flow was itself spawned as a subflow item, not a node-graph distance.
673
+ - Exactly one of `nodeId` (another node's own output, unwrapped from its `{[nodeId]: value}` shape automatically) or `entry` (an ancestor's entry field — `runId`, `startedAt`, `args`, `triggeredBy`, `pipelineId`, `cost`, `_display`, `approvedIds`, `rejectedIds`, `editedTexts`, `approvalPending`, `approvalResults`, `_cascadeError`; `gates` is deliberately not reachable this way — see *State conventions*) must be declared.
674
+ - Optional `fields: ["a","b"]` picks a subset of a `nodeId`-type target's own output instead of the whole thing.
675
+ - Resolution is **lazy** — a node with 3 declared `needs` only pays for the ones its own code actually `await`s; a branch that never calls `ctx.needs("x")` never resolves or blocks on `x`.
676
+ - `ctx.needs(varName)` on an undeclared `varName` throws a plain `Error` (an author typo) — not a wait state. A declared-but-not-yet-ready target throws `NodeBlocked` with `_kind: "needs-not-ready"` explicitly stamped on — which genuinely pauses the flow (unlike a bare `ctx.blocked()`, see above) — and resolves automatically once the target completes; a declared target that will never exist (walked off the top of the ancestor chain, or the named node was never dispatched by that ancestor) also throws the same stamped `NodeBlocked` — there is no silent `undefined`.
677
+ - All of this is validated at pipeline-load time against the real ancestor chain (a hop deeper than the pipeline actually nests, a `nodeId` that doesn't exist at that level, or declaring `needs:` on a `human-gate` node) — a bad declaration fails to load, never a silent runtime miss.
678
+
679
+ ### Human-gate pending item shape
680
+
681
+ The `pendingSelector` may return raw strings (just itemIds) or objects.
682
+ The dashboard's `GateForm` reads these to decide which buttons to show:
683
+
684
+ | Field | Type | Effect on the dashboard form |
685
+ | ------------- | -------- | --------------------------------------------------------------------- |
686
+ | `id` | string | **Required.** Used by `approve <flowId> <itemId> <decision>`. |
687
+ | `reason`/`hint` | string | Rendered as a small subtitle under the item row. |
688
+ | `text` | string | Enables the **edit** button. Textarea is pre-filled with this text. |
689
+ | `editable` | boolean | If `true`, enables the **edit** button with an empty textarea. |
690
+
691
+ If neither `text` nor `editable` is present, the row shows approve/reject only. Approve and reject are always available.
692
+
693
+ Submitting an edit goes through `applyApproval` (`gates.js`) and writes
694
+ `state.editedTexts[itemId]` — downstream nodes that should honor an
695
+ edited result must read from there.
696
+
697
+ ### Per-gate discuss opt-in
698
+
699
+ A `human-gate` node can optionally let the operator chat with an agent
700
+ about a pending item before deciding. The chat lives in a dedicated
701
+ Inbox screen and is transported over the WS dialog door
702
+ (`ws://<gateway-host>:<dialog-port>/api/dialog?bearer=<MANIFOLD_BEARER>`):
703
+ the client sends `{type:"message", flowId, itemId, text}` frames and gets
704
+ back `{type:"ack"}`, then `{type:"reply"}` (or `{type:"error"}`).
705
+
706
+ **Global default** — set `discuss.defaultAgent` in `openclaw.json`
707
+ so every gate in every pipeline gets a discuss agent without declaring
708
+ its own `discuss` block:
709
+
710
+ ```json
711
+ {
712
+ "plugins": {
713
+ "entries": {
714
+ "manifold": {
715
+ "enabled": true,
716
+ "config": {
717
+ "discuss": {
718
+ "defaultAgent": "main"
719
+ }
720
+ }
721
+ }
722
+ }
723
+ }
724
+ }
725
+ ```
726
+
727
+ **Per-gate override** — add a `discuss` block on the gate node to use a
728
+ different agent or inject context into every session turn:
729
+
730
+ ```js
731
+ GATE: {
732
+ kind: "human-gate",
733
+ discuss: {
734
+ agent: "main",
735
+ promptBuilder: ({ state, itemId, flowId, pipelineId }) => {
736
+ // Injected as a system prompt for every turn in this gate's session.
737
+ // Give the agent context: the listing, current draft, orchestration rules.
738
+ const draft = state.items?.find(i => i.id === itemId)?.text ?? "";
739
+ return [
740
+ `You are reviewing item ${itemId} for pipeline ${pipelineId}.`,
741
+ `flowId: ${flowId} itemId: ${itemId}`,
742
+ draft ? `Current draft:\n${draft}` : "",
743
+ `When the operator asks for a revision, spawn Cyrano (content-writer)`,
744
+ `with the task and instruct them to propose through the pipeline's`,
745
+ `discuss tooling (oc-config). End your turn immediately — do NOT call sessions_yield.`,
746
+ ].filter(Boolean).join("\n");
747
+ },
748
+ },
749
+ },
750
+ ```
751
+
752
+ Without the `discuss` block (and no global default), the Inbox hides
753
+ the Discuss row entirely. Gates that aren't reachable for chat behave
754
+ exactly as before — Approve / Deny / Edit & approve / Cancel only.
755
+
756
+ **Mechanics:**
757
+
758
+ | Concern | Behavior |
759
+ |---|---|
760
+ | Channel | the WS dialog door — no channel plugin. Operator messages arrive as `{type:"message", flowId, itemId, text}` frames; the door answers `{type:"ack"}`, then `{type:"reply"}` (or `{type:"error"}`). |
761
+ | Session key | the harness's own session id, passed through verbatim — locked on the first turn and kept for the gate's lifetime. |
762
+ | Session stamp | Recorded in the session roster (`discuss_threads`: flow, gate, item → agent + session key) on first turn, so agent/config changes never break a live chat. |
763
+ | First-turn prompt | `promptBuilder` output is injected as a system prompt for the session; called on every turn (not just first). Return a non-string to skip it. |
764
+ | Draft proposal | A `discuss.component` event carrying a draft payload — a connected client surfaces an Apply affordance. |
765
+ | Meta proposal | A `discuss.component` event carrying a fields payload — updates the chip row on connected clients. |
766
+ | subflow (sub-node gate) | Gates inside `flow.nodes` opt in identically. `resolveDiscussTarget` walks `subflow` parents and picks the first `kind: "human-gate"` sub-node with a `discuss` block. |
767
+ | Resolution order | Stamped session → node `discuss.agent` → `discuss.defaultAgent` in openclaw.json. |
768
+ | History | `GET /manifold/runs/<flowId>/discuss?itemId=...` returns message history and pending components for cold-reconnect. |
769
+
770
+ **Pipeline authors:** `promptBuilder` is your contract surface. Inline the
771
+ listing context, current draft, and orchestration rules the agent needs.
772
+ Point the agent at oc-config's discuss tooling — not at `<draft>` tags or
773
+ `subagent_run`. Keep the prompt under ~2 KB.
774
+
775
+ ### needs-info: free-text vs button choices
776
+
777
+ A `code` node that returns `{ _blocked: { reason, needed, hint } }` puts
778
+ the flow into `status=waiting`, `waitJson.kind="needs-info"`. The
779
+ dashboard renders a `RespondForm` with a textarea by default; the
780
+ operator's reply gets appended to `state.userAnswers[nodeId]` and the
781
+ node re-runs.
782
+
783
+ Pipeline authors can opt into a **button-only** form by passing
784
+ `choices: string[]` in the `_blocked` payload:
785
+
786
+ ```js
787
+ return {
788
+ _blocked: {
789
+ reason: "approve to ship this proposal",
790
+ choices: ["approve", "deny"], // ← opt-in: dashboard renders 2 buttons
791
+ },
792
+ };
793
+ ```
794
+
795
+ The dashboard's RespondForm renders one button per choice (each
796
+ submits the choice label as the response text) and skips the textarea.
797
+ The node is responsible for interpreting the choice in its next run
798
+ via `state.userAnswers[nodeId].at(-1).text`. If `choices` is omitted,
799
+ the textarea remains.
800
+
801
+ `choices` is invisible to the CLI (`manifold respond` still takes
802
+ free text) and to companion Live Activity surfaces (which carry their own
803
+ approve/deny opinion regardless of `choices`). It's a dashboard-form
804
+ hint, not a contract.
805
+
806
+ ## Groups (compound parents in the dashboard)
807
+
808
+ `pipeline.groups` is optional. Each entry is a logical grouping of
809
+ nodes the dashboard renders as a compound parent. Typical use: a
810
+ **code+agent pair** like `(SCAN_CODE, SCAN_AGENT)` where reaching the
811
+ second member signals the cheap/fast path failed.
812
+
813
+ ```js
814
+ groups: {
815
+ GROUP_ID: {
816
+ label: "human-friendly title", // optional; defaults to GROUP_ID
817
+ kind: "pair", // optional; styling hint
818
+ members: ["NODE_A", "NODE_B"], // required, non-empty
819
+ },
820
+ }
821
+ ```
822
+
823
+ ### Member id forms
824
+
825
+ | Form | Example | Where the node lives |
826
+ | ----------------- | -------------------------------- | ------------------------------------------ |
827
+ | Bare | `"SCAN_CODE"` | top-level `pipeline.nodes` |
828
+ | Qualified | `"PROPOSE.SUBMIT_CODE"` | inside a `subflow` node's `flow.nodes` |
829
+
830
+ A qualified id is `<subflowParentId>.<childId>`. The loader
831
+ validates: parent exists, has `kind === "subflow"` and has `flow.nodes`, and child
832
+ is in `parent.flow.nodes`.
833
+
834
+ ### Same-scope rule
835
+
836
+ Every member of one group must live in the same scope — either all
837
+ top-level or all inside the same subflow. Cytoscape's
838
+ compound model allows only one parent per node, so a group's compound
839
+ has to be wholly nested in one place.
840
+
841
+ **Examples:** ✅ `["SCAN_CODE", "SCAN_AGENT"]` (both top-level)
842
+ ✅ `["PROPOSE.SUBMIT_CODE", "PROPOSE.SUBMIT"]` (both inside PROPOSE)
843
+ ❌ `["SCORE", "PROPOSE.SUBMIT"]` (mixes scopes — loader throws)
844
+ ❌ `["A.X", "B.Y"]` (different subflow parents — loader throws)
845
+
846
+ A node cannot be a member of more than one group.
847
+
848
+ Code paths: `loader.js: validateGroups` (validation),
849
+ `dashboard/src/components/GraphView.tsx` (rendering — nests
850
+ subflow-internal group compounds inside their subflow node).
851
+
852
+ ## Conventions (and what breaks if you violate them)
853
+
854
+ ### 1. Node IDs are token-style — no hyphens
855
+
856
+ **Rule:** Node ids match `[A-Za-z0-9_.]+`. Use UPPER_SNAKE, `lowercase`,
857
+ or `parent.child` for subflow members. **Never use hyphens.**
858
+
859
+ **Why:** Node ids surface verbatim in synthetic `${pipelineId}::${nodeId}`
860
+ addresses, lineage labels, and human-readable contexts — next to
861
+ hyphenated kebab-case item keys. Keeping hyphens out of node ids keeps
862
+ those compound names unambiguous to both readers and tooling.
863
+
864
+ **Examples:** ✅ `SCORE`, `ENSURE_LOGIN_CODE`, `propose.draft`
865
+ ❌ `ensure-login`, `score-listing`
866
+
867
+ ### 2. Item keys are kebab-case slugs
868
+
869
+ **Rule:** For `subflow` nodes, each item must expose a
870
+ stable string key via `item.id` or `item.listingId` (or `String(item)`
871
+ fallback). Slugs may (and usually do) contain hyphens.
872
+
873
+ **Why:** itemKey is the second component of the session key (rule 1).
874
+
875
+ ### 3. Plugin config nests under `.config`
876
+
877
+ **Rule:** In `~/.openclaw/openclaw.json`:
878
+
879
+ ```jsonc
880
+ "plugins": {
881
+ "entries": {
882
+ "manifold": {
883
+ "enabled": true,
884
+ "config": { // ← NOT flat on the entry
885
+ "dashboardHost": "127.0.0.1"
886
+ }
887
+ }
888
+ }
889
+ }
890
+ ```
891
+
892
+ **Why:** openclaw's config validator at `dist/io-…js: validateConfigObjectWithPluginsBase` builds plugin-config issue paths as `plugins.entries.<id>.config.*`. Flat keys fail strict validation with `Unrecognized key: "<name>"`.
893
+
894
+ ### 4. Singleton — one active run per pipelineId (opt-out via `allowConcurrent`)
895
+
896
+ **Rule:** `executor.start(pipelineId, args)` throws if any flow for
897
+ that pipeline is `running`, `blocked`, or `waiting`. Cancel or finish
898
+ the existing flow before starting a new one.
899
+
900
+ **Why:** Pipelines own real-world resources (a browser profile, a
901
+ marketplace login, operator attention via push notification). Parallel runs
902
+ race for those. `executor.js: start` lines 95–111.
903
+
904
+ **Opt-out:** add `allowConcurrent: true` on the pipeline definition.
905
+ The singleton check is skipped; multiple active flows for the same
906
+ pipelineId become a normal operating state. Use when each flow owns
907
+ an independent slice of state — e.g., one flow per inbound reply,
908
+ each gated independently by the operator. Don't use for pipelines
909
+ that share a real-world resource (browser, login, etc.); the
910
+ serialization is doing real work there.
911
+
912
+ ## Session keys (agent nodes dispatched by manifold)
913
+
914
+ Manifold does not mint session ids: the harness owns the id format, so an
915
+ agent node declares its own key and manifold passes it through verbatim.
916
+
917
+ ```
918
+ node.sessionKey // static
919
+ node.sessionKeyBuilder(state, flowId) // derived
920
+ ```
921
+
922
+ `dispatchAgentEntry` refuses an agent node that declares neither —
923
+ tool-handoff and the lineage ledger both key off this value, so inventing
924
+ one here would silently diverge from the harness's id. A discuss thread
925
+ carries its own session id, locked on the first turn and re-used for every
926
+ later turn of that thread.
927
+
928
+ Transcript attribution comes from the session ledger, never from the key's
929
+ shape.
930
+
931
+ A session is one conversation the harness owns; manifold addresses it by
932
+ id and never opens its files. Transcript content comes from the harness's
933
+ own surfaces (and, for discuss threads, from the messages manifold
934
+ persisted itself).
935
+
936
+ ## State conventions
937
+
938
+ Keys the executor writes; the dashboard reads:
939
+
940
+ | Key | Type | Purpose |
941
+ | --------------- | ------------------------------------------ | -------------------------------------------------------------------------------- |
942
+ | `runId` | string (UUID) | Assigned at `start`. Stable across restarts. |
943
+ | `pipelineId` | string | The pipeline that owns this flow. |
944
+ | `startedAt` | number (ms epoch) | Set at `start`. |
945
+ | `endedAt` | number (ms epoch) | Set at terminal transition. |
946
+ | `args` | object | The JSON passed via `start --args '…'`. Merged into initial state, not mutable. |
947
+ | `_subflowGroups` | `{ [groupId]: { [subflowKey]: SubflowData } }` | **Transient, never persisted.** Computed fresh each step by `assembleState()` — dual-mode: real `flow_runs` children for any subflow node, `flow_branches` fallback for flows that have no `flow_runs` children. Pipeline code reads `state._subflowGroups?.GROUP?.[key]?.data?.<subNodeId>`. See `SubflowData` in `dashboard/src/api/types.ts`. |
948
+
949
+ The dashboard derives the path-trail from `GET
950
+ /manifold/runs/:flowId/tree` (`flow_node_invocations`/`flow_node_executions`),
951
+ one row per invocation rather than one entry per dispatch — a retried node
952
+ collapses to a single pill instead of showing consecutive duplicates. Also
953
+ worth knowing: `state_json` holds no key per
954
+ dispatched node at all — the table above is the complete list of what's
955
+ actually in it; a node's own output lives in
956
+ `flow_node_invocations.result_json`, reconstructed on read by
957
+ `assembleState()`, never in the raw column.
958
+
959
+ Errors are NOT a state field — pipeline code never writes them directly.
960
+ Every node failure (top-level or inside a `subflow`) is recorded to
961
+ `flow_node_executions` (via `nodeExecutionsStore.write(..., error)`) and
962
+ served normalized as `errorEntries: [{ nodeId, subflowKey, message, at, executionId, invocationId }]` —
963
+ a top-level field sibling to `stateJson` on `GET /manifold/runs/:flowId`
964
+ and on each row of `GET /manifold/runs/:flowId/subflows`, not something
965
+ nested inside `stateJson`. Dashboard and companion clients render from `errorEntries`, not
966
+ from any `state.errors` key.
967
+
968
+ User-defined keys: anything else. Don't shadow the names above.
969
+
970
+ ## Status transitions
971
+
972
+ Real status values only — verified directly against `state/run-store.js`'s
973
+ own literal `status:` writes, not assumed from method names (`setWaiting`
974
+ the method actually writes status `blocked`; there is no `waiting` status
975
+ at all, despite the method's own name):
976
+
977
+ ```mermaid
978
+ stateDiagram-v2
979
+ [*] --> running: create()
980
+
981
+ running --> blocked: human-gate opens,<br/>ctx.needs() not ready,<br/>children-pending
982
+ blocked --> running: gate resolved /<br/>needed data arrived
983
+
984
+ running --> queued: agent-dispatch semaphore<br/>or cross-process lock contended
985
+ queued --> running: slot/lock freed<br/>(self-resolving, no operator action)
986
+
987
+ running --> succeeded: reached __end__ cleanly
988
+ running --> failed: a node threw,<br/>or applyResult rejected
989
+ running --> skipped: pipeline ran,<br/>produced no output
990
+ running --> cancelled: operator-initiated<br/>termination
991
+
992
+ succeeded --> [*]
993
+ failed --> [*]
994
+ skipped --> [*]
995
+ cancelled --> [*]
996
+ ```
997
+
998
+ | Status | What it means |
999
+ | ------------- | ------------------------------------------------------------------------------------------------ |
1000
+ | `running` | Executor loop is (or should be) driving this flow. |
1001
+ | `blocked` | `waitJson` is set; an operator/external actor must clear it (human-gate, `ctx.needs()` not-ready, children-pending). Executor exited the loop. |
1002
+ | `queued` | Waiting on an *internal* resource that frees itself (agent-dispatch semaphore, cross-process lock) — distinct from `blocked` specifically so consumers can tell "needs a human" from "will resolve on its own" without inspecting `wait_json.kind`. |
1003
+ | `succeeded` | Reached `__end__` cleanly. Terminal. |
1004
+ | `failed` | A node threw, or an applyResult rejected. Terminal. Also where a bare `ctx.blocked()` call ends up today — see *Code-node `ctx` argument* above. |
1005
+ | `skipped` | Pipeline ran but produced no output (nothing to score, all filtered, cap reached). Terminal. |
1006
+ | `cancelled` | Operator-initiated termination via tool / SQL (no CLI command yet — see *Operational quirks*). |
1007
+
1008
+ ## CLI
1009
+
1010
+ ```
1011
+ openclaw manifold list
1012
+ openclaw manifold runs
1013
+ openclaw manifold start <pipelineId> [--args <json>] [--detach]
1014
+ openclaw manifold status <flowId>
1015
+ openclaw manifold respond <flowId> <text>
1016
+ openclaw manifold approve <flowId> <itemId> <decision>
1017
+ openclaw manifold retry <flowId>
1018
+ openclaw manifold pause <flowId>
1019
+ openclaw manifold resume <flowId>
1020
+ openclaw manifold paused
1021
+ openclaw manifold dashboard
1022
+ openclaw manifold node-health status [pipelineId] [--all]
1023
+ openclaw manifold node-health reset <pipelineId> <nodeId>
1024
+ ```
1025
+
1026
+ Implementation: `cli.js`.
1027
+
1028
+ ## Tool surface (agent-facing)
1029
+
1030
+ Declared in `openclaw.plugin.json`, one tool per file under `agent/tools/`
1031
+ (barrel re-export in `agent/tools/index.js`):
1032
+
1033
+ | Tool | File | Signature input fields | Purpose |
1034
+ | ------------------------- | ---------------------------------------- | ------------------------------ | ---------------------------------------------------- |
1035
+ | `manifold_start` | `agent/tools/manifold-start.js` | `pipelineId`, optional `args` | Start a flow. Returns `flowId`. |
1036
+
1037
+ Pipeline-specific tools (`propose_*`, `submit_*`, `report_*`) live in
1038
+ oc-config, not here — core keeps only the harness-agnostic surface.
1039
+
1040
+ Shared helpers (`toolErr`) live in `agent/tools/shared.js`.
1041
+
1042
+ ### Adding a new tool
1043
+
1044
+ 1. New file under `agent/tools/`, one `registerXTool({ api, ...deps })`
1045
+ export per file.
1046
+ 2. Add the tool name to `contracts.tools` in `openclaw.plugin.json` — the
1047
+ loader rejects registration for undeclared names.
1048
+ 3. Register with `api.registerTool({ name: "...", ... })` — **prefer the
1049
+ object form**. Only reach for the factory form
1050
+ (`api.registerTool((ctx) => ({ name: "...", ... }))`, as `manifold_start`
1051
+ does) when you actually need `ctx` (e.g. `ctx.sessionKey`) in closure.
1052
+ 4. **If you use the factory form, you MUST pass `{ name: "..." }` as the
1053
+ second argument**: `api.registerTool((ctx) => ({...}), { name: "..." })`.
1054
+ Object-form registrations get their `names` populated automatically from
1055
+ the object's own `.name` field; factory-form registrations do not — the
1056
+ core loader never inspects what the factory *returns*, only
1057
+ `opts.name`/`opts.names`. Omitting this on a factory-form tool leaves its
1058
+ registry entry with an empty `names` array, which falls back to matching
1059
+ the *whole plugin's* declared tool list. Combined with `Array.find()`
1060
+ picking the *first* matching registry entry, a single factory-form tool
1061
+ registered without `opts.name` can silently hijack lookups for every
1062
+ *other* tool in the plugin — surfacing as `plugin tool runtime missing
1063
+ (manifold): <unrelated-tool-name>` at call time for tools that are
1064
+ otherwise correctly registered.
1065
+ 5. Wire the register call into `index.js`.
1066
+ 6. Add a test file under `test/unit/agent/tools/<tool-name>.test.js`
1067
+ mirroring the source file 1:1.
1068
+
1069
+ ## Dashboard
1070
+
1071
+ Mostly read-only web UI with one actuation endpoint
1072
+ (`POST /api/runs/:flowId/approve`) that resolves a blocked human-gate.
1073
+ Listens on `dashboardHost:dashboardPort` (default `127.0.0.1:7430`).
1074
+ Behind tailscale serve at `https://<tailnet>/graph/` when configured
1075
+ (`tailscale serve --set-path=/graph`).
1076
+
1077
+ API endpoints:
1078
+
1079
+ ```
1080
+ GET /api/health
1081
+ GET /api/pipelines
1082
+ GET /api/pipelines/:id
1083
+ GET /api/runs?status=&pipelineId=&limit=
1084
+ GET /api/runs/:flowId
1085
+ GET /api/runs/:flowId/events
1086
+ GET /api/runs/:flowId/artifacts
1087
+ GET /api/runs/:flowId/artifacts/:name
1088
+ GET /api/runs/:flowId/transcripts
1089
+ GET /api/runs/:flowId/compare
1090
+ GET /api/stats
1091
+ GET /api/stats/pipelines/:id
1092
+ GET /api/stats/pipelines/:id/views?sinceDays=N (pipeline-declared view payloads — see below)
1093
+ GET /api/events (SSE: flow_created | flow_changed | flow_terminated | pipelines_changed)
1094
+
1095
+ POST /api/runs/:flowId/approve body: { itemId, decision: "approve"|"reject"|"edit", text? }
1096
+ → 200 { decision, itemId, stillPending, status: "blocked"|"resumed" }
1097
+ → 400 invalid body | 404 flow not found
1098
+ → 409 not awaiting / itemId not pending / store write race
1099
+ ```
1100
+
1101
+ Source: `dashboard/server.js`. Frontend uses hash routing (`#/`,
1102
+ `#/pipelines`, `#/pipelines/:id`, `#/runs/:flowId`), filter state in
1103
+ URL query (`#/?status=succeeded&range=7d`). See `dashboard/src/App.tsx`.
1104
+
1105
+ ## Declared views (embed-view pattern)
1106
+
1107
+ A pipeline can attach extra cards to its dashboard detail page by
1108
+ exporting a `views: [...]` array. The dashboard discovers them via
1109
+ `GET /api/stats/pipelines/:id/views` and dispatches on `kind` to a
1110
+ generic renderer — **no dashboard code changes are required** to ship
1111
+ a new view, as long as the kind + source pair is already supported.
1112
+
1113
+ ```ts
1114
+ type ViewDeclaration = {
1115
+ id: string; // pipeline-unique, stable across reloads
1116
+ kind: "funnel"; // currently the only supported kind
1117
+ label: string; // card title
1118
+ source: SourceDeclaration;
1119
+ stages: StageDeclaration[];
1120
+ };
1121
+
1122
+ type SourceDeclaration = {
1123
+ kind: "frontmatter-dir"; // walks <dir>/*.md, parses YAML frontmatter
1124
+ path: string; // absolute path
1125
+ timeField?: string; // default "sent-at" — used for sinceDays window
1126
+ };
1127
+
1128
+ type StageDeclaration = {
1129
+ id: string; // stage-unique
1130
+ label?: string; // default = id
1131
+ outcomeIn?: string[]; // record's `outcome` field must be in this set
1132
+ outcomeEq?: string; // record's `outcome` field must equal this
1133
+ // No filter declared ⇒ stage matches every record (cohort base).
1134
+ };
1135
+ ```
1136
+
1137
+ Server computer: `dashboard/views.js` (top-level `computeViews`,
1138
+ per-kind `computeFunnelView`, per-source `loadFrontmatterDirRecords`).
1139
+ Frontend dispatcher: `dashboard/src/views/PipelineDetail.tsx`
1140
+ `DeclaredViewCard` / `FunnelViewCard`.
1141
+
1142
+ ### How the funnel computes
1143
+
1144
+ For `kind: "funnel"`:
1145
+
1146
+ 1. Load records via the source loader (frontmatter-dir → one record
1147
+ per `*.md` file, with all frontmatter keys plus `__ts` from the
1148
+ `timeField`).
1149
+ 2. Apply the time window: records whose `timeField` is missing or
1150
+ earlier than `Date.now() - sinceDays * 86_400_000` are excluded.
1151
+ 3. For each stage, count records matching the stage filter. Stages
1152
+ are independent filters over the full record set — they don't
1153
+ *enforce* superset semantics, so an honest funnel relies on the
1154
+ pipeline author declaring later stages as subsets of earlier ones.
1155
+ 4. Compute `conversionFromPrev = count[i] / count[i-1]`, and
1156
+ `conversionFromStart` on the last stage.
1157
+ 5. Build `byOutcome` (per-outcome distribution) when the source's
1158
+ records carry an `outcome` field — surfaces under the funnel as a
1159
+ "breakdown" strip.
1160
+
1161
+ ### Adding a new view kind
1162
+
1163
+ When a pipeline needs a view that isn't a funnel (e.g. a leaderboard,
1164
+ a per-day timeline, a single-number KPI):
1165
+
1166
+ 1. **Server:** add a `kind: "<name>"` branch to `computeView()` in
1167
+ `dashboard/views.js` and a per-kind computer that returns the
1168
+ payload shape (decide the shape — there's no required envelope
1169
+ beyond `{ id, kind, label, sinceMs }`).
1170
+ 2. **API types:** add a `DeclaredView<Name>` variant to the union in
1171
+ `dashboard/src/api/types.ts`.
1172
+ 3. **Frontend:** add a `view.kind === "<name>"` branch in
1173
+ `DeclaredViewCard` (in `PipelineDetail.tsx`) and the matching
1174
+ `<Name>ViewCard` renderer.
1175
+ 4. **Pipeline:** declare the view in `views: [...]`.
1176
+
1177
+ If the new view uses a new *source* (not `frontmatter-dir`), also add
1178
+ a `source.kind === "<name>"` branch in `loadRecords()`.
1179
+
1180
+ ### Anti-patterns — don't
1181
+
1182
+ - **Don't hardcode a view in the dashboard for a single pipeline.**
1183
+ The whole point of `views: [...]` is to keep per-pipeline surfaces
1184
+ out of `PipelineDetail.tsx`. If you're tempted to add an `if
1185
+ (pipelineId === "foo")` branch, declare a view instead.
1186
+ - **Don't expose secrets in `source.path`.** The dashboard reads
1187
+ every `.md` file in the dir and ships parsed frontmatter to the
1188
+ client. Sensitive fields belong elsewhere.
1189
+ - **Don't declare stages whose filters aren't subset-ordered.** The
1190
+ funnel won't reject it, but conversions will read >100% and
1191
+ confuse operators. Pattern: stage 0 = no filter (cohort base),
1192
+ later stages add filters that progressively narrow.
1193
+
1194
+ ### Recipe — declare an outcome funnel
1195
+
1196
+ When you need: a "did the pipeline's output actually work" surface
1197
+ backed by per-record outcomes stored as YAML frontmatter in a flat
1198
+ directory.
1199
+
1200
+ ```js
1201
+ // In your pipeline's index.js:
1202
+ const RECORDS_DIR = path.join(SHARED, "<domain>", "outcomes");
1203
+
1204
+ export default {
1205
+ id: "<pipelineId>",
1206
+ // ...nodes, edges...
1207
+ views: [
1208
+ {
1209
+ id: "outcomes",
1210
+ kind: "funnel",
1211
+ label: "outcomes (last 30d)",
1212
+ source: {
1213
+ kind: "frontmatter-dir",
1214
+ path: RECORDS_DIR,
1215
+ timeField: "created-at",
1216
+ },
1217
+ stages: [
1218
+ { id: "created", label: "created" }, // cohort base
1219
+ { id: "engaged", label: "engaged", outcomeIn: ["engaged","won"] }, // strict superset of `won`
1220
+ { id: "won", label: "won", outcomeEq: "won" },
1221
+ ],
1222
+ },
1223
+ ],
1224
+ };
1225
+ ```
1226
+
1227
+ Each `*.md` in `RECORDS_DIR` needs at minimum:
1228
+
1229
+ ```markdown
1230
+ ---
1231
+ created-at: 2026-05-20T10:00:00Z
1232
+ outcome: engaged
1233
+ ---
1234
+ <body>
1235
+ ```
1236
+
1237
+ The dashboard renders the card below the in-run funnel/histogram row
1238
+ on `PipelineDetail`, showing absolute counts, per-stage conversion,
1239
+ the `byOutcome` breakdown, and overall `created → won` %.
1240
+
1241
+ ## Common tasks
1242
+
1243
+ ### Add a new pipeline
1244
+
1245
+ 1. Create `~/.openclaw/workspace/.pipelines/<id>/index.js`.
1246
+ 2. Default-export an object matching *Pipeline schema (canonical)*.
1247
+ 3. No restart needed — `pipelines-watcher.js` reloads on change.
1248
+ 4. Verify with `openclaw manifold list` or
1249
+ `GET /api/pipelines/<id>`.
1250
+
1251
+ ### Run a pipeline once
1252
+
1253
+ ```
1254
+ openclaw manifold start my-pipeline --args '{"someInput":"x"}'
1255
+ ```
1256
+
1257
+ Without `--detach`, the CLI blocks driving the executor loop until
1258
+ the flow terminates or hits a gate. **With `--detach`, the flow record
1259
+ is created but never driven** (see *Operational quirks*).
1260
+
1261
+ ### Seed a pipeline with operator-supplied state
1262
+
1263
+ When the operator wants to drive a pipeline for a specific input the
1264
+ pipeline's normal SCAN/ENUMERATE stage wouldn't produce — e.g. "run
1265
+ the proposal flow for *this* listing URL" — neither `--args` nor the
1266
+ `manifold_start` tool fits: the pipeline's discovery stage still
1267
+ runs. Instead, insert a `flow_runs` row at `status='running'` +
1268
+ `current_step='__start__'` with pre-populated `state_json`. The
1269
+ gateway's *revival service* catches it at the next boot (~15s delay)
1270
+ and drives forward; the pipeline's start-edge typically short-circuits
1271
+ past discovery when its readiness condition is already satisfied (e.g.
1272
+ `PRIME: (s) => s.listings.length > 0 ? "FILTER" : "ENSURE_LOGIN"`).
1273
+
1274
+ Procedure lives in Vulcan's `seed-pipeline-flow` skill —
1275
+ `workspace/agents/agent-forger/skills/seed-pipeline-flow/SKILL.md`.
1276
+
1277
+ **⚠ Infra-skip gotcha.** Skipping `ENSURE_LOGIN_CODE` /
1278
+ `LAUNCH_BROWSER` / etc. via a pre-populated state leaves downstream
1279
+ CDP-dependent nodes failing with `ECONNREFUSED 127.0.0.1:9222`. Either
1280
+ run the infra step manually before seeding, or set the row's
1281
+ `current_step` to that infra node (revival starts there).
1282
+
1283
+ ### Inspect why a flow failed
1284
+
1285
+ ```
1286
+ openclaw manifold status <flowId> # shows status, currentStep, waitJson
1287
+ ```
1288
+
1289
+ Or open the dashboard at `#/runs/<flowId>`:
1290
+ - `errors` card lists `errorEntries[*]` (top-level, sourced from `flow_node_executions` — not a `stateJson` field)
1291
+ - `transcripts` card shows the full subagent conversation per session
1292
+ - `state` tree shows the full `stateJson`
1293
+
1294
+ ### Failures feed + operator recovery actions (operator Inbox)
1295
+
1296
+ A separate `failures.sqlite` store (sibling of `runtime.sqlite`)
1297
+ records one row per distinct branch- or flow-level failure on terminal
1298
+ `__end__`. Powers the operator Inbox's Recover/Done buckets and the dashboard
1299
+ "Needs Attention" strip. Dedup via `UNIQUE(flow_id, branch_item_id,
1300
+ failure_node)`; UPSERT semantics on re-records (see
1301
+ `failure-store.js:215-235`).
1302
+
1303
+ ```bash
1304
+ # Open rows (default: not resolved, not ignored)
1305
+ curl -H "Authorization: Bearer $TOKEN" \
1306
+ http://127.0.0.1:18789/manifold/failures
1307
+
1308
+ # Include resolved + ignored — what Inbox clients fetch in one shot
1309
+ curl -H "Authorization: Bearer $TOKEN" \
1310
+ 'http://127.0.0.1:18789/manifold/failures?resolved=all&ignored=all&limit=200'
1311
+ ```
1312
+
1313
+ Each row carries an `available_actions[]` array — descriptor list of
1314
+ operator actions Inbox clients render (kind / label / icon / tint /
1315
+ destructive). Framework defaults always present; pipeline-declared
1316
+ actions opt in via the `recoveryActions` map (see *Pipeline schema*
1317
+ above).
1318
+
1319
+ **Action dispatch endpoints** (gateway, port 18789):
1320
+
1321
+ ```bash
1322
+ # Generic dispatch — for any kind the row's available_actions exposes.
1323
+ # Includes pipeline-declared kinds (e.g. `skip` on workana-proposal)
1324
+ # and would include future custom kinds without code changes here.
1325
+ curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
1326
+ -d '{"via":"app"}' \
1327
+ http://127.0.0.1:18789/manifold/failures/<id>/action/<kind>
1328
+
1329
+ # Framework-default routes — same semantics, dedicated URLs:
1330
+ curl -X POST .../manifold/failures/<id>/retry # surgical branch retry
1331
+ curl -X POST .../manifold/failures/<id>/ignore # snooze
1332
+ curl -X POST .../manifold/failures/<id>/unignore # restore
1333
+ curl -X POST .../manifold/failures/<id>/skip # dedicated URL for the skip action
1334
+ ```
1335
+
1336
+ `/retry` walks the failure's own flow (a top-level flow, OR a `subflow`
1337
+ item's own child flow — both retry identically, since a child is just an
1338
+ ordinary flow with its own `flow_id`) back through its topology to the
1339
+ first node with a currently-live error, clears that node and everything
1340
+ downstream from `stateJson`, bumps `_attemptNumber`, and resumes — the
1341
+ executor re-enters at the failing node only, skipping nothing upstream of
1342
+ it that already succeeded. Refuses if the flow isn't in a terminal-ish
1343
+ state (`running`/`blocked`/`waiting`/`succeeded`/`failed`/`cancelled`/
1344
+ `skipped` only — never races a live executor iteration), or if the
1345
+ recorded `failure_node` doesn't match a current error (already
1346
+ resolved by an earlier retry). There is no separate itemId-keyed branch
1347
+ retry.
1348
+ Implementation: `routes/operator-retry.js: retryFailureBranch`.
1349
+
1350
+ ### Resume a gated flow
1351
+
1352
+ Three surfaces, same underlying operation:
1353
+
1354
+ ```
1355
+ # CLI
1356
+ openclaw manifold approve <flowId> <itemId> approve # human-gate / gate
1357
+ openclaw manifold approve <flowId> <itemId> edit --text "..." # replace agent output
1358
+ openclaw manifold respond <flowId> "the answer" # needs-info (free-form)
1359
+
1360
+ # Dashboard: open #/runs/<flowId> → "waiting on …" card. Approve/reject buttons are
1361
+ # always rendered; the edit button shows only when the pending item has
1362
+ # `text` (textarea pre-fills) or `editable: true` (empty textarea). The SSE
1363
+ # stream refreshes the page once the executor reacts.
1364
+
1365
+ # HTTP (what the dashboard sends)
1366
+ curl -X POST -H 'Content-Type: application/json' \
1367
+ -d '{"itemId":"<itemId>","decision":"approve"}' \
1368
+ http://127.0.0.1:7430/api/runs/<flowId>/approve
1369
+ ```
1370
+
1371
+ `itemId` must match the `id` of an entry returned by the node's
1372
+ `pendingSelector`. Both the CLI and the dashboard endpoint share
1373
+ `gates.js: applyApproval` so the resulting state mutation is identical.
1374
+
1375
+ ### Rerun a flow or a single subflow item
1376
+
1377
+ Three escalating strategies. Use the lowest one that fits.
1378
+
1379
+ **A. Whole flow, fresh from `__start__` (creates a new flow id):**
1380
+
1381
+ ```
1382
+ curl -X POST http://127.0.0.1:18789/manifold/runs/<flowId>/rerun
1383
+ ```
1384
+
1385
+ Routes through `executor.rerunFromSource` — copies the source flow's
1386
+ args, stamps `state.rerunOf = <oldFlowId>` for dashboard lineage,
1387
+ inserts a fresh `flow_runs` row, and fires `runFlow` on it. The
1388
+ original flow is untouched. Use when the failure was in `__start__`
1389
+ discovery or you genuinely want the pipeline to re-enumerate from
1390
+ scratch.
1391
+
1392
+ **B. One item of a `subflow` node (re-fire SEND/SUBMIT/etc. for a
1393
+ specific item without re-drafting):**
1394
+
1395
+ Because every subflow item is a real, independent flow (its own `flowId`,
1396
+ `childFlowId` in `_subflowGroups[groupId][subflowKey]`), retrying one item is
1397
+ just retrying that flow — the exact same mechanism as option A/the
1398
+ failures flow, pointed at the CHILD's own flowId instead of the parent's:
1399
+
1400
+ ```
1401
+ curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
1402
+ -d '{"via":"app"}' \
1403
+ http://127.0.0.1:18789/manifold/failures/<id>/retry
1404
+ ```
1405
+
1406
+ where `<id>` is the failure event recorded against the child's own
1407
+ `flow_id` — `state/failure-store.js: recordEngineFailure` fires from
1408
+ within the CHILD's own executor iteration and records this way for any
1409
+ genuine thrown error. Every `subflow` sub-node failure throws (zero soft
1410
+ `{ _error }` returns survive anywhere in this codebase), so every
1411
+ subflow-item failure ends up recorded this way and is directly
1412
+ retryable. `branch_item_id` on the wire
1413
+ (derived read-time from `flow_node_invocations.subflow_key`) is purely
1414
+ descriptive — it
1415
+ doesn't gate whether a failure can be retried (see
1416
+ `routes/operator-retry.js`'s own comment).
1417
+
1418
+ **One real caveat**:
1419
+ `recordEngineFailure` *can* also fire against the **parent's** own
1420
+ `flow_id` — `engine/child-resume-trigger.js`'s `maybeResumeParent`
1421
+ calls it directly (`failure_kind: "subflow-mode-not-satisfied"`) when
1422
+ every sibling child has reached a terminal status but the subflow node's own
1423
+ `mode` ("any"/"all") isn't satisfied. That's a policy decision, not a
1424
+ throw — nothing in the parent's own dispatch failed. Retrying *that*
1425
+ failure event doesn't re-run the parent (it already dispatched
1426
+ correctly); `routes/operator-retry.js`'s `retryFailureBranch` detects
1427
+ the `subflow-mode-not-satisfied` kind and redirects to the real
1428
+ underlying child failure instead, recursing through any further
1429
+ nested propagations first.
1430
+
1431
+ This walks
1432
+ the child's own topology back to the failing node exactly like a
1433
+ flow-level retry (see *Failures feed + operator recovery actions*
1434
+ above) — no manual `runtime.sqlite` surgery, no
1435
+ `branch.step`/`flow.currentStep` rewind math, no gateway restart. The
1436
+ parent flow is untouched and stays blocked on `children-pending` until
1437
+ this one child (re-)reaches a terminal status.
1438
+
1439
+ `routes/operator-retry.js` returns a clean `not_found` for any failure
1440
+ event whose `itemId` refers to a `flow_branches` row — there is no
1441
+ branch-row retry path.
1442
+
1443
+ **C. Whole pipeline, custom initial state (operator-supplied input
1444
+ the pipeline's discovery wouldn't produce):** see *Seed a pipeline
1445
+ with operator-supplied state* above.
1446
+
1447
+ ## If you see…
1448
+
1449
+ | Symptom | Likely cause + where to look |
1450
+ | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
1451
+ | `pipeline "<id>" already has 1 active flow(s)` | Singleton guard. Cancel/finish the prior run. `executor.js: start` line 105. |
1452
+ | `Unrecognized key: "<name>"` from `openclaw doctor` or gateway start | Plugin config not nested under `.config`. See *Conventions §3*. |
1453
+ | Flow stuck at `__start__` in `running` for forever | `--detach` was used. CLI never invoked `runFlow`. Restart the gateway (revival picks orphans) or re-run without `--detach`. |
1454
+ | `manifold: flow not found: <shortId>` | CLI commands take full UUID, not the dashboard's 8-char display id. |
1455
+ | Dashboard transcript pane shows long messy nodeId, no item | Pipeline uses a node id with a hyphen. Fix the node id. See *Conventions §1*. |
1456
+ | Dashboard pipeline detail renders blank black | `pipeline.nodes` is an array instead of an object keyed by id. Fix the export shape. |
1457
+ | `itemId "<x>" not in pending list. Pending: [object Object]` | `pendingSelector` returned objects without `.id`. Items must be `{ id: string, … }`. |
1458
+
1459
+ ## Operational quirks
1460
+
1461
+ - **`--detach` is a footgun.** It creates the flow record without
1462
+ driving the executor loop. The flow stays at `__start__` in
1463
+ `running` until something fires `executor.runFlow(flowId)`. The
1464
+ gateway's *revival service* (registered in `index.js: manifold-flow-revival`)
1465
+ picks up orphans at gateway boot. Practical fix: run without
1466
+ `--detach` inside a background shell instead.
1467
+ - **No `cancel` CLI command.** Terminal status is only `succeeded` /
1468
+ `failed`. To force-stop a flow today, the only path is direct sqlite
1469
+ surgery against `runtime.sqlite` (`UPDATE flow_runs SET status='cancelled', ended_at=<ms> …`).
1470
+ This is on the *actuation* roadmap (`POST /api/runs/:id/cancel`).
1471
+ - **Per-run artifacts** live in `<pipelinesDir>/<id>/runs/<runId>/`,
1472
+ not under the dashboard. The dashboard's `/api/runs/:flowId/artifacts`
1473
+ endpoint reads from there.
1474
+ - **State is large.** Avoid stuffing huge blobs into `stateJson` —
1475
+ every revision rewrites the row. Use artifacts (file on disk) for
1476
+ anything >10KB.
1477
+
1478
+ ## Plugin config (default values)
1479
+
1480
+ ```jsonc
1481
+ "plugins.entries.manifold": {
1482
+ "enabled": true,
1483
+ "config": {
1484
+ "pipelinesDir": "~/.openclaw/workspace/.pipelines", // discovery root
1485
+ "ownerSessionKey": "agent:main:explicit:manifold-owner",
1486
+ "dashboardEnabled": true,
1487
+ "dashboardPort": 7430,
1488
+ "dashboardHost": "127.0.0.1"
1489
+ }
1490
+ }
1491
+ ```
1492
+
1493
+ Schema enforced in `openclaw.plugin.json: configSchema`.
1494
+
1495
+ ## Database migrations
1496
+
1497
+ Table shapes live in `state/schema.js` (`runtime.sqlite`) and
1498
+ `state/schema.ops.js` (`ops.sqlite`) — drizzle definitions, the single
1499
+ source of truth. `npm run db:generate` snapshots them into
1500
+ `.migrations/<db>/`; `state/migrate.js` applies pending snapshots at
1501
+ store open via better-sqlite3 + drizzle, before any libsql handle opens.
1502
+ Snapshots are the sole schema path. New schema changes go in the defs +
1503
+ a generated snapshot. `test/unit/state/migrate.test.js` fails the build
1504
+ if live-booted columns drift from the defs either way, and if any snapshot
1505
+ file carries an unguarded CREATE or a DROP/RENAME.
1506
+
1507
+ ## SQLite shape (for direct queries / surgery)
1508
+
1509
+ Manifold owns `flow_runs`, `flow_node_invocations`, and
1510
+ `flow_node_executions`, all in `runtime.sqlite` — the sole read/write
1511
+ store for the dashboard, revival, gate-resolver, and executor.
1512
+ `registry.sqlite` is the platform's own store and is never written by
1513
+ manifold. All direct SQL surgery should target `runtime.sqlite`. Use the
1514
+ [`dql` skill](../../.claude/skills/dql) (`oc-dql`) for read-only
1515
+ inspection — it's the safe default; only reach for raw `sqlite3` when you
1516
+ actually intend to write.
1517
+
1518
+ ```
1519
+ file: <store home>/runtime.sqlite ← manifold read/write store (use this)
1520
+ table: flow_runs
1521
+
1522
+ flow_id TEXT PRIMARY KEY
1523
+ pipeline_id TEXT (the pipeline that owns this flow — top-level id,
1524
+ or "<parentPipelineId>::<subflowNodeId>" for a childFlows child)
1525
+ status TEXT ('running' | 'blocked' | 'waiting' | 'succeeded' | 'failed' | 'skipped' | 'cancelled')
1526
+ current_step TEXT (node currently in flight; NULL when idle or terminal)
1527
+ last_step TEXT (last completed node; NULL on creation)
1528
+ revision INTEGER
1529
+ state_json TEXT (JSON; the full mutable state)
1530
+ wait_json TEXT (JSON; null when not gated)
1531
+ status_reason TEXT (reason for the current status — blocked/queued/failed/skipped,
1532
+ optional on cancelled; always NULL for running/succeeded)
1533
+ owner_key TEXT
1534
+ parent_invocation_id TEXT (NULL for a top-level flow; FK → flow_node_invocations.id
1535
+ for a childFlows subflow item — see below)
1536
+ cancel_requested_at INTEGER
1537
+ created_at INTEGER (ms epoch)
1538
+ updated_at INTEGER (ms epoch)
1539
+ ended_at INTEGER (ms epoch; null until terminal)
1540
+
1541
+ indexes: status, owner_key, updated_at, parent_invocation_id (partial, WHERE NOT NULL)
1542
+
1543
+ -- "list of runs" queries (dashboard, CLI, companion clients) should filter
1544
+ -- WHERE parent_invocation_id IS NULL — every childFlows subflow item is its
1545
+ -- own flow_runs row and is not an independent "run" from an operator's
1546
+ -- perspective. See state/run-store.js's own listStmt for the canonical
1547
+ -- filtered query.
1548
+
1549
+
1550
+ table: flow_node_invocations ← one row per LOGICAL node dispatch (created once)
1551
+
1552
+ id TEXT PRIMARY KEY
1553
+ flow_id TEXT NOT NULL (the PARENT flow — the one that has the subflow node)
1554
+ pipeline_id TEXT
1555
+ node_id TEXT NOT NULL (the subflow node's own id; also its id in a
1556
+ root-level node's timing-only invocation)
1557
+ subflow_key TEXT (NULL for a root-level node; the item's
1558
+ derived key for a subflow child — see
1559
+ "Deriving subflowKey" above)
1560
+ visit_seq INTEGER NOT NULL DEFAULT 1 (distinguishes a genuine fresh
1561
+ loop-back pass from a retry/revival
1562
+ continuation of the same dispatch)
1563
+ invoked_at INTEGER NOT NULL
1564
+
1565
+ unique index: (flow_id, node_id, COALESCE(subflow_key,''), visit_seq)
1566
+
1567
+ -- subflow_key IS NOT NULL is the "this is a subflow-child invocation" signal —
1568
+ -- flow_runs.parent_invocation_id joins here to find a subflow node's real
1569
+ -- children: JOIN flow_runs r ON r.parent_invocation_id = flow_node_invocations.id
1570
+
1571
+
1572
+ table: flow_node_executions ← one row per EXECUTION ATTEMPT of an invocation (one per retry)
1573
+
1574
+ id TEXT PRIMARY KEY
1575
+ invocation_id TEXT NOT NULL (FK → flow_node_invocations.id)
1576
+ entered_at INTEGER NOT NULL
1577
+ exited_at INTEGER NOT NULL
1578
+ error TEXT (NULL on success — this is also the source
1579
+ of the wire-level errorEntries[], never a
1580
+ stateJson field, see State conventions)
1581
+ ```
1582
+
1583
+ For dry-run-then-commit destructive SQL, wrap in `BEGIN TRANSACTION;
1584
+ … ; ROLLBACK;` first, inspect, then re-run with `COMMIT;`.