agent-trellis 0.11.0 → 0.12.0

package/dist/adapters/mcpPlan.d.ts

@@ -34,6 +34,7 @@ export declare const RUNTIME_COMMAND = "trellis";
  * routing it exists to carry (trellis-mcp-oauth-static-client design.md
  * D1). */
 export declare function isOAuthMcpServer(def: McpServerDef): boolean;
+export declare function isAgentOwnedOAuth(def: McpServerDef): boolean;
 /**
  * Gateway mode applies to every managed agent when `agents` is omitted —
  * the expected normal case (design.md D14). An explicit list narrows it,

package/dist/adapters/mcpPlan.js

@@ -18,7 +18,7 @@
  */
 import { isInScope } from "../core/adapter.js";
 import { capabilityDeliveryForAgent } from "../core/types.js";
-import { isOAuthAuth } from "../core/types.js";
+import { isOAuthAuth, oauthOwner } from "../core/types.js";
 import { codexBearerTokenEnvVar } from "../lib/tomlSection.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 export const HUB_ENTRY_NAME = "trellis-hub";
@@ -40,6 +40,9 @@ export const RUNTIME_COMMAND = "trellis";
 export function isOAuthMcpServer(def) {
     return isOAuthAuth(def.auth);
 }
+export function isAgentOwnedOAuth(def) {
+    return isOAuthMcpServer(def) && oauthOwner(def.auth) === "agent";
+}
 /**
  * Gateway mode applies to every managed agent when `agents` is omitted —
  * the expected normal case (design.md D14). An explicit list narrows it,
@@ -158,7 +161,7 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
                 conflicts: [{ name: entryName, message: collisionMessage(entryName, agentId), remediation: collisionRemediation(entryName) }],
             };
         }
-        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isOAuthMcpServer);
+        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isAgentOwnedOAuth);
         // Every ordinary per-server check (enabled, scope, literal secrets,
         // unresolved env names, Codex's header shape) still runs at gateway
         // startup. OAuth servers are the deliberate exception: they are written
@@ -234,15 +237,21 @@ export function resolveMcpPlan(agentId, mcp, managedAgents, policy) {
         // Runtime mode owns the agent-facing MCP edge. It resolves the same
         // direct/gateway-compatible upstream route at startup, so native
         // per-server entries are not duplicated here.
+        const oauth = planDirectServers(agentId, mcp, managedAgents, policy, route, isAgentOwnedOAuth);
         return {
             desired: [{
                     name: RUNTIME_ENTRY_NAME,
                     def: { transport: "stdio", command: RUNTIME_COMMAND, args: ["mcp-runtime", "--agent", agentId] },
-                }],
-            conflicts: [],
+                }, ...oauth.desired],
+            conflicts: oauth.conflicts,
         };
     }
-    return planDirectServers(agentId, mcp, managedAgents, policy, route);
+    const native = planDirectServers(agentId, mcp, managedAgents, policy, route);
+    const hosted = native.desired.filter(({ def }) => isOAuthMcpServer(def) && oauthOwner(def.auth) === "trellis");
+    return {
+        desired: native.desired.filter(({ def }) => !isOAuthMcpServer(def) || oauthOwner(def.auth) === "agent"),
+        conflicts: [...native.conflicts, ...hosted.map(({ name }) => ({ name, message: `Trellis-owned OAuth server "${name}" requires gateway or runtime delivery for ${agentId}`, remediation: "enable gateway/runtime delivery or set auth.owner to agent" }))],
+    };
 }
 function planDirectServers(agentId, mcp, managedAgents, policy, route, filter) {
     const desired = [];

package/dist/cli.js

@@ -133,7 +133,7 @@ Commands:
             --json       machine-readable output, no report text
   mcp set <name> --auth oauth|none
             Set or clear explicit OAuth classification; canonical only.
-            --auth oauth [--client-id <id>] [--client-secret-env <NAME>]
+            --auth oauth [--auth-owner agent|trellis] [--client-id <id>] [--client-secret-env <NAME>]
                          pre-register a client for a provider that refuses
                          dynamic registration. --client-id is the PROVIDER's
                          published identifier (public by design);

package/dist/commands/mcp.d.ts

@@ -56,6 +56,12 @@ export interface McpListEntry {
     /** Normalized: `oauth` in either the scalar or the object form reports as
      * the scalar here — the listing reports classification, not metadata. */
     auth?: McpAuthMode;
+    authOwner?: "agent" | "trellis";
+    agentAuthorization?: Array<{
+        agent: AgentId;
+        status: "unknown";
+        instruction: string;
+    }>;
     /** Presence of pre-registered client metadata
      * (trellis-mcp-oauth-static-client task 3.2) — `true` when the object form
      * carries a `client_id`. A presence flag, deliberately not the id itself:
@@ -84,7 +90,7 @@ export interface McpListEntry {
      * printed in full. */
     staticEnv?: Record<string, string>;
 }
-export type McpAuthStatus = "not-authorized" | "authorized" | "refreshable" | "expired";
+export type McpAuthStatus = "not-authorized" | "authorized" | "refreshable" | "expired" | "unknown";
 /**
  * Reads only the per-server token store and returns the state, never a
  * token. Classification stays explicit — the caller only asks for servers
@@ -92,7 +98,7 @@ export type McpAuthStatus = "not-authorized" | "authorized" | "refreshable" | "e
  * name that cannot be a token filename, or an unreadable file, simply has no
  * credential: one odd entry must not take down the whole listing.
  */
-export declare function mcpCredentialState(homeDir: string, serverName: string): {
+export declare function mcpCredentialState(homeDir: string, serverName: string, resourceUrl?: string): {
     authStatus: McpAuthStatus;
     authExpiresAt?: number;
 };
@@ -156,6 +162,7 @@ export interface McpSetAuthPlan {
  * plan collector. */
 export interface McpSetAuthRawArgs {
     auth?: string;
+    authOwner?: string;
     /** Public literal by design (design.md D2) — the one field it is fine to
      * pass on a command line. Never echoed back in output or errors. */
     clientId?: string;
@@ -188,6 +195,10 @@ export declare function runMcpSetAuth(name: string | undefined, raw: McpSetAuthR
 }): {
     exitCode: number;
 };
+export declare function applyMcpSetAuthWithSync(plan: McpSetAuthPlan, homeDir: string): Promise<{
+    plan: McpSetAuthPlan;
+    sync?: McpSyncReport;
+}>;
 export type McpScopeAction = "updated" | "already-set" | "not-found" | "invalid-input";
 export interface McpScopePlan {
     name: string;

package/dist/commands/mcp.js

@@ -16,7 +16,7 @@ import { homedir } from "node:os";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { loadCanonicalSource, upsertServerYaml, removeServerYaml } from "../core/canonical.js";
-import { ALL_AGENTS, isOAuthAuth, oauthClientMetadata, resolveScope } from "../core/types.js";
+import { ALL_AGENTS, isOAuthAuth, oauthClientMetadata, oauthOwner, resolveScope } from "../core/types.js";
 import { isValidSecretVarName } from "../lib/secretEnv.js";
 import { isExpired, readToken } from "../lib/oauth/store.js";
 import { describeScope, resolveScopeSelection, sameScope } from "../lib/scopeSelection.js";
@@ -123,7 +123,7 @@ function serversYamlPath(homeDir) {
  * name that cannot be a token filename, or an unreadable file, simply has no
  * credential: one odd entry must not take down the whole listing.
  */
-export function mcpCredentialState(homeDir, serverName) {
+export function mcpCredentialState(homeDir, serverName, resourceUrl) {
     let token;
     try {
         token = readToken(homeDir, serverName);
@@ -133,6 +133,12 @@ export function mcpCredentialState(homeDir, serverName) {
     }
     if (!token?.accessToken)
         return { authStatus: "not-authorized" };
+    if (resourceUrl && token.resourceUrl) {
+        const resource = new URL(resourceUrl);
+        resource.hash = "";
+        if (token.resourceUrl !== resource.toString())
+            return { authStatus: "not-authorized" };
+    }
     const expiry = token.expiresAt !== undefined ? { authExpiresAt: token.expiresAt } : {};
     if (!isExpired(token))
         return { authStatus: "authorized", ...expiry };
@@ -145,7 +151,16 @@ export function collectMcpListPlan(homeDir = homedir()) {
         transport: def.transport,
         auth: isOAuthAuth(def.auth) ? "oauth" : undefined,
         preRegisteredClient: oauthClientMetadata(def.auth).clientId !== undefined ? true : undefined,
-        ...(isOAuthAuth(def.auth) ? mcpCredentialState(homeDir, name) : {}),
+        ...(isOAuthAuth(def.auth) ? {
+            authOwner: oauthOwner(def.auth),
+            ...(oauthOwner(def.auth) === "trellis" ? mcpCredentialState(homeDir, name, def.url) : {
+                authStatus: "unknown",
+                agentAuthorization: resolveScope(def.agents, canonical.managedAgents).map((agent) => ({
+                    agent, status: "unknown",
+                    instruction: agent === "codex" ? `codex mcp login ${name}` : agent === "claude-code" ? "Open Claude Code and use /mcp to authorize this server" : "Authorize this server in the Agent's MCP settings",
+                })),
+            }),
+        } : {}),
         enabled: def.enabled ?? true,
         agents: resolveScope(def.agents, canonical.managedAgents),
         command: def.command,
@@ -211,6 +226,7 @@ export function parseMcpSetArgs(argv) {
         auth: flag("--auth"),
         clientId: flag("--client-id"),
         clientSecretEnv: flag("--client-secret-env"),
+        authOwner: flag("--auth-owner"),
     };
 }
 function parseCsv(raw) {
@@ -314,8 +330,10 @@ export function collectMcpSetAuthPlan(name, raw, homeDir = homedir()) {
     const mode = raw.auth === "oauth" || raw.auth === "none" ? raw.auth : undefined;
     if (!name)
         return { name: "(none)", auth: (mode ?? "none"), action: "invalid-input", detail: "usage: trellis mcp set <name> --auth oauth|none [--client-id <id>] [--client-secret-env <NAME>]" };
-    const hasClientFlags = raw.clientId !== undefined || raw.clientSecretEnv !== undefined;
-    const clientFlagsDetail = "--client-id / --client-secret-env require an explicit --auth oauth in the same command";
+    const hasClientFlags = raw.clientId !== undefined || raw.clientSecretEnv !== undefined || raw.authOwner !== undefined;
+    const clientFlagsDetail = raw.authOwner !== undefined
+        ? "--auth-owner requires an explicit --auth oauth in the same command"
+        : "--client-id / --client-secret-env require an explicit --auth oauth in the same command";
     if (mode === undefined) {
         // Naming the missing --auth is the actionable error when that is what
         // the user was reaching for; otherwise report the invalid value itself.
@@ -329,6 +347,9 @@ export function collectMcpSetAuthPlan(name, raw, homeDir = homedir()) {
     if (raw.clientId === "") {
         return { name, auth: mode, action: "invalid-input", detail: "--client-id must not be empty" };
     }
+    if (raw.authOwner !== undefined && raw.authOwner !== "agent" && raw.authOwner !== "trellis") {
+        return { name, auth: mode, action: "invalid-input", detail: "--auth-owner must be agent or trellis" };
+    }
     if (raw.clientSecretEnv !== undefined && !isValidSecretVarName(raw.clientSecretEnv)) {
         // The value is deliberately not echoed: a name-shaped field failing
         // this check is at best a typo and at worst a pasted credential
@@ -387,6 +408,7 @@ export function collectMcpSetAuthPlan(name, raw, homeDir = homedir()) {
             ...current,
             auth: {
                 kind: "oauth",
+                ...(raw.authOwner !== undefined ? { owner: raw.authOwner } : typeof current.auth === "object" && current.auth.owner !== undefined ? { owner: current.auth.owner } : {}),
                 ...(clientId !== undefined ? { clientId } : {}),
                 ...(clientSecretEnv !== undefined ? { clientSecretEnv } : {}),
             },
@@ -424,6 +446,21 @@ export function runMcpSetAuth(name, raw, opts = {}) {
     }
     return { exitCode: ["invalid-input", "not-found"].includes(plan.action) || Boolean(writeError) ? 1 : 0 };
 }
+export async function applyMcpSetAuthWithSync(plan, homeDir) {
+    if (plan.action !== "updated" || !plan.def)
+        return { plan };
+    const backup = openBackupSession(homeDir, "mcp-auth-owner");
+    try {
+        const path = serversYamlPath(homeDir);
+        const result = upsertServerYaml(path, plan.name, plan.def, backup);
+        if (!result.ok)
+            throw new Error(result.error);
+        return { plan, sync: await collectMcpSyncReport({ homeDir, backupSession: backup }) };
+    }
+    finally {
+        backup.finalize();
+    }
+}
 /**
  * `mcp scope <name> --agents a,b | --all | --none`
  * (trellis-scope-editing-and-auth-status tasks.md 1.2). Same selector rules as

package/dist/commands/mcpAuth.d.ts

@@ -16,6 +16,11 @@ export interface RunMcpAuthOptions {
     homeDir?: string;
     /** Test seam — the real one launches the platform browser. */
     openBrowser?: (url: string) => void | Promise<void>;
+    signal?: AbortSignal;
+    onProgress?: (phase: "discovering" | "registering" | "waiting" | "exchanging" | "saving") => void;
+    timeoutMs?: number;
+    /** Used by the desktop; native grants belong to each Agent. */
+    requireHosted?: boolean;
 }
 export interface McpAuthResult {
     server: string;
@@ -26,3 +31,4 @@ export interface McpAuthResult {
 export declare function runMcpAuth(opts: RunMcpAuthOptions): Promise<{
     exitCode: number;
 }>;
+export declare function authorizeMcpServer(opts: RunMcpAuthOptions): Promise<McpAuthResult>;

package/dist/commands/mcpAuth.js

@@ -11,16 +11,17 @@
 import { homedir } from "node:os";
 import { loadCanonicalSource } from "../core/canonical.js";
 import { discoverAuthorizationServer, parseResourceMetadataUrl } from "../lib/oauth/discovery.js";
-import { authorize } from "../lib/oauth/flow.js";
+import { authorize, abortable } from "../lib/oauth/flow.js";
 import { ensureFreshToken } from "../lib/oauth/refresh.js";
 import { resolveSecretEnv } from "../lib/secretEnv.js";
 import { isExpired, readToken, tokenPath, writeToken } from "../lib/oauth/store.js";
-import { oauthClientMetadata } from "../core/types.js";
+import { withServerLock } from "../lib/oauth/lock.js";
+import { isOAuthAuth, oauthOwner, oauthClientMetadata } from "../core/types.js";
 export async function runMcpAuth(opts) {
     const homeDir = opts.homeDir ?? homedir();
     let result;
     try {
-        result = await authorizeServer(opts, homeDir);
+        result = await authorizeMcpServer(opts);
     }
     catch (err) {
         console.error(err instanceof Error ? err.message : String(err));
@@ -41,7 +42,9 @@ export async function runMcpAuth(opts) {
     }
     return { exitCode: 0 };
 }
-async function authorizeServer(opts, homeDir) {
+export async function authorizeMcpServer(opts) {
+    const homeDir = opts.homeDir ?? homedir();
+    opts.signal?.throwIfAborted();
     const canonical = loadCanonicalSource(homeDir);
     const def = canonical.mcp.servers[opts.serverName];
     if (!def) {
@@ -54,15 +57,21 @@ async function authorizeServer(opts, homeDir) {
         // flow that does not exist.
         throw new Error(`MCP server "${opts.serverName}" is a stdio server — OAuth applies to http/sse servers. Its credentials come from \`env\`/\`env_aliases\` and secrets.policy.yaml.`);
     }
+    if (opts.requireHosted && (!isOAuthAuth(def.auth) || oauthOwner(def.auth) !== "trellis" || def.enabled === false)) {
+        throw new Error("This connection is authorized by its Agent; choose explicit Trellis ownership before starting hosted authorization");
+    }
     const file = tokenPath(homeDir, opts.serverName);
+    const resourceUrl = new URL(def.url);
+    resourceUrl.hash = "";
     if (!opts.force) {
-        const existing = readToken(homeDir, opts.serverName);
+        const stored = readToken(homeDir, opts.serverName);
+        const existing = stored?.resourceUrl && stored.resourceUrl !== resourceUrl.toString() ? undefined : stored;
         if (existing && !isExpired(existing)) {
             // Re-running is a no-op rather than a fresh grant: rotating a
             // perfectly good credential is a way to break a working setup.
             return { server: opts.serverName, status: "already-valid", tokenFile: file, ...(existing.expiresAt ? { expiresAt: existing.expiresAt } : {}) };
         }
-        if (existing?.refreshToken) {
+        if (existing?.refreshToken && !opts.requireHosted) {
             // Expired but renewable — no browser needed.
             const refreshed = await ensureFreshToken(homeDir, opts.serverName);
             if (refreshed) {
@@ -70,7 +79,10 @@ async function authorizeServer(opts, homeDir) {
             }
         }
     }
-    const metadata = await discoverAuthorizationServer(def.url, { wwwAuthenticate: await probeWwwAuthenticate(def) });
+    opts.onProgress?.("discovering");
+    const fetchImpl = (url, init) => fetch(url, { ...init, signal: opts.signal });
+    const metadata = await abortable(discoverAuthorizationServer(def.url, { wwwAuthenticate: await probeWwwAuthenticate(def, opts.signal), fetchImpl }), opts.signal);
+    opts.signal?.throwIfAborted();
     if (!metadata) {
         throw new Error(`could not discover OAuth metadata for "${opts.serverName}" (${def.url}) — it may not use OAuth, or may not publish RFC 8414/9728 metadata`);
     }
@@ -90,12 +102,28 @@ async function authorizeServer(opts, homeDir) {
         clientSecret = value;
     }
     const token = await authorize(opts.serverName, metadata, {
+        signal: opts.signal,
+        resourceUrl: resourceUrl.toString(),
+        onProgress: opts.onProgress,
+        timeoutMs: opts.timeoutMs,
         ...(opts.openBrowser ? { openBrowser: opts.openBrowser } : {}),
         ...(metadata.scopesSupported?.length ? { scope: metadata.scopesSupported.join(" ") } : {}),
         ...(client.clientId !== undefined ? { clientId: client.clientId } : {}),
         ...(clientSecret !== undefined ? { clientSecret } : {}),
     });
-    writeToken(homeDir, opts.serverName, token);
+    opts.signal?.throwIfAborted();
+    // Serialize the final write with silent refreshes, without holding a lock
+    // while the user is in the browser. An older refresh cannot overwrite a new
+    // grant after it is committed.
+    opts.onProgress?.("saving");
+    await withServerLock(homeDir, opts.serverName, async () => {
+        opts.signal?.throwIfAborted();
+        const current = loadCanonicalSource(homeDir).mcp.servers[opts.serverName];
+        if (!current || current.url !== def.url || JSON.stringify(current.auth) !== JSON.stringify(def.auth) || current.enabled === false) {
+            throw new Error("The server's endpoint or authorization configuration changed; start authorization again");
+        }
+        writeToken(homeDir, opts.serverName, token);
+    });
     return { server: opts.serverName, status: "authorized", tokenFile: file, ...(token.expiresAt ? { expiresAt: token.expiresAt } : {}) };
 }
 /**
@@ -113,9 +141,9 @@ function secretSourceLabel(policy) {
  * server directly, which beats probing well-known paths. Failure is not
  * an error: discovery falls back to probing.
  */
-async function probeWwwAuthenticate(def) {
+async function probeWwwAuthenticate(def, signal) {
     try {
-        const response = await fetch(def.url, { method: "GET" });
+        const response = await fetch(def.url, { method: "GET", signal });
         if (response.status !== 401)
             return null;
         const header = response.headers.get("www-authenticate");

package/dist/commands/mcpGateway.js

@@ -14,10 +14,10 @@
  * an in-process backend without this file, or any agent's config,
  * changing.
  */
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { homedir } from "node:os";
 import { loadCanonicalSource } from "../core/canonical.js";
-import { isGatewayAgent, isOAuthMcpServer, resolveMcpPlan } from "../adapters/mcpPlan.js";
+import { isGatewayAgent, isAgentOwnedOAuth, resolveMcpPlan } from "../adapters/mcpPlan.js";
 import { LocalBackend } from "../lib/gatewayBackend.js";
 import { DEFAULT_CONNECT_TIMEOUT_MS } from "../lib/mcpConnect.js";
 import { BuiltinRegistry, createRuntimeServer, UpstreamProvider } from "../lib/mcpRuntime.js";
@@ -65,7 +65,9 @@ export function resolveGatewayUpstreams(agentId, canonical) {
     const directRoutes = canonical.mcp.routes && route
         ? { ...canonical.mcp.routes, [agentId]: { mode: "direct", ...(route.servers ? { servers: route.servers } : {}) } }
         : canonical.mcp.routes;
-    const ordinaryServers = Object.fromEntries(Object.entries(canonical.mcp.servers).filter(([, def]) => !isOAuthMcpServer(def)));
+    const ordinaryServers = Object.fromEntries(Object.entries(canonical.mcp.servers)
+        .filter(([, def]) => !isAgentOwnedOAuth(def))
+        .map(([name, def]) => { const { auth: _auth, ...ordinary } = def; return [name, ordinary]; }));
     const direct = { ...canonical.mcp, servers: ordinaryServers, gateway: undefined, hub: undefined, routes: directRoutes, runtime: undefined };
     // The managed set is passed through unchanged, so an unmanaged agent
     // reaches nothing. Being spawned is NOT treated as consent here, which
@@ -80,7 +82,7 @@ export function resolveGatewayUpstreams(agentId, canonical) {
     // user just said to stop involving.
     const { desired, conflicts } = resolveMcpPlan(agentId, direct, canonical.managedAgents, canonical.secretsPolicy);
     return {
-        upstreams: desired.map(({ name, def }) => ({ name, def })),
+        upstreams: desired.map(({ name }) => ({ name, def: canonical.mcp.servers[name] })),
         conflicts: conflicts.map((conflict) => conflict.message),
     };
 }
@@ -123,9 +125,7 @@ async function runMcpEdge(opts, clientInfo, serverInfo) {
             homeDir,
         });
     const registry = new BuiltinRegistry([new SkillProvider(), new RuntimeMemoryProvider(), new RuntimeControlProvider(backend), new McpStatusProvider(backend), new TaskProvider(), new AgentBridgeProvider(), new UpstreamProvider(backend)]);
-    const server = createRuntimeServer(serverInfo, { agentId: opts.agentId, homeDir }, registry);
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
+    const server = serveStdio(() => createRuntimeServer(serverInfo, { agentId: opts.agentId, homeDir }, registry));
     await waitForShutdown(registry, server);
     return { exitCode: 0 };
 }

package/dist/core/canonical.d.ts

@@ -25,6 +25,7 @@ type McpServerDefYaml = Omit<McpServerDef, "staticEnv" | "envAliases" | "auth">
  * them — a YAML cast is optimistic, validation is this module's job. */
 type McpAuthYaml = string | {
     kind?: unknown;
+    owner?: unknown;
     client_id?: unknown;
     client_secret_env?: unknown;
 };

package/dist/core/canonical.js

@@ -25,7 +25,7 @@ function fromServerDefYaml(serverName, def) {
  * `auth` translation and shape validation
  * (trellis-mcp-oauth-static-client tasks 1.1/1.3): the scalar and the
  * object form share one discriminator — `kind: oauth` — and the object
- * accepts exactly `kind`, `client_id`, `client_secret_env`. Everything
+ * accepts exactly `kind`, `owner`, `client_id`, `client_secret_env`. Everything
  * else is refused here at load, naming the field but never echoing the
  * value: an invalid `client_secret_env` is at best a typo, at worst a
  * pasted secret.
@@ -36,10 +36,10 @@ function fromAuthYaml(serverName, auth) {
     if (typeof auth !== "object" || auth === null) {
         throw new Error(`mcp/servers.yaml: "${serverName}" auth must be the scalar "oauth" or { kind: oauth, client_id?, client_secret_env? }`);
     }
-    const { kind, client_id, client_secret_env, ...extra } = auth;
+    const { kind, owner, client_id, client_secret_env, ...extra } = auth;
     const unknownKey = Object.keys(extra)[0];
     if (unknownKey !== undefined) {
-        throw new Error(`mcp/servers.yaml: "${serverName}" auth has unrecognized key "${unknownKey}" — expected kind, client_id, client_secret_env`);
+        throw new Error(`mcp/servers.yaml: "${serverName}" auth has unrecognized key "${unknownKey}" — expected kind, owner, client_id, client_secret_env`);
     }
     if (kind !== "oauth") {
         throw new Error(`mcp/servers.yaml: "${serverName}" auth.kind must be "oauth" — kind is the only recognized discriminator`);
@@ -51,6 +51,10 @@ function fromAuthYaml(serverName, auth) {
         throw new Error(`mcp/servers.yaml: "${serverName}" auth.client_secret_env must be a variable NAME (e.g. FIGMA_CLIENT_SECRET), never a secret value`);
     }
     const out = { kind: "oauth" };
+    if (owner !== undefined && owner !== "agent" && owner !== "trellis")
+        throw new Error(`mcp/servers.yaml: "${serverName}" auth.owner must be agent or trellis`);
+    if (owner !== undefined)
+        out.owner = owner;
     if (typeof client_id === "string")
         out.clientId = client_id;
     if (typeof client_secret_env === "string")
@@ -73,6 +77,7 @@ export function toServerDefYaml(def) {
                 ? auth
                 : {
                     kind: auth.kind,
+                    ...(auth.owner !== undefined ? { owner: auth.owner } : {}),
                     ...(auth.clientId !== undefined ? { client_id: auth.clientId } : {}),
                     ...(auth.clientSecretEnv !== undefined ? { client_secret_env: auth.clientSecretEnv } : {}),
                 };

package/dist/core/types.d.ts

@@ -15,6 +15,8 @@ export type McpAuthMode = "oauth";
  */
 export interface McpAuthConfig {
     kind: McpAuthMode;
+    /** Omitted preserves each Agent's native authorization. */
+    owner?: "agent" | "trellis";
     clientId?: string;
     clientSecretEnv?: string;
 }
@@ -23,6 +25,7 @@ export interface McpAuthConfig {
  * object form exists — a strict-equality check would silently strip the
  * OAuth routing from metadata-bearing servers. */
 export declare function isOAuthAuth(auth: McpAuthMode | McpAuthConfig | undefined): boolean;
+export declare function oauthOwner(auth: McpAuthMode | McpAuthConfig | undefined): "agent" | "trellis";
 /** The pre-registered client metadata a classification carries. A scalar
  * carries none — both forms route identically (design.md D1). */
 export declare function oauthClientMetadata(auth: McpAuthMode | McpAuthConfig | undefined): {
@@ -53,7 +56,7 @@ export interface McpServerDef {
     /** Explicit authorization classification. Absence means ordinary MCP;
      * Trellis never infers OAuth from a URL or a transient 401. The scalar
      * form and a metadata-less object are equivalent — metadata extends the
-     * authorization flow, it never changes routing
+     * authorization flow; only explicit `owner: trellis` changes routing
      * (trellis-mcp-oauth-static-client design.md D1). */
     auth?: McpAuthMode | McpAuthConfig;
     /** stdio only */

package/dist/core/types.js

@@ -11,6 +11,9 @@
 export function isOAuthAuth(auth) {
     return auth === "oauth" || (typeof auth === "object" && auth !== null && auth.kind === "oauth");
 }
+export function oauthOwner(auth) {
+    return typeof auth === "object" && auth?.owner === "trellis" ? "trellis" : "agent";
+}
 /** The pre-registered client metadata a classification carries. A scalar
  * carries none — both forms route identically (design.md D1). */
 export function oauthClientMetadata(auth) {

package/dist/lib/agentBridgeProvider.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";
 /** Exposes every `agent-bridge.yaml` target — other than the calling
  * Agent itself — as one MCP tool per target Agent. Routing which target

package/dist/lib/gatewayBackend.d.ts

@@ -18,6 +18,8 @@
 import type { McpServerDef, SecretsPolicy } from "../core/types.js";
 import { type McpClientInfo } from "./mcpConnect.js";
 import { type AggregatedTool } from "./mcpToolRegistry.js";
+import type { Resource, ReadResourceResult } from "@modelcontextprotocol/client";
+import type { SkillEntry } from "./skillManifest.js";
 export interface GatewayBackend {
     /** Every tool available through this backend, under its aggregated name. */
     listTools(): Promise<AggregatedTool[]>;
@@ -25,6 +27,10 @@ export interface GatewayBackend {
     callTool(name: string, args?: Record<string, unknown>): Promise<unknown>;
     /** Sanitized connection state for user/Agent remediation. */
     listStatus?(): readonly UpstreamStatus[];
+    listResources?(): Promise<Resource[]>;
+    readResource?(uri: string): Promise<ReadResourceResult>;
+    listSkills?(): Promise<SkillEntry[]>;
+    getSkill?(uri: string): Promise<SkillEntry | undefined>;
     /** Release everything this backend holds. Must be safe to call twice. */
     close(): Promise<void>;
 }
@@ -79,11 +85,16 @@ export declare class LocalBackend implements GatewayBackend {
     private readonly connected;
     private readonly statuses;
     private closed;
+    private readonly resources;
     private constructor();
     static connect(upstreams: readonly UpstreamSpec[], options: LocalBackendOptions): Promise<LocalBackend>;
     private addUpstream;
     listTools(): Promise<AggregatedTool[]>;
     callTool(name: string, args?: Record<string, unknown>): Promise<unknown>;
+    listResources(): Promise<Resource[]>;
+    readResource(uri: string): Promise<ReadResourceResult>;
+    listSkills(): Promise<SkillEntry[]>;
+    getSkill(uri: string): Promise<SkillEntry | undefined>;
     listStatus(): readonly UpstreamStatus[];
     close(): Promise<void>;
     private closeUpstream;

package/dist/lib/gatewayBackend.js

@@ -15,10 +15,13 @@
  * standard `Client` rather than something with its own shape to maintain
  * (D12).
  */
+import { isOAuthAuth, oauthOwner } from "../core/types.js";
 import { connectServer } from "./mcpConnect.js";
 import { withTimeout } from "./mcpConnect.js";
 import { ensureFreshToken } from "./oauth/refresh.js";
+import { readToken } from "./oauth/store.js";
 import { McpToolRegistry } from "./mcpToolRegistry.js";
+import { UpstreamResources } from "./upstreamResources.js";
 /**
  * v1's backend: connects each upstream itself and aggregates the result.
  *
@@ -34,12 +37,14 @@ export class LocalBackend {
     connected = new Set();
     statuses = new Map();
     closed = false;
-    constructor(warn) {
+    resources;
+    constructor(warn, timeoutMs) {
         this.warn = warn;
+        this.resources = new UpstreamResources(timeoutMs, warn);
     }
     static async connect(upstreams, options) {
         const warn = options.onWarning ?? ((message) => console.error(message));
-        const backend = new LocalBackend(warn);
+        const backend = new LocalBackend(warn, options.connectTimeoutMs);
         await Promise.all(upstreams.map((upstream) => backend.addUpstream(upstream, options)));
         return backend;
     }
@@ -62,7 +67,7 @@ export class LocalBackend {
         }
         let client;
         try {
-            client = (await connectServer(effectiveDef, options.secretsPolicy, options.connectTimeoutMs, options.clientInfo));
+            client = await connectServer(effectiveDef, options.secretsPolicy, options.connectTimeoutMs, options.clientInfo);
         }
         catch (err) {
             this.warn(`trellis-mcp-gateway: failed to connect to MCP server "${name}": ${errorText(err)}`);
@@ -72,7 +77,9 @@ export class LocalBackend {
         this.connected.add(client);
         let tools;
         try {
-            const result = await withTimeout(client.listTools(), options.connectTimeoutMs, `listTools timed out after ${options.connectTimeoutMs}ms`);
+            const result = client.getServerCapabilities()?.tools
+                ? await withTimeout(client.listTools(), options.connectTimeoutMs, `listTools timed out after ${options.connectTimeoutMs}ms`)
+                : { tools: [] };
             tools = result.tools;
         }
         catch (err) {
@@ -82,6 +89,7 @@ export class LocalBackend {
             return;
         }
         const { skipped } = this.registry.add(name, client, tools);
+        this.resources.add(name, client);
         for (const collided of skipped) {
             this.warn(`trellis-mcp-gateway: tool "${collided}" from server "${name}" collides with an already-registered tool and was skipped`);
         }
@@ -107,6 +115,10 @@ export class LocalBackend {
     async callTool(name, args) {
         return this.registry.callTool(name, args);
     }
+    listResources() { return this.resources.listResources(); }
+    readResource(uri) { return this.resources.readResource(uri); }
+    listSkills() { return this.resources.listSkills(); }
+    getSkill(uri) { return this.resources.getSkill(uri); }
     listStatus() {
         return [...this.statuses.values()];
     }
@@ -189,9 +201,16 @@ function failureStatus(name, def, error) {
  * the kind of invisible precedence that is impossible to debug.
  */
 export async function withOAuthHeader(name, def, homeDir) {
+    if (!isOAuthAuth(def.auth) || oauthOwner(def.auth) !== "trellis")
+        return def;
     const hasExplicitAuth = Object.keys(def.headers ?? {}).some((key) => key.toLowerCase() === "authorization");
     if (hasExplicitAuth)
         return def;
+    const stored = readToken(homeDir, name);
+    const resource = new URL(def.url);
+    resource.hash = "";
+    if (stored?.resourceUrl && stored.resourceUrl !== resource.toString())
+        throw new Error("OAuth authorization required: saved credential targets another MCP resource");
     const token = await ensureFreshToken(homeDir, name);
     if (!token)
         return def;

package/dist/lib/mcpConnect.d.ts

@@ -12,8 +12,7 @@
  * which servers are in scope, or knows what a tool is; callers isolate
  * failures in whatever way suits them.
  */
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { Client } from "@modelcontextprotocol/client";
 import type { McpServerDef, SecretsPolicy } from "../core/types.js";
 /** What an MCP upstream is told this client is. Each consumer passes its
  * own so an upstream's logs name the thing that actually connected. */
@@ -40,7 +39,11 @@ export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, m
  * on close, but the original connect failure is what the caller needs
  * to see, not a secondary cleanup error.
  */
-export declare function connectWithCleanup(client: Client, transport: Transport, timeoutMs: number, message: string): Promise<Client>;
+export declare function connectWithCleanup<T, TTransport extends {
+    close(): Promise<void>;
+}>(client: T & {
+    connect(transport: TTransport): Promise<unknown>;
+}, transport: TTransport, timeoutMs: number, message: string): Promise<T>;
 export declare function connectStdio(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;
 export declare function resolveHeaders(def: McpServerDef, secretsPolicy: SecretsPolicy): Record<string, string> | undefined;
 export declare function connectHttp(def: McpServerDef, secretsPolicy: SecretsPolicy, timeoutMs: number, clientInfo: McpClientInfo): Promise<Client>;