botmux-workflow-core 3.56.0 → 3.57.1

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.
@@ -244,6 +244,22 @@ export interface V3Node {
244
244
  * validateDag enforces every entry is an ANCESTOR (transitive `depends`),
245
245
  * so a revisit can never create a forward jump or a cycle in the run. */
246
246
  revisitTo?: string[];
247
+ /** Goal nodes only (design 2026-11-03 §13.6, M6): "look at the result
248
+ * before deciding how the rest goes". In a run whose goal nodes are
249
+ * handed to bots, the main bot is woken when this node completes. Only
250
+ * `true` is kept — absent (and an authored `false`) serialize exactly as a
251
+ * node that never had the field, so existing DAGs and saved templates keep
252
+ * their bytes. */
253
+ checkpoint?: true;
254
+ /** Top-level goal nodes only (design 2026-11-03 §5.1, D2): where a
255
+ * bot-executed run hands this node off. `'main'` = in the run's main topic
256
+ * (no node card, no topic of its own); absent = `'topic'`, a node topic.
257
+ * Only `'main'` is kept — an authored `'topic'` serializes exactly as a
258
+ * node that never had the field, so existing DAGs and saved templates keep
259
+ * their bytes. Loop body nodes and host / loop nodes always use a node
260
+ * topic (a body re-runs every round and can be revisited; host / loop
261
+ * nodes are never handed to a bot). Ignored by runs on temporary workers. */
262
+ placement?: 'main';
247
263
  /** Deterministic executor invoked by the host runtime (never an LLM). */
248
264
  executor?: V3HostExecutorName;
249
265
  /** Frozen before the runtime gate; supports typed host bindings. */
@@ -35,15 +35,245 @@ export interface V3LoopRef {
35
35
  iteration: number;
36
36
  bodyNodeId: string;
37
37
  }
38
+ /** Where an external goal-node handoff is delivered (design §5.1). */
39
+ export type V3ExternalPlacement = 'topic' | 'main';
40
+ /** Per-message idempotency keys, frozen in `nodeHandoffPrepared` so a
41
+ * re-dispatch after a crash reuses the exact same keys. */
42
+ export interface V3HandoffIdempotency {
43
+ /** Node card (topic placement only). */
44
+ nodeCard?: string;
45
+ handoff: string;
46
+ }
47
+ /**
48
+ * Why a runtime flow revision needs the initiator's confirmation before it
49
+ * takes effect (design §13.5 / M1). `callerNotInitiator` covers every edit
50
+ * made in a turn neither opened by the run's initiator nor woken by this
51
+ * run's own events; the rest are the §13.5 categories.
52
+ */
53
+ export type V3RevisionConfirmReason = 'callerNotInitiator' | 'newBot' | 'hostNode' | 'gateRelaxed' | 'budgetExpanded';
54
+ /**
55
+ * State changes a revision makes to already-dispatched work, folded
56
+ * atomically with its `dagRevised` event (one journal line, so a crash can
57
+ * never apply the new definition without its invalidations or vice versa).
58
+ */
59
+ export interface V3RevisionEffects {
60
+ /** Current instances invalidated by a definition change, reassignment or
61
+ * rerun — materialized exactly like `nodeInstanceSuperseded`: the node
62
+ * re-dispatches a fresh instance (and re-passes its gate). `waitId` names a
63
+ * pending gate wait voided by the change. */
64
+ supersede?: Array<{
65
+ nodeId: string;
66
+ instanceId: string;
67
+ waitId?: string;
68
+ }>;
69
+ /** Removed nodes that had already been dispatched or gated: neutral
70
+ * cancellation of that exact instance/attempt (only ever via this effect,
71
+ * never a separate `nodeCancelled`). `waitId` = a pending gate it voids. */
72
+ cancel?: Array<{
73
+ nodeId: string;
74
+ instanceId?: string;
75
+ attemptId?: string;
76
+ waitId?: string;
77
+ }>;
78
+ /** Blocked instances whose gate approval no longer covers their changed
79
+ * definition: the approval is dropped and their next retry runs as a
80
+ * fresh instance that must pass the gate again, however it is triggered. */
81
+ regate?: Array<{
82
+ nodeId: string;
83
+ instanceId: string;
84
+ }>;
85
+ /** Done nodes re-run with Revisit semantics; each consumes revisit budget. */
86
+ rerun?: string[];
87
+ /** Revisit budget the initiator's own edit lifted for its re-runs (M2 乙):
88
+ * each entry is one more revisit, counted exactly like a
89
+ * `revisitBudgetGranted` (`pair` = that node onto itself, `run` =
90
+ * run-wide) and attributed to this revision's `by`. In this event, never
91
+ * a separate line, so a crash cannot leave a lift without its revision. */
92
+ budgetGrants?: Array<{
93
+ nodeId: string;
94
+ tier: 'pair' | 'run';
95
+ }>;
96
+ /** RECORD ONLY: blocked nodes re-run by this revision. State advances
97
+ * through the `nodeRetryRequested` written in the same lock; replay never
98
+ * applies this list, reconciliation re-appends a lost retry from it. */
99
+ retry?: Array<{
100
+ nodeId: string;
101
+ instanceId?: string;
102
+ }>;
103
+ /** RECORD ONLY: reassignments, applied by the `nodeReassigned` written in
104
+ * the same lock (reconciled the same way as `retry`). */
105
+ assign?: Array<{
106
+ nodeId: string;
107
+ from?: string;
108
+ to: string;
109
+ }>;
110
+ }
111
+ /** Set when the main bot made the change on its own (`by: 'main_bot'`):
112
+ * a turn woken by this run's events, or another turn no message of the
113
+ * initiator opened (design §13.6). `reason` is the `--reason` the CLI
114
+ * requires in a wake turn; elsewhere it may fall back to the edit's note or
115
+ * be empty. */
116
+ export interface V3AutoProvenance {
117
+ reason: string;
118
+ }
119
+ /** Why a checkpoint's dependants may go on (design §13.6):
120
+ * `wakeTurnEnded` — the main bot's turn for its wake-up ended (it may have
121
+ * changed the flow in it); `wakeNotDelivered` — the wake-up could not be
122
+ * delivered after its retries; `wakeSessionEnded` — the session that took
123
+ * the wake-up was closed, or its CLI stopped, before that turn was seen to
124
+ * end; `holdTimeout` — the safety cap on how long a checkpoint may hold its
125
+ * dependants ran out. */
126
+ export type V3CheckpointReleaseReason = 'wakeTurnEnded' | 'wakeNotDelivered' | 'wakeSessionEnded' | 'holdTimeout';
38
127
  export type V3Event = {
39
128
  type: 'runStarted';
40
129
  runId: string;
130
+ /** Stamped by a runtime executing goal nodes through bot sessions. */
131
+ nodeExecutor?: 'bot';
41
132
  } | {
42
133
  type: 'nodeDispatched';
43
134
  nodeId: string;
44
135
  instanceId?: string;
45
136
  attemptId: string;
46
137
  loop?: V3LoopRef;
138
+ /** Present when the attempt is executed by an external bot session
139
+ * (`run.json` `nodeExecutor: "bot"`). Such attempts own no local worker
140
+ * process, so they never enter the worker attempt ledger. */
141
+ nodeExecutor?: 'bot';
142
+ /** Flow revision the attempt was dispatched under. Absent = 1 (the
143
+ * approved DAG), so runs that never revised keep their exact bytes. */
144
+ revision?: number;
145
+ } | {
146
+ /** A flow revision took effect (design §13.3). `dag-revisions/<NNN>.json`
147
+ * holds the full new DAG; every digest here is of the exact file bytes
148
+ * and replay fails closed on a mismatch. */
149
+ type: 'dagRevised';
150
+ revision: number;
151
+ baseRevision: number;
152
+ sha256: string;
153
+ patchSha256: string;
154
+ /** `dag-revisions/<NNN>.bots.json`: snapshots of bots the revision
155
+ * newly brought into the run (always initiator-confirmed). */
156
+ botsSha256?: string;
157
+ summary: string;
158
+ /** Free-text note supplied with the edit (display only). */
159
+ note?: string;
160
+ /** Operator: the turn's open_id, or `main_bot` for a change the main
161
+ * bot made on its own in a turn this run's events woke. */
162
+ by: string;
163
+ /** Only with `by: 'main_bot'`: why it acted (design §13.6). */
164
+ auto?: V3AutoProvenance;
165
+ /** Present when the revision was a confirmed proposal. */
166
+ approval?: {
167
+ by: string;
168
+ proposedBy: string;
169
+ };
170
+ effects?: V3RevisionEffects;
171
+ } | {
172
+ /** A revision that needs the initiator's confirmation (design §13.5).
173
+ * Its files are already written; it takes effect only through a later
174
+ * `dagRevised` carrying `approval`. A pending wait lives in
175
+ * `waits/revisions/<NNN>.json`. */
176
+ type: 'dagRevisionProposed';
177
+ revision: number;
178
+ baseRevision: number;
179
+ sha256: string;
180
+ patchSha256: string;
181
+ botsSha256?: string;
182
+ summary: string;
183
+ note?: string;
184
+ by: string;
185
+ auto?: V3AutoProvenance;
186
+ reasons: V3RevisionConfirmReason[];
187
+ /** Existing nodes the proposal touches; they are not dispatched while
188
+ * it is pending (the rest of the run keeps going). */
189
+ touched: string[];
190
+ /** The pending proposal this one carries onto a direct revision that
191
+ * took effect first (same patch, same proposer, re-based): landing
192
+ * supersedes it, and its card and wait move here. */
193
+ carriedFrom?: number;
194
+ } | {
195
+ type: 'dagRevisionApproved';
196
+ revision: number;
197
+ by: string;
198
+ } | {
199
+ type: 'dagRevisionRejected';
200
+ revision: number;
201
+ by: string;
202
+ /** `stale` = the flow moved on (another revision took effect, or the
203
+ * proposal no longer applies to the current node states);
204
+ * `superseded` = a newer proposal replaced it; `runEnded` = the run
205
+ * left running/blocked before anyone decided. */
206
+ reason: 'rejected' | 'stale' | 'superseded' | 'runEnded';
207
+ detail?: string;
208
+ } | {
209
+ /** Durable intent written before any handoff message is sent. */
210
+ type: 'nodeHandoffPrepared';
211
+ nodeId: string;
212
+ instanceId?: string;
213
+ attemptId: string;
214
+ targetLarkAppId: string;
215
+ placement: V3ExternalPlacement;
216
+ /** Flow revision the attempt was dispatched under (1 = approved DAG). */
217
+ revision: number;
218
+ idempotency: V3HandoffIdempotency;
219
+ /** Engine clock (ms) at preparation; bounds same-key re-dispatch. */
220
+ preparedAt: number;
221
+ } | {
222
+ type: 'nodeHandoffSent';
223
+ nodeId: string;
224
+ instanceId?: string;
225
+ attemptId: string;
226
+ handoffMessageId: string;
227
+ nodeCardMessageId?: string;
228
+ threadId?: string;
229
+ sentAt: number;
230
+ /** Absolute engine-clock deadline for the target bot to accept. */
231
+ acceptDeadlineAt: number;
232
+ } | {
233
+ type: 'nodeHandoffAccepted';
234
+ nodeId: string;
235
+ instanceId?: string;
236
+ attemptId: string;
237
+ sessionId: string;
238
+ acceptedAt: number;
239
+ /** Absolute engine-clock deadline = acceptedAt + node timeoutSec. */
240
+ deadlineAt: number;
241
+ /** Main-topic placement only (design §5.5): the handoff entered the
242
+ * target session's queue — that session may be busy with another turn
243
+ * — and its own turn has not been seen to start. `deadlineAt` is then
244
+ * a backstop (queued past it, the node times out); the node's real
245
+ * deadline is set by `nodeHandoffStarted`. Absent everywhere else, so
246
+ * node-topic attempts keep their bytes. */
247
+ startPending?: true;
248
+ } | {
249
+ /** Main-topic placement only: the handoff's own turn reached the CLI
250
+ * (its input was committed) after a `startPending` acceptance; the
251
+ * node timeout now counts from here. At most once per attempt. */
252
+ type: 'nodeHandoffStarted';
253
+ nodeId: string;
254
+ instanceId?: string;
255
+ attemptId: string;
256
+ startedAt: number;
257
+ /** Absolute engine-clock deadline = startedAt + node timeoutSec. */
258
+ deadlineAt: number;
259
+ } | {
260
+ /** The bot's turn ended without a valid submission (display only). */
261
+ type: 'nodeStalled';
262
+ nodeId: string;
263
+ instanceId?: string;
264
+ attemptId: string;
265
+ at: number;
266
+ } | {
267
+ type: 'nodeReassigned';
268
+ nodeId: string;
269
+ instanceId?: string;
270
+ /** The open external attempt this reassignment closed, if any. */
271
+ attemptId?: string;
272
+ from: string;
273
+ to: string;
274
+ by: string;
275
+ /** Main-bot provenance of an automatic change (design §13.6). */
276
+ auto?: V3AutoProvenance;
47
277
  } | {
48
278
  type: 'hostInputPrepared';
49
279
  nodeId: string;
@@ -148,6 +378,39 @@ export type V3Event = {
148
378
  preview: string;
149
379
  by: string;
150
380
  };
381
+ /** Operator, when recorded: `main_bot` for a retry the main bot
382
+ * decided on its own (with `auto`), the caller's open_id for a human
383
+ * turn that gave a reason (with `note`). A retry recorded without a
384
+ * reason keeps the original shape (no `by`). */
385
+ by?: string;
386
+ auto?: V3AutoProvenance;
387
+ /** The reason a human turn gave (`--reason`), display only. */
388
+ note?: string;
389
+ } | {
390
+ /** A checkpoint node's success may now be followed by its dependants
391
+ * (design §13.6; until then they are not dispatched). Names the exact
392
+ * success: its attempt and journal position. Older readers skip it. */
393
+ type: 'checkpointReleased';
394
+ nodeId: string;
395
+ instanceId?: string;
396
+ attemptId: string;
397
+ eventSeq: number;
398
+ reason: V3CheckpointReleaseReason;
399
+ } | {
400
+ /** The node was handed to a human (design §13.6): a record only. The
401
+ * `nodeBlocked(HANDED_TO_HUMAN)` written right after it in the same
402
+ * lock closes the attempt; if a crash separates the two, the runtime
403
+ * writes that block on the next drive (never waiting for a deadline). */
404
+ type: 'nodeHandedToHuman';
405
+ nodeId: string;
406
+ instanceId?: string;
407
+ /** The attempt it was handed over on (open, or the latest closed one). */
408
+ attemptId: string;
409
+ reason: string;
410
+ /** `main_bot`, or the initiator's open_id in their own turn. */
411
+ by: string;
412
+ /** The turn that decided it (audit). */
413
+ turnId?: string;
151
414
  } | {
152
415
  type: 'gateDispatched';
153
416
  nodeId: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "botmux-workflow-core",
3
- "version": "3.56.0",
3
+ "version": "3.57.1",
4
4
  "description": "Daemon-independent Workflow v3 schema, scheduler, control policy, and host contracts",
5
5
  "type": "module",
6
6
  "sideEffects": false,