@graphrefly/graphrefly 0.47.1 → 0.48.0

package/dist/presets/ai/index.js

@@ -1,17 +1,17 @@
 import {
   DebateGraph,
   heterogeneousDebate
-} from "../../chunk-E5OZPDIW.js";
+} from "../../chunk-X7BA5PWG.js";
 import {
   CompressionCache,
   renderContextView,
   taggedContextPool,
   tierCompress
-} from "../../chunk-MTTRCEJT.js";
+} from "../../chunk-DVTDF5OI.js";
 import {
   AgentMemoryGraph,
   agentMemory
-} from "../../chunk-J5WFUEO4.js";
+} from "../../chunk-23MAWVOJ.js";
 import {
   AgentGraph,
   AgentLoopGraph,
@@ -20,19 +20,19 @@ import {
   agent,
   agentLoop,
   presetRegistry
-} from "../../chunk-RGMTUZCL.js";
-import "../../chunk-YXCPV26R.js";
-import "../../chunk-U225SKB4.js";
-import "../../chunk-NPRP3MCV.js";
-import "../../chunk-QMBYUVRL.js";
-import "../../chunk-FMPF42Q4.js";
-import "../../chunk-BXGZFGZ4.js";
-import "../../chunk-A7KV5UK4.js";
-import "../../chunk-DKNHAICT.js";
-import "../../chunk-O3MT7DYI.js";
-import "../../chunk-Z4YXAUDN.js";
+} from "../../chunk-65OM4XLQ.js";
+import "../../chunk-3REMCHSS.js";
+import "../../chunk-K4ZYJ4EM.js";
+import "../../chunk-DHDCOOJU.js";
+import "../../chunk-KUFXLAEY.js";
 import "../../chunk-TSBFTJKM.js";
 import "../../chunk-P5LBT622.js";
+import "../../chunk-QMBYUVRL.js";
+import "../../chunk-FMPF42Q4.js";
+import "../../chunk-C5QD5DQX.js";
+import "../../chunk-G7H6PN7P.js";
+import "../../chunk-MMHGYX44.js";
+import "../../chunk-N6MNJNHB.js";
 import "../../chunk-AZDQPQ3V.js";
 export {
   AgentGraph,

package/dist/presets/harness/index.cjs

@@ -313,11 +313,13 @@ function withTimeout(source, opts, extraOpts) {
       if (latestOpts != null) {
         attachSource();
       }
-      return () => {
-        stopped = true;
-        timer.cancel();
-        if (srcUnsub) srcUnsub();
-        if (optsUnsub) optsUnsub();
+      return {
+        onDeactivation: () => {
+          stopped = true;
+          timer.cancel();
+          if (srcUnsub) srcUnsub();
+          if (optsUnsub) optsUnsub();
+        }
       };
     },
     {
@@ -431,9 +433,11 @@ function _oneShotLlmCall(adapter, messages, config) {
         invokeResult = adapter.invoke(messages, { ...config.invokeOpts, signal: ac.signal });
       } catch (err) {
         emitOnce(config.onFailure("throw", err));
-        return () => {
-          unlinkParent();
-          ac.abort();
+        return {
+          onDeactivation: () => {
+            unlinkParent();
+            ac.abort();
+          }
         };
       }
       const callNode = (0, import_extra.fromAny)(invokeResult, { signal: ac.signal });
@@ -462,11 +466,13 @@ function _oneShotLlmCall(adapter, messages, config) {
         unsub();
         unsub = null;
       }
-      return () => {
-        unlinkParent();
-        ac.abort();
-        unsub?.();
-        unsub = null;
+      return {
+        onDeactivation: () => {
+          unlinkParent();
+          ac.abort();
+          unsub?.();
+          unsub = null;
+        }
       };
     },
     { describeKind: "producer" }
@@ -676,7 +682,7 @@ function actorPool(parent, opts = {}) {
   const name = opts.name ?? `actorPool-${++_actorPoolSeq}`;
   const graph = new import_graph2.Graph(name);
   parent.mount(name, graph);
-  const depthCap = opts.depthCap ?? Number.POSITIVE_INFINITY;
+  const depthCap = opts.depthCap ?? 8;
   let autoActor = 0;
   const liveHandles = /* @__PURE__ */ new Set();
   const contextPool = taggedContextPool(graph, {
@@ -808,6 +814,26 @@ function createAuditLog(opts) {
   }
   return log;
 }
+function readonlyAuditLog(log) {
+  return Object.freeze({
+    get entries() {
+      return log.entries;
+    },
+    get size() {
+      return log.size;
+    },
+    get lastValue() {
+      return log.lastValue;
+    },
+    get mutationLog() {
+      return log.mutationLog;
+    },
+    at: log.at.bind(log),
+    withLatest: log.withLatest.bind(log),
+    view: log.view.bind(log),
+    scan: log.scan.bind(log)
+  });
+}
 function deepFreeze(value) {
   if (value === null || typeof value !== "object" || Object.isFrozen(value)) return value;
   for (const k of Object.keys(value)) {
@@ -1394,6 +1420,16 @@ function topicBridge(name, sourceTopic, targetTopic, opts) {
 
 // src/presets/harness/refine-loop.ts
 var RefineLoopGraph = class extends import_graph5.Graph {
+  /**
+   * Best candidate so far. **SENTINEL until the first iteration settles** —
+   * `loop.best.cache` is `undefined` (not `null`) before any iteration
+   * produces a best, and a degenerate empty-candidate iteration leaves the
+   * prior best in place rather than wiping it. Consumers guard with
+   * `=== undefined` (spec §3 SENTINEL), not `== null`. (Anti-pattern sweep
+   * 2026-05-18: dropped the `initial: null` eager-placeholder; `null` is
+   * reserved for the per-iteration {@link Iteration.best} data field where an
+   * empty batch is a valid domain value.)
+   */
   best;
   /**
    * Best score so far. Pseudo-private (`_score`) to avoid colliding with any
@@ -1444,8 +1480,7 @@ var RefineLoopGraph = class extends import_graph5.Graph {
     });
     this.add(strategyNode, { name: "strategy" });
     const lastFeedbackState = (0, import_core6.node)([], {
-      name: "lastFeedback",
-      initial: null
+      name: "lastFeedback"
     });
     this.add(lastFeedbackState, { name: "lastFeedback" });
     const prevCandidatesState = (0, import_core6.node)([], {
@@ -1464,7 +1499,7 @@ var RefineLoopGraph = class extends import_graph5.Graph {
       // append-style; reactive consumers want every push
     });
     this.add(historyState, { name: "history" });
-    const bestState = (0, import_core6.node)([], { name: "best", initial: null });
+    const bestState = (0, import_core6.node)([], { name: "best" });
     this.add(bestState, { name: "best" });
     const scoreState = (0, import_core6.node)([], { name: "score", initial: Number.NEGATIVE_INFINITY });
     this.add(scoreState, { name: "score" });
@@ -1488,7 +1523,7 @@ var RefineLoopGraph = class extends import_graph5.Graph {
     this.decide = hubDecideTopic;
     this._pauseState = pauseState;
     let latestStrategy = initialStrategy;
-    let latestFeedback = null;
+    let latestFeedback;
     let latestPrevCandidates = [];
     this.addDisposer(
       strategyNode.subscribe((msgs) => {
@@ -1509,7 +1544,7 @@ var RefineLoopGraph = class extends import_graph5.Graph {
       iterationTrigger,
       (iter) => {
         const strat = latestStrategy;
-        const isSeed = iter === 0 || latestFeedback == null;
+        const isSeed = iter === 0 || latestFeedback === void 0;
         return (0, import_core6.node)(
           [],
           (_data, actions) => {
@@ -1525,8 +1560,10 @@ var RefineLoopGraph = class extends import_graph5.Graph {
                     if (!cancelled) actions.down([[import_core6.ERROR, err]]);
                   }
                 );
-                return () => {
-                  cancelled = true;
+                return {
+                  onDeactivation: () => {
+                    cancelled = true;
+                  }
                 };
               }
               actions.emit({ iter, items: result });
@@ -1899,7 +1936,7 @@ var RefineLoopGraph = class extends import_graph5.Graph {
           decision = "paused";
         }
         (0, import_core6.batch)(() => {
-          bestState.emit(best);
+          if (best !== null) bestState.emit(best);
           scoreState.emit(fb.score);
           historyState.emit(nextHistory);
           budgetState.emit(nextBudget);
@@ -2139,7 +2176,7 @@ function errorCritique(opts) {
 function defaultToOutput(result) {
   const { best, score, status } = result;
   const scoreStr = Number.isFinite(score) ? score.toFixed(3) : String(score);
-  const artifact = best ?? void 0;
+  const artifact = best;
   if (status === "converged") {
     return {
       outcome: "success",
@@ -2665,9 +2702,11 @@ function _retrySource(source, opts, emitState) {
       const merged = makeMergedOptsMirror(opts);
       const getCfg = () => resolveRetryConfig(merged.current());
       const inner = _runRetryStateMachine(getCfg, () => source, a, emitState);
-      return () => {
-        inner();
-        merged.unsub();
+      return {
+        onDeactivation: () => {
+          inner();
+          merged.unsub();
+        }
       };
     },
     {
@@ -2691,9 +2730,11 @@ function _retryFactory(factory, opts, emitState) {
       const merged = makeMergedOptsMirror(opts);
       const getCfg = () => resolveRetryConfig(merged.current());
       const inner = _runRetryStateMachine(getCfg, factory, a, emitState);
-      return () => {
-        inner();
-        merged.unsub();
+      return {
+        onDeactivation: () => {
+          inner();
+          merged.unsub();
+        }
       };
     },
     {
@@ -2791,8 +2832,10 @@ function promptNode(adapter, deps, prompt, opts) {
           } catch (err) {
             done = true;
             actions.down([[import_core13.ERROR, err]]);
-            return () => {
-              abortDispose?.();
+            return {
+              onDeactivation: () => {
+                abortDispose?.();
+              }
             };
           }
           const callNode = (0, import_extra9.fromAny)(invokeResult);
@@ -2850,11 +2893,13 @@ function promptNode(adapter, deps, prompt, opts) {
               }
             }
           });
-          return () => {
-            cancelled = true;
-            sub();
-            abortDispose?.();
-            abortDispose = void 0;
+          return {
+            onDeactivation: () => {
+              cancelled = true;
+              sub();
+              abortDispose?.();
+              abortDispose = void 0;
+            }
           };
         },
         {
@@ -3069,6 +3114,10 @@ var PipelineGraph = class extends import_graph7.Graph {
       {
         name,
         describeKind: "derived",
+        // Spec §2.7 R2.7.1 (DS-2.7.A). fn must fire on
+        // upstream-COMPLETE/ERROR-only-without-DATA so the
+        // teardown-decision record + downstream terminal forward run.
+        terminalAsRealInput: true,
         meta: meta("approval_gate", opts.meta)
       }
     );
@@ -3286,6 +3335,11 @@ var PipelineGraph = class extends import_graph7.Graph {
         describeKind: "derived",
         completeWhenDepsComplete: opts.completeWhenDepsComplete ?? !(mode === "completed" || mode === "terminal"),
         errorWhenDepsError: !(mode === "errored" || mode === "terminal"),
+        // Spec §2.7 R2.7.1 (DS-2.7.A). `catch` exists to fire on a
+        // source terminal — its whole job is `recover(cause, …)` on a
+        // terminal-only wave. Without this opt-in the gate holds and
+        // the recover branch never runs.
+        terminalAsRealInput: true,
         meta: meta("catch", opts.meta)
       }
     );
@@ -3531,16 +3585,20 @@ var ToolRegistryGraph = class extends import_graph9.Graph {
           inner = handlerResultToNode(raw, ac.signal);
         } catch (err) {
           actions.down([[import_core17.ERROR, err]]);
-          return () => {
-            ac.abort();
+          return {
+            onDeactivation: () => {
+              ac.abort();
+            }
           };
         }
         const unsub = inner.subscribe((batch10) => {
           actions.down(batch10);
         });
-        return () => {
-          ac.abort();
-          unsub();
+        return {
+          onDeactivation: () => {
+            ac.abort();
+            unsub();
+          }
         };
       },
       {
@@ -3750,7 +3808,10 @@ var JobQueueGraph = class extends import_graph11.Graph {
   depth;
   /** Audit log of every queue mutation (Audit 2). */
   events;
-  /** Alias for {@link JobQueueGraph.events} — Audit 2 `.audit` duplication. */
+  /**
+   * Read-only view of {@link JobQueueGraph.events} — Audit 2 `.audit`
+   * duplication; M7 (cannot mutate the canonical log via the alias).
+   */
   audit;
   // Tier 8 / COMPOSITION-GUIDE §35: mutate wrappers for the four
   // single-record mutation methods. Assigned in the constructor (NOT via
@@ -3791,7 +3852,7 @@ var JobQueueGraph = class extends import_graph11.Graph {
       retainedLimit: 1024,
       graph: this
     });
-    this.audit = this.events;
+    this.audit = readonlyAuditLog(this.events);
     this._seqCursor = registerCursor(this, "seq", 0);
     this._enqueueImpl = mutate(
       (payload, enqueueOpts) => {
@@ -3844,7 +3905,7 @@ var JobQueueGraph = class extends import_graph11.Graph {
       }
     );
     this._nackImpl = mutate(
-      (id, job, requeue) => {
+      (id, job, requeue, _error) => {
         if (requeue) {
           this._jobs.set(id, { ...job, state: "queued" });
           this._pending.append(id);
@@ -3857,12 +3918,16 @@ var JobQueueGraph = class extends import_graph11.Graph {
         log: this.events,
         seq: this._seqCursor,
         freeze: false,
-        onSuccessRecord: ([id, job], _r, { t_ns, seq }) => ({
+        onSuccessRecord: ([id, job, requeue, error], _r, { t_ns, seq }) => ({
           action: "nack",
           id,
           attempts: job.attempts,
           t_ns,
-          seq: seq ?? 0
+          seq: seq ?? 0,
+          // F-CATCH D-3: surface the failure cause on the no-requeue
+          // (terminal-failure) nack only. A requeue nack is a retry,
+          // not a failure, so it carries no error.
+          ...!requeue && error !== void 0 ? { error } : {}
         })
       }
     );
@@ -3934,10 +3999,20 @@ var JobQueueGraph = class extends import_graph11.Graph {
     this._ackImpl(id, job);
     return true;
   }
+  /**
+   * Negatively-acknowledge an inflight job.
+   *
+   * @param opts.requeue - `true` (default) returns the job to the queue for
+   *   retry; `false` drops it permanently (terminal failure).
+   * @param opts.error - Optional failure cause for a `requeue: false` nack.
+   *   Recorded on the emitted `"nack"` {@link JobEvent} as `error` so the
+   *   reason a job failed is recoverable from the event stream (F-CATCH
+   *   D-3). Ignored when `requeue` is `true` (a retry is not a failure).
+   */
   nack(id, opts = {}) {
     const job = this._jobs.get(id);
     if (!job || job.state !== "inflight") return false;
-    this._nackImpl(id, job, opts.requeue ?? true);
+    this._nackImpl(id, job, opts.requeue ?? true, opts.error);
     return true;
   }
   /**
@@ -4103,10 +4178,10 @@ var JobFlowGraph = class extends import_graph11.Graph {
               let result;
               try {
                 result = workFn(job, { signal: ac.signal });
-              } catch {
+              } catch (err) {
                 inflight.delete(entry);
                 inflightCounter?.emit(inflight.size);
-                current.nack(job.id, { requeue: false });
+                current.nack(job.id, { requeue: false, error: err });
                 processed += 1;
                 continue;
               }
@@ -4157,7 +4232,7 @@ var JobFlowGraph = class extends import_graph11.Graph {
                   } else if (m[0] === import_core19.ERROR) {
                     settled = true;
                     cleanupSub();
-                    current.nack(job.id, { requeue: false });
+                    current.nack(job.id, { requeue: false, error: m[1] });
                     return;
                   }
                 }
@@ -4413,7 +4488,18 @@ var HarnessGraph = class extends import_graph12.Graph {
    * (use {@link unrouted}), and the internal `triage-output` fan-in.
    */
   queueTopics;
-  /** Strategy model — `auditedSuccessTracker` keyed by `StrategyKey`. */
+  /**
+   * Strategy model — `auditedSuccessTracker` keyed by `StrategyKey`.
+   *
+   * **Ownership (EC10/EC15).** Owned by the harness: it is mounted as a
+   * child subgraph (`harness.mount("strategy", strategy)`), so its disposal
+   * cascades from `harness.destroy()` via the mount lifecycle. Do **not**
+   * call `strategy.destroy()` independently — the harness's `triage-input`
+   * node and (when `opts.priority` is set) `buildPriorityScores` hold
+   * cross-graph deps on `strategy.entries`; destroying the strategy out of
+   * band staleness those nodes while the rest of the loop keeps running.
+   * Read/subscribe freely; let the harness own the lifecycle.
+   */
   strategy;
   /** Global retry count across all items (circuit breaker). Reactive — subscribable. */
   totalRetries;
@@ -5255,6 +5341,11 @@ var AgentLoopGraph = class extends import_graph15.Graph {
           chat.append("assistant", response.content, {
             toolCalls: response.toolCalls
           });
+          if (capReached && hasToolCalls) {
+            for (const tc of response.toolCalls) {
+              chat.appendToolResult(tc.id, "[tool call denied: maxTurns reached]");
+            }
+          }
         });
       },
       { describeKind: "effect" }
@@ -5276,6 +5367,45 @@ var AgentLoopGraph = class extends import_graph15.Graph {
       },
       { describeKind: "effect" }
     );
+    const effFullDeny = gatedToolCallsNode !== toolCallsRaw ? (0, import_core22.node)(
+      [toolCallsRaw, gatedToolCallsNode],
+      (batchData) => {
+        if (latestAborted) return;
+        const rawBatch = batchData[0];
+        const gatedBatch = batchData[1];
+        const rawCalls = rawBatch != null && rawBatch.length > 0 ? rawBatch.at(-1) : null;
+        if (rawCalls == null || rawCalls.length === 0) return;
+        const gatedCalls = gatedBatch != null && gatedBatch.length > 0 ? gatedBatch.at(-1) : null;
+        const allowedIds = gatedCalls === null ? null : new Set(gatedCalls.map((c) => c.id));
+        const denied = allowedIds === null ? rawCalls : rawCalls.filter((c) => !allowedIds.has(c.id));
+        if (denied.length === 0) return;
+        const isFullDeny = gatedCalls === null;
+        (0, import_core22.batch)(() => {
+          if (isFullDeny) {
+            statusNode.emit(latestTurn >= maxTurns ? "done" : "thinking");
+          }
+          for (const c of denied)
+            chat.appendToolResult(c.id, "[tool call denied by interceptor]");
+        });
+      },
+      {
+        name: "fullDenyRecovery",
+        describeKind: "effect",
+        meta: aiMeta("agent_full_deny_recovery"),
+        // MUST be explicit: the core `node()` default is
+        // `partial: false` (node.ts `opts.partial ?? false`),
+        // and `gatedToolCallsNode` only ever emits RESOLVED on the
+        // full-deny path (never DATA/terminal). Spec R2.7.0
+        // (DS-2.7.A, 2026-05-19) holds the `partial: false`
+        // first-run gate until every dep has contributed real
+        // DATA, so a `partial: false` effFullDeny would hold the
+        // fn FOREVER. Spec R2.7.2 = `partial: true` disables the
+        // gate; the fn body's `denied`-subtraction guard above
+        // covers the SENTINEL slot per the R2.7.2 author
+        // contract.
+        partial: true
+      }
+    ) : null;
     let latestStatus = statusNode.cache ?? "idle";
     const statusSub = statusNode.subscribe((msgs) => {
       for (const m of msgs) if (m[0] === import_core22.DATA) latestStatus = m[1];
@@ -5295,6 +5425,7 @@ var AgentLoopGraph = class extends import_graph15.Graph {
     );
     const kaResponse = (0, import_extra17.keepalive)(effResponse);
     const kaResults = (0, import_extra17.keepalive)(effResults);
+    const kaFullDeny = effFullDeny ? (0, import_extra17.keepalive)(effFullDeny) : null;
     const kaAbort = (0, import_extra17.keepalive)(effAbort);
     this._terminalResult = (0, import_core22.node)(
       [statusNode, lastResponseState],
@@ -5347,6 +5478,7 @@ var AgentLoopGraph = class extends import_graph15.Graph {
     this.addDisposer(statusSub);
     this.addDisposer(kaResponse);
     this.addDisposer(kaResults);
+    if (kaFullDeny) this.addDisposer(kaFullDeny);
     this.addDisposer(kaAbort);
     this._disposeRunWiring = () => {
     };