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.
- package/dist/cjs/control.cjs +9 -0
- package/dist/cjs/control.cjs.map +2 -2
- package/dist/cjs/engine.cjs.map +2 -2
- package/dist/cjs/gate-policy.cjs.map +1 -1
- package/dist/cjs/index.cjs +44 -1
- package/dist/cjs/index.cjs.map +2 -2
- package/dist/cjs/runtime.cjs +2028 -356
- package/dist/cjs/runtime.cjs.map +4 -4
- package/dist/cjs/schema.cjs +35 -1
- package/dist/cjs/schema.cjs.map +2 -2
- package/dist/esm/control.js +9 -0
- package/dist/esm/control.js.map +2 -2
- package/dist/esm/engine.js.map +2 -2
- package/dist/esm/gate-policy.js.map +1 -1
- package/dist/esm/index.js +44 -1
- package/dist/esm/index.js.map +2 -2
- package/dist/esm/runtime.js +2033 -352
- package/dist/esm/runtime.js.map +4 -4
- package/dist/esm/schema.js +35 -1
- package/dist/esm/schema.js.map +2 -2
- package/dist/types/src/workflows/v3/dag.d.ts +16 -0
- package/dist/types/src/workflows/v3/event-contract.d.ts +263 -0
- package/package.json +1 -1
|
@@ -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;
|