@zenera/neo 1.1.0

package/dist/skill-providers/file.js

@@ -0,0 +1,209 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { selectTools } from "../types.js";
+// ---------------------------------------------------------------------------
+// Filesystem-backed skill provider
+// ---------------------------------------------------------------------------
+const SKILL_FILE = 'SKILL.md';
+/**
+ * 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 class FileSkillProvider {
+    id;
+    #dirs;
+    #tools = new Map();
+    #index;
+    constructor(opts) {
+        const o = typeof opts === 'string' ? { dir: opts } : opts;
+        const raw = Array.isArray(o.dir) ? o.dir : [o.dir];
+        this.#dirs = raw.map((d) => resolve(d));
+        this.id = o.id ?? 'file';
+        for (const t of o.tools ?? []) {
+            this.#tools.set(t.name, t);
+        }
+    }
+    /** The first configured directory (kept for backwards compatibility). */
+    get dir() {
+        return this.#dirs[0];
+    }
+    /** All configured directories. */
+    get dirs() {
+        return [...this.#dirs];
+    }
+    /** Drops the cached scan; call after editing skills on disk. */
+    refresh() {
+        this.#index = undefined;
+    }
+    async list() {
+        const index = await this.#scan();
+        return [...index.values()]
+            .map((e) => e.summary)
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async search(query, limit = 8) {
+        const q = query.toLowerCase();
+        const all = await this.list();
+        return all
+            .filter((s) => s.name.toLowerCase().includes(q) ||
+            s.description.toLowerCase().includes(q) ||
+            (s.tags ?? []).some((t) => t.toLowerCase().includes(q)))
+            .slice(0, limit);
+    }
+    async load(name, version) {
+        const entry = (await this.#scan()).get(name);
+        if (!entry) {
+            throw new Error(`unknown skill: ${name}`);
+        }
+        const { version: found } = entry.summary;
+        if (version && found && found !== version) {
+            throw new Error(`skill ${name} is at ${found}, ${version} was requested`);
+        }
+        const tools = selectTools([...this.#tools.values()], entry.summary.toolNames ?? [], {
+            where: `skill "${name}"`,
+            hint: `register it on provider "${this.id}"`,
+        });
+        return {
+            ...entry.summary,
+            content: entry.content,
+            file: entry.file,
+            ...(tools.length ? { tools } : {}),
+            ...(entry.folder ? { resources: await readResources(entry.folder) } : {}),
+        };
+    }
+    tool(name) {
+        return this.#tools.get(name);
+    }
+    /** One scan, memoized: `list` runs on every `skill_load`. */
+    #scan() {
+        this.#index ??= this.#read();
+        return this.#index;
+    }
+    async #read() {
+        const index = new Map();
+        for (const dir of this.#dirs) {
+            let items;
+            try {
+                items = await readdir(dir, { withFileTypes: true });
+            }
+            catch (err) {
+                if (err.code === 'ENOENT') {
+                    continue;
+                }
+                throw err;
+            }
+            for (const item of items) {
+                const folder = item.isDirectory() ? join(dir, item.name) : undefined;
+                const file = folder ? join(folder, SKILL_FILE) : join(dir, item.name);
+                if (!folder && !(item.isFile() && item.name.endsWith('.md'))) {
+                    continue;
+                }
+                const raw = await readOptional(file);
+                if (raw === undefined) {
+                    continue;
+                }
+                const base = folder ? item.name : item.name.slice(0, -'.md'.length);
+                const entry = parse(raw, base, file, folder);
+                index.set(entry.summary.name, entry);
+            }
+        }
+        return index;
+    }
+}
+function parse(raw, base, file, folder) {
+    const { data, body } = frontmatter(raw);
+    const tags = toList(data.tags);
+    const tools = toList(data.tools);
+    return {
+        file,
+        folder,
+        content: body,
+        summary: {
+            name: data.name || base,
+            description: data.description || firstLine(body),
+            ...(tags.length ? { tags } : {}),
+            ...(data.version ? { version: data.version } : {}),
+            ...(tools.length ? { toolNames: tools } : {}),
+        },
+    };
+}
+/** Sibling files of a `SKILL.md`, top level only, keyed by filename. */
+async function readResources(folder) {
+    const out = {};
+    for (const item of await readdir(folder, { withFileTypes: true })) {
+        if (!item.isFile() || item.name === SKILL_FILE) {
+            continue;
+        }
+        const value = await readOptional(join(folder, item.name));
+        if (value !== undefined) {
+            out[item.name] = value;
+        }
+    }
+    return out;
+}
+async function readOptional(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (err) {
+        const code = err.code;
+        // ENOENT: a folder without a SKILL.md is simply not a skill.
+        // EISDIR: a `<name>.md` directory is not one either.
+        if (code === 'ENOENT' || code === 'EISDIR') {
+            return undefined;
+        }
+        throw err;
+    }
+}
+/**
+ * Deliberately not a YAML parser: `key: value` and flow lists cover what a
+ * skill header needs, and a real dependency would buy nothing.
+ */
+function frontmatter(raw) {
+    const m = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(raw);
+    if (!m) {
+        return { data: {}, body: raw.trim() };
+    }
+    const data = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const i = line.indexOf(':');
+        const key = i < 0 ? '' : line.slice(0, i).trim();
+        if (!key || key.startsWith('#')) {
+            continue;
+        }
+        data[key] = unquote(line.slice(i + 1).trim());
+    }
+    return { data, body: raw.slice(m[0].length).trim() };
+}
+function toList(value) {
+    if (!value) {
+        return [];
+    }
+    const inner = value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1) : value;
+    return inner
+        .split(',')
+        .map((v) => unquote(v.trim()))
+        .filter(Boolean);
+}
+function unquote(value) {
+    const quoted = (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"));
+    return quoted && value.length > 1 ? value.slice(1, -1) : value;
+}
+function firstLine(body) {
+    return (body
+        .split(/\r?\n/)
+        .find((l) => l.trim())
+        ?.replace(/^#+\s*/, '')
+        .trim() ?? '');
+}
+//# sourceMappingURL=file.js.map

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

@@ -0,0 +1,4 @@
+export * from './factory.ts';
+export * from './file.ts';
+export * from './static.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/skill-providers/index.js

@@ -0,0 +1,5 @@
+// Sources for the `SkillProvider` contract in `../skills.ts`.
+export * from "./factory.js";
+export * from "./file.js";
+export * from "./static.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,13 @@
+import type { Skill, SkillProvider, SkillSummary } from '../skills.ts';
+import type { AnyTool } from '../types.ts';
+/** Skills handed over in code, held in a map. No I/O, no catalog to scan. */
+export declare class StaticSkillProvider implements SkillProvider {
+    #private;
+    readonly id: string;
+    constructor(skills?: Skill[], id?: string);
+    list(): Promise<SkillSummary[]>;
+    search(query: string, limit?: number): Promise<SkillSummary[]>;
+    load(name: string, version?: string): Promise<Skill>;
+    tool(name: string): AnyTool<any> | undefined;
+}
+//# sourceMappingURL=static.d.ts.map

package/dist/skill-providers/static.js

@@ -0,0 +1,47 @@
+/** Skills handed over in code, held in a map. No I/O, no catalog to scan. */
+export class StaticSkillProvider {
+    id;
+    #skills = new Map();
+    #tools = new Map();
+    constructor(skills = [], id = 'static') {
+        this.id = id;
+        for (const s of skills) {
+            this.#skills.set(s.name, s);
+            for (const t of s.tools ?? []) {
+                this.#tools.set(t.name, t);
+            }
+        }
+    }
+    async list() {
+        return [...this.#skills.values()].map(({ name, description, tags, version, tools }) => ({
+            name,
+            description,
+            tags,
+            version,
+            toolNames: tools?.length ? tools.map((t) => t.name) : undefined,
+        }));
+    }
+    async search(query, limit = 8) {
+        const q = query.toLowerCase();
+        const all = await this.list();
+        return all
+            .filter((s) => s.name.toLowerCase().includes(q) ||
+            s.description.toLowerCase().includes(q) ||
+            (s.tags ?? []).some((t) => t.toLowerCase().includes(q)))
+            .slice(0, limit);
+    }
+    async load(name, version) {
+        const s = this.#skills.get(name);
+        if (!s) {
+            throw new Error(`unknown skill: ${name}`);
+        }
+        if (version && s.version && s.version !== version) {
+            throw new Error(`skill ${name} is at ${s.version}, ${version} was requested`);
+        }
+        return s;
+    }
+    tool(name) {
+        return this.#tools.get(name);
+    }
+}
+//# sourceMappingURL=static.js.map

package/dist/skills.d.ts

@@ -0,0 +1,102 @@
+import type { AgentState } from './state.ts';
+import { type AnyTool } from './types.ts';
+export interface SkillSummary {
+    name: string;
+    /** one line — this is what search and the prompt index see */
+    description: string;
+    tags?: string[];
+    version?: string;
+    /**
+     * Tools this skill unlocks, by name. On the *summary* rather than only on
+     * the loaded skill, because the declared tool set has to be known before
+     * anything is loaded — see `lockedSkillTools`. Names only: a summary comes
+     * from a cheap index, and code cannot live in one.
+     */
+    toolNames?: string[];
+}
+/**
+ * Note on the spec: `content` is a plain string here rather than a `Payload`,
+ * because a provider is a content source and must not need a payload store.
+ * The kernel offloads it when the activation is recorded in the trajectory.
+ */
+export interface Skill extends SkillSummary {
+    content: string;
+    /** tools unlocked while the skill is active; the context type is the host agent's */
+    tools?: AnyTool<any>[];
+    resources?: Record<string, string>;
+    /** absolute path of the source file, if known (set by file-backed providers) */
+    file?: string;
+}
+export interface SkillProvider {
+    readonly id: string;
+    /** cheap index */
+    list(): Promise<SkillSummary[]>;
+    search(query: string, limit?: number): Promise<SkillSummary[]>;
+    /** full content */
+    load(name: string, version?: string): Promise<Skill>;
+    /**
+     * Resolves a tool name declared by some skill in this catalog to its
+     * implementation, *without* loading the skill. The declared tool set is
+     * built from this, so it must not depend on what is currently active.
+     */
+    tool(name: string): AnyTool<any> | undefined;
+}
+export interface SkillBinding {
+    /** SkillProvider id */
+    provider: string;
+    /**
+     * 'index'  — names + descriptions rendered into the system prompt.
+     * 'search' — only a `skill_search` tool; nothing pre-rendered.
+     * 'none'   — preloads only.
+     */
+    discovery: 'index' | 'search' | 'none';
+    /** always loaded at run start, before the first LLM call */
+    preload?: string[];
+    maxIndexEntries?: number;
+    allow?: string[] | ((s: SkillSummary) => boolean);
+}
+export interface SkillLoadSpec {
+    kind: 'skill_load';
+    provider: string;
+    skills: Skill[];
+}
+export declare function skillContentHash(s: Skill): string;
+export declare function renderSkills(skills: Skill[]): string;
+export declare function renderSkillIndex(summaries: SkillSummary[], max: number): string;
+export declare function allows(binding: SkillBinding, s: SkillSummary): boolean;
+/**
+ * Skills activated by still-projected `load_skills` nodes of the active agent.
+ *
+ * Reads the names straight off the nodes rather than re-loading the skills: an
+ * activation records what it activated, so the provider has nothing left to
+ * say, and a gate that did I/O could not be a plain predicate.
+ *
+ * Exported because `preload` needs exactly the same answer: "what is active for
+ * this agent, right now?" One derivation, so a preloaded skill and a
+ * model-loaded one are indistinguishable to the gate.
+ */
+export declare function activeSkillNames(state: AgentState): Set<string>;
+/** Thrown by a locked tool whose skill is not active. Reaches the model as an ordinary error result. */
+export declare class SkillRequiredError extends Error {
+    readonly code = "SKILL_REQUIRED";
+    readonly tool: string;
+    /** every skill that unlocks this tool, in catalog order */
+    readonly candidates: SkillSummary[];
+    constructor(tool: string, candidates: SkillSummary[]);
+}
+/**
+ * Every tool the binding's catalog can unlock, each gated on its own skills.
+ * Depends on `binding` and the catalog, never on the trajectory \u2014 which is what
+ * keeps the declared set stable across turns.
+ *
+ * `exclude` is the host agent's own tool names: an agent-level tool of the same
+ * name wins and is never gated.
+ */
+export declare function lockedSkillTools<TCtx>(binding: SkillBinding, provider: SkillProvider, exclude?: ReadonlySet<string>): Promise<AnyTool<TCtx>[]>;
+/**
+ * `skill_load` deliberately returns a short acknowledgement: the instructions
+ * themselves reach the model through the `LoadSkillsNode` projection, so they
+ * are not duplicated in the tool result and can be compacted independently.
+ */
+export declare function skillTools<TCtx>(binding: SkillBinding): AnyTool<TCtx>[];
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.js

@@ -0,0 +1,232 @@
+import { hash } from "./payload.js";
+import { projected } from "./trajectory.js";
+import { SKILL_LOAD_TOOL, SKILL_SEARCH_TOOL, tool, withEffects, } from "./types.js";
+export function skillContentHash(s) {
+    return hash(s.content);
+}
+export function renderSkills(skills) {
+    return skills
+        .map((s) => `## Skill: ${s.name}${s.version ? ` (${s.version})` : ''}\n${s.content}`)
+        .join('\n\n');
+}
+export function renderSkillIndex(summaries, max) {
+    const shown = summaries.slice(0, max);
+    if (!shown.length) {
+        return '';
+    }
+    const lines = shown.map((s) => `- ${s.name}: ${s.description}`);
+    return (`Available skills (load with the \`${SKILL_LOAD_TOOL}\` tool before ` +
+        `relying on them):\n${lines.join('\n')}`);
+}
+export function allows(binding, s) {
+    if (!binding.allow) {
+        return true;
+    }
+    return typeof binding.allow === 'function' ? binding.allow(s) : binding.allow.includes(s.name);
+}
+// ---------------------------------------------------------------------------
+// Locked tools
+//
+// A tool a skill unlocks is declared to the model from the first turn and never
+// withdrawn; only its *execution* is gated. The alternative \u2014 appending the
+// tool once its skill activates \u2014 mutates the `tools` array mid-conversation,
+// and since tool definitions are serialized ahead of the system prompt and the
+// transcript, that puts the first differing token near position 0 and costs a
+// full re-read of the entire context at exactly the point where it is largest.
+//
+// So the gate lives in the closure, never in the schema: `name`, `description`
+// and `parameters` are derived from the catalog alone and are byte-identical on
+// every turn.
+//
+// The gate itself captures nothing. It reads the trajectory it is handed at the
+// moment of the call, which makes `lockedSkillTools` a pure function of the
+// binding and the catalog — the stability the cache depends on is then a
+// property of the code rather than a discipline callers have to keep.
+// ---------------------------------------------------------------------------
+/**
+ * Skills activated by still-projected `load_skills` nodes of the active agent.
+ *
+ * Reads the names straight off the nodes rather than re-loading the skills: an
+ * activation records what it activated, so the provider has nothing left to
+ * say, and a gate that did I/O could not be a plain predicate.
+ *
+ * Exported because `preload` needs exactly the same answer: "what is active for
+ * this agent, right now?" One derivation, so a preloaded skill and a
+ * model-loaded one are indistinguishable to the gate.
+ */
+export function activeSkillNames(state) {
+    const out = new Set();
+    for (const n of projected(state.trajectory)) {
+        if (n.type === 'load_skills' && n.agent === state.agentName) {
+            for (const s of n.skills) {
+                out.add(s.name);
+            }
+        }
+    }
+    return out;
+}
+/** Thrown by a locked tool whose skill is not active. Reaches the model as an ordinary error result. */
+export class SkillRequiredError extends Error {
+    code = 'SKILL_REQUIRED';
+    tool;
+    /** every skill that unlocks this tool, in catalog order */
+    candidates;
+    constructor(tool, candidates) {
+        super(skillRequiredMessage(tool, candidates));
+        this.name = 'SkillRequiredError';
+        this.tool = tool;
+        this.candidates = candidates;
+    }
+}
+/**
+ * With one candidate the model has nothing to decide, so the message is an
+ * instruction. With several it does, so the message states the choice and
+ * carries each description \u2014 under `discovery: 'search'` there is no index in
+ * the prompt, and this error is the only place those descriptions appear.
+ */
+function skillRequiredMessage(tool, candidates) {
+    if (candidates.length === 1) {
+        const { name } = candidates[0];
+        return (`PREREQUISITE_MISSING: "${tool}" requires the "${name}" skill. ` +
+            `Call ${SKILL_LOAD_TOOL}({"names":["${name}"]}), then retry this call.`);
+    }
+    const lines = candidates.map((c) => `  - ${c.name}: ${c.description}`);
+    return (`PREREQUISITE_MISSING: "${tool}" requires at least one of these skills to be ` +
+        `loaded first:\n${lines.join('\n')}\n` +
+        'Decide which one applies to this call. If the case spans more than one, load ' +
+        `them together. Then call ${SKILL_LOAD_TOOL}({"names":[...]}) and retry this call.`);
+}
+function lockedDescription(inner, candidates) {
+    const names = candidates.map((c) => `"${c.name}"`);
+    const note = names.length === 1
+        ? `Unlocked by the ${names[0]} skill; load it with \`${SKILL_LOAD_TOOL}\` first.`
+        : `Unlocked by any of: ${names.join(', ')}; ` +
+            `load whichever applies with \`${SKILL_LOAD_TOOL}\` first.`;
+    return inner.description ? `${inner.description} (${note})` : note;
+}
+function lock(inner, candidates) {
+    return {
+        name: inner.name,
+        description: lockedDescription(inner, candidates),
+        parameters: inner.parameters,
+        // The three fields above are all the model is sent, and none of them can
+        // see the run. The state enters here and only here, per call.
+        execute: (args, tc) => {
+            const active = activeSkillNames(tc.state);
+            if (!candidates.some((c) => active.has(c.name))) {
+                throw new SkillRequiredError(inner.name, candidates);
+            }
+            return inner.execute(args, tc);
+        },
+    };
+}
+/**
+ * Every tool the binding's catalog can unlock, each gated on its own skills.
+ * Depends on `binding` and the catalog, never on the trajectory \u2014 which is what
+ * keeps the declared set stable across turns.
+ *
+ * `exclude` is the host agent's own tool names: an agent-level tool of the same
+ * name wins and is never gated.
+ */
+export async function lockedSkillTools(binding, provider, exclude) {
+    const index = (await provider.list())
+        .filter((s) => allows(binding, s))
+        // Not every provider promises an order; the declared tool list must not
+        // depend on one that varies.
+        .sort((a, b) => a.name.localeCompare(b.name));
+    // name -> every skill declaring it. Two owners need no tie-break: either one
+    // being active is enough, and both are offered when neither is.
+    const owners = new Map();
+    for (const summary of index) {
+        for (const name of summary.toolNames ?? []) {
+            if (exclude?.has(name)) {
+                continue;
+            }
+            const known = owners.get(name);
+            if (known) {
+                known.push(summary);
+            }
+            else {
+                owners.set(name, [summary]);
+            }
+        }
+    }
+    const out = [];
+    for (const [name, candidates] of owners) {
+        const inner = provider.tool(name);
+        if (!inner) {
+            // A catalog naming a tool nobody implements is a configuration
+            // error, but throwing here would fail every turn of every run that
+            // touches the provider, which is worse than leaving it undeclared.
+            console.warn(`skill provider "${provider.id}": no implementation for tool "${name}" ` +
+                `(declared by ${candidates.map((c) => c.name).join(', ')})`);
+            continue;
+        }
+        out.push(lock(inner, candidates));
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Built-in skill tools
+// ---------------------------------------------------------------------------
+/**
+ * `skill_load` deliberately returns a short acknowledgement: the instructions
+ * themselves reach the model through the `LoadSkillsNode` projection, so they
+ * are not duplicated in the tool result and can be compacted independently.
+ */
+export function skillTools(binding) {
+    const tools = [
+        tool({
+            name: SKILL_LOAD_TOOL,
+            description: 'Load skill instructions (and any tools they unlock) into the context.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    names: { type: 'array', items: { type: 'string' }, minItems: 1 },
+                },
+                required: ['names'],
+                additionalProperties: false,
+            },
+            execute: async (args, tc) => {
+                const provider = tc.services.skillProvider(binding.provider);
+                const index = await provider.list();
+                const loaded = [];
+                for (const name of args.names) {
+                    const summary = index.find((s) => s.name === name);
+                    if (summary && !allows(binding, summary)) {
+                        throw new Error(`skill "${name}" is not available to this agent`);
+                    }
+                    loaded.push(await provider.load(name, summary?.version));
+                }
+                // Two skills may declare the same tool; it is unlocked once.
+                const unlocked = [
+                    ...new Set(loaded.flatMap((s) => (s.tools ?? []).map((t) => t.name))),
+                ];
+                return withEffects(`loaded: ${loaded.map((s) => s.name).join(', ')}` +
+                    (unlocked.length ? `; tools unlocked: ${unlocked.join(', ')}` : ''), {
+                    kind: 'skill_load',
+                    spec: { kind: 'skill_load', provider: provider.id, skills: loaded },
+                });
+            },
+        }),
+    ];
+    if (binding.discovery === 'search') {
+        tools.push(tool({
+            name: SKILL_SEARCH_TOOL,
+            description: 'Find skills by topic before loading them.',
+            parameters: {
+                type: 'object',
+                properties: { query: { type: 'string' }, limit: { type: 'integer' } },
+                required: ['query'],
+                additionalProperties: false,
+            },
+            execute: async (args, tc) => {
+                const provider = tc.services.skillProvider(binding.provider);
+                const found = await provider.search(args.query, args.limit);
+                return found.filter((s) => allows(binding, s));
+            },
+        }));
+    }
+    return tools;
+}
+//# sourceMappingURL=skills.js.map