@zenera/neo 1.1.0

package/dist/runner.js

@@ -0,0 +1,537 @@
+import { Agent, AgentRegistry } from "./agent.js";
+import { describeArchitecture } from "./architecture.js";
+import { EventQueue, RunStream, } from "./events.js";
+import { systemClock } from "./ids.js";
+import * as Kernel from "./kernel.js";
+import { renderMemories } from "./memory.js";
+import { PayloadResolver } from "./payload.js";
+import { Services } from "./services.js";
+import { activeSkillNames } from "./skills.js";
+import { lastText } from "./state.js";
+import { lastOfType, projectMessages, } from "./trajectory.js";
+import { isToolReturn, stringify, zeroUsage, } from "./types.js";
+const defaultJoinPolicy = {
+    summarize: (child, services) => lastText(child, services.payloads),
+    onBranchError: 'continue',
+};
+/** Used when no summarizer is configured: says what went, spends no tokens. */
+const structuralSummarizer = {
+    summarize(nodes, reason) {
+        const counts = new Map();
+        for (const n of nodes) {
+            counts.set(n.type, (counts.get(n.type) ?? 0) + 1);
+        }
+        const what = [...counts].map(([type, n]) => `${n}\u00d7 ${type}`).join(', ');
+        return Promise.resolve(`[${reason}] ${nodes.length} earlier steps were dropped: ${what}.`);
+    },
+};
+const SUMMARY_INSTRUCTIONS = 'You compress an agent transcript. Rewrite the excerpt below as a short plain-text ' +
+    'briefing that preserves every decision, fact and open question a successor would ' +
+    'need. Do not add commentary and do not invent detail.';
+/** A summarizer that asks a model, so the compaction node holds real prose. */
+export function modelSummarizer(model, instructions = SUMMARY_INSTRUCTIONS) {
+    return {
+        async summarize(nodes, reason, services) {
+            // The summarizer reads exactly what the model read.
+            const { messages } = await projectMessages(nodes, services.payloads);
+            const req = {
+                system: instructions,
+                messages: [
+                    ...messages,
+                    {
+                        role: 'user',
+                        content: [{ type: 'text', text: `Summarize the above (${reason}).` }],
+                    },
+                ],
+                tools: [],
+                toolChoice: 'auto',
+            };
+            const res = await model.generate(req);
+            return { text: res.text, usage: res.usage };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+/**
+ * The driver: it owns all nondeterminism and all I/O, and calls the kernel to
+ * advance the state. Every checkpoint event carries a complete snapshot, so a
+ * consumer can persist it and later `resume()` from exactly that point.
+ *
+ * There is no turn budget. A run ends on a final answer, an abort or an
+ * unrecoverable error.
+ */
+export class AgentRunner {
+    registry = new AgentRegistry();
+    services;
+    #model;
+    #context;
+    #handoffPolicy;
+    #summarizer;
+    #joinPolicy;
+    #stream;
+    #recordRequests;
+    #clock;
+    constructor(opts = {}) {
+        this.#model = opts.model;
+        this.#context = opts.context;
+        this.services =
+            opts.services ??
+                new Services({
+                    payloads: opts.payloads,
+                    memory: opts.memory,
+                    skills: opts.skills,
+                });
+        this.#handoffPolicy = opts.handoffPolicy;
+        this.#summarizer = opts.summarizer ?? structuralSummarizer;
+        this.#joinPolicy = opts.joinPolicy ?? defaultJoinPolicy;
+        this.#stream = opts.stream ?? true;
+        this.#recordRequests = opts.recordRequests ?? false;
+        this.#clock = opts.clock ?? systemClock;
+    }
+    /** Registers agents; chainable. */
+    add(...agents) {
+        this.registry.add(...agents);
+        return this;
+    }
+    /** Creates + registers + returns an agent in one call. */
+    agent(opts) {
+        return this.registry.agent(opts);
+    }
+    get(name) {
+        return this.registry.get(name);
+    }
+    /**
+     * The declared wiring as plain JSON: agents, their tools, skills, memory
+     * and hand-offs. It lives here rather than on the registry because three
+     * of those answers are the runner's: the fallback model, the skill
+     * catalogs behind `services`, and the context that resolves memory scopes.
+     */
+    describe() {
+        return describeArchitecture(this.registry, {
+            services: this.services,
+            defaultModel: this.#model,
+            context: this.#context,
+        });
+    }
+    /**
+     * Starts a new run. State creation is explicit inside, so the first event a
+     * consumer sees (`run_created`) already carries a persistable snapshot.
+     */
+    run(agent, input, opts = {}) {
+        // Generators are lazy: nothing executes until the stream is iterated or
+        // awaited, so building a RunStream costs nothing.
+        return new RunStream(this.#start(agent, input, opts));
+    }
+    /** Continues a persisted run from its own snapshot. */
+    resume(state, opts = {}) {
+        return new RunStream(this.#drive(state, opts));
+    }
+    /** Adds a follow-up message to a finished (or paused) run and continues it. */
+    send(state, input, opts = {}) {
+        return new RunStream(this.#sendAndDrive(state, input, opts));
+    }
+    async *#sendAndDrive(state, input, opts) {
+        const next = await Kernel.applyUserInput(state, input, this.#env(opts));
+        return yield* this.#drive(next, opts);
+    }
+    #env(opts) {
+        return {
+            services: this.services,
+            output: opts.output,
+            clock: this.#clock,
+        };
+    }
+    async *#start(agent, input, opts) {
+        const name = typeof agent === 'string' ? agent : agent.name;
+        this.registry.get(name);
+        const state = await Kernel.createState({
+            agent: name,
+            input,
+            context: (opts.context ?? this.#context),
+            output: opts.output,
+            maxForkDepth: opts.maxForkDepth,
+        }, this.#env(opts));
+        yield tag(state, undefined, { type: 'run_created', state });
+        return yield* this.#drive(state, opts);
+    }
+    /**
+     * The loop. `state` is reassigned rather than mutated: every kernel call
+     * returns a fresh object, so the snapshot inside an already-emitted event
+     * stays valid.
+     */
+    async *#drive(initial, opts) {
+        const env = this.#env(opts);
+        Kernel.checkOutputSchema(initial, env);
+        const branch = opts.branch;
+        const signal = opts.signal;
+        let state = initial;
+        for (;;) {
+            if (signal?.aborted) {
+                return yield* this.#finish(state, branch, 'aborted');
+            }
+            const action = Kernel.nextAction(state);
+            switch (action.kind) {
+                case 'done':
+                    return yield* this.#finish(state, branch, 'final');
+                case 'llm': {
+                    state = await Kernel.applySystemPrompt(state, this.registry, env);
+                    state = await this.#preload(state, env);
+                    state = await this.#autoRecall(state, env);
+                    yield tag(state, branch, { type: 'before_llm_call', state });
+                    const req = await Kernel.buildRequest(state, this.registry, env);
+                    const digest = Kernel.requestDigest(req);
+                    const model = this.#modelFor(state);
+                    const deltas = new EventQueue();
+                    const call = (this.#stream && model.stream
+                        ? model.stream({ ...req, signal }, (d) => deltas.push(tag(state, branch, d)))
+                        : model.generate({ ...req, signal })).finally(() => deltas.close());
+                    // Deltas arrive in a callback, which a generator cannot
+                    // yield from; draining the queue while the call is in
+                    // flight bridges the two.
+                    yield* deltas.drain();
+                    const res = await call;
+                    const before = state;
+                    state = await Kernel.applyLlmResponse(state, res, model.id, env, {
+                        digest,
+                        request: this.#recordRequests ? req : undefined,
+                        registry: this.registry,
+                    });
+                    const node = appended(before, state).find((n) => n.type === 'llm_call');
+                    if (node) {
+                        yield tag(state, branch, { type: 'after_llm_call', state, node });
+                    }
+                    break;
+                }
+                case 'tools': {
+                    const tools = await Kernel.resolveTools(state, this.registry, env);
+                    for (const call of action.calls) {
+                        yield tag(state, branch, { type: 'before_tool_call', state, call });
+                        const was = state;
+                        const outcome = await this.#runTool(state, tools, call, opts);
+                        state = await Kernel.applyToolResult(state, call.callId, outcome, env);
+                        const added = appended(was, state);
+                        const node = added.find((n) => n.type === 'tool_result');
+                        if (node) {
+                            yield tag(state, branch, { type: 'after_tool_call', state, node });
+                        }
+                        const handoff = added.find((n) => n.type === 'handoff');
+                        if (handoff) {
+                            state = await this.#compactHandoff(state, handoff, env);
+                            yield tag(state, branch, {
+                                type: 'handoff',
+                                state,
+                                from: handoff.from,
+                                to: handoff.to,
+                            });
+                        }
+                    }
+                    break;
+                }
+                case 'fork': {
+                    const fork = state.trajectory.find((n) => n.type === 'fork' && n.callId === action.forkId);
+                    if (fork) {
+                        yield tag(state, branch, { type: 'before_fork', state, node: fork });
+                    }
+                    const results = yield* this.#runBranches(state, action, opts);
+                    const before = state;
+                    state = await Kernel.applyJoin(state, action.forkId, results, env);
+                    const node = appended(before, state).find((n) => n.type === 'join');
+                    if (node) {
+                        yield tag(state, branch, { type: 'after_join', state, node });
+                    }
+                    break;
+                }
+            }
+        }
+    }
+    /**
+     * Branches really run in parallel — each has its own model calls and its own
+     * tool executions. Their events are interleaved into the parent stream but
+     * stay demultiplexable through the `branch` tag, while their trajectories
+     * remain separate and ordered.
+     */
+    async *#runBranches(parent, action, opts) {
+        const env = this.#env(opts);
+        const queue = new EventQueue();
+        const siblings = new AbortController();
+        const signal = this.#joinPolicy.onBranchError === 'abort_siblings'
+            ? anySignal(opts.signal, siblings.signal)
+            : opts.signal;
+        const tasks = action.branches.map(async (plan) => {
+            const child = await Kernel.createChildState(parent, action.forkId, plan.name, env);
+            const ref = {
+                forkId: action.forkId,
+                name: plan.name,
+                runId: child.runId,
+                depth: child.spec.forkDepth,
+            };
+            queue.push(tag(parent, opts.branch, {
+                type: 'branch_started',
+                state: parent,
+                child: ref,
+                childState: child,
+            }));
+            // Branches are plain runs: tools, handoffs, memory, skills and even
+            // nested forks work inside them exactly as on the trunk.
+            const gen = this.#drive(child, {
+                ...opts,
+                output: undefined,
+                signal,
+                branch: ref,
+            });
+            let result;
+            let error;
+            try {
+                for (;;) {
+                    const step = await gen.next();
+                    if (step.done) {
+                        result = step.value;
+                        break;
+                    }
+                    queue.push(step.value);
+                }
+            }
+            catch (e) {
+                error = e instanceof Error ? e.message : String(e);
+                if (this.#joinPolicy.onBranchError === 'abort_siblings') {
+                    siblings.abort();
+                }
+            }
+            const childState = result?.state ?? child;
+            const status = error
+                ? 'error'
+                : result?.stopReason === 'aborted'
+                    ? 'aborted'
+                    : 'ok';
+            queue.push(tag(parent, opts.branch, {
+                type: 'branch_finished',
+                state: parent,
+                child: ref,
+                childState,
+                status,
+            }));
+            return {
+                name: plan.name,
+                status,
+                output: status === 'ok'
+                    ? await this.#joinPolicy.summarize(childState, this.services)
+                    : (error ?? ''),
+                error,
+                usage: childState.usage ?? zeroUsage(),
+                childRunId: child.runId,
+                childState,
+            };
+        });
+        const all = Promise.all(tasks).finally(() => queue.close());
+        yield* queue.drain();
+        return await all;
+    }
+    /**
+     * Collapses what the outgoing agent left behind. The nodes stay in the
+     * trajectory; only the projection replaces them with the summary.
+     */
+    async #compactHandoff(state, handoff, env) {
+        const nodes = this.#handoffPolicy?.select(state, handoff);
+        if (!nodes?.length) {
+            return state;
+        }
+        const summary = await this.#summarizer.summarize(nodes, 'handoff_noise', this.services);
+        const { text, usage } = typeof summary === 'string' ? { text: summary, usage: undefined } : summary;
+        return Kernel.applyCompaction(state, { covers: nodes.map((n) => n.id), summary: text, reason: 'handoff_noise', usage }, env);
+    }
+    /**
+     * Activates the current agent's `preload` skills, if they are not active
+     * already.
+     *
+     * Preloading is not a second mechanism: it appends the same `load_skills`
+     * node the `skill_load` tool does, so a preloaded skill and a
+     * model-loaded one are indistinguishable downstream — same projection,
+     * same unlocked tools.
+     *
+     * Checked before every call rather than once at `createState`, because
+     * `activeSkillNames` is scoped to the *current* agent. That one placement
+     * buys four behaviours: loaded before the first call; skipped with no I/O
+     * on every later turn; applied afresh when a hand-off makes another agent
+     * current, without inheriting the outgoing agent's set; and re-applied if
+     * compaction drops the activation. Self-healing for the same reason the
+     * tool gate is — both read the projected trajectory rather than a snapshot
+     * taken once.
+     *
+     * The node lands at the head of the transcript and never moves, so it sits
+     * inside the cached prefix from turn 0 — strictly cheaper than the model
+     * reaching for `skill_load` after its first reply.
+     *
+     * A name the catalog does not know throws. That is a configuration error,
+     * and callers that build agents from a file are expected to have validated
+     * it at load time rather than discovering it mid-run.
+     */
+    async #preload(state, env) {
+        const binding = this.registry.get(state.agentName).skills;
+        if (!binding?.preload?.length) {
+            return state;
+        }
+        const active = activeSkillNames(state);
+        const missing = binding.preload.filter((n) => !active.has(n));
+        if (!missing.length) {
+            return state;
+        }
+        const provider = this.services.skillProvider(binding.provider);
+        const skills = await Promise.all(missing.map((n) => provider.load(n)));
+        return Kernel.applySkillLoad(state, binding.provider, skills, env);
+    }
+    /**
+     * Auto-recall runs after new user input and after a hand-off, not before
+     * every call: recalling on every turn costs tokens and defeats prompt
+     * caching for a marginal gain.
+     */
+    async #autoRecall(state, env) {
+        const agent = this.registry.get(state.agentName);
+        const bindings = agent
+            .memoryBindings(state.context)
+            .filter((b) => b.autoRecall && b.autoRecall.query !== 'none');
+        if (!bindings.length || !shouldRecall(state)) {
+            return state;
+        }
+        const input = Kernel.lastUserInput(state);
+        if (!input) {
+            return state;
+        }
+        const parts = await Promise.all(input.content.map((p) => p.type === 'text' ? this.services.payloads.get(p.text) : Promise.resolve('')));
+        const query = parts.filter(Boolean).join('\n');
+        if (!query) {
+            return state;
+        }
+        let next = state;
+        for (const b of bindings) {
+            const hits = await this.services
+                .memoryStore(b.store)
+                .search(b.scope, { text: query, limit: b.autoRecall?.limit ?? 5 });
+            if (!hits.length) {
+                continue;
+            }
+            next = await Kernel.applyMemoryEffect(next, {
+                kind: 'recall',
+                store: b.store,
+                scope: b.scope,
+                query: { text: query, limit: b.autoRecall?.limit ?? 5 },
+                hits: hits.map((h) => ({
+                    id: h.record.id,
+                    score: h.score,
+                    revision: h.record.revision,
+                })),
+                content: renderMemories(hits),
+            }, env);
+        }
+        return next;
+    }
+    /**
+     * Failure-tolerant on purpose: an unknown tool, malformed arguments or a
+     * throwing implementation are all reported back to the model as ordinary
+     * tool output, so an otherwise recoverable run continues.
+     */
+    async #runTool(state, tools, call, opts) {
+        const started = Date.now();
+        const fail = (output) => ({
+            output,
+            isError: true,
+            durationMs: Date.now() - started,
+        });
+        const def = tools.find((t) => t.name === call.name);
+        if (!def) {
+            return fail(`error: unknown tool "${call.name}"`);
+        }
+        const raw = await this.services.payloads.get(call.args);
+        let args;
+        try {
+            args = JSON.parse(raw || '{}');
+        }
+        catch (e) {
+            return fail(`error: arguments are not valid JSON: ${String(e)}`);
+        }
+        try {
+            const out = await def.execute(args, {
+                ctx: state.context,
+                state,
+                agent: this.registry.get(state.agentName),
+                callId: call.callId,
+                services: this.services,
+                signal: opts.signal,
+            });
+            const effects = isToolReturn(out) ? out.effects : [];
+            const value = isToolReturn(out) ? out.output : out;
+            return {
+                output: stringify(value),
+                isError: false,
+                durationMs: Date.now() - started,
+                effects: effects.length ? effects : undefined,
+            };
+        }
+        catch (e) {
+            return fail(`error: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    #modelFor(state) {
+        const model = this.registry.get(state.agentName).model ?? this.#model;
+        if (!model) {
+            throw new Error(`no model configured for agent "${state.agentName}"`);
+        }
+        return model;
+    }
+    async *#finish(state, branch, stopReason) {
+        const final = lastOfType(state.trajectory, 'final_output');
+        const output = (state.spec.outputSchema && final && 'parsed' in final
+            ? final.parsed
+            : await lastText(state, this.services.payloads));
+        const result = {
+            output,
+            agent: state.agentName,
+            state,
+            usage: state.usage,
+            stopReason,
+        };
+        yield tag(state, branch, {
+            type: 'run_finished',
+            state,
+            result: result,
+        });
+        return result;
+    }
+}
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+function tag(state, branch, event) {
+    return { runId: state.runId, agent: state.agentName, branch, ...event };
+}
+/**
+ * What a kernel call just appended. The trajectory is append-only and `apply*`
+ * only ever appends, so the tail is exactly the new nodes — no backwards scan.
+ */
+function appended(before, after) {
+    return after.trajectory.slice(before.trajectory.length);
+}
+/** Recall after new user input or a hand-off, and never twice in a row. */
+function shouldRecall(state) {
+    const nodes = state.trajectory;
+    for (let i = nodes.length - 1; i >= 0; i--) {
+        const n = nodes[i];
+        if (n.type === 'system_prompt') {
+            continue;
+        }
+        if (n.type === 'memory_recall') {
+            return false;
+        }
+        return n.type === 'handoff' || (n.type === 'user_input' && !n.synthetic);
+    }
+    return false;
+}
+function anySignal(...signals) {
+    const present = signals.filter((s) => Boolean(s));
+    if (!present.length) {
+        return undefined;
+    }
+    return present.length === 1 ? present[0] : AbortSignal.any(present);
+}
+//# sourceMappingURL=runner.js.map

package/dist/services.d.ts

@@ -0,0 +1,23 @@
+import { PayloadResolver, type PayloadStore } from './payload.ts';
+import type { MemoryStore } from './memory.ts';
+import type { SkillProvider } from './skills.ts';
+/**
+ * The I/O the kernel is not allowed to do itself: payload resolution, memory
+ * backends and skill catalogs. Held by the driver (runner or Temporal
+ * activity) and handed to the kernel and to tools explicitly, so nothing reads
+ * ambient state.
+ */
+export declare class Services {
+    #private;
+    readonly payloads: PayloadResolver;
+    constructor(opts?: {
+        payloads?: PayloadResolver | PayloadStore;
+        memory?: MemoryStore[];
+        skills?: SkillProvider[];
+    });
+    memoryStore(id: string): MemoryStore;
+    skillProvider(id: string): SkillProvider;
+    hasMemory(id: string): boolean;
+    hasSkills(id: string): boolean;
+}
+//# sourceMappingURL=services.d.ts.map

package/dist/services.js

@@ -0,0 +1,44 @@
+import { PayloadResolver } from "./payload.js";
+import { InMemoryPayloadStore } from "./payload-stores/in-memory.js";
+/**
+ * The I/O the kernel is not allowed to do itself: payload resolution, memory
+ * backends and skill catalogs. Held by the driver (runner or Temporal
+ * activity) and handed to the kernel and to tools explicitly, so nothing reads
+ * ambient state.
+ */
+export class Services {
+    payloads;
+    #memory = new Map();
+    #skills = new Map();
+    constructor(opts = {}) {
+        const p = opts.payloads ?? new InMemoryPayloadStore();
+        this.payloads = p instanceof PayloadResolver ? p : new PayloadResolver(p);
+        for (const m of opts.memory ?? []) {
+            this.#memory.set(m.id, m);
+        }
+        for (const s of opts.skills ?? []) {
+            this.#skills.set(s.id, s);
+        }
+    }
+    memoryStore(id) {
+        const s = this.#memory.get(id);
+        if (!s) {
+            throw new Error(`unknown memory store: ${id} (known: ${[...this.#memory.keys()]})`);
+        }
+        return s;
+    }
+    skillProvider(id) {
+        const p = this.#skills.get(id);
+        if (!p) {
+            throw new Error(`unknown skill provider: ${id} (known: ${[...this.#skills.keys()]})`);
+        }
+        return p;
+    }
+    hasMemory(id) {
+        return this.#memory.has(id);
+    }
+    hasSkills(id) {
+        return this.#skills.has(id);
+    }
+}
+//# sourceMappingURL=services.js.map

package/dist/skill-providers/factory.d.ts

@@ -0,0 +1,16 @@
+import type { Skill, SkillProvider } from '../skills.ts';
+import { type FileSkillProviderOptions } from './file.ts';
+export interface StaticSkillProviderSpec {
+    kind: 'static';
+    id?: string;
+    skills: Skill[];
+}
+export interface FileSkillProviderSpec extends FileSkillProviderOptions {
+    kind: 'file';
+}
+/** Grows a member per source (`http`, `git`, …). */
+export type SkillProviderSpec = StaticSkillProviderSpec | FileSkillProviderSpec;
+/** Shorthand: `file:./skills`. The static provider needs its skills inline. */
+export type SkillProviderRef = SkillProviderSpec | string;
+export declare function createSkillProvider(ref: SkillProviderRef): SkillProvider;
+//# sourceMappingURL=factory.d.ts.map

package/dist/skill-providers/factory.js

@@ -0,0 +1,26 @@
+import { FileSkillProvider } from "./file.js";
+import { StaticSkillProvider } from "./static.js";
+export function createSkillProvider(ref) {
+    const spec = typeof ref === 'string' ? parseRef(ref) : ref;
+    switch (spec.kind) {
+        case 'static':
+            return new StaticSkillProvider(spec.skills, spec.id);
+        case 'file':
+            return new FileSkillProvider(spec);
+        default:
+            throw new TypeError(`unknown skill provider kind: ${spec.kind}`);
+    }
+}
+function parseRef(ref) {
+    const colon = ref.indexOf(':');
+    const scheme = colon < 0 ? ref : ref.slice(0, colon);
+    const rest = colon < 0 ? '' : ref.slice(colon + 1);
+    if (scheme === 'file') {
+        if (!rest) {
+            throw new TypeError(`missing directory in "${ref}" (expected file:<dir>)`);
+        }
+        return { kind: 'file', dir: rest };
+    }
+    throw new TypeError(`unknown skill provider ref: "${ref}"`);
+}
+//# sourceMappingURL=factory.js.map

package/dist/skill-providers/file.d.ts

@@ -0,0 +1,44 @@
+import type { Skill, SkillProvider, SkillSummary } from '../skills.ts';
+import { type AnyTool } from '../types.ts';
+export interface FileSkillProviderOptions {
+    /** one or more root directories holding `<name>.md` files and/or `<name>/SKILL.md` folders */
+    dir: string | string[];
+    /** logical provider id agents bind to; defaults to `file` */
+    id?: string;
+    /**
+     * Tools a skill may unlock, by name. Instructions can live in a file but
+     * code cannot, so a markdown skill declares `tools: [a, b]` in its
+     * frontmatter and the names are resolved against this registry — by name,
+     * by `<group>:*`, or `*` for all of them.
+     */
+    tools?: AnyTool<any>[];
+}
+/**
+ * Reads skills from disk. Two layouts, both discovered in one scan:
+ *
+ * ```
+ * <dir>/budget_travel.md          flat: frontmatter + body
+ * <dir>/budget_travel/SKILL.md    folder: sibling files become `resources`
+ * ```
+ *
+ * Frontmatter is a small subset of YAML — `key: value`, plus `[a, b]` lists
+ * for `tags` and `tools`. `name` defaults to the file or folder name and
+ * `description` to the first line of the body, so the minimum viable skill is
+ * a markdown file with no frontmatter at all.
+ */
+export declare class FileSkillProvider implements SkillProvider {
+    #private;
+    readonly id: string;
+    constructor(opts: FileSkillProviderOptions | string);
+    /** The first configured directory (kept for backwards compatibility). */
+    get dir(): string;
+    /** All configured directories. */
+    get dirs(): string[];
+    /** Drops the cached scan; call after editing skills on disk. */
+    refresh(): void;
+    list(): Promise<SkillSummary[]>;
+    search(query: string, limit?: number): Promise<SkillSummary[]>;
+    load(name: string, version?: string): Promise<Skill>;
+    tool(name: string): AnyTool<any> | undefined;
+}
+//# sourceMappingURL=file.d.ts.map