agentfootprint 8.6.0 → 8.7.0

package/dist/types/lib/injection-engine/skillGraph.d.ts

@@ -50,6 +50,7 @@ import type { Injection, InjectionContext } from './types.js';
 import type { Embedder } from '../../memory/embedding/types.js';
 import type { EntryScore, EntryScoring, EntryScorer } from './entryScorer.js';
 import { type GraphCheckup } from './skillGraphCheckup.js';
+export { formatCheckup } from './skillGraphCheckup.js';
 export type { GraphCheckup, GraphProblem, GraphProblemCode } from './skillGraphCheckup.js';
 /** How `.build({ check })` reacts to the graph check-up. */
 export type GraphCheckMode = 'throw' | 'warn' | 'off';
@@ -60,9 +61,36 @@ export interface BuildOptions {
      *   • `'throw'` — throw if any ERROR-level problem (unknown-skill / no-entry);
      *   • `'warn'`  — console.warn every problem in dev mode (`enableDevMode()`), silent otherwise;
      *   • `'off'`   — skip it entirely.
-     * Default `'warn'`. `graph.checkup()` is always available regardless.
+     *
+     * **Default `'throw'` since 8.7.0** (was `'warn'`), matching the object-literal
+     * form. A graph with an error-level problem cannot start a turn at all, and under
+     * the old default it built silently outside dev mode and failed at run time
+     * instead. `'warn'` still means exactly what it says — never throws — so an
+     * explicit `check: 'warn'` keeps the old soft behavior.
+     *
+     * `graph.checkup()` is always available regardless.
      */
     readonly check?: GraphCheckMode;
+    /**
+     * Tool names the AGENT exposes to every skill (`.tool()` / `.tools()` / a baseline
+     * `ToolProvider`). Without them the skill-body contract check reads a body's
+     * `lookup_order(id)` as a typo, because the graph only knows the tools its own
+     * skills carry. Same field as `checkup({ knownTools })` — see `SkillGraph.checkup`.
+     */
+    readonly knownTools?: readonly string[];
+}
+/** Options for `graph.checkup()`. */
+export interface CheckupOptions {
+    /**
+     * Tool names the AGENT exposes to every skill — `.tool()` / `.tools()`
+     * registrations and any always-on `ToolProvider`. A skill body may name them
+     * freely: they are callable from every skill, so they are neither `body-unknown-tool`
+     * (they exist) nor `body-foreign-tool` (they are not somebody else's).
+     *
+     * @example
+     *   graph.checkup({ knownTools: ['lookup_order', 'list_skills'] });
+     */
+    readonly knownTools?: readonly string[];
 }
 /** Where a turn starts, in the object-literal (flat) form. */
 export type SkillGraphStart = string | {
@@ -102,7 +130,12 @@ export interface SkillGraphFlatConfig {
     /** Tool-result transitions; `from`/`to` are skill ids resolved against `skills`. */
     readonly steps?: readonly SkillGraphStep[];
     readonly tree?: never;
+    /** `tree`-only (there are no leaves to scope here) — typed `never` so the
+     *  contradiction is a compile error, the same way `tree` is on this arm. */
+    readonly scopeTools?: never;
     readonly check?: GraphCheckMode;
+    /** Baseline agent tool names — see {@link BuildOptions.knownTools}. */
+    readonly knownTools?: readonly string[];
 }
 /**
  * Object-literal form, TREE arm — a decision tree owns the routing, so there is
@@ -115,9 +148,18 @@ export interface SkillGraphTreeConfig {
     readonly skills: readonly Injection[];
     /** A decision tree (instead of `start` + `steps`). */
     readonly tree: DecisionNode | Injection;
+    /**
+     * Scope each leaf's tools to the routed leaf. The object form's half of
+     * `.tree(root, { scopeTools })` — added in 8.7.0, because until then this form
+     * hard-coded `true` and the fluent form's only opt-out had no object-form twin.
+     * Default `true`. See {@link TreeOptions.scopeTools}.
+     */
+    readonly scopeTools?: boolean;
     readonly start?: never;
     readonly steps?: never;
     readonly check?: GraphCheckMode;
+    /** Baseline agent tool names — see {@link BuildOptions.knownTools}. */
+    readonly knownTools?: readonly string[];
 }
 /**
  * Object-literal form of a skill graph — an alternative to the fluent builder.
@@ -299,6 +341,14 @@ export interface SkillGraph {
      * route triggers and the agent loop's cursor-update stage, so the two can never
      * disagree. Flat entry/route graphs only; a decision `tree()` routes per-iteration
      * by predicate (no cursor) and returns the unchanged `ctx.currentSkillId`.
+     *
+     * **The cursor is PER RUN.** It describes where the graph is inside ONE
+     * `agent.run()`, across that run's iterations. A second `run()` on the same agent
+     * starts cold — at the entry — whatever skill the first run ended on: a skill graph
+     * is a per-turn state machine, not conversation memory, and `currentSkillId` lives
+     * in the run's own state. To resume where the last turn stopped, persist the id
+     * yourself and start the next turn's graph from it (`start: { rules: [...] }`);
+     * nothing in the graph will carry it across for you.
      */
     nextSkill(ctx: InjectionContext): string | undefined;
     /**
@@ -347,10 +397,21 @@ export interface SkillGraph {
     /**
      * Build-time check-up — inspect the declared graph for wiring mistakes (a skill
      * nobody can reach, an edge to an unknown skill, two un-prioritized edges from one
-     * skill, no entry, a self-loop). Pure + side-effect-free; call it whenever.
-     * `ok` is false iff there's an error-level problem (`unknown-skill` / `no-entry`).
+     * skill, no entry, a self-loop, an entry menu with no way to choose from it, a
+     * transition the cold-start cursor can never take). Pure + side-effect-free; call
+     * it whenever. `ok` is false iff there's an error-level problem (`unknown-skill` /
+     * `no-entry`) — everything else is a warning, because a graph the model can still
+     * navigate is not a broken graph.
+     *
+     * Pass `knownTools` when the agent registers baseline tools with `.tool()`: the
+     * graph only knows the tools its own skills carry, so without them a body that
+     * says `lookup_order(id)` is reported as naming a tool that exists nowhere.
+     *
+     * @example
+     *   const report = graph.checkup({ knownTools: ['lookup_order'] });
+     *   if (!report.ok) throw new Error(formatCheckup(report));
      */
-    checkup(): GraphCheckup;
+    checkup(options?: CheckupOptions): GraphCheckup;
 }
 export interface SkillGraphBuilder {
     /** Mark a skill as reachable at turn start (optionally intent-conditional). */

package/dist/types/lib/injection-engine/skillGraph.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skillGraph.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/skillGraph.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skillGraph.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/skillGraph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAoB,MAAM,YAAY,CAAC;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE9E,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE3F,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAEtD,8BAA8B;AAC9B,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GACvB,MAAM,GACN;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACxB;IACE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;QAC5B,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;QAClD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;CACJ,GACD;IACE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;mFAC+E;IAC/E,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC;IAChC;2EACuE;IACvE,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC;CACjC,CAAC;AAEN,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IACtB;gFAC4E;IAC5E,QAAQ,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;8EAC0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAC;IAChC,uEAAuE;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;AAK3E,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AAEzC,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC;gEAC4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC;IAC5F;+DAC2D;IAC3D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC;gEAC4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACnD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,WAAW,GAAG,gBAAgB,GAAG,OAAO,CAAC;AAE/E,MAAM,WAAW,SAAS;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC;IACvD,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,YAAY,GAAG,SAAS,CAAC;IAC7C,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;gDAEgD;AAChD,wBAAgB,WAAW,CACzB,SAAS,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,EAC7C,QAAQ,EAAE,YAAY,GAAG,SAAS,EAClC,SAAS,EAAE,YAAY,GAAG,SAAS,EACnC,KAAK,CAAC,EAAE,MAAM,GACb,YAAY,CAEd;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAEjF,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,EAAE,eAAe,CAAC;CAC9B;AAED,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC;IACrC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,gFAAgF;AAChF,MAAM,WAAW,gBAAgB;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B;yEACqE;IACrE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACnD;;gCAE4B;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C;;4EAEwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,SAAS,gBAAgB,EAAE,CAAC,CAAC;IAC5D,gCAAgC;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,8DAA8D;AAC9D,eAAO,MAAM,wBAAwB,cAAwB,CAAC;AAE9D,MAAM,WAAW,UAAU;IACzB;oDACgD;IAChD,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC;gEAC4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;IACrC,sEAAsE;IACtE,SAAS,IAAI,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAAC;IACrD;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,UAAU,CAAC;IACpD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eAAe,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;IAC5D;;;;;;OAMG;IACH,YAAY,CAAC,CAAC,GAAG,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAClF;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,YAAY,CAAC;CACjD;AAED,MAAM,WAAW,iBAAiB;IAChC,+EAA+E;IAC/E,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,CAAC;IACrE,gFAAgF;IAChF,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,CAAC;IACnF;;;8EAG0E;IAC1E,IAAI,CAAC,IAAI,EAAE,YAAY,GAAG,SAAS,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,iBAAiB,CAAC;IAC5E;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,iBAAiB,CAAC;IAChD;;;;;OAKG;IACH,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,GAAG,iBAAiB,CAAC;IACxD;;;;;;;;;;;;;OAaG;IACH,WAAW,IAAI,iBAAiB,CAAC;IACjC,KAAK,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;CACxC;AAkCD,wBAAgB,UAAU,IAAI,iBAAiB,CAAC;AAChD,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CAAC"}

package/dist/types/lib/injection-engine/skillGraphCheckup.d.ts

@@ -3,17 +3,36 @@
  *
  * Pure + side-effect-free. Catches wiring mistakes at authoring time instead of
  * mid-run: a skill nobody can reach, an edge to a skill that isn't in the graph,
- * two un-prioritized edges leaving one skill, a graph with no start, a self-loop.
+ * two un-prioritized edges leaving one skill, a graph with no start, a self-loop,
+ * an entry menu with no way to choose from it, a transition the cursor can never take.
  *
  * Surfaced two ways:
  *   • `graph.checkup()` → `{ ok, problems }` — always available, call it whenever.
  *   • `.build({ check: 'throw' | 'warn' | 'off' })` — run it at build time.
  *
- * `unreachable-skill` is a WARNING, not an error: a skill with no incoming edge is
- * still legitimately reachable by the model via `read_skill`. Only `unknown-skill`
- * and `no-entry` are true errors.
+ * **Only `unknown-skill` and `no-entry` are ERRORS.** Everything else is a WARNING,
+ * and deliberately so: this file reports what it can PROVE from the declaration, and
+ * a graph the model can still navigate is not a broken graph. `unreachable-skill`,
+ * `model-edge-only` and `dead-entry-step` all describe skills or transitions that
+ * deterministic routing cannot reach — but `read_skill` can, so calling them errors
+ * would claim more than the declaration supports.
+ *
+ * ## What "reachable" means here (8.7.0)
+ *
+ * The BFS walks **deterministic** edges only — an edge with a `when` or an
+ * `onToolReturn`. A bare `.route(a, b)` compiles to no trigger at all (`b` keeps its
+ * `llm-activated` default), so counting it as reachability answered a question nobody
+ * asked: the graph does not route there, the model does. Bare edges get their own
+ * code, `model-edge-only`, which says exactly that and names the one cursor position
+ * the gate will grant the jump from.
  */
-export type GraphProblemCode = 'unknown-skill' | 'no-entry' | 'unreachable-skill' | 'ambiguous-routes' | 'self-loop' | 'body-foreign-tool' | 'body-unknown-tool';
+/**
+ * The compiled trigger kinds this file needs to tell apart. Mirrors
+ * `InjectionTrigger['kind']` without importing it — the check-up is pure over
+ * strings and must not depend on the engine's types.
+ */
+export type CheckupTriggerKind = 'always' | 'rule' | 'on-tool-return' | 'llm-activated';
+export type GraphProblemCode = 'unknown-skill' | 'no-entry' | 'unreachable-skill' | 'model-edge-only' | 'multi-entry-fanout' | 'dead-entry-step' | 'ambiguous-routes' | 'self-loop' | 'body-foreign-tool' | 'body-unknown-tool';
 /** One issue found by the check-up. `kind: 'error'` fails `ok` (and `'throw'`). */
 export interface GraphProblem {
     readonly kind: 'error' | 'warning';
@@ -29,11 +48,17 @@ export interface GraphCheckup {
     readonly ok: boolean;
     readonly problems: readonly GraphProblem[];
 }
+/** One declared entry, in declaration order. */
+export interface CheckupEntry {
+    readonly id: string;
+    /** Has a `when` predicate — i.e. it does NOT unconditionally win the cold-start cursor. */
+    readonly conditional: boolean;
+}
 export interface CheckupInput {
     /** Every skill id IN the graph. */
     readonly skillIds: ReadonlySet<string>;
-    /** Declared entry skill ids. */
-    readonly entryIds: readonly string[];
+    /** Declared entries, in declaration order (the order the cursor resolver reads). */
+    readonly entries: readonly CheckupEntry[];
     /** Declared edges; `deterministic` = has a `when`/`onToolReturn` predicate. */
     readonly routes: ReadonlyArray<{
         fromId: string;
@@ -42,6 +67,21 @@ export interface CheckupInput {
     }>;
     /** Decision-`tree()` graphs are exhaustive by construction — only id checks apply. */
     readonly isTree: boolean;
+    /**
+     * The entries are EXCLUSIVE — a scorer (`.entryBy()`/`.entryByRelevance()`) or
+     * `.entryByRead()` picks exactly one. When true, the fan-out checks do not apply:
+     * choosing among the entries is precisely what those strategies do.
+     */
+    readonly exclusiveEntries: boolean;
+    /**
+     * The COMPILED trigger kind per skill id. Read only to keep `unreachable-skill`'s
+     * sentence true: "the model can still open it with read_skill" holds for an
+     * `llm-activated` trigger and for no other kind — the agent's gate admits an open
+     * pick only for that one (`Agent.openSkillIds`). A skill that arrived carrying a
+     * hand-authored `rule` trigger keeps it (`deriveTrigger` returns null for an
+     * unwired skill), and for that skill the old sentence was false.
+     */
+    readonly triggerKinds: ReadonlyMap<string, CheckupTriggerKind>;
 }
 /** Run the check-up. Pure. */
 export declare function checkupGraph(input: CheckupInput): GraphCheckup;

package/dist/types/lib/injection-engine/skillGraphCheckup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skillGraphCheckup.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/skillGraphCheckup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,gBAAgB,GACxB,eAAe,GACf,UAAU,GACV,mBAAmB,GACnB,kBAAkB,GAClB,WAAW,GAEX,mBAAmB,GACnB,mBAAmB,CAAC;AAExB,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACzF,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,8BAA8B;AAC9B,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAoG9D;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAE3D"}
+{"version":3,"file":"skillGraphCheckup.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/skillGraphCheckup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,MAAM,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAExF,MAAM,MAAM,gBAAgB,GACxB,eAAe,GACf,UAAU,GACV,mBAAmB,GACnB,iBAAiB,GACjB,oBAAoB,GACpB,iBAAiB,GACjB,kBAAkB,GAClB,WAAW,GAEX,mBAAmB,GACnB,mBAAmB,CAAC;AAExB,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,0EAA0E;AAC1E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAED,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,2FAA2F;IAC3F,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACzF,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAChE;AAED,8BAA8B;AAC9B,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAsN9D;AA2CD,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAE3D"}

package/dist/types/lib/injection-engine/skillsFromDir.d.ts

@@ -29,6 +29,25 @@
  * body (what it reads after deciding). That is the same file convention Claude
  * Code made familiar, so a skill folder is portable between the two.
  *
+ * ── What a SKILL.md can and cannot carry ─────────────────────────────────────
+ * `name`, `description`, the body. That is the whole per-file surface, and the
+ * limits follow from it rather than from an oversight:
+ *
+ *   - **no `tools`** — a tool is code with an `execute`, and a markdown file has
+ *     none. Every loaded skill is body-only. To give one tools, define that skill
+ *     with `defineSkill` and mix the lists (`[...loaded, codeAuthored]`), or put
+ *     the tools on the route target you declare in code.
+ *   - **no `autoActivate`** — so a loaded skill never scopes the agent's tool list
+ *     on its own (it has no tools to scope).
+ *   - **no per-file `surfaceMode`, `cache` or `refreshPolicy`** — `surfaceMode` is
+ *     settable for the WHOLE directory via `opts`, all of them or none; the others
+ *     take `defineSkill`'s defaults.
+ *   - unknown frontmatter keys are IGNORED, not rejected, so a file carrying
+ *     another tool's metadata still loads here.
+ *
+ * A worked example feeding this into a graph:
+ * `examples/features/47-skills-from-dir-graph.ts`.
+ *
  * ── Why authorship is decided here, at load time ─────────────────────────────
  * A Skill body is *instructions to a model*. Where it came from is therefore a
  * security property, not a convenience: content fetched at run time from
@@ -49,6 +68,11 @@ export interface SkillsFromDirOptions {
     /**
      * Override the activation tool name for every loaded skill. Defaults to
      * `defineSkill`'s own default, `'read_skill'`.
+     *
+     * @deprecated Since 8.7.0 — see {@link DefineSkillOptions.viaToolName}. Nothing has
+     * ever read the field, and mounting a skill that carries another value is now
+     * refused, so a directory loaded with this option produces skills no agent will
+     * accept. Removed in 9.0.0.
      */
     readonly viaToolName?: string;
     /**

package/dist/types/lib/injection-engine/skillsFromDir.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skillsFromDir.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/skillsFromDir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAe3E,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACpC;AAeD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CA+E/B"}
+{"version":3,"file":"skillsFromDir.d.ts","sourceRoot":"","sources":["../../../../src/lib/injection-engine/skillsFromDir.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAe3E,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACpC;AAeD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CA+E/B"}

package/dist/types/lib/injection-engine/types.d.ts

@@ -128,6 +128,14 @@ export interface InjectionContext {
      * Set by the loop's cursor-update stage to `graph.nextSkill(ctx)` each
      * iteration; absent for agents that don't use `skillGraph()`. Plain
      * `rule`/`always`/`on-tool-return` predicates may ignore it.
+     *
+     * **Scope: ONE run.** "Persisted across iterations" means across the iterations of
+     * a single `agent.run()`. It lives in that run's state, so a second `run()` on the
+     * same agent begins cold — at the entry, not at the skill the previous turn ended
+     * on. That is deliberate: a skill graph declares how ONE turn is routed, and a
+     * cursor that survived would silently make turn 2 start somewhere the author never
+     * declared. To carry a position between turns, persist the id in your own store and
+     * start the next turn's graph from it.
      */
     readonly currentSkillId?: string;
     /**

package/dist/types/lib/injection-engine/types.d.ts.map

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

package/dist/types/tool-providers/index.d.ts

@@ -49,7 +49,7 @@
  */
 export { staticTools } from './staticTools.js';
 export { gatedTools } from './gatedTools.js';
-export { skillScopedTools } from './skillScopedTools.js';
+export { skillScopedTools, skillScopedToolsTarget, SKILL_SCOPED_TOOLS_ID_PREFIX, } from './skillScopedTools.js';
 export type { ToolProvider, ToolDispatchContext, ToolGatePredicate } from './types.js';
 export { mcpClient, mcpServe, mockMcpClient, gatewayTransport, GatewayAuthorizationRequiredError, } from '../lib/mcp/index.js';
 export type { GatewayTransportOptions, McpCallToolResult, McpClient, McpClientOptions, McpSdkClient, McpTransport, McpStdioTransport, McpHttpTransport, McpGatewayTransport, MockMcpClientOptions, MockMcpTool, McpServeOptions, McpServeHandle, McpServeTransport, McpStdioServeTransport, McpHttpServeTransport, McpSdkServer, } from '../lib/mcp/index.js';

package/dist/types/tool-providers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAKvF,OAAO,EACL,SAAS,EACT,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,iCAAiC,GAClC,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,uBAAuB,EACvB,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EACX,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,GACb,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EACL,gBAAgB,EAGhB,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAKvF,OAAO,EACL,SAAS,EACT,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,iCAAiC,GAClC,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,uBAAuB,EACvB,iBAAiB,EACjB,SAAS,EACT,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EACX,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,YAAY,GACb,MAAM,qBAAqB,CAAC"}

package/dist/types/tool-providers/skillScopedTools.d.ts

@@ -49,5 +49,9 @@
  */
 import type { Tool } from '../core/tools.js';
 import type { ToolProvider } from './types.js';
+/** The `ToolProvider.id` prefix every `skillScopedTools(...)` carries. */
+export declare const SKILL_SCOPED_TOOLS_ID_PREFIX = "skill-scoped:";
+/** Recover the skill id from a `skillScopedTools` provider id, or `undefined`. */
+export declare function skillScopedToolsTarget(providerId: string | undefined): string | undefined;
 export declare function skillScopedTools(skillId: string, tools: readonly Tool[]): ToolProvider;
 //# sourceMappingURL=skillScopedTools.d.ts.map

package/dist/types/tool-providers/skillScopedTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skillScopedTools.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/skillScopedTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,YAAY,CAAC;AAGpE,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,YAAY,CAgBtF"}
+{"version":3,"file":"skillScopedTools.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/skillScopedTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAIH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,YAAY,CAAC;AAEpE,0EAA0E;AAC1E,eAAO,MAAM,4BAA4B,kBAAkB,CAAC;AAE5D,kFAAkF;AAClF,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAIzF;AAGD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,IAAI,EAAE,GAAG,YAAY,CAwCtF"}

package/dist/types/tool-providers/types.d.ts

@@ -62,8 +62,33 @@ export interface ToolDispatchContext {
      * The id of the currently-activated Skill, if any.
      * Set by `read_skill(id)` activation; cleared between turns.
      * Used by `autoActivate`-driven per-skill tool gating.
+     *
+     * **This is the last `read_skill` activation, not the graph's position.** It is
+     * filled from the tail of `activatedInjectionIds`, which only `read_skill` ever
+     * appends to. For "which skills are actually loaded right now", including the ones
+     * an entry rule or a `skillGraph()` edge activated, read {@link activeSkillIds}.
      */
     readonly activeSkillId?: string;
+    /**
+     * **Every skill active on this iteration** — the real active set, however each one
+     * got there: a `read_skill` activation, an entry rule, a `skillGraph()` route, a
+     * decision-tree leaf. Added in 8.7.0.
+     *
+     * `activeSkillId` answers "what did the model most recently open"; this answers
+     * "what is loaded". A provider that wants to follow the graph's POSITION — which
+     * `skillScopedTools`' own docs said was impossible — reads this one:
+     *
+     * ```ts
+     * const graphScoped = (id: string, tools: Tool[]): ToolProvider => ({
+     *   id: `graph-scoped:${id}`,
+     *   list: (ctx) => (ctx.activeSkillIds?.includes(id) ? tools : []),
+     * });
+     * ```
+     *
+     * Optional for forward-compat: a provider written before 8.7.0 sees `undefined` and
+     * behaves exactly as it always did.
+     */
+    readonly activeSkillIds?: readonly string[];
     /**
      * Caller identity tuple — passed through from `agent.run({ identity })`.
      * Permission predicates can role-check based on `identity.principal`

package/dist/types/tool-providers/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,CAAC;IACF;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,IAAI,CAAC,GAAG,EAAE,mBAAmB,GAAG,SAAS,IAAI,EAAE,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAE3E;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/tool-providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,CAAC;IACF;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,IAAI,CAAC,GAAG,EAAE,mBAAmB,GAAG,SAAS,IAAI,EAAE,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;IAE3E;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,mBAAmB,KAAK,OAAO,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "8.6.0",
+  "version": "8.7.0",
   "description": "The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.",
   "license": "MIT",
   "type": "commonjs",