@osolmaz/pi-workflows 0.16.2 → 0.16.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (315) hide show
  1. package/README.md +41 -41
  2. package/dist/builtins/monitor.workflow.d.ts +1 -1
  3. package/dist/builtins/monitor.workflow.js +8 -8
  4. package/dist/builtins/pi-agent-group.js +3 -3
  5. package/dist/builtins/pi-agent-group.js.map +1 -1
  6. package/dist/channels/adapter-entry.js +14 -14
  7. package/dist/channels/adapter-entry.js.map +1 -1
  8. package/dist/client/client.d.ts +6 -6
  9. package/dist/client/client.js +27 -27
  10. package/dist/client/client.js.map +1 -1
  11. package/dist/client/protocol.d.ts +4 -1
  12. package/dist/client/protocol.js +17 -11
  13. package/dist/client/protocol.js.map +1 -1
  14. package/dist/client/resolver.d.ts +4 -4
  15. package/dist/client/view.d.ts +1 -1
  16. package/dist/extension/index.d.ts +1 -1
  17. package/dist/extension/index.js +32 -32
  18. package/dist/extension/index.js.map +1 -1
  19. package/dist/extension/recorder.d.ts +1 -1
  20. package/dist/extension/recorder.js +1 -1
  21. package/dist/extension/recorder.js.map +1 -1
  22. package/dist/extension/remote-recorder-store.d.ts +1 -1
  23. package/dist/extension/remote-recorder-store.js +2 -2
  24. package/dist/extension/remote-recorder-store.js.map +1 -1
  25. package/dist/extension/{controller-command.d.ts → resource-manager-command.d.ts} +6 -6
  26. package/dist/extension/{controller-command.js → resource-manager-command.js} +7 -7
  27. package/dist/extension/resource-manager-command.js.map +1 -0
  28. package/dist/extension/session-delivery.d.ts +1 -1
  29. package/dist/extension/session-delivery.js +2 -2
  30. package/dist/extension/session-delivery.js.map +1 -1
  31. package/dist/extension/session-view.d.ts +1 -1
  32. package/dist/extension/session-view.js +1 -1
  33. package/dist/extension/session-view.js.map +1 -1
  34. package/dist/extension/workflow-message-coordinator.d.ts +1 -1
  35. package/dist/extension/workflow-message-coordinator.js +6 -6
  36. package/dist/extension/workflow-message-coordinator.js.map +1 -1
  37. package/dist/resource-managers/conditions.d.ts +6 -0
  38. package/dist/{controllers → resource-managers}/conditions.js +3 -3
  39. package/dist/resource-managers/conditions.js.map +1 -0
  40. package/dist/resource-managers/definition.d.ts +6 -0
  41. package/dist/resource-managers/definition.js +45 -0
  42. package/dist/resource-managers/definition.js.map +1 -0
  43. package/dist/resource-managers/effects.d.ts +15 -0
  44. package/dist/{controllers → resource-managers}/effects.js +2 -2
  45. package/dist/resource-managers/effects.js.map +1 -0
  46. package/dist/resource-managers/errors.d.ts +12 -0
  47. package/dist/resource-managers/errors.js +25 -0
  48. package/dist/resource-managers/errors.js.map +1 -0
  49. package/dist/resource-managers/index.d.ts +12 -0
  50. package/dist/resource-managers/index.js +12 -0
  51. package/dist/resource-managers/index.js.map +1 -0
  52. package/dist/resource-managers/json.js.map +1 -0
  53. package/dist/resource-managers/loader.d.ts +23 -0
  54. package/dist/resource-managers/loader.js +75 -0
  55. package/dist/resource-managers/loader.js.map +1 -0
  56. package/dist/resource-managers/results.d.ts +5 -0
  57. package/dist/resource-managers/results.js.map +1 -0
  58. package/dist/resource-managers/runtime.d.ts +59 -0
  59. package/dist/{controllers/manager.js → resource-managers/runtime.js} +57 -57
  60. package/dist/resource-managers/runtime.js.map +1 -0
  61. package/dist/{controllers → resource-managers}/sqlite.d.ts +44 -44
  62. package/dist/{controllers → resource-managers}/sqlite.js +139 -130
  63. package/dist/resource-managers/sqlite.js.map +1 -0
  64. package/dist/{controllers → resource-managers}/store.d.ts +33 -33
  65. package/dist/{controllers → resource-managers}/store.js.map +1 -1
  66. package/dist/{controllers → resource-managers}/types.d.ts +41 -41
  67. package/dist/{controllers → resource-managers}/types.js.map +1 -1
  68. package/dist/resource-managers/workflows.d.ts +34 -0
  69. package/dist/{controllers → resource-managers}/workflows.js +15 -15
  70. package/dist/resource-managers/workflows.js.map +1 -0
  71. package/dist/server/channel-effects.js.map +1 -0
  72. package/dist/{host → server}/channel-supervisor.d.ts +6 -6
  73. package/dist/{host → server}/channel-supervisor.js +3 -3
  74. package/dist/server/channel-supervisor.js.map +1 -0
  75. package/dist/{host/child-worker-supervisor.d.ts → server/child-runner-supervisor.d.ts} +15 -13
  76. package/dist/{host/child-worker-supervisor.js → server/child-runner-supervisor.js} +6 -5
  77. package/dist/server/child-runner-supervisor.js.map +1 -0
  78. package/dist/{host → server}/processes.d.ts +3 -3
  79. package/dist/{host → server}/processes.js +3 -3
  80. package/dist/server/processes.js.map +1 -0
  81. package/dist/{host → server}/resolver-entry.d.ts +6 -6
  82. package/dist/{host → server}/resolver-entry.js +14 -14
  83. package/dist/server/resolver-entry.js.map +1 -0
  84. package/dist/server/resource-runner-entry.d.ts +2 -0
  85. package/dist/{host/controller-worker-entry.js → server/resource-runner-entry.js} +33 -33
  86. package/dist/server/resource-runner-entry.js.map +1 -0
  87. package/dist/server/resource-runner-protocol.d.ts +36 -0
  88. package/dist/server/resource-runner-protocol.js +49 -0
  89. package/dist/server/resource-runner-protocol.js.map +1 -0
  90. package/dist/server/resource-runner-supervisor.d.ts +21 -0
  91. package/dist/{host/worker-supervisor.js → server/resource-runner-supervisor.js} +17 -17
  92. package/dist/server/resource-runner-supervisor.js.map +1 -0
  93. package/dist/{host → server}/rpc-bridge.d.ts +3 -3
  94. package/dist/{host → server}/rpc-bridge.js +3 -3
  95. package/dist/server/rpc-bridge.js.map +1 -0
  96. package/dist/{host → server}/rpc-executor.d.ts +1 -1
  97. package/dist/{host → server}/rpc-executor.js +3 -3
  98. package/dist/server/rpc-executor.js.map +1 -0
  99. package/dist/{host/host-entry.js → server/server-entry.js} +6 -6
  100. package/dist/server/server-entry.js.map +1 -0
  101. package/dist/{host/runner.d.ts → server/server.d.ts} +39 -38
  102. package/dist/{host/runner.js → server/server.js} +408 -374
  103. package/dist/server/server.js.map +1 -0
  104. package/dist/{host → server}/state.d.ts +25 -25
  105. package/dist/{host → server}/state.js +49 -49
  106. package/dist/server/state.js.map +1 -0
  107. package/dist/{host → server}/view.d.ts +7 -7
  108. package/dist/{host → server}/view.js +13 -13
  109. package/dist/server/view.js.map +1 -0
  110. package/dist/server/workflow-runner-content.d.ts +6 -0
  111. package/dist/server/workflow-runner-content.js +96 -0
  112. package/dist/server/workflow-runner-content.js.map +1 -0
  113. package/dist/{host/worker-entry.d.ts → server/workflow-runner-entry.d.ts} +3 -3
  114. package/dist/{host/worker-entry.js → server/workflow-runner-entry.js} +68 -35
  115. package/dist/server/workflow-runner-entry.js.map +1 -0
  116. package/dist/server/workflow-runner-protocol.d.ts +69 -0
  117. package/dist/server/workflow-runner-protocol.js +176 -0
  118. package/dist/server/workflow-runner-protocol.js.map +1 -0
  119. package/dist/{host/worker-store.d.ts → server/workflow-runner-store.d.ts} +11 -11
  120. package/dist/{host/worker-store.js → server/workflow-runner-store.js} +8 -8
  121. package/dist/server/workflow-runner-store.js.map +1 -0
  122. package/dist/server/workflow-runner-supervisor.d.ts +22 -0
  123. package/dist/server/workflow-runner-supervisor.js +56 -0
  124. package/dist/server/workflow-runner-supervisor.js.map +1 -0
  125. package/dist/state/prune.d.ts +1 -1
  126. package/dist/state/prune.js +17 -10
  127. package/dist/state/prune.js.map +1 -1
  128. package/dist/state/schema.js +2 -2
  129. package/dist/state/workflow-messages.d.ts +1 -1
  130. package/dist/state/workflow-messages.js +1 -1
  131. package/dist/state/workflow-messages.js.map +1 -1
  132. package/dist/viewer/backup.js +1 -1
  133. package/dist/viewer/backup.js.map +1 -1
  134. package/dist/viewer/cli.d.ts +2 -2
  135. package/dist/viewer/cli.js +46 -32
  136. package/dist/viewer/cli.js.map +1 -1
  137. package/dist/viewer/tui.d.ts +1 -1
  138. package/dist/viewer/tui.js +1 -1
  139. package/dist/viewer/tui.js.map +1 -1
  140. package/dist/workflows/command-batch.js +2 -2
  141. package/dist/workflows/engine.js +14 -15
  142. package/dist/workflows/engine.js.map +1 -1
  143. package/dist/workflows/store.d.ts +12 -11
  144. package/dist/workflows/store.js +24 -18
  145. package/dist/workflows/store.js.map +1 -1
  146. package/dist/workflows/types.d.ts +2 -2
  147. package/docs/2026-08-20-durable-workflow-launch-plan.md +12 -12
  148. package/docs/2026-08-25-workflow-follow-ups.md +7 -7
  149. package/docs/2026-08-25-workflow-settings.md +3 -3
  150. package/docs/2026-08-30-out-of-process-workflow-host-plan.md +3 -3
  151. package/docs/2026-09-01-restore-session-delivery-controls-plan.md +5 -5
  152. package/docs/2026-09-01-unified-workflow-client-plan.md +6 -6
  153. package/docs/2026-09-02-installed-live-e2e-plan.md +3 -3
  154. package/docs/2026-09-02-unify-workflow-messages-plan.md +8 -8
  155. package/docs/2026-09-04-workflow-run-state-plan.md +6 -6
  156. package/docs/DEFERRED_TURNS.md +7 -7
  157. package/docs/DESIGN_PHILOSOPHY.md +1 -1
  158. package/docs/HUMAN_DECISIONS.md +11 -11
  159. package/docs/HUMAN_DECISION_PRESENTATIONS.md +4 -4
  160. package/docs/MONITOR.md +1 -1
  161. package/docs/RESOURCE_MANAGERS.md +221 -0
  162. package/docs/SQLITE_STATE.md +35 -33
  163. package/docs/WORKFLOW_COMPOSITION.md +1 -1
  164. package/docs/{WORKFLOW_HOST.md → WORKFLOW_SERVER.md} +125 -119
  165. package/docs/WORKFLOW_STEP_MESSAGES.md +18 -18
  166. package/docs/WORKFLOW_UPDATES.md +16 -16
  167. package/docs/development.md +15 -14
  168. package/docs/live-replay-protocol.md +20 -20
  169. package/docs/plans/2026-08-04-controller-runtime-plan.md +25 -25
  170. package/docs/plans/2026-08-05-always-on-workflows-plan.md +8 -8
  171. package/docs/plans/2026-08-10-agent-managed-monitor-workflows-plan.md +2 -2
  172. package/docs/plans/2026-08-13-session-addressed-workflow-notifications-plan.md +1 -1
  173. package/docs/plans/2026-08-16-workflow-updates-plan.md +5 -5
  174. package/docs/plans/2026-08-19-human-decision-gates-plan.md +1 -1
  175. package/docs/plans/2026-08-20-bounded-command-batches-plan.md +1 -1
  176. package/docs/plans/2026-08-21-deferred-turn-intents-plan.md +3 -3
  177. package/docs/plans/2026-08-21-sanity-check-plan.md +2 -2
  178. package/docs/plans/2026-08-23-assistant-agent-completion-plan.md +5 -5
  179. package/docs/plans/2026-08-23-sqlite-state-plan.md +25 -25
  180. package/docs/plans/2026-08-25-live-workflow-settings-plan.md +4 -4
  181. package/docs/plans/2026-08-27-workflow-terminal-restart-plan.md +3 -3
  182. package/docs/plans/2026-09-04-workflow-runner-resume-state-plan.md +318 -0
  183. package/docs/plans/piw-viewer-experience-implementation-plan.md +1 -1
  184. package/docs/tui-viewer.md +9 -9
  185. package/docs/workflows.md +72 -66
  186. package/examples/{controllers/pull-request.controller.ts → resource-managers/pull-request.resource-manager.ts} +12 -12
  187. package/herdr-plugin.toml +1 -1
  188. package/package.json +5 -5
  189. package/protocol/client.v1.schema.json +7 -7
  190. package/protocol/fixtures/client-v1.json +1 -1
  191. package/src/builtins/monitor.workflow.ts +9 -9
  192. package/src/builtins/pi-agent-group.ts +3 -3
  193. package/src/channels/adapter-entry.ts +14 -14
  194. package/src/client/client.ts +33 -32
  195. package/src/client/protocol.ts +16 -11
  196. package/src/client/resolver.ts +4 -4
  197. package/src/client/view.ts +1 -1
  198. package/src/extension/index.ts +44 -34
  199. package/src/extension/recorder.ts +1 -1
  200. package/src/extension/remote-recorder-store.ts +2 -2
  201. package/src/extension/resource-manager-command.ts +45 -0
  202. package/src/extension/session-delivery.ts +2 -2
  203. package/src/extension/session-view.ts +1 -1
  204. package/src/extension/workflow-message-coordinator.ts +6 -6
  205. package/src/{controllers → resource-managers}/conditions.ts +23 -23
  206. package/src/resource-managers/definition.ts +71 -0
  207. package/src/{controllers → resource-managers}/effects.ts +9 -9
  208. package/src/resource-managers/errors.ts +27 -0
  209. package/src/resource-managers/index.ts +88 -0
  210. package/src/resource-managers/loader.ts +111 -0
  211. package/src/{controllers → resource-managers}/results.ts +4 -4
  212. package/src/{controllers/manager.ts → resource-managers/runtime.ts} +95 -92
  213. package/src/{controllers → resource-managers}/sqlite.ts +198 -186
  214. package/src/{controllers → resource-managers}/store.ts +46 -38
  215. package/src/{controllers → resource-managers}/types.ts +50 -41
  216. package/src/{controllers → resource-managers}/workflows.ts +43 -41
  217. package/src/{host → server}/channel-supervisor.ts +8 -8
  218. package/src/{host/child-worker-supervisor.ts → server/child-runner-supervisor.ts} +22 -18
  219. package/src/{host → server}/processes.ts +3 -3
  220. package/src/{host → server}/resolver-entry.ts +28 -25
  221. package/src/{host/controller-worker-entry.ts → server/resource-runner-entry.ts} +67 -65
  222. package/src/server/resource-runner-protocol.ts +103 -0
  223. package/src/server/resource-runner-supervisor.ts +76 -0
  224. package/src/{host → server}/rpc-bridge.ts +3 -3
  225. package/src/{host → server}/rpc-executor.ts +4 -4
  226. package/src/{host/host-entry.ts → server/server-entry.ts} +5 -5
  227. package/src/{host/runner.ts → server/server.ts} +526 -461
  228. package/src/{host → server}/state.ts +78 -67
  229. package/src/{host → server}/view.ts +15 -15
  230. package/src/server/workflow-runner-content.ts +119 -0
  231. package/src/{host/worker-entry.ts → server/workflow-runner-entry.ts} +98 -57
  232. package/src/server/workflow-runner-protocol.ts +241 -0
  233. package/src/{host/worker-store.ts → server/workflow-runner-store.ts} +18 -20
  234. package/src/server/workflow-runner-supervisor.ts +79 -0
  235. package/src/state/prune.ts +27 -9
  236. package/src/state/schema.ts +2 -2
  237. package/src/state/workflow-messages.ts +1 -1
  238. package/src/viewer/backup.ts +1 -1
  239. package/src/viewer/cli.ts +50 -36
  240. package/src/viewer/tui.ts +1 -1
  241. package/src/workflows/command-batch.ts +2 -2
  242. package/src/workflows/engine.ts +14 -15
  243. package/src/workflows/store.ts +31 -28
  244. package/src/workflows/types.ts +2 -2
  245. package/dist/controllers/conditions.d.ts +0 -6
  246. package/dist/controllers/conditions.js.map +0 -1
  247. package/dist/controllers/definition.d.ts +0 -6
  248. package/dist/controllers/definition.js +0 -45
  249. package/dist/controllers/definition.js.map +0 -1
  250. package/dist/controllers/effects.d.ts +0 -15
  251. package/dist/controllers/effects.js.map +0 -1
  252. package/dist/controllers/errors.d.ts +0 -12
  253. package/dist/controllers/errors.js +0 -25
  254. package/dist/controllers/errors.js.map +0 -1
  255. package/dist/controllers/index.d.ts +0 -12
  256. package/dist/controllers/index.js +0 -12
  257. package/dist/controllers/index.js.map +0 -1
  258. package/dist/controllers/json.js.map +0 -1
  259. package/dist/controllers/loader.d.ts +0 -23
  260. package/dist/controllers/loader.js +0 -74
  261. package/dist/controllers/loader.js.map +0 -1
  262. package/dist/controllers/manager.d.ts +0 -59
  263. package/dist/controllers/manager.js.map +0 -1
  264. package/dist/controllers/results.d.ts +0 -5
  265. package/dist/controllers/results.js.map +0 -1
  266. package/dist/controllers/sqlite.js.map +0 -1
  267. package/dist/controllers/workflows.d.ts +0 -34
  268. package/dist/controllers/workflows.js.map +0 -1
  269. package/dist/extension/controller-command.js.map +0 -1
  270. package/dist/host/channel-effects.js.map +0 -1
  271. package/dist/host/channel-supervisor.js.map +0 -1
  272. package/dist/host/child-worker-supervisor.js.map +0 -1
  273. package/dist/host/controller-worker-entry.d.ts +0 -2
  274. package/dist/host/controller-worker-entry.js.map +0 -1
  275. package/dist/host/controller-worker-protocol.d.ts +0 -36
  276. package/dist/host/controller-worker-protocol.js +0 -49
  277. package/dist/host/controller-worker-protocol.js.map +0 -1
  278. package/dist/host/controller-worker-supervisor.d.ts +0 -21
  279. package/dist/host/controller-worker-supervisor.js +0 -54
  280. package/dist/host/controller-worker-supervisor.js.map +0 -1
  281. package/dist/host/host-entry.js.map +0 -1
  282. package/dist/host/processes.js.map +0 -1
  283. package/dist/host/resolver-entry.js.map +0 -1
  284. package/dist/host/rpc-bridge.js.map +0 -1
  285. package/dist/host/rpc-executor.js.map +0 -1
  286. package/dist/host/runner.js.map +0 -1
  287. package/dist/host/state.js.map +0 -1
  288. package/dist/host/view.js.map +0 -1
  289. package/dist/host/worker-entry.js.map +0 -1
  290. package/dist/host/worker-protocol.d.ts +0 -46
  291. package/dist/host/worker-protocol.js +0 -122
  292. package/dist/host/worker-protocol.js.map +0 -1
  293. package/dist/host/worker-store.js.map +0 -1
  294. package/dist/host/worker-supervisor.d.ts +0 -22
  295. package/dist/host/worker-supervisor.js.map +0 -1
  296. package/docs/CONTROLLERS.md +0 -217
  297. package/src/controllers/definition.ts +0 -65
  298. package/src/controllers/errors.ts +0 -27
  299. package/src/controllers/index.ts +0 -88
  300. package/src/controllers/loader.ts +0 -104
  301. package/src/extension/controller-command.ts +0 -45
  302. package/src/host/controller-worker-protocol.ts +0 -104
  303. package/src/host/controller-worker-supervisor.ts +0 -79
  304. package/src/host/worker-protocol.ts +0 -176
  305. package/src/host/worker-supervisor.ts +0 -74
  306. /package/dist/{controllers → resource-managers}/json.d.ts +0 -0
  307. /package/dist/{controllers → resource-managers}/json.js +0 -0
  308. /package/dist/{controllers → resource-managers}/results.js +0 -0
  309. /package/dist/{controllers → resource-managers}/store.js +0 -0
  310. /package/dist/{controllers → resource-managers}/types.js +0 -0
  311. /package/dist/{host → server}/channel-effects.d.ts +0 -0
  312. /package/dist/{host → server}/channel-effects.js +0 -0
  313. /package/dist/{host/host-entry.d.ts → server/server-entry.d.ts} +0 -0
  314. /package/src/{controllers → resource-managers}/json.ts +0 -0
  315. /package/src/{host → server}/channel-effects.ts +0 -0
@@ -1,46 +0,0 @@
1
- import { type JsonValue } from "../state/json.js";
2
- export declare const WORKER_MESSAGE_SCHEMA: "pi-workflows.worker-message.v1";
3
- export declare const WORKER_RESPONSE_SCHEMA: "pi-workflows.worker-response.v1";
4
- export type WorkerRunCommand = {
5
- kind: "start";
6
- input: JsonValue;
7
- } | {
8
- kind: "resume";
9
- resumeInteractionAttemptId?: string;
10
- } | {
11
- kind: "continue";
12
- parentRunId: string;
13
- input: JsonValue;
14
- humanDecision?: JsonValue;
15
- } | {
16
- kind: "restart";
17
- input: JsonValue;
18
- };
19
- export declare const WORKER_MESSAGE_KINDS: readonly ["worker.ready", "node.started", "node.update", "node.finished", "node.failed", "run.parked", "run.finished", "interaction.requested", "interaction.accepted", "interaction.rejected", "notification.requested", "presentation.requested", "effect.reserve", "effect.settle", "worker.progress", "worker.exiting"];
20
- export type WorkerMessageKind = (typeof WORKER_MESSAGE_KINDS)[number];
21
- export type WorkerStoreOperation = "store.initializeRun" | "store.prepareRunResume" | "store.readRun" | "store.writeSnapshot" | "store.publishUpdate" | "store.findSettingsScope" | "store.ensureSettingsScope" | "store.getSettingsScopeAtChange" | "store.createHumanDecisionRequest" | "store.readResolvedHumanDecision" | "store.reserveEffect" | "store.settleEffect" | "process.register" | "process.unregister" | "interaction.request" | "interaction.accept" | "interaction.reject" | "notification.request" | "presentation.request";
22
- export type WorkerMessage = {
23
- schema: typeof WORKER_MESSAGE_SCHEMA;
24
- launchSchema: "pi-workflows.worker-launch.v1";
25
- messageId: string;
26
- kind: WorkerMessageKind;
27
- operation: WorkerStoreOperation | "worker.ready" | "worker.exiting";
28
- runId: string;
29
- generation: number;
30
- workerEpoch: string;
31
- expectedRevision: number;
32
- attemptId?: string;
33
- payload: JsonValue;
34
- };
35
- export type WorkerResponse = {
36
- schema: typeof WORKER_RESPONSE_SCHEMA;
37
- messageId: string;
38
- outcome: "accepted" | "adopted" | "rejected" | "claimLost";
39
- revision?: number;
40
- result?: JsonValue;
41
- error?: string;
42
- };
43
- export declare function workerKindForOperation(operation: WorkerStoreOperation, payload: Record<string, unknown>): WorkerMessageKind;
44
- export declare function encodeWorkerLine(message: WorkerMessage | WorkerResponse): Buffer;
45
- export declare function parseWorkerMessage(line: Buffer | string): WorkerMessage;
46
- export declare function parseWorkerResponse(line: Buffer | string): WorkerResponse;
@@ -1,122 +0,0 @@
1
- import { MAX_PROTOCOL_MESSAGE_BYTES } from "../client/protocol.js";
2
- import { canonicalJson, parseJson } from "../state/json.js";
3
- export const WORKER_MESSAGE_SCHEMA = "pi-workflows.worker-message.v1";
4
- export const WORKER_RESPONSE_SCHEMA = "pi-workflows.worker-response.v1";
5
- export const WORKER_MESSAGE_KINDS = [
6
- "worker.ready",
7
- "node.started",
8
- "node.update",
9
- "node.finished",
10
- "node.failed",
11
- "run.parked",
12
- "run.finished",
13
- "interaction.requested",
14
- "interaction.accepted",
15
- "interaction.rejected",
16
- "notification.requested",
17
- "presentation.requested",
18
- "effect.reserve",
19
- "effect.settle",
20
- "worker.progress",
21
- "worker.exiting",
22
- ];
23
- export function workerKindForOperation(operation, payload) {
24
- if (operation === "store.publishUpdate")
25
- return "node.update";
26
- if (operation === "store.reserveEffect")
27
- return "effect.reserve";
28
- if (operation === "store.settleEffect")
29
- return "effect.settle";
30
- if (operation === "store.createHumanDecisionRequest" || operation === "interaction.request") {
31
- return "interaction.requested";
32
- }
33
- if (operation === "interaction.accept")
34
- return "interaction.accepted";
35
- if (operation === "interaction.reject")
36
- return "interaction.rejected";
37
- if (operation === "notification.request")
38
- return "notification.requested";
39
- if (operation === "presentation.request")
40
- return "presentation.requested";
41
- if (operation === "store.writeSnapshot") {
42
- const event = payload.event;
43
- const eventType = isRecord(event) && typeof event.type === "string" ? event.type : "";
44
- if (eventType === "node_started")
45
- return "node.started";
46
- if (eventType === "node_finished")
47
- return "node.finished";
48
- if (eventType === "node_failed" || eventType === "node_timed_out")
49
- return "node.failed";
50
- if (eventType === "run_waiting" || eventType.includes("park"))
51
- return "run.parked";
52
- if (eventType.startsWith("run_") && eventType !== "run_started")
53
- return "run.finished";
54
- }
55
- return "worker.progress";
56
- }
57
- export function encodeWorkerLine(message) {
58
- const encoded = Buffer.from(`${canonicalJson(message)}\n`, "utf8");
59
- if (encoded.byteLength > MAX_PROTOCOL_MESSAGE_BYTES) {
60
- throw new Error("Worker protocol message exceeds 1 MiB");
61
- }
62
- return encoded;
63
- }
64
- export function parseWorkerMessage(line) {
65
- const value = parseWorkerValue(line);
66
- if (value.schema !== WORKER_MESSAGE_SCHEMA ||
67
- value.launchSchema !== "pi-workflows.worker-launch.v1") {
68
- throw new Error("Invalid worker message schema");
69
- }
70
- requireText(value.messageId, "messageId");
71
- requireText(value.runId, "runId");
72
- requireText(value.workerEpoch, "workerEpoch");
73
- if (!WORKER_MESSAGE_KINDS.includes(value.kind)) {
74
- throw new Error("Invalid worker message kind");
75
- }
76
- if (!Number.isSafeInteger(value.generation) || value.generation <= 0) {
77
- throw new Error("Worker generation must be positive");
78
- }
79
- if (!Number.isSafeInteger(value.expectedRevision) || value.expectedRevision < 0) {
80
- throw new Error("Worker expectedRevision must be non-negative");
81
- }
82
- requireText(value.operation, "operation");
83
- if (value.attemptId !== undefined)
84
- requireText(value.attemptId, "attemptId");
85
- if (!Object.hasOwn(value, "payload"))
86
- throw new Error("Worker payload is required");
87
- return value;
88
- }
89
- export function parseWorkerResponse(line) {
90
- const value = parseWorkerValue(line);
91
- if (value.schema !== WORKER_RESPONSE_SCHEMA)
92
- throw new Error("Invalid worker response schema");
93
- requireText(value.messageId, "messageId");
94
- if (!["accepted", "adopted", "rejected", "claimLost"].includes(value.outcome)) {
95
- throw new Error("Invalid worker response outcome");
96
- }
97
- if (value.error !== undefined && typeof value.error !== "string") {
98
- throw new Error("Worker response error must be text");
99
- }
100
- return value;
101
- }
102
- function parseWorkerValue(line) {
103
- const buffer = Buffer.isBuffer(line) ? line : Buffer.from(line, "utf8");
104
- if (buffer.byteLength + 1 > MAX_PROTOCOL_MESSAGE_BYTES) {
105
- throw new Error("Worker protocol message exceeds 1 MiB");
106
- }
107
- const text = buffer.toString("utf8");
108
- const value = parseJson(text);
109
- if (!isRecord(value) || canonicalJson(value) !== text) {
110
- throw new Error("Worker protocol message must be a canonical JSON object");
111
- }
112
- return value;
113
- }
114
- function requireText(value, field) {
115
- if (typeof value !== "string" || value.length === 0 || value.length > 256) {
116
- throw new Error(`Worker ${field} must be nonempty bounded text`);
117
- }
118
- }
119
- function isRecord(value) {
120
- return typeof value === "object" && value !== null && !Array.isArray(value);
121
- }
122
- //# sourceMappingURL=worker-protocol.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"worker-protocol.js","sourceRoot":"","sources":["../../src/host/worker-protocol.ts"],"names":[],"mappings":"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"}
@@ -1 +0,0 @@
1
- {"version":3,"file":"worker-store.js","sourceRoot":"","sources":["../../src/host/worker-store.ts"],"names":[],"mappings":"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"}
@@ -1,22 +0,0 @@
1
- import { type SupervisedWorkerResult } from "./child-worker-supervisor.js";
2
- import { HostProcessRegistry, type ProcessIdentity } from "./processes.js";
3
- import type { WorkerLaunchEnvelope, WorkerOutcome } from "./state.js";
4
- import { type WorkerMessage, type WorkerResponse } from "./worker-protocol.js";
5
- export type WorkflowWorkerResult = SupervisedWorkerResult;
6
- export declare class WorkflowWorkerSupervisor {
7
- readonly envelope: WorkerLaunchEnvelope;
8
- private readonly options;
9
- private readonly supervisor;
10
- constructor(envelope: WorkerLaunchEnvelope, options: {
11
- registry: HostProcessRegistry;
12
- onMessage: (message: WorkerMessage) => Promise<WorkerResponse>;
13
- env?: Record<string, string>;
14
- startupTimeoutMs?: number;
15
- workerEntryPath?: string;
16
- onSpawn?: (identity: ProcessIdentity) => void;
17
- onDiagnostic?: (message: string) => void;
18
- });
19
- start(): Promise<void>;
20
- wait(): Promise<WorkflowWorkerResult>;
21
- stop(outcome?: WorkerOutcome): Promise<void>;
22
- }
@@ -1 +0,0 @@
1
- {"version":3,"file":"worker-supervisor.js","sourceRoot":"","sources":["../../src/host/worker-supervisor.ts"],"names":[],"mappings":"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"}
@@ -1,217 +0,0 @@
1
- # Controller runtime specification
2
-
3
- pi-workflows runs finite TypeScript graphs. A graph starts with an input, follows explicit edges, and ends with a result or checkpoint. This works well for one bounded task.
4
-
5
- Long-running automation has a different job. It must keep comparing a requested state with the current state of another system. Events can arrive more than once, processes can stop between an external request and its local receipt, and the external state can change while work is running.
6
-
7
- This specification adds a Kubernetes-style controller runtime to pi-workflows. The controller runtime sits beside the graph engine. Controllers manage durable resources, while workflows remain finite jobs that a controller can start and observe.
8
-
9
- The design follows the Kubernetes [controller pattern](https://kubernetes.io/docs/concepts/architecture/controller/), its [`spec` and `status` split](https://kubernetes.io/docs/concepts/overview/working-with-objects/), and the [idempotent reconciliation guidance](https://book.kubebuilder.io/reference/good-practices).
10
-
11
- ## Scope
12
-
13
- The controller runtime provides:
14
-
15
- - Durable desired and observed state.
16
- - Level-based reconciliation from current facts.
17
- - A deduplicated work queue with delayed retries.
18
- - Compare-and-swap writes for concurrent workers.
19
- - Recoverable records for external effects.
20
- - Child workflow runs with stable request keys.
21
- - Conditions and generations, with cleanup and structured events.
22
- - Local resource control through the Pi extension and reconciliation through the global host.
23
-
24
- The first production use case is pull request automation. A controller can observe a pull request, start a review or repair workflow, wait for checks, validate the current head, and apply an approved change through deterministic code.
25
-
26
- ## Boundaries
27
-
28
- The graph engine remains the execution layer for finite work. A finite workflow can include another finite workflow in the same run through `includeWorkflow()`. Use a controller child run when work needs an independent retry history, stable request key, parallel lifecycle, or indefinite reconciliation. The graph engine does not import the controller runtime. The controller runtime may start workflows through a narrow scheduler interface.
29
-
30
- The Pi extension is a thin client. It resolves controller initialization in a dedicated child process and sends declarative resource commands to the one global host. The host schedules reconciliation but does not load controller definitions in its event loop. A supervised controller worker loads one definition and proposes bounded state changes through the host.
31
-
32
- External events are wake-up hints. An event enqueues a resource key and carries no transition command. The reconciler reloads the resource and the external system before deciding what to do.
33
-
34
- ## Resource model
35
-
36
- A resource is the durable record of one requested outcome. The controller owns `status`; callers own `spec`.
37
-
38
- ```ts
39
- export type ControllerResource<TSpec, TStatus> = {
40
- metadata: {
41
- uid: string;
42
- controller: string;
43
- key: string;
44
- resourceVersion: number;
45
- generation: number;
46
- deletionTimestamp?: string;
47
- finalizers: string[];
48
- };
49
- spec: TSpec;
50
- status: {
51
- observedGeneration: number;
52
- conditions: ControllerCondition[];
53
- workflowRun?: {
54
- requestId: string;
55
- runId?: string;
56
- state: "pending" | "running" | "waiting" | "succeeded" | "failed" | "interrupted";
57
- attempt: number;
58
- };
59
- controllerStatus: TStatus;
60
- };
61
- };
62
-
63
- export type ControllerCondition = {
64
- type: string;
65
- status: true | false | "unknown";
66
- reason: string;
67
- message?: string;
68
- observedGeneration: number;
69
- lastTransitionTime: string;
70
- };
71
- ```
72
-
73
- `uid` stays stable for the life of the resource and is never reused. `resourceVersion` changes after every write and acts as the compare-and-swap token. `generation` changes only when `spec` changes. A condition describes the latest known state for one stable condition type.
74
-
75
- `observedGeneration` shows which desired state produced the current status. A controller must not report a resource as ready when its conditions came from an older generation.
76
-
77
- ## Controller contract
78
-
79
- A controller receives the latest resource, a cancellation signal, and runtime services. It returns after one bounded reconciliation pass.
80
-
81
- ```ts
82
- import { conditionFalse, conditionTrue, defineController } from "@osolmaz/pi-workflows/controllers";
83
-
84
- export default defineController<PullRequestSpec, PullRequestStatus>({
85
- name: "pull-request",
86
- initialStatus: () => ({ phase: "observing" }),
87
-
88
- async reconcile(ctx, resource) {
89
- const pullRequest = await github.getPullRequest(resource.spec, ctx.signal);
90
-
91
- if (pullRequest.merged) {
92
- return ctx.settled({
93
- controllerStatus: { phase: "merged" },
94
- conditions: [conditionTrue("Ready", "Merged")],
95
- });
96
- }
97
- if (pullRequest.headSha !== resource.spec.expectedHeadSha) {
98
- return ctx.settled({
99
- controllerStatus: { phase: "blocked" },
100
- conditions: [conditionFalse("Ready", "HeadChanged")],
101
- });
102
- }
103
-
104
- const run = await ctx.workflows.ensure({
105
- requestKey: `repair:${resource.metadata.generation}:${pullRequest.headSha}`,
106
- workflow: "repair-pull-request",
107
- input: { repository: resource.spec.repository, number: pullRequest.number },
108
- });
109
- if (run.state !== "succeeded") {
110
- return ctx.requeueAfter(30_000);
111
- }
112
-
113
- await ctx.effects.ensure({
114
- key: `merge:${resource.metadata.generation}:${pullRequest.headSha}`,
115
- kind: "github-merge",
116
- request: { number: pullRequest.number, expectedHeadSha: pullRequest.headSha },
117
- observe: (signal) => github.observeMerge(resource.spec, signal),
118
- apply: (signal) => github.merge(resource.spec, pullRequest.headSha, signal),
119
- });
120
- return ctx.requeue();
121
- },
122
- });
123
- ```
124
-
125
- The runtime supports three normal results. `settled` removes the key from the queue until another event arrives. `requeue` asks for another pass as soon as capacity is available. `requeueAfter` schedules a later pass.
126
-
127
- A returned error receives exponential backoff with jitter. A controller records a durable condition and returns `settled` for a problem that requires new input. Reconciliation retries do not depend on the event that caused the first attempt.
128
-
129
- ## Work queue
130
-
131
- The queue contains one row for each controller and resource key. Repeated enqueue calls update that row instead of adding copies. A worker claims a key with an opaque claim token and an expiry time. The runtime prevents concurrent reconciliation of the same key.
132
-
133
- A claim that expires returns to the queue. A successful settled result removes the queue row. A requested delay updates its available time. Consecutive errors increase an internal retry counter used for backoff.
134
-
135
- The local implementation uses `better-sqlite3` in WAL mode. Transactions cover resource compare-and-swap writes, queue claims, and effect claims. `ControllerStore` remains an interface so another host can supply a remote implementation. Pi hosts use a store scoped to the canonical project directory, which prevents a same-named controller in another project from claiming its resources. The store limits each resource spec and status value to 1 MiB. Event payloads are limited to 64 KiB.
136
-
137
- The resource store is the source of truth. Queue rows only describe delivery. A repair can rebuild the queue by enqueuing every resource; each reconciler then computes any needed delay again.
138
-
139
- ## External effects
140
-
141
- An external effect can succeed while the local process is unable to save the response. The runtime records each effect before calling the provider.
142
-
143
- ```ts
144
- export type EffectRecord = {
145
- key: string;
146
- resourceUid: string;
147
- generation: number;
148
- requestFingerprint: string;
149
- state: "pending" | "applied" | "rejected" | "indeterminate";
150
- externalRef?: string;
151
- startedAt: string;
152
- completedAt?: string;
153
- };
154
- ```
155
-
156
- The key names one intended effect. Reusing the key with another request fingerprint is an error. The next reconciliation observes the external system before retrying an existing pending or indeterminate effect. The effect can be treated as effectively once when the provider offers an idempotency token, a conditional request, or a reliable way to observe the requested result. The runtime does not promise generic exactly-once execution.
157
-
158
- Mutation policy stays in deterministic effect drivers. Agent workflows return findings or artifacts for deterministic code to check and apply. Worker processes run as the same operating-system user and are not credential sandboxes. Deployments that require credential isolation should put authenticated effects behind a separate broker.
159
-
160
- ## Child workflows
161
-
162
- `ctx.workflows.ensure()` creates or finds a workflow run by a stable request key and input fingerprint. Repeated reconciliations find the same active or completed request. A changed input must use a new key. An asynchronous child completion validates the reserved request and run IDs through a separate scheduler-completion command; it never reuses the controller claim that launched the child. The controller transaction reserves and saves each attempt's run ID before the scheduler starts it, so recovery can find the run row.
163
-
164
- A child run has one durable execution record. The parent resource points to the current run, and workflow completion enqueues the parent key. The global host runs it through the same queue and supervised worker protocol as other workflows.
165
-
166
- A stopped worker does not make the child failed by itself. The host reads the last committed node and effect state. It resumes pure or idempotent work in a new worker epoch. An uncertain manual effect becomes ambiguous and blocks automatic retry. A changed input still requires a new stable request key.
167
-
168
- ## Deletion and cleanup
169
-
170
- Setting `deletionTimestamp` requests deletion. A controller with a finalizer first removes external resources it owns, then removes its finalizer. The store deletes the resource after the finalizer list becomes empty.
171
-
172
- Controllers should add finalizers only when they own something that needs cleanup, such as an isolated worktree or a remote action session. Ordinary completed resources can remain as history or be removed by a separate retention policy.
173
-
174
- ## Sources and workers
175
-
176
- A source maps an external event to one or more resource keys. Sources include filesystem watches, webhooks, scheduled polling, and child workflow completion. They share the same enqueue API.
177
-
178
- The global host claims controller keys and starts a supervised process group for each active reconciliation. A reconciliation deadline stops and requeues the child even when controller code ignores its abort signal. Reconciler code must still pass the signal to provider calls and keep consequential writes inside guarded effect drivers. One host owns the local database. Distributed leader election remains outside this local runtime.
179
-
180
- The extension starts the package host on demand. Reconciliation continues when the Pi session closes. The package installs no operating-system service.
181
-
182
- ## Observability
183
-
184
- Every reconciliation emits structured records with the controller name, resource key, generation, reconcile ID, outcome and duration, plus the requeue reason. Effect state changes and child workflow links are also recorded. Logs and viewer projections remain secondary to the resource and effect stores.
185
-
186
- `pi-workflows controllers` lists resources and their current readiness condition. `pi-workflows controller <controller> <key>` prints one resource together with its effects, child workflows, and recent events. Run views read the same database through query-only connections.
187
-
188
- ## Safety rules
189
-
190
- A production controller must follow these rules:
191
-
192
- - Read current external state on every reconciliation.
193
- - Check authorization and target boundaries in deterministic code.
194
- - Use provider-side preconditions for consequential writes when available.
195
- - Save status with the resource version that was read.
196
- - Reconcile again after each consequential external effect.
197
- - Keep model output separate from mutation authority.
198
- - Bound worker counts and retry rates. Also bound timeouts and stored payload sizes.
199
- - Redact credentials and private provider responses from logs and SQLite runs.
200
-
201
- ## Package and Pi integration
202
-
203
- The controller API is exported from `@osolmaz/pi-workflows/controllers`. Controller definitions use a `.controller.ts` suffix. Project definitions live under `.pi/controllers/`; global definitions live under `~/.pi/agent/controllers/`.
204
-
205
- The implementation uses documented Pi extension APIs only. `/controller` lists and inspects resources, applies specs, and requests reconciliation or deletion. There are no extension-local worker start or stop controls.
206
-
207
- For `apply`, a source resolver child discovers the named controller, verifies its exported name, computes `initialStatus(spec)`, and hashes the source. The host accepts the proposal only while the path still follows discovery rules and the exact digest still matches. Reconcile code runs only in a supervised controller worker.
208
-
209
- Controller resources use the canonical [SQLite state](SQLITE_STATE.md) database. `projects` separates repository-local resources by canonical project path. Controller claims use the shared lease generation, token, expiry, and expected resource revision. Effects and child workflows use durable request keys and receipts.
210
-
211
- One global host owns that database for all Pi sessions and projects. The extension and mutating CLI paths are local protocol clients; viewers remain read-only. A controller child without an origin session uses a headless `pi --mode rpc` process for structured agent steps.
212
-
213
- Normal workflow prompts, tool calls, and replies remain part of the Pi session. No Pi internal type, private API, or persistent Pi schema changes.
214
-
215
- ## Exclusions
216
-
217
- This specification does not add Kubernetes API compatibility, YAML resources, a cluster scheduler, or a general distributed database. GitHub policy and credentials belong in a provider adapter, leaving the controller core independent of GitHub. The first release also excludes automatic service installation and generic exactly-once claims.
@@ -1,65 +0,0 @@
1
- import type { AnyControllerDefinition, ControllerDefinition, ControllerResource } from "./types.js";
2
-
3
- const CONTROLLER_DEFINITION_BRAND = Symbol.for("pi-workflows.controller-definition");
4
- const CONTROLLER_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
5
-
6
- export function defineController<TSpec, TStatus>(
7
- definition: ControllerDefinition<TSpec, TStatus>,
8
- ): ControllerDefinition<TSpec, TStatus> {
9
- assertValidControllerDefinition(definition);
10
- if (isControllerDefinition(definition)) {
11
- return definition;
12
- }
13
- Object.defineProperty(definition, CONTROLLER_DEFINITION_BRAND, {
14
- value: true,
15
- enumerable: false,
16
- configurable: false,
17
- writable: false,
18
- });
19
- return definition;
20
- }
21
-
22
- export function isControllerDefinition(value: unknown): value is AnyControllerDefinition {
23
- return (
24
- value !== null &&
25
- typeof value === "object" &&
26
- (value as Record<PropertyKey, unknown>)[CONTROLLER_DEFINITION_BRAND] === true
27
- );
28
- }
29
-
30
- export function assertValidControllerDefinition<TSpec, TStatus>(
31
- definition: ControllerDefinition<TSpec, TStatus>,
32
- ): void {
33
- if (definition === null || typeof definition !== "object") {
34
- throw new Error("Invalid controller definition: expected an object");
35
- }
36
- if (!CONTROLLER_NAME_PATTERN.test(definition.name)) {
37
- throw new Error(
38
- `Invalid controller definition: name ${JSON.stringify(definition.name)} must match ${CONTROLLER_NAME_PATTERN.source}`,
39
- );
40
- }
41
- if (typeof definition.initialStatus !== "function") {
42
- throw new Error("Invalid controller definition: initialStatus must be a function");
43
- }
44
- if (typeof definition.reconcile !== "function") {
45
- throw new Error("Invalid controller definition: reconcile must be a function");
46
- }
47
- if (
48
- definition.timeoutMs !== undefined &&
49
- (!Number.isSafeInteger(definition.timeoutMs) || definition.timeoutMs <= 0)
50
- ) {
51
- throw new Error("Invalid controller definition: timeoutMs must be a positive safe integer");
52
- }
53
- }
54
-
55
- export function asAnyControllerDefinition<TSpec, TStatus>(
56
- definition: ControllerDefinition<TSpec, TStatus>,
57
- ): AnyControllerDefinition {
58
- return definition as unknown as ControllerDefinition<unknown, unknown>;
59
- }
60
-
61
- export function asTypedResource<TSpec, TStatus>(
62
- resource: ControllerResource,
63
- ): ControllerResource<TSpec, TStatus> {
64
- return resource as ControllerResource<TSpec, TStatus>;
65
- }
@@ -1,27 +0,0 @@
1
- export class ResourceConflictError extends Error {
2
- constructor(controller: string, key: string) {
3
- super(`Controller resource ${controller}/${key} changed during reconciliation`);
4
- this.name = "ResourceConflictError";
5
- }
6
- }
7
-
8
- export class ResourceNotFoundError extends Error {
9
- constructor(controller: string, key: string) {
10
- super(`Controller resource not found: ${controller}/${key}`);
11
- this.name = "ResourceNotFoundError";
12
- }
13
- }
14
-
15
- export class EffectRequestConflictError extends Error {
16
- constructor(key: string) {
17
- super(`Effect key ${JSON.stringify(key)} was reused with a different request`);
18
- this.name = "EffectRequestConflictError";
19
- }
20
- }
21
-
22
- export class WorkflowRequestConflictError extends Error {
23
- constructor(key: string) {
24
- super(`Workflow request key ${JSON.stringify(key)} was reused with different input`);
25
- this.name = "WorkflowRequestConflictError";
26
- }
27
- }
@@ -1,88 +0,0 @@
1
- export {
2
- assertValidControllerDefinition,
3
- defineController,
4
- isControllerDefinition,
5
- } from "./definition.js";
6
- export {
7
- applyStatusPatch,
8
- conditionFalse,
9
- conditionTrue,
10
- conditionUnknown,
11
- mergeConditions,
12
- } from "./conditions.js";
13
- export {
14
- EffectRequestConflictError,
15
- ResourceConflictError,
16
- ResourceNotFoundError,
17
- WorkflowRequestConflictError,
18
- } from "./errors.js";
19
- export { ControllerEffectService } from "./effects.js";
20
- export { canonicalJson, jsonFingerprint } from "./json.js";
21
- export { ControllerManager, type ControllerManagerOptions } from "./manager.js";
22
- export { createResultHelpers, requeue, requeueAfter, settled } from "./results.js";
23
- export {
24
- SqliteControllerStore,
25
- type RunEventRecord,
26
- type WorkflowRunClaimOptions,
27
- type WorkflowRunPreparationResult,
28
- type WorkflowRunQueueRecord,
29
- type WorkflowRunReservationOptions,
30
- } from "./sqlite.js";
31
- export {
32
- type ControllerStore,
33
- type EffectReservation,
34
- type QueueItem,
35
- type QueueRequeueOptions,
36
- type WorkflowRecordUpdate,
37
- type WorkflowReservation,
38
- } from "./store.js";
39
- export {
40
- controllerFileStem,
41
- controllerSearchDirs,
42
- discoverControllers,
43
- loadControllerFile,
44
- loadDiscoveredControllers,
45
- type DiscoveredController,
46
- } from "./loader.js";
47
- export {
48
- ControllerWorkflowCoordinator,
49
- type ControllerWorkflowControlRequest,
50
- type ControllerWorkflowScheduler,
51
- type WorkflowSchedulerRequest,
52
- type WorkflowSchedulerResult,
53
- } from "./workflows.js";
54
- export type {
55
- AnyControllerDefinition,
56
- ChildWorkflowRecord,
57
- ChildWorkflowReference,
58
- ChildWorkflowRequest,
59
- ChildWorkflowState,
60
- ControllerCondition,
61
- ControllerConditionInput,
62
- ControllerConditionStatus,
63
- ControllerDefinition,
64
- ControllerEffects,
65
- ControllerFollowUpResult,
66
- ControllerQueueFollowUpRequest,
67
- ControllerRemoveFollowUpRequest,
68
- ControllerSettingsChangeRequest,
69
- ControllerSettingsChangeResult,
70
- ControllerEvent,
71
- ControllerQueueClaim,
72
- ControllerResource,
73
- ControllerResourceRef,
74
- ControllerResourceStatus,
75
- ControllerStatusPatch,
76
- ControllerWorkflows,
77
- EffectApplication,
78
- EffectDefinition,
79
- EffectObservation,
80
- EffectRecord,
81
- EffectState,
82
- JsonObject,
83
- JsonPrimitive,
84
- JsonValue,
85
- MaybePromise,
86
- ReconcileContext,
87
- ReconcileResult,
88
- } from "./types.js";