agent-trellis 0.11.0 → 0.13.0

package/dist/lib/mcpStatusProvider.js

@@ -1,14 +1,17 @@
+import { describeStoredToken, remediationFor } from "./oauth/renew.js";
 const STATUS_TOOL = {
     name: "trellis.mcp.status",
-    description: "Show MCP upstream availability and the safe next action for authentication or configuration failures.",
+    description: "Show MCP upstream availability, credential health for OAuth-classified direct-routed servers, and the safe next action for authentication or configuration failures.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
     annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
 };
 export class McpStatusProvider {
     backend;
+    options;
     id = "mcp";
-    constructor(backend) {
+    constructor(backend, options = {}) {
         this.backend = backend;
+        this.options = options;
     }
     listTools() {
         return [STATUS_TOOL];
@@ -17,9 +20,29 @@ export class McpStatusProvider {
         if (name !== STATUS_TOOL.name)
             return { content: [{ type: "text", text: `unknown MCP status tool "${name}"` }], isError: true };
         const statuses = this.backend.listStatus?.() ?? [];
+        // Strictly read-only (design.md D3): classification reads the token
+        // files and nothing else — no token endpoint, no refresh, no writes.
+        // The readOnlyHint annotation on the tool depends on that staying true.
+        const oauth = this.options.homeDir
+            ? (this.options.oauthServers ?? []).map(({ name: serverName, owner }) => {
+                if (owner === "agent") {
+                    return { name: serverName, owner, credential: "agent-managed" };
+                }
+                const { status, expiresAt } = describeStoredToken(this.options.homeDir, serverName);
+                const remediation = remediationFor(status, serverName);
+                return {
+                    name: serverName,
+                    owner,
+                    credential: status,
+                    ...(expiresAt !== undefined ? { expiresAt } : {}),
+                    ...(remediation !== "" ? { remediation } : {}),
+                };
+            })
+            : [];
+        const report = { servers: statuses, oauth };
         return {
-            content: [{ type: "text", text: JSON.stringify({ servers: statuses }, null, 2) }],
-            structuredContent: { servers: statuses },
+            content: [{ type: "text", text: JSON.stringify(report, null, 2) }],
+            structuredContent: report,
         };
     }
 }

package/dist/lib/memoryProvider.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 { Scope } from "../core/types.js";
 import type { RuntimeContext, TrellisProvider } from "./mcpRuntime.js";
 /**

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

@@ -0,0 +1,11 @@
+export interface CallbackPageOptions {
+    serverName: string;
+    hasCode: boolean;
+    error?: string;
+    acceptLanguage?: string;
+}
+/** Browser receipt only: the caller still validates and persists the grant. */
+export declare function renderCallbackPage(options: CallbackPageOptions): {
+    html: string;
+    contentSecurityPolicy: string;
+};

package/dist/lib/oauth/callbackPage.js

@@ -0,0 +1,89 @@
+import { randomBytes } from "node:crypto";
+const COPY = {
+    en: {
+        received: "Authorization response received",
+        receivedBody: "Return to Trellis or your terminal to check the final connection result.",
+        cancelled: "Authorization cancelled",
+        cancelledBody: "Return to Trellis and start again when you are ready.",
+        failed: "Authorization could not continue",
+        failedBody: "Return to Trellis or your terminal for details, then try again.",
+        incomplete: "Authorization response incomplete",
+        incompleteBody: "No authorization code was received. Start again from Trellis.",
+        close: "Close this tab",
+        manual: "If this tab stays open, close it manually and return to Trellis or your terminal.",
+        noScript: "You can close this tab manually and return to Trellis or your terminal.",
+    },
+    zh: {
+        received: "授权响应已接收",
+        receivedBody: "请返回 Trellis 或终端查看最终连接结果。",
+        cancelled: "授权已取消",
+        cancelledBody: "准备好后，请返回 Trellis 重新发起授权。",
+        failed: "授权暂未完成",
+        failedBody: "请返回 Trellis 或终端查看原因，然后重试。",
+        incomplete: "授权响应不完整",
+        incompleteBody: "未收到授权码，请从 Trellis 重新发起授权。",
+        close: "关闭此标签页",
+        manual: "如果页面没有关闭，请手动关闭此标签页，返回 Trellis 或终端。",
+        noScript: "你可以手动关闭此标签页，返回 Trellis 或终端。",
+    },
+};
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (character) => `&#${character.charCodeAt(0)};`);
+}
+// Inline the existing docs/assets/brand-v3/trellis-mark-v3-a.svg geometry so
+// callback pages work offline and inside the packaged Sidecar.
+const MARK = `<svg viewBox="0 0 96 96" aria-hidden="true" focusable="false"><g fill="none" stroke="currentColor" stroke-linecap="round"><rect x="16" y="18" width="64" height="18" rx="9" stroke-width="5.5"/><g stroke-width="2.6" clip-path="url(#a-beam)"><path d="M-64.5 32 L-55.5 23"/><path d="M-64.5 23 L-55.5 32"/><path d="M-46.5 32 L-37.5 23"/><path d="M-46.5 23 L-37.5 32"/><path d="M-28.5 32 L-19.5 23"/><path d="M-28.5 23 L-19.5 32"/><path d="M-10.5 32 L-1.5 23"/><path d="M-10.5 23 L-1.5 32"/><path d="M7.5 32 L16.5 23"/><path d="M7.5 23 L16.5 32"/><path d="M25.5 32 L34.5 23"/><path d="M25.5 23 L34.5 32"/><path d="M43.5 32 L52.5 23"/><path d="M43.5 23 L52.5 32"/><path d="M61.5 32 L70.5 23"/><path d="M61.5 23 L70.5 32"/><path d="M79.5 32 L88.5 23"/><path d="M79.5 23 L88.5 32"/><path d="M97.5 32 L106.5 23"/><path d="M97.5 23 L106.5 32"/><path d="M115.5 32 L124.5 23"/><path d="M115.5 23 L124.5 32"/></g><path d="M48 36 V78" stroke-width="8"/></g><defs><clipPath id="a-beam"><rect x="21" y="23" width="54" height="9" rx="4.5"/></clipPath></defs></svg>`;
+/** Browser receipt only: the caller still validates and persists the grant. */
+export function renderCallbackPage(options) {
+    const chinese = options.acceptLanguage?.split(",")[0]?.trim().toLowerCase().startsWith("zh") ?? false;
+    const copy = chinese ? COPY.zh : COPY.en;
+    const state = options.error === "access_denied" ? "cancelled" : options.error ? "failed" : options.hasCode ? "received" : "incomplete";
+    const title = copy[state];
+    const description = copy[`${state}Body`];
+    const nonce = randomBytes(16).toString("base64");
+    const contentSecurityPolicy = `default-src 'none'; style-src 'nonce-${nonce}'; script-src 'nonce-${nonce}'; img-src data:; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`;
+    const html = `<!doctype html>
+<html lang="${chinese ? "zh-CN" : "en"}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="light">
+<title>${escapeHtml(title)} · Trellis</title>
+<style nonce="${nonce}">
+:root{color-scheme:light;font-family:-apple-system,BlinkMacSystemFont,"Segoe UI","Noto Sans",Arial,sans-serif;color:#182230;background:#fff;font-synthesis:none;-webkit-font-smoothing:antialiased}
+*{box-sizing:border-box}body{margin:0;min-height:100vh;min-height:100dvh;display:grid;place-items:center;padding:32px 24px}
+main{width:100%;max-width:440px;text-align:center}.brand{display:flex;align-items:center;justify-content:center;flex-wrap:wrap;gap:8px;margin-bottom:24px;font-size:14px;color:#667085}.brand svg{width:28px;height:28px;flex:none}.brand-name{font-weight:600;color:#344054}.separator{color:#98a2b3}.server{max-width:100%;overflow-wrap:anywhere}
+h1{font-size:25px;font-weight:600;line-height:1.35;letter-spacing:-.5px;margin:0 0 12px;overflow-wrap:anywhere}.description{font-size:14px;line-height:1.7;color:#667085;margin:0 0 24px}
+button{appearance:none;border:1px solid #2563eb;border-radius:8px;background:#2563eb;color:#fff;font:inherit;font-size:14px;font-weight:500;line-height:1.5;padding:10px 18px;min-height:44px;max-width:100%;cursor:pointer}button:hover{background:#1d4ed8;border-color:#1d4ed8}button:focus-visible{outline:3px solid #93b4ff;outline-offset:3px}.help{font-size:12px;line-height:1.65;color:#667085;margin:16px 0 0;overflow-wrap:anywhere}.help:focus{outline:none}
+[hidden]{display:none!important}@media(max-width:480px){body{padding:24px}h1{font-size:23px}}
+</style>
+</head>
+<body>
+<main>
+  <div class="brand">${MARK}<span class="brand-name">Trellis</span><span class="separator" aria-hidden="true">·</span><span class="server">${escapeHtml(options.serverName)}</span></div>
+  <section aria-labelledby="page-title" data-state="${state}">
+    <h1 id="page-title">${title}</h1>
+    <p class="description">${description}</p>
+    <button id="close-tab" type="button" hidden>${copy.close}</button>
+    <p id="close-help" class="help" role="status" tabindex="-1" hidden>${copy.manual}</p>
+    <p id="manual-close" class="help">${copy.noScript}</p>
+  </section>
+</main>
+<script nonce="${nonce}">
+try { history.replaceState(null, '', location.pathname); } catch (_) {}
+const button = document.getElementById('close-tab');
+button.hidden = false;
+document.getElementById('manual-close').hidden = true;
+button.addEventListener('click', function () {
+  try { window.close(); } catch (_) {}
+  setTimeout(function () {
+    const help = document.getElementById('close-help');
+    help.hidden = false;
+    help.focus({ preventScroll: true });
+  }, 150);
+});
+</script>
+</body>
+</html>`;
+    return { html, contentSecurityPolicy };
+}

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

@@ -27,6 +27,7 @@ export interface AuthorizationServerMetadata {
     registrationEndpoint?: string;
     scopesSupported?: string[];
     codeChallengeMethodsSupported?: string[];
+    issuerParameterSupported?: boolean;
 }
 export type FetchLike = (url: string, init?: {
     method?: string;

package/dist/lib/oauth/discovery.js

@@ -37,6 +37,8 @@ function toMetadata(raw) {
         out.scopesSupported = raw.scopes_supported;
     if (raw.code_challenge_methods_supported)
         out.codeChallengeMethodsSupported = raw.code_challenge_methods_supported;
+    if (raw.authorization_response_iss_parameter_supported)
+        out.issuerParameterSupported = true;
     return out;
 }
 async function tryJson(fetchImpl, url) {

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,7 +15,9 @@
  */
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
 import { createPkcePair } from "./pkce.js";
+import { renderCallbackPage } from "./callbackPage.js";
 export class AuthorizationError extends Error {
 }
 /**
@@ -81,7 +83,7 @@ const STATIC_CLIENT_REMEDIATION = "register a client with the provider and set a
 /** A one-shot loopback listener for the redirect. Bound to 127.0.0.1
  * explicitly, never 0.0.0.0: the authorization code arrives in this URL,
  * and a listener on all interfaces would accept it from the network. */
-function listenForCallback(port) {
+function listenForCallback(port, serverName) {
     return new Promise((resolve, reject) => {
         let settle;
         const received = new Promise((r) => {
@@ -89,6 +91,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,16 +104,24 @@ 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");
                 if (description)
                     result.errorDescription = description;
             }
-            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>");
+            const page = renderCallbackPage({ serverName, hasCode: Boolean(result.code), error: result.error, acceptLanguage: req.headers["accept-language"] });
+            res.writeHead(200, {
+                "content-type": "text/html; charset=utf-8",
+                "cache-control": "no-store",
+                "referrer-policy": "no-referrer",
+                "x-content-type-options": "nosniff",
+                "content-security-policy": page.contentSecurityPolicy,
+            });
+            res.end(page.html);
             settle(result);
         });
         server.on("error", reject);
@@ -115,31 +130,30 @@ function listenForCallback(port) {
         });
     });
 }
-function escapeHtml(value) {
-    return value.replace(/[&<>"']/g, (char) => `&#${char.charCodeAt(0)};`);
-}
 /**
  * Runs the full authorization-code-plus-PKCE exchange and returns a
  * token ready to persist. Does not write anything — storage is the
  * 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);
+    const { server, port, received } = await listenForCallback(opts.callbackPort ?? 0, serverName);
     const redirectUri = `http://127.0.0.1:${port}/callback`;
     try {
         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 +178,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 +195,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 +209,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 +227,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 +241,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/renew.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Per-server OAuth credential health classification, shared by
+ * `trellis mcp renew`, `trellis doctor`, and the `trellis.mcp.status`
+ * Runtime tool (trellis-mcp-oauth-renew design.md D2,
+ * trellis-mcp-status-credential-health design.md D2).
+ *
+ * One function, two consumers, on purpose: a gateway call, a renew run,
+ * and a doctor report all read the same token files, so the statuses they
+ * derive must come from a single computation — two classifiers could
+ * drift into disagreeing about whether a credential is healthy, which is
+ * exactly the kind of "reported ready but 401s in session" mismatch this
+ * change exists to eliminate.
+ *
+ * Everything here is derived from the stored token at call time. Nothing
+ * is persisted: the next caller recomputes from the same source of truth
+ * the gateway reads.
+ */
+import { type StoredToken } from "./store.js";
+export type OAuthRenewStatus = 
+/** Nothing stored; renewal can do nothing. */
+"no-token"
+/** Stored and not expired (within the same skew `ensureFreshToken` uses). */
+ | "valid"
+/** Was expired, refresh succeeded. Only the refresh path produces this. */
+ | "refreshed"
+/** Expired but a refresh token is present — a real renew run would
+ * attempt a refresh. Only the read-only path produces this. */
+ | "expired-renewable"
+/** Refresh was attempted and failed (network error, or the grant was
+ * rejected — a possibly revoked credential). */
+ | "refresh-failed"
+/** Expired with no refresh token: only a fresh authorization helps. */
+ | "needs-auth"
+/** A file exists on disk but cannot be interpreted. */
+ | "unreadable";
+/** Statuses that mean "a human step is required" — the non-zero-exit set
+ * (design.md D6). */
+export declare const FAILURE_STATUSES: ReadonlySet<OAuthRenewStatus>;
+export declare function remediationFor(status: OAuthRenewStatus, serverName: string): string;
+/** Test seam for expiry checks, mirroring the `now` seams the rest of the
+ * oauth package already exposes. */
+export interface ClassifyOptions {
+    now?: number;
+}
+/**
+ * The stored token's health plus its expiry (ISO 8601, when the token
+ * carries one — store.ts's contract makes `expiresAt` optional). The
+ * status tool needs the timestamp to answer "how long is this credential
+ * good for"; renew and doctor need only the status
+ * (trellis-mcp-status-credential-health design.md D2).
+ */
+export interface OAuthTokenDescription {
+    status: OAuthRenewStatus;
+    expiresAt?: string;
+}
+/**
+ * Read-only classification: no network, no writes — doctor's and the
+ * status tool's path (design.md D4). A token with no `expiresAt` never
+ * expires (store.ts's own contract), so it classifies `valid`.
+ */
+export declare function describeStoredToken(homeDir: string, serverName: string, opts?: ClassifyOptions): OAuthTokenDescription;
+export declare function classifyStoredToken(homeDir: string, serverName: string, opts?: ClassifyOptions): OAuthRenewStatus;
+/** Exported for tests that build statuses straight from token fixtures. */
+export declare function hasRefreshToken(token: StoredToken | undefined): boolean;
+/**
+ * Maps a refresh failure to a status. The RFC 6749 §5.2 errors that mean
+ * "this grant is dead" — `invalid_grant`, and Figma-style servers that
+ * answer a rejected refresh with a bare 400/401 and no parseable body —
+ * get `needs-auth`, because re-authorization is the only remaining step
+ * and the user should not be told to "try refreshing again". Everything
+ * else (timeouts, 5xx, DNS) is `refresh-failed`: transient, worth another
+ * scheduled attempt before bothering a human. Rejected-grant phrasing
+ * varies by provider, so message sniffing stays deliberately narrow.
+ */
+export declare function classifyRefreshFailure(err: unknown): OAuthRenewStatus;

package/dist/lib/oauth/renew.js

@@ -0,0 +1,86 @@
+/**
+ * Per-server OAuth credential health classification, shared by
+ * `trellis mcp renew`, `trellis doctor`, and the `trellis.mcp.status`
+ * Runtime tool (trellis-mcp-oauth-renew design.md D2,
+ * trellis-mcp-status-credential-health design.md D2).
+ *
+ * One function, two consumers, on purpose: a gateway call, a renew run,
+ * and a doctor report all read the same token files, so the statuses they
+ * derive must come from a single computation — two classifiers could
+ * drift into disagreeing about whether a credential is healthy, which is
+ * exactly the kind of "reported ready but 401s in session" mismatch this
+ * change exists to eliminate.
+ *
+ * Everything here is derived from the stored token at call time. Nothing
+ * is persisted: the next caller recomputes from the same source of truth
+ * the gateway reads.
+ */
+import { existsSync } from "node:fs";
+import { isExpired, readToken, tokenPath } from "./store.js";
+/** Statuses that mean "a human step is required" — the non-zero-exit set
+ * (design.md D6). */
+export const FAILURE_STATUSES = new Set([
+    "no-token",
+    "refresh-failed",
+    "needs-auth",
+    "unreadable",
+]);
+export function remediationFor(status, serverName) {
+    switch (status) {
+        case "no-token":
+        case "needs-auth":
+        case "unreadable":
+            return `run \`trellis mcp auth ${serverName}\``;
+        case "expired-renewable":
+            return `run \`trellis mcp renew\` to attempt a silent refresh now, or \`trellis mcp auth ${serverName}\` if that fails`;
+        case "refresh-failed":
+            return `run \`trellis mcp auth ${serverName}\` — the stored grant was rejected or unreachable (possibly revoked)`;
+        default:
+            return "";
+    }
+}
+/**
+ * Read-only classification: no network, no writes — doctor's and the
+ * status tool's path (design.md D4). A token with no `expiresAt` never
+ * expires (store.ts's own contract), so it classifies `valid`.
+ */
+export function describeStoredToken(homeDir, serverName, opts = {}) {
+    if (!existsSync(tokenPath(homeDir, serverName)))
+        return { status: "no-token" };
+    const token = readToken(homeDir, serverName);
+    if (!token)
+        return { status: "unreadable" };
+    const description = {
+        status: "valid",
+        ...(token.expiresAt !== undefined ? { expiresAt: new Date(token.expiresAt).toISOString() } : {}),
+    };
+    if (!isExpired(token, undefined, opts.now))
+        return description;
+    description.status = token.refreshToken ? "expired-renewable" : "needs-auth";
+    return description;
+}
+export function classifyStoredToken(homeDir, serverName, opts = {}) {
+    return describeStoredToken(homeDir, serverName, opts).status;
+}
+/** Exported for tests that build statuses straight from token fixtures. */
+export function hasRefreshToken(token) {
+    return token?.refreshToken !== undefined;
+}
+/**
+ * Maps a refresh failure to a status. The RFC 6749 §5.2 errors that mean
+ * "this grant is dead" — `invalid_grant`, and Figma-style servers that
+ * answer a rejected refresh with a bare 400/401 and no parseable body —
+ * get `needs-auth`, because re-authorization is the only remaining step
+ * and the user should not be told to "try refreshing again". Everything
+ * else (timeouts, 5xx, DNS) is `refresh-failed`: transient, worth another
+ * scheduled attempt before bothering a human. Rejected-grant phrasing
+ * varies by provider, so message sniffing stays deliberately narrow.
+ */
+export function classifyRefreshFailure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (/there is no refresh token/.test(message))
+        return "needs-auth";
+    if (/invalid_grant|HTTP 400|HTTP 401/.test(message))
+        return "needs-auth";
+    return "refresh-failed";
+}

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/skillManifest.d.ts

@@ -22,6 +22,7 @@ export interface SkillEntry {
     uri: string;
     frontmatter: Record<string, unknown>;
     resources: SkillManifestFile[];
+    _meta?: Record<string, unknown>;
 }
 export type SkillBuild = {
     ok: true;

package/dist/lib/skillManifest.js

@@ -94,7 +94,7 @@ export function mimeTypeFor(path) {
  * 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);
+        const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
         return { uri, mimeType: mimeTypeFor(path), text };
     }
     catch {

package/dist/lib/skillProvider.d.ts

@@ -1,4 +1,4 @@
-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 {

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";