@lapis-notes/ai 0.1.0

package/dist/skills/discovery.js

@@ -0,0 +1,227 @@
+import { parseSkillMarkdown, SkillParseError } from "./parser";
+const SOURCE_RANK = {
+    folder: 5,
+    vault: 4,
+    user: 3,
+    extension: 2,
+    programmatic: 2,
+    bundled: 1,
+};
+function skillGlob(prefix) {
+    const root = prefix.replace(/\/$/u, "");
+    return root ? `${root}/**/SKILL.md` : ".agents/skills/**/SKILL.md";
+}
+function folderPrefix(scopeDir) {
+    return scopeDir ? `${scopeDir}/.agents/skills` : ".agents/skills";
+}
+export class SkillDiscovery {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async discover(context) {
+        const diagnostics = [];
+        const buckets = new Map();
+        await this.#collectVault("folder", folderPrefix(context.scopeDir), buckets, diagnostics);
+        await this.#collectVault("vault", ".agents/skills", buckets, diagnostics);
+        await this.#collectVault("user", this.options.userPrefix ?? ".agents/user/skills", buckets, diagnostics);
+        await this.#collectRegistered(buckets, diagnostics, context);
+        for (const bundled of this.options.bundled ?? []) {
+            addToBucket(buckets, bundled);
+        }
+        return mergeByPrecedence(buckets, diagnostics, context);
+    }
+    async #collectVault(source, prefix, buckets, diagnostics) {
+        const files = this.options.vault.getFilesByGlob(skillGlob(prefix));
+        for (const file of files) {
+            if (file.path.includes("/scripts/") || file.path.includes("/references/")) {
+                continue;
+            }
+            const root = file.path.replace(/\/SKILL\.md$/u, "");
+            if (rootIncludesEscape(root, prefix)) {
+                diagnostics.push({
+                    path: file.path,
+                    source,
+                    message: "Skill path escapes the trusted root.",
+                });
+                continue;
+            }
+            const content = await this.options.vault.cachedRead(file);
+            try {
+                addToBucket(buckets, parseSkillMarkdown(content, {
+                    path: file.path,
+                    source,
+                    root,
+                }));
+            }
+            catch (error) {
+                diagnostics.push({
+                    path: file.path,
+                    source,
+                    message: error instanceof SkillParseError
+                        ? error.message
+                        : "Skill could not be parsed.",
+                });
+            }
+        }
+    }
+    async #collectRegistered(buckets, diagnostics, context) {
+        for (const source of this.options.appSkills?.list() ?? []) {
+            if (context.enabledPluginIds &&
+                context.enabledPluginIds.length > 0 &&
+                !context.enabledPluginIds.includes(source.ownerPluginId)) {
+                diagnostics.push({
+                    path: source.path ?? source.skill?.name ?? source.ownerPluginId,
+                    source: source.kind === "programmatic" ? "programmatic" : "extension",
+                    message: `Disabled extension root is excluded: ${source.ownerPluginId}`,
+                });
+                continue;
+            }
+            if (source.kind === "programmatic" && source.skill) {
+                addToBucket(buckets, programmaticSkill(source));
+                continue;
+            }
+            const files = this.options.extensionFiles?.get(`${source.ownerPluginId}:${source.path ?? ""}`) ?? (await this.#vaultExtensionFiles(source));
+            if (!files)
+                continue;
+            for (const [relativePath, content] of Object.entries(files)) {
+                if (!relativePath.endsWith("SKILL.md"))
+                    continue;
+                try {
+                    addToBucket(buckets, parseSkillMarkdown(content, {
+                        path: `${source.ownerPluginId}/${relativePath}`,
+                        source: "extension",
+                        root: `${source.ownerPluginId}/${relativePath.replace(/\/SKILL\.md$/u, "")}`,
+                    }));
+                }
+                catch (error) {
+                    diagnostics.push({
+                        path: `${source.ownerPluginId}/${relativePath}`,
+                        source: "extension",
+                        message: error instanceof SkillParseError
+                            ? error.message
+                            : "Skill could not be parsed.",
+                    });
+                }
+            }
+        }
+    }
+    async #vaultExtensionFiles(source) {
+        if (!source.path)
+            return undefined;
+        const pluginRoot = this.options.extensionRootFor?.(source.ownerPluginId);
+        if (!pluginRoot)
+            return undefined;
+        const prefix = `${pluginRoot.replace(/\/$/u, "")}/${source.path}`;
+        const files = this.options.vault.getFilesByGlob(skillGlob(prefix));
+        const contents = {};
+        for (const file of files) {
+            if (rootIncludesEscape(file.path.replace(/\/SKILL\.md$/u, ""), prefix)) {
+                continue;
+            }
+            contents[file.path.slice(prefix.length + 1)] =
+                await this.options.vault.cachedRead(file);
+        }
+        return Object.keys(contents).length > 0 ? contents : undefined;
+    }
+}
+function programmaticSkill(source) {
+    const skill = source.skill;
+    const frontmatter = [
+        "---",
+        `name: ${skill.name}`,
+        `description: ${skill.description}`,
+        skill.userInvocable === false ? "user-invocable: false" : undefined,
+        skill.disableModelInvocation ? "disable-model-invocation: true" : undefined,
+        skill.argumentHint ? `argument-hint: ${JSON.stringify(skill.argumentHint)}` : undefined,
+        skill.command?.kind === "tool" ? "command-dispatch: tool" : undefined,
+        skill.command?.kind === "tool" ? `command-tool: ${skill.command.tool}` : undefined,
+        "---",
+    ].filter((line) => Boolean(line));
+    const content = [...frontmatter, "", skill.instructions].join("\n");
+    return parseSkillMarkdown(content, {
+        path: `programmatic:${source.ownerPluginId}/${skill.name}`,
+        source: "programmatic",
+        root: `programmatic:${source.ownerPluginId}/${skill.name}`,
+    });
+}
+function addToBucket(buckets, skill) {
+    const bucket = buckets.get(skill.source) ?? [];
+    bucket.push(skill);
+    buckets.set(skill.source, bucket);
+}
+function rootIncludesEscape(root, prefix) {
+    const normalized = prefix.replace(/\/$/u, "");
+    if (root.includes("/../") || root.endsWith("/..") || root.includes("/./")) {
+        return true;
+    }
+    return normalized !== "" && root !== normalized && !root.startsWith(`${normalized}/`);
+}
+function isEligible(skill, context) {
+    const requiredTools = skill.requirements?.tools ?? [];
+    const available = new Set(context.availableToolNames ?? []);
+    const missingTool = requiredTools.find((tool) => !available.has(tool));
+    if (missingTool)
+        return `Required tool is unavailable: ${missingTool}`;
+    const requiredPlugins = skill.requirements?.extensions ?? [];
+    const enabled = new Set(context.enabledPluginIds ?? []);
+    if (requiredPlugins.length > 0 && enabled.size > 0) {
+        const missing = requiredPlugins.find((id) => !enabled.has(id));
+        if (missing)
+            return `Required extension is unavailable: ${missing}`;
+    }
+    return undefined;
+}
+function mergeByPrecedence(buckets, diagnostics, context) {
+    const winners = new Map();
+    const kinds = [
+        "bundled",
+        "extension",
+        "programmatic",
+        "user",
+        "vault",
+        "folder",
+    ];
+    for (const kind of kinds) {
+        const skills = buckets.get(kind) ?? [];
+        const seen = new Set();
+        for (const skill of skills) {
+            if (seen.has(skill.name)) {
+                diagnostics.push({
+                    path: skill.root,
+                    source: skill.source,
+                    message: `Duplicate skill name at the same precedence: ${skill.name}`,
+                });
+                winners.delete(skill.name);
+                continue;
+            }
+            seen.add(skill.name);
+            const reason = isEligible(skill, context);
+            if (reason) {
+                diagnostics.push({
+                    path: skill.root,
+                    source: skill.source,
+                    message: reason,
+                });
+                continue;
+            }
+            const existing = winners.get(skill.name);
+            if (existing && SOURCE_RANK[existing.source] > SOURCE_RANK[skill.source]) {
+                continue;
+            }
+            if (existing) {
+                diagnostics.push({
+                    path: existing.root,
+                    source: existing.source,
+                    message: `Shadowed by ${skill.source} skill ${skill.name}`,
+                    shadowedBy: skill.root,
+                });
+            }
+            winners.set(skill.name, skill);
+        }
+    }
+    return {
+        skills: [...winners.values()].sort((left, right) => left.name.localeCompare(right.name)),
+        diagnostics,
+    };
+}

package/dist/skills/manifest.d.ts

@@ -0,0 +1,3 @@
+import type { SkillSnapshot } from "./types";
+export declare function hasHostFilesystemPath(value: string): boolean;
+export declare function buildAvailableSkillsManifest(snapshot: SkillSnapshot): string;

package/dist/skills/manifest.js

@@ -0,0 +1,39 @@
+const MANIFEST_BUDGET = 8_000;
+export function hasHostFilesystemPath(value) {
+    return /(?:(?:^|[\s"'>=])(?:\/|[A-Za-z]:\\|file:\/\/)|\.lapis\/skills\/|\.agents\/(?:user\/)?skills\/)/u.test(value);
+}
+export function buildAvailableSkillsManifest(snapshot) {
+    const visible = snapshot.skills.filter((skill) => skill.modelInvocable);
+    const body = visible
+        .map((skill) => renderSkill(skill))
+        .join("\n");
+    const xml = [
+        "<available_skills>",
+        body,
+        "</available_skills>",
+        "",
+        "When a listed skill clearly applies, load it using skills_read before proceeding.",
+        "Only load skills listed in available_skills.",
+    ].join("\n");
+    if (xml.length > MANIFEST_BUDGET) {
+        throw new Error(`Available-skills manifest exceeds ${MANIFEST_BUDGET} characters.`);
+    }
+    return xml;
+}
+function renderSkill(skill) {
+    return [
+        "  <skill>",
+        `    <name>${escapeXml(skill.name)}</name>`,
+        `    <description>${escapeXml(skill.description)}</description>`,
+        `    <id>${escapeXml(skill.skillId)}</id>`,
+        `    <version>${escapeXml(skill.version)}</version>`,
+        "  </skill>",
+    ].join("\n");
+}
+function escapeXml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}

package/dist/skills/parser.d.ts

@@ -0,0 +1,12 @@
+import type { SkillSourceKind } from "@lapis-notes/api/agent-skills";
+import type { LoadedAppSkill } from "./types";
+export declare class SkillParseError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export declare function skillContentVersion(content: string): string;
+export declare function parseSkillMarkdown(content: string, input: {
+    path: string;
+    source: SkillSourceKind;
+    root: string;
+}): LoadedAppSkill;

package/dist/skills/parser.js

@@ -0,0 +1,124 @@
+import { parse as parseYaml } from "yaml";
+import { SKILL_NAME_PATTERN } from "@lapis-notes/api/agent-skills";
+const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/u;
+export class SkillParseError extends Error {
+    path;
+    constructor(path, message) {
+        super(message);
+        this.path = path;
+        this.name = "SkillParseError";
+    }
+}
+export function skillContentVersion(content) {
+    let hash = 2166136261;
+    for (let index = 0; index < content.length; index += 1) {
+        hash ^= content.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return `fnv1a:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function readBoolean(value, fallback) {
+    return typeof value === "boolean" ? value : fallback;
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function readStringList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const items = value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return items.length > 0 ? items : undefined;
+}
+function parseCommand(data) {
+    const dispatch = readString(data["command-dispatch"]);
+    if (!dispatch || dispatch === "model")
+        return { kind: "model" };
+    if (dispatch !== "tool") {
+        throw new Error(`Unsupported command-dispatch: ${dispatch}`);
+    }
+    const tool = readString(data["command-tool"]);
+    if (!tool) {
+        throw new Error("command-dispatch: tool requires command-tool");
+    }
+    const argMode = readString(data["command-arg-mode"]) ?? "raw";
+    if (argMode !== "raw") {
+        throw new Error(`Unsupported command-arg-mode: ${argMode}`);
+    }
+    return { kind: "tool", tool, argMode: "raw" };
+}
+function parseRequirements(data) {
+    const metadata = isRecord(data.metadata) ? data.metadata : undefined;
+    const lapis = metadata && isRecord(metadata.lapis) ? metadata.lapis : undefined;
+    const requires = lapis && isRecord(lapis.requires) ? lapis.requires : undefined;
+    if (!requires)
+        return undefined;
+    const requirements = {
+        tools: readStringList(requires.tools),
+        capabilities: readStringList(requires.capabilities),
+        extensions: readStringList(requires.extensions),
+    };
+    if (!requirements.tools &&
+        !requirements.capabilities &&
+        !requirements.extensions) {
+        return undefined;
+    }
+    return requirements;
+}
+export function parseSkillMarkdown(content, input) {
+    const match = content.match(FRONTMATTER);
+    if (!match) {
+        throw new SkillParseError(input.path, "SKILL.md must start with YAML frontmatter.");
+    }
+    let data;
+    try {
+        data = parseYaml(match[1] ?? "");
+    }
+    catch {
+        throw new SkillParseError(input.path, "SKILL.md frontmatter is not valid YAML.");
+    }
+    if (!isRecord(data)) {
+        throw new SkillParseError(input.path, "SKILL.md frontmatter must be a mapping.");
+    }
+    const name = readString(data.name);
+    const description = readString(data.description);
+    if (!name) {
+        throw new SkillParseError(input.path, "SKILL.md must declare name.");
+    }
+    if (!SKILL_NAME_PATTERN.test(name)) {
+        throw new SkillParseError(input.path, `Invalid skill name: ${name}`);
+    }
+    if (!description) {
+        throw new SkillParseError(input.path, "SKILL.md must declare description.");
+    }
+    let command;
+    try {
+        command = parseCommand(data);
+    }
+    catch (error) {
+        throw new SkillParseError(input.path, error instanceof Error ? error.message : String(error));
+    }
+    const disableModel = readBoolean(data["disable-model-invocation"], false);
+    const descriptor = {
+        id: `${input.source}:${name}`,
+        name,
+        description,
+        source: input.source,
+        root: input.root,
+        version: skillContentVersion(content),
+        userInvocable: readBoolean(data["user-invocable"], true),
+        modelInvocable: !disableModel,
+        argumentHint: readString(data["argument-hint"]),
+        command,
+        requirements: parseRequirements(data),
+    };
+    return {
+        ...descriptor,
+        instructions: (match[2] ?? "").trim(),
+    };
+}

package/dist/skills/registry.d.ts

@@ -0,0 +1,21 @@
+import { type SkillDiscoveryOptions } from "./discovery";
+import type { AppSkillDescriptor, LoadedAppSkill, SkillActivation, SkillDiagnostic, SkillDiscoveryContext, SkillSnapshot } from "./types";
+export declare class SkillRegistry {
+    #private;
+    diagnostics: SkillDiagnostic[];
+    constructor(options: SkillDiscoveryOptions);
+    invalidate(): void;
+    discover(context: SkillDiscoveryContext): Promise<readonly AppSkillDescriptor[]>;
+    resolve(name: string, context: SkillDiscoveryContext): Promise<AppSkillDescriptor | undefined>;
+    load(id: string, version: string): Promise<LoadedAppSkill>;
+    snapshot(context: SkillDiscoveryContext): Promise<SkillSnapshot>;
+    activate(name: string, context: SkillDiscoveryContext, source: SkillActivation["source"], args?: string): Promise<SkillActivation>;
+    getLoaded(name: string): LoadedAppSkill | undefined;
+}
+export declare class SkillSnapshotStore {
+    #private;
+    set(bindingId: string, snapshot: SkillSnapshot): void;
+    get(bindingId: string): SkillSnapshot | undefined;
+    close(bindingId: string): void;
+    clear(): void;
+}

package/dist/skills/registry.js

@@ -0,0 +1,89 @@
+import { SkillDiscovery } from "./discovery";
+export class SkillRegistry {
+    #discovery;
+    #loaded = new Map();
+    #history = new Map();
+    #generation = 0;
+    diagnostics = [];
+    constructor(options) {
+        this.#discovery = new SkillDiscovery(options);
+    }
+    invalidate() {
+        this.#generation += 1;
+        this.#loaded.clear();
+    }
+    async discover(context) {
+        const discovered = await this.#discovery.discover(context);
+        this.diagnostics = discovered.diagnostics;
+        this.#loaded.clear();
+        for (const skill of discovered.skills) {
+            this.#loaded.set(skill.id, skill);
+            this.#history.set(`${skill.id}@${skill.version}`, skill);
+        }
+        return discovered.skills;
+    }
+    async resolve(name, context) {
+        const skills = await this.discover(context);
+        return skills.find((skill) => skill.name === name);
+    }
+    async load(id, version) {
+        const loaded = this.#history.get(`${id}@${version}`) ??
+            this.#loaded.get(id) ??
+            [...this.#history.values()].find((skill) => skill.version === version &&
+                (skill.id === id || skill.name === id));
+        if (!loaded || loaded.version !== version) {
+            throw new Error(`Skill is not available: ${id}`);
+        }
+        return loaded;
+    }
+    async snapshot(context) {
+        const skills = await this.discover(context);
+        const entries = skills.map((skill) => ({
+            skillId: skill.id,
+            name: skill.name,
+            description: skill.description,
+            version: skill.version,
+            userInvocable: skill.userInvocable,
+            modelInvocable: skill.modelInvocable,
+            argumentHint: skill.argumentHint,
+        }));
+        return Object.freeze({
+            id: `skill-snapshot-${this.#generation}-${crypto.randomUUID()}`,
+            createdAt: new Date().toISOString(),
+            skills: Object.freeze(entries),
+        });
+    }
+    async activate(name, context, source, args) {
+        const descriptor = await this.resolve(name, context);
+        if (!descriptor) {
+            throw new Error(`Unknown skill: ${name}`);
+        }
+        const loaded = await this.load(descriptor.id, descriptor.version);
+        return {
+            skillId: loaded.id,
+            skillName: loaded.name,
+            version: loaded.version,
+            source,
+            arguments: args,
+            instructions: loaded.instructions,
+        };
+    }
+    getLoaded(name) {
+        return [...this.#loaded.values()].find((skill) => skill.name === name);
+    }
+}
+export class SkillSnapshotStore {
+    #snapshots = new Map();
+    set(bindingId, snapshot) {
+        this.#snapshots.set(bindingId, snapshot);
+    }
+    get(bindingId) {
+        return this.#snapshots.get(bindingId);
+    }
+    close(bindingId) {
+        this.#snapshots.delete(bindingId);
+    }
+    clear() {
+        this.#snapshots.clear();
+    }
+}

package/dist/skills/seed.d.ts

@@ -0,0 +1,5 @@
+import type { Vault } from "@lapis-notes/api";
+export declare function bundledSkillVaultPath(name: string): string;
+export declare function seedBundledSkills(vault: Vault, options?: {
+    overwrite?: boolean;
+}): Promise<void>;

package/dist/skills/seed.js

@@ -0,0 +1,18 @@
+import { BUNDLED_SKILL_MARKDOWN } from "./bundled/research";
+export function bundledSkillVaultPath(name) {
+    return `.agents/skills/${name}/SKILL.md`;
+}
+export async function seedBundledSkills(vault, options = {}) {
+    for (const [name, markdown] of Object.entries(BUNDLED_SKILL_MARKDOWN)) {
+        const path = bundledSkillVaultPath(name);
+        const existing = vault.getFileByPath(path);
+        if (existing && !options.overwrite)
+            continue;
+        if (existing) {
+            await vault.modify(existing, markdown);
+            continue;
+        }
+        await vault.mkpath(`.agents/skills/${name}`);
+        await vault.create(path, markdown);
+    }
+}

package/dist/skills/skill-tools.d.ts

@@ -0,0 +1,8 @@
+import type { AppTool } from "@lapis-notes/api/agent-tools";
+import type { Vault } from "@lapis-notes/api";
+import type { SkillRegistry, SkillSnapshotStore } from "./registry";
+export declare function createSkillAppTools(options: {
+    registry: SkillRegistry;
+    snapshots: SkillSnapshotStore;
+    vault: Vault;
+}): AppTool[];

package/dist/skills/skill-tools.js

@@ -0,0 +1,113 @@
+const MAX_RESOURCE_BYTES = 64 * 1024;
+export function createSkillAppTools(options) {
+    return [
+        {
+            name: "skills_read",
+            description: "Load the full instructions for an available application skill.",
+            inputSchema: {
+                type: "object",
+                properties: { name: { type: "string" } },
+                required: ["name"],
+            },
+            effect: "read",
+            async execute(input, context) {
+                const name = input && typeof input === "object" && "name" in input
+                    ? String(input.name)
+                    : "";
+                const snapshot = options.snapshots.get(context.agentBindingId);
+                const entry = snapshot?.skills.find((skill) => skill.name === name);
+                if (!entry) {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `Unknown skill: ${name}` }],
+                    };
+                }
+                if (!entry.modelInvocable) {
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: "text",
+                                text: `Skill ${name} is not available for model invocation.`,
+                            },
+                        ],
+                    };
+                }
+                const loaded = await options.registry.load(entry.skillId, entry.version);
+                return {
+                    content: [{ type: "text", text: loaded.instructions }],
+                    structuredContent: {
+                        name: loaded.name,
+                        version: loaded.version,
+                        instructions: loaded.instructions,
+                        resources: [],
+                    },
+                };
+            },
+        },
+        {
+            name: "skills_resource",
+            description: "Read a resource belonging to a skill already available to this agent.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    skill: { type: "string" },
+                    path: { type: "string" },
+                },
+                required: ["skill", "path"],
+            },
+            effect: "read",
+            async execute(input, context) {
+                const body = input && typeof input === "object"
+                    ? input
+                    : {};
+                const skillName = String(body.skill ?? "");
+                const relative = String(body.path ?? "").replaceAll("\\", "/");
+                const snapshot = options.snapshots.get(context.agentBindingId);
+                const entry = snapshot?.skills.find((skill) => skill.name === skillName);
+                if (!entry) {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `Unknown skill: ${skillName}` }],
+                    };
+                }
+                if (!relative ||
+                    relative.startsWith("/") ||
+                    relative.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: "Skill resource path is invalid." }],
+                    };
+                }
+                let loaded;
+                try {
+                    loaded = await options.registry.load(entry.skillId, entry.version);
+                }
+                catch {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `Skill is not loaded: ${skillName}` }],
+                    };
+                }
+                const target = `${loaded.root}/${relative}`;
+                const file = options.vault.getFileByPath(target);
+                if (!file) {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `Skill resource not found: ${relative}` }],
+                    };
+                }
+                const text = await options.vault.cachedRead(file);
+                if (new TextEncoder().encode(text).byteLength > MAX_RESOURCE_BYTES) {
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: "Skill resource exceeds the size limit." }],
+                    };
+                }
+                return {
+                    content: [{ type: "text", text }],
+                };
+            },
+        },
+    ];
+}