agent-trellis 0.10.0 → 0.11.0

package/dist/lib/scopeSelection.js

@@ -0,0 +1,65 @@
+/**
+ * Shared agent-scope selection for `skill scope` / `mcp scope`
+ * (trellis-scope-editing-and-auth-status design.md D1–D3). Both commands
+ * take exactly one of `--agents a,b`, `--all`, `--none`; keeping the parsing,
+ * validation and normalization here means a skill and an MCP server can never
+ * disagree about what a given selection means.
+ */
+import { ALL_AGENTS } from "../core/types.js";
+export const SCOPE_SELECTOR_USAGE = "exactly one of --agents <ids>, --all, --none is required";
+/** `argv.indexOf`-style reader, same idiom as every other command's flags. */
+export function parseScopeArgs(argv) {
+    const i = argv.indexOf("--agents");
+    return {
+        ...(i >= 0 ? { agents: argv[i + 1] ?? "" } : {}),
+        all: argv.includes("--all"),
+        none: argv.includes("--none"),
+    };
+}
+function sameSet(a, b) {
+    return a.length === b.length && a.every((id) => b.includes(id));
+}
+export function resolveScopeSelection(raw, managed) {
+    const chosen = [raw.agents !== undefined, raw.all === true, raw.none === true].filter(Boolean).length;
+    if (chosen !== 1)
+        return { ok: false, detail: SCOPE_SELECTOR_USAGE };
+    if (raw.all)
+        return { ok: true, scope: undefined, mode: "all", normalizedFromFull: false };
+    if (raw.none)
+        return { ok: true, scope: [], mode: "none", normalizedFromFull: false };
+    // An empty list is refused rather than read as "nobody": "nobody" is a real
+    // choice and has its own spelling, so a blank value is almost always a slip.
+    const ids = [...new Set((raw.agents ?? "").split(",").map((s) => s.trim()).filter(Boolean))];
+    if (ids.length === 0) {
+        return { ok: false, detail: "--agents must list at least one agent id (use --none for no agent at all)" };
+    }
+    for (const id of ids) {
+        if (!ALL_AGENTS.includes(id)) {
+            return { ok: false, detail: `--agents "${id}" is not a recognized agent id (${ALL_AGENTS.join(", ")})` };
+        }
+        // An unmanaged id would be accepted by the data model but never take
+        // effect — scope is always intersected with the managed set — so writing
+        // it would only leave config that looks like it does something.
+        if (!managed.includes(id)) {
+            const known = managed.length > 0 ? `managed agents: ${managed.join(", ")}` : "no agents are managed yet — run `trellis onboard` first";
+            return { ok: false, detail: `--agents "${id}" is not a managed agent (${known})` };
+        }
+    }
+    // Stable on-disk order regardless of how the user typed the list.
+    const scope = ALL_AGENTS.filter((id) => ids.includes(id));
+    if (sameSet(scope, managed))
+        return { ok: true, scope: undefined, mode: "all", normalizedFromFull: true };
+    return { ok: true, scope, mode: "explicit", normalizedFromFull: false };
+}
+/** Order-insensitive equality between the scope on disk and the one about to
+ * be written, with `undefined` (no explicit scope) distinct from `[]`. */
+export function sameScope(current, next) {
+    if (current === undefined || next === undefined)
+        return current === next;
+    return sameSet(current, next);
+}
+export function describeScope(scope, managed) {
+    if (scope === undefined)
+        return `every managed agent (${managed.join(", ") || "none managed yet"})`;
+    return scope.length > 0 ? scope.join(", ") : "no agent";
+}

package/dist/lib/skillManifest.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Manifest for serving a canonical skill in the shape the Skills-over-MCP
+ * extension defines (trellis-skills-over-mcp design.md D2/D3): every file's
+ * URI, `sha256:<hex>` digest and byte size, computed from the exact bytes
+ * that `resources/read` returns. One reader serves both, so the manifest and
+ * the content can never disagree.
+ *
+ * A digest here means "these bytes match this manifest" — it is not a claim
+ * about the content's safety (design.md D5).
+ */
+/** The extension's SHOULD-NOT-exceed limits per skill. */
+export declare const MAX_SKILL_FILES = 512;
+export declare const MAX_SKILL_BYTES: number;
+/** Same per-file bound the existing provider tools enforce. */
+export declare const MAX_SKILL_FILE_BYTES: number;
+export interface SkillManifestFile {
+    uri: string;
+    digest: string;
+    size: number;
+}
+export interface SkillEntry {
+    uri: string;
+    frontmatter: Record<string, unknown>;
+    resources: SkillManifestFile[];
+}
+export type SkillBuild = {
+    ok: true;
+    entry: SkillEntry;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function skillRootUri(name: string): string;
+export declare function skillFileUri(name: string, relativePath: string): string;
+/** `skill://<name>/<path>` → parts, or undefined for any other shape. Parsed
+ * by hand: `URL` would lowercase the authority and mangle odd names. */
+export declare function parseSkillUri(uri: string): {
+    name: string;
+    path: string;
+} | undefined;
+export declare function digestOf(bytes: Buffer): string;
+/**
+ * The one reader. Refuses secret-shaped paths, anything resolving outside the
+ * skill root (symlink escape included), non-files and oversized files; returns
+ * the raw bytes otherwise.
+ */
+export declare function readSkillFileBytes(skillDir: string, relativePath: string): Buffer;
+export declare function mimeTypeFor(path: string): string;
+/** Valid UTF-8 round-trips exactly as `text`; anything else must go out as a
+ * base64 blob, or the bytes a host verifies would not be the bytes we hashed. */
+export declare function toResourceContent(uri: string, path: string, bytes: Buffer): {
+    uri: string;
+    mimeType: string;
+    text: string;
+} | {
+    uri: string;
+    mimeType: string;
+    blob: string;
+};
+/**
+ * Builds the entry for one skill, or says why it cannot be served. A skill
+ * that breaks a limit is omitted whole rather than published with a partial
+ * manifest — a partial manifest is a false claim of completeness (D2).
+ */
+export declare function buildSkillEntry(name: string, skillDir: string): SkillBuild;

package/dist/lib/skillManifest.js

@@ -0,0 +1,203 @@
+/**
+ * Manifest for serving a canonical skill in the shape the Skills-over-MCP
+ * extension defines (trellis-skills-over-mcp design.md D2/D3): every file's
+ * URI, `sha256:<hex>` digest and byte size, computed from the exact bytes
+ * that `resources/read` returns. One reader serves both, so the manifest and
+ * the content can never disagree.
+ *
+ * A digest here means "these bytes match this manifest" — it is not a claim
+ * about the content's safety (design.md D5).
+ */
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { parse as parseYaml } from "yaml";
+/** The extension's SHOULD-NOT-exceed limits per skill. */
+export const MAX_SKILL_FILES = 512;
+export const MAX_SKILL_BYTES = 16 * 1024 * 1024;
+/** Same per-file bound the existing provider tools enforce. */
+export const MAX_SKILL_FILE_BYTES = 256 * 1024;
+const SKILL_SCHEME = "skill://";
+/** Agent Skills naming rule: lowercase alphanumerics and single hyphens. It
+ * also keeps the name safe as a URI authority, which lowercases. */
+const NAME_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const SKIPPED_DIRS = new Set(["node_modules"]);
+export function skillRootUri(name) {
+    return `${SKILL_SCHEME}${name}/SKILL.md`;
+}
+export function skillFileUri(name, relativePath) {
+    return `${SKILL_SCHEME}${name}/${relativePath.split(sep).map(encodeURIComponent).join("/")}`;
+}
+/** `skill://<name>/<path>` → parts, or undefined for any other shape. Parsed
+ * by hand: `URL` would lowercase the authority and mangle odd names. */
+export function parseSkillUri(uri) {
+    if (!uri.startsWith(SKILL_SCHEME))
+        return undefined;
+    const rest = uri.slice(SKILL_SCHEME.length);
+    const slash = rest.indexOf("/");
+    if (slash <= 0)
+        return undefined;
+    const name = rest.slice(0, slash);
+    try {
+        const segments = rest.slice(slash + 1).split("/").map(decodeURIComponent);
+        if (segments.length === 0 || segments.some((s) => s === "" || s === "." || s === ".."))
+            return undefined;
+        return { name, path: segments.join("/") };
+    }
+    catch {
+        return undefined;
+    }
+}
+function isSecretLikePath(path) {
+    const normalized = path.toLowerCase();
+    return normalized.includes(".env") || normalized.includes("secret") || normalized.endsWith("servers.local.env");
+}
+export function digestOf(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+/**
+ * The one reader. Refuses secret-shaped paths, anything resolving outside the
+ * skill root (symlink escape included), non-files and oversized files; returns
+ * the raw bytes otherwise.
+ */
+export function readSkillFileBytes(skillDir, relativePath) {
+    if (relativePath.length === 0 || relativePath.includes("\0") || isSecretLikePath(relativePath)) {
+        throw new Error("supporting file path is not allowed");
+    }
+    const root = realpathSync(skillDir);
+    const real = realpathSync(resolve(skillDir, relativePath));
+    const rel = relative(root, real);
+    if (rel.startsWith(`..${sep}`) || rel === ".." || rel === "")
+        throw new Error("file is outside the skill root");
+    if (isSecretLikePath(rel))
+        throw new Error("secret-like files are not readable through the skill provider");
+    const stat = statSync(real);
+    if (!stat.isFile())
+        throw new Error("not a regular file");
+    if (stat.size > MAX_SKILL_FILE_BYTES)
+        throw new Error(`file exceeds the ${MAX_SKILL_FILE_BYTES}-byte provider limit`);
+    return readFileSync(real);
+}
+export function mimeTypeFor(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".md"))
+        return "text/markdown";
+    if (lower.endsWith(".json"))
+        return "application/json";
+    if (lower.endsWith(".yaml") || lower.endsWith(".yml"))
+        return "application/yaml";
+    if (lower.endsWith(".html"))
+        return "text/html";
+    return "text/plain";
+}
+/** Valid UTF-8 round-trips exactly as `text`; anything else must go out as a
+ * base64 blob, or the bytes a host verifies would not be the bytes we hashed. */
+export function toResourceContent(uri, path, bytes) {
+    try {
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return { uri, mimeType: mimeTypeFor(path), text };
+    }
+    catch {
+        return { uri, mimeType: "application/octet-stream", blob: bytes.toString("base64") };
+    }
+}
+function parseFrontmatter(content) {
+    if (!content.startsWith("---"))
+        return undefined;
+    const end = content.indexOf("\n---", 3);
+    if (end < 0)
+        return undefined;
+    try {
+        const parsed = parseYaml(content.slice(3, end));
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Walks the skill directory without following links out of it. Stops as soon
+ * as a limit is exceeded so a huge tree is never fully traversed. */
+function collectFiles(skillDir) {
+    const files = [];
+    const stack = [skillDir];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        for (const name of readdirSync(dir).sort()) {
+            if (name.startsWith(".") || SKIPPED_DIRS.has(name))
+                continue;
+            const full = resolve(dir, name);
+            const link = lstatSync(full);
+            if (link.isSymbolicLink()) {
+                // A link is followed only if it stays inside the root and is a file.
+                try {
+                    const target = realpathSync(full);
+                    const rel = relative(realpathSync(skillDir), target);
+                    if (rel.startsWith(`..${sep}`) || rel === ".." || !statSync(target).isFile())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+            }
+            else if (link.isDirectory()) {
+                stack.push(full);
+                continue;
+            }
+            else if (!link.isFile()) {
+                continue;
+            }
+            files.push(relative(skillDir, full));
+            if (files.length > MAX_SKILL_FILES)
+                return { tooLarge: `more than ${MAX_SKILL_FILES} files` };
+        }
+    }
+    return { files };
+}
+/**
+ * Builds the entry for one skill, or says why it cannot be served. A skill
+ * that breaks a limit is omitted whole rather than published with a partial
+ * manifest — a partial manifest is a false claim of completeness (D2).
+ */
+export function buildSkillEntry(name, skillDir) {
+    if (!NAME_RE.test(name) || name.length > 64) {
+        return { ok: false, reason: `"${name}" is not a valid Agent Skills name (lowercase letters, digits and single hyphens, at most 64 characters)` };
+    }
+    if (!existsSync(resolve(skillDir, "SKILL.md")))
+        return { ok: false, reason: `"${name}" has no SKILL.md` };
+    let skillMd;
+    try {
+        skillMd = readSkillFileBytes(skillDir, "SKILL.md");
+    }
+    catch (err) {
+        return { ok: false, reason: `"${name}" SKILL.md cannot be served: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    const frontmatter = parseFrontmatter(skillMd.toString("utf8"));
+    if (!frontmatter || typeof frontmatter.name !== "string" || typeof frontmatter.description !== "string" || frontmatter.description.length === 0) {
+        return { ok: false, reason: `"${name}" SKILL.md frontmatter needs a string name and a non-empty description` };
+    }
+    if (frontmatter.name !== name) {
+        return { ok: false, reason: `"${name}" directory name does not match its frontmatter name "${frontmatter.name}"` };
+    }
+    const collected = collectFiles(skillDir);
+    if ("tooLarge" in collected)
+        return { ok: false, reason: `"${name}" exceeds the extension's size limit (${collected.tooLarge})` };
+    const resources = [];
+    let total = 0;
+    for (const rel of collected.files) {
+        let bytes;
+        try {
+            bytes = readSkillFileBytes(skillDir, rel);
+        }
+        catch {
+            continue; // refused by the reader: absent from the manifest and from reads alike
+        }
+        total += bytes.length;
+        if (total > MAX_SKILL_BYTES)
+            return { ok: false, reason: `"${name}" exceeds the extension's size limit (more than ${MAX_SKILL_BYTES} bytes)` };
+        resources.push({ uri: skillFileUri(name, rel), digest: digestOf(bytes), size: bytes.length });
+    }
+    if (!resources.some((file) => file.uri === skillRootUri(name))) {
+        return { ok: false, reason: `"${name}" SKILL.md is missing from its own manifest` };
+    }
+    return { ok: true, entry: { uri: skillRootUri(name), frontmatter, resources } };
+}

package/dist/lib/skillProvider.d.ts

@@ -1,11 +1,31 @@
 import type { Resource, ReadResourceResult, Tool, CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
+import { type SkillEntry } from "./skillManifest.js";
 export declare class SkillProvider implements TrellisProvider {
+    private readonly onDiagnostic;
     readonly id = "skills";
+    /** Each omitted skill is reported once per process, not on every request. */
+    private readonly reported;
+    constructor(onDiagnostic?: (message: string) => void);
+    /**
+     * The skills this agent may be served under `skill://`, each with a manifest
+     * computed from the bytes it would read (trellis-skills-over-mcp D2/D3). A
+     * skill that cannot be served validly is omitted and reported, never served
+     * under a URI the specification calls invalid.
+     */
+    private catalog;
+    /** `skills/list` — one entry per servable, in-scope skill. */
+    listSkillEntries(context: RuntimeContext): SkillEntry[];
+    /** `skills/get` — lookup by URI, independent of listing. Out-of-scope and
+     * unknown URIs are indistinguishable by design. */
+    getSkillEntry(uri: string, context: RuntimeContext): SkillEntry | undefined;
     listTools(): Tool[];
     callTool(name: string, args: unknown, context: RuntimeContext): Promise<CallToolResult>;
     listResources(context: RuntimeContext): Resource[];
     readResource(uri: URL, context: RuntimeContext): ReadResourceResult;
+    /** Serves only what the manifest advertises, from the same reader that
+     * computed its digests — the two cannot disagree. */
+    private readConventionalResource;
     private search;
     private readSkill;
     private readFile;

package/dist/lib/skillProvider.js

@@ -5,6 +5,7 @@ import { parse as parseYaml } from "yaml";
 import { isInScope } from "../core/adapter.js";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { resolveScope } from "../core/types.js";
+import { buildSkillEntry, parseSkillUri, readSkillFileBytes, toResourceContent } from "./skillManifest.js";
 const MAX_FILE_BYTES = 256 * 1024;
 const SKILL_RESOURCE_PREFIX = "trellis://skills/";
 const SEARCH_TOOL = {
@@ -99,7 +100,47 @@ function skillMetadata(skill, canonical, agentId, content) {
     };
 }
 export class SkillProvider {
+    onDiagnostic;
     id = "skills";
+    /** Each omitted skill is reported once per process, not on every request. */
+    reported = new Set();
+    constructor(onDiagnostic = (message) => console.error(message)) {
+        this.onDiagnostic = onDiagnostic;
+    }
+    /**
+     * The skills this agent may be served under `skill://`, each with a manifest
+     * computed from the bytes it would read (trellis-skills-over-mcp D2/D3). A
+     * skill that cannot be served validly is omitted and reported, never served
+     * under a URI the specification calls invalid.
+     */
+    catalog(canonical, agentId) {
+        const out = [];
+        for (const skill of canonical.skills) {
+            if (!hasSkillDocument(skill) || !isInScope(agentId, skill.scope, canonical.managedAgents))
+                continue;
+            const built = buildSkillEntry(skill.name, skill.dir);
+            if (built.ok) {
+                out.push({ skill, entry: built.entry });
+            }
+            else if (!this.reported.has(built.reason)) {
+                this.reported.add(built.reason);
+                this.onDiagnostic(`trellis-mcp-runtime: skill not served under skill://: ${built.reason}`);
+            }
+        }
+        return out;
+    }
+    /** `skills/list` — one entry per servable, in-scope skill. */
+    listSkillEntries(context) {
+        return this.catalog(loadCanonicalSource(context.homeDir), context.agentId).map(({ entry }) => entry);
+    }
+    /** `skills/get` — lookup by URI, independent of listing. Out-of-scope and
+     * unknown URIs are indistinguishable by design. */
+    getSkillEntry(uri, context) {
+        const parsed = parseSkillUri(uri);
+        if (!parsed || parsed.path !== "SKILL.md")
+            return undefined;
+        return this.listSkillEntries(context).find((entry) => entry.uri === uri);
+    }
     listTools() {
         return [SEARCH_TOOL, READ_TOOL, READ_FILE_TOOL];
     }
@@ -116,7 +157,7 @@ export class SkillProvider {
     }
     listResources(context) {
         const canonical = loadCanonicalSource(context.homeDir);
-        return canonical.skills
+        const legacy = canonical.skills
             .filter((skill) => hasSkillDocument(skill) && isInScope(context.agentId, skill.scope, canonical.managedAgents))
             .map((skill) => ({
             uri: skillUri(skill.name),
@@ -124,8 +165,15 @@ export class SkillProvider {
             description: `Instructions for the ${skill.name} skill`,
             mimeType: "text/markdown",
         }));
+        // The convention's view of the same data, additive to the above
+        // (design.md D1): every manifest file, so a host that lists resources
+        // sees exactly what skills/list advertises.
+        const conventional = this.catalog(canonical, context.agentId).flatMap(({ entry }) => entry.resources.map((file) => ({ uri: file.uri, name: file.uri.slice("skill://".length), mimeType: file.uri.endsWith(".md") ? "text/markdown" : "text/plain", size: file.size })));
+        return [...legacy, ...conventional];
     }
     readResource(uri, context) {
+        if (uri.protocol === "skill:")
+            return this.readConventionalResource(uri.toString(), context);
         if (uri.protocol !== "trellis:" || uri.hostname !== "skills") {
             throw new Error(`unsupported skill resource URI "${uri.toString()}"`);
         }
@@ -140,6 +188,18 @@ export class SkillProvider {
         const content = this.readBoundedFile(resolve(skill.dir, "SKILL.md"), skill.dir);
         return { contents: [{ uri: uri.toString(), mimeType: "text/markdown", text: content }] };
     }
+    /** Serves only what the manifest advertises, from the same reader that
+     * computed its digests — the two cannot disagree. */
+    readConventionalResource(uri, context) {
+        const parsed = parseSkillUri(uri);
+        const canonical = loadCanonicalSource(context.homeDir);
+        const skill = parsed ? skillFor(canonical, context.agentId, parsed.name) : undefined;
+        const served = skill && parsed ? this.catalog(canonical, context.agentId).find(({ entry }) => entry.uri === `skill://${parsed.name}/SKILL.md`) : undefined;
+        if (!parsed || !skill || !served || !served.entry.resources.some((file) => file.uri === uri)) {
+            throw new Error(`skill resource "${uri}" is not available to ${context.agentId}`);
+        }
+        return { contents: [toResourceContent(uri, parsed.path, readSkillFileBytes(skill.dir, parsed.path))] };
+    }
     search(canonical, agentId, input) {
         const query = typeof input.query === "string" ? input.query.trim().toLowerCase() : "";
         const limit = typeof input.limit === "number" ? Math.min(50, Math.max(1, Math.floor(input.limit))) : 20;