agentfootprint 9.35.0 → 9.36.0

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

@@ -0,0 +1,56 @@
+/**
+ * toolsFromActiveSkill — the AGENT-level tool posture (9.36.0).
+ *
+ * Pattern: pure fold over the final injection list, run once at `Agent.build()`.
+ * Role:    core/ layer. One declaration replaces a per-skill discipline.
+ * Emits:   nothing. It changes what the OFFER contains, and the tools slot
+ *          already records every offered tool and the skill that unlocked it.
+ *
+ * ── The defect this exists for ───────────────────────────────────────────
+ * `buildToolRegistry` pre-loads a skill's `inject.tools` into the STATIC
+ * registry unless that skill declared `autoActivate: 'currentSkill'`. Static
+ * means on the wire from iteration 1, whatever the cursor says. So "only the
+ * active skill's tools are offered" was a promise you had to keep on EVERY
+ * skill, one field at a time, and the first skill you forgot leaked its tools
+ * for the life of the agent — silently, because a tool that is offered too
+ * early looks exactly like a tool that is offered.
+ *
+ * A skill graph can already say it once for the skills it WIRES
+ * (`skillGraph({ scopeTools: true })`, which stamps the same field at graph
+ * compile). Three kinds of skill fall outside that: a skill the graph lists
+ * but never routes to, a skill registered beside the graph, and every skill on
+ * an agent with no graph at all — including a whole directory loaded through
+ * `skillsFromDir`. This is the same decision made where every skill is in
+ * hand: at the agent.
+ *
+ * ── Why it stamps the shipped field instead of adding a second gate ──────
+ * The alternative was a flag threaded into `buildToolRegistry`. That would
+ * have created TWO ways for a tool to be held out, and only one of them
+ * visible to everyone else who asks the question: `ActiveInjection.autoActivate`
+ * (which the boundary projects), a consumer's own `ToolProvider`, a lens
+ * drawing the graph, `warnRedundantSkillScopedTools`. Stamping the declared
+ * field keeps ONE mechanism and one answer.
+ *
+ * ── Which wins: the per-skill flag or the agent posture ──────────────────
+ * Neither overrides the other, because they cannot disagree. `autoActivate`
+ * has exactly one legal value (`'currentSkill'`), so a skill can ask to be
+ * scoped and cannot ask to be exempt. The stamp is `existing ?? 'currentSkill'`
+ * — a DEFAULT, never an override — the same sentence `skillGraph`'s
+ * `scopeTools` already lives by. The result is monotone: turning the posture
+ * on can only ever REMOVE tools from the static registry, never add one.
+ */
+import type { Injection } from '../../lib/injection-engine/types.js';
+/**
+ * Stamp `autoActivate: 'currentSkill'` on every skill that carries tools and
+ * has not already declared the field.
+ *
+ * Only skills WITH tools are touched: `autoActivate` says where a skill's
+ * tools appear, and a skill with none has nothing to say — stamping it would
+ * put a field on the record that decides nothing, which is exactly the kind of
+ * metadata a reader later has to disprove.
+ *
+ * Called only from `Agent.build()` and only under the opt-in, so an agent that
+ * never asks for it never runs this code.
+ */
+export declare function scopeToolsToActiveSkill(injections: readonly Injection[]): Injection[];
+//# sourceMappingURL=toolsFromActiveSkill.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"toolsFromActiveSkill.d.ts","sourceRoot":"","sources":["../../../../src/core/agent/toolsFromActiveSkill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAKrE;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,SAAS,EAAE,CAerF"}

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

@@ -151,6 +151,13 @@ export interface DefineSkillOptions {
      *   agent's registry at BUILD time and the model can see and call them
      *   from iteration 1, activated or not.
      *
+     * Saying it once for the whole agent instead of once per skill:
+     * `.toolsFromActiveSkill()` on the builder (9.36.0) stamps this field on
+     * every tool-carrying skill, and `skillGraph({ scopeTools: true })` stamps it
+     * on the skills a graph wires. Both are DEFAULTS — a skill that declared its
+     * own keeps it — and since `'currentSkill'` is the only legal value, none of
+     * the three can contradict another.
+     *
      * Wired at runtime since v2.5: `buildToolRegistry` holds these tools out of the
      * static registry and `buildToolsSlot` readmits them per-iteration from the
      * active injections. Dispatch is unaffected either way — an autoActivate tool

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

@@ -1 +1 @@
-{"version":3,"file":"defineSkill.d.ts","sourceRoot":"","sources":["../../../../../src/lib/injection-engine/factories/defineSkill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAsB,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,eAAe,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;gDAM4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC;IACzC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,4BAA4B,EAAE,WAAW,CAAC;IACrE;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAahF;AAqDD,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,SAAS,CA2E/D"}
+{"version":3,"file":"defineSkill.d.ts","sourceRoot":"","sources":["../../../../../src/lib/injection-engine/factories/defineSkill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAsB,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGzF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,eAAe,GAAG,WAAW,GAAG,MAAM,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;gDAM4C;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC;IACzC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,SAAS,EAAE,CAAC;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC;IAC/B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,4BAA4B,EAAE,WAAW,CAAC;IACrE;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAE9C;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAahF;AAqDD,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,SAAS,CA2E/D"}

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

@@ -29,21 +29,56 @@
  * 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.
+ * ── What a SKILL.md can carry (9.36.0: the whole runbook) ────────────────────
+ * A runbook you already have on disk is three things — what to do (prose),
+ * what to do it WITH (tools), and in what order (steps). This door used to
+ * carry the first and drop the other two, so the one thing the library exists
+ * to say ("extract the workflow you already have") arrived two-thirds empty.
+ * All three now cross:
+ *
+ *   ---
+ *   name: billing
+ *   description: Use for refunds, charges and billing questions.
+ *   tools: lookup_order, issue_refund
+ *   steps:
+ *     - lookup_order: look up the order before touching money
+ *     - issue_refund: refund only what the lookup found
+ *   onSkip: hold
+ *   ---
+ *   When handling billing: confirm identity first, then …
+ *
+ *   const skills = await skillsFromDir('./skills', {
+ *     tools: [lookupOrder, issueRefund],   // the real Tools, from YOUR code
+ *   });
+ *
+ * The remaining limits, and why each one is a decision rather than an
+ * oversight:
+ *
+ *   - **the file names a tool; it never defines one.** A tool is code with an
+ *     `execute`, and a markdown file has none. `tools:` is a list of NAMES,
+ *     resolved against the `tools` registry the CALLER passes — so the file
+ *     can only ever pick from capabilities you already handed in, and reading a
+ *     directory can never introduce one. See "why this is not a code-execution
+ *     vector" below.
+ *   - **a name the registry does not carry is refused BY NAME at load** —
+ *     never a skill that quietly loads without the tool it asked for, because
+ *     that skill runs, sounds confident, and cannot do the job.
+ *   - **no per-step `produces` / `consumes`** — the artifact vocabularies
+ *     (9.25.0) are a build-time contract between skills, not runbook prose;
+ *     declare them with `defineSkill` where the rest of the agent is declared.
+ *   - **no `autoActivate`** — a directory does not decide the agent's tool
+ *     posture. Say it once on the agent with `.toolsFromActiveSkill()`
+ *     (9.36.0), which scopes every skill's tools to that skill's activation.
+ *     Without it, a loaded skill's tools are on the wire from iteration 1, the
+ *     same as any hand-written `defineSkill({ tools })`.
+ *   - **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 still IGNORED, not rejected, so a file
+ *     carrying another tool's metadata still loads here. `name`,
+ *     `description`, `tools`, `steps` and `onSkip` are the KNOWN keys — a file
+ *     that used one of those five for something else is the one case this
+ *     release can change, and it changes it loudly.
  *
  * A worked example feeding this into a graph:
  * `examples/features/47-skills-from-dir-graph.ts`.
@@ -57,12 +92,24 @@
  * only make about a path on your own disk at build time. Each file is read
  * ONCE, here; a later edit does not reach a run already in flight.
  *
+ * ── Why carrying tools is not a code-execution vector ───────────────────────
+ * Nothing in a SKILL.md is evaluated, imported, required or resolved as a
+ * path. `tools:` is a list of strings, and the only thing a string can do here
+ * is MATCH — against `tool.schema.name` in a registry the caller constructed in
+ * their own source, from their own imports. A hostile file can therefore ask
+ * for a tool you already gave the agent (and it would have to guess the name);
+ * it can never name a module, widen the agent's capabilities, or cause one byte
+ * of new code to run. The set of things this directory can do is a SUBSET of
+ * what the calling file already decided to do, which is the same property the
+ * local-path rule above buys for bodies.
+ *
  * Node-only. `node:fs/promises` and `node:path` are imported lazily inside the
  * call, the same gating `lib/tool-lint/cli.ts` uses: this module is reachable
  * from the `agentfootprint/context` barrel, and a TOP-LEVEL node:fs
  * import detonates a browser bundle at module-eval even when nothing calls it.
  */
 import type { Injection } from './types.js';
+import type { Tool } from '../../core/tools.js';
 import { type SurfaceMode } from './factories/defineSkill.js';
 export interface SkillsFromDirOptions {
     /**
@@ -70,6 +117,21 @@ export interface SkillsFromDirOptions {
      * `defineSkill`'s own default, `'auto'`. See {@link SurfaceMode}.
      */
     readonly surfaceMode?: SurfaceMode;
+    /**
+     * The tools a file may NAME (9.36.0) — the resolution registry for every
+     * `tools:` declaration in the directory, matched by `tool.schema.name`.
+     *
+     * This is the half a markdown file cannot supply. The file picks; you decide
+     * what there is to pick FROM, in your own source, from your own imports. A
+     * declared name that is not in here is refused at load, naming the file, the
+     * name, and what this registry does carry.
+     *
+     * Pass every tool the directory might use; a tool nothing names is simply
+     * unused (no skill gets it, and no error). Omit the option entirely on a
+     * prose-only directory — a file that declares `tools:` with no registry
+     * passed is refused rather than loaded without them.
+     */
+    readonly tools?: readonly Tool[];
 }
 /**
  * Load every `SKILL.md` under `dir` as a Skill Injection.
@@ -88,8 +150,9 @@ export interface SkillsFromDirOptions {
  *
  * @throws when `dir` is not a local path, does not exist, is not a directory,
  *   or contains no `SKILL.md` at all; when a file's frontmatter is malformed
- *   (the message names the file); or when two files claim the same skill name
- *   (the message names both).
+ *   (the message names the file); when two files claim the same skill name
+ *   (the message names both); or when a file names a tool the `tools` registry
+ *   does not carry, or sequences a tool the file itself did not declare.
  */
 export declare function skillsFromDir(dir: string, opts?: SkillsFromDirOptions): Promise<readonly Injection[]>;
 //# sourceMappingURL=skillsFromDir.d.ts.map

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAEhD,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAmB3E,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;CAClC;AAsBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,SAAS,SAAS,EAAE,CAAC,CAyF/B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "9.35.0",
+  "version": "9.36.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",