@osolmaz/pi-workflows 0.12.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (257) hide show
  1. package/README.md +56 -31
  2. package/dist/builtins/autodoc.workflow.d.ts +4 -4
  3. package/dist/builtins/autoimplement.workflow.d.ts +797 -142
  4. package/dist/builtins/autoimplement.workflow.js +17 -105
  5. package/dist/builtins/autoimplement.workflow.js.map +1 -1
  6. package/dist/builtins/autoplan.workflow.d.ts +126 -13
  7. package/dist/builtins/autoplan.workflow.js +200 -29
  8. package/dist/builtins/autoplan.workflow.js.map +1 -1
  9. package/dist/builtins/catalog.js +7 -5
  10. package/dist/builtins/catalog.js.map +1 -1
  11. package/dist/builtins/index.d.ts +4 -2
  12. package/dist/builtins/index.js +3 -1
  13. package/dist/builtins/index.js.map +1 -1
  14. package/dist/builtins/monitor.workflow.d.ts +56 -23
  15. package/dist/builtins/monitor.workflow.js +508 -329
  16. package/dist/builtins/monitor.workflow.js.map +1 -1
  17. package/dist/builtins/pi-agent-group.d.ts +72 -0
  18. package/dist/builtins/pi-agent-group.js +1087 -0
  19. package/dist/builtins/pi-agent-group.js.map +1 -0
  20. package/dist/builtins/plain-summary.workflow.d.ts +32 -0
  21. package/dist/builtins/plain-summary.workflow.js +134 -0
  22. package/dist/builtins/plain-summary.workflow.js.map +1 -0
  23. package/dist/builtins/plan-approval.workflow.d.ts +39 -5
  24. package/dist/builtins/plan-approval.workflow.js +92 -14
  25. package/dist/builtins/plan-approval.workflow.js.map +1 -1
  26. package/dist/builtins/plan-change.workflow.d.ts +449 -0
  27. package/dist/builtins/plan-change.workflow.js +256 -0
  28. package/dist/builtins/plan-change.workflow.js.map +1 -0
  29. package/dist/builtins/plan-presentation.js +2 -2
  30. package/dist/builtins/plan-presentation.js.map +1 -1
  31. package/dist/builtins/sanity-check.workflow.d.ts +50 -6
  32. package/dist/builtins/sanity-check.workflow.js +150 -28
  33. package/dist/builtins/sanity-check.workflow.js.map +1 -1
  34. package/dist/controllers/effects.d.ts +3 -2
  35. package/dist/controllers/effects.js +8 -1
  36. package/dist/controllers/effects.js.map +1 -1
  37. package/dist/controllers/index.d.ts +1 -1
  38. package/dist/controllers/index.js +1 -1
  39. package/dist/controllers/index.js.map +1 -1
  40. package/dist/controllers/manager.d.ts +1 -0
  41. package/dist/controllers/manager.js +41 -17
  42. package/dist/controllers/manager.js.map +1 -1
  43. package/dist/controllers/sqlite.d.ts +107 -85
  44. package/dist/controllers/sqlite.js +1611 -1486
  45. package/dist/controllers/sqlite.js.map +1 -1
  46. package/dist/controllers/store.d.ts +9 -8
  47. package/dist/controllers/store.js +1 -31
  48. package/dist/controllers/store.js.map +1 -1
  49. package/dist/controllers/types.d.ts +3 -0
  50. package/dist/controllers/workflow-engine-scheduler.d.ts +1 -1
  51. package/dist/controllers/workflow-engine-scheduler.js +3 -5
  52. package/dist/controllers/workflow-engine-scheduler.js.map +1 -1
  53. package/dist/controllers/workflows.d.ts +2 -2
  54. package/dist/controllers/workflows.js +11 -10
  55. package/dist/controllers/workflows.js.map +1 -1
  56. package/dist/extension/controller-host.js +2 -2
  57. package/dist/extension/controller-host.js.map +1 -1
  58. package/dist/extension/decision-channels.d.ts +4 -2
  59. package/dist/extension/decision-channels.js +333 -146
  60. package/dist/extension/decision-channels.js.map +1 -1
  61. package/dist/extension/executor.d.ts +9 -2
  62. package/dist/extension/executor.js +89 -2
  63. package/dist/extension/executor.js.map +1 -1
  64. package/dist/extension/herdr-viewer.d.ts +0 -1
  65. package/dist/extension/herdr-viewer.js +0 -4
  66. package/dist/extension/herdr-viewer.js.map +1 -1
  67. package/dist/extension/index.js +209 -127
  68. package/dist/extension/index.js.map +1 -1
  69. package/dist/extension/recorder.d.ts +3 -10
  70. package/dist/extension/recorder.js +13 -22
  71. package/dist/extension/recorder.js.map +1 -1
  72. package/dist/extension/session-events.d.ts +2 -2
  73. package/dist/extension/step-message.d.ts +7 -2
  74. package/dist/extension/step-message.js +94 -2
  75. package/dist/extension/step-message.js.map +1 -1
  76. package/dist/extension/widget.js +29 -3
  77. package/dist/extension/widget.js.map +1 -1
  78. package/dist/host/rpc-executor.d.ts +3 -0
  79. package/dist/host/rpc-executor.js +2 -0
  80. package/dist/host/rpc-executor.js.map +1 -1
  81. package/dist/host/runner.d.ts +3 -6
  82. package/dist/host/runner.js +83 -32
  83. package/dist/host/runner.js.map +1 -1
  84. package/dist/render/graph-render.js +15 -10
  85. package/dist/render/graph-render.js.map +1 -1
  86. package/dist/state/database.d.ts +35 -0
  87. package/dist/state/database.js +287 -0
  88. package/dist/state/database.js.map +1 -0
  89. package/dist/state/index.d.ts +4 -0
  90. package/dist/state/index.js +5 -0
  91. package/dist/state/index.js.map +1 -0
  92. package/dist/state/json.d.ts +6 -0
  93. package/dist/state/json.js +38 -0
  94. package/dist/state/json.js.map +1 -0
  95. package/dist/state/mutation.d.ts +57 -0
  96. package/dist/state/mutation.js +255 -0
  97. package/dist/state/mutation.js.map +1 -0
  98. package/dist/state/schema.d.ts +6 -0
  99. package/dist/state/schema.js +473 -0
  100. package/dist/state/schema.js.map +1 -0
  101. package/dist/viewer/cli.d.ts +2 -2
  102. package/dist/viewer/cli.js +142 -122
  103. package/dist/viewer/cli.js.map +1 -1
  104. package/dist/viewer/render.d.ts +4 -4
  105. package/dist/viewer/render.js +9 -23
  106. package/dist/viewer/render.js.map +1 -1
  107. package/dist/viewer/session-reducer.d.ts +1 -1
  108. package/dist/viewer/session-reducer.js +1 -1
  109. package/dist/viewer/tui.d.ts +3 -3
  110. package/dist/viewer/tui.js +15 -13
  111. package/dist/viewer/tui.js.map +1 -1
  112. package/dist/viewer/watch.d.ts +2 -5
  113. package/dist/viewer/watch.js +13 -13
  114. package/dist/viewer/watch.js.map +1 -1
  115. package/dist/workflows/catalog.js +7 -2
  116. package/dist/workflows/catalog.js.map +1 -1
  117. package/dist/workflows/composition.js +20 -2
  118. package/dist/workflows/composition.js.map +1 -1
  119. package/dist/workflows/decision-presentation.d.ts +1 -1
  120. package/dist/workflows/decision-presentation.js +51 -38
  121. package/dist/workflows/decision-presentation.js.map +1 -1
  122. package/dist/workflows/definition.d.ts +6 -2
  123. package/dist/workflows/definition.js +17 -0
  124. package/dist/workflows/definition.js.map +1 -1
  125. package/dist/workflows/engine.d.ts +7 -7
  126. package/dist/workflows/engine.js +196 -115
  127. package/dist/workflows/engine.js.map +1 -1
  128. package/dist/workflows/errors.d.ts +16 -3
  129. package/dist/workflows/errors.js +18 -3
  130. package/dist/workflows/errors.js.map +1 -1
  131. package/dist/workflows/human-decision.d.ts +45 -8
  132. package/dist/workflows/human-decision.js +641 -274
  133. package/dist/workflows/human-decision.js.map +1 -1
  134. package/dist/workflows/index.d.ts +5 -6
  135. package/dist/workflows/index.js +4 -5
  136. package/dist/workflows/index.js.map +1 -1
  137. package/dist/workflows/progress.d.ts +1 -0
  138. package/dist/workflows/progress.js +15 -3
  139. package/dist/workflows/progress.js.map +1 -1
  140. package/dist/workflows/schema.js +27 -1
  141. package/dist/workflows/schema.js.map +1 -1
  142. package/dist/workflows/store.d.ts +83 -103
  143. package/dist/workflows/store.js +907 -951
  144. package/dist/workflows/store.js.map +1 -1
  145. package/dist/workflows/types.d.ts +88 -126
  146. package/docs/CONTROLLERS.md +10 -8
  147. package/docs/DEFERRED_TURNS.md +2 -2
  148. package/docs/DESIGN_PHILOSOPHY.md +4 -2
  149. package/docs/HUMAN_DECISIONS.md +36 -47
  150. package/docs/HUMAN_DECISION_PRESENTATIONS.md +14 -24
  151. package/docs/MONITOR.md +179 -237
  152. package/docs/SQLITE_STATE.md +219 -0
  153. package/docs/WORKFLOW_COMPOSITION.md +27 -26
  154. package/docs/WORKFLOW_STEP_MESSAGES.md +20 -18
  155. package/docs/WORKFLOW_UPDATES.md +10 -9
  156. package/docs/development.md +9 -9
  157. package/docs/live-replay-protocol.md +28 -37
  158. package/docs/plans/2026-08-16-workflow-updates-plan.md +1 -1
  159. package/docs/plans/2026-08-19-human-decision-gates-plan.md +1 -1
  160. package/docs/plans/2026-08-21-autoimplement-timeout-fallback-plan.md +1 -1
  161. package/docs/plans/2026-08-21-plan-change-approval-policy-plan.md +322 -0
  162. package/docs/plans/2026-08-21-sanity-check-plan.md +217 -95
  163. package/docs/plans/2026-08-22-goal-finishing-monitor-plan.md +200 -0
  164. package/docs/plans/2026-08-23-assistant-agent-completion-plan.md +701 -0
  165. package/docs/plans/2026-08-23-sqlite-state-plan.md +970 -0
  166. package/docs/plans/replayable-run-bundles-implementation-plan.md +2 -2
  167. package/docs/plans/session-event-replay-implementation-plan.md +1 -1
  168. package/docs/plans/tui-viewer-implementation-plan.md +1 -1
  169. package/docs/session-event-journal.md +63 -434
  170. package/docs/tui-viewer.md +13 -15
  171. package/docs/workflows.md +127 -53
  172. package/examples/workflows/approved-plan.workflow.ts +19 -46
  173. package/examples/workflows/plain-summary.workflow.ts +1 -0
  174. package/herdr-plugin.toml +1 -1
  175. package/package.json +7 -7
  176. package/plugins/herdr/viewer.mjs +1 -11
  177. package/schemas/human-decision-accepted-v1.schema.json +15 -3
  178. package/schemas/human-decision-continuation-v1.schema.json +10 -1
  179. package/schemas/human-decision-delivery-v1.schema.json +8 -0
  180. package/schemas/human-decision-receipt-v1.schema.json +8 -0
  181. package/schemas/human-decision-request-v1.schema.json +24 -4
  182. package/skills/autoimplement/SKILL.md +27 -0
  183. package/skills/autoplan/SKILL.md +5 -4
  184. package/skills/monitor/SKILL.md +91 -135
  185. package/skills/pi-workflows/SKILL.md +9 -8
  186. package/skills/sanity-check/SKILL.md +44 -0
  187. package/src/builtins/autoimplement.workflow.ts +19 -118
  188. package/src/builtins/autoplan.workflow.ts +290 -40
  189. package/src/builtins/catalog.ts +7 -5
  190. package/src/builtins/index.ts +18 -1
  191. package/src/builtins/monitor.workflow.ts +673 -382
  192. package/src/builtins/pi-agent-group.ts +1407 -0
  193. package/src/builtins/plain-summary.workflow.ts +185 -0
  194. package/src/builtins/plan-approval.workflow.ts +157 -24
  195. package/src/builtins/plan-change.workflow.ts +321 -0
  196. package/src/builtins/plan-presentation.ts +2 -2
  197. package/src/builtins/sanity-check.workflow.ts +248 -48
  198. package/src/controllers/effects.ts +7 -0
  199. package/src/controllers/index.ts +0 -6
  200. package/src/controllers/manager.ts +72 -32
  201. package/src/controllers/sqlite.ts +2420 -1948
  202. package/src/controllers/store.ts +17 -38
  203. package/src/controllers/types.ts +3 -0
  204. package/src/controllers/workflow-engine-scheduler.ts +4 -8
  205. package/src/controllers/workflows.ts +45 -21
  206. package/src/extension/controller-host.ts +1 -2
  207. package/src/extension/decision-channels.ts +456 -203
  208. package/src/extension/executor.ts +105 -2
  209. package/src/extension/herdr-viewer.ts +0 -5
  210. package/src/extension/index.ts +251 -151
  211. package/src/extension/recorder.ts +13 -22
  212. package/src/extension/session-events.ts +2 -2
  213. package/src/extension/step-message.ts +106 -4
  214. package/src/extension/widget.ts +32 -5
  215. package/src/host/rpc-executor.ts +4 -0
  216. package/src/host/runner.ts +93 -41
  217. package/src/render/graph-render.ts +12 -6
  218. package/src/state/database.ts +375 -0
  219. package/src/state/index.ts +29 -0
  220. package/src/state/json.ts +42 -0
  221. package/src/state/mutation.ts +435 -0
  222. package/src/state/schema.ts +475 -0
  223. package/src/viewer/cli.ts +151 -144
  224. package/src/viewer/render.ts +19 -30
  225. package/src/viewer/session-reducer.ts +1 -1
  226. package/src/viewer/tui.ts +18 -17
  227. package/src/viewer/watch.ts +13 -17
  228. package/src/workflows/catalog.ts +7 -2
  229. package/src/workflows/composition.ts +21 -3
  230. package/src/workflows/decision-presentation.ts +56 -43
  231. package/src/workflows/definition.ts +36 -3
  232. package/src/workflows/engine.ts +228 -130
  233. package/src/workflows/errors.ts +27 -3
  234. package/src/workflows/human-decision.ts +921 -349
  235. package/src/workflows/index.ts +20 -30
  236. package/src/workflows/progress.ts +18 -3
  237. package/src/workflows/schema.ts +36 -1
  238. package/src/workflows/store.ts +1300 -1163
  239. package/src/workflows/types.ts +100 -137
  240. package/dist/builtins/sanity-check-session.d.ts +0 -17
  241. package/dist/builtins/sanity-check-session.js +0 -168
  242. package/dist/builtins/sanity-check-session.js.map +0 -1
  243. package/dist/workflows/artifacts.d.ts +0 -40
  244. package/dist/workflows/artifacts.js +0 -155
  245. package/dist/workflows/artifacts.js.map +0 -1
  246. package/dist/workflows/migrate-sources.d.ts +0 -42
  247. package/dist/workflows/migrate-sources.js +0 -133
  248. package/dist/workflows/migrate-sources.js.map +0 -1
  249. package/docs/run-bundles.md +0 -481
  250. package/schemas/human-decision-accepted-v2.schema.json +0 -50
  251. package/schemas/human-decision-delivery-v2.schema.json +0 -36
  252. package/schemas/human-decision-receipt-v2.schema.json +0 -39
  253. package/schemas/human-decision-request-v2.schema.json +0 -69
  254. package/schemas/human-decision-resolution-v2.schema.json +0 -27
  255. package/src/builtins/sanity-check-session.ts +0 -205
  256. package/src/workflows/artifacts.ts +0 -188
  257. package/src/workflows/migrate-sources.ts +0 -178
@@ -1,481 +0,0 @@
1
- # Run bundle format
2
-
3
- Every workflow run persists to its own directory, called a run bundle. The
4
- bundle is the contract between the engine and anything that observes runs: the
5
- bundled terminal viewer, the Rust TUI, and any external tool. A bundle is
6
- **self-contained for replay**: a reader never needs access to Pi's global
7
- session store or any other file outside the bundle directory.
8
-
9
- This document is the authoritative specification. There is exactly one format
10
- version; older layouts are not read and no compatibility paths exist.
11
-
12
- ## Location and layout
13
-
14
- Bundles live under `~/.pi/agent/workflows/runs/` by default. The
15
- `PI_WORKFLOWS_RUNS_DIR` environment variable overrides the location for both
16
- the engine and all viewers, which is how the test suite keeps runs inside
17
- temporary directories.
18
-
19
- ```
20
- ~/.pi/agent/workflows/runs/
21
- 20260729T023912Z-autoimplement-3f2a9c1b/
22
- manifest.json # pi-workflows.run-bundle.v1
23
- workflow.json # pi-workflows.definition-snapshot.v1
24
- state.json # pi-workflows.run-state.v1, derived projection
25
- trace.ndjson # pi-workflows.trace-event.v1, append-only source of truth
26
- session/ # present when the run executed inside a Pi conversation
27
- binding.json # pi-workflows.session-binding.v1
28
- entries.ndjson # pi-workflows.session-entry.v1, append-only
29
- events.ndjson # pi-workflows.session-event.v1, append-only
30
- capture.json # pi-workflows.session-capture.v1, atomic projection
31
- artifacts/ # present when any persisted value was externalized
32
- sha256-<64 hex>.txt
33
- ```
34
-
35
- Human decision records use a separate additive directory next to `runs/` so a waiting run bundle remains immutable:
36
-
37
- ```text
38
- ~/.pi/agent/workflows/decisions/
39
- <decision-id>/
40
- request.json
41
- deliveries/<channel>/<attempt-id>.json
42
- answers/<attempt-id>.json
43
- resolution.json # atomic accepted-or-cancelled fence
44
- accepted.json
45
- cancelled.json # present only when a pending request is cancelled or expires
46
- settlements/<channel>/<attempt-id>.json
47
- continuation.json
48
- ```
49
-
50
- The request links to the waiting run, node, attempt, workflow source, and canonical request digest. A v2 request stores the canonical subject and a separate normalized operator presentation. Its subject, presentation, revision, choices, and input prompts are bound to the request digest. V2 accepted records and redacted continuation receipts preserve the subject and presentation digests. Final records use no-replace creation and adopt only identical retries. `resolution.json` is the first accepted-or-cancelled fence. It materializes either `accepted.json` or the mutually exclusive `cancelled.json`; a crash can rebuild that detail from the resolution. `continuation.json` binds an accepted answer to one deterministic continuation run. Delivery and settlement records cannot change the accepted answer.
51
-
52
- Telegram multipart delivery uses additive v2 delivery records for the overall intent, each part, and completion. Part records contain only recipient indexes, part indexes, counts, and content digests. Telegram chat and message IDs remain in the private disposable channel projection and never enter run or decision bundles. An ambiguous part remains unknown and is not retried blindly.
53
-
54
- A human-decision continuation preserves the parent's original workflow input and replaces the carried checkpoint output with the accepted typed response for routing. Its `humanDecision` state is a redacted receipt. A v2 receipt includes the subject digest, presentation digest, and revision, but not the subject itself. Verified actor, channel, event, and idempotency provenance remains in the private sibling decision records and is not copied into the run bundle. Ordinary checkpoint continuations keep using the answer as the continuation input. Existing bundles without human decision data remain valid. V1 requests and their original digests are never rewritten.
55
-
56
- Run ids are `<UTC timestamp>-<workflow slug>-<8 hex chars>`, so lexical order
57
- is chronological order.
58
-
59
- Bundle directories are created with mode `0700` and files with mode `0600`.
60
- Bundles can contain prompts, model output, shell commands, environment
61
- details, and absolute paths; treat them as private data and review before
62
- exporting.
63
-
64
- ## Source of truth and write discipline
65
-
66
- `trace.ndjson` is the source of truth for workflow execution. Final Pi
67
- conversation entries and temporal session history have separate authority in
68
- `session/entries.ndjson` and `session/events.ndjson`. `session/capture.json`
69
- reports whether temporal capture is complete. These sequence spaces are
70
- independent and must not be compared.
71
-
72
- Write order for every transition:
73
-
74
- 1. Append the trace event (one JSON object per line, appends serialized per
75
- file, `seq` starting at 1 and increasing by exactly 1).
76
- 2. Atomically replace `state.json`, carrying `traceSeq` = the `seq` of the
77
- trace event it reflects (write to a temp file in the same directory, then
78
- rename).
79
- 3. Atomically replace `manifest.json`.
80
-
81
- Consequences for readers:
82
-
83
- - A reader never sees a partial JSON document; a torn final trace line must be
84
- ignored.
85
- - `state.json` with `traceSeq` older than the last trace line is a stale
86
- projection: either re-read after the writer catches up or fold the trace
87
- tail on top of it.
88
- - Before the engine writes a terminal workflow event, session recording stops,
89
- drains accepted entries and events, and atomically writes `capture.json`.
90
- - After a run reaches a terminal status (`completed`, `failed`, `timed_out`,
91
- `cancelled`, or `waiting`), the bundle no longer changes, and
92
- `state.traceSeq` equals the final trace `seq`.
93
- - A bundle whose state is `running` but whose files have stopped growing may
94
- be an interrupted run (crash, reboot); viewers should label it as possibly
95
- interrupted rather than live.
96
-
97
- ## Externalized values and artifacts
98
-
99
- Large payloads are stored once, content-addressed, under `artifacts/` and
100
- referenced from the documents that use them. This applies uniformly to every
101
- **persisted value position**. These positions include `input`, `outputs.*`,
102
- `results.*.output`, `steps[*].prompt`, `steps[*].output`, and `finalOutput`.
103
- Trace event payload values follow the same rule.
104
-
105
- Encoding rule, applied recursively to a persisted value:
106
-
107
- - A string leaf whose UTF-8 encoding is larger than 4096 bytes is written to
108
- `artifacts/sha256-<digest>.txt` (UTF-8, digest over the exact bytes) and
109
- replaced by an artifact reference:
110
-
111
- ```json
112
- {
113
- "$artifact": {
114
- "path": "artifacts/sha256-2b1f….txt",
115
- "mediaType": "text/plain",
116
- "bytes": 18342,
117
- "sha256": "2b1f…"
118
- }
119
- }
120
- ```
121
-
122
- - Any user object that has an own key `$artifact` or `$escaped` is wrapped as
123
- `{ "$escaped": <object> }` so the sentinel stays unambiguous. Decoders
124
- unwrap `$escaped` one level and resolve `$artifact` refs.
125
- - Everything else is stored inline. Small values are never externalized.
126
-
127
- Artifact rules:
128
-
129
- - `path` is bundle-relative; a reference never points outside the bundle.
130
- - Artifacts are immutable once written and deduplicate by content hash.
131
- - Readers must tolerate unknown `mediaType` values.
132
-
133
- The same output can legitimately appear in several places. Externalization
134
- keeps each copy in `outputs`, `results`, `steps`, or the trace as the same small
135
- reference.
136
-
137
- ## manifest.json
138
-
139
- Identity and pointers, kept in sync with the state on every snapshot:
140
-
141
- ```json
142
- {
143
- "schema": "pi-workflows.run-bundle.v1",
144
- "runId": "20260729T023912Z-autoimplement-3f2a9c1b",
145
- "workflowName": "autoimplement",
146
- "runTitle": "autoimplement: fix the flaky test",
147
- "workflowSource": {
148
- "kind": "file",
149
- "path": "/repo/.pi/workflows/autoimplement.workflow.ts",
150
- "hash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
151
- },
152
- "startedAt": "2026-07-29T02:39:12.412Z",
153
- "finishedAt": "2026-07-29T02:41:03.977Z",
154
- "status": "completed",
155
- "traceSchema": "pi-workflows.trace-event.v1",
156
- "paths": {
157
- "workflow": "workflow.json",
158
- "state": "state.json",
159
- "trace": "trace.ndjson",
160
- "session": "session",
161
- "artifacts": "artifacts"
162
- }
163
- }
164
- ```
165
-
166
- `workflowSource` identifies the root definition used by the run. User workflow
167
- files use an absolute path and SHA-256 hash. Package-provided workflows use a
168
- stable identity such as `{ "kind": "builtin", "id": "monitor", "revision": "4" }`.
169
- A built-in identity does not contain an installation path.
170
-
171
- A composed run also records `workflowSources`, sorted by mount path, and `definitionDigest`. Each mounted source has `mountPath`, `workflowName`, and the same file or built-in source identity. The digest is SHA-256 over the resolved definition snapshot.
172
-
173
- `paths.artifacts` is declared from bundle creation so a live session-event
174
- patch can safely reference a newly written artifact before the next workflow
175
- state projection. The directory itself is created only when needed.
176
- `paths.session` appears when the run binds to Pi. Readers must start from
177
- `manifest.json`, check `schema`, skip bundles they do not understand, resolve
178
- files through `paths`, and reject any path that escapes the bundle directory.
179
-
180
- ## workflow.json
181
-
182
- A serializable snapshot of the graph taken at run start
183
- (`pi-workflows.definition-snapshot.v1`). Functions such as prompts and
184
- validators are not serialized. Each node keeps only its metadata (`nodeType`,
185
- `timeoutMs`, `statusDetail`, `expectedOutput`, `summary`, `actionExecution`),
186
- and edges are copied verbatim. A fixed `timeoutMs: null` is preserved and means
187
- that the node has no wall-clock deadline. Timeout callbacks remain omitted.
188
- Included nodes also record `mountPath`, `localNodeId`, and internal entry or exit status. The top-level `composition.mounts` list records every mount, entry, named exit, and child step limit. The snapshot is what lets viewers draw all nodes, including ones that have not run yet. It is immutable after run start.
189
-
190
- ## Resume and repair
191
-
192
- An interrupted run (status `running` with no terminal trace event) can resume
193
- instead of failing. Resume is a named operation with strict rules:
194
-
195
- 1. The caller must hold the run's queue claim. Only the current claim holder
196
- may resume or interrupt a bundle, and every bundle write verifies the
197
- claim token first (write fencing).
198
- 2. A torn trace tail (a crash mid-append) is truncated to the last complete
199
- line. Trace events the state projection never recorded are dropped, so
200
- `state.traceSeq` and the trace agree again before any new event.
201
- 3. Completed nodes replay from the projection. The in-flight node reruns with
202
- a fresh attempt; a `run_resumed` trace event marks the boundary.
203
- 4. `state.workflowSource` pins the root workflow source from run start. File
204
- sources require the same hash. Built-in sources require the same catalog
205
- id and revision.
206
- 5. Composed runs also require the same sorted `workflowSources` and
207
- `definitionDigest`. A changed or missing child refuses normal resume.
208
- 6. A forced resume records the identity mismatch in the `run_resumed` payload.
209
-
210
- Continuation runs (answering a checkpoint) are new bundles, not resumed ones.
211
- They link back through `state.parentRunId`, carry the parent's outputs,
212
- results, and step records forward, and note `continuedFrom` in their
213
- `run_started` payload. Bundles stay append-only; a continuation is the only
214
- way work follows a terminal `waiting` state.
215
-
216
- ## state.json
217
-
218
- The full run projection (`WorkflowRunState` in
219
- [`src/workflows/types.ts`](../src/workflows/types.ts)), schema
220
- `pi-workflows.run-state.v1`:
221
-
222
- ```json
223
- {
224
- "schema": "pi-workflows.run-state.v1",
225
- "traceSeq": 17,
226
- "runId": "20260729T023912Z-autoimplement-3f2a9c1b",
227
- "workflowName": "autoimplement",
228
- "workflowSource": {
229
- "kind": "file",
230
- "path": "/repo/.pi/workflows/autoimplement.workflow.ts",
231
- "hash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
232
- },
233
- "workflowSources": [
234
- {
235
- "mountPath": ["redesign"],
236
- "workflowName": "autoplan",
237
- "source": { "kind": "builtin", "id": "autoplan", "revision": "1" }
238
- }
239
- ],
240
- "definitionDigest": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
241
- "startedAt": "…",
242
- "updatedAt": "…",
243
- "status": "running",
244
- "input": { "task": "fix the flaky test" },
245
- "outputs": {},
246
- "results": {},
247
- "steps": [],
248
- "updates": []
249
- }
250
- ```
251
-
252
- - `workflowSource` is the canonical root source identity. Resuming a file requires
253
- the same hash. Resuming a built-in requires the same catalog revision.
254
- - `workflowSources` and `definitionDigest` attest the complete composed graph.
255
- A mismatch refuses resume instead of loading another child definition.
256
- - `status` is one of `running`, `waiting`, `completed`, `failed`, `timed_out`,
257
- or `cancelled`. A controller host records an abandoned bundle as `failed`
258
- with a final `run_interrupted` trace event. Before doing that, recovery checks
259
- the trace tail and repairs a stale projection when the terminal event was
260
- already appended. The controller store can then retry a genuinely abandoned
261
- child attempt without changing this schema. If startup stopped before a
262
- manifest existed, the scheduler preserves that incomplete directory as a
263
- hidden sibling before creating the reserved run.
264
- - While a node is executing, `currentNode` and `currentAttemptId` identify it.
265
- `currentNodeStartedAt` and `statusDetail` add timing and display context.
266
- These fields disappear when the node finishes. The executing node's type comes from the definition
267
- snapshot, not from the state.
268
- - While a pause request holds the run at a step boundary, `paused` is `true`
269
- (with matching `run_paused`/`run_resumed` trace events); it disappears when
270
- the run resumes or ends.
271
- - Per-node data lives in `outputs` (the accepted output of each finished node,
272
- latest attempt wins on loops) and `results` (the full result record of the
273
- latest attempt, including outcome and timing).
274
- - `updates` contains the latest durable record for each `(type, key)` pair,
275
- sorted by trace sequence. New runs start with an empty array. Older bundles
276
- can omit it. Resume keeps it; checkpoint continuation starts a new empty
277
- projection. The trace keeps the complete update history.
278
- - `steps` is the ordered history, one record per node attempt:
279
-
280
- ```json
281
- {
282
- "attemptId": "d81f…",
283
- "nodeId": "implement",
284
- "nodeType": "agent",
285
- "outcome": "ok",
286
- "startedAt": "…",
287
- "finishedAt": "…",
288
- "prompt": {
289
- "$artifact": {
290
- "path": "artifacts/sha256-….txt",
291
- "mediaType": "text/plain",
292
- "bytes": 9120,
293
- "sha256": "…"
294
- }
295
- },
296
- "output": { "summary": "…" },
297
- "conversation": { "firstEntryId": "a1b2c3d4", "lastEntryId": "c3d4e5f6" }
298
- }
299
- ```
300
-
301
- - `prompt` is the full prompt text for agent steps (`null` for other node
302
- types), subject to value externalization.
303
- - `conversation` is present on agent steps recorded inside a Pi conversation:
304
- the inclusive range of Pi session entry ids in `session/entries.ndjson`
305
- produced by this attempt, from prompt delivery through accepted submission.
306
- Viewers must use this explicit linkage and never infer it heuristically.
307
- - Action steps carry an `action` receipt with `actionType`
308
- (`shell`/`function`). Shell actions also record `command`, `args`, `cwd`,
309
- `exitCode`, `signal`, and `durationMs`. Shell stdout/stderr live in the step
310
- output (the parsed or raw shell result) and are externalized when large.
311
- - When a run pauses at a checkpoint, `waitingOn` names the checkpoint node.
312
- Terminal runs carry `finalOutput` on success and `error` on failure.
313
-
314
- ## trace.ndjson
315
-
316
- One event per line, monotonically sequenced per run, schema
317
- `pi-workflows.trace-event.v1`:
318
-
319
- ```json
320
- {
321
- "seq": 3,
322
- "at": "2026-07-29T02:39:14.101Z",
323
- "scope": "agent",
324
- "type": "agent_prompt_sent",
325
- "runId": "20260729T023912Z-autoimplement-3f2a9c1b",
326
- "nodeId": "implement",
327
- "attemptId": "d81f…",
328
- "payload": { "prompt": "…" }
329
- }
330
- ```
331
-
332
- `scope` is one of `run`, `node`, `agent`, `action`, or `session`.
333
- A node-scoped `update_published` event carries the runtime update ID, type, key, and data;
334
- its event sequence and timestamp are the update sequence and timestamp. See
335
- [WORKFLOW_UPDATES.md](WORKFLOW_UPDATES.md) for the full contract. `nodeId` and
336
- `attemptId` are present on node-scoped and agent-scoped events. Consumers must
337
- ignore unknown event types and unknown payload fields so new ones can be added
338
- within the same schema version.
339
-
340
- The trace alone is sufficient to reconstruct the run because terminal node
341
- events carry outputs and receipts.
342
-
343
- Event catalog and payload contracts:
344
-
345
- | type | scope | payload |
346
- | ------------------- | ------- | ------------------------------------------------------------------- |
347
- | `run_started` | run | `workflowName`, `runTitle?`, `input` |
348
- | `session_bound` | session | `piSessionId` |
349
- | `node_started` | node | `nodeType`, `statusDetail?` |
350
- | `agent_prompt_sent` | agent | `prompt` |
351
- | `node_finished` | node | `outcome: "ok"`, `durationMs`, `output`, `conversation?`, `action?` |
352
- | `node_failed` | node | `outcome`, `durationMs`, `error`, `conversation?`, `action?` |
353
- | `include_entered` | run | `mountPath`, `workflowName`, `invocation` |
354
- | `include_exited` | run | `mountPath`, `workflowName`, `invocation`, `exit`, `output` |
355
- | `run_paused` | run | _(empty)_ |
356
- | `run_resumed` | run | _(empty)_ |
357
- | `run_completed` | run | `status`, `finalOutput` |
358
- | `run_waiting` | run | `status`, `waitingOn`, `finalOutput` |
359
- | `run_failed` | run | `status`, `error` |
360
- | `run_timed_out` | run | `status`, `error` |
361
- | `run_cancelled` | run | `status`, `error?` |
362
- | `run_interrupted` | run | `error` |
363
-
364
- Invariants:
365
-
366
- - every node attempt has exactly one `node_started` and exactly one terminal
367
- `node_finished`/`node_failed` with the same `attemptId`;
368
- - `attemptId` values are unique within a run;
369
- - a terminal `run_*` event is the last event of the run;
370
- - events are never rewritten or deleted.
371
-
372
- ## session/
373
-
374
- Present when the run executed inside a Pi conversation. The extension records
375
- the conversation into the bundle so replay never depends on Pi's global
376
- session store.
377
-
378
- A run that outlives its first session (parked, then resumed by another
379
- session or the host) gains a second capture under
380
- `session/segments/<attemptId>/` with the same file layout (`binding.json`,
381
- `entries.ndjson`, `events.ndjson`, `capture.json`). The first capture stays
382
- flat at `session/`; only captures from the second bind onward become
383
- segments, so readers that predate segments keep working on single-session
384
- bundles. An interrupted run finalizes any segment still `recording` as
385
- `failed` with the interruption reason.
386
-
387
- ### binding.json
388
-
389
- Written once when the run binds to the conversation
390
- (`pi-workflows.session-binding.v1`):
391
-
392
- ```json
393
- {
394
- "schema": "pi-workflows.session-binding.v1",
395
- "runId": "20260729T023912Z-autoimplement-3f2a9c1b",
396
- "piSessionId": "019fad89-…",
397
- "piSessionFile": "/home/user/.pi/agent/sessions/--repo--/2026-07-29….jsonl",
398
- "cwd": "/repo",
399
- "boundAt": "2026-07-29T02:39:12.412Z"
400
- }
401
- ```
402
-
403
- `piSessionFile` is provenance only and absent for in-memory sessions; replay
404
- readers must not read it.
405
-
406
- ### entries.ndjson
407
-
408
- Append-only copies of the Pi session entries produced on the current branch
409
- while the run was active, schema `pi-workflows.session-entry.v1`:
410
-
411
- ```json
412
- {
413
- "seq": 1,
414
- "at": "2026-07-29T02:39:12.902Z",
415
- "entry": {
416
- "type": "message",
417
- "id": "a1b2c3d4",
418
- "parentId": "9f8e7d6c",
419
- "timestamp": "…",
420
- "message": { "role": "user", "content": "…" }
421
- }
422
- }
423
- ```
424
-
425
- - `seq` is strictly increasing within the file, starting at 1.
426
- - `entry` is the verbatim Pi session entry (Pi's own versioned format),
427
- including user messages, assistant messages, tool results, model changes,
428
- and compaction entries. Nothing is normalized or rewritten.
429
- - Entries include everything that happened in the conversation during the run.
430
- This includes workflow prompts and nudges together with user interruptions.
431
- - `conversation` ranges in step records and `node_finished` events address
432
- entries by Pi entry id (`entry.id`).
433
-
434
- ### events.ndjson
435
-
436
- The temporal journal records documented Pi `turn_*` and `message_*` hooks plus
437
- `tool_execution_*` hooks with schema `pi-workflows.session-event.v1`. Each
438
- record has a per-file `seq`, timestamp, `nodeId`, and `attemptId`. Optional
439
- turn, message, and tool call IDs link related records. A normalized `type` and
440
- `payload` carry the event data.
441
- The full contract and event catalog are in
442
- [session-event-journal.md](session-event-journal.md).
443
-
444
- Events preserve semantic deltas. Assistant `partial` snapshots are never
445
- stored, and neither are terminal `message` or `error` snapshots. Tool update records omit Pi's
446
- cumulative `partialResult`. Final `message_finished` records link to settled
447
- Pi entries with `entryId`; after that linkage, `entries.ndjson` is the
448
- verbatim content authority.
449
-
450
- Readers process events by `seq`. Timestamps schedule playback but never reorder
451
- records. A torn final line is buffered while capture is `recording`; malformed
452
- complete lines, sequence gaps, and terminal torn tails are integrity failures.
453
-
454
- ### capture.json
455
-
456
- `capture.json` is an atomically replaced integrity projection:
457
-
458
- ```json
459
- {
460
- "schema": "pi-workflows.session-capture.v1",
461
- "eventSchema": "pi-workflows.session-event.v1",
462
- "status": "complete",
463
- "eventCount": 241,
464
- "entryCount": 7,
465
- "lastEventSeq": 241
466
- }
467
- ```
468
-
469
- `status` starts as `recording` and ends as `complete` or `failed`. Failed
470
- capture adds `failure` with `failedAt` plus a code and message. Capture failure
471
- is visible to readers but does not fail the workflow. Terminal readers verify
472
- the counts and last sequence, then check schemas and contiguous event order. Missing temporal files
473
- in a session-bound bundle are invalid, not an older supported layout.
474
-
475
- ## Versioning
476
-
477
- Each file carries a versioned schema identifier, and the identifier changes
478
- only on breaking shape changes. Readers check `manifest.json`'s `schema` field
479
- and skip bundles they do not understand. Within a version, additions of new
480
- fields and new trace event types are allowed; readers must ignore what they do
481
- not know.
@@ -1,50 +0,0 @@
1
- {
2
- "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-accepted-v2.schema.json",
4
- "title": "pi-workflows accepted human decision v2",
5
- "type": "object",
6
- "additionalProperties": false,
7
- "required": [
8
- "schema",
9
- "decisionId",
10
- "requestDigest",
11
- "subjectDigest",
12
- "presentationDigest",
13
- "revision",
14
- "response",
15
- "source",
16
- "idempotencyKey",
17
- "acceptedAt",
18
- "answerDigest"
19
- ],
20
- "properties": {
21
- "schema": { "const": "pi-workflows.human-decision-accepted.v2" },
22
- "decisionId": { "type": "string" },
23
- "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
24
- "subjectDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
25
- "presentationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
26
- "revision": { "type": "integer", "minimum": 1 },
27
- "response": {
28
- "type": "object",
29
- "additionalProperties": false,
30
- "required": ["choice"],
31
- "properties": {
32
- "choice": { "type": "string" },
33
- "input": { "type": "object", "additionalProperties": { "type": "string" } }
34
- }
35
- },
36
- "source": {
37
- "type": "object",
38
- "additionalProperties": false,
39
- "required": ["channel", "actorId", "eventId"],
40
- "properties": {
41
- "channel": { "type": "string" },
42
- "actorId": { "type": "string" },
43
- "eventId": { "type": "string" }
44
- }
45
- },
46
- "idempotencyKey": { "type": "string" },
47
- "acceptedAt": { "type": "string", "format": "date-time" },
48
- "answerDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
49
- }
50
- }
@@ -1,36 +0,0 @@
1
- {
2
- "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-delivery-v2.schema.json",
4
- "title": "pi-workflows human decision delivery v2",
5
- "type": "object",
6
- "additionalProperties": false,
7
- "required": [
8
- "schema",
9
- "attemptId",
10
- "decisionId",
11
- "requestDigest",
12
- "presentationDigest",
13
- "channel",
14
- "phase",
15
- "state",
16
- "createdAt"
17
- ],
18
- "properties": {
19
- "schema": { "const": "pi-workflows.human-decision-delivery.v2" },
20
- "attemptId": { "type": "string" },
21
- "decisionId": { "type": "string" },
22
- "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
23
- "presentationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
24
- "channel": { "type": "string" },
25
- "phase": { "enum": ["intent", "part", "complete"] },
26
- "state": { "enum": ["intent", "confirmed", "failed", "unknown"] },
27
- "createdAt": { "type": "string", "format": "date-time" },
28
- "finishedAt": { "type": "string", "format": "date-time" },
29
- "recipientIndex": { "type": "integer", "minimum": 1 },
30
- "partIndex": { "type": "integer", "minimum": 1 },
31
- "partCount": { "type": "integer", "minimum": 1, "maximum": 20 },
32
- "contentDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
33
- "messageCount": { "type": "integer", "minimum": 0 },
34
- "errorCode": { "type": "string" }
35
- }
36
- }
@@ -1,39 +0,0 @@
1
- {
2
- "$schema": "https://json-schema.org/draft/2020-12/schema",
3
- "$id": "https://github.com/osolmaz/pi-workflows/schemas/human-decision-receipt-v2.schema.json",
4
- "title": "pi-workflows redacted human decision receipt v2",
5
- "type": "object",
6
- "additionalProperties": false,
7
- "required": [
8
- "schema",
9
- "decisionId",
10
- "requestDigest",
11
- "subjectDigest",
12
- "presentationDigest",
13
- "revision",
14
- "nodeId",
15
- "response",
16
- "acceptedAt",
17
- "answerDigest"
18
- ],
19
- "properties": {
20
- "schema": { "const": "pi-workflows.human-decision-receipt.v2" },
21
- "decisionId": { "type": "string" },
22
- "requestDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
23
- "subjectDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
24
- "presentationDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" },
25
- "revision": { "type": "integer", "minimum": 1 },
26
- "nodeId": { "type": "string" },
27
- "response": {
28
- "type": "object",
29
- "additionalProperties": false,
30
- "required": ["choice"],
31
- "properties": {
32
- "choice": { "type": "string" },
33
- "input": { "type": "object", "additionalProperties": { "type": "string" } }
34
- }
35
- },
36
- "acceptedAt": { "type": "string", "format": "date-time" },
37
- "answerDigest": { "type": "string", "pattern": "^sha256:[a-f0-9]{64}$" }
38
- }
39
- }