agentfootprint 7.12.0 → 7.13.0

package/dist/esm/core/agent/stages/callLLM.js

@@ -34,6 +34,12 @@ export function buildCallLLMStage(deps) {
         // `scope.messagesInjections` is read by ContextRecorder for
         // observability; the LLM-wire path now reads scope.history directly.
         const iteration = scope.iteration;
+        // The model for this run. `.configure()` resolved it at seed and
+        // COMMITTED it to scope, so what gets called, what the `llm_start`
+        // event reports and what cost is priced against are all one value —
+        // the one the trace records. Without `.configure()` this is the
+        // build-time model and scope is never touched.
+        const model = (deps.runConfigured ? scope.resolvedModel : undefined) ?? deps.model;
         // Per-iteration boundary marker (was a dedicated `IterationStart` stage —
         // folded here since emitting is passive observability, not work that needs
         // its own execution stage). Fires FIRST, before the LLM call, so recorders
@@ -63,7 +69,7 @@ export function buildCallLLMStage(deps) {
         typedEmit(scope, 'agentfootprint.stream.llm_start', {
             iteration,
             provider: deps.provider.name,
-            model: deps.model,
+            model,
             systemPromptChars: systemPrompt.length,
             messagesCount: messages.length,
             toolsCount: activeToolSchemas.length,
@@ -80,7 +86,7 @@ export function buildCallLLMStage(deps) {
             ...(systemPrompt.length > 0 && { systemPrompt }),
             messages,
             ...(activeToolSchemas.length > 0 && { tools: activeToolSchemas }),
-            model: deps.model,
+            model,
             ...(deps.temperature !== undefined && { temperature: deps.temperature }),
             ...(deps.maxTokens !== undefined && { maxTokens: deps.maxTokens }),
             ...(deps.thinkingBudget !== undefined && {
@@ -198,7 +204,7 @@ export function buildCallLLMStage(deps) {
         }
         let response;
         if (deps.reliability) {
-            response = await executeWithReliability(scope, llmRequest, deps.reliability, deps.provider, deps.provider.name, deps.model, singleProviderCall, postValidate);
+            response = await executeWithReliability(scope, llmRequest, deps.reliability, deps.provider, deps.provider.name, model, singleProviderCall, postValidate);
             // `executeWithReliability` returns `undefined` when it took the
             // fail-fast path. It already wrote scope state and called
             // `$break(reason)` — `Agent.run()` translates the propagated
@@ -231,7 +237,7 @@ export function buildCallLLMStage(deps) {
             stopReason: response.stopReason,
             durationMs,
         });
-        emitCostTick(scope, deps.pricingTable, deps.costBudget, deps.model, response.usage);
+        emitCostTick(scope, deps.pricingTable, deps.costBudget, model, response.usage);
     };
 }
 //# sourceMappingURL=callLLM.js.map

package/dist/esm/core/agent/stages/callLLM.js.map

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

package/dist/esm/core/agent/stages/seed.d.ts

@@ -18,7 +18,7 @@
  */
 import type { TypedScope } from 'footprintjs';
 import type { LLMMessage, LLMToolSchema } from '../../../adapters/types.js';
-import type { AgentState } from '../types.js';
+import type { AgentInput, AgentState, RunConfig } from '../types.js';
 export interface SeedStageDeps {
     /** Resolved `clampIterations(opts.maxIterations ?? 10)`. Frozen at
      *  chart-build time. */
@@ -44,6 +44,15 @@ export interface SeedStageDeps {
      * Returns `undefined` only in degenerate (test) cases.
      */
     readonly getCurrentRunId: () => string | undefined;
+    /**
+     * Per-run config resolver from `.configure()`. Seed is where run-level
+     * facts are decided AND committed (identity, iteration budget, turn
+     * number all land here), so this rides the same commit rather than
+     * inventing a second place a run can change itself. Undefined when the
+     * consumer never called `.configure()` — and then nothing extra is
+     * written, so the commit log is byte-identical to earlier releases.
+     */
+    readonly resolveRunConfig?: (input: AgentInput) => RunConfig | undefined;
 }
 /**
  * Build the seed stage function for an Agent instance. Captures both

package/dist/esm/core/agent/stages/seed.js

@@ -90,6 +90,22 @@ export function buildSeedStage(deps) {
         // graph through the entry router (cold start). The Injection Engine advances
         // it each iteration; undefined for agents without a skillGraph().
         scope.currentSkillId = undefined;
+        // `.configure()` — resolved ONCE here (seed runs exactly once per run)
+        // and written to scope, which means the run's commit log records the
+        // model and instructions the run actually used. A run that changed its
+        // own model without committing that fact would produce a trace that
+        // reads as if the built-in default answered.
+        //
+        // Only what the resolver actually returned is written: an agent with no
+        // `.configure()`, or one whose resolver returned `{}`, commits nothing
+        // extra and behaves exactly as before.
+        if (deps.resolveRunConfig) {
+            const resolved = deps.resolveRunConfig(args);
+            if (resolved?.model !== undefined)
+                scope.resolvedModel = resolved.model;
+            if (resolved?.instructions !== undefined)
+                scope.resolvedInstructions = resolved.instructions;
+        }
         typedEmit(scope, 'agentfootprint.agent.turn_start', {
             turnIndex: 0,
             userPrompt: args.message,

package/dist/esm/core/agent/stages/seed.js.map

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

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

@@ -256,6 +256,39 @@ export interface AgentOptions {
      */
     readonly observerDeliveryOptions?: ObserverDeliveryOptions;
 }
+/**
+ * What `.configure(fn)` may change for one run. Both fields are
+ * optional; returning `{}` (or nothing) means "use the built defaults",
+ * which is exactly what an agent without `.configure()` does.
+ *
+ * Deliberately NOT the tools axis — `.toolProvider()` already owns that,
+ * and it is consulted every iteration rather than once per run.
+ */
+export interface RunConfig {
+    /** Model id for every LLM call in this run. */
+    readonly model?: string;
+    /** Replaces the base system prompt set by `.system(...)` for this run. */
+    readonly instructions?: string;
+}
+/** What a `.configure(fn)` resolver is given. */
+export interface RunConfigContext {
+    /** The message this run was started with. */
+    readonly message: string;
+    /** The memory identity passed to `run({ identity })`, when there was one. */
+    readonly identity?: MemoryIdentity;
+    /** This run's id — the same one that stamps every typed event's `meta.runId`. */
+    readonly runId: string;
+    /** What the agent was BUILT with, so a resolver can decide relative to it. */
+    readonly defaults: {
+        readonly model: string;
+        readonly instructions: string;
+    };
+}
+/**
+ * Per-run configuration resolver — see `AgentBuilder.configure`. Called
+ * exactly once per run, synchronously, at the start of the run.
+ */
+export type RunConfigFn = (ctx: RunConfigContext) => RunConfig | undefined;
 export interface AgentInput {
     readonly message: string;
     /**
@@ -363,6 +396,17 @@ export interface AgentState {
     /** Name of the entry scorer that produced `entryScores` (`'keyword'` /
      *  `'embedding'` / a custom scorer's name). */
     entryScorer?: string;
+    /** The model `.configure()` resolved for THIS run, written by seed and read
+     *  by CallLLM. Present only when a resolver returned one — a run that did
+     *  not change its model records nothing here, so an agent without
+     *  `.configure()` commits exactly what it always did. The point of writing
+     *  it at all is that the trace must say which model actually answered:
+     *  a run that switched models without recording it would be a trace that
+     *  lies about its own most expensive fact. */
+    resolvedModel?: string;
+    /** The base system prompt `.configure()` resolved for THIS run, replacing
+     *  `.system(...)`. Same rule: absent unless a resolver returned one. */
+    resolvedInstructions?: string;
     /** Set when a `PermissionChecker` returns `{ result: 'halt', ... }`.
      *  `Agent.run()` reads these at the API boundary and throws a typed
      *  `PolicyHaltError` carrying the same context — the chart $break's

package/dist/esm/core/slots/buildSystemPromptSlot.d.ts

@@ -17,17 +17,32 @@ import type { FlowChart } from 'footprintjs';
  * Function that produces the system prompt string given runtime scope
  * context. Receives the subflow's $getArgs() payload.
  */
-export type SystemPromptFn = (args: {
+export type SystemPromptFn = (args: SystemPromptSlotArgs) => string | Promise<string>;
+/**
+ * What the slot's `$getArgs()` carries. `instructions` is present only when
+ * the Agent's `.configure()` resolved a per-run system prompt — the mount's
+ * inputMapper omits the key entirely otherwise, so an unconfigured agent
+ * seeds this subflow with exactly the state it always did.
+ */
+export interface SystemPromptSlotArgs {
     readonly userMessage?: string;
     readonly iteration?: number;
-}) => string | Promise<string>;
+    readonly instructions?: string;
+}
 export interface SystemPromptSlotConfig {
     /** Static string OR a function. Empty string → no injection, empty slot. */
     readonly prompt: string | SystemPromptFn;
     /** Budget cap (chars). Default: 4000. */
     readonly budgetCap?: number;
-    /** Optional description — where this prompt originated (e.g. "agent.system()"). */
-    readonly reason?: string;
+    /**
+     * Where this prompt originated, recorded on the base InjectionRecord
+     * (e.g. `"agent.system()"`). A function when the origin depends on the
+     * run — an Agent with `.configure()` reports `Agent.configure()` on the
+     * runs that actually overrode the prompt and `Agent.system()` on the rest,
+     * so the context record names the real author rather than a build-time
+     * guess.
+     */
+    readonly reason?: string | ((args: SystemPromptSlotArgs) => string);
 }
 /**
  * Build the System-Prompt slot subflow.

package/dist/esm/core/slots/buildSystemPromptSlot.js

@@ -27,13 +27,14 @@ import { composeSlot, fnv1a, formatOverflowWarning, slotOverflow, truncate } fro
  */
 export function buildSystemPromptSlot(config) {
     const budgetCap = config.budgetCap ?? 4000;
-    const reason = config.reason ?? 'static system prompt';
+    const reasonSource = config.reason ?? 'static system prompt';
     const promptSource = config.prompt;
     // Dedup latch for the human-facing overflow warning (see buildToolsSlot).
     let warnedOverflow = false;
     return flowChart('Compose', async (scope) => {
         const args = scope.$getArgs();
         const resolved = typeof promptSource === 'function' ? await promptSource(args) : promptSource;
+        const reason = typeof reasonSource === 'function' ? reasonSource(args) : reasonSource;
         const injections = [];
         // Base prompt — `source: 'base'`. Configured at build time via
         // Agent.create({...}).system('...') OR LLMCall config. Baseline

package/dist/esm/core/slots/buildSystemPromptSlot.js.map

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

package/dist/esm/lib/injection-engine/index.d.ts

@@ -13,6 +13,7 @@ export { defineInstruction, type DefineInstructionOptions } from './factories/de
 export { defineRelevanceHint, type RelevanceHintOptions } from './factories/defineRelevanceHint.js';
 export { defineSkill, resolveSurfaceMode, type DefineSkillOptions, type SurfaceMode, type RefreshPolicy, type AutoActivateMode, } from './factories/defineSkill.js';
 export { SkillRegistry, type SkillRegistryOptions } from './SkillRegistry.js';
+export { skillsFromDir, type SkillsFromDirOptions } from './skillsFromDir.js';
 export { buildListSkillsTool, buildReadSkillTool, type SkillToolPair } from './skillTools.js';
 export { defineSteering, type DefineSteeringOptions } from './factories/defineSteering.js';
 export { defineFact, type DefineFactOptions } from './factories/defineFact.js';

package/dist/esm/lib/injection-engine/index.js

@@ -15,6 +15,10 @@ export { defineInstruction } from './factories/defineInstruction.js';
 export { defineRelevanceHint } from './factories/defineRelevanceHint.js';
 export { defineSkill, resolveSurfaceMode, } from './factories/defineSkill.js';
 export { SkillRegistry } from './SkillRegistry.js';
+// File-authored skills — a loader over `defineSkill`, not a second mechanism.
+// Node-only (reads the filesystem); node:fs is imported lazily inside the call
+// so this barrel stays safe to import from a browser bundle.
+export { skillsFromDir } from './skillsFromDir.js';
 // Skill-tool builders — used by SkillRegistry.toTools() and the Agent's
 // auto-attach path. Exported so consumers building custom tool wiring
 // (e.g., gatedTools chains) can compose the same `list_skills` /

package/dist/esm/lib/injection-engine/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,+DAA+D;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,SAAS;AACT,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACL,2BAA2B,GAE5B,MAAM,kCAAkC,CAAC;AAE1C,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,EAAiC,MAAM,kCAAkC,CAAC;AACpG,OAAO,EAAE,mBAAmB,EAA6B,MAAM,oCAAoC,CAAC;AAEpG,OAAO,EACL,WAAW,EACX,kBAAkB,GAKnB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,aAAa,EAA6B,MAAM,oBAAoB,CAAC;AAE9E,wEAAwE;AACxE,sEAAsE;AACtE,iEAAiE;AACjE,+BAA+B;AAC/B,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAsB,MAAM,iBAAiB,CAAC;AAE9F,OAAO,EAAE,cAAc,EAA8B,MAAM,+BAA+B,CAAC;AAE3F,OAAO,EAAE,UAAU,EAA0B,MAAM,2BAA2B,CAAC;AAE/E,6EAA6E;AAC7E,0EAA0E;AAC1E,qDAAqD;AACrD,OAAO,EACL,eAAe,GAGhB,MAAM,gCAAgC,CAAC;AAExC,4EAA4E;AAC5E,8EAA8E;AAC9E,OAAO,EACL,UAAU,EACV,WAAW,EACX,wBAAwB,GAoBzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,aAAa,EACb,eAAe,EACf,WAAW,GAIZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/injection-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAYH,+DAA+D;AAC/D,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEpD,SAAS;AACT,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EACL,2BAA2B,GAE5B,MAAM,kCAAkC,CAAC;AAE1C,gFAAgF;AAChF,OAAO,EAAE,iBAAiB,EAAiC,MAAM,kCAAkC,CAAC;AACpG,OAAO,EAAE,mBAAmB,EAA6B,MAAM,oCAAoC,CAAC;AAEpG,OAAO,EACL,WAAW,EACX,kBAAkB,GAKnB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,aAAa,EAA6B,MAAM,oBAAoB,CAAC;AAE9E,8EAA8E;AAC9E,+EAA+E;AAC/E,6DAA6D;AAC7D,OAAO,EAAE,aAAa,EAA6B,MAAM,oBAAoB,CAAC;AAE9E,wEAAwE;AACxE,sEAAsE;AACtE,iEAAiE;AACjE,+BAA+B;AAC/B,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAsB,MAAM,iBAAiB,CAAC;AAE9F,OAAO,EAAE,cAAc,EAA8B,MAAM,+BAA+B,CAAC;AAE3F,OAAO,EAAE,UAAU,EAA0B,MAAM,2BAA2B,CAAC;AAE/E,6EAA6E;AAC7E,0EAA0E;AAC1E,qDAAqD;AACrD,OAAO,EACL,eAAe,GAGhB,MAAM,gCAAgC,CAAC;AAExC,4EAA4E;AAC5E,8EAA8E;AAC9E,OAAO,EACL,UAAU,EACV,WAAW,EACX,wBAAwB,GAoBzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,aAAa,EACb,eAAe,EACf,WAAW,GAIZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ *
+ * ── 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.
+ *
+ * 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/injection-engine` 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 SurfaceMode } from './factories/defineSkill.js';
+export interface SkillsFromDirOptions {
+    /**
+     * Override the activation tool name for every loaded skill. Defaults to
+     * `defineSkill`'s own default, `'read_skill'`.
+     */
+    readonly viaToolName?: string;
+    /**
+     * Where a loaded skill's body lands once activated. Defaults to
+     * `defineSkill`'s own default, `'auto'`. See {@link SurfaceMode}.
+     */
+    readonly surfaceMode?: SurfaceMode;
+}
+/**
+ * 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); or when two files claim the same skill name
+ *   (the message names both).
+ */
+export declare function skillsFromDir(dir: string, opts?: SkillsFromDirOptions): Promise<readonly Injection[]>;

package/dist/esm/lib/injection-engine/skillsFromDir.js

@@ -0,0 +1,243 @@
+/**
+ * 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.
+ *
+ * ── 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.
+ *
+ * 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/injection-engine` barrel, and a TOP-LEVEL node:fs
+ * import detonates a browser bundle at module-eval even when nothing calls it.
+ */
+import { defineSkill } from './factories/defineSkill.js';
+/** The file name every skill folder is expected to use. */
+const SKILL_FILE = 'SKILL.md';
+/**
+ * Skill ids ride into `read_skill`'s `enum` and into the skill-graph's node
+ * ids. The house tool-name charset keeps them quotable in a prompt, comparable
+ * as plain strings, and safe as an object key.
+ */
+const SKILL_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
+/** Anything of the form `scheme://…` — http, https, s3, git+ssh, file, … */
+const URL_LIKE_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
+/**
+ * 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); or when two files claim the same skill name
+ *   (the message names both).
+ */
+export async function skillsFromDir(dir, opts = {}) {
+    assertLocalDirectoryArgument(dir);
+    // Lazy node imports (browser-compat) — see module header.
+    const { readdir, readFile, stat } = await import('node:fs/promises');
+    const { join } = await import('node:path');
+    let isDirectory = false;
+    try {
+        isDirectory = (await stat(dir)).isDirectory();
+    }
+    catch {
+        throw new Error(`skillsFromDir: '${dir}' does not exist. Pass the directory that holds your ` +
+            `${SKILL_FILE} folders.`);
+    }
+    if (!isDirectory) {
+        throw new Error(`skillsFromDir: '${dir}' is a file, not a directory. Pass the directory that holds ` +
+            `your ${SKILL_FILE} folders.`);
+    }
+    const entries = await readdir(dir, { withFileTypes: true });
+    const files = [];
+    // `dir/SKILL.md` — the whole directory is one skill.
+    if (entries.some((e) => e.isFile() && e.name === SKILL_FILE)) {
+        files.push(join(dir, SKILL_FILE));
+    }
+    // `dir/<folder>/SKILL.md` — the portable layout.
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const candidate = join(dir, entry.name, SKILL_FILE);
+        try {
+            if ((await stat(candidate)).isFile())
+                files.push(candidate);
+        }
+        catch {
+            // A subdirectory without a SKILL.md is not an error — a skill folder can
+            // sit next to assets, fixtures, or anything else the author keeps here.
+        }
+    }
+    if (files.length === 0) {
+        throw new Error(`skillsFromDir: no ${SKILL_FILE} found under '${dir}'. Expected '${dir}/<skill>/${SKILL_FILE}' ` +
+            `or '${dir}/${SKILL_FILE}'.`);
+    }
+    const parsed = [];
+    for (const file of files.sort()) {
+        parsed.push(parseSkillFile(await readFile(file, 'utf8'), file));
+    }
+    // Collisions are refused naming BOTH files: with only the id in the message
+    // you would know a duplicate exists and still have to go find the pair.
+    const byName = new Map();
+    for (const skill of parsed) {
+        const clash = byName.get(skill.name);
+        if (clash) {
+            throw new Error(`skillsFromDir: two files claim the skill name '${skill.name}' — '${clash.file}' and ` +
+                `'${skill.file}'. Skill ids must be unique (read_skill dispatches by id); rename one.`);
+        }
+        byName.set(skill.name, skill);
+    }
+    return parsed
+        .slice()
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+        .map((skill) => defineSkill({
+        id: skill.name,
+        description: skill.description,
+        body: skill.body,
+        ...(opts.viaToolName !== undefined && { viaToolName: opts.viaToolName }),
+        ...(opts.surfaceMode !== undefined && { surfaceMode: opts.surfaceMode }),
+    }));
+}
+// ─── Authorship guard ──────────────────────────────────────────────
+/**
+ * Refuse anything that is not a local path, BY NAME. The message quotes what
+ * was passed, because the whole point is that the reader can see the thing
+ * that was rejected.
+ */
+function assertLocalDirectoryArgument(dir) {
+    if (typeof dir !== 'string' || dir.trim().length === 0) {
+        throw new Error(`skillsFromDir: expected a local directory path, got ${JSON.stringify(dir)}.`);
+    }
+    const scheme = URL_LIKE_RE.exec(dir);
+    if (scheme) {
+        throw new Error(`skillsFromDir: '${dir}' is a ${scheme[0].slice(0, -3)} URL, not a local directory. ` +
+            `Skill bodies are instructions to a model, so this loader only reads files you own ` +
+            `at build time — fetch remote content yourself, review it, and pass defineSkill(...) ` +
+            `the result.`);
+    }
+    if (dir.startsWith('\\\\')) {
+        throw new Error(`skillsFromDir: '${dir}' is a network (UNC) path, not a local directory. ` +
+            `Skill bodies are instructions to a model, so this loader only reads files you own ` +
+            `at build time.`);
+    }
+}
+// ─── Frontmatter ───────────────────────────────────────────────────
+/**
+ * Parse one `SKILL.md`. Every refusal names the file — a loader that says
+ * "malformed frontmatter" over a directory of forty files has told you nothing.
+ *
+ * The grammar is deliberately small: an opening `---` line, `key: value` lines
+ * (`#` comments and blank lines skipped, single/double quotes stripped), a
+ * closing `---` line, then the body. Keys other than `name` and `description`
+ * are IGNORED rather than rejected, so a file carrying extra frontmatter for
+ * another tool still loads here.
+ */
+function parseSkillFile(raw, file) {
+    // Strip a UTF-8 BOM — an editor artifact, not the author's intent.
+    const text = raw.charCodeAt(0) === 0xfeff ? raw.slice(1) : raw;
+    const lines = text.split(/\r?\n/);
+    if (lines[0]?.trim() !== '---') {
+        throw new Error(`skillsFromDir: '${file}' does not start with a '---' frontmatter block. ` +
+            `Expected:\n---\nname: my-skill\ndescription: When to use it.\n---\n<the body>`);
+    }
+    const closingIndex = lines.findIndex((line, i) => i > 0 && line.trim() === '---');
+    if (closingIndex === -1) {
+        throw new Error(`skillsFromDir: '${file}' opens a '---' frontmatter block that is never closed. ` +
+            `Add a '---' line after the last frontmatter key.`);
+    }
+    const fields = new Map();
+    for (let i = 1; i < closingIndex; i++) {
+        const line = lines[i] ?? '';
+        if (line.trim().length === 0 || line.trimStart().startsWith('#'))
+            continue;
+        const separator = line.indexOf(':');
+        if (separator === -1) {
+            throw new Error(`skillsFromDir: '${file}' frontmatter line ${i + 1} is not 'key: value' — got ` +
+                `${JSON.stringify(line)}.`);
+        }
+        const key = line.slice(0, separator).trim();
+        if (key.length === 0) {
+            throw new Error(`skillsFromDir: '${file}' frontmatter line ${i + 1} has an empty key — got ` +
+                `${JSON.stringify(line)}.`);
+        }
+        fields.set(key, unquote(line.slice(separator + 1).trim()));
+    }
+    const name = fields.get('name') ?? '';
+    const description = fields.get('description') ?? '';
+    const body = lines
+        .slice(closingIndex + 1)
+        .join('\n')
+        .trim();
+    if (name.length === 0) {
+        throw new Error(`skillsFromDir: '${file}' frontmatter is missing 'name'. It becomes the skill id the ` +
+            `model passes to read_skill.`);
+    }
+    if (!SKILL_NAME_RE.test(name)) {
+        throw new Error(`skillsFromDir: '${file}' frontmatter name '${name}' must match ` +
+            `/^[a-zA-Z0-9_-]{1,64}$/ — it is the id the model passes to read_skill.`);
+    }
+    if (description.length === 0) {
+        throw new Error(`skillsFromDir: '${file}' frontmatter is missing 'description'. It is the ONLY thing ` +
+            `the model reads when deciding whether to open this skill.`);
+    }
+    if (body.length === 0) {
+        throw new Error(`skillsFromDir: '${file}' has no body after the closing '---'. The body is what the ` +
+            `model reads once it activates the skill.`);
+    }
+    return { name, description, body, file };
+}
+/** Strip one layer of matching single or double quotes from a YAML-ish scalar. */
+function unquote(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+//# sourceMappingURL=skillsFromDir.js.map