agentfootprint 3.0.0 → 3.1.0

package/README.md

@@ -16,7 +16,7 @@
 
 <p align="center">
   <a href="https://github.com/footprintjs/agentfootprint/actions"><img src="https://github.com/footprintjs/agentfootprint/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-  <a href="https://codecov.io/gh/footprintjs/agentfootprint"><img src="https://codecov.io/gh/footprintjs/agentfootprint/branch/main/graph/badge.svg" alt="Coverage"></a>
+  <!-- coverage-badge --><img src="https://img.shields.io/badge/coverage-87%25-green.svg" alt="coverage: 87%"><!-- /coverage-badge -->
   <a href="https://www.npmjs.com/package/agentfootprint"><img src="https://img.shields.io/npm/v/agentfootprint.svg?style=flat" alt="npm version"></a>
   <a href="https://www.npmjs.com/package/agentfootprint"><img src="https://img.shields.io/npm/dm/agentfootprint.svg" alt="Downloads"></a>
   <a href="https://github.com/footprintjs/agentfootprint/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>

package/dist/cache/CacheDecisionSubflow.js

@@ -26,8 +26,7 @@
  * always-active rules) follow.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cacheDecisionSubflow = exports.computeCacheMarkers = exports.injectionTargetSlots = exports.evaluateCachePolicy = void 0;
-const footprintjs_1 = require("footprintjs");
+exports.decideCacheMarkers = exports.computeCacheMarkers = exports.injectionTargetSlots = exports.evaluateCachePolicy = void 0;
 /**
  * Evaluate a `CachePolicy` against the current context.
  * Returns `true` if the policy says THIS iteration's content is cacheable.
@@ -143,10 +142,13 @@ function computeCacheMarkers(state) {
 }
 exports.computeCacheMarkers = computeCacheMarkers;
 /**
- * The decision function. Thin scope-binding wrapper around
- * `computeCacheMarkers`.
+ * The decision stage function. Thin scope-binding wrapper around
+ * `computeCacheMarkers`. Exported so it can serve as the ROOT stage of
+ * the `sf-cache` subflow (a chart cannot start with a nested subflow),
+ * while `cacheDecisionSubflow` below still wraps the SAME function for
+ * standalone use — no logic duplication.
  */
-function decide(scope) {
+function decideCacheMarkers(scope) {
     scope.cacheMarkers = computeCacheMarkers({
         activeInjections: scope.activeInjections,
         iteration: scope.iteration,
@@ -158,17 +160,10 @@ function decide(scope) {
         cachingDisabled: scope.cachingDisabled,
     });
 }
-/**
- * The cache-decision subflow. Mounted into the agent's main chart
- * after the slot subflows (System / Messages / Tools) and before
- * the CacheGate decider stage.
- *
- * Mounted via `addSubFlowChartNext(SUBFLOW_IDS.CACHE_DECISION, ...)`
- * with `arrayMerge: ArrayMergeMode.Replace` on the outputMapper —
- * `cacheMarkers` MUST replace, not concatenate, across iterations
- * (same lesson as the v2.5.1 InjectionEngine fix).
- */
-exports.cacheDecisionSubflow = (0, footprintjs_1.flowChart)('DecideCacheMarkers', decide, 'decide-cache-markers', {
-    description: 'CacheDecision: walk activeInjections, evaluate cache directives, emit CacheMarker[]',
-}).build();
+exports.decideCacheMarkers = decideCacheMarkers;
+// NOTE: the cache decision is now the ROOT stage of the `sf-cache` subflow
+// (see core/agent/buildCacheSubflow.ts) via the exported `decideCacheMarkers`
+// above. The former standalone `cacheDecisionSubflow` FlowChart export was
+// removed when the agent stopped mounting it directly — `computeCacheMarkers`
+// + `decideCacheMarkers` are the reusable pieces.
 //# sourceMappingURL=CacheDecisionSubflow.js.map

package/dist/cache/CacheDecisionSubflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"CacheDecisionSubflow.js","sourceRoot":"","sources":["../../src/cache/CacheDecisionSubflow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CacheDecisionSubflow.js","sourceRoot":"","sources":["../../src/cache/CacheDecisionSubflow.ts"],"names":[],"mappings":"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"}

package/dist/cache/CacheGateDecider.js

@@ -102,15 +102,30 @@ exports.cacheGateDecide = cacheGateDecide;
 /**
  * Update the skill-history rolling window. Called as a function
  * stage BEFORE the CacheGate decider. Reads the current iteration's
- * active skill (head of `activatedInjectionIds`) and appends to the
- * `skillHistory` array.
+ * active skill (the MOST-RECENTLY activated one — the TAIL of
+ * `activatedInjectionIds`) and appends it to the `skillHistory` array.
+ *
+ * WHY THE TAIL, NOT THE HEAD: `read_skill` APPENDS each newly-activated
+ * skill to the end of `activatedInjectionIds`, and the list is cumulative
+ * + deduped per turn (reset only at seed). So the HEAD is frozen at the
+ * FIRST skill activated and never changes mid-turn — sampling it made the
+ * window record one constant value, so `detectSkillChurn` could never fire
+ * (the skill-churn cache rule was effectively dead). The tail tracks what
+ * the agent just switched to, which is the churn signal we actually want.
+ *
+ * KNOWN LIMITATION: if several skills are activated in the SAME iteration,
+ * only the last (tail) is recorded for that iteration — churn can
+ * under-count a multi-skill burst. A fully order-independent signal would
+ * read `activatedInjectionIds.length` directly in the gate; that is a
+ * larger change deferred for now.
  *
  * Window length is bounded at `SKILL_CHURN_WINDOW * 2` so the array
  * doesn't grow unboundedly across long agent runs. Old entries
  * fall off the front naturally.
  */
 function updateSkillHistory(scope) {
-    const current = scope.activatedInjectionIds?.[0];
+    const ids = scope.activatedInjectionIds ?? [];
+    const current = ids.length > 0 ? ids[ids.length - 1] : undefined;
     const prior = scope.skillHistory ?? [];
     const next = [...prior, current];
     // Bounded buffer — keep window*2 to give detectSkillChurn room

package/dist/cache/CacheGateDecider.js.map

@@ -1 +1 @@
-{"version":3,"file":"CacheGateDecider.js","sourceRoot":"","sources":["../../src/cache/CacheGateDecider.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;;AAEH,6CAA2E;AA6B3E;;;;;;;;;;;;GAYG;AACU,QAAA,cAAc,GAAG,GAAG,CAAC;AAElC;;;GAGG;AACU,QAAA,kBAAkB,GAAG,CAAC,CAAC;AAEpC;;;;GAIG;AACU,QAAA,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;GAGG;AACH,SAAgB,gBAAgB,CAC9B,OAAwC,EACxC,aAAqB,0BAAkB,EACvC,YAAoB,6BAAqB;IAEzC,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,yBAAyB;IACvE,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC;IAC1C,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,KAAK,SAAS;YAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,YAAY,CAAC,IAAI,IAAI,SAAS,CAAC;AACxC,CAAC;AAZD,4CAYC;AAQD;;;;;;;;;;;GAWG;AACH,SAAgB,eAAe,CAAC,KAAiC;IAC/D,OAAO,IAAA,oBAAM,EACX,KAAK,EACL;QACE;YACE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,KAAK,IAAI;YACvC,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,uDAAuD;SAC/D;QACD;YACE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,KAAK,SAAS,IAAI,CAAC,CAAC,aAAa,GAAG,sBAAc;YAC9E,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,cAAc,sBAAc,GAAG,GAAG,kBAAkB;SAC5D;QACD;YACE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,YAAY,CAAC;YAC7C,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,iBAAiB,6BAAqB,0BAA0B,0BAAkB,SAAS;SACnG;KACF,EACD,eAAe,CAChB,CAAC;AACJ,CAAC;AAtBD,0CAsBC;AAED;;;;;;;;;GASG;AACH,SAAgB,kBAAkB,CAChC,KAGE;IAEF,MAAM,OAAO,GAAG,KAAK,CAAC,qBAAqB,EAAE,CAAC,CAAC,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,KAAK,CAAC,YAAY,IAAI,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,CAAC,CAAC;IACjC,+DAA+D;IAC/D,mDAAmD;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,0BAAkB,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,0BAAkB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClG,KAAK,CAAC,YAAY,GAAG,OAAO,CAAC;AAC/B,CAAC;AAbD,gDAaC"}
+{"version":3,"file":"CacheGateDecider.js","sourceRoot":"","sources":["../../src/cache/CacheGateDecider.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;;;AAEH,6CAA2E;AA6B3E;;;;;;;;;;;;GAYG;AACU,QAAA,cAAc,GAAG,GAAG,CAAC;AAElC;;;GAGG;AACU,QAAA,kBAAkB,GAAG,CAAC,CAAC;AAEpC;;;;GAIG;AACU,QAAA,qBAAqB,GAAG,CAAC,CAAC;AAEvC;;;GAGG;AACH,SAAgB,gBAAgB,CAC9B,OAAwC,EACxC,aAAqB,0BAAkB,EACvC,YAAoB,6BAAqB;IAEzC,IAAI,OAAO,CAAC,MAAM,GAAG,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,yBAAyB;IACvE,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC;IAC1C,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;IACvC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,KAAK,SAAS;YAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,YAAY,CAAC,IAAI,IAAI,SAAS,CAAC;AACxC,CAAC;AAZD,4CAYC;AAQD;;;;;;;;;;;GAWG;AACH,SAAgB,eAAe,CAAC,KAAiC;IAC/D,OAAO,IAAA,oBAAM,EACX,KAAK,EACL;QACE;YACE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,eAAe,KAAK,IAAI;YACvC,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,uDAAuD;SAC/D;QACD;YACE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,KAAK,SAAS,IAAI,CAAC,CAAC,aAAa,GAAG,sBAAc;YAC9E,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,cAAc,sBAAc,GAAG,GAAG,kBAAkB;SAC5D;QACD;YACE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,gBAAgB,CAAC,CAAC,CAAC,YAAY,CAAC;YAC7C,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,iBAAiB,6BAAqB,0BAA0B,0BAAkB,SAAS;SACnG;KACF,EACD,eAAe,CAChB,CAAC;AACJ,CAAC;AAtBD,0CAsBC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,SAAgB,kBAAkB,CAChC,KAGE;IAEF,MAAM,GAAG,GAAG,KAAK,CAAC,qBAAqB,IAAI,EAAE,CAAC;IAC9C,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,MAAM,KAAK,GAAG,KAAK,CAAC,YAAY,IAAI,EAAE,CAAC;IACvC,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,EAAE,OAAO,CAAC,CAAC;IACjC,+DAA+D;IAC/D,mDAAmD;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,0BAAkB,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,0BAAkB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClG,KAAK,CAAC,YAAY,GAAG,OAAO,CAAC;AAC/B,CAAC;AAdD,gDAcC"}

package/dist/cache/cacheRecorder.js

@@ -28,6 +28,8 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cacheRecorder = void 0;
+const trace_1 = require("footprintjs/trace");
+const conventions_js_1 = require("../conventions.js");
 function cacheRecorder(options = {}) {
     const perIter = [];
     let lastDecision;
@@ -41,9 +43,16 @@ function cacheRecorder(options = {}) {
     const handle = {
         id: 'cache-recorder',
         onDecision(event) {
-            // Only care about CacheGate decisions; identified by the
-            // decider's stage id (the third arg to addDeciderFunction).
-            if (event.decider !== 'cache-gate')
+            // Only care about CacheGate decisions, matched by the decider's LOCAL
+            // stage id. Both `event.decider` (the node NAME) and the prefixed
+            // `traversalContext.stageId` become `sf-cache/…` now that CacheGate is
+            // nested in sf-cache, so we strip the subflow path with splitStageId and
+            // compare the local id. This is id-stable (survives a display-name
+            // rename) and nesting-safe (works top-level or inside sf-cache).
+            // (The old `event.decider !== 'cache-gate'` was a no-op: event.decider is
+            // the NAME 'CacheGate', never the id 'cache-gate'.)
+            const stageId = event.traversalContext?.stageId;
+            if (!stageId || (0, trace_1.splitStageId)(stageId).localStageId !== conventions_js_1.STAGE_IDS.CACHE_GATE)
                 return;
             const matched = event.evidence?.rules.find((r) => r.matched);
             lastDecision = {

package/dist/cache/cacheRecorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"cacheRecorder.js","sourceRoot":"","sources":["../../src/cache/cacheRecorder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cacheRecorder.js","sourceRoot":"","sources":["../../src/cache/cacheRecorder.ts"],"names":[],"mappings":"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"}

package/dist/conventions.js

@@ -11,13 +11,17 @@
  * Rename any ID here → both builders and recorders stay in sync.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isInjectionKey = exports.injectionKeyForSlot = exports.INJECTION_KEYS = exports.isKnownStage = exports.isKnownSubflow = exports.slotFromSubflowId = exports.isSlotSubflow = exports.STAGE_IDS = exports.SUBFLOW_IDS = void 0;
+exports.isInjectionKey = exports.injectionKeyForSlot = exports.INJECTION_KEYS = exports.milestoneFor = exports.stageRole = exports.isKnownStage = exports.isKnownSubflow = exports.slotFromRuntimeStageId = exports.slotFromSubflowId = exports.isSlotSubflow = exports.STAGE_IDS = exports.SUBFLOW_IDS = void 0;
 const trace_1 = require("footprintjs/trace");
 /** Subflow IDs — mounted by builders, observed by recorders. */
 exports.SUBFLOW_IDS = {
     /** Injection Engine subflow. Evaluates every Injection's trigger
      *  and writes activeInjections[] for the slot subflows to consume. */
     INJECTION_ENGINE: 'sf-injection-engine',
+    /** Inner subflow inside LLMCall that wraps the invocation
+     *  (seed + slots + call-llm + optional thinking + extract-final).
+     *  Mounted by LLMCall's outer `client` chart. */
+    LLM_CALL: 'sf-llm-call',
     /** System-prompt slot subflow. Observed by ContextRecorder. */
     SYSTEM_PROMPT: 'sf-system-prompt',
     /** Messages slot subflow. */
@@ -36,8 +40,18 @@ exports.SUBFLOW_IDS = {
      *  decider returns `'final'` as a routing value AND the same string
      *  becomes the subflow's id. */
     FINAL: 'final',
+    /** Cache subflow (v2.14). Wraps the whole per-turn cache machinery —
+     *  decide markers → CacheGate decider → apply/skip — as ONE collapsible
+     *  boundary in the chart. Provider-independent decision layer; the
+     *  attached provider's CacheStrategy turns markers into wire format.
+     *  UpdateSkillHistory stays OUTSIDE (in the main loop) so the rolling
+     *  skillHistory window persists across iterations without round-tripping
+     *  through this subflow. */
+    CACHE: 'sf-cache',
     /** Cache decision subflow (v2.6). Walks activeInjections, emits
-     *  agnostic CacheMarker[]. Provider-independent. */
+     *  agnostic CacheMarker[]. Provider-independent. Standalone building
+     *  block; the agent now uses the `decideCacheMarkers` stage inside
+     *  `sf-cache` instead of mounting this directly. */
     CACHE_DECISION: 'sf-cache-decision',
     /** Thinking-normalization mount (v2.14). Wraps the consumer's
      *  ThinkingHandler.normalize() in a real footprintjs subflow so it
@@ -50,7 +64,24 @@ exports.SUBFLOW_IDS = {
 /** Stage IDs — plain function stages that builders mount. */
 exports.STAGE_IDS = {
     SEED: 'seed',
+    /** Context-assembly selector stage. Runs AFTER InjectionEngine and
+     *  fans the 3 slot subflows (system-prompt / messages / tools) out in
+     *  PARALLEL (selector picks all 3 every iteration; failFast so a
+     *  required slot's throw aborts the turn). They converge before
+     *  CacheDecision. Shared by buildAgentChart + buildDynamicAgentChart;
+     *  the flat viz proof chart uses the same id as its root selector. */
+    CONTEXT: 'context',
+    /** Outer "client" stage in LLMCall's wrapped chart. Receives args on
+     *  the first visit, $break()s on the second (post-loop) visit with
+     *  the LLM answer as TraversalResult. This is the lens-friendly
+     *  affordance — the User pill maps to this stage. */
+    CLIENT: 'client',
     CALL_LLM: 'call-llm',
+    /** Final-response extraction stage that runs after CallLLM (and
+     *  optional sf-thinking). For LLMCall this is mostly symmetric with
+     *  Agent's `sf-final` branch — gives lens a "Final" node and a
+     *  clear commit boundary marking "we have the answer." */
+    EXTRACT_FINAL: 'extract-final',
     FINAL: 'final',
     FORMAT_MERGE: 'format-merge',
     MERGE_LLM: 'merge-llm',
@@ -96,6 +127,30 @@ function slotFromSubflowId(id) {
     }
 }
 exports.slotFromSubflowId = slotFromSubflowId;
+/**
+ * Resolve the context slot a scope write belongs to FROM THE WRITE'S OWN
+ * `runtimeStageId` — not from a "currently-open slot" stack.
+ *
+ * Why: once the 3 slot subflows run in PARALLEL (selector fan-out), their
+ * entry/write/exit events INTERLEAVE — a stack top is unreliable, so a write
+ * inside `sf-messages` could be attributed to (or dropped against)
+ * `sf-tools`. The write's `runtimeStageId` (`[subflowPath/]stageId#index`)
+ * always encodes which slot subflow enclosed it; we scan the path segments
+ * innermost-first for a slot id. Matches the sequential result exactly
+ * (the write is still inside its own slot), so it is behavior-preserving.
+ */
+function slotFromRuntimeStageId(runtimeStageId) {
+    // Strip the `#index` suffix, then walk `[subflowPath/]stageId` segments.
+    const path = runtimeStageId.split('#', 1)[0];
+    const segments = path.split('/');
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const slot = slotFromSubflowId(segments[i]);
+        if (slot)
+            return slot;
+    }
+    return undefined;
+}
+exports.slotFromRuntimeStageId = slotFromRuntimeStageId;
 /** True when an id is any of the library's known subflow IDs. */
 function isKnownSubflow(id) {
     return Object.values(exports.SUBFLOW_IDS).includes(id);
@@ -106,6 +161,101 @@ function isKnownStage(id) {
     return Object.values(exports.STAGE_IDS).includes(id);
 }
 exports.isKnownStage = isKnownStage;
+/** Mechanism stages — present so the run works, not what the user reads. */
+const PLUMBING_LOCAL_IDS = new Set([
+    exports.SUBFLOW_IDS.INJECTION_ENGINE,
+    exports.SUBFLOW_IDS.LLM_CALL, // wrapper; the hero is the `call-llm` stage INSIDE it
+    exports.SUBFLOW_IDS.ROUTE,
+    exports.SUBFLOW_IDS.MERGE,
+    exports.SUBFLOW_IDS.CACHE,
+    exports.SUBFLOW_IDS.CACHE_DECISION,
+    exports.SUBFLOW_IDS.THINKING,
+    exports.STAGE_IDS.CONTEXT, // the selector fan-out point; its 3 slot children are the heroes
+    exports.STAGE_IDS.CLIENT,
+    exports.STAGE_IDS.EXTRACT_FINAL,
+    exports.STAGE_IDS.FORMAT_MERGE,
+    exports.STAGE_IDS.EXTRACT_MERGE,
+    exports.STAGE_IDS.UPDATE_SKILL_HISTORY,
+    exports.STAGE_IDS.CACHE_GATE,
+    exports.STAGE_IDS.APPLY_MARKERS,
+    exports.STAGE_IDS.SKIP_CACHING,
+    exports.STAGE_IDS.BUILD_LLM_REQUEST,
+]);
+/** Neutral chart boundaries — entry/exit, rendered normally (not muted). */
+const BOUNDARY_LOCAL_IDS = new Set([
+    exports.STAGE_IDS.SEED, // 'Initialize' — chart root / Agent boundary
+    exports.STAGE_IDS.FINAL, // 'final' (=== SUBFLOW_IDS.FINAL)
+]);
+/**
+ * Classify a stage id into its {@link StageRole}. Accepts a path-qualified id
+ * (`sf-llm-call/call-llm`) — only the LOCAL segment matters, so it works at
+ * any nesting depth. Built entirely from the id constants above, so adding a
+ * stage to the chart only requires listing it here.
+ */
+function stageRole(id) {
+    const { localStageId } = (0, trace_1.splitStageId)(id);
+    if (isSlotSubflow(localStageId))
+        return 'hero-slot';
+    if (localStageId === exports.STAGE_IDS.CALL_LLM || localStageId === exports.STAGE_IDS.MERGE_LLM)
+        return 'hero-llm';
+    // Tool execution mounts under the bare branch key 'tool-calls' in shipped
+    // charts; SUBFLOW_IDS.TOOL_CALLS is the reserved prefixed form.
+    if (localStageId === 'tool-calls' || localStageId === exports.SUBFLOW_IDS.TOOL_CALLS)
+        return 'hero-action';
+    if (BOUNDARY_LOCAL_IDS.has(localStageId))
+        return 'boundary';
+    if (PLUMBING_LOCAL_IDS.has(localStageId))
+        return 'plumbing';
+    return 'boundary'; // unknown → neutral (never silently muted)
+}
+exports.stageRole = stageRole;
+/**
+ * Classify a stage id into a {@link Milestone}, or `null` when the stage is NOT
+ * a milestone boundary (its commits fold into the surrounding milestone's
+ * collection). This is the DOMAIN's declaration of which steps are scrub-worthy;
+ * the Lens consumes it to build the time-travel slider (see
+ * agentfootprint-lens `cursorPositionsAtDrill`).
+ *
+ * Mirrors {@link stageRole}: accepts a runtimeStageId (`call-llm#17`), a
+ * path-qualified id (`sf-llm-call/call-llm`), or a bare local id — only the
+ * LOCAL stage segment matters, so it works at any nesting depth and for both
+ * commit ids and subflow-group ids.
+ */
+function milestoneFor(id) {
+    // Strip the `#executionIndex` suffix (runtimeStageId form) before decomposing
+    // the path prefix — splitStageId expects the segment before `#`.
+    const beforeHash = id.includes('#') ? id.slice(0, id.indexOf('#')) : id;
+    const { localStageId } = (0, trace_1.splitStageId)(beforeHash);
+    switch (localStageId) {
+        // Loop entry — one per ReAct iteration. INJECTION_ENGINE is the flat loop
+        // target; LLM_CALL is the subflow-shape loop target.
+        case exports.SUBFLOW_IDS.INJECTION_ENGINE:
+        case exports.SUBFLOW_IDS.LLM_CALL:
+            return { kind: 'iteration', label: 'Iteration' };
+        // Context slots — one stop per slot that was engineered THIS iteration. In
+        // dynamic mode all three appear every turn; in classic mode only the slot
+        // that actually re-ran (Messages) appears after turn 1 — so scrubbing shows
+        // exactly "which slot got updated."
+        case exports.SUBFLOW_IDS.SYSTEM_PROMPT:
+            return { kind: 'slot', label: 'System prompt' };
+        case exports.SUBFLOW_IDS.MESSAGES:
+            return { kind: 'slot', label: 'Messages' };
+        case exports.SUBFLOW_IDS.TOOLS:
+            return { kind: 'slot', label: 'Tools' };
+        case exports.STAGE_IDS.CALL_LLM:
+        case exports.STAGE_IDS.MERGE_LLM:
+            return { kind: 'llm-turn', label: 'LLM turn' };
+        // Tool execution mounts under the bare branch key 'tool-calls'.
+        case 'tool-calls':
+        case exports.SUBFLOW_IDS.TOOL_CALLS:
+            return { kind: 'tool-call', label: 'Tool call' };
+        case exports.SUBFLOW_IDS.ROUTE:
+            return { kind: 'decision', label: 'Route' };
+        default:
+            return null;
+    }
+}
+exports.milestoneFor = milestoneFor;
 /**
  * Scope-key convention for context injections.
  *

package/dist/conventions.js.map

@@ -1 +1 @@
-{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../src/conventions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../src/conventions.ts"],"names":[],"mappings":"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"}

package/dist/core/Agent.js

@@ -20,19 +20,21 @@ const footprintjs_1 = require("footprintjs");
 const types_js_1 = require("../reliability/types.js");
 const extractSequence_js_1 = require("../security/extractSequence.js");
 const PolicyHaltError_js_1 = require("../security/PolicyHaltError.js");
-const CacheDecisionSubflow_js_1 = require("../cache/CacheDecisionSubflow.js");
 const CacheGateDecider_js_1 = require("../cache/CacheGateDecider.js");
 const strategyRegistry_js_1 = require("../cache/strategyRegistry.js");
 const conventions_js_1 = require("../conventions.js");
 const ContextRecorder_js_1 = require("../recorders/core/ContextRecorder.js");
+const ContextEvaluatedRecorder_js_1 = require("../recorders/core/ContextEvaluatedRecorder.js");
 const StreamRecorder_js_1 = require("../recorders/core/StreamRecorder.js");
 const AgentRecorder_js_1 = require("../recorders/core/AgentRecorder.js");
+const ErrorBridge_js_1 = require("../recorders/core/ErrorBridge.js");
 const CostRecorder_js_1 = require("../recorders/core/CostRecorder.js");
 const PermissionRecorder_js_1 = require("../recorders/core/PermissionRecorder.js");
 const EvalRecorder_js_1 = require("../recorders/core/EvalRecorder.js");
 const MemoryRecorder_js_1 = require("../recorders/core/MemoryRecorder.js");
 const SkillRecorder_js_1 = require("../recorders/core/SkillRecorder.js");
 const ToolsRecorder_js_1 = require("../recorders/core/ToolsRecorder.js");
+const ReliabilityRecorder_js_1 = require("../recorders/core/ReliabilityRecorder.js");
 const buildSystemPromptSlot_js_1 = require("./slots/buildSystemPromptSlot.js");
 const buildMessagesSlot_js_1 = require("./slots/buildMessagesSlot.js");
 const buildToolsSlot_js_1 = require("./slots/buildToolsSlot.js");
@@ -42,12 +44,12 @@ const runCheckpoint_js_1 = require("./runCheckpoint.js");
 const outputSchema_js_1 = require("./outputSchema.js");
 const RunnerBase_js_1 = require("./RunnerBase.js");
 const validators_js_1 = require("./agent/validators.js");
-const iterationStart_js_1 = require("./agent/stages/iterationStart.js");
 const route_js_1 = require("./agent/stages/route.js");
 const seed_js_1 = require("./agent/stages/seed.js");
 const callLLM_js_1 = require("./agent/stages/callLLM.js");
 const toolCalls_js_1 = require("./agent/stages/toolCalls.js");
 const buildAgentChart_js_1 = require("./agent/buildAgentChart.js");
+const buildDynamicAgentChart_js_1 = require("./agent/buildDynamicAgentChart.js");
 const buildToolRegistry_js_1 = require("./agent/buildToolRegistry.js");
 const AgentBuilder_js_1 = require("./agent/AgentBuilder.js");
 Object.defineProperty(exports, "AgentBuilder", { enumerable: true, get: function () { return AgentBuilder_js_1.AgentBuilder; } });
@@ -185,6 +187,14 @@ class Agent extends RunnerBase_js_1.RunnerBase {
     /** Per-COMPOSITION translator (L1b). Set from `opts.groupTranslator`;
      *  undefined when consumer didn't attach one. */
     agentGroupTranslator;
+    /** ReAct chart shape — 'flat' (default, bare call-llm stage) or
+     *  'subflow' (LLM turn wrapped in sf-llm-call). Set from
+     *  `opts.reactStructure`. */
+    reactStructure;
+    /** ReAct loop SEMANTICS — 'dynamic' (default, re-engineer all slots each
+     *  turn, loop→InjectionEngine) or 'classic' (engineer context once,
+     *  loop→Messages only). Set from `opts.reactMode`. See AgentOptions. */
+    reactMode;
     constructor(opts, systemPromptValue, registry, voice, injections = [], memories = [], outputSchemaParser, toolProvider, systemPromptCachePolicy = 'always', cachingDisabled = false, cacheStrategy, outputFallbackCfg, reliabilityConfig, thinkingHandlerValue, thinkingBudgetValue) {
         super();
         this.provider = opts.provider;
@@ -196,6 +206,8 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         this.maxIterations = (0, validators_js_1.clampIterations)(opts.maxIterations ?? 10);
         this.structureRecorders = opts.structureRecorders;
         this.agentGroupTranslator = opts.groupTranslator;
+        this.reactStructure = opts.reactStructure ?? 'flat';
+        this.reactMode = opts.reactMode ?? 'dynamic';
         this.systemPromptValue = systemPromptValue;
         this.systemPromptCachePolicy = systemPromptCachePolicy;
         this.cachingDisabledValue = cachingDisabled;
@@ -554,8 +566,14 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         const dispatcher = this.getDispatcher();
         const getRunCtx = () => this.currentRunContext;
         executor.attachCombinedRecorder(new ContextRecorder_js_1.ContextRecorder({ dispatcher, getRunContext: getRunCtx }));
+        // The InjectionEngine typedEmits context.evaluated; this bridge forwards it
+        // to the dispatcher (ContextRecorder handles the write-derived context.*).
+        executor.attachCombinedRecorder((0, ContextEvaluatedRecorder_js_1.contextEvaluatedRecorder)({ dispatcher, getRunContext: getRunCtx }));
         executor.attachCombinedRecorder((0, StreamRecorder_js_1.streamRecorder)({ dispatcher, getRunContext: getRunCtx }));
         executor.attachCombinedRecorder((0, AgentRecorder_js_1.agentRecorder)({ dispatcher, getRunContext: getRunCtx }));
+        // Terminal-failure bridge: footprintjs onRunFailed → typed error.fatal,
+        // so a thrown run clears in-flight live state + flips monitor status.
+        executor.attachCombinedRecorder((0, ErrorBridge_js_1.errorBridge)({ dispatcher, getRunContext: getRunCtx }));
         if (this.pricingTable) {
             executor.attachCombinedRecorder((0, CostRecorder_js_1.costRecorder)({ dispatcher, getRunContext: getRunCtx }));
         }
@@ -567,6 +585,9 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         executor.attachCombinedRecorder((0, MemoryRecorder_js_1.memoryRecorder)({ dispatcher, getRunContext: getRunCtx }));
         executor.attachCombinedRecorder((0, SkillRecorder_js_1.skillRecorder)({ dispatcher, getRunContext: getRunCtx }));
         executor.attachCombinedRecorder((0, ToolsRecorder_js_1.toolsRecorder)({ dispatcher, getRunContext: getRunCtx }));
+        // Reliability telemetry (rules-loop fail_fast / retried / recovered).
+        // Always-on, but zero-cost when no .reliability() config fires events.
+        executor.attachCombinedRecorder((0, ReliabilityRecorder_js_1.reliabilityRecorder)({ dispatcher, getRunContext: getRunCtx }));
         for (const r of this.attachedRecorders)
             executor.attachCombinedRecorder(r);
         return executor;
@@ -584,6 +605,8 @@ class Agent extends RunnerBase_js_1.RunnerBase {
         // and branch on `.kind`.
         if (this.reliabilityConfig !== undefined) {
             const snap = executor.getSnapshot();
+            // Read via Pick<AgentState, …> so the read shape cannot drift from
+            // the typed write side (the fields are declared once on AgentState).
             const state = snap.sharedState;
             if (state.reliabilityFailKind !== undefined) {
                 // Reconstruct the cause Error from the captured message+name —
@@ -718,8 +741,6 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             ...(this.externalToolProvider && { toolProvider: this.externalToolProvider }),
             ...(this.externalToolProvider && { providerToolCache }),
         });
-        // iterationStart extracted to ./agent/stages/iterationStart.ts (v2.11.2).
-        const iterationStart = iterationStart_js_1.iterationStartStage;
         // callLLM extracted to ./agent/stages/callLLM.ts (v2.11.2). Same
         // late-binding pattern as seed for toolSchemas (computed below).
         const callLLM = (0, callLLM_js_1.buildCallLLMStage)({
@@ -758,12 +779,13 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             ? (0, buildThinkingSubflow_js_1.buildThinkingSubflow)(this.thinkingHandler)
             : undefined;
         // Chart composition extracted to ./agent/buildAgentChart.ts (v2.11.2).
-        return (0, buildAgentChart_js_1.buildAgentChart)({
+        // The deps object is identical for both chart shapes — only the
+        // wiring differs (flat call-llm stage vs sf-llm-call subflow).
+        const chartDeps = {
             memories: this.memories,
             systemPromptCachePolicy,
             maxIterations,
             seed,
-            iterationStart,
             callLLM,
             routeDecider,
             toolCallsHandler,
@@ -772,13 +794,28 @@ class Agent extends RunnerBase_js_1.RunnerBase {
             messagesSubflow,
             toolsSubflow,
             ...(thinkingSubflow !== undefined && { thinkingSubflow }),
-            cacheDecisionSubflow: CacheDecisionSubflow_js_1.cacheDecisionSubflow,
             updateSkillHistoryStage: CacheGateDecider_js_1.updateSkillHistory,
-            cacheGateDecide: CacheGateDecider_js_1.cacheGateDecide,
+            // Gate the UpdateSkillHistory stage on skills being registered —
+            // same idiom buildToolRegistry uses to auto-attach `read_skill`.
+            hasSkills: this.injections.some((i) => i.flavor === 'skill'),
+            reactMode: this.reactMode,
             ...(this.structureRecorders !== undefined && {
                 structureRecorders: [...this.structureRecorders],
             }),
-        });
+        };
+        // `reactMode: 'classic'` engineers context ONCE and loops only Messages —
+        // it uses the flat builder's classic path (the subflow grouping is
+        // dynamic-only for now), so it takes precedence over reactStructure.
+        if (this.reactMode === 'classic') {
+            return (0, buildAgentChart_js_1.buildAgentChart)(chartDeps);
+        }
+        // `reactStructure: 'subflow'` (opt-in) wraps the LLM turn in an
+        // `sf-llm-call` subflow — same boundary LLMCall produces — so Lens /
+        // explainable-ui render it as an LLM group with slots inside. Default
+        // `'flat'` keeps the historical bare-stage shape. Behaviour identical.
+        return this.reactStructure === 'subflow'
+            ? (0, buildDynamicAgentChart_js_1.buildDynamicAgentChart)(chartDeps)
+            : (0, buildAgentChart_js_1.buildAgentChart)(chartDeps);
     }
 }
 exports.Agent = Agent;