agent-trellis 0.10.0 → 0.12.0

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;

package/dist/lib/taskProvider.d.ts

@@ -1,4 +1,4 @@
-import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolResult, Tool } from "@modelcontextprotocol/server";
 import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
 export declare class TaskProvider implements TrellisProvider {
     readonly id = "tasks";

package/dist/lib/upstreamResources.d.ts

@@ -0,0 +1,23 @@
+import type { Client, Resource, ReadResourceResult } from "@modelcontextprotocol/client";
+import { type SkillEntry } from "./skillManifest.js";
+/** The outer response belongs to the gateway; upstream identity is provenance. */
+export declare function withoutUpstreamServerInfo<T extends {
+    _meta?: Record<string, unknown>;
+}>(result: T): T;
+/** Retain path segments so relative supporting-file references remain valid. */
+export declare function upstreamUri(source: string, uri: string): string;
+export declare class UpstreamResources {
+    private readonly timeoutMs;
+    private readonly warn;
+    private readonly clients;
+    private readonly files;
+    constructor(timeoutMs: number, warn: (message: string) => void);
+    add(source: string, client: Client): void;
+    private skillsEnabled;
+    private isolated;
+    listResources(): Promise<Resource[]>;
+    private registerSkill;
+    listSkills(): Promise<SkillEntry[]>;
+    getSkill(uri: string): Promise<SkillEntry | undefined>;
+    readResource(uri: string): Promise<ReadResourceResult>;
+}

package/dist/lib/upstreamResources.js

@@ -0,0 +1,192 @@
+import { z } from "zod/v4";
+import { isDeepStrictEqual } from "node:util";
+import { parse as parseYaml } from "yaml";
+import { digestOf, MAX_SKILL_BYTES, MAX_SKILL_FILES } from "./skillManifest.js";
+import { withTimeout } from "./mcpConnect.js";
+const EXTENSION = "io.modelcontextprotocol/skills";
+const listSchema = z.looseObject({ skills: z.array(z.unknown()), nextCursor: z.string().optional() });
+const getSchema = z.looseObject({ skill: z.unknown() });
+const PREFIX = "trellis-upstream:";
+/** The outer response belongs to the gateway; upstream identity is provenance. */
+export function withoutUpstreamServerInfo(result) {
+    if (!result._meta || !("io.modelcontextprotocol/serverInfo" in result._meta))
+        return result;
+    const { "io.modelcontextprotocol/serverInfo": _server, ...meta } = result._meta;
+    return { ...result, _meta: meta };
+}
+/** Retain path segments so relative supporting-file references remain valid. */
+export function upstreamUri(source, uri) {
+    const original = new URL(uri);
+    if (original.username || original.password || !original.pathname.startsWith("/"))
+        throw new Error("resource URI must be hierarchical and contain no credentials");
+    const label = `s${Buffer.from(source).toString("hex")}`;
+    const protocol = Buffer.from(original.protocol).toString("base64url");
+    return `${PREFIX}//${label}/${protocol}/${encodeURIComponent(original.host) || "~"}${original.pathname}${original.search}${original.hash}`;
+}
+function originalUri(uri) {
+    try {
+        const exposed = new URL(uri);
+        if (exposed.protocol !== PREFIX || !/^s(?:[0-9a-f]{2})+$/.test(exposed.hostname))
+            return undefined;
+        const match = /^\/([^/]+)\/([^/]+)(\/.*)$/.exec(exposed.pathname);
+        if (!match)
+            return undefined;
+        const protocol = Buffer.from(match[1], "base64url").toString();
+        if (!/^[a-z][a-z0-9+.-]*:$/.test(protocol))
+            return undefined;
+        const source = Buffer.from(exposed.hostname.slice(1), "hex").toString();
+        const original = `${protocol}//${match[2] === "~" ? "" : decodeURIComponent(match[2])}${match[3]}${exposed.search}${exposed.hash}`;
+        if (upstreamUri(source, original) !== uri)
+            return undefined;
+        return { source, original };
+    }
+    catch {
+        return undefined;
+    }
+}
+export class UpstreamResources {
+    timeoutMs;
+    warn;
+    clients = new Map();
+    files = new Map();
+    constructor(timeoutMs, warn) {
+        this.timeoutMs = timeoutMs;
+        this.warn = warn;
+    }
+    add(source, client) { this.clients.set(source, client); }
+    skillsEnabled(client) {
+        return Boolean(client.getServerCapabilities()?.resources && client.getDiscoverResult()?.capabilities.extensions?.[EXTENSION]);
+    }
+    async isolated(source, work, fallback) {
+        try {
+            return await withTimeout(work(), this.timeoutMs, "upstream resource request timed out");
+        }
+        catch (err) {
+            this.warn(`trellis-mcp-runtime: upstream "${source}" resources: ${err instanceof Error ? err.message : String(err)}`);
+            return fallback;
+        }
+    }
+    async listResources() {
+        const lists = await Promise.all([...this.clients].map(([source, client]) => this.isolated(source, async () => {
+            if (!client.getServerCapabilities()?.resources)
+                return [];
+            const { resources } = await client.listResources();
+            if (resources.length > 8192)
+                throw new Error("upstream resource catalog exceeds 8192 entries");
+            return resources.map((resource) => {
+                const uri = upstreamUri(source, resource.uri);
+                if (!this.files.get(uri)?.manifest)
+                    this.files.set(uri, { source, original: resource.uri });
+                return { ...resource, uri, _meta: { ...resource._meta, "io.trellis/origin": { server: source, uri: resource.uri } } };
+            });
+        }, [])));
+        return lists.flat();
+    }
+    registerSkill(source, value) {
+        if (!value || typeof value !== "object")
+            throw new Error("invalid upstream skill entry");
+        const entry = value;
+        if (typeof entry.uri !== "string" || !entry.frontmatter || typeof entry.frontmatter.name !== "string" || typeof entry.frontmatter.description !== "string" || !entry.frontmatter.description.trim())
+            throw new Error("invalid upstream skill metadata");
+        if (!Array.isArray(entry.resources) || entry.resources.length === 0 || entry.resources.length > MAX_SKILL_FILES)
+            throw new Error("upstream skill needs a bounded, complete manifest");
+        const root = new URL(".", entry.uri).toString();
+        if (!new URL(entry.uri).pathname.endsWith("/SKILL.md") || !/^[a-z0-9]+(-[a-z0-9]+)*$/.test(entry.frontmatter.name) || entry.frontmatter.name.length > 64)
+            throw new Error("invalid upstream skill name or entry URI");
+        const directory = new URL(root);
+        const parent = directory.pathname.split("/").filter(Boolean).at(-1) ?? directory.hostname;
+        if (decodeURIComponent(parent) !== entry.frontmatter.name)
+            throw new Error("upstream skill name does not match its directory");
+        const seen = new Set();
+        let total = 0;
+        for (const file of entry.resources) {
+            if (!file || typeof file.uri !== "string" || !file.uri.startsWith(root) || !/^sha256:[a-f0-9]{64}$/.test(file.digest) || !Number.isSafeInteger(file.size) || file.size < 0 || seen.has(file.uri))
+                throw new Error("invalid upstream skill manifest");
+            const parsed = new URL(file.uri);
+            if (!parsed.toString().startsWith(root))
+                throw new Error("skill file escaped its source directory");
+            upstreamUri(source, file.uri);
+            seen.add(file.uri);
+            total += file.size;
+        }
+        if (total > MAX_SKILL_BYTES || !seen.has(entry.uri))
+            throw new Error("upstream skill manifest exceeds limits or omits SKILL.md");
+        const uri = upstreamUri(source, entry.uri);
+        for (const [key, route] of this.files)
+            if (route.skill === uri)
+                this.files.delete(key);
+        const resources = entry.resources.map((file) => {
+            const exposed = upstreamUri(source, file.uri);
+            this.files.set(exposed, { source, original: file.uri, manifest: file, skill: uri, ...(file.uri === entry.uri ? { frontmatter: entry.frontmatter } : {}) });
+            return { ...file, uri: exposed };
+        });
+        return { ...entry, uri, resources, _meta: { "io.trellis/origin": { server: source, uri: entry.uri } } };
+    }
+    async listSkills() {
+        const lists = await Promise.all([...this.clients].map(([source, client]) => this.isolated(source, async () => {
+            if (!this.skillsEnabled(client))
+                return [];
+            const entries = [];
+            let cursor;
+            const cursors = new Set();
+            for (let page = 0; page < 64; page++) {
+                const result = await client.request({ method: "skills/list", params: cursor ? { cursor } : {} }, listSchema, { timeout: this.timeoutMs });
+                for (const entry of result.skills) {
+                    if (entries.length >= 2048)
+                        throw new Error("upstream skill catalog exceeds 2048 entries");
+                    try {
+                        entries.push(this.registerSkill(source, entry));
+                    }
+                    catch (err) {
+                        this.warn(`trellis-mcp-runtime: omitted skill from "${source}": ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                if (!result.nextCursor)
+                    return entries;
+                if (cursors.has(result.nextCursor))
+                    throw new Error("repeated upstream skill cursor");
+                cursors.add(result.nextCursor);
+                cursor = result.nextCursor;
+            }
+            throw new Error("upstream skill pagination exceeded 64 pages");
+        }, [])));
+        return lists.flat();
+    }
+    async getSkill(uri) {
+        const decoded = originalUri(uri);
+        if (!decoded)
+            return undefined;
+        const client = this.clients.get(decoded.source);
+        if (!client || !this.skillsEnabled(client))
+            return undefined;
+        const result = await client.request({ method: "skills/get", params: { uri: decoded.original } }, getSchema, { timeout: this.timeoutMs });
+        if (result.skill?.uri !== decoded.original)
+            throw new Error("upstream returned another skill identity");
+        const entry = this.registerSkill(decoded.source, result.skill);
+        if (entry.uri !== uri)
+            throw new Error("upstream returned another skill identity");
+        return entry;
+    }
+    async readResource(uri) {
+        const route = this.files.get(uri);
+        const client = route && this.clients.get(route.source);
+        if (!route || !client)
+            throw new Error("unknown upstream resource");
+        const result = await client.readResource({ uri: route.original }, { timeout: this.timeoutMs });
+        if (result.contents.length !== 1 || result.contents[0].uri !== route.original)
+            throw new Error("upstream resource identity mismatch");
+        const content = result.contents[0];
+        if (route.manifest) {
+            const bytes = "blob" in content ? Buffer.from(content.blob, "base64") : Buffer.from(content.text, "utf8");
+            if (bytes.length !== route.manifest.size || digestOf(bytes) !== route.manifest.digest)
+                throw new Error("upstream skill file differs from its manifest; refresh the skill entry");
+            if (route.frontmatter) {
+                const text = new TextDecoder("utf8", { fatal: true, ignoreBOM: true }).decode(bytes);
+                const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text);
+                if (!match || !isDeepStrictEqual(parseYaml(match[1]), route.frontmatter))
+                    throw new Error("upstream skill frontmatter differs from its entry");
+            }
+        }
+        return { ...withoutUpstreamServerInfo(result), ttlMs: 0, cacheScope: "private", contents: [{ ...content, uri }] };
+    }
+}