@sammorrowdrums/mcpi-ext 0.2.1 → 1.0.0

package/dist/skills/discover.js

@@ -4,24 +4,30 @@ import { parseFrontmatter } from "@sammorrowdrums/mcpi";
  *
  * Looks for resources with `skill://` URIs ending in `/SKILL.md`,
  * reads each one, and parses YAML frontmatter for skill metadata.
+ *
+ * All resource I/O goes through the shared policy boundary, so a server can
+ * only ever surface its own skill resources.
  */
-export async function discoverSkillsFromServer(client, serverName, log = console.error) {
+export async function discoverSkillsFromServer(policy, serverName, log = console.error, signal) {
     const skills = [];
-    let resources;
+    let skillResources;
     try {
-        const result = await client.listResources();
-        resources = result.resources;
+        skillResources = await policy.listSkillResources(serverName, signal);
     }
     catch {
         log(`[skills] Server "${serverName}" does not support resources/list, skipping skill discovery`);
         return skills;
     }
-    const skillResources = resources.filter((r) => r.uri.startsWith("skill://") && r.uri.endsWith("/SKILL.md"));
     if (skillResources.length === 0)
         return skills;
     for (const resource of skillResources) {
         try {
-            const result = await client.readResource({ uri: resource.uri });
+            const result = await policy.readResource({
+                source: "skill-discovery",
+                serverName,
+                uri: resource.uri,
+                ...(signal ? { signal } : {}),
+            });
             const textContent = result.contents.find((c) => "text" in c);
             if (!textContent) {
                 log(`[skills] Skill resource ${resource.uri} returned no text content, skipping`);
@@ -31,7 +37,7 @@ export async function discoverSkillsFromServer(client, serverName, log = console
             const fm = parsed.frontmatter;
             const name = fm.name ?? resource.name;
             const description = fm.description ?? "";
-            const allowedTools = parseAllowedTools(fm["allowed-tools"]);
+            const allowedTools = parseAllowedTools(fm);
             if (!name) {
                 log(`[skills] Skill at ${resource.uri} has no name, skipping`);
                 continue;
@@ -49,12 +55,31 @@ export async function discoverSkillsFromServer(client, serverName, log = console
             log(`[skills] Failed to read skill ${resource.uri}: ${err.message}`);
         }
     }
-    return skills;
+    return skills.sort((left, right) => compareStrings(left.name, right.name));
+}
+function compareStrings(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
 }
-function parseAllowedTools(value) {
-    if (Array.isArray(value)) {
-        return value.filter((v) => typeof v === "string");
+/**
+ * Parse tool names from frontmatter, supporting both formats:
+ * - Current: `allowed-tools: [tool_a, tool_b]` (YAML array)
+ * - Proposed spec: `metadata.io.modelcontextprotocol/tools: "tool_a tool_b"` (space-separated)
+ *
+ * Prefers the proposed spec format when both are present.
+ */
+function parseAllowedTools(fm) {
+    // Proposed spec format: metadata.io.modelcontextprotocol/tools (space-separated string)
+    const metadata = fm.metadata;
+    if (metadata) {
+        const specTools = metadata["io.modelcontextprotocol/tools"];
+        if (typeof specTools === "string" && specTools.trim().length > 0) {
+            return specTools.trim().split(/\s+/);
+        }
+    }
+    // Current format: allowed-tools (YAML array)
+    const legacy = fm["allowed-tools"];
+    if (Array.isArray(legacy)) {
+        return legacy.filter((v) => typeof v === "string");
     }
     return [];
 }
-//# sourceMappingURL=discover.js.map

package/dist/skills/format.d.ts

@@ -5,6 +5,9 @@ import type { McpSkillMetadata } from "./skill-registry.js";
  * Produces XML matching Pi's native `formatSkillsForPrompt` structure,
  * but references the `load_skill` tool instead of `read` and uses
  * `mcp:<serverName>` as the location.
+ *
+ * This is the catalogue of what exists. Which kind of task suits a skill at all
+ * is decided by the `<execution_routing>` section, which reports skill
+ * availability whether or not any were discovered.
  */
 export declare function formatMcpSkillsForPrompt(skills: McpSkillMetadata[]): string;
-//# sourceMappingURL=format.d.ts.map

package/dist/skills/format.js

@@ -12,6 +12,10 @@ function escapeXml(str) {
  * Produces XML matching Pi's native `formatSkillsForPrompt` structure,
  * but references the `load_skill` tool instead of `read` and uses
  * `mcp:<serverName>` as the location.
+ *
+ * This is the catalogue of what exists. Which kind of task suits a skill at all
+ * is decided by the `<execution_routing>` section, which reports skill
+ * availability whether or not any were discovered.
  */
 export function formatMcpSkillsForPrompt(skills) {
     if (skills.length === 0)
@@ -19,9 +23,10 @@ export function formatMcpSkillsForPrompt(skills) {
     const lines = [
         "",
         "",
-        "The following MCP skills provide specialized instructions and tools for specific tasks.",
-        "MCP tools are deferred — they are available but not described in this prompt.",
-        "You MUST call load_skill to get usage instructions before using a skill's tools.",
+        "Use when a task matches one of the domain workflows these MCP skills document.",
+        "Call load_skill with the skill's name to read its instructions before working through it.",
+        "MCP tools are deferred — registered for dispatch but not described in this prompt. A skill's",
+        "declared tools are enabled only after you approve its grant; declining leaves them locked.",
         "",
         "<available_mcp_skills>",
     ];
@@ -35,4 +40,3 @@ export function formatMcpSkillsForPrompt(skills) {
     lines.push("</available_mcp_skills>");
     return lines.join("\n");
 }
-//# sourceMappingURL=format.js.map

package/dist/skills/index.d.ts

@@ -1,6 +1,6 @@
-export { SkillRegistry, type McpSkillMetadata } from "./skill-registry.js";
+export { SkillRegistry, type McpSkillMetadata, type SkillNameCollision } from "./skill-registry.js";
 export { formatMcpSkillsForPrompt } from "./format.js";
 export { createLoadSkillTool, type LoadSkillDeps, type LoadSkillDetails, } from "./load-skill-tool.js";
 export { discoverSkillsFromServer } from "./discover.js";
 export { registerMcpToolProxies } from "./mcp-tool-proxy.js";
-//# sourceMappingURL=index.d.ts.map
+export { SKILLS_EXTENSION_NAME, SKILLS_EXTENSION_REVISION, SKILLS_EXTENSION_STATUS, SkillsExtensionClient, describeNegotiation, discoverSkillsViaExtension, loadSkillDocument, readSkillResource, skillsExtensionDiagnostic, type Sep2640DiscoveryResult, type SkillEntry, type SkillsListing, } from "./sep2640/index.js";

package/dist/skills/index.js

@@ -3,4 +3,4 @@ export { formatMcpSkillsForPrompt } from "./format.js";
 export { createLoadSkillTool, } from "./load-skill-tool.js";
 export { discoverSkillsFromServer } from "./discover.js";
 export { registerMcpToolProxies } from "./mcp-tool-proxy.js";
-//# sourceMappingURL=index.js.map
+export { SKILLS_EXTENSION_NAME, SKILLS_EXTENSION_REVISION, SKILLS_EXTENSION_STATUS, SkillsExtensionClient, describeNegotiation, discoverSkillsViaExtension, loadSkillDocument, readSkillResource, skillsExtensionDiagnostic, } from "./sep2640/index.js";

package/dist/skills/load-skill-tool.d.ts

@@ -1,6 +1,7 @@
 import type { AgentToolResult, ExtensionContext } from "@sammorrowdrums/mcpi";
 import { Type, type Static } from "typebox";
-import type { McpClientManager } from "../mcp/index.js";
+import type { McpPolicy } from "../mcp/policy.js";
+import type { SkillsExtensionClient } from "./sep2640/client.js";
 import type { SkillRegistry } from "./skill-registry.js";
 declare const LoadSkillParams: Type.TObject<{
     name: Type.TString;
@@ -8,23 +9,39 @@ declare const LoadSkillParams: Type.TObject<{
 type LoadSkillInput = Static<typeof LoadSkillParams>;
 export interface LoadSkillDeps {
     registry: SkillRegistry;
-    mcpManager: McpClientManager;
-    enabledTools: Set<string>;
+    policy: McpPolicy;
+    /**
+     * Client for the draft skills extension.
+     *
+     * Required to load a skill discovered over SEP-2640: that contract only holds
+     * if the digests are re-fetched at load time, so a skill with no client to
+     * ask is refused rather than loaded unverified.
+     */
+    skillsClient?: SkillsExtensionClient;
 }
 export interface LoadSkillDetails {
     skillName: string;
     serverName?: string;
     activatedTools?: string[];
     error?: string;
+    /** True when the content was verified against SEP-2640 digests. */
+    verified?: boolean;
+    /** True when the server's resource set changed since discovery. */
+    resourceSetRotated?: boolean;
 }
 /**
  * Create the load_skill tool definition.
  *
  * When the model calls this tool, it:
  * 1. Looks up the skill in the registry
- * 2. Reads the full SKILL.md content from the MCP server
- * 3. Returns the SKILL.md body (the skill names its tools, and the model
+ * 2. Reads the full SKILL.md content through the shared policy boundary
+ * 3. Asks the user to approve the skill's `allowed-tools` grant
+ * 4. Returns the SKILL.md body (the skill names its tools, and the model
  *    already has their schemas from the deferred tools array)
+ *
+ * The grant is requested before the body is returned, so a server cannot use
+ * skill instructions to influence a pending authorization decision. A declined
+ * or unavailable approval leaves every gated tool locked.
  */
 export declare function createLoadSkillTool(deps: LoadSkillDeps): {
     name: string;
@@ -34,7 +51,6 @@ export declare function createLoadSkillTool(deps: LoadSkillDeps): {
     parameters: Type.TObject<{
         name: Type.TString;
     }>;
-    execute(_toolCallId: string, params: LoadSkillInput, _signal: AbortSignal | undefined, _onUpdate: undefined, _ctx: ExtensionContext): Promise<AgentToolResult<LoadSkillDetails>>;
+    execute(_toolCallId: string, params: LoadSkillInput, signal: AbortSignal | undefined, _onUpdate: undefined, _ctx: ExtensionContext): Promise<AgentToolResult<LoadSkillDetails>>;
 };
 export {};
-//# sourceMappingURL=load-skill-tool.d.ts.map

package/dist/skills/load-skill-tool.js

@@ -1,5 +1,7 @@
 import { stripFrontmatter } from "@sammorrowdrums/mcpi";
 import { Type } from "typebox";
+import { loadSkillDocument, SkillFetchBudget } from "./sep2640/load.js";
+import { resourceSetFingerprint } from "./sep2640/protocol.js";
 const LoadSkillParams = Type.Object({
     name: Type.String({ description: "Name of the MCP skill to load" }),
 });
@@ -8,19 +10,24 @@ const LoadSkillParams = Type.Object({
  *
  * When the model calls this tool, it:
  * 1. Looks up the skill in the registry
- * 2. Reads the full SKILL.md content from the MCP server
- * 3. Returns the SKILL.md body (the skill names its tools, and the model
+ * 2. Reads the full SKILL.md content through the shared policy boundary
+ * 3. Asks the user to approve the skill's `allowed-tools` grant
+ * 4. Returns the SKILL.md body (the skill names its tools, and the model
  *    already has their schemas from the deferred tools array)
+ *
+ * The grant is requested before the body is returned, so a server cannot use
+ * skill instructions to influence a pending authorization decision. A declined
+ * or unavailable approval leaves every gated tool locked.
  */
 export function createLoadSkillTool(deps) {
-    const { registry, mcpManager, enabledTools } = deps;
+    const { registry, policy, skillsClient } = deps;
     return {
         name: "load_skill",
         label: "Load Skill",
-        description: "Load an MCP skill by name. Activates the skill's instructions and tools.",
-        promptSnippet: "Load an MCP skill to get specialized instructions and activate its tools.",
+        description: "Use when a task matches an MCP skill's documented workflow and you need its instructions. Returns the skill body and requests approval to enable the tools it declares; the tools stay locked unless that grant is approved.",
+        promptSnippet: "Use when a task matches an MCP skill's workflow: returns its instructions and, once you approve the grant, enables the tools it declares.",
         parameters: LoadSkillParams,
-        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+        async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
             const skill = registry.get(params.name);
             if (!skill) {
                 const available = registry
@@ -37,34 +44,69 @@ export function createLoadSkillTool(deps) {
                     details: { skillName: params.name, error: "not_found" },
                 };
             }
-            const client = mcpManager.getClient(skill.serverName);
-            if (!client) {
+            const verifiable = skill.origin === "sep2640";
+            if (verifiable && !skillsClient) {
                 return {
                     content: [
                         {
                             type: "text",
-                            text: `MCP server "${skill.serverName}" is not connected. Cannot load skill "${params.name}".`,
+                            text: `Skill "${params.name}" was discovered over the draft skills extension, but no extension client is available to verify it. Refusing to load unverified content.`,
                         },
                     ],
-                    details: { skillName: params.name, serverName: skill.serverName, error: "disconnected" },
+                    details: {
+                        skillName: params.name,
+                        serverName: skill.serverName,
+                        error: "verification_unavailable",
+                        verified: false,
+                    },
                 };
             }
             let body;
+            let entry;
+            let rotated = false;
             try {
-                const result = await client.readResource({ uri: skill.uri });
-                const textContent = result.contents.find((c) => "text" in c);
-                if (!textContent) {
-                    return {
-                        content: [
-                            {
-                                type: "text",
-                                text: `Skill "${params.name}" returned no text content.`,
+                if (verifiable && skillsClient) {
+                    // Re-fetch the entry so verification uses the digests the server is
+                    // publishing now, not the ones it published at discovery.
+                    entry = await skillsClient.getSkill(skill.serverName, skill.uri, signal);
+                    const fingerprint = resourceSetFingerprint(entry);
+                    rotated =
+                        skill.contentFingerprint !== undefined && skill.contentFingerprint !== fingerprint;
+                    policy.registerSkillResources(skill.serverName, entry.uri, entry.resources === "dynamic" ? [] : entry.resources.map((ref) => ref.uri));
+                    const document = await loadSkillDocument({
+                        policy,
+                        entry,
+                        serverName: skill.serverName,
+                        budget: new SkillFetchBudget(),
+                        ...(signal ? { signal } : {}),
+                    });
+                    body = stripFrontmatter(document.text);
+                }
+                else {
+                    const result = await policy.readResource({
+                        source: "skill-load",
+                        serverName: skill.serverName,
+                        uri: skill.uri,
+                        ...(signal ? { signal } : {}),
+                    });
+                    const textContent = result.contents.find((c) => "text" in c);
+                    if (!textContent) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Skill "${params.name}" returned no text content.`,
+                                },
+                            ],
+                            details: {
+                                skillName: params.name,
+                                serverName: skill.serverName,
+                                error: "no_content",
                             },
-                        ],
-                        details: { skillName: params.name, serverName: skill.serverName, error: "no_content" },
-                    };
+                        };
+                    }
+                    body = stripFrontmatter(textContent.text);
                 }
-                body = stripFrontmatter(textContent.text);
             }
             catch (err) {
                 return {
@@ -78,27 +120,64 @@ export function createLoadSkillTool(deps) {
                         skillName: params.name,
                         serverName: skill.serverName,
                         error: err.message,
+                        verified: false,
                     },
                 };
             }
-            // Enable the skill's tools so the tool_call gate allows them
-            for (const t of skill.allowedTools) {
-                enabledTools.add(t);
+            // Approval is bound to the resource set the server just published. A
+            // rotated set produces a different grant key, so a previously approved
+            // skill is re-prompted instead of inheriting the old answer.
+            const grantSubject = entry ? withFreshContent(skill, entry) : skill;
+            const grant = await policy.activateSkillGrant(grantSubject, signal);
+            if (grant.status === "granted" || grant.status === "reused") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: body,
+                        },
+                    ],
+                    details: {
+                        skillName: params.name,
+                        serverName: skill.serverName,
+                        activatedTools: [...grant.activatedTools],
+                        verified: verifiable,
+                        resourceSetRotated: rotated,
+                    },
+                };
             }
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: body,
-                    },
-                ],
+                content: [{ type: "text", text: grant.message }],
                 details: {
                     skillName: params.name,
                     serverName: skill.serverName,
-                    activatedTools: skill.allowedTools,
+                    activatedTools: [],
+                    error: grant.status === "declined" ? "approval_declined" : "approval_unavailable",
+                    verified: verifiable,
+                    resourceSetRotated: rotated,
                 },
             };
         },
     };
 }
-//# sourceMappingURL=load-skill-tool.js.map
+/**
+ * Rebuild skill metadata from the entry the server just served.
+ *
+ * Both the gated tool names and the content fingerprint come from the verified
+ * entry rather than the discovery-time copy, so an `allowed-tools` list that
+ * grew since discovery cannot ride in on an approval the user gave for a
+ * smaller one.
+ */
+function withFreshContent(skill, entry) {
+    const declared = entry.frontmatter["allowed-tools"];
+    const allowedTools = Array.isArray(declared)
+        ? declared.filter((value) => typeof value === "string")
+        : typeof declared === "string" && declared.trim().length > 0
+            ? declared.trim().split(/\s+/)
+            : [];
+    return {
+        ...skill,
+        allowedTools,
+        contentFingerprint: resourceSetFingerprint(entry),
+    };
+}

package/dist/skills/mcp-tool-proxy.d.ts

@@ -1,11 +1,7 @@
 import type { ExtensionAPI } from "@sammorrowdrums/mcpi";
-import type { McpClientManager } from "../mcp/index.js";
+import type { McpClientManager } from "../mcp/client-manager.js";
+import type { McpPolicy } from "../mcp/policy.js";
 /**
- * Register MCP tools as Pi tool proxies.
- *
- * Each registered tool forwards calls to the MCP server via `client.callTool()`.
- * Uses `Type.Unsafe()` to pass the MCP tool's original JSON Schema through
- * to Pi, preserving property names and types for the model.
+ * Register MCP tools as deferred mcpi proxies backed by the shared policy boundary.
  */
-export declare function registerMcpToolProxies(toolNames: string[], mcpManager: McpClientManager, pi: ExtensionAPI): string[];
-//# sourceMappingURL=mcp-tool-proxy.d.ts.map
+export declare function registerMcpToolProxies(toolNames: string[], manager: McpClientManager, policy: McpPolicy, pi: ExtensionAPI): string[];

package/dist/skills/mcp-tool-proxy.js

@@ -1,116 +1,41 @@
-import { writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { Type } from "typebox";
-/** Threshold in chars above which tool output is written to a tmp file. */
-const LARGE_OUTPUT_THRESHOLD = 10_000;
+import { renderTerminalCallToolResult } from "../mcp/call-tool-result.js";
 /**
- * Register MCP tools as Pi tool proxies.
- *
- * Each registered tool forwards calls to the MCP server via `client.callTool()`.
- * Uses `Type.Unsafe()` to pass the MCP tool's original JSON Schema through
- * to Pi, preserving property names and types for the model.
+ * Register MCP tools as deferred mcpi proxies backed by the shared policy boundary.
  */
-export function registerMcpToolProxies(toolNames, mcpManager, pi) {
+export function registerMcpToolProxies(toolNames, manager, policy, pi) {
     const registered = [];
-    const allTools = mcpManager.getTools();
-    // Check which tools are already registered to avoid double-registration
-    const existingTools = new Set(pi.getAllTools().map((t) => t.name));
+    const existingTools = new Set(pi.getAllTools().map((tool) => tool.name));
+    const toolsByName = new Map(manager.getTools().map((tool) => [tool.name, tool]));
     for (const name of toolNames) {
         if (existingTools.has(name)) {
             registered.push(name);
             continue;
         }
-        const mcpTool = allTools.find((t) => t.name === name);
-        if (!mcpTool)
+        const tool = toolsByName.get(name);
+        if (!tool)
             continue;
-        pi.registerTool(createMcpToolProxy(mcpTool, mcpManager));
+        pi.registerTool(createMcpToolProxy(policy, tool));
         registered.push(name);
     }
     return registered;
 }
-function createMcpToolProxy(mcpTool, mcpManager) {
-    // Pass through the MCP tool's JSON Schema directly via Type.Unsafe()
-    // This preserves the original property names and types for the model
-    const inputSchema = mcpTool.inputSchema;
-    const parameters = Type.Unsafe({
-        type: "object",
-        properties: inputSchema.properties ?? {},
-        required: inputSchema.required ?? [],
-    });
+function createMcpToolProxy(policy, tool) {
     return {
-        name: mcpTool.name,
-        label: mcpTool.name,
-        description: mcpTool.description ?? `MCP tool from ${mcpTool.serverName}`,
+        name: tool.name,
+        label: tool.name,
+        description: tool.description ?? `MCP tool from ${tool.serverName}`,
         deferred: true,
-        parameters,
-        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
-            const client = mcpManager.getClient(mcpTool.serverName);
-            if (!client) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `MCP server "${mcpTool.serverName}" is not connected.`,
-                        },
-                    ],
-                    details: {
-                        serverName: mcpTool.serverName,
-                        toolName: mcpTool.name,
-                        error: "disconnected",
-                    },
-                };
-            }
-            try {
-                const result = await client.callTool({
-                    name: mcpTool.name,
-                    arguments: params,
-                });
-                // Prefer structuredContent when available
-                let text;
-                if (result.structuredContent) {
-                    text = JSON.stringify(result.structuredContent, null, 2);
-                }
-                else if (Array.isArray(result.content)) {
-                    text = result.content
-                        .map((c) => {
-                        if (typeof c === "object" && c !== null && "text" in c) {
-                            return String(c.text);
-                        }
-                        return JSON.stringify(c);
-                    })
-                        .join("\n");
-                }
-                else {
-                    text = JSON.stringify(result);
-                }
-                // Write large outputs to tmp file to avoid bloating context
-                if (text.length > LARGE_OUTPUT_THRESHOLD) {
-                    const tmpPath = join(tmpdir(), `mcp-${mcpTool.name}-${Date.now()}.json`);
-                    writeFileSync(tmpPath, text, "utf-8");
-                    text = `Output too large (${text.length} chars). Written to: ${tmpPath}`;
-                }
-                return {
-                    content: [{ type: "text", text }],
-                    details: { serverName: mcpTool.serverName, toolName: mcpTool.name },
-                };
-            }
-            catch (err) {
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `MCP tool "${mcpTool.name}" failed: ${err.message}`,
-                        },
-                    ],
-                    details: {
-                        serverName: mcpTool.serverName,
-                        toolName: mcpTool.name,
-                        error: err.message,
-                    },
-                };
-            }
+        parameters: Type.Unsafe(tool.inputSchema),
+        async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
+            const terminal = await policy.callTool({
+                source: "proxy",
+                serverName: tool.serverName,
+                toolName: tool.name,
+                args: params,
+                ...(signal ? { signal } : {}),
+            });
+            return renderTerminalCallToolResult(terminal);
         },
     };
 }
-//# sourceMappingURL=mcp-tool-proxy.js.map

package/dist/skills/sep2640/client.d.ts

@@ -0,0 +1,91 @@
+import type { McpPolicy } from "../../mcp/policy.js";
+import { type DirectoryResource, type SkillEntry } from "./protocol.js";
+/** What a listing pass observed, including why it may be incomplete. */
+export interface SkillsListing {
+    /** Entries that passed pre-fetch validation. */
+    readonly skills: SkillEntry[];
+    /**
+     * Entries the server returned that this host refused to consider, with the
+     * reason. Surfaced rather than silently dropped so a malformed skill is
+     * visible instead of just missing.
+     */
+    readonly rejected: {
+        readonly uri: string;
+        readonly reason: string;
+    }[];
+    /**
+     * True when the server had more pages than this host was willing to walk.
+     *
+     * SEP-2640 forbids treating a listing as proof of what a server has; this
+     * flag is how that uncertainty travels with the data instead of being
+     * flattened into "these are the skills".
+     */
+    readonly truncated: boolean;
+    /** Whether this listing came from the in-memory freshness cache. */
+    readonly fromCache: boolean;
+}
+export interface SkillsExtensionClientOptions {
+    readonly policy: McpPolicy;
+    /** Injectable clock; defaults to `Date.now`. */
+    readonly now?: () => number;
+}
+/**
+ * A client for the draft SEP-2640 skills extension.
+ *
+ * Every request goes through {@link McpPolicy}, which re-checks the negotiated
+ * capability immediately before dispatch. This class therefore never caches
+ * "server X supports skills" — it caches only listing *content*, and only when
+ * the server asked it to with terms this host is willing to honour.
+ */
+export declare class SkillsExtensionClient {
+    private readonly policy;
+    private readonly now;
+    private readonly listCache;
+    constructor(options: SkillsExtensionClientOptions);
+    /** True when the server declared the extension on the live connection. */
+    supports(serverName: string): boolean;
+    /** True when the server additionally declared `directoryRead: true`. */
+    supportsDirectoryRead(serverName: string): boolean;
+    /** The declared extension settings, for diagnostics. */
+    capability(serverName: string): Record<string, unknown> | undefined;
+    /**
+     * Walk `skills/list` to completion, validating each entry before it is
+     * admitted.
+     *
+     * Pagination stops at {@link MAX_SKILL_LIST_PAGES}; the result is then marked
+     * `truncated` rather than presented as the whole set. A server that returns
+     * the same cursor twice is also treated as truncated, which stops a cursor
+     * loop from becoming an unbounded request stream.
+     */
+    listSkills(serverName: string, signal?: AbortSignal): Promise<SkillsListing>;
+    /**
+     * Fetch one skill's authoritative entry with `skills/get`.
+     *
+     * Always goes to the server: `skills/get` is what re-establishes current
+     * digests after a verification failure, so serving it from cache would defeat
+     * the recovery path the spec defines.
+     */
+    getSkill(serverName: string, uri: string, signal?: AbortSignal): Promise<SkillEntry>;
+    /**
+     * Enumerate a skill directory, when the server declared `directoryRead`.
+     *
+     * Directory listings are navigational only. Nothing they return becomes
+     * readable: a file is readable because the skill entry lists it with a
+     * digest, and a directory cannot add entries to that list.
+     */
+    readDirectory(serverName: string, uri: string, signal?: AbortSignal): Promise<DirectoryResource[]>;
+    /** Drop cached listings; call on disconnect or reset. */
+    clearCache(serverName?: string): void;
+    private readCache;
+    /**
+     * Cache a listing only when the server asked for it in terms this host
+     * understands.
+     *
+     * `cacheScope`'s value set is defined by SEP-2549, not SEP-2640, so an
+     * unrecognised scope is treated as "do not cache" rather than guessed at. A
+     * truncated listing is never cached, because caching an incomplete answer is
+     * exactly the "empty listing means no skills" mistake the spec warns against,
+     * just with a longer lifetime.
+     */
+    private writeCache;
+}