@nylorun/agents 0.2.0-beta → 0.4.0-beta

package/dist/plugins/load.d.ts

@@ -0,0 +1,23 @@
+import type { McpServerManifest, SkillRecord } from "@nylorun/core/define";
+export declare const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+export declare const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+export interface PluginDiagnostic {
+    readonly severity: "info" | "warning";
+    readonly code: string;
+    readonly message: string;
+    readonly path?: string;
+}
+export declare class PluginError extends Error {
+    readonly code: string;
+    readonly diagnostics: readonly PluginDiagnostic[];
+    constructor(code: string, message: string, diagnostics?: readonly PluginDiagnostic[]);
+}
+export interface LoadedPlugin {
+    readonly root: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly skills: Readonly<Record<string, SkillRecord>>;
+    readonly mcpServers: Readonly<Record<string, McpServerManifest>>;
+    readonly diagnostics: readonly PluginDiagnostic[];
+}
+export declare function loadPlugin(directory: string): LoadedPlugin;

package/dist/plugins/load.js

@@ -0,0 +1,369 @@
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { loadSkillsFromDirectory } from "../skills/load.js";
+import { expandPluginPlaceholders } from "./launch.js";
+export const PLUGIN_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json";
+export const MCP_SCHEMA = "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+const PLUGIN_FIELDS = new Set([
+    "$schema",
+    "name",
+    "version",
+    "description",
+    "author",
+    "homepage",
+    "repository",
+    "license",
+    "keywords",
+    "extensions",
+]);
+const AUTHOR_FIELDS = new Set(["name", "email", "url"]);
+const RESERVED_ENV = new Set(["PLUGIN_ROOT", "PLUGIN_DATA"]);
+export class PluginError extends Error {
+    code;
+    diagnostics;
+    constructor(code, message, diagnostics = []) {
+        super(message);
+        this.name = "PluginError";
+        this.code = code;
+        this.diagnostics = diagnostics;
+    }
+}
+export function loadPlugin(directory) {
+    const root = resolveRoot(directory);
+    const manifestPath = join(root, "plugin.json");
+    const manifestReal = realInside(root, manifestPath);
+    if (!manifestReal || !existsSync(manifestReal) || !statSync(manifestReal).isFile())
+        throw new PluginError("plugin.manifest-missing", `plugin.json must be a file inside ${root}`, [{ severity: "warning", code: "plugin.manifest-missing", message: "plugin.json is missing or escapes the package root", path: manifestPath }]);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(manifestReal, "utf8"));
+    }
+    catch {
+        throw new PluginError("plugin.manifest-invalid", "plugin.json is not valid JSON");
+    }
+    if (!isRecord(parsed))
+        throw new PluginError("plugin.manifest-invalid", "plugin.json must be a JSON object");
+    const diagnostics = [];
+    for (const key of Object.keys(parsed)) {
+        if (!PLUGIN_FIELDS.has(key))
+            diagnostics.push({
+                severity: "warning",
+                code: "plugin.unknown-field",
+                message: `Ignored unknown plugin.json field '${key}'`,
+                path: manifestPath,
+            });
+    }
+    if (parsed.$schema !== PLUGIN_SCHEMA)
+        throw new PluginError("plugin.schema-unsupported", "plugin.json $schema must be the Agent Plugins 1.0.0 plugin schema", diagnostics);
+    if (!isPluginName(parsed.name))
+        throw new PluginError("plugin.name-invalid", "plugin.json name must be 1-64 characters of lowercase letters, digits, hyphens, and periods", diagnostics);
+    validateMetadata(parsed, diagnostics);
+    const extensions = parsed.extensions;
+    if (extensions !== undefined && !isRecord(extensions))
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.extensions-ignored",
+            message: "Ignored non-object extensions field",
+            path: manifestPath,
+        });
+    else if (isRecord(extensions)) {
+        for (const namespace of Object.keys(extensions))
+            diagnostics.push({
+                severity: "info",
+                code: "plugin.extension-ignored",
+                message: `Ignored unimplemented extension namespace '${namespace}'`,
+                path: manifestPath,
+            });
+    }
+    const skills = loadSkills(root, diagnostics);
+    const mcpServers = loadMcp(root, parsed.name, diagnostics);
+    return {
+        root,
+        name: parsed.name,
+        ...(typeof parsed.description === "string" ? { description: parsed.description } : {}),
+        skills,
+        mcpServers,
+        diagnostics,
+    };
+}
+function resolveRoot(directory) {
+    const resolved = resolve(directory);
+    if (!existsSync(resolved))
+        throw new PluginError("plugin.missing", `Plugin directory does not exist: ${directory}`);
+    const real = realpathSync(resolved);
+    if (!statSync(real).isDirectory())
+        throw new PluginError("plugin.missing", `Plugin path is not a directory: ${directory}`);
+    return real;
+}
+function validateMetadata(manifest, diagnostics) {
+    for (const field of ["version", "description", "homepage", "repository", "license"]) {
+        if (manifest[field] !== undefined && typeof manifest[field] !== "string")
+            throw new PluginError("plugin.manifest-invalid", `plugin.json ${field} must be a string`, diagnostics);
+    }
+    if (manifest.keywords !== undefined) {
+        if (!Array.isArray(manifest.keywords) || manifest.keywords.some((item) => typeof item !== "string"))
+            throw new PluginError("plugin.manifest-invalid", "plugin.json keywords must be an array of strings", diagnostics);
+    }
+    if (manifest.author !== undefined) {
+        if (!isRecord(manifest.author))
+            throw new PluginError("plugin.manifest-invalid", "plugin.json author must be an object", diagnostics);
+        for (const key of Object.keys(manifest.author)) {
+            if (!AUTHOR_FIELDS.has(key) || typeof manifest.author[key] !== "string")
+                throw new PluginError("plugin.manifest-invalid", "plugin.json author contains an invalid field", diagnostics);
+        }
+    }
+}
+function loadSkills(root, diagnostics) {
+    const location = join(root, "skills");
+    if (!existsSync(location))
+        return {};
+    const real = realInside(root, location);
+    if (!real || !statSync(real).isDirectory()) {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.skills-invalid",
+            message: "skills/ is not a directory inside the package",
+            path: location,
+        });
+        return {};
+    }
+    return loadSkillsFromDirectory(real, diagnostics, {
+        boundary: root,
+        codePrefix: "plugin",
+    });
+}
+function loadMcp(root, pluginName, diagnostics) {
+    const location = join(root, "mcp.json");
+    if (!existsSync(location))
+        return {};
+    const real = realInside(root, location);
+    if (!real || !statSync(real).isFile()) {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.mcp-invalid",
+            message: "mcp.json is not a file inside the package",
+            path: location,
+        });
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(real, "utf8"));
+    }
+    catch {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.mcp-invalid",
+            message: "mcp.json is not valid JSON",
+            path: location,
+        });
+        return {};
+    }
+    if (!isRecord(parsed) || Object.keys(parsed).some((key) => key !== "$schema" && key !== "mcpServers")) {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.mcp-invalid",
+            message: "mcp.json must contain only $schema and mcpServers",
+            path: location,
+        });
+        return {};
+    }
+    if (parsed.$schema !== MCP_SCHEMA) {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.mcp-invalid",
+            message: "mcp.json $schema does not match the plugin schema version",
+            path: location,
+        });
+        return {};
+    }
+    if (!isRecord(parsed.mcpServers)) {
+        diagnostics.push({
+            severity: "warning",
+            code: "plugin.mcp-invalid",
+            message: "mcp.json mcpServers must be an object",
+            path: location,
+        });
+        return {};
+    }
+    const pluginData = join(dirname(root), ".nylorun", "plugin-data", pluginName);
+    const servers = {};
+    for (const [name, value] of Object.entries(parsed.mcpServers)) {
+        const server = validateServer(name, value, root, pluginData);
+        if (!server) {
+            diagnostics.push({
+                severity: "warning",
+                code: "plugin.mcp-server-skipped",
+                message: `Skipped invalid MCP server '${name}'`,
+                path: location,
+            });
+            continue;
+        }
+        if (server.type === "stdio")
+            mkdirSync(pluginData, { recursive: true });
+        servers[name] = server;
+    }
+    return servers;
+}
+function validateServer(name, value, root, pluginData) {
+    if (!isRecord(value) || typeof value.type !== "string")
+        return undefined;
+    if (value.type === "stdio")
+        return validateStdio(name, value, root, pluginData);
+    if (value.type === "streamable-http" || value.type === "sse")
+        return validateRemote(name, value);
+    return undefined;
+}
+function validateStdio(name, value, root, pluginData) {
+    const allowed = new Set(["type", "command", "args", "env", "cwd"]);
+    if (Object.keys(value).some((key) => !allowed.has(key)))
+        return undefined;
+    if (typeof value.command !== "string" || !isCommandToken(value.command))
+        return undefined;
+    if (value.command.startsWith("./") && !commandStaysInside(root, value.command))
+        return undefined;
+    let args;
+    if (value.args !== undefined) {
+        if (!Array.isArray(value.args) || value.args.some((item) => typeof item !== "string"))
+            return undefined;
+        args = value.args;
+    }
+    let env;
+    if (value.env !== undefined) {
+        if (!isRecord(value.env))
+            return undefined;
+        env = {};
+        for (const [key, item] of Object.entries(value.env)) {
+            if (typeof item !== "string" || RESERVED_ENV.has(key))
+                return undefined;
+            env[key] = item;
+        }
+    }
+    let cwd;
+    if (value.cwd !== undefined) {
+        if (typeof value.cwd !== "string" || !isCwdForm(value.cwd))
+            return undefined;
+        const expanded = expandPluginPlaceholders(value.cwd, root, pluginData);
+        const absolute = expanded.startsWith("/") || /^[A-Za-z]:[\\/]/.test(expanded)
+            ? expanded
+            : resolve(root, expanded);
+        const boundary = value.cwd === "${PLUGIN_DATA}" || value.cwd.startsWith("${PLUGIN_DATA}/")
+            ? pluginData
+            : root;
+        if (!isInside(boundary, absolute))
+            return undefined;
+        cwd = value.cwd;
+    }
+    return {
+        name,
+        type: "stdio",
+        command: value.command,
+        ...(args === undefined ? {} : { args }),
+        ...(env === undefined ? {} : { env }),
+        ...(cwd === undefined ? {} : { cwd }),
+    };
+}
+function validateRemote(name, value) {
+    const allowed = new Set(["type", "url", "headers"]);
+    if (Object.keys(value).some((key) => !allowed.has(key)))
+        return undefined;
+    if (typeof value.url !== "string" || !isRemoteUrl(value.url))
+        return undefined;
+    let headers;
+    if (value.headers !== undefined) {
+        if (!isRecord(value.headers))
+            return undefined;
+        const seen = new Set();
+        headers = {};
+        for (const [key, item] of Object.entries(value.headers)) {
+            if (typeof item !== "string" || !isHeaderName(key) || /[\r\n\0]/.test(item))
+                return undefined;
+            const folded = key.toLowerCase();
+            if (seen.has(folded))
+                return undefined;
+            seen.add(folded);
+            headers[key] = item;
+        }
+    }
+    return {
+        name,
+        type: value.type,
+        url: value.url,
+        ...(headers === undefined ? {} : { headers }),
+    };
+}
+function commandStaysInside(root, command) {
+    const lexical = resolve(root, command);
+    if (!isInside(root, lexical))
+        return false;
+    return !existsSync(lexical) || realInside(root, lexical) !== undefined;
+}
+function isCommandToken(command) {
+    if (!command || /\s/.test(command))
+        return false;
+    if (command.startsWith("./"))
+        return !command.split("/").includes("..");
+    return !command.includes("/") && !command.includes("\\") && !command.includes("${");
+}
+function isCwdForm(cwd) {
+    return (cwd.startsWith("./") ||
+        cwd === "${PLUGIN_ROOT}" ||
+        cwd.startsWith("${PLUGIN_ROOT}/") ||
+        cwd === "${PLUGIN_DATA}" ||
+        cwd.startsWith("${PLUGIN_DATA}/"));
+}
+function isRemoteUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return false;
+    }
+    if (url.username || url.password || url.hash)
+        return false;
+    if (url.protocol === "https:")
+        return true;
+    if (url.protocol !== "http:")
+        return false;
+    return isLoopback(url.hostname);
+}
+function isLoopback(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, "");
+    if (host === "localhost" || host === "::1")
+        return true;
+    const match = /^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    if (!match)
+        return false;
+    return match.slice(1).every((part) => Number(part) <= 255);
+}
+function isHeaderName(name) {
+    return /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/.test(name);
+}
+function isPluginName(value) {
+    if (typeof value !== "string" || value.length < 1 || value.length > 64)
+        return false;
+    if (!/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(value) && value.length !== 1)
+        return false;
+    if (value.length === 1)
+        return /^[a-z0-9]$/.test(value);
+    return !value.includes("--") && !value.includes("..");
+}
+function realInside(root, candidate) {
+    if (!existsSync(candidate))
+        return undefined;
+    try {
+        const real = realpathSync(candidate);
+        return isInside(root, real) ? real : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isInside(root, target) {
+    const rel = relative(root, target);
+    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}

package/dist/plugins/plugin.d.ts

@@ -0,0 +1,8 @@
+import type { CapabilityDeclaration } from "@nylorun/core/define";
+import { type LoadedPlugin, type PluginDiagnostic } from "./load.js";
+export interface PluginCapability extends CapabilityDeclaration {
+    readonly diagnostics: readonly PluginDiagnostic[];
+}
+/** Read an Agent Plugin package and return one capability for `Agent.use`. */
+export declare function plugin(directory: string): PluginCapability;
+export declare function capabilityFromPlugin(loaded: LoadedPlugin): PluginCapability;

package/dist/plugins/plugin.js

@@ -0,0 +1,35 @@
+import { formatSkillCatalog, SKILLS_USAGE } from "../skills/catalog.js";
+import { loadPlugin, } from "./load.js";
+/** Read an Agent Plugin package and return one capability for `Agent.use`. */
+export function plugin(directory) {
+    const loaded = loadPlugin(directory);
+    return capabilityFromPlugin(loaded);
+}
+export function capabilityFromPlugin(loaded) {
+    const names = Object.values(loaded.skills);
+    const instructions = names.length === 0
+        ? undefined
+        : [
+            SKILLS_USAGE,
+            formatSkillCatalog(names.map((skill) => ({
+                name: skill.name,
+                description: skill.description,
+            }))),
+        ];
+    const skills = Object.fromEntries(names.map((skill) => [
+        skill.name,
+        { name: skill.name, description: skill.description },
+    ]));
+    return {
+        id: loaded.name,
+        type: "agent-plugin",
+        pluginRoot: loaded.root,
+        ...(loaded.description === undefined ? {} : { description: loaded.description }),
+        ...(instructions === undefined ? {} : { instructions }),
+        ...(names.length === 0 ? {} : { skills, skillRecords: loaded.skills }),
+        ...(Object.keys(loaded.mcpServers).length === 0
+            ? {}
+            : { mcpServers: loaded.mcpServers }),
+        diagnostics: loaded.diagnostics,
+    };
+}

package/dist/sandbox/index.d.ts

@@ -0,0 +1,2 @@
+export { sandbox, SandboxError } from "./sandbox.js";
+export type { SandboxCapability, SandboxCapabilityOptions, SandboxOptions, } from "./sandbox.js";

package/dist/sandbox/index.js

@@ -0,0 +1 @@
+export { sandbox, SandboxError } from "./sandbox.js";

package/dist/sandbox/sandbox.d.ts

@@ -0,0 +1,28 @@
+import type { CapabilityDeclaration, SandboxManifest, ToolDefinition } from "@nylorun/core/define";
+/** What computer the agent needs. The Runtime decides where it runs. */
+export type SandboxOptions = SandboxManifest;
+export interface SandboxCapabilityOptions {
+    /** Capability id. Defaults to `"sandbox"`. */
+    readonly id?: string;
+}
+export interface SandboxCapability extends CapabilityDeclaration {
+    readonly sandbox: SandboxManifest;
+    readonly tools: readonly ToolDefinition[];
+}
+export declare class SandboxError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Give the agent an isolated Linux machine with a persistent `/workspace`.
+ *
+ * Adds the built-in `bash`, `read`, `write`, `edit`, `grep` and `glob` tools. They run in the
+ * Nylorun Runtime, which picks the backend (a microsandbox VM where available). Agent code
+ * declares requirements only.
+ *
+ * ```ts
+ * Agent({ id: "analyst", instructions: "..." }).use(sandbox())
+ * Agent({ ... }).use(sandbox({ image: "node:24", network: { allow: ["api.github.com"] } }))
+ * ```
+ */
+export declare function sandbox(options?: SandboxOptions, capability?: SandboxCapabilityOptions): SandboxCapability;

package/dist/sandbox/sandbox.js

@@ -0,0 +1,93 @@
+import { SANDBOX_DEFERRED_FIELDS, SANDBOX_FIELDS, SANDBOX_INSTRUCTIONS, SANDBOX_NETWORK_PRESETS, createSandboxTools, isSandboxHostPattern, parseSandboxDuration, parseSandboxSize, } from "@nylorun/core/define";
+export class SandboxError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "SandboxError";
+        this.code = code;
+    }
+}
+/**
+ * Give the agent an isolated Linux machine with a persistent `/workspace`.
+ *
+ * Adds the built-in `bash`, `read`, `write`, `edit`, `grep` and `glob` tools. They run in the
+ * Nylorun Runtime, which picks the backend (a microsandbox VM where available). Agent code
+ * declares requirements only.
+ *
+ * ```ts
+ * Agent({ id: "analyst", instructions: "..." }).use(sandbox())
+ * Agent({ ... }).use(sandbox({ image: "node:24", network: { allow: ["api.github.com"] } }))
+ * ```
+ */
+export function sandbox(options = {}, capability = {}) {
+    const id = capability.id ?? "sandbox";
+    if (!isRecord(options))
+        throw new SandboxError("sandbox.invalid", "sandbox() expects an options object");
+    for (const key of Object.keys(options)) {
+        if (SANDBOX_DEFERRED_FIELDS.includes(key))
+            throw new SandboxError("sandbox.unsupported", `sandbox({ ${key} }) is not supported in this version. ` +
+                `Supported options: ${SANDBOX_FIELDS.join(", ")}. See docs/design/sandboxes.md for what is planned.`);
+        if (!SANDBOX_FIELDS.includes(key))
+            throw new SandboxError("sandbox.unknown-option", `Unknown sandbox option '${key}'. Supported options: ${SANDBOX_FIELDS.join(", ")}`);
+    }
+    return Object.freeze({
+        id,
+        instructions: Object.freeze([SANDBOX_INSTRUCTIONS]),
+        tools: createSandboxTools(),
+        sandbox: freezeOptions(options),
+    });
+}
+function freezeOptions(options) {
+    const result = {};
+    if (options.image !== undefined) {
+        if (typeof options.image !== "string" || options.image.trim().length === 0)
+            throw new SandboxError("sandbox.invalid-image", "sandbox({ image }) must be a non-empty OCI image reference");
+        result.image = options.image;
+    }
+    if (options.network !== undefined) {
+        if (!isRecord(options.network))
+            throw new SandboxError("sandbox.invalid-network", "sandbox({ network }) must be an object");
+        for (const key of Object.keys(options.network))
+            if (key !== "preset" && key !== "allow")
+                throw new SandboxError("sandbox.invalid-network", `Unknown network option '${key}'. Use preset and allow.`);
+        const { preset, allow } = options.network;
+        if (preset !== undefined && !SANDBOX_NETWORK_PRESETS.includes(preset))
+            throw new SandboxError("sandbox.invalid-network", `network.preset must be one of ${SANDBOX_NETWORK_PRESETS.join(", ")}`);
+        if (allow !== undefined) {
+            if (!Array.isArray(allow))
+                throw new SandboxError("sandbox.invalid-network", "network.allow must be an array of host names");
+            for (const host of allow)
+                if (typeof host !== "string" || !isSandboxHostPattern(host))
+                    throw new SandboxError("sandbox.invalid-network", `network.allow entry '${String(host)}' must be a host name such as api.github.com or *.example.com (no scheme, port or path)`);
+        }
+        result.network = Object.freeze({
+            ...(preset === undefined ? {} : { preset: preset }),
+            ...(allow === undefined ? {} : { allow: Object.freeze([...allow]) }),
+        });
+    }
+    if (options.resources !== undefined) {
+        if (!isRecord(options.resources))
+            throw new SandboxError("sandbox.invalid-resources", "sandbox({ resources }) must be an object");
+        for (const key of Object.keys(options.resources))
+            if (key !== "cpus" && key !== "memory")
+                throw new SandboxError("sandbox.invalid-resources", `resources.${key} is not supported in this version. Use cpus and memory.`);
+        const { cpus, memory } = options.resources;
+        if (cpus !== undefined && (!Number.isInteger(cpus) || cpus < 1 || cpus > 64))
+            throw new SandboxError("sandbox.invalid-resources", "resources.cpus must be an integer from 1 to 64");
+        if (memory !== undefined && (typeof memory !== "string" || parseSandboxSize(memory) === undefined))
+            throw new SandboxError("sandbox.invalid-resources", "resources.memory must be a size such as 512MiB or 2GiB");
+        result.resources = Object.freeze({
+            ...(cpus === undefined ? {} : { cpus }),
+            ...(memory === undefined ? {} : { memory }),
+        });
+    }
+    if (options.idle !== undefined) {
+        if (typeof options.idle !== "string" || parseSandboxDuration(options.idle) === undefined)
+            throw new SandboxError("sandbox.invalid-idle", "sandbox({ idle }) must be a duration such as 30s, 15m or 1h");
+        result.idle = options.idle;
+    }
+    return Object.freeze(result);
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}

package/dist/skills/catalog.d.ts

@@ -0,0 +1,5 @@
+export declare const SKILLS_USAGE = "The following skills provide specialized instructions. When a task matches a skill description, call load_skill with that name before proceeding.";
+export declare function formatSkillCatalog(skills: readonly {
+    name: string;
+    description: string;
+}[]): string;

package/dist/skills/catalog.js

@@ -0,0 +1,14 @@
+export const SKILLS_USAGE = "The following skills provide specialized instructions. When a task matches a skill description, call load_skill with that name before proceeding.";
+export function formatSkillCatalog(skills) {
+    const entries = skills
+        .map((skill) => `  <skill>\n    <name>${escapeXml(skill.name)}</name>\n    <description>${escapeXml(skill.description)}</description>\n  </skill>`)
+        .join("\n");
+    return `<available_skills>\n${entries}\n</available_skills>`;
+}
+function escapeXml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}

package/dist/skills/index.d.ts

@@ -0,0 +1,5 @@
+export { skills } from "./skills.js";
+export type { SkillsCapability, SkillsOptions } from "./skills.js";
+export { loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, } from "./load.js";
+export type { SkillDiagnostic } from "./load.js";
+export { formatSkillCatalog, SKILLS_USAGE } from "./catalog.js";

package/dist/skills/index.js

@@ -0,0 +1,3 @@
+export { skills } from "./skills.js";
+export { loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, } from "./load.js";
+export { formatSkillCatalog, SKILLS_USAGE } from "./catalog.js";

package/dist/skills/load.d.ts

@@ -0,0 +1,27 @@
+import type { SkillRecord } from "@nylorun/core/define";
+export interface SkillDiagnostic {
+    readonly severity: "info" | "warning";
+    readonly code: string;
+    readonly message: string;
+    readonly path?: string;
+}
+export declare class SkillsError extends Error {
+    readonly code: string;
+    readonly diagnostics: readonly SkillDiagnostic[];
+    constructor(code: string, message: string, diagnostics?: readonly SkillDiagnostic[]);
+}
+/** Resolve a skills catalog directory; throws when missing or not a directory. */
+export declare function resolveSkillsRoot(directory: string): string;
+/**
+ * Load Agent Skills (agentskills.io) from a catalog directory.
+ * Each immediate subdirectory with a valid SKILL.md becomes one skill.
+ */
+export declare function loadSkillsFromDirectory(directory: string, diagnostics: SkillDiagnostic[], options?: {
+    readonly boundary?: string;
+    readonly codePrefix?: string;
+}): Readonly<Record<string, SkillRecord>>;
+export declare function parseSkill(text: string, directoryName: string): {
+    name: string;
+    description: string;
+    instructions: string;
+} | undefined;