agentfootprint 10.2.0 → 10.3.1

package/dist/esm/injection-engine/skillTools.js

@@ -0,0 +1,115 @@
+/**
+ * Skill-tool ADAPTERS — the one place the graph's tool DESCRIPTIONS become
+ * agentfootprint `Tool`s.
+ *
+ * `list_skills`, `read_skill` and `skip_step` are described — name, schema,
+ * every sentence the model reads — by the pure skill-graph core
+ * (`skillToolDescriptors.ts`, `skillSteps.ts`). This module does the last
+ * step: hands each descriptor to `defineTool`. That split (9.34.0) is what
+ * keeps `read_skill`'s grammar, which is genuinely the graph's — the enum is
+ * the catalog, the description is the reachability offer, the result is what
+ * the model learns about the skill it activated — out of a module that has to
+ * import the framework's tool factory, and therefore out of everything that
+ * factory pulls in (artifacts, credentials, check-in, tool sessions).
+ *
+ * Both tool pairs work over the SAME catalog (a list of `Injection` skills),
+ * used by the Agent's auto-attach path AND by `SkillRegistry.toTools()`
+ * (explicit composition path). Pulling them out of `core/Agent.ts` removed
+ * the v2.4 duplication risk: the Agent auto-attaches its own `read_skill`,
+ * the registry builds a sibling — they MUST agree on schema + execute
+ * semantics, and now they cannot disagree because neither writes the words.
+ *
+ * Tool execute is identity-style (returns a confirmation string); the agent's
+ * tool-calls subflow inspects the tool name + args and updates
+ * `scope.activatedInjectionIds` so the next iteration's InjectionEngine sees
+ * the new activation.
+ *
+ * Zone: HOST. Importing `tools/tools.js` here is the point of the file.
+ */
+import { defineTool } from '../tools/tools.js';
+import { skipStepDescriptor } from './skillSteps.js';
+import { listSkillsDescriptor, readSkillDescriptor, } from './skillToolDescriptors.js';
+/**
+ * Build the `list_skills` tool — a no-arg tool that returns the
+ * registered skills as `{ id, description }[]`. Lets the LLM discover
+ * skills without paying the prompt-token cost of embedding the
+ * catalog into every system prompt.
+ *
+ * Pairs with `read_skill` (which actually activates a skill by id).
+ *
+ * Returns `undefined` when there are no skills — callers should
+ * guard or filter undefined out of their tool list.
+ */
+export function buildListSkillsTool(skills) {
+    const d = listSkillsDescriptor(skills);
+    if (!d)
+        return undefined;
+    return defineTool({
+        name: d.name,
+        description: d.description,
+        inputSchema: d.inputSchema,
+        execute: (args) => d.execute(args),
+    });
+}
+/**
+ * Build the `read_skill` tool — activates a skill for the next
+ * iteration. The LLM picks WHICH skill via the `id` argument.
+ *
+ * Tool execute() returns a confirmation string. The actual bookkeeping
+ * (appending the requested skill id to `scope.activatedInjectionIds`)
+ * is handled by the Agent's tool-calls subflow, which inspects every
+ * `read_skill` tool call by name. The next iteration's InjectionEngine
+ * matches Skills with `trigger.kind: 'llm-activated'` by id and
+ * includes them in the active set; slot subflows then inject the body
+ * + tools.
+ *
+ * The tool's description lists each Skill's `id` + `description` so
+ * the LLM can choose meaningfully without first calling `list_skills`
+ * (a perf trade-off — small registries can afford the inline catalog;
+ * large ones should use `list_skills` for discovery and rely on the
+ * shorter `read_skill` description.) See `surfaceMode` (Block A4) for
+ * tunable trade-offs.
+ *
+ * Returns `undefined` when there are no skills — callers should
+ * guard or filter undefined out of their tool list.
+ *
+ * Pass `offer` to scope the DESCRIPTION to what the graph's gate will actually
+ * grant from the current cursor (8.5.0); the enum stays the full catalog either
+ * way. Omit it and the tool is byte-identical to what it has always been.
+ */
+export function buildReadSkillTool(skills, offer) {
+    const d = readSkillDescriptor(skills, offer);
+    if (!d)
+        return undefined;
+    return defineTool({
+        name: d.name,
+        description: d.description,
+        inputSchema: d.inputSchema,
+        execute: (args) => d.execute(args),
+    });
+}
+/**
+ * Build the `skip_step` tool. Auto-attached to the dispatch registry when
+ * ≥1 registered skill declares steps (the `read_skill` auto-attach seam) —
+ * always dispatchable, but OFFERED (schema in the request) only while a
+ * stepped tenure is active and unfinished. Its execute returns a
+ * placeholder; the tool-calls stage overwrites the model-visible result
+ * with the authoritative sentence, exactly as the skill-graph gate
+ * overwrites `read_skill` refusals — bookkeeping lives where the batch
+ * order lives.
+ *
+ * Lived in `skillSteps.ts` through 9.33.x; moved here in 9.34.0 so that
+ * module — the procedure GRAMMAR — stops importing the tool factory. The
+ * sentences it speaks are still `skillSteps.ts`'s
+ * ({@link skipStepDescriptor}); only the wrapping moved.
+ */
+export function buildSkipStepTool() {
+    const d = skipStepDescriptor();
+    return defineTool({
+        name: d.name,
+        description: d.description,
+        inputSchema: d.inputSchema,
+        execute: (args) => d.execute(args),
+    });
+}
+//# sourceMappingURL=skillTools.js.map

package/dist/esm/injection-engine/skillTools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skillTools.js","sourceRoot":"","sources":["../../../src/injection-engine/skillTools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EACL,oBAAoB,EACpB,mBAAmB,GAEpB,MAAM,2BAA2B,CAAC;AAOnC;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAA4B;IAC9D,MAAM,CAAC,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,OAAO,UAAU,CAAgC;QAC/C,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;KACnC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAA4B,EAC5B,KAAsB;IAEtB,MAAM,CAAC,GAAG,mBAAmB,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC7C,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,OAAO,UAAU,CAAyB;QACxC,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;KACnC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,CAAC,GAAG,kBAAkB,EAAE,CAAC;IAC/B,OAAO,UAAU,CAA6B;QAC5C,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,WAAW,EAAE,CAAC,CAAC,WAAW;QAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC;KACnC,CAAoB,CAAC;AACxB,CAAC"}

package/dist/esm/injection-engine/skillVocabulary.js.map

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

package/dist/esm/injection-engine/skillsFromDir.d.ts

@@ -0,0 +1,237 @@
+/**
+ * skillsFromDir — load Skills that were AUTHORED AS FILES.
+ *
+ * The just-in-time half of skills already ships: `defineSkill` produces an
+ * Injection whose `description` is all the model sees until it calls
+ * `read_skill(<id>)`, at which point the body enters the context. What did not
+ * ship was the other half — a way to keep those bodies where prose belongs, in
+ * files, next to the code they describe, reviewable in a diff.
+ *
+ * This is that loader, and nothing more. It reads a directory of `SKILL.md`
+ * files and hands each one to `defineSkill`. The progressive disclosure, the
+ * activation tool, the slot routing — all unchanged, all upstream of here.
+ *
+ *   skills/
+ *     billing/SKILL.md
+ *     refunds/SKILL.md
+ *
+ *   ---
+ *   name: billing
+ *   description: Use for refunds, charges and billing questions.
+ *   ---
+ *   When handling billing: confirm identity first, then …
+ *
+ *   const skills = await skillsFromDir('./skills');
+ *   const agent = Agent.create({ provider, model }).skills({ list: () => skills }).build();
+ *
+ * The frontmatter is the disclosure stub (`name` + `description` — what the
+ * model reads when deciding), and everything after the closing fence is the
+ * 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 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` or `cache`** — `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`, `onSkip` and `routes` are the KNOWN
+ *     keys — a file that used one of those six for something else is the one
+ *     case a release can change, and it changes it loudly.
+ *
+ * ── The routing, and the door that reads it (9.43.0) ─────────────────────────
+ * A runbook says what to do, what to do it with, in what order — and where the
+ * work goes NEXT. That last part is the graph, and until now it had to be
+ * hand-wired in code even when the files said it plainly. `routes:` closes it:
+ *
+ *   ---
+ *   name: billing
+ *   tools: lookup_order, issue_refund
+ *   routes:
+ *     - escalation: on issue_refund status=denied
+ *     - receipts: on issue_refund
+ *   ---
+ *
+ *   const runbook = await runbookFromDir('./skills', { tools: [...] });
+ *   const graph = skillGraph({ ...runbook, start: 'billing' });
+ *
+ * TWO DOORS, one truth: `skillsFromDir` returns skills and REFUSES a file that
+ * declares `routes:` (a door that dropped the routing would hand back a graph
+ * you believed was declared on disk); {@link runbookFromDir} returns
+ * `{ skills, steps }`. Same law as `tools:` — the file PICKS (a route names a
+ * skill id this directory declares; an unknown id is refused at load, by name,
+ * listing what is available), it never DEFINES. A guard is one of the two DATA
+ * conditions a route already has (`on <tool_name>`, `status=<outcome>`), and
+ * nothing else: a `when` predicate is CODE, no file can carry code, and that
+ * conditional stays in your source. See `skillsFromDirRoutes.ts` for the whole
+ * grammar and every refusal.
+ *
+ * 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
+ * somewhere else is content someone else can change after you reviewed it.
+ * This loader accepts a local directory and nothing else — a URL is refused BY
+ * NAME rather than fetched — because "these files are mine" is a claim you can
+ * 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 `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 '../tools/tools.js';
+import { type SurfaceMode } from './factories/defineSkill.js';
+import type { SkillGraphStep } from './skillGraph.js';
+export interface SkillsFromDirOptions {
+    /**
+     * Where a loaded skill's body lands once activated. Defaults to
+     * `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[];
+}
+/**
+ * A whole runbook directory, read as the two things a graph is made of
+ * (9.43.0): the skills, and the edges between them.
+ *
+ * Spreads straight into the graph — the field names are the graph's own, so
+ * nothing has to be translated at the call site:
+ *
+ *   const runbook = await runbookFromDir('./skills', { tools });
+ *   const graph = skillGraph({ ...runbook, start: 'triage' });
+ */
+export interface DirRunbook {
+    /** Every `SKILL.md` under the directory, as Skill Injections — byte-identical
+     *  to what `skillsFromDir` returns for the same directory. */
+    readonly skills: readonly Injection[];
+    /**
+     * The declared edges, ready for `skillGraph({ steps })`. In skill-name order,
+     * then file order, so a graph built from a directory is stable.
+     *
+     * NAME NOTE, because two different things are spelled `steps` in this
+     * library: a file's own `steps:` key is that SKILL's tool sequence (which
+     * rides on the skill, unchanged); these `steps` are the GRAPH's edges, read
+     * from each file's `routes:` key. They never meet.
+     */
+    readonly steps: readonly SkillGraphStep[];
+}
+/**
+ * Load every `SKILL.md` under `dir` as a Skill Injection.
+ *
+ * Two layouts are accepted, and they can be mixed:
+ *   - `dir/<anything>/SKILL.md` — one folder per skill (the portable layout,
+ *     and the one to prefer: the folder can hold the skill's other assets).
+ *   - `dir/SKILL.md` — the directory IS one skill.
+ *
+ * The returned array is sorted by skill name, so a chart built from it is
+ * stable regardless of the order the filesystem happened to hand back.
+ *
+ * @param dir - A local filesystem path. A URL (or any `scheme://` string, or a
+ *   UNC network path) is refused by name — see the module header for why.
+ * @param opts - Applied uniformly to every loaded skill.
+ *
+ * @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); 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[]>;
+/**
+ * Load a directory as a whole RUNBOOK (9.43.0) — the skills AND the edges
+ * between them.
+ *
+ * `skillsFromDir` reads what one skill is; this reads what the skills are TO
+ * EACH OTHER, from each file's `routes:` key, and hands back both halves ready
+ * for `skillGraph({ ...runbook, start })`. Everything else is identical: same
+ * layouts, same frontmatter, same tool registry, same refusals.
+ *
+ * The routing a file may carry is deliberately small, and the boundary is a
+ * security property rather than a limitation — see `skillsFromDirRoutes.ts`:
+ * a route NAMES a skill this directory declares (an unknown id is refused at
+ * load, by name, listing what is available — never a half-graph), and a guard
+ * is one of the two DATA conditions a route already has (`on <tool>`,
+ * `status=<outcome>`). A `when` predicate is code, so no file can express one;
+ * that conditional stays in your source, where `skillGraph({ steps })` takes it.
+ *
+ * @param dir - A local filesystem path. Same rule as `skillsFromDir`.
+ * @param opts - Applied uniformly to every loaded skill.
+ *
+ * @throws everything `skillsFromDir` throws, plus: a route to an id no
+ *   `SKILL.md` in the directory declares (the message lists what is
+ *   available), a guard the grammar cannot express (the message quotes the
+ *   whole grammar), a guard naming a tool the file itself does not declare,
+ *   and a file routing to the same skill twice.
+ */
+export declare function runbookFromDir(dir: string, opts?: SkillsFromDirOptions): Promise<DirRunbook>;