@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.
- package/.migrations/ops/0000_futuristic_karma.sql +111 -0
- package/.migrations/ops/0001_low_maximus.sql +7 -0
- package/.migrations/ops/meta/0000_snapshot.json +763 -0
- package/.migrations/ops/meta/0001_snapshot.json +173 -0
- package/.migrations/ops/meta/_journal.json +20 -0
- package/.migrations/runtime/0000_real_boomer.sql +180 -0
- package/.migrations/runtime/0001_hot_dakota_north.sql +2 -0
- package/.migrations/runtime/0002_breezy_vertigo.sql +8 -0
- package/.migrations/runtime/0003_dashing_jack_flag.sql +5 -0
- package/.migrations/runtime/0004_panoramic_ego.sql +1 -0
- package/.migrations/runtime/0005_tidy_ben_grimm.sql +10 -0
- package/.migrations/runtime/0006_wet_nightmare.sql +57 -0
- package/.migrations/runtime/0007_ambiguous_chronomancer.sql +8 -0
- package/.migrations/runtime/0008_wealthy_thundra.sql +301 -0
- package/.migrations/runtime/0009_lying_shocker.sql +96 -0
- package/.migrations/runtime/0010_solid_phantom_reporter.sql +160 -0
- package/.migrations/runtime/0011_windy_demogoblin.sql +175 -0
- package/.migrations/runtime/0012_restore_harness_fks.sql +103 -0
- package/.migrations/runtime/meta/0000_snapshot.json +1181 -0
- package/.migrations/runtime/meta/0001_snapshot.json +1209 -0
- package/.migrations/runtime/meta/0002_snapshot.json +1261 -0
- package/.migrations/runtime/meta/0003_snapshot.json +1292 -0
- package/.migrations/runtime/meta/0004_snapshot.json +1240 -0
- package/.migrations/runtime/meta/0006_snapshot.json +1310 -0
- package/.migrations/runtime/meta/0007_snapshot.json +1362 -0
- package/.migrations/runtime/meta/0008_snapshot.json +1742 -0
- package/.migrations/runtime/meta/0009_snapshot.json +2413 -0
- package/.migrations/runtime/meta/0010_snapshot.json +2562 -0
- package/.migrations/runtime/meta/0011_snapshot.json +2812 -0
- package/.migrations/runtime/meta/0012_snapshot.json +2812 -0
- package/.migrations/runtime/meta/_journal.json +97 -0
- package/README.md +1583 -2
- package/RELEASING.md +89 -0
- package/agent/fleet.js +100 -0
- package/bin/cli.js +854 -0
- package/bin/manifold.js +4 -0
- package/boot/flow-revival.js +536 -0
- package/budget/index.js +495 -0
- package/budget/lib.js +59 -0
- package/dashboard/cost.js +528 -0
- package/dashboard/dist/assets/index-CUfp63sj.css +1 -0
- package/dashboard/dist/assets/index-Qy9JMpma.js +371 -0
- package/dashboard/dist/index.html +13 -0
- package/dashboard/event-log.js +267 -0
- package/dashboard/index.html +12 -0
- package/dashboard/package-lock.json +2877 -0
- package/dashboard/package.json +37 -0
- package/dashboard/pipeline-graph.js +131 -0
- package/dashboard/postcss.config.js +6 -0
- package/dashboard/search.js +183 -0
- package/dashboard/server.js +1015 -0
- package/dashboard/src/App.tsx +42 -0
- package/dashboard/src/api/client.ts +118 -0
- package/dashboard/src/api/types.ts +510 -0
- package/dashboard/src/api/ws.tsx +112 -0
- package/dashboard/src/components/CancelButton.tsx +63 -0
- package/dashboard/src/components/ClickToCopy.tsx +68 -0
- package/dashboard/src/components/CopyButton.tsx +61 -0
- package/dashboard/src/components/DailyCostTrend.tsx +85 -0
- package/dashboard/src/components/DailyTimeTrend.tsx +94 -0
- package/dashboard/src/components/Funnel.tsx +149 -0
- package/dashboard/src/components/GateForm.tsx +158 -0
- package/dashboard/src/components/GraphView.tsx +302 -0
- package/dashboard/src/components/GroupPathsSummary.tsx +47 -0
- package/dashboard/src/components/Histogram.tsx +292 -0
- package/dashboard/src/components/Layout.tsx +28 -0
- package/dashboard/src/components/NeedsAttention.tsx +98 -0
- package/dashboard/src/components/NodeContextCard.tsx +132 -0
- package/dashboard/src/components/PathTrail.tsx +35 -0
- package/dashboard/src/components/PipelineCostBreakdown.tsx +277 -0
- package/dashboard/src/components/RerunButton.tsx +46 -0
- package/dashboard/src/components/RunComparison.tsx +53 -0
- package/dashboard/src/components/Sparkline.tsx +94 -0
- package/dashboard/src/components/StatStrip.tsx +147 -0
- package/dashboard/src/components/StateTree.tsx +84 -0
- package/dashboard/src/components/StatusBadge.tsx +18 -0
- package/dashboard/src/components/SubflowPathPills.tsx +38 -0
- package/dashboard/src/components/SubflowSummary.tsx +24 -0
- package/dashboard/src/components/SubflowsCard.tsx +327 -0
- package/dashboard/src/components/TodayStrip.tsx +86 -0
- package/dashboard/src/components/TranscriptPane.tsx +99 -0
- package/dashboard/src/components/TranscriptRow.tsx +69 -0
- package/dashboard/src/components/ui/badge.tsx +38 -0
- package/dashboard/src/components/ui/button.tsx +28 -0
- package/dashboard/src/components/ui/card.tsx +42 -0
- package/dashboard/src/components/ui/skeleton.tsx +9 -0
- package/dashboard/src/components/ui/table.tsx +62 -0
- package/dashboard/src/index.css +26 -0
- package/dashboard/src/lib/anomaly.ts +42 -0
- package/dashboard/src/lib/format.ts +30 -0
- package/dashboard/src/lib/step-history.ts +13 -0
- package/dashboard/src/lib/subflow.ts +154 -0
- package/dashboard/src/lib/use-click-outside.ts +28 -0
- package/dashboard/src/lib/use-ignored-clusters.ts +67 -0
- package/dashboard/src/lib/utils.ts +6 -0
- package/dashboard/src/main.tsx +10 -0
- package/dashboard/src/types/shims.d.ts +4 -0
- package/dashboard/src/views/Home.tsx +478 -0
- package/dashboard/src/views/PipelineDetail.tsx +1185 -0
- package/dashboard/src/views/PipelinesList.tsx +111 -0
- package/dashboard/src/views/RunDetail.tsx +248 -0
- package/dashboard/src/views/Search.tsx +196 -0
- package/dashboard/stats.js +668 -0
- package/dashboard/tailwind.config.ts +43 -0
- package/dashboard/tree-stats.js +12 -0
- package/dashboard/tsconfig.json +25 -0
- package/dashboard/views.js +231 -0
- package/dashboard/vite.config.ts +34 -0
- package/drizzle.config.js +12 -0
- package/drizzle.config.ops.js +12 -0
- package/elevation.js +116 -0
- package/engine/admission-promotion-resume.js +127 -0
- package/engine/agent-dispatch.js +64 -0
- package/engine/child-resume-trigger.js +315 -0
- package/engine/executor-budget.js +87 -0
- package/engine/executor-cancel.js +83 -0
- package/engine/executor-errors.js +122 -0
- package/engine/executor-helpers.js +254 -0
- package/engine/executor-nodes.js +292 -0
- package/engine/executor-persist.js +212 -0
- package/engine/executor-subflow-children.js +275 -0
- package/engine/executor.js +1013 -0
- package/engine/global-concurrency.js +33 -0
- package/engine/loader.js +528 -0
- package/engine/needs-resolver.js +229 -0
- package/engine/pipelines-watcher.js +133 -0
- package/engine/result-replay.js +34 -0
- package/engine/revival-messages.js +11 -0
- package/engine/spawn-child.js +55 -0
- package/engine/wait-for-flow-settlement.js +109 -0
- package/events/catalog.js +26 -0
- package/events/emit.js +44 -0
- package/events/kinds.js +118 -0
- package/events/serve-ws.js +74 -0
- package/events/stream.js +35 -0
- package/events/ws-dialog.js +257 -0
- package/events/ws-frame.js +194 -0
- package/events/ws-run-events.js +70 -0
- package/events.js +32 -0
- package/gates/gate-resolver.js +576 -0
- package/gates/paused-flows.js +55 -0
- package/graphql/columns.js +67 -0
- package/graphql/schema.js +333 -0
- package/index.js +49 -0
- package/mcp/http.js +159 -0
- package/mcp/identity.js +94 -0
- package/mcp/stdio.js +80 -0
- package/mcp/tools.js +245 -0
- package/mcp/wire-ops.js +178 -0
- package/package.json +49 -4
- package/routes/bearer-auth.js +57 -0
- package/routes/discuss-audio.js +87 -0
- package/routes/discuss-component.js +39 -0
- package/routes/discuss-draft.js +159 -0
- package/routes/discuss-helpers.js +20 -0
- package/routes/discuss.js +848 -0
- package/routes/failures.js +104 -0
- package/routes/graphql.js +61 -0
- package/routes/health.js +54 -0
- package/routes/operator-discuss.js +193 -0
- package/routes/operator-resume.js +32 -0
- package/routes/operator-retry.js +301 -0
- package/routes/operator.js +539 -0
- package/routes/pipelines.js +118 -0
- package/routes/runs.js +1129 -0
- package/scripts/ci/import-check.mjs +50 -0
- package/scripts/link-core-self.mjs +31 -0
- package/scripts/with-guard.sh +24 -0
- package/server/app.js +503 -0
- package/server/registry.js +53 -0
- package/server/serve.js +163 -0
- package/state/admission-queue-store.js +325 -0
- package/state/attribution-registries.js +102 -0
- package/state/batch-writer.js +162 -0
- package/state/db-guard.js +63 -0
- package/state/db-health.js +27 -0
- package/state/db.js +122 -0
- package/state/discuss-store.js +299 -0
- package/state/failure-store.js +427 -0
- package/state/migrate.js +104 -0
- package/state/node-cost.js +67 -0
- package/state/node-executions.js +775 -0
- package/state/node-health-store.js +124 -0
- package/state/ops-merge.js +93 -0
- package/state/paths.js +146 -0
- package/state/pipeline-dirs.js +99 -0
- package/state/pipeline-registry.js +449 -0
- package/state/run-store.js +697 -0
- package/state/schema.js +438 -0
- package/state/schema.ops.js +44 -0
- package/state/session-index.js +177 -0
- package/state/session-keys.js +39 -0
- package/state/state-store.js +311 -0
- package/state/subflow-state.js +126 -0
- package/state/tool-handoff.js +169 -0
- package/telemetry/budget-alert.js +353 -0
- package/telemetry/cli.js +331 -0
- package/telemetry/grammar.js +119 -0
- package/telemetry/http-budget.js +132 -0
- package/telemetry/http-cost.js +670 -0
- package/telemetry/http-helpers.js +134 -0
- package/telemetry/http-tree.js +349 -0
- package/telemetry/http.js +44 -0
- package/telemetry/index.js +307 -0
- package/telemetry/ingest.js +134 -0
- package/telemetry/labels.js +115 -0
- package/telemetry/pricer.js +77 -0
- package/telemetry/resolver.js +314 -0
- package/telemetry/store.js +147 -0
- package/utils/run-patch.js +43 -0
package/README.md
CHANGED
|
@@ -1,3 +1,1584 @@
|
|
|
1
|
-
#
|
|
1
|
+
# manifold
|
|
2
2
|
|
|
3
|
-
|
|
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;`.
|