@humain/terminal 0.1.1 → 0.2.1

package/dist/humain/mcp-adapter/vendor/server-manager.ts

@@ -1,13 +1,16 @@
 import { mkdirSync, statSync } from "node:fs";
+import { BlockList, isIP } from "node:net";
 import { isDeepStrictEqual } from "node:util";
 import {
   Client,
   SdkError,
   SdkErrorCode,
   SdkHttpError,
+  SseError,
   SSEClientTransport,
   StreamableHTTPClientTransport,
   UnauthorizedError,
+  type FetchLike,
   type GetPromptResult,
   type ListToolsResult,
   type ReadResourceResult,
@@ -38,9 +41,16 @@ import { resolveNpxBinary } from "./npx-resolver.ts";
 import { createJsonSchemaValidator } from "./json-schema-validator.ts";
 import { logger } from "./logger.ts";
 import { RESOURCE_MIME_TYPE } from "./ui-app-bridge-helpers.ts";
+import { isBuiltInAgentPlugin } from "./agent-plugin-provenance.ts";
 import { McpOAuthProvider } from "./mcp-oauth-provider.ts";
 import { extractOAuthConfig, supportsOAuth, type McpOAuthRuntime } from "./mcp-auth-flow.ts";
-import { inspectAuthForUrl, invalidateAuthEntryCache, type AuthStorageOptions } from "./mcp-auth.ts";
+import {
+  captureOAuthAuthority,
+  inspectAuthForUrl,
+  invalidateAuthEntryCache,
+  type AuthStorageOptions,
+  type OAuthAuthority,
+} from "./mcp-auth.ts";
 import { getBearerTokenForUrl } from "./mcp-bearer-store.ts";
 import { registerSamplingHandler, type ServerSamplingConfig } from "./sampling-handler.ts";
 import {
@@ -66,7 +76,9 @@ import {
   traceTransportKind,
   wrapTransportWithMcpTrace,
 } from "./mcp-trace.ts";
+import { createOAuthFetch, resolveOAuthHeaders } from "./mcp-auth-fetch.ts";
 import { createRequestHeadersCommandFetch } from "./request-headers-command.ts";
+import { createCaFetch, validateCaFile } from "./http-ca.ts";
 
 const MAX_CAPTURED_STDERR_BYTES = 8 * 1024;
 const MAX_CAPTURED_STDERR_LINES = 3;
@@ -79,6 +91,35 @@ type HttpAuthProviderState =
   | { status: "explicit"; provider: McpOAuthProvider }
   | { status: "implicit-challenged"; provider: McpOAuthProvider };
 
+function isLiteralLocalAddress(url: string): boolean {
+  const hostname = new URL(url).hostname.replace(/^\[|\]$/g, "");
+  const family = isIP(hostname);
+  if (!family) return false;
+  const local = new BlockList();
+  local.addSubnet("10.0.0.0", 8);
+  local.addSubnet("172.16.0.0", 12);
+  local.addSubnet("192.168.0.0", 16);
+  local.addSubnet("169.254.0.0", 16);
+  local.addSubnet("fc00::", 7, "ipv6");
+  local.addSubnet("fe80::", 10, "ipv6");
+  return local.check(hostname, family === 6 ? "ipv6" : "ipv4");
+}
+
+function localNetworkFailureCodes(error: unknown, seen = new Set<object>()): string[] {
+  if (typeof error !== "object" || error === null || seen.has(error)) return [];
+  seen.add(error);
+  const codes: string[] = [];
+  if ("code" in error && typeof error.code === "string"
+    && ["EHOSTUNREACH", "ENETUNREACH", "EACCES"].includes(error.code)) {
+    codes.push(error.code);
+  }
+  if ("cause" in error) codes.push(...localNetworkFailureCodes(error.cause, seen));
+  if (error instanceof AggregateError) {
+    for (const nested of error.errors) codes.push(...localNetworkFailureCodes(nested, seen));
+  }
+  return [...new Set(codes)];
+}
+
 function isUnauthorizedHttpError(error: unknown): boolean {
   return error instanceof UnauthorizedError || (error instanceof SdkHttpError && error.status === 401);
 }
@@ -139,6 +180,8 @@ export interface ServerConnection {
   /** Monotonic guard against older refresh responses replacing newer notifications. */
   toolsRevision?: number;
   resources: McpResource[];
+  /** True when resources were advertised but resources/list failed. */
+  resourceDiscoveryFailed?: boolean;
   prompts: McpPrompt[];
   /** True when prompts were advertised but prompts/list failed. */
   promptDiscoveryFailed?: boolean;
@@ -172,6 +215,7 @@ export type ToolRefreshResult = "updated" | "unchanged" | "superseded" | "refres
 
 type ToolListCacheHints = Partial<Pick<ListToolsResult, "ttlMs" | "cacheScope">>;
 type ToolListResult = { tools: McpTool[]; hints?: ToolListCacheHints };
+type ResourceListResult = { resources: McpResource[]; failed: boolean };
 
 const KEEP_ALIVE_REFRESH_TIMEOUT_MS = 5_000;
 const LISTEN_RETRY_DELAY_MS = 5_000;
@@ -190,6 +234,7 @@ export function isTransientHttpConnectError(error: unknown): boolean {
 export class McpServerManager {
   private connections = new Map<string, ServerConnection>();
   private connectPromises = new Map<string, Promise<ServerConnection>>();
+  private connectOAuthAuthorities = new Map<string, OAuthAuthority>();
   private reconnectPromises = new Map<string, Promise<ServerConnection>>();
   private uiStreamListeners = new Map<string, UiStreamListener>();
   private samplingConfig: ServerSamplingConfig | undefined;
@@ -305,17 +350,39 @@ export class McpServerManager {
   }
 
   async connect(name: string, definition: ServerDefinition, signal?: AbortSignal): Promise<ServerConnection> {
+    validateCaFile(definition);
     if (isServerDisabled(definition)) throw new Error(`MCP server "${name}" is disabled`);
     if (this.stopped) throw new Error("MCP server manager is closed");
     const ownedSignal = combineAbortSignals(this.runtimeSignal, signal);
     throwIfAborted(ownedSignal);
+    const oauthAuthority = definition.url && supportsOAuth(definition)
+      ? captureOAuthAuthority(name, false)
+      : undefined;
     const closing = this.closePromises.get(name);
     if (closing) await abortable(closing, ownedSignal);
     throwIfAborted(ownedSignal);
 
     // Dedupe concurrent connection attempts.
-    if (this.connectPromises.has(name)) {
-      return abortable(this.connectPromises.get(name)!, ownedSignal);
+    const existingConnect = this.connectPromises.get(name);
+    if (existingConnect) {
+      const existingAuthority = this.connectOAuthAuthorities.get(name);
+      let reusable = oauthAuthority === undefined && existingAuthority === undefined;
+      if (oauthAuthority && existingAuthority) {
+        try {
+          existingAuthority();
+          reusable = true;
+        } catch {
+          reusable = false;
+        }
+      }
+      if (reusable) return abortable(existingConnect, ownedSignal);
+      const replacedAttempt = this.connectAttempts.get(name);
+      replacedAttempt?.abort(new Error(`MCP connection ${name} was replaced`));
+      if (this.connectAttempts.get(name) === replacedAttempt) this.connectAttempts.delete(name);
+      if (this.connectPromises.get(name) === existingConnect) this.connectPromises.delete(name);
+      if (this.connectOAuthAuthorities.get(name) === existingAuthority) {
+        this.connectOAuthAuthorities.delete(name);
+      }
     }
 
     const existing = this.connections.get(name);
@@ -329,11 +396,20 @@ export class McpServerManager {
     const generation = this.closeGenerations.get(name) ?? 0;
     const attemptController = new AbortController();
     const attemptSignal = combineAbortSignals(ownedSignal, attemptController.signal);
-    const connectionAttempt = this.createConnection(name, definition, attemptSignal, ownedSignal, credentialsInvalidated);
+    const connectionAttempt = this.createConnection(
+      name,
+      definition,
+      attemptSignal,
+      ownedSignal,
+      credentialsInvalidated,
+      oauthAuthority,
+      attemptController,
+    );
     const promise = definition.url
       ? connectionAttempt.catch(async error => { throw await this.enrichHttpConnectionError(definition, error); })
       : connectionAttempt;
     this.connectPromises.set(name, promise);
+    if (oauthAuthority) this.connectOAuthAuthorities.set(name, oauthAuthority);
     this.connectAttempts.set(name, attemptController);
 
     try {
@@ -351,6 +427,9 @@ export class McpServerManager {
       return connection;
     } finally {
       if (this.connectPromises.get(name) === promise) this.connectPromises.delete(name);
+      if (this.connectOAuthAuthorities.get(name) === oauthAuthority) {
+        this.connectOAuthAuthorities.delete(name);
+      }
       if (this.connectAttempts.get(name) === attemptController) this.connectAttempts.delete(name);
     }
   }
@@ -673,7 +752,10 @@ export class McpServerManager {
       !isDeepStrictEqual(expectedConnection.tools, nextTools.tools) ||
       !isDeepStrictEqual(expectedConnection.toolListHints, nextTools.hints)
     )) ||
-      (nextResources !== undefined && !isDeepStrictEqual(expectedConnection.resources, nextResources)) ||
+      (nextResources !== undefined && (
+        !isDeepStrictEqual(expectedConnection.resources, nextResources.resources) ||
+        expectedConnection.resourceDiscoveryFailed !== nextResources.failed
+      )) ||
       (nextPrompts !== undefined && (
         !isDeepStrictEqual(expectedConnection.prompts, nextPrompts.prompts) ||
         expectedConnection.promptDiscoveryFailed !== false
@@ -690,7 +772,10 @@ export class McpServerManager {
       expectedConnection.toolListHints = nextTools.hints;
       expectedConnection.toolsRevision = (expectedConnection.toolsRevision ?? 0) + 1;
     }
-    if (nextResources !== undefined) expectedConnection.resources = nextResources;
+    if (nextResources !== undefined) {
+      expectedConnection.resources = nextResources.resources;
+      expectedConnection.resourceDiscoveryFailed = nextResources.failed;
+    }
     if (nextPrompts !== undefined) {
       expectedConnection.prompts = nextPrompts.prompts;
       expectedConnection.promptDiscoveryFailed = false;
@@ -767,6 +852,8 @@ export class McpServerManager {
     signal?: AbortSignal,
     requestSignal?: AbortSignal,
     credentialsInvalidated = false,
+    oauthAuthority?: OAuthAuthority,
+    attemptOwner?: AbortController,
   ): Promise<ServerConnection> {
     throwIfAborted(signal);
 
@@ -795,8 +882,11 @@ export class McpServerManager {
     if (definition.command) {
       client = this.createClient(name, definition);
       let command = definition.command;
-      let args = (definition.args ?? []).map((argument) => interpolateEnvVars(argument));
-      const cwd = resolveConfigPath(definition.cwd) ?? this.defaultCwd;
+      const literalArgs = isBuiltInAgentPlugin(definition, "args");
+      const literalCwd = isBuiltInAgentPlugin(definition, "cwd");
+      let args = literalArgs ? [...(definition.args ?? [])] : (definition.args ?? []).map((argument) => interpolateEnvVars(argument));
+      const cwd = (literalCwd ? definition.cwd : resolveConfigPath(definition.cwd)) ?? this.defaultCwd;
+      if (definition.pluginDataDir) mkdirSync(definition.pluginDataDir, { recursive: true });
       if (cwd !== undefined) {
         const cwdStats = statSync(cwd, { throwIfNoEntry: false });
         if (!cwdStats) throw new Error(`MCP server "${name}" configured cwd does not exist: "${cwd}"`);
@@ -813,11 +903,15 @@ export class McpServerManager {
       }
       throwIfAborted(signal);
 
-      if (definition.pluginDataDir) mkdirSync(definition.pluginDataDir, { recursive: true });
       const stdioTransport = new StdioClientTransport({
         command,
         args,
-        env: resolveEnv(definition.env, name, definition.literalEnv === true),
+        env: resolveEnv(
+          definition.env,
+          name,
+          isBuiltInAgentPlugin(definition, "env") || definition.literalEnv === true,
+          definition.inheritEnv !== false,
+        ),
         ...(cwd !== undefined ? { cwd } : {}),
         stderr: definition.debug ? "inherit" : "pipe",
       });
@@ -837,6 +931,8 @@ export class McpServerManager {
         signal,
         traceObserver,
         invalidated,
+        oauthAuthority,
+        attemptOwner,
       );
       client = httpConnection.client;
       transport = httpConnection.transport;
@@ -905,9 +1001,10 @@ export class McpServerManager {
       // identity so a stale connection's late close can never clobber a fresh
       // connection. The SDK client owns the transport callbacks.
       client.onclose = () => {
-        if (this.connections.get(name) === connection) {
-          connection.status = "closed";
-        }
+        if (connection.status === "closed") return;
+        connection.status = "closed";
+        if (this.connections.get(name) !== connection) return;
+        this.metadataListChangedListener?.(name, "remote-close");
       };
 
       // Discover tools, resources, and prompts. Resource and prompt listing is
@@ -917,9 +1014,13 @@ export class McpServerManager {
         this.fetchAllResources(client, requestOptions),
         this.fetchAllPrompts(client, requestOptions),
       ]);
+      if (connection.status !== "connected") {
+        throw new Error(`MCP connection for ${name} closed during metadata discovery`);
+      }
       connection.tools = toolResult.tools;
       connection.toolListHints = toolResult.hints;
-      connection.resources = resources;
+      connection.resources = resources.resources;
+      connection.resourceDiscoveryFailed = resources.failed;
       connection.prompts = promptResult.prompts;
       connection.promptDiscoveryFailed = promptResult.failed;
 
@@ -977,6 +1078,12 @@ export class McpServerManager {
 
   private async enrichHttpConnectionError(definition: ServerDefinition, error: unknown): Promise<Error> {
     const originalMessage = error instanceof Error ? error.message : String(error);
+    if (process.platform === "darwin") {
+      const codes = localNetworkFailureCodes(error);
+      if (codes.length > 0 && isLiteralLocalAddress(resolveServerUrl(definition)!)) {
+        return new Error(`${originalMessage} — ${codes.join(", ")} — macOS Local Network Privacy may be blocking access. Check System Settings > Privacy & Security > Local Network for the app hosting Pi; enable access if listed and restart it. Try launching Pi from Terminal.app or SSH. Routing or firewall problems can also cause this error.`, { cause: error });
+      }
+    }
     if (isTransientHttpConnectError(error)) {
       return new Error(`${originalMessage} — endpoint is temporarily unavailable (HTTP 503)`, { cause: error });
     }
@@ -1142,6 +1249,7 @@ export class McpServerManager {
     const connection = this.connections.get(serverName);
     if (!connection || connection.client !== client || connection.status !== "connected") return;
     connection.resources = resources;
+    connection.resourceDiscoveryFailed = false;
     this.metadataListChangedListener?.(serverName, "resources-list-changed");
     this.pendingMetadataPublications.delete(serverName);
   }
@@ -1179,6 +1287,8 @@ export class McpServerManager {
     signal?: AbortSignal,
     traceObserver?: McpTraceObserver,
     credentialsInvalidated = false,
+    oauthAuthority?: OAuthAuthority,
+    attemptOwner?: AbortController,
   ): Promise<{ client: Client; transport: Transport; status: "connected" | "needs-auth"; credentialsInvalidated: boolean }> {
     throwIfAborted(signal);
     const serverUrl = resolveServerUrl(definition)!;
@@ -1186,12 +1296,21 @@ export class McpServerManager {
 
     // Resolve secret commands only for this connection attempt, without
     // mutating the persisted configuration.
-    const hasCommandHeader = Object.values(definition.headers ?? {})
+    const literalHeaders = isBuiltInAgentPlugin(definition, "headers");
+    const hasCommandHeader = !literalHeaders && Object.values(definition.headers ?? {})
       .some(value => value.startsWith("!") && !value.startsWith("!!"));
-    const headers = resolveCommandSecretsRecord(
-      definition.headers,
-      key => `MCP server "${serverName}" HTTP header "${key}"`,
-    ) ?? {};
+    const oauthEnabled = supportsOAuth(definition);
+    let headers: Record<string, string>;
+    if (literalHeaders) {
+      headers = { ...definition.headers };
+    } else if (oauthEnabled) {
+      headers = Object.fromEntries(resolveOAuthHeaders(definition.headers));
+    } else {
+      headers = resolveCommandSecretsRecord(
+        definition.headers,
+        key => `MCP server "${serverName}" HTTP header "${key}"`,
+      ) ?? {};
+    }
 
     // Resolve bearer auth before creating requestInit so every attempted
     // transport receives the same headers.
@@ -1216,18 +1335,34 @@ export class McpServerManager {
       }
     }
 
-    const requestInit = Object.keys(headers).length > 0 ? { headers } : undefined;
-    const requestFetch = definition.requestHeadersCommand
-      ? createRequestHeadersCommandFetch(definition.requestHeadersCommand)
-      : undefined;
-    const createAuthProvider = (): McpOAuthProvider => new McpOAuthProvider(
-      serverName,
-      serverUrl,
-      extractOAuthConfig(definition),
-      { onRedirect: async () => {} },
-      this.authStorageOptions,
-      this.oauthRuntime?.signal,
-    );
+    // Do not give origin-bound headers to SDK requestInit: it reuses those
+    // defaults for discovered OAuth endpoints, including other origins.
+    const requestInit = !oauthEnabled && Object.keys(headers).length > 0 ? { headers } : undefined;
+    const serviceHeaders = oauthEnabled ? new Headers(headers) : new Headers();
+    let caFetch = createCaFetch(definition);
+    try {
+    const createAuthProvider = (): McpOAuthProvider => {
+      const currentAttempt = this.connectAttempts.get(serverName);
+      if (currentAttempt && currentAttempt !== attemptOwner) {
+        throw new Error(`MCP connection for ${serverName} was replaced while connecting`);
+      }
+      if (!oauthAuthority) throw new Error(`Missing OAuth authority for ${serverName}`);
+      const provider = new McpOAuthProvider(
+        serverName,
+        serverUrl,
+        extractOAuthConfig(definition),
+        { onRedirect: async () => {} },
+        this.authStorageOptions,
+        this.oauthRuntime?.signal,
+        undefined,
+        oauthAuthority,
+      );
+      provider.setAuthFetch(createOAuthFetch(serverUrl, () => serviceHeaders,
+        combineAbortSignals(this.oauthRuntime?.signal, signal), {
+          ...(caFetch ? { delegate: caFetch.fetch } : {}),
+        }));
+      return provider;
+    };
 
     // Explicit OAuth checks secure storage immediately. Implicit OAuth keeps
     // anonymous servers provider-free unless URL-bound credentials are already
@@ -1252,6 +1387,16 @@ export class McpServerManager {
         : { status: "explicit", provider: createAuthProvider() }
       : { status: "disabled" };
 
+    const commandFetch = definition.requestHeadersCommand
+      ? createRequestHeadersCommandFetch(definition.requestHeadersCommand, caFetch?.fetch)
+      : caFetch?.fetch;
+    const requestFetch = oauthEnabled
+      ? createOAuthFetch(serverUrl, () => serviceHeaders, this.oauthRuntime?.signal, {
+        // MCP streams outlive individual auth requests; retain SDK request deadlines.
+        timeout: false,
+        ...(commandFetch ? { delegate: commandFetch } : {}),
+      })
+      : commandFetch;
     const attempt = async (
       kind: "streamable-http" | "sse",
     ): Promise<
@@ -1259,9 +1404,21 @@ export class McpServerManager {
       | { status: "failed"; client: Client; transport: Transport; error: unknown }
     > => {
       const authProvider = "provider" in authState ? authState.provider : undefined;
+      let sseFetchFailure: unknown;
+      const transportFetch: FetchLike | undefined = kind === "sse" && process.platform === "darwin" && isLiteralLocalAddress(serverUrl)
+        ? async (input, init) => {
+          try {
+            return await (requestFetch ?? globalThis.fetch)(input, init);
+          } catch (error) {
+            // EventSource discards the fetch cause before the SDK creates SseError.
+            if (localNetworkFailureCodes(error).length > 0) sseFetchFailure = error;
+            throw error;
+          }
+        }
+        : requestFetch;
       const transportOptions = {
         ...(requestInit !== undefined ? { requestInit } : {}),
-        ...(requestFetch !== undefined ? { fetch: requestFetch } : {}),
+        ...(transportFetch !== undefined ? { fetch: transportFetch } : {}),
         ...(authProvider !== undefined ? { authProvider } : {}),
         ...(authProvider !== undefined
           && definition.oauth !== false
@@ -1281,6 +1438,9 @@ export class McpServerManager {
         await this.connectClientWithAbort(client, transport, requestOptions, signal);
         return { status: "connected", client, transport };
       } catch (error) {
+        if (error instanceof SseError && sseFetchFailure !== undefined) {
+          error = new AggregateError([error, sseFetchFailure], error.message);
+        }
         const abortCleanupFailed = error instanceof AggregateError
           && error.message === "MCP connection abort cleanup failed";
         if (!abortCleanupFailed) {
@@ -1301,7 +1461,24 @@ export class McpServerManager {
     let invalidated = credentialsInvalidated;
     for (;;) {
       const result = await attempt(kind);
-      if (result.status === "connected") return { ...result, credentialsInvalidated: invalidated };
+      if (result.status === "connected") {
+        const ownedCa = caFetch;
+        if (ownedCa) {
+          const close = result.transport.close.bind(result.transport);
+          const onclose = result.transport.onclose;
+          result.transport.onclose = () => {
+            void ownedCa.close().catch(error => {
+              logger.debug(`MCP: CA dispatcher cleanup failed for ${serverName}: ${String(error)}`);
+            });
+            onclose?.();
+          };
+          result.transport.close = async () => {
+            try { await close(); } finally { await ownedCa.close(); }
+          };
+          caFetch = undefined;
+        }
+        return { ...result, credentialsInvalidated: invalidated };
+      }
       if (result.error instanceof AggregateError
         && result.error.message === "MCP connection abort cleanup failed") {
         throw result.error;
@@ -1334,6 +1511,9 @@ export class McpServerManager {
       }
       throw result.error;
     }
+    } finally {
+      await caFetch?.close();
+    }
   }
 
   private async fetchAllTools(client: Client, requestOptions?: CacheableRequestOptions): Promise<ToolListResult> {
@@ -1391,9 +1571,9 @@ export class McpServerManager {
     }
   }
 
-  private async fetchAllResources(client: Client, requestOptions?: RequestOptions, strict = false): Promise<McpResource[]> {
+  private async fetchAllResources(client: Client, requestOptions?: RequestOptions, strict = false): Promise<ResourceListResult> {
     const capabilities = client.getServerCapabilities?.();
-    if (!capabilities?.resources) return [];
+    if (!capabilities?.resources) return { resources: [], failed: false };
 
     try {
       const allResources: McpResource[] = [];
@@ -1405,7 +1585,7 @@ export class McpServerManager {
         cursor = result.nextCursor;
       } while (cursor);
 
-      return allResources;
+      return { resources: allResources, failed: false };
     } catch (error) {
       if (requestOptions?.signal?.aborted) {
         throwIfAborted(requestOptions.signal);
@@ -1413,7 +1593,7 @@ export class McpServerManager {
       if (isUnauthorizedHttpError(error)) throw error;
       if (strict) throw error;
       // The server advertises resources but the listing failed
-      return [];
+      return { resources: [], failed: true };
     }
   }
 
@@ -1634,10 +1814,17 @@ export class McpServerManager {
 /**
  * Resolve environment variables with interpolation.
  */
-function resolveEnv(env: Record<string, string> | undefined, serverName: string, literalEnv = false): Record<string, string> {
+function resolveEnv(
+  env: Record<string, string> | undefined,
+  serverName: string,
+  literalEnv = false,
+  inheritEnv = true,
+): Record<string, string> {
   const resolved: Record<string, string> = {};
-  for (const [key, value] of Object.entries(process.env)) {
-    if (value !== undefined) resolved[key] = value;
+  if (inheritEnv) {
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined) resolved[key] = value;
+    }
   }
   if (literalEnv) return env ? { ...resolved, ...env } : resolved;