@tangle-network/agent-runtime 0.164.0 → 0.166.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 (70) hide show
  1. package/dist/{activation-CneAm4jL.js → activation-BkO0p4I1.js} +3 -3
  2. package/dist/{activation-CneAm4jL.js.map → activation-BkO0p4I1.js.map} +1 -1
  3. package/dist/agent.d.ts +1 -1
  4. package/dist/agent.js +2 -2
  5. package/dist/{authoring-CZM22nUG.js → authoring-Bt17KOML.js} +2 -2
  6. package/dist/{authoring-CZM22nUG.js.map → authoring-Bt17KOML.js.map} +1 -1
  7. package/dist/candidate-execution/index.js +4 -4
  8. package/dist/{candidate-execution-DNLk6h0A.js → candidate-execution-DC0T8l2p.js} +4 -4
  9. package/dist/{candidate-execution-DNLk6h0A.js.map → candidate-execution-DC0T8l2p.js.map} +1 -1
  10. package/dist/conversation.d.ts +1 -1
  11. package/dist/durable.d.ts +2 -2
  12. package/dist/durable.js +1 -1
  13. package/dist/{environment-provider-BXFFK_rZ.d.ts → environment-provider-DWjbGH8W.d.ts} +2 -2
  14. package/dist/environment-provider.d.ts +1 -1
  15. package/dist/graph-E0U0c2YP.js +2668 -0
  16. package/dist/graph-E0U0c2YP.js.map +1 -0
  17. package/dist/graph.d.ts +319 -53
  18. package/dist/graph.js +2 -1203
  19. package/dist/{improvement-cycle-a_L8FFql.js → improvement-cycle-BAWOyeTA.js} +4 -4
  20. package/dist/{improvement-cycle-a_L8FFql.js.map → improvement-cycle-BAWOyeTA.js.map} +1 -1
  21. package/dist/{index-BP11HXYi.d.ts → index-BGQtpQuJ.d.ts} +5 -5
  22. package/dist/{index-C2X-OVPZ.d.ts → index-BgptUCKl.d.ts} +4 -4
  23. package/dist/{index-OFOvnNc2.d.ts → index-CFMB9ux3.d.ts} +2 -2
  24. package/dist/index.d.ts +7 -7
  25. package/dist/index.js +11 -11
  26. package/dist/intelligence.d.ts +4 -4
  27. package/dist/intelligence.js +5 -5
  28. package/dist/kernel.d.ts +5 -5
  29. package/dist/kernel.js +7 -7
  30. package/dist/{knowledge-Ccdghy81.js → knowledge-Bhhz6lvH.js} +5 -5
  31. package/dist/{knowledge-Ccdghy81.js.map → knowledge-Bhhz6lvH.js.map} +1 -1
  32. package/dist/knowledge.d.ts +1 -1
  33. package/dist/knowledge.js +1 -1
  34. package/dist/{loop-runner-bin-DM-AnPC-.js → loop-runner-bin-BQnpSn0h.js} +3 -3
  35. package/dist/{loop-runner-bin-DM-AnPC-.js.map → loop-runner-bin-BQnpSn0h.js.map} +1 -1
  36. package/dist/{loop-runner-bin-2NITRIFc.d.ts → loop-runner-bin-C2NXQK7J.d.ts} +3 -3
  37. package/dist/loop-runner-bin.d.ts +1 -1
  38. package/dist/loop-runner-bin.js +1 -1
  39. package/dist/mcp/bin.js +3 -3
  40. package/dist/mcp/index.d.ts +3 -3
  41. package/dist/mcp/index.js +4 -4
  42. package/dist/{openai-tools-CIo9tB75.js → openai-tools-t6spVYKL.js} +2 -2
  43. package/dist/{openai-tools-CIo9tB75.js.map → openai-tools-t6spVYKL.js.map} +1 -1
  44. package/dist/{prepare-D7Fb75XR.js → prepare-BCScSDCv.js} +2 -2
  45. package/dist/{prepare-D7Fb75XR.js.map → prepare-BCScSDCv.js.map} +1 -1
  46. package/dist/primeintellect/index.d.ts +1 -1
  47. package/dist/{protected-model-port-RZkxRZhp.js → protected-model-port-D-5E3HBe.js} +2 -2
  48. package/dist/{protected-model-port-RZkxRZhp.js.map → protected-model-port-D-5E3HBe.js.map} +1 -1
  49. package/dist/{redact-D4vlt6p4.d.ts → redact-DkObldQP.d.ts} +3 -3
  50. package/dist/{runtime-D44YrQ4t.d.ts → runtime-B0HZbuEv.d.ts} +3 -3
  51. package/dist/{runtime-BDHsMgCK.js → runtime-BJoNta1Y.js} +7 -7
  52. package/dist/{runtime-BDHsMgCK.js.map → runtime-BJoNta1Y.js.map} +1 -1
  53. package/dist/{spawn-journal-oewq1g2h.js → spawn-journal-Tgvp5VS5.js} +8 -2
  54. package/dist/{spawn-journal-oewq1g2h.js.map → spawn-journal-Tgvp5VS5.js.map} +1 -1
  55. package/dist/{stream-agent-turn-Dx2YrEWW.d.ts → stream-agent-turn-DxQ3GOuR.d.ts} +2 -2
  56. package/dist/{structural-rollout-CBK2LHni.js → structural-rollout-B5E0mWCH.js} +3 -3
  57. package/dist/{structural-rollout-CBK2LHni.js.map → structural-rollout-B5E0mWCH.js.map} +1 -1
  58. package/dist/{supervise-CzllE0vn.js → supervise-CnxqHx1P.js} +3 -3
  59. package/dist/{supervise-CzllE0vn.js.map → supervise-CnxqHx1P.js.map} +1 -1
  60. package/dist/{supervisor-D5K8ihKQ.js → supervisor-C8kgh8mf.js} +29 -6
  61. package/dist/{supervisor-D5K8ihKQ.js.map → supervisor-C8kgh8mf.js.map} +1 -1
  62. package/dist/testing.d.ts +2 -2
  63. package/dist/testing.js +12 -12
  64. package/dist/{types-C2l1jaos.d.ts → types-DjVO-p7R.d.ts} +58 -3
  65. package/dist/{workspace-archive-DK0mDjSB.js → workspace-archive-CHY5HvrF.js} +2 -2
  66. package/dist/{workspace-archive-DK0mDjSB.js.map → workspace-archive-CHY5HvrF.js.map} +1 -1
  67. package/package.json +1 -1
  68. package/dist/graph-DzE4SwfP.js +0 -532
  69. package/dist/graph-DzE4SwfP.js.map +0 -1
  70. package/dist/graph.js.map +0 -1
package/dist/graph.d.ts CHANGED
@@ -1,6 +1,6 @@
1
- import { $l as MakeWorkerAgent, If as DeliverableSpec, an as PromptRegistry, bo as SupervisorAgentDeps, in as PromptHandle, mu as WorkerSpawnContext, os as SupervisorFinalizer } from "./index-BP11HXYi.js";
2
- import { H as SpawnJournal, K as Spend, i as Budget, j as ResultBlobStore, t as Agent } from "./types-C2l1jaos.js";
3
- import { o as ExecutorConfig } from "./runtime-D44YrQ4t.js";
1
+ import { $l as MakeWorkerAgent, Gt as AgentGraph, If as DeliverableSpec, Qt as RunGraphOptions, Zt as GraphResult, an as PromptRegistry, bo as SupervisorAgentDeps, in as PromptHandle, mu as WorkerSpawnContext, os as SupervisorFinalizer } from "./index-BGQtpQuJ.js";
2
+ import { H as SpawnJournal, K as Spend, V as SpawnEvent, i as Budget, j as ResultBlobStore, t as Agent, z as Scope } from "./types-DjVO-p7R.js";
3
+ import { _t as ToolLoopChat, o as ExecutorConfig } from "./runtime-B0HZbuEv.js";
4
4
  import { AgentProfile } from "@tangle-network/agent-interface";
5
5
  //#region src/runtime/graph/condition.d.ts
6
6
  /** The leaf comparison operators; `exists`/`truthy` are unary, the rest compare against `value`. */
@@ -225,6 +225,10 @@ interface EngineGraphNode {
225
225
  readonly deliverable?: DeliverableSpec<unknown>;
226
226
  /** Force-mark a terminal. Absent, a node with no outbound gating edge is terminal. */
227
227
  readonly terminal?: boolean;
228
+ /** Force a node out of (or into) the run's entry set. Absent, a node with no inbound edge is an
229
+ * entry, and the declared root always is. A node another node SPAWNS — the `runGraph` preset's
230
+ * workers and analysts — sets `false`: the scheduler must never enter it on its own. */
231
+ readonly entry?: boolean;
228
232
  /** Profile fields merged over the engine-authored `{ name: id }` for this node's spawns. */
229
233
  readonly profile?: Readonly<Partial<AgentProfile>>;
230
234
  /** Per-instance reservation for this node's spawns; falls back to the run's `perNode`. */
@@ -246,7 +250,7 @@ interface EngineGraphEdge {
246
250
  readonly guard?: Condition;
247
251
  /** `data` edges only: ONE pure reshape of the admitted payload. */
248
252
  readonly projection?: Projection;
249
- /** Refuses the traversal past this many firings (ledgered `unpropagated`). */
253
+ /** Refuses the traversal past this many firings (ledgered `unpropagated`); `0` closes the edge from the start. */
250
254
  readonly maxTraversals?: number;
251
255
  /** `delegates`/`analyzes`: the versioned directive appended to the target's task. */
252
256
  readonly directive?: PromptHandle;
@@ -294,6 +298,10 @@ interface CompiledEdge {
294
298
  readonly fromPort: string;
295
299
  readonly toPort: string;
296
300
  }
301
+ /** `delegates` is the one MODEL-fired edge kind (agent-runtime#971): its payload is a directive and
302
+ * its target is spawned by the source supervisor through the coordination protocol, not released
303
+ * by the scheduler. `data` and `analyzes` are engine-fired. */
304
+ declare function isEngineFired(edge: CompiledEdge): boolean;
297
305
  interface CompiledNode {
298
306
  readonly id: string;
299
307
  readonly kind: NodeKind;
@@ -307,6 +315,8 @@ interface CompiledNode {
307
315
  readonly deliverable?: DeliverableSpec<unknown>;
308
316
  readonly inbound: ReadonlyArray<CompiledEdge>;
309
317
  readonly outbound: ReadonlyArray<CompiledEdge>;
318
+ /** Spawned by a supervisor through a `delegates` edge, never entered by the scheduler. */
319
+ readonly modelFired: boolean;
310
320
  readonly spec: EngineGraphSpec['nodes'][number];
311
321
  }
312
322
  interface CompiledGraph {
@@ -330,6 +340,137 @@ declare function schemaAccepts(source: JsonSchema, target: JsonSchema, depth?: n
330
340
  */
331
341
  declare function compileGraph(engine: GraphEngine, spec: EngineGraphSpec, context?: string): CompiledGraph;
332
342
  //#endregion
343
+ //#region src/runtime/graph/scheduler-types.d.ts
344
+ /** Result vocabulary shared by the scheduler and the fold (agent-runtime#973, #974, #976). */
345
+ type GraphRunReason = 'all-children-down' | 'budget-exhausted' | 'aborted' | 'driver-failed' | 'cycle-budget-exceeded' | 'unreachable-terminal';
346
+ /** One node settlement as the graph result reports it. */
347
+ interface GraphNodeSettle {
348
+ readonly node: string;
349
+ readonly visit: number;
350
+ readonly status: 'done' | 'down';
351
+ /** The node's completion check verdict; `undefined` when the node declares no check. */
352
+ readonly valid?: boolean;
353
+ readonly out?: unknown;
354
+ readonly outRef?: string;
355
+ readonly reason?: string;
356
+ }
357
+ /** One ledgered edge firing (or refusal) — the run's observable data flow. */
358
+ interface GraphEdgeTraversal {
359
+ readonly edge: string;
360
+ readonly kind: 'delegates' | 'analyzes' | 'data';
361
+ readonly from: string;
362
+ readonly to: string;
363
+ readonly traversal: number;
364
+ readonly outcome: 'delivered' | 'empty' | 'unpropagated';
365
+ readonly directive?: string;
366
+ readonly port?: string;
367
+ readonly reason?: string;
368
+ }
369
+ type GraphRunResult = {
370
+ readonly kind: 'winner';
371
+ readonly out: unknown;
372
+ readonly terminals: ReadonlyArray<GraphNodeSettle>;
373
+ readonly settles: ReadonlyArray<GraphNodeSettle>;
374
+ readonly ledger: ReadonlyArray<GraphEdgeTraversal>;
375
+ } | {
376
+ readonly kind: 'no-winner';
377
+ readonly reason: GraphRunReason;
378
+ readonly error?: {
379
+ readonly name: string;
380
+ readonly message: string;
381
+ };
382
+ readonly terminals: ReadonlyArray<GraphNodeSettle>;
383
+ readonly settles: ReadonlyArray<GraphNodeSettle>;
384
+ readonly ledger: ReadonlyArray<GraphEdgeTraversal>;
385
+ /** Nodes provably stuck when the run ended: every upstream settled, no release possible. */
386
+ readonly unreachable: ReadonlyArray<string>;
387
+ } | {
388
+ /** Every live branch parked on a host wake: a legitimate terminal state for an offline run.
389
+ * Restart over the same journal and `resume(token, payload)` to continue (#976). */
390
+ readonly kind: 'suspended';
391
+ readonly tokens: ReadonlyArray<string>;
392
+ readonly terminals: ReadonlyArray<GraphNodeSettle>;
393
+ readonly settles: ReadonlyArray<GraphNodeSettle>;
394
+ readonly ledger: ReadonlyArray<GraphEdgeTraversal>;
395
+ };
396
+ //#endregion
397
+ //#region src/runtime/graph/fold.d.ts
398
+ type FoldEdgeState = 'pending' | 'satisfied' | 'dead' | 'failed';
399
+ interface FoldEdge {
400
+ state: FoldEdgeState;
401
+ /** Set by a `join-state` whose wave this edge was pending inside; cleared when the in-flight
402
+ * completion it refers to settles (absorbed, never re-released). */
403
+ consumedOnce: boolean;
404
+ /** Delivered consumptions — what the per-edge cap counts. */
405
+ traversals: number;
406
+ /** How many of the source's settles this edge has accounted for — by a journaled verdict or by
407
+ * an absorption. The idempotence key: a kill between a settle and its verdicts re-judges ONLY
408
+ * the unaccounted edges on restart, never a judged or absorbed one twice. */
409
+ judgedSourceSettles: number;
410
+ /** The admitted source payload this state reflects (the source settle's outRef). */
411
+ payloadRef?: string;
412
+ capped: boolean;
413
+ }
414
+ type FoldInstanceStatus = 'released' | 'live' | 'done' | 'down' | 'suspended';
415
+ interface FoldInstance {
416
+ readonly node: string;
417
+ readonly instance: string;
418
+ readonly visit: number;
419
+ inputRef?: string;
420
+ status: FoldInstanceStatus;
421
+ settle?: GraphNodeSettle;
422
+ }
423
+ interface FoldSuspension {
424
+ readonly token: string;
425
+ readonly node: string;
426
+ readonly instance: string;
427
+ readonly onExpire: 'wait' | 'fail' | 'default';
428
+ readonly expiresAtMs?: number;
429
+ readonly defaultRef?: string;
430
+ status: 'pending' | 'woken' | 'expired';
431
+ }
432
+ interface FoldNode {
433
+ visits: number;
434
+ blocked: boolean;
435
+ settles: GraphNodeSettle[];
436
+ }
437
+ interface GraphFoldState {
438
+ readonly nodes: Map<string, FoldNode>;
439
+ readonly edges: Map<string, FoldEdge>;
440
+ /** Every node instance the journal knows, keyed by `<node>#<visit>`. */
441
+ readonly instances: Map<string, FoldInstance>;
442
+ /** Kernel node id → engine instance label, from `spawned`. */
443
+ readonly spawnedIds: Map<string, string>;
444
+ readonly suspensions: Map<string, FoldSuspension>;
445
+ readonly exhaustedEdges: Set<string>;
446
+ }
447
+ /** The reducer's zero: every node unvisited, every edge pending, nothing suspended. */
448
+ declare function emptyFoldState(compiled: CompiledGraph): GraphFoldState;
449
+ /**
450
+ * Apply ONE journal event. The live scheduler calls this right after each append; the restart path
451
+ * calls it over the loaded journal. Unknown kernel events are ignored — the engine folds only what
452
+ * it understands, exactly as the kernel's replay skips the engine's events.
453
+ */
454
+ declare function applyGraphFoldEvent(state: GraphFoldState, ev: SpawnEvent, compiled: CompiledGraph): void;
455
+ /** Fold a loaded journal (append order) into scheduler state. */
456
+ declare function foldGraphJournal(events: ReadonlyArray<SpawnEvent>, compiled: CompiledGraph): GraphFoldState;
457
+ //#endregion
458
+ //#region src/runtime/graph/join.d.ts
459
+ interface GatingEdge {
460
+ readonly edge: CompiledEdge;
461
+ readonly folded: FoldEdge | undefined;
462
+ }
463
+ interface JoinDecision {
464
+ /** Whether the node releases now. */
465
+ readonly release: boolean;
466
+ /** The edges whose outcomes produced this release — the ones a traversal cap judges. */
467
+ readonly consuming: ReadonlyArray<GatingEdge>;
468
+ /** Whether the node can never release again on this wave (recorded like skipped-by-guard). */
469
+ readonly blocked: boolean;
470
+ }
471
+ /** Decide whether a node's gating edges release it, and which of them the release consumes. */
472
+ declare function decideJoin(rule: JoinRule, gating: ReadonlyArray<GatingEdge>): JoinDecision;
473
+ //#endregion
333
474
  //#region src/runtime/graph/kinds.d.ts
334
475
  interface AgentKindConfig {
335
476
  /** Where this node's profile runs. Omit to inherit the engine's default backend. */
@@ -393,50 +534,165 @@ declare function subgraphKind(): NodeKind<{
393
534
  readonly graph: unknown;
394
535
  }>;
395
536
  //#endregion
396
- //#region src/runtime/graph/scheduler.d.ts
397
- type GraphRunReason = 'all-children-down' | 'budget-exhausted' | 'aborted' | 'driver-failed' | 'cycle-budget-exceeded' | 'unreachable-terminal';
398
- /** One node settlement as the graph result reports it. */
399
- interface GraphNodeSettle {
400
- readonly node: string;
401
- readonly visit: number;
402
- readonly status: 'done' | 'down';
403
- /** The node's completion check verdict; `undefined` when the node declares no check. */
404
- readonly valid?: boolean;
405
- readonly out?: unknown;
406
- readonly outRef?: string;
407
- readonly reason?: string;
537
+ //#region src/runtime/graph/ledger.d.ts
538
+ interface EdgeLedger {
539
+ readonly entries: ReadonlyArray<GraphEdgeTraversal>;
540
+ record(edge: CompiledEdge, traversal: number, outcome: GraphEdgeTraversal['outcome'], reason?: string): Promise<void>;
408
541
  }
409
- /** One ledgered edge firing (or refusal) the run's observable data flow. */
410
- interface GraphEdgeTraversal {
411
- readonly edge: string;
412
- readonly kind: 'delegates' | 'analyzes' | 'data';
413
- readonly from: string;
414
- readonly to: string;
415
- readonly traversal: number;
416
- readonly outcome: 'delivered' | 'empty' | 'unpropagated';
417
- readonly directive?: string;
418
- readonly port?: string;
419
- readonly reason?: string;
542
+ /** Open a ledger for one run; its ordinals continue past whatever a prior process recorded. */
543
+ declare function createEdgeLedger(args: {
544
+ readonly journal: SpawnJournal;
545
+ readonly runId: string;
546
+ readonly now: () => number;
547
+ readonly startSeq: number;
548
+ }): EdgeLedger;
549
+ //#endregion
550
+ //#region src/runtime/graph/preset-run-graph.d.ts
551
+ /** The preset's root kind: one node whose body is the graph's supervise run. */
552
+ declare const RUN_GRAPH_KIND = "run-graph.supervisor";
553
+ /** The graph supervise run, injected rather than imported: the preset describes the graph, and
554
+ * `runGraph` supplies the body, so this module never imports its caller at runtime. */
555
+ type RunGraphBody = (graph: AgentGraph, options: RunGraphOptions, brain?: ToolLoopChat) => Promise<GraphResult>;
556
+ /** Where the run body's raw failure is kept. A node's output crosses the edge-admission boundary
557
+ * (JSON round-trip), which would reduce an `Error` to a plain object and a typed
558
+ * `GraphEdgeCapError` to an untyped one. The error therefore travels beside the output, by
559
+ * reference, and the preset rethrows the ORIGINAL object. */
560
+ interface RunGraphCapture {
561
+ error?: unknown;
420
562
  }
421
- type GraphRunResult = {
422
- readonly kind: 'winner';
423
- readonly out: unknown;
424
- readonly terminals: ReadonlyArray<GraphNodeSettle>;
425
- readonly settles: ReadonlyArray<GraphNodeSettle>;
563
+ /** What the root node carries: the authored graph, the caller's options, and the run body. */
564
+ interface RunGraphNodeConfig {
565
+ readonly graph: AgentGraph;
566
+ readonly options: RunGraphOptions;
567
+ readonly run: RunGraphBody;
568
+ readonly capture: RunGraphCapture;
569
+ readonly brain?: ToolLoopChat;
570
+ }
571
+ /** The run's outcome as the root node's output: never a throw, so a typed failure (an exhausted
572
+ * delegates cap) reaches the caller as the exact error object rather than a settle reason. */
573
+ type RunGraphNodeOut = {
574
+ readonly ok: true;
575
+ readonly result: GraphResult;
576
+ } |
577
+ /** The message only; the raw error rides in {@link RunGraphCapture}. */
578
+ {
579
+ readonly ok: false;
580
+ readonly error: string;
581
+ };
582
+ /**
583
+ * The node kind behind the preset. Its executor runs the graph and reports the run's own measured
584
+ * spend, so the engine pool debits what the graph actually used, never a second copy of it.
585
+ */
586
+ declare function runGraphKind(): NodeKind<RunGraphNodeConfig>;
587
+ /** An engine with the preset kind registered beside the core `agent` kind the workers use. */
588
+ declare function runGraphEngine(): GraphEngine;
589
+ /**
590
+ * Compile an `AgentGraph` into the engine graph that represents it: the supervisor root, one
591
+ * pinned `agent` node per worker, and every authored edge. Pure — nothing runs, so a caller can
592
+ * inspect, diff, or extend the result before handing it to the engine.
593
+ */
594
+ declare function graphFromRunGraph(graph: AgentGraph, options: RunGraphOptions, run: RunGraphBody, capture?: RunGraphCapture, brain?: ToolLoopChat): EngineGraphSpec;
595
+ /**
596
+ * Run an `AgentGraph` through the engine: compile it with {@link graphFromRunGraph}, schedule it,
597
+ * and answer the caller in `runGraph`'s own vocabulary. A typed failure the graph threw — an
598
+ * exhausted delegates cap — is rethrown as the exact error object it was, never flattened into a
599
+ * settle reason.
600
+ */
601
+ declare function runGraphThroughEngine(graph: AgentGraph, options: RunGraphOptions, run: RunGraphBody, brain?: ToolLoopChat): Promise<GraphResult>;
602
+ //#endregion
603
+ //#region src/runtime/graph/result.d.ts
604
+ type FinalizerChoice = 'bestDelivered' | 'collectDelivered' | SupervisorFinalizer;
605
+ /** Every node settlement with its output rehydrated and its completion check applied. */
606
+ declare function materializeSettles(compiled: CompiledGraph, state: GraphFoldState, blobs: ResultBlobStore, outCache: ReadonlyMap<string, unknown>): Promise<GraphNodeSettle[]>;
607
+ /** Turn a finished run into its result: rehydrate, reduce the terminals, classify a no-winner. */
608
+ declare function assembleGraphResult(args: {
609
+ readonly compiled: CompiledGraph;
610
+ readonly state: GraphFoldState;
611
+ readonly blobs: ResultBlobStore;
612
+ readonly scope: Scope<unknown>;
613
+ readonly outCache: ReadonlyMap<string, unknown>;
426
614
  readonly ledger: ReadonlyArray<GraphEdgeTraversal>;
427
- } | {
428
- readonly kind: 'no-winner';
429
- readonly reason: GraphRunReason;
430
- readonly error?: {
431
- readonly name: string;
432
- readonly message: string;
615
+ readonly finalizer?: FinalizerChoice;
616
+ readonly failure?: {
617
+ readonly reason: GraphRunReason;
618
+ readonly error?: {
619
+ name: string;
620
+ message: string;
621
+ };
433
622
  };
434
- readonly terminals: ReadonlyArray<GraphNodeSettle>;
435
- readonly settles: ReadonlyArray<GraphNodeSettle>;
436
- readonly ledger: ReadonlyArray<GraphEdgeTraversal>;
437
- /** Nodes provably stuck when the run ended: every upstream settled, no release possible. */
438
- readonly unreachable: ReadonlyArray<string>;
439
- };
623
+ readonly aborted: boolean;
624
+ }): Promise<GraphRunResult>;
625
+ //#endregion
626
+ //#region src/runtime/graph/run-context.d.ts
627
+ /** Engine-appended `woken` ordinals start here — far above any kernel cursor counter, so the two
628
+ * counters can advance independently without ever colliding. */
629
+ declare const ENGINE_WOKEN_SEQ_BASE = 10000000;
630
+ interface GraphRunContext {
631
+ readonly runId: string;
632
+ readonly journal: SpawnJournal;
633
+ readonly blobs: ResultBlobStore;
634
+ readonly scope: Scope<unknown>;
635
+ readonly abort: AbortController;
636
+ readonly state: GraphFoldState;
637
+ readonly resuming: boolean;
638
+ /** Journal events present before this process started; empty on a fresh run. */
639
+ readonly prior: ReadonlyArray<SpawnEvent>;
640
+ /** Next engine fold-event ordinal, and next engine `woken` ordinal. */
641
+ readonly engineSeq: number;
642
+ readonly engineWokenSeq: number;
643
+ /** Ledger ordinals already used by a prior process. */
644
+ readonly ledgerSeq: number;
645
+ }
646
+ /** Begin or resume a run's journaled tree, pool, scope and folded state. */
647
+ declare function openGraphRun(args: {
648
+ readonly compiled: CompiledGraph;
649
+ readonly runId: string;
650
+ readonly budget: Budget;
651
+ readonly journal?: SpawnJournal;
652
+ readonly blobs?: ResultBlobStore;
653
+ readonly now: () => number;
654
+ readonly resume?: boolean;
655
+ readonly signal?: AbortSignal;
656
+ readonly onAbort: (listener: () => void) => void;
657
+ }): Promise<GraphRunContext>;
658
+ //#endregion
659
+ //#region src/runtime/graph/admit.d.ts
660
+ /**
661
+ * Edge payload admission (agent-runtime#971): every value crossing an edge is JSON round-tripped,
662
+ * `undefined` stripped to absence, and a non-representable value (a cycle, a BigInt, a function)
663
+ * becomes a RECORD of that fact. This is the kernel's existing findings-guard rule, and it is what
664
+ * makes `inputRef` stable and `onCrash: 'restart'` well defined — a degraded record beats a
665
+ * vanished edge.
666
+ */
667
+ declare function admitPayload(value: unknown): unknown;
668
+ //#endregion
669
+ //#region src/runtime/graph/suspension.d.ts
670
+ declare const SUSPEND_MARK = "__graphSuspension";
671
+ /** What a kind's executor returns to park its node until a host wakes it. */
672
+ interface SuspensionRequest {
673
+ readonly [SUSPEND_MARK]: true;
674
+ readonly onExpire: 'wait' | 'fail' | 'default';
675
+ /** Milliseconds from the suspension's journaling instant; absent with `onExpire: 'wait'`. */
676
+ readonly expiresInMs?: number;
677
+ readonly default?: unknown;
678
+ }
679
+ /** Build a suspension request. `wait` never expires; `fail` settles the node down at its deadline;
680
+ * `default` resolves with the given payload. */
681
+ declare function suspended(options?: {
682
+ readonly onExpire?: 'wait' | 'fail' | 'default';
683
+ readonly expiresInMs?: number;
684
+ readonly default?: unknown;
685
+ }): SuspensionRequest;
686
+ /** Whether a node's output is a park request rather than its result. */
687
+ declare function isSuspensionRequest(value: unknown): value is SuspensionRequest;
688
+ /** Content-addressed over the run identity, so a restart recomputes it and needs no token table. */
689
+ declare function mintSuspensionToken(runId: string, instance: string): string;
690
+ /** The journal id one suspension's `waiting`/`woken` pair shares. */
691
+ declare function suspensionNodeId(token: string): string;
692
+ /** The token inside a suspension node id, or `undefined` for any other id. */
693
+ declare function tokenFromSuspensionNodeId(id: string): string | undefined;
694
+ //#endregion
695
+ //#region src/runtime/graph/scheduler.d.ts
440
696
  interface GraphRunOptions {
441
697
  /** The run's conserved pool. */
442
698
  readonly budget: Budget;
@@ -448,20 +704,30 @@ interface GraphRunOptions {
448
704
  /** Resolves `delegates`/`analyzes` directives; required when any edge carries one. */
449
705
  readonly prompts?: PromptRegistry;
450
706
  /** How terminal settles reduce to `out`. Default `bestDelivered`. */
451
- readonly finalizer?: 'bestDelivered' | 'collectDelivered' | SupervisorFinalizer;
707
+ readonly finalizer?: FinalizerChoice;
452
708
  readonly signal?: AbortSignal;
453
709
  readonly now?: () => number;
454
710
  readonly runId?: string;
711
+ /** Continue an existing journaled run. An existing tree without this refuses, like the kernel. */
712
+ readonly resume?: boolean;
713
+ /** Hold a fully-suspended run open for live `resume()` calls instead of returning
714
+ * `{ kind: 'suspended' }`. Offline callers leave this off and restart later (#976). */
715
+ readonly waitForWakes?: boolean;
455
716
  }
456
- /** Admission for every value crossing an edge (#971): JSON round-trip, `undefined` stripped, a
457
- * non-representable value becomes a RECORD of that fact — a degraded record beats a vanished
458
- * edge. */
459
- declare function admitPayload(value: unknown): unknown;
717
+ /** A live run: await `done`; deliver host wakes through `resume`/`expire` (#976). */
718
+ interface GraphRunHandle {
719
+ readonly done: Promise<GraphRunResult>;
720
+ resume(token: string, payload: unknown): Promise<void>;
721
+ expire(token: string): Promise<void>;
722
+ }
723
+ /** Run a graph to its result: `createGraphRun` awaited — the one-call form for a run that needs no
724
+ * live host wakes. */
725
+ declare function runEngineGraph(engine: GraphEngine, spec: EngineGraphSpec | CompiledGraph, task: string, options: GraphRunOptions): Promise<GraphRunResult>;
460
726
  /**
461
- * Run a graph: host every node instance on one kernel `Scope`, resolve joins over guarded edges,
462
- * enforce the traversal and visit caps, and reduce the terminal settlements through the finalizer.
727
+ * Start (or resume) a graph run and return its handle: await `done` for the result; deliver host
728
+ * wakes through `resume`/`expire` while it runs (#976).
463
729
  */
464
- declare function runEngineGraph(engine: GraphEngine, spec: EngineGraphSpec | CompiledGraph, task: string, options: GraphRunOptions): Promise<GraphRunResult>;
730
+ declare function createGraphRun(engine: GraphEngine, spec: EngineGraphSpec | CompiledGraph, task: string, options: GraphRunOptions): GraphRunHandle;
465
731
  //#endregion
466
- export { type AgentKindConfig, type BudgetMode, CONDITION_OPS, type CompiledEdge, type CompiledGraph, type CompiledNode, type Condition, type ConditionLeaf, type ConditionOp, DEFAULT_MAX_NODE_VISITS, type EffectContext, type EffectName, type EngineGraphEdge, type EngineGraphNode, type EngineGraphSpec, type GraphEdgeKind, type GraphEdgeTraversal, type GraphEngine, type GraphEngineOptions, type GraphNodeSettle, type GraphRunOptions, type GraphRunReason, type GraphRunResult, JOIN_RULES, type JoinRule, type JsonSchema, MAX_MAX_NODE_VISITS, type NodeFlags, type NodeKind, type OnCrash, type PortSpec, type Projection, type Registered, type Registry, type RegistryHandle, type ScriptBody, type ScriptKindConfig, type SupervisorKindConfig, admitPayload, agentKind, applyProjection, compileGraph, createGraphEngine, createRegistry, evaluateCondition, formatRegistryHandle, kindHandle, narrowEffects, parseRegistryHandle, runEngineGraph, schemaAccepts, scriptKind, subgraphKind, supervisorKind, validateCondition, validateNodeKind, validateProjection };
732
+ export { type AgentKindConfig, type BudgetMode, CONDITION_OPS, type CompiledEdge, type CompiledGraph, type CompiledNode, type Condition, type ConditionLeaf, type ConditionOp, DEFAULT_MAX_NODE_VISITS, ENGINE_WOKEN_SEQ_BASE, type EdgeLedger, type EffectContext, type EffectName, type EngineGraphEdge, type EngineGraphNode, type EngineGraphSpec, type FinalizerChoice, type FoldEdge, type FoldEdgeState, type FoldInstance, type FoldInstanceStatus, type FoldNode, type FoldSuspension, type GatingEdge, type GraphEdgeKind, type GraphEdgeTraversal, type GraphEngine, type GraphEngineOptions, type GraphFoldState, type GraphNodeSettle, type GraphRunContext, type GraphRunHandle, type GraphRunOptions, type GraphRunReason, type GraphRunResult, JOIN_RULES, type JoinDecision, type JoinRule, type JsonSchema, MAX_MAX_NODE_VISITS, type NodeFlags, type NodeKind, type OnCrash, type PortSpec, type Projection, RUN_GRAPH_KIND, type Registered, type Registry, type RegistryHandle, type RunGraphBody, type RunGraphCapture, type RunGraphNodeConfig, type RunGraphNodeOut, type ScriptBody, type ScriptKindConfig, type SupervisorKindConfig, type SuspensionRequest, admitPayload, agentKind, applyGraphFoldEvent, applyProjection, assembleGraphResult, compileGraph, createEdgeLedger, createGraphEngine, createGraphRun, createRegistry, decideJoin, emptyFoldState, evaluateCondition, foldGraphJournal, formatRegistryHandle, graphFromRunGraph, isEngineFired, isSuspensionRequest, kindHandle, materializeSettles, mintSuspensionToken, narrowEffects, openGraphRun, parseRegistryHandle, runEngineGraph, runGraphEngine, runGraphKind, runGraphThroughEngine, schemaAccepts, scriptKind, subgraphKind, supervisorKind, suspended, suspensionNodeId, tokenFromSuspensionNodeId, validateCondition, validateNodeKind, validateProjection };
467
733
  //# sourceMappingURL=graph.d.ts.map