agentfootprint 3.0.0 → 3.1.1

package/dist/types/conventions.d.ts

@@ -15,6 +15,10 @@ export declare const SUBFLOW_IDS: {
     /** Injection Engine subflow. Evaluates every Injection's trigger
      *  and writes activeInjections[] for the slot subflows to consume. */
     readonly 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. */
+    readonly LLM_CALL: "sf-llm-call";
     /** System-prompt slot subflow. Observed by ContextRecorder. */
     readonly SYSTEM_PROMPT: "sf-system-prompt";
     /** Messages slot subflow. */
@@ -33,8 +37,18 @@ export declare const SUBFLOW_IDS: {
      *  decider returns `'final'` as a routing value AND the same string
      *  becomes the subflow's id. */
     readonly 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. */
+    readonly 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. */
     readonly CACHE_DECISION: "sf-cache-decision";
     /** Thinking-normalization mount (v2.14). Wraps the consumer's
      *  ThinkingHandler.normalize() in a real footprintjs subflow so it
@@ -48,7 +62,24 @@ export type SubflowId = (typeof SUBFLOW_IDS)[keyof typeof SUBFLOW_IDS];
 /** Stage IDs — plain function stages that builders mount. */
 export declare const STAGE_IDS: {
     readonly 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. */
+    readonly 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. */
+    readonly CLIENT: "client";
     readonly 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." */
+    readonly EXTRACT_FINAL: "extract-final";
     readonly FINAL: "final";
     readonly FORMAT_MERGE: "format-merge";
     readonly MERGE_LLM: "merge-llm";
@@ -74,10 +105,79 @@ export type StageId = (typeof STAGE_IDS)[keyof typeof STAGE_IDS];
 export declare function isSlotSubflow(id: string): id is typeof SUBFLOW_IDS.SYSTEM_PROMPT | typeof SUBFLOW_IDS.MESSAGES | typeof SUBFLOW_IDS.TOOLS;
 /** Map a slot subflow id to its ContextSlot type. Undefined for non-slot ids. */
 export declare function slotFromSubflowId(id: string): ContextSlot | undefined;
+/**
+ * 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.
+ */
+export declare function slotFromRuntimeStageId(runtimeStageId: string): ContextSlot | undefined;
 /** True when an id is any of the library's known subflow IDs. */
 export declare function isKnownSubflow(id: string): id is SubflowId;
 /** True when an id is any of the library's known stage IDs. */
 export declare function isKnownStage(id: string): id is StageId;
+/**
+ * Semantic role of a stage, used by renderers to decide visual emphasis.
+ *
+ * The agent's chart mixes a handful of stages users actually care about
+ * (the HEROES — what context was built, what the model decided, what it did)
+ * with mechanism stages (PLUMBING). This is the ONE place that says which is
+ * which; renderers stay generic and style purely off this role (e.g. heroes
+ * prominent, plumbing muted). Keeping it here — the semantic owner — avoids
+ * the "name-based filter list duplicated across renderers" anti-pattern.
+ *
+ * - `hero-slot`   — a context slot (system-prompt / messages / tools)
+ * - `hero-llm`    — the LLM invocation
+ * - `hero-action` — tool execution (the agent's actions)
+ * - `plumbing`    — mechanism (injection engine, cache, route, thinking, …)
+ * - `boundary`    — neutral chart boundaries (Initialize root, Final) +
+ *                   anything unrecognised (rendered normally, never muted)
+ */
+export type StageRole = 'hero-slot' | 'hero-llm' | 'hero-action' | 'plumbing' | 'boundary';
+/**
+ * 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.
+ */
+export declare function stageRole(id: string): StageRole;
+/**
+ * A {@link Milestone}'s kind — the domain vocabulary for "meaningful step you'd
+ * scrub to" in the agent's run.
+ */
+export type MilestoneKind = 'iteration' | 'slot' | 'llm-turn' | 'tool-call' | 'decision';
+/**
+ * A time-travel milestone: a domain-declared scrub stop. Conceptually each
+ * milestone marks the boundary of a COLLECTION of commits (the commits that
+ * belong to that step) — so the Lens slider can step stage-by-stage
+ * (iteration → llm-turn → tool-call → …) instead of stopping only on
+ * structural subflow boundaries. The renderer iterates whatever the domain
+ * classifies; it never hardcodes agent vocabulary.
+ */
+export interface Milestone {
+    readonly kind: MilestoneKind;
+    /** Human-readable base label ("LLM turn"); the renderer may add an ordinal. */
+    readonly label: string;
+}
+/**
+ * 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.
+ */
+export declare function milestoneFor(id: string): Milestone | null;
 /**
  * Scope-key convention for context injections.
  *

package/dist/types/conventions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conventions.d.ts","sourceRoot":"","sources":["../../src/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,gEAAgE;AAChE,eAAO,MAAM,WAAW;IACtB;0EACsE;;IAEtE,+DAA+D;;IAE/D,6BAA6B;;IAE7B,0BAA0B;;IAE1B,2CAA2C;;IAE3C,uDAAuD;;IAEvD,kCAAkC;;IAElC;;;;oCAIgC;;IAEhC;wDACoD;;IAEpD;;;;;iCAK6B;;CAErB,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEvE,6DAA6D;AAC7D,eAAO,MAAM,SAAS;;;;;;;IAOpB;wCACoC;;IAEpC;gEAC4D;;IAE5D;4EACwE;;IAExE;kEAC8D;;IAE9D;8CAC0C;;CAElC,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAIjE,wEAAwE;AACxE,wBAAgB,aAAa,CAC3B,EAAE,EAAE,MAAM,GACT,EAAE,IAAI,OAAO,WAAW,CAAC,aAAa,GAAG,OAAO,WAAW,CAAC,QAAQ,GAAG,OAAO,WAAW,CAAC,KAAK,CAIjG;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAgBrE;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,SAAS,CAE1D;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,OAAO,CAEtD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEhF,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,CAS9F;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,YAAY,CAE/D"}
+{"version":3,"file":"conventions.d.ts","sourceRoot":"","sources":["../../src/conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,gEAAgE;AAChE,eAAO,MAAM,WAAW;IACtB;0EACsE;;IAEtE;;qDAEiD;;IAEjD,+DAA+D;;IAE/D,6BAA6B;;IAE7B,0BAA0B;;IAE1B,2CAA2C;;IAE3C,uDAAuD;;IAEvD,kCAAkC;;IAElC;;;;oCAIgC;;IAEhC;;;;;;gCAM4B;;IAE5B;;;wDAGoD;;IAEpD;;;;;iCAK6B;;CAErB,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAEvE,6DAA6D;AAC7D,eAAO,MAAM,SAAS;;IAEpB;;;;;0EAKsE;;IAEtE;;;yDAGqD;;;IAGrD;;;8DAG0D;;;;;;IAM1D;wCACoC;;IAEpC;gEAC4D;;IAE5D;4EACwE;;IAExE;kEAC8D;;IAE9D;8CAC0C;;CAElC,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAIjE,wEAAwE;AACxE,wBAAgB,aAAa,CAC3B,EAAE,EAAE,MAAM,GACT,EAAE,IAAI,OAAO,WAAW,CAAC,aAAa,GAAG,OAAO,WAAW,CAAC,QAAQ,GAAG,OAAO,WAAW,CAAC,KAAK,CAIjG;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAgBrE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,cAAc,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAStF;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,SAAS,CAE1D;AAED,+DAA+D;AAC/D,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,OAAO,CAEtD;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,GAAG,UAAU,CAAC;AA6B3F;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAY/C;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,MAAM,GAAG,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;AAEzF;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAiCzD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,OAAO,cAAc,CAAC,CAAC;AAEhF,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG,UAAU,GAAG,OAAO,GAAG,YAAY,CAS9F;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,IAAI,YAAY,CAE/D"}

package/dist/types/core/Agent.d.ts

@@ -145,6 +145,14 @@ export declare class Agent extends RunnerBase<AgentInput, AgentOutput> {
     /** Per-COMPOSITION translator (L1b). Set from `opts.groupTranslator`;
      *  undefined when consumer didn't attach one. */
     private readonly agentGroupTranslator?;
+    /** ReAct chart shape — 'flat' (default, bare call-llm stage) or
+     *  'subflow' (LLM turn wrapped in sf-llm-call). Set from
+     *  `opts.reactStructure`. */
+    private readonly 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. */
+    private readonly reactMode;
     constructor(opts: AgentOptions, systemPromptValue: string, registry: readonly ToolRegistryEntry[], voice: {
         readonly appName: string;
         readonly commentaryTemplates: Readonly<Record<string, string>>;

package/dist/types/core/Agent.d.ts.map

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

package/dist/types/core/LLMCall.d.ts

@@ -1,15 +1,42 @@
 /**
- * LLMCall — the leaf primitive for a single LLM invocation (no tools, no loop).
+ * LLMCall — the leaf primitive for a single LLM invocation (no tools).
  *
  * Pattern: Builder (GoF) → produces a Runner backed by a footprintjs FlowChart.
- * Role:    Layer-5 primitive (core/). Uses the 3-slot model internally:
- *            Seed → sf-system-prompt → sf-messages → sf-tools → call-llm
- *          Slot subflows write convention-keyed injections observed by
- *          ContextRecorder. The call-llm stage typedEmits stream.llm_start
- *          and stream.llm_end observed by StreamRecorder.
- * Emits:   Through its internally-attached recorders:
- *            agentfootprint.stream.llm_start / llm_end
- *            agentfootprint.context.injected / slot_composed
+ *
+ * Chart shape — outer client wrapper around an inner llm-subflow:
+ *
+ *     Client → sf-llm-call → loopTo(client)
+ *
+ *   Outer `Client` stage:
+ *     - First visit: receives args, writes userMessage to scope.
+ *     - Second visit (after the loop completes): $break()s with
+ *       scope.answer as the chart's TraversalResult.
+ *
+ *   Inner `sf-llm-call` subflow (drill-down view):
+ *     Initialize → sf-system-prompt → sf-messages → call-llm
+ *          → [sf-thinking if handler]  → extract-final
+ *
+ *   NO `sf-tools` slot — LLMCall has no tools by design (that's Agent's
+ *   territory). Atomic LLMCall's lens chart is a clean 3-node top-level
+ *   view (Client + LLM + loop edge) that drills into the real flowchart
+ *   below.
+ *
+ *   Loop semantics: LLMCall is one-shot. The loop fires once; the
+ *   second Client visit immediately breaks. The shape is identical to
+ *   chat-mode (future): swap `$break()` for `pause()` and the same
+ *   chart supports multi-turn conversation.
+ *
+ * Slot subflows write convention-keyed injections observed by
+ * ContextRecorder. The call-llm stage typedEmits stream.llm_start
+ * and stream.llm_end observed by StreamRecorder. When a
+ * `ThinkingHandler` resolves for the provider, `sf-thinking` mounts
+ * automatically (auto-wired by provider.name — same convention Agent
+ * uses).
+ *
+ * Emits (through internally-attached recorders):
+ *     agentfootprint.stream.llm_start / llm_end
+ *     agentfootprint.context.injected / slot_composed
+ *     agentfootprint.stream.thinking_end (when sf-thinking mounted)
  */
 import { type FlowchartCheckpoint, type RunOptions, type StructureRecorder } from 'footprintjs';
 import type { GroupMetadata, GroupTranslator } from './translator.js';
@@ -45,7 +72,7 @@ export interface LLMCallOptions {
      * Optional build-time recorders threaded into footprintjs's
      * `flowChart()` factory. Each recorder observes per-node build
      * events (`onStageAdded` / `onSubflowMounted` / etc.) for this
-     * LLMCall's internal chart (Seed + slot mounts + CallLLM). When
+     * LLMCall's internal chart (Initialize + slot mounts + CallLLM). When
      * omitted, no build-time observation is wired up.
      */
     readonly structureRecorders?: readonly StructureRecorder[];
@@ -76,14 +103,23 @@ export declare class LLMCall extends RunnerBase<LLMCallInput, LLMCallOutput> {
     private readonly costBudget?;
     private readonly structureRecorders?;
     private readonly groupTranslator?;
+    /** Auto-resolved from provider.name at construction time (same
+     *  convention Agent uses — see findThinkingHandler). When undefined,
+     *  sf-thinking is NOT mounted and the chart has zero thinking
+     *  overhead (build-time conditional mount). */
+    private readonly thinkingHandler?;
     private currentRunContext;
     constructor(opts: LLMCallOptions, systemPromptValue: string);
     static create(opts: LLMCallOptions): LLMCallBuilder;
     protected getGroupTranslator(): GroupTranslator | undefined;
     /** LLMCall has no nested-runner members (slots are subflows of
-     *  the LLMCall's own chart, not Runner instances). The 3 slot ids
+     *  the LLMCall's own chart, not Runner instances). The slot ids
      *  are surfaced via `extra` so Lens can render the slot cards
-     *  inside an LLMCall card without inspecting `buildTimeStructure`. */
+     *  inside an LLMCall card without inspecting `buildTimeStructure`.
+     *
+     *  TWO slots only — LLMCall does not have tools (that's Agent's
+     *  affordance). Atomic LLMCall renders as a clean 2-pill card in
+     *  collapsed (top-level) view. */
     protected buildUIGroupMetadata(): GroupMetadata;
     run(input: LLMCallInput, options?: RunOptions): Promise<LLMCallOutput | RunnerPauseOutcome>;
     resume(checkpoint: FlowchartCheckpoint, input?: unknown, options?: RunOptions): Promise<LLMCallOutput | RunnerPauseOutcome>;

package/dist/types/core/LLMCall.d.ts.map

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

package/dist/types/core/RunnerBase.d.ts

@@ -65,6 +65,18 @@ export declare abstract class RunnerBase<TIn = unknown, TOut = unknown> implemen
      * across multi-turn reuse of the same runner instance).
      */
     getLastSnapshot(): ReturnType<FlowChartExecutor['getSnapshot']> | undefined;
+    /**
+     * Alias for `getLastSnapshot()` that mirrors `FlowChartExecutor.getSnapshot()`
+     * so consumers (lens, playground, ExplainableShell) can read the live or
+     * just-completed snapshot through the same method name they'd use on a
+     * footprintjs executor — without having to know whether they're holding
+     * an agentfootprint Runner or a raw executor.
+     *
+     * During an active run, returns the live snapshot (commit log + execution
+     * tree built incrementally as stages execute). Between runs, returns the
+     * last completed run's snapshot. Undefined before any run has started.
+     */
+    getSnapshot(): ReturnType<FlowChartExecutor['getSnapshot']> | undefined;
     /**
      * Return the footprintjs FlowChart for this runner — the canonical
      * design-time blueprint. STABLE REFERENCE across calls (`getSpec()

package/dist/types/core/RunnerBase.d.ts.map

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

package/dist/types/core/agent/buildAgentChart.d.ts

@@ -15,27 +15,27 @@
  *
  * Chart shape:
  *
- *     Seed
+ *     Initialize
  *       → [memory READ subflows for each .memory()]
- *       → InjectionEngine (subflow)
- *       → SystemPrompt (slot subflow)
- *       → Messages (slot subflow)
- *       → Tools (slot subflow)
- *       → CacheDecision (subflow)
+ *       → InjectionEngine (subflow)               ← loop target (tool-calls loops here)
+ *       → Context (selector, PARALLEL fan-out, failFast)
+ *             ⇉ {System Prompt ‖ Messages ‖ Tools}  (slot subflows)
+ *             → converge
  *       → UpdateSkillHistory
- *       → CacheGate (decider) → ApplyMarkers / SkipCaching
- *       → IterationStart
- *       → CallLLM
- *       → Route (decider) → tool-calls (pausable) / final (subflow)
- *                                                        |
- *                          ┌────── PrepareFinal           ▼
+ *       → Cache (sf-cache subflow: decideCacheMarkers → CacheGate
+ *                → ApplyMarkers / SkipCaching)
+ *       → CallLLM (also emits the per-iteration iteration_start marker)
+ *       → [NormalizeThinking] (subflow, only when a ThinkingHandler resolved)
+ *       → Route (decider)
+ *             ├─ tool-calls (pausable) → loopTo(InjectionEngine)   ← branch-sourced loop
+ *             └─ final (subflow) → terminal leaf
+ *                          ┌────── PrepareFinal
  *                          ├──── [memory WRITE subflows]
  *                          └──── BreakFinal ($break)
- *       loopTo(InjectionEngine)
  *
  * (When v2.11.x reliability is configured, the reliability gate chart
- * mounts as a subflow between IterationStart and CallLLM with a
- * TranslateFailFast stage after it. Lands in the next commit.)
+ * mounts as a subflow before CallLLM with a TranslateFailFast stage
+ * after it. Lands in the next commit.)
  */
 import type { FlowChart, StructureRecorder } from 'footprintjs';
 import type { CachePolicy } from '../../cache/types.js';
@@ -55,7 +55,6 @@ export interface AgentChartDeps {
      *  inputMapper for max-iteration policies. */
     readonly maxIterations: number;
     readonly seed: (scope: never) => void;
-    readonly iterationStart: (scope: never) => void;
     readonly callLLM: (scope: never) => Promise<void>;
     readonly routeDecider: (scope: never) => 'tool-calls' | 'final';
     readonly toolCallsHandler: import('footprintjs').PausableHandler<never>;
@@ -71,9 +70,23 @@ export interface AgentChartDeps {
      * zero overhead for non-thinking agents (build-time conditional mount).
      */
     readonly thinkingSubflow?: FlowChart;
-    readonly cacheDecisionSubflow: FlowChart;
     readonly updateSkillHistoryStage: (scope: never) => void;
-    readonly cacheGateDecide: (scope: never) => unknown;
+    /**
+     * Whether ≥1 Skill is registered. The `UpdateSkillHistory` stage (and
+     * therefore the cache's skill-churn rule) is mounted ONLY when true:
+     * with no skills the window would record "no skill" every iteration and
+     * `detectSkillChurn` could never fire, so the stage would be pure dead
+     * weight + a misleading box. Mirrors the `skills.length > 0` gate that
+     * auto-attaches `read_skill`, and the `thinkingSubflow` conditional mount.
+     */
+    readonly hasSkills: boolean;
+    /**
+     * ReAct loop semantics. `'dynamic'` (default) re-runs the InjectionEngine +
+     * all 3 slots every iteration (loop → InjectionEngine). `'classic'`
+     * engineers context ONCE (InjectionEngine + system-prompt + tools up front)
+     * and loops only the Messages slot (loop → Messages). See AgentOptions.reactMode.
+     */
+    readonly reactMode?: 'classic' | 'dynamic';
     /** Structure recorders threaded into both `flowChart()` calls (the
      *  main chart and the PrepareFinal sub-chart). Each recorder
      *  observes per-node build events (`onStageAdded` /

package/dist/types/core/agent/buildAgentChart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"buildAgentChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildAgentChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAQrE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAE/C;uEACmE;IACnE,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC;IAE9C;kDAC8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAG/B,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAChD,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,YAAY,GAAG,OAAO,CAAC;IAChE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,aAAa,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAGxE,QAAQ,CAAC,sBAAsB,EAAE,SAAS,CAAC;IAC3C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC;IAGrC,QAAQ,CAAC,oBAAoB,EAAE,SAAS,CAAC;IACzC,QAAQ,CAAC,uBAAuB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACzD,QAAQ,CAAC,eAAe,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IAGpD;;;;0CAIsC;IACtC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CA0P/D"}
+{"version":3,"file":"buildAgentChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildAgentChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAc,MAAM,aAAa,CAAC;AAE5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AASrE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAE/C;uEACmE;IACnE,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC;IAE9C;kDAC8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAG/B,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,YAAY,GAAG,OAAO,CAAC;IAChE,QAAQ,CAAC,gBAAgB,EAAE,OAAO,aAAa,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;IAGxE,QAAQ,CAAC,sBAAsB,EAAE,SAAS,CAAC;IAC3C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,CAAC;IACxC,QAAQ,CAAC,eAAe,EAAE,SAAS,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC;IAMrC,QAAQ,CAAC,uBAAuB,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAEzD;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAG3C;;;;0CAIsC;IACtC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC5D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAqT/D"}

package/dist/types/core/agent/buildAgentMessageApiChart.d.ts

@@ -0,0 +1,41 @@
+/**
+ * buildAgentMessageApiChart — the Agent (ReAct) form of the messageAPI
+ * merge-tree, as ONE FLAT main chart (no inner LLM-call sub-box).
+ *
+ * The whole ReAct cycle lives directly in the single Agent chart:
+ *
+ *   Context (ROOT selector — inits + picks which context slots to engineer)
+ *     ├─ system-prompt ┐
+ *     ├─ messages ─────┼─→ messageAPI → Call-LLM
+ *     └─ tools ────────┘
+ *        → Route (decider) → [ ToolCalls (execute) → loop ] / Final (response)
+ *   loopTo(Context)
+ *
+ * WHY flat (the user's call): the entire agent — context engineering, the LLM
+ * call, routing, tool execution, the loop, and the final response — is ONE
+ * visible flowchart in ONE Agent box. No nested LLM-call box: Lens wraps the
+ * whole chart in the Agent main-box and renders the slots as pills. This is
+ * simpler than the composed (sf-llm-call subflow) shape and avoids box-in-box
+ * nesting entirely.
+ *
+ * The three context slots are DIRECT children of Context; all converge at
+ * messageAPI (which assembles system-prompt + messages); Call-LLM then sends
+ * the assembled payload plus the tool schemas. Route decides tool-calls (loop)
+ * vs final (terminate). The same chart serves Static and Dynamic agents — only
+ * which slots the Context selector lights per iteration differs.
+ */
+import type { FlowChart } from 'footprintjs';
+import type { LLMProvider, LLMToolSchema } from '../../adapters/types.js';
+export interface AgentMessageApiChartDeps {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    readonly systemPrompt: string;
+    readonly tools: readonly LLMToolSchema[];
+    readonly maxIterations?: number;
+    readonly structureRecorders?: readonly import('footprintjs').StructureRecorder[];
+}
+/**
+ * Build the Agent merge-tree chart as one flat ReAct flowchart.
+ */
+export declare function buildAgentMessageApiChart(deps: AgentMessageApiChartDeps): FlowChart;
+//# sourceMappingURL=buildAgentMessageApiChart.d.ts.map

package/dist/types/core/agent/buildAgentMessageApiChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildAgentMessageApiChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildAgentMessageApiChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAc,WAAW,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AA8BtF,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,OAAO,aAAa,EAAE,iBAAiB,EAAE,CAAC;CAClF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,wBAAwB,GAAG,SAAS,CA8LnF"}

package/dist/types/core/agent/buildCacheSubflow.d.ts

@@ -0,0 +1,36 @@
+/**
+ * buildCacheSubflow — the per-turn prompt-cache decision, as ONE subflow.
+ *
+ * Collapses the cache machinery into a single `sf-cache` boundary so the
+ * agent chart reads cleanly (one "Cache" box you can drill into) while the
+ * execution tree stays honest:
+ *
+ *     decideCacheMarkers  →  CacheGate (decider)  →  ApplyMarkers / SkipCaching
+ *
+ * Layering (see src/cache/types.ts):
+ *   - This subflow is the provider-AGNOSTIC DECISION layer — it only computes
+ *     and gates provider-neutral `CacheMarker[]`. It knows nothing about any
+ *     provider.
+ *   - The provider-SPECIFIC MECHANISM (Anthropic `cache_control`, OpenAI
+ *     automatic, …) is the attached provider's `CacheStrategy`, selected by
+ *     `provider.name`, applied later when the request is built.
+ *
+ * Why `UpdateSkillHistory` is NOT in here: the `skillHistory` rolling window
+ * must persist across loop iterations. Keeping `UpdateSkillHistory` in the
+ * main loop (just before this subflow) lets `skillHistory` live in the parent
+ * scope without round-tripping through this subflow's in/out mappers — the
+ * subflow stays pure (reads the turn's state, writes only `cacheMarkers`).
+ *
+ * Deps-free: every input (`activeInjections`, `iteration`, `skillHistory`,
+ * `recentHitRate`, `systemPromptCachePolicy`, …) is supplied by the PARENT's
+ * `inputMapper` at the mount site; the output is just `cacheMarkers`.
+ */
+import { type FlowChart } from 'footprintjs';
+/**
+ * Build the `sf-cache` subflow chart. Called by `buildAgentChart` and
+ * `buildDynamicAgentChart` and mounted via `addSubFlowChartNext(
+ * SUBFLOW_IDS.CACHE, buildCacheSubflow(), 'Cache', { inputMapper,
+ * outputMapper, arrayMerge: Replace })`.
+ */
+export declare function buildCacheSubflow(): FlowChart;
+//# sourceMappingURL=buildCacheSubflow.d.ts.map

package/dist/types/core/agent/buildCacheSubflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildCacheSubflow.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildCacheSubflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAMxD;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,SAAS,CAqC7C"}

package/dist/types/core/agent/buildDynamicAgentChart.d.ts

@@ -0,0 +1,57 @@
+/**
+ * buildDynamicAgentChart — the Dynamic-ReAct agent chart, where the
+ * whole LLM turn (context engineering + the call) is ONE `sf-llm-call`
+ * subflow, exactly like the `LLMCall` primitive produces.
+ *
+ * WHY a second builder (vs `buildAgentChart`)
+ * ───────────────────────────────────────────
+ * `buildAgentChart` mounts the LLM as a flat `call-llm` STAGE with the
+ * slot subflows as its siblings. That renders as nothing in Lens — a
+ * bare stage is dropped by the subflow-level collapser, so the slots
+ * have no LLM card to fold into and the chart comes up empty.
+ *
+ * This builder wraps that same region in an `sf-llm-call` SUBFLOW. The
+ * payoff is purely structural — Lens already maps `sf-llm-call → LLM
+ * group` (same boundary `LLMCall` produces), so the Dynamic agent
+ * renders as an LLM group with its slots inside, a peer Tool node, and
+ * the loop arc, with ZERO Lens-specific special-casing.
+ *
+ * The data flow is IDENTICAL to `buildAgentChart` — every stage handler
+ * + slot subflow is reused verbatim from the same `AgentChartDeps`. The
+ * ONLY new thing is the subflow boundary, which means:
+ *
+ *   • A small inner seed (`dynamicTurnSeed`) initialises the per-turn
+ *     working keys the OUTER seed used to set, since the inner subflow
+ *     gets a fresh scope each loop re-entry.
+ *   • Cross-iteration accumulators (token totals, cost counters,
+ *     skill-history) round-trip out→in: the boundary `outputMapper`
+ *     bubbles them to the outer scope, and the next iteration's
+ *     `inputMapper` feeds them back under `prior*` aliases (because
+ *     keys passed via `inputMapper` are FROZEN inside the subflow —
+ *     `ScopeFacade.setValue` throws on them — so the writable working
+ *     key must have a different name from the read-only input).
+ *
+ * Chart shape (mirrors the diagram the team locked):
+ *
+ *     Initialize
+ *       → [memory READ subflows]
+ *       → sf-llm-call  (SUBFLOW — same boundary LLMCall produces)
+ *           dynamicTurnSeed → InjectionEngine
+ *           → Context (selector, PARALLEL fan-out, failFast)
+ *               ⇉ {System Prompt ‖ Messages ‖ Tools} → converge
+ *           → UpdateSkillHistory → Cache (sf-cache subflow)
+ *           → CallLLM (emits iteration_start) → [NormalizeThinking]
+ *       → Route (decider)
+ *            ├─ tool-calls (pausable) → loopTo(sf-llm-call)   ← branch-sourced loop
+ *            └─ sf-final (the answer) → terminal leaf
+ *
+ * Classic ReAct keeps using `buildAgentChart` until its own shape is
+ * designed — this builder is Dynamic-only.
+ */
+import type { FlowChart } from 'footprintjs';
+import type { AgentChartDeps } from './buildAgentChart.js';
+/**
+ * Build the Dynamic-ReAct agent chart from the shared `AgentChartDeps`.
+ */
+export declare function buildDynamicAgentChart(deps: AgentChartDeps): FlowChart;
+//# sourceMappingURL=buildDynamicAgentChart.d.ts.map

package/dist/types/core/agent/buildDynamicAgentChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildDynamicAgentChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildDynamicAgentChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AAUzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAgD3D;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,cAAc,GAAG,SAAS,CAkTtE"}

package/dist/types/core/agent/buildMessageApiChart.d.ts

@@ -0,0 +1,48 @@
+/**
+ * buildMessageApiChart — PROOF of the locked "messageAPI merge-tree" shape
+ * (MENTAL_MODEL.md ★ LOCKED DESIGN), LLM-only (no tools subflow yet).
+ *
+ * This is Step 1 of the agreed build order: prove the Context-selector →
+ * slot subflows → messageAPI stage → Call-LLM tree works + renders, BEFORE
+ * bringing it to the Agent (Step 2 adds the tools subflow + the loop).
+ *
+ * Chart shape (LLM-only):
+ *
+ *     Seed
+ *       → Context (SELECTOR stage — picks which slots to engineer)
+ *           ├─ sf-system-prompt ┐   (selected branches run in parallel)
+ *           └─ sf-messages ──────┴─→ messageAPI stage   (the join point)
+ *       → Call-LLM
+ *
+ * WHY a selector (not a plain fork): "Context = Selector stage" — it RETURNS
+ * the list of slot branch ids to engineer this iteration, and `select()`
+ * captures evidence (which slots + why). That is what will unify Static and
+ * Dynamic agent in ONE chart later: Static picks only `messages` per loop;
+ * Dynamic also picks `system-prompt` (and `tools`) when they re-engineer.
+ * The picked-set IS the lit/unlit-pill signal. For this LLM-only proof the
+ * selector picks BOTH slots (a one-shot call engineers everything once).
+ *
+ * WHY messageAPI is a REAL stage: it assembles the LLM request bulk that the
+ * agent's `callLLM` builds invisibly today (callLLM.ts:132) — `systemPrompt`
+ * (separate field) + `messages` (the conversation, incl. tool-results) → the
+ * message-API payload. Making it a stage makes that assembly visible +
+ * inspectable in Lens/Trace. (Tools is a separate field added at Call-LLM —
+ * it joins in Step 2.)
+ *
+ * Slots are REAL subflows (reused verbatim: buildSystemPromptSlot /
+ * buildMessagesSlot) writing the convention INJECTION_KEYS, so ContextRecorder
+ * emits context.injected and Lens renders them — no bespoke collapser.
+ */
+import type { FlowChart } from 'footprintjs';
+import type { LLMProvider } from '../../adapters/types.js';
+export interface MessageApiChartDeps {
+    readonly provider: LLMProvider;
+    readonly model: string;
+    readonly systemPrompt: string;
+    readonly structureRecorders?: readonly import('footprintjs').StructureRecorder[];
+}
+/**
+ * Build the LLM-only messageAPI merge-tree chart.
+ */
+export declare function buildMessageApiChart(deps: MessageApiChartDeps): FlowChart;
+//# sourceMappingURL=buildMessageApiChart.d.ts.map

package/dist/types/core/agent/buildMessageApiChart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildMessageApiChart.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/buildMessageApiChart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAuBvE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,OAAO,aAAa,EAAE,iBAAiB,EAAE,CAAC;CAClF;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,mBAAmB,GAAG,SAAS,CA8HzE"}

package/dist/types/core/agent/stages/callLLM.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"callLLM.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/callLLM.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAEV,WAAW,EAGX,aAAa,EACb,YAAY,EACb,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAI1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAMnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;qDACiD;IACjD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;;sEAEkE;IAClE,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C;;;;;uBAKmB;IACnB,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;IACzC;;;;;;oCAMgC;IAChC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC1D;;yDAEqD;IACrD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,GACrB,CAAC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAwMlD"}
+{"version":3,"file":"callLLM.d.ts","sourceRoot":"","sources":["../../../../../src/core/agent/stages/callLLM.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAEV,WAAW,EAGX,aAAa,EACb,YAAY,EACb,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAI1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAqB,KAAK,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAMnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qCAAqC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;IACrC,2CAA2C;IAC3C,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;qDACiD;IACjD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC;;sEAEkE;IAClE,QAAQ,CAAC,WAAW,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C;;;;;uBAKmB;IACnB,QAAQ,CAAC,WAAW,CAAC,EAAE,iBAAiB,CAAC;IACzC;;;;;;oCAMgC;IAChC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC1D;;yDAEqD;IACrD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,GACrB,CAAC,KAAK,EAAE,UAAU,CAAC,UAAU,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAoNlD"}