agent-trellis 0.10.0 → 0.12.0

package/dist/lib/oauth/flow.d.ts

@@ -31,6 +31,9 @@ export interface AuthorizeOptions {
      * is actually bound, so a fixed one is never required. */
     callbackPort?: number;
     timeoutMs?: number;
+    signal?: AbortSignal;
+    resourceUrl?: string;
+    onProgress?: (phase: "registering" | "waiting" | "exchanging") => void;
 }
 /**
  * RFC 7591. Returns `undefined` when the AS advertises no registration
@@ -58,3 +61,4 @@ export declare function registerClient(metadata: AuthorizationServerMetadata, re
  * caller's decision, so this stays testable without a home directory.
  */
 export declare function authorize(serverName: string, metadata: AuthorizationServerMetadata, opts?: AuthorizeOptions): Promise<StoredToken>;
+export declare function abortable<T>(value: T | Promise<T>, signal?: AbortSignal): Promise<T>;

package/dist/lib/oauth/flow.js

@@ -15,6 +15,7 @@
  */
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
 import { createPkcePair } from "./pkce.js";
 export class AuthorizationError extends Error {
 }
@@ -89,6 +90,11 @@ function listenForCallback(port) {
         });
         const server = createServer((req, res) => {
             const url = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (req.method !== "GET" || url.pathname !== "/callback") {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
             const result = {};
             const code = url.searchParams.get("code");
             const state = url.searchParams.get("state");
@@ -97,6 +103,9 @@ function listenForCallback(port) {
                 result.code = code;
             if (state)
                 result.state = state;
+            const issuer = url.searchParams.get("iss");
+            if (issuer)
+                result.issuer = issuer;
             if (error) {
                 result.error = error;
                 const description = url.searchParams.get("error_description");
@@ -106,7 +115,7 @@ function listenForCallback(port) {
             res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
             res.end(result.error
                 ? `<html><body><h1>Authorization failed</h1><p>${escapeHtml(result.errorDescription ?? result.error)}</p></body></html>`
-                : "<html><body><h1>Authorized</h1><p>You can close this tab and return to your terminal.</p></body></html>");
+                : "<html><body><h1>Authorization response received</h1><p>You can close this tab and return to Trellis.</p></body></html>");
             settle(result);
         });
         server.on("error", reject);
@@ -124,7 +133,8 @@ function escapeHtml(value) {
  * caller's decision, so this stays testable without a home directory.
  */
 export async function authorize(serverName, metadata, opts = {}) {
-    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    opts.signal?.throwIfAborted();
+    const fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, { ...init, signal: opts.signal }));
     const now = opts.now ?? Date.now;
     const timeoutMs = opts.timeoutMs ?? 300_000;
     const { server, port, received } = await listenForCallback(opts.callbackPort ?? 0);
@@ -133,13 +143,14 @@ export async function authorize(serverName, metadata, opts = {}) {
         let clientId = opts.clientId;
         let clientSecret = opts.clientSecret;
         if (!clientId) {
+            opts.onProgress?.("registering");
             // The AS cannot register us AND canonical carries no client_id — the
             // one dead end a person has to resolve by hand, so it is reported as
             // such rather than as a generic registration failure
             // (trellis-mcp-oauth-static-client design.md D3, task 2.3).
             let registered;
             try {
-                registered = await registerClient(metadata, redirectUri, { fetchImpl, scope: opts.scope });
+                registered = await abortable(registerClient(metadata, redirectUri, { fetchImpl, scope: opts.scope }), opts.signal);
             }
             catch (err) {
                 if (err instanceof AuthorizationError) {
@@ -164,8 +175,12 @@ export async function authorize(serverName, metadata, opts = {}) {
         authUrl.searchParams.set("state", state);
         if (opts.scope)
             authUrl.searchParams.set("scope", opts.scope);
-        await (opts.openBrowser ?? defaultOpenBrowser)(authUrl.toString());
-        const callback = await withTimeout(received, timeoutMs, `timed out waiting for the authorization callback for "${serverName}"`);
+        if (opts.resourceUrl)
+            authUrl.searchParams.set("resource", opts.resourceUrl);
+        opts.signal?.throwIfAborted();
+        opts.onProgress?.("waiting");
+        await abortable((opts.openBrowser ?? defaultOpenBrowser)(authUrl.toString()), opts.signal);
+        const callback = await withTimeout(received, timeoutMs, `timed out waiting for the authorization callback for "${serverName}"`, opts.signal);
         if (callback.error) {
             throw new AuthorizationError(`authorization for "${serverName}" was refused: ${callback.errorDescription ?? callback.error}`);
         }
@@ -177,6 +192,11 @@ export async function authorize(serverName, metadata, opts = {}) {
         if (callback.state !== state) {
             throw new AuthorizationError(`authorization callback for "${serverName}" carried an unexpected state parameter`);
         }
+        if ((callback.issuer && callback.issuer !== metadata.issuer) || (metadata.issuerParameterSupported && !callback.issuer)) {
+            throw new AuthorizationError("authorization callback issuer does not match the discovered authorization server");
+        }
+        opts.signal?.throwIfAborted();
+        opts.onProgress?.("exchanging");
         const body = new URLSearchParams({
             grant_type: "authorization_code",
             code: callback.code,
@@ -186,11 +206,13 @@ export async function authorize(serverName, metadata, opts = {}) {
         });
         if (clientSecret)
             body.set("client_secret", clientSecret);
-        const response = await fetchImpl(metadata.tokenEndpoint, {
+        if (opts.resourceUrl)
+            body.set("resource", opts.resourceUrl);
+        const response = await abortable(fetchImpl(metadata.tokenEndpoint, {
             method: "POST",
             headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
             body: body.toString(),
-        });
+        }), opts.signal);
         if (!response.ok) {
             throw new AuthorizationError(`token exchange for "${serverName}" failed with HTTP ${response.status}`);
         }
@@ -202,6 +224,8 @@ export async function authorize(serverName, metadata, opts = {}) {
             accessToken: payload.access_token,
             tokenEndpoint: metadata.tokenEndpoint,
             clientId,
+            issuer: metadata.issuer,
+            ...(opts.resourceUrl ? { resourceUrl: opts.resourceUrl } : {}),
         };
         if (payload.refresh_token)
             token.refreshToken = payload.refresh_token;
@@ -214,25 +238,38 @@ export async function authorize(serverName, metadata, opts = {}) {
         return token;
     }
     finally {
+        server.closeAllConnections();
         server.close();
     }
 }
-function withTimeout(promise, timeoutMs, message) {
+function withTimeout(promise, timeoutMs, message, signal) {
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new AuthorizationError(message)), timeoutMs);
+        const abort = () => { clearTimeout(timer); signal?.removeEventListener("abort", abort); reject(signal?.reason ?? new Error("authorization cancelled")); };
+        const timer = setTimeout(() => { signal?.removeEventListener("abort", abort); reject(new AuthorizationError(message)); }, timeoutMs);
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
         promise.then((value) => {
             clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
             resolve(value);
         }, (err) => {
             clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
             reject(err);
         });
     });
 }
+export function abortable(value, signal) {
+    return withTimeout(Promise.resolve(value), 300_000, "authorization timed out", signal);
+}
 async function defaultOpenBrowser(url) {
-    const { spawn } = await import("node:child_process");
     const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
     // Detached and fully ignored: a browser that outlives this command is
     // correct, and its stdio must not be inherited onto ours.
-    spawn(command, [url], { detached: true, stdio: "ignore" }).unref();
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, [url], { detached: true, stdio: "ignore" });
+        child.once("error", reject);
+        child.once("spawn", () => { child.unref(); resolve(); });
+    });
 }

package/dist/lib/oauth/refresh.d.ts

@@ -12,6 +12,7 @@ import { type StoredToken } from "./store.js";
 import type { FetchLike } from "./discovery.js";
 export interface RefreshOptions {
     fetchImpl?: FetchLike;
+    timeoutMs?: number;
     /** Test seam; also lets a caller widen the early-refresh skew. */
     now?: () => number;
     skewMs?: number;

package/dist/lib/oauth/refresh.js

@@ -49,7 +49,7 @@ export async function ensureFreshToken(homeDir, serverName, opts = {}) {
     }, { timeoutMs: opts.lockTimeoutMs, now });
 }
 export async function performRefresh(serverName, token, opts = {}) {
-    const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    const fetchImpl = opts.fetchImpl ?? ((url, init) => fetch(url, { ...init, signal: AbortSignal.timeout(opts.timeoutMs ?? 10_000) }));
     const now = opts.now ?? Date.now;
     if (!token.tokenEndpoint) {
         throw new RefreshError(`OAuth token for "${serverName}" has no recorded token endpoint — run \`trellis mcp auth ${serverName}\``);
@@ -59,6 +59,8 @@ export async function performRefresh(serverName, token, opts = {}) {
         body.set("client_id", token.clientId);
     if (token.clientSecret)
         body.set("client_secret", token.clientSecret);
+    if (token.resourceUrl)
+        body.set("resource", token.resourceUrl);
     const response = await fetchImpl(token.tokenEndpoint, {
         method: "POST",
         headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },

package/dist/lib/oauth/store.d.ts

@@ -29,6 +29,8 @@ export interface StoredToken {
      * metadata — the gateway's refresh path should be one request. */
     tokenEndpoint?: string;
     scope?: string;
+    resourceUrl?: string;
+    issuer?: string;
 }
 export declare function oauthDir(homeDir: string): string;
 /**

package/dist/lib/runtimeControlProvider.d.ts

@@ -1,4 +1,4 @@
-import type { CallToolResult, ReadResourceResult, Resource, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult, ReadResourceResult, Resource, Tool } from "@modelcontextprotocol/server";
 import type { GatewayBackend } from "./gatewayBackend.js";
 import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
 export declare class RuntimeControlProvider implements TrellisProvider {

package/dist/lib/scopeSelection.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 type { AgentId } from "../core/types.js";
+/** Raw, unvalidated flag values — the parser stays a dumb reader and every
+ * rule below lives in `resolveScopeSelection`. */
+export interface ScopeSelectorRaw {
+    /** Comma-separated agent ids. */
+    agents?: string;
+    all?: boolean;
+    none?: boolean;
+}
+export type ScopeSelection = {
+    ok: true;
+    /** What to record: `undefined` clears the explicit scope. */
+    scope: AgentId[] | undefined;
+    mode: "all" | "none" | "explicit";
+    /** True when the user listed every managed agent and the explicit scope
+     * was dropped instead of recorded (design.md D3). */
+    normalizedFromFull: boolean;
+} | {
+    ok: false;
+    detail: string;
+};
+export declare 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 declare function parseScopeArgs(argv: readonly string[]): ScopeSelectorRaw;
+export declare function resolveScopeSelection(raw: ScopeSelectorRaw, managed: readonly AgentId[]): ScopeSelection;
+/** Order-insensitive equality between the scope on disk and the one about to
+ * be written, with `undefined` (no explicit scope) distinct from `[]`. */
+export declare function sameScope(current: readonly AgentId[] | undefined, next: readonly AgentId[] | undefined): boolean;
+export declare function describeScope(scope: readonly AgentId[] | undefined, managed: readonly AgentId[]): string;

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,66 @@
+/**
+ * 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[];
+    _meta?: Record<string, unknown>;
+}
+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, ignoreBOM: 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 { Resource, ReadResourceResult, Tool, CallToolResult } from "@modelcontextprotocol/server";
 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;