botmux-workflow-core 3.57.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. */
@@ -108,12 +108,22 @@ export interface V3RevisionEffects {
108
108
  to: string;
109
109
  }>;
110
110
  }
111
- /** Set when the main bot made the change on its own in a turn woken by
112
- * this run's events (design §13.6). The reason becomes mandatory with the
113
- * wake-up wiring; until then it carries the edit's note (may be empty). */
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. */
114
116
  export interface V3AutoProvenance {
115
117
  reason: string;
116
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';
117
127
  export type V3Event = {
118
128
  type: 'runStarted';
119
129
  runId: string;
@@ -228,6 +238,24 @@ export type V3Event = {
228
238
  acceptedAt: number;
229
239
  /** Absolute engine-clock deadline = acceptedAt + node timeoutSec. */
230
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;
231
259
  } | {
232
260
  /** The bot's turn ended without a valid submission (display only). */
233
261
  type: 'nodeStalled';
@@ -350,9 +378,39 @@ export type V3Event = {
350
378
  preview: string;
351
379
  by: string;
352
380
  };
353
- /** Operator (`main_bot` for an automatic retry), when recorded. */
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`). */
354
385
  by?: string;
355
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;
356
414
  } | {
357
415
  type: 'gateDispatched';
358
416
  nodeId: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "botmux-workflow-core",
3
- "version": "3.57.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,