melchizedek-agents 0.18.0 → 0.20.0

package/dist/lib/tools/skills/loader.d.ts

@@ -0,0 +1,91 @@
+/**
+ * lib/tools/skills/loader.ts — a directory of skills, loaded by the engine
+ * (WS3-3, ADR 0083).
+ *
+ * WHY this file exists:
+ *   The skills harness (lib/tools/skillToolset.ts, ADR 0029) loaded skills
+ *   through ADK's `loadAllSkillsInDir` until WS3-3. This module walks the
+ *   same layout to the same objects, so a skill reads the same on either
+ *   runtime:
+ *   - a skill is a directory, other than the base itself, holding a file
+ *     named SKILL.md in any case; its name must equal the directory's;
+ *   - a directory that is not a skill is searched for skills below it;
+ *   - a skill's `references/`, `assets/` and `scripts/` are read whole,
+ *     each file keyed by its path inside that directory: UTF-8 text as a
+ *     string, anything else as a Buffer; a script is `{ src }` and only a
+ *     text one is kept;
+ *   - build and tool directories (node_modules, .git, __pycache__, …) and
+ *     compiled files (.pyc, …) are skipped, as are symbolic links, which a
+ *     directory listing never reports as a file or a directory;
+ *   - an invalid skill is skipped (validateSkillDir says why).
+ *
+ * WHAT IS BOUNDED (none of these limits exists in ADK's loader):
+ *   SKILL_LIMITS caps a SKILL.md's size, each resource file's size, the
+ *   files one skill may ship, and how deep the walk goes. A resource over
+ *   its limit is skipped and reported through `onWarning`; nothing larger is
+ *   read into memory.
+ *
+ * The files are the operator's: the YAML's `skills.dir` names the shelf,
+ * and nothing a model sends reaches this module.
+ */
+import type { SkillFrontmatter } from './frontmatter.ts';
+/** A file a skill ships: text as a string, binary as a Buffer. */
+export type SkillFile = string | Buffer;
+/** One skill, loaded: the shape load_skill and the tools read. */
+export interface Skill {
+    frontmatter: SkillFrontmatter;
+    /** The SKILL.md body: the procedure. */
+    instructions: string;
+    resources: {
+        references: Record<string, SkillFile>;
+        assets: Record<string, SkillFile>;
+        scripts: Record<string, {
+            src: string;
+        }>;
+    };
+}
+/** What the loader refuses to read. */
+/**
+ * A file's bytes read through one open handle, so the size checked is the
+ * size of the file read (no check-then-read race): undefined when it holds
+ * more than `maxBytes`, or is not a regular file.
+ */
+export declare function readFileBounded(file: string, maxBytes: number): Promise<Buffer | undefined>;
+export declare const SKILL_LIMITS: {
+    /** Bytes a SKILL.md may hold. */
+    readonly skillMdBytes: number;
+    /** Bytes one resource file may hold; a larger one is skipped. */
+    readonly resourceBytes: number;
+    /** Resource files one skill may ship; those past it are skipped. */
+    readonly resourceFiles: 1000;
+    /** Directory levels below the base (or below a resource directory) the walk descends. */
+    readonly depth: 12;
+};
+/** Directories never searched for skills or resources (ADK's list). */
+export declare const IGNORED_DIRECTORIES: ReadonlySet<string>;
+/** Files never read as resources (ADK's list). */
+export declare const IGNORED_EXTENSIONS: ReadonlySet<string>;
+/** Where the loader reports what it skipped for a limit. */
+export interface LoadOptions {
+    onWarning?: (message: string) => void;
+}
+/** The SKILL.md in `skillDir`, checked; throws ADK's texts when it is missing or invalid. */
+export declare function loadSkillFile(skillDir: string): Promise<{
+    frontmatter: SkillFrontmatter;
+    instructions: string;
+}>;
+/** One skill directory: its SKILL.md and the files it ships. */
+export declare function loadSkillFromDir(skillDir: string, opts?: LoadOptions): Promise<Skill>;
+/**
+ * Why `skillDir` is not a valid skill, or nothing: ADK's validateSkillDir.
+ * A SKILL.md that cannot be read or parsed is one problem; otherwise each
+ * frontmatter key the standard does not name, and a name that is not the
+ * directory's.
+ */
+export declare function validateSkillDir(skillDir: string): Promise<string[]>;
+/**
+ * Every valid skill under `basePath`, by name, in the order the walk finds
+ * them (a later skill of the same name replaces an earlier one, as in ADK).
+ * A base that is not a readable directory yields none.
+ */
+export declare function loadAllSkillsInDir(basePath: string, opts?: LoadOptions): Promise<Record<string, Skill>>;

package/dist/lib/tools/skills/loader.js

@@ -0,0 +1,257 @@
+/**
+ * lib/tools/skills/loader.ts — a directory of skills, loaded by the engine
+ * (WS3-3, ADR 0083).
+ *
+ * WHY this file exists:
+ *   The skills harness (lib/tools/skillToolset.ts, ADR 0029) loaded skills
+ *   through ADK's `loadAllSkillsInDir` until WS3-3. This module walks the
+ *   same layout to the same objects, so a skill reads the same on either
+ *   runtime:
+ *   - a skill is a directory, other than the base itself, holding a file
+ *     named SKILL.md in any case; its name must equal the directory's;
+ *   - a directory that is not a skill is searched for skills below it;
+ *   - a skill's `references/`, `assets/` and `scripts/` are read whole,
+ *     each file keyed by its path inside that directory: UTF-8 text as a
+ *     string, anything else as a Buffer; a script is `{ src }` and only a
+ *     text one is kept;
+ *   - build and tool directories (node_modules, .git, __pycache__, …) and
+ *     compiled files (.pyc, …) are skipped, as are symbolic links, which a
+ *     directory listing never reports as a file or a directory;
+ *   - an invalid skill is skipped (validateSkillDir says why).
+ *
+ * WHAT IS BOUNDED (none of these limits exists in ADK's loader):
+ *   SKILL_LIMITS caps a SKILL.md's size, each resource file's size, the
+ *   files one skill may ship, and how deep the walk goes. A resource over
+ *   its limit is skipped and reported through `onWarning`; nothing larger is
+ *   read into memory.
+ *
+ * The files are the operator's: the YAML's `skills.dir` names the shelf,
+ * and nothing a model sends reaches this module.
+ */
+import { isUtf8 } from 'node:buffer';
+import { constants as fsConstants } from 'node:fs';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { ALLOWED_FRONTMATTER_KEYS, MAX_SKILL_MD_CHARS, parseSkillMdContent } from './frontmatter.js';
+/** What the loader refuses to read. */
+/**
+ * A file's bytes read through one open handle, so the size checked is the
+ * size of the file read (no check-then-read race): undefined when it holds
+ * more than `maxBytes`, or is not a regular file.
+ */
+export async function readFileBounded(file, maxBytes) {
+    const handle = await fs.open(file, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > maxBytes)
+            return undefined;
+        const buffer = Buffer.alloc(maxBytes + 1);
+        let length = 0;
+        for (;;) {
+            const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+            if (bytesRead === 0)
+                break;
+            length += bytesRead;
+            if (length > maxBytes)
+                return undefined;
+        }
+        return buffer.subarray(0, length);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export const SKILL_LIMITS = {
+    /** Bytes a SKILL.md may hold. */
+    skillMdBytes: MAX_SKILL_MD_CHARS,
+    /** Bytes one resource file may hold; a larger one is skipped. */
+    resourceBytes: 8 * 1024 * 1024,
+    /** Resource files one skill may ship; those past it are skipped. */
+    resourceFiles: 1000,
+    /** Directory levels below the base (or below a resource directory) the walk descends. */
+    depth: 12,
+};
+/** Directories never searched for skills or resources (ADK's list). */
+export const IGNORED_DIRECTORIES = new Set([
+    '__pycache__',
+    '.pytest_cache',
+    '.mypy_cache',
+    '.ruff_cache',
+    'node_modules',
+    'coverage',
+    'venv',
+    '.venv',
+    'env',
+    '.env',
+    '.git',
+    '.vscode',
+    '.idea',
+]);
+/** Files never read as resources (ADK's list). */
+export const IGNORED_EXTENSIONS = new Set(['.pyc', '.pyo', '.pyd', '.tsbuildinfo', '.DS_Store']);
+function decode(data) {
+    return isUtf8(data) ? data.toString('utf-8') : data;
+}
+/** Every file under `directoryPath`, keyed by its relative path, within the limits. Absent: none. */
+async function loadDir(directoryPath, budget, opts) {
+    const files = {};
+    const walk = async (dir, depth) => {
+        if (depth > SKILL_LIMITS.depth) {
+            opts.onWarning?.(`skipped '${dir}': deeper than ${SKILL_LIMITS.depth} levels`);
+            return;
+        }
+        const entries = await fs.readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (IGNORED_DIRECTORIES.has(entry.name))
+                    continue;
+                await walk(fullPath, depth + 1);
+            }
+            else if (entry.isFile()) {
+                if (IGNORED_EXTENSIONS.has(path.extname(entry.name)))
+                    continue;
+                const relativePath = path.relative(directoryPath, fullPath);
+                if (budget.files <= 0) {
+                    opts.onWarning?.(`skipped '${fullPath}': a skill ships at most ${SKILL_LIMITS.resourceFiles} files`);
+                    continue;
+                }
+                const bytes = await readFileBounded(fullPath, SKILL_LIMITS.resourceBytes);
+                if (!bytes) {
+                    opts.onWarning?.(`skipped '${fullPath}': larger than ${SKILL_LIMITS.resourceBytes} bytes`);
+                    continue;
+                }
+                budget.files -= 1;
+                Object.defineProperty(files, relativePath, { value: decode(bytes), enumerable: true, writable: true, configurable: true });
+            }
+        }
+    };
+    let isDir = false;
+    try {
+        isDir = (await fs.stat(directoryPath)).isDirectory();
+    }
+    catch {
+        return files; // no such directory: the skill ships none of this kind
+    }
+    if (isDir) {
+        try {
+            await walk(directoryPath, 0);
+        }
+        catch (e) {
+            opts.onWarning?.(`failed to load directory '${directoryPath}': ${e.message}`);
+        }
+    }
+    return files;
+}
+/** The SKILL.md in `skillDir`, checked; throws ADK's texts when it is missing or invalid. */
+export async function loadSkillFile(skillDir) {
+    const resolvedDir = path.resolve(skillDir);
+    let content;
+    let entries = [];
+    try {
+        entries = await fs.readdir(resolvedDir, { withFileTypes: true });
+    }
+    catch {
+        entries = [];
+    }
+    for (const entry of entries) {
+        if (!entry.isFile() || entry.name.toLowerCase() !== 'skill.md')
+            continue;
+        const file = path.join(resolvedDir, entry.name);
+        try {
+            const bytes = await readFileBounded(file, SKILL_LIMITS.skillMdBytes);
+            if (!bytes)
+                throw new Error(`SKILL.md is larger than ${SKILL_LIMITS.skillMdBytes} bytes`);
+            content = bytes.toString('utf-8');
+            break;
+        }
+        catch (e) {
+            if (e.message.startsWith('SKILL.md is larger'))
+                throw e;
+        }
+    }
+    if (content === undefined)
+        throw new Error(`SKILL.md (or any case variation like skill.md) not found in '${skillDir}'.`);
+    const { frontmatter, body } = parseSkillMdContent(content);
+    const dirName = path.basename(resolvedDir);
+    if (dirName !== frontmatter.name)
+        throw new Error(`Skill name '${frontmatter.name}' does not match directory name '${dirName}'.`);
+    return { frontmatter, instructions: body };
+}
+/** One skill directory: its SKILL.md and the files it ships. */
+export async function loadSkillFromDir(skillDir, opts = {}) {
+    const resolvedDir = path.resolve(skillDir);
+    const skill = await loadSkillFile(skillDir);
+    const budget = { files: SKILL_LIMITS.resourceFiles };
+    const references = await loadDir(path.join(resolvedDir, 'references'), budget, opts);
+    const assets = await loadDir(path.join(resolvedDir, 'assets'), budget, opts);
+    const rawScripts = await loadDir(path.join(resolvedDir, 'scripts'), budget, opts);
+    const scripts = {};
+    for (const [name, src] of Object.entries(rawScripts)) {
+        if (typeof src === 'string')
+            Object.defineProperty(scripts, name, { value: { src }, enumerable: true, writable: true, configurable: true });
+    }
+    return { ...skill, resources: { references, assets, scripts } };
+}
+/**
+ * Why `skillDir` is not a valid skill, or nothing: ADK's validateSkillDir.
+ * A SKILL.md that cannot be read or parsed is one problem; otherwise each
+ * frontmatter key the standard does not name, and a name that is not the
+ * directory's.
+ */
+export async function validateSkillDir(skillDir) {
+    const resolvedDir = path.resolve(skillDir);
+    let skill;
+    try {
+        skill = await loadSkillFile(resolvedDir);
+    }
+    catch (e) {
+        return [e.message];
+    }
+    const problems = [];
+    const unknown = Object.keys(skill.frontmatter).filter((k) => !ALLOWED_FRONTMATTER_KEYS.has(k));
+    if (unknown.length > 0)
+        problems.push(`Unknown frontmatter fields: [${unknown.sort().join(', ')}]`);
+    const dirName = path.basename(resolvedDir);
+    if (dirName !== skill.frontmatter.name)
+        problems.push(`Skill name '${skill.frontmatter.name}' does not match directory name '${dirName}'.`);
+    return problems;
+}
+/**
+ * Every valid skill under `basePath`, by name, in the order the walk finds
+ * them (a later skill of the same name replaces an earlier one, as in ADK).
+ * A base that is not a readable directory yields none.
+ */
+export async function loadAllSkillsInDir(basePath, opts = {}) {
+    const resolvedPath = path.resolve(basePath);
+    const skills = {};
+    const scan = async (currentDir, depth) => {
+        if (depth > SKILL_LIMITS.depth)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        const isSkillDir = currentDir !== resolvedPath && entries.some((e) => e.isFile() && e.name.toLowerCase() === 'skill.md');
+        if (isSkillDir) {
+            try {
+                const skill = await loadSkillFromDir(currentDir, opts);
+                Object.defineProperty(skills, skill.frontmatter.name, { value: skill, enumerable: true, writable: true, configurable: true });
+            }
+            catch {
+                // Skipped: validateSkillDir (skillSuiteProblems) reports why.
+            }
+            return;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || IGNORED_DIRECTORIES.has(entry.name))
+                continue;
+            await scan(path.join(currentDir, entry.name), depth + 1);
+        }
+    };
+    await scan(resolvedPath, 0);
+    return skills;
+}

package/dist/lib/tools/skills/tools.d.ts

@@ -0,0 +1,187 @@
+/**
+ * lib/tools/skills/tools.ts — the skill tools and the toolset that holds
+ * them, on the engine's own tool base (lib/tools/tool.ts; WS3-3, ADR 0083).
+ *
+ * WHY this file exists:
+ *   The skills harness (ADR 0029) was built on ADK's SkillToolset until
+ *   WS3-3. These are the same tools as own Tools, so the native loop runs
+ *   them directly and the ADK runtime runs them through the one tool
+ *   adapter (lib/tools/adkTool.ts, toAdkToolset). A model is sent the same
+ *   names, descriptions and parameters as before, and reads the same
+ *   results and error texts, on either runtime:
+ *   - list_skills: the `<available_skills>` index (ADK's ListSkillsTool).
+ *     The harness leaves it out, since the index is in the instruction.
+ *   - load_skill: the procedure, the frontmatter and the NAMES of the files
+ *     the skill ships (ADR 0029's lean load), and it activates the skill.
+ *   - load_skill_resource: one of those files (ADK's tool, word for word).
+ *     A binary file is shown to the model as inline data in the next
+ *     request, through the Tool's `contents` hook, as ADK's tool did in its
+ *     processLlmRequest.
+ *   - run_skill_script: asks a person to approve, then runs one script the
+ *     skill ships on the local executor (./executor.ts).
+ *
+ * ACTIVATION: load_skill appends the skill's name to the session state key
+ *   `_adk_activated_skill_<agent>` (ADK's key, so a session stored by
+ *   either runtime reads the same). SkillToolset.getTools reads it and adds
+ *   the tools the activated skills name (`metadata.adk_additional_tools`,
+ *   filled from `allowed-tools`), but only from the tools the YAML handed
+ *   it under `skills.tools`: a skill cannot grant itself a tool the YAML
+ *   withheld.
+ *
+ * WHY NOT defineTool: a defineTool contract validates its arguments with
+ *   zod and answers a bad call with its own error string. These tools keep
+ *   ADK's answers to a bad call (`{ error, error_code }`), so their
+ *   parameters are written here as JSON Schema and their arguments checked
+ *   in execute.
+ *
+ * UNTRUSTED INPUT: every argument is the model's. A skill name and a file
+ *   path are looked up as own keys of the loaded maps (never on a
+ *   prototype), so nothing a model sends opens a file the skill did not
+ *   ship or names a script outside its `scripts/`.
+ */
+import type { ToolDeclaration } from '../../models/contract.ts';
+import type { TurnContent } from '../../runtime/events.ts';
+import type { Tool, ToolContext, Toolset, ToolsetContext } from '../tool.ts';
+import { LocalScriptExecutor } from './executor.ts';
+import type { Skill } from './loader.ts';
+/** The `<available_skills>` index, in the skills' order (ADK's formatSkillsAsXml). */
+export declare function formatSkillsAsXml(skills: Skill[]): string;
+/** The session state key holding the skills an agent has loaded (ADK's). */
+export declare function activatedSkillsKey(agentName: string | undefined): string;
+/** Seconds a skill script may run before the local executor kills it. */
+export declare const SCRIPT_TIMEOUT_SECONDS = 120;
+export interface SkillToolsetOptions {
+    /** `local` runs a skill's scripts on this machine, each after approval; otherwise run_skill_script is absent. */
+    scripts?: 'none' | 'local';
+    /** The tools a loaded skill may unlock by name (the YAML's `skills.tools`, resolved). */
+    additionalTools?: readonly unknown[];
+    /** Variable names a script gets beyond the base allowlist (the YAML's `skills.env` and `skills.secret_env`; ADR 0086). */
+    envNames?: readonly string[];
+    /** The executor for `scripts: local`. Default: the local executor with SCRIPT_TIMEOUT_SECONDS and `envNames`. */
+    executor?: LocalScriptExecutor;
+    /** Where script output files are copied. Default: a private temp directory, made once. */
+    scriptOutputDir?: string;
+}
+/**
+ * The tools an agent with `skills:` carries: load_skill and
+ * load_skill_resource always, run_skill_script with `scripts: local`, and
+ * the tools its loaded skills unlock. A toolset by shape (getTools), which
+ * the native loop expands and lib/tools/adkTool.ts wraps for ADK.
+ */
+export declare class SkillToolset implements Toolset {
+    #private;
+    readonly name = "skill_toolset";
+    readonly skills: Readonly<Record<string, Skill>>;
+    readonly executor?: LocalScriptExecutor;
+    constructor(skills: Record<string, Skill>, options?: SkillToolsetOptions);
+    /** The skill named `name`, or undefined. Only the toolset's own skills, never a prototype key. */
+    getSkill(name: string): Skill | undefined;
+    /** The harness tools, then the tools the agent's loaded skills unlock. */
+    getTools(context?: ToolsetContext): Promise<unknown[]>;
+    /**
+     * Where a script's output files are copied: the configured directory, or
+     * a private temp directory made once per toolset. Output file names are
+     * the script's choice, so they are never resolved against the server's
+     * working directory.
+     */
+    scriptOutputDir(): Promise<string>;
+}
+declare abstract class SkillTool implements Tool {
+    abstract readonly name: string;
+    abstract readonly description: string;
+    protected abstract readonly parameters: Record<string, unknown>;
+    protected readonly toolset: SkillToolset;
+    constructor(toolset: SkillToolset);
+    declaration(): ToolDeclaration;
+    abstract execute(args: Record<string, unknown>, ctx: ToolContext): Promise<unknown>;
+}
+/** list_skills: the index of every installed skill. The harness does not carry it (ADR 0029). */
+export declare class ListSkillsTool extends SkillTool {
+    readonly name = "list_skills";
+    readonly description = "Lists all available skills with their names and descriptions.";
+    protected readonly parameters: {
+        type: string;
+        properties: {};
+    };
+    execute(): Promise<unknown>;
+}
+/**
+ * load_skill, lean (ADR 0029): the procedure, the frontmatter and the names
+ * of the files the skill ships, never their contents. Loading activates the
+ * skill, which unlocks its permitted `allowed-tools` on the next request.
+ */
+export declare class LoadSkillTool extends SkillTool {
+    readonly name = "load_skill";
+    readonly description = "Read one installed skill in full: its SKILL.md procedure, its frontmatter, and the names of the files it ships. Read a skill before you follow it.";
+    protected readonly parameters: {
+        type: string;
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    execute(args: Record<string, unknown>, ctx: ToolContext): Promise<unknown>;
+}
+/** load_skill_resource: one file a skill ships, by its path (ADK's tool). */
+export declare class LoadSkillResourceTool extends SkillTool {
+    readonly name = "load_skill_resource";
+    readonly description = "Loads a resource file (from references/, assets/, or scripts/) from within a skill.";
+    protected readonly parameters: {
+        type: string;
+        properties: {
+            skill_name: {
+                type: string;
+                description: string;
+            };
+            path: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    execute(args: Record<string, unknown>): Promise<unknown>;
+    /**
+     * A binary file this tool just answered for is added to the request as
+     * inline data, after the history (ADK's processLlmRequest): the latest
+     * content, when it is the tools' answer, is searched for this tool's
+     * binary notices.
+     */
+    contents(contents: TurnContent[]): Promise<void>;
+}
+/**
+ * run_skill_script behind a person's approval: the first call asks for it
+ * (the hint names the skill, the script and the arguments) and returns
+ * without running; the call made again with the answer runs only when the
+ * answer approved it. The confirmation travels as `adk_request_confirmation`
+ * on either runtime, so the turn pauses `input-required` exactly as for
+ * `require_approval` (ADR 0028), with this tool's own texts.
+ */
+export declare class RunSkillScriptTool extends SkillTool {
+    #private;
+    readonly name = "run_skill_script";
+    readonly description = "Executes a script from a skill's scripts/ directory.";
+    protected readonly parameters: {
+        type: string;
+        properties: {
+            skill_name: {
+                type: string;
+                description: string;
+            };
+            script_path: {
+                type: string;
+                description: string;
+            };
+            args: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    execute(args: Record<string, unknown>, ctx: ToolContext): Promise<unknown>;
+}
+export {};