@humain/terminal 0.0.6 → 0.0.7

package/dist/humain/mcp-adapter/vendor/proxy-modes.ts

@@ -1,5 +1,5 @@
 import type { AgentToolResult, ToolInfo } from "@earendil-works/pi-coding-agent";
-import { UrlElicitationRequiredError, type Client } from "@modelcontextprotocol/client";
+import { UrlElicitationRequiredError, type Client, type Progress, type RequestOptions } from "@modelcontextprotocol/client";
 import { createRequire } from "node:module";
 import type { McpExtensionState } from "./state.ts";
 import type { ToolMetadata, McpContent } from "./types.ts";
@@ -18,6 +18,7 @@ import { authenticate, completeAuthFromInput, startAuth, supportsOAuth } from ".
 import { SessionRecoveryAuthRequiredError, withSessionRecovery } from "./session-recovery.ts";
 import { paginate, rankSuggestions, rankToolMatches, resolveSearchKeywords } from "./search-ranking.ts";
 import { ensureToolCallApproved, isToolCallApprovalRequired } from "./tool-approval.ts";
+import { isServerInActiveFailureBackoff } from "./failure-backoff.ts";
 
 type ProxyToolResult = AgentToolResult<Record<string, unknown>>;
 type ClientCallToolResult = Awaited<ReturnType<Client["callTool"]>>;
@@ -37,6 +38,30 @@ type AutoAuthResult =
   | { status: "success" }
   | { status: "failed"; message: string };
 
+let nextProgressInvocationId = 1;
+
+/**
+ * Bridges SDK request-local progress callbacks to the interactive UI notify
+ * path (#437 item 3). The SDK owns `_meta.progressToken` injection when
+ * `onprogress` is set; this never writes the token manually.
+ */
+function withUiProgressBridge(
+  options: RequestOptions | undefined,
+  ui: McpExtensionState["ui"],
+  serverName: string,
+  toolName: string,
+): RequestOptions | undefined {
+  if (!ui) return options;
+  const label = `MCP ${serverName}/${toolName}#${nextProgressInvocationId++}`;
+  return {
+    ...options,
+    onprogress: (progress: Progress) => {
+      const ratio = `${progress.progress}${progress.total === undefined ? "" : `/${progress.total}`}`;
+      ui.notify(progress.message ? `${label}: ${progress.message} (${ratio})` : `${label}: ${ratio}`, "info");
+    },
+  };
+}
+
 function getToolMatches(metadata: ToolMetadata[] | undefined, toolName: string, exact: boolean): ToolMetadata[] {
   if (!metadata) return [];
   if (exact) return metadata.filter(tool => tool.name === toolName);
@@ -53,12 +78,39 @@ function getEnabledToolMatches(state: McpExtensionState, toolName: string, exact
   return matches;
 }
 
+function serverBackoffResult(state: McpExtensionState, mode: string, serverName: string): ProxyToolResult {
+  const failedAgo = getFailureAgeSeconds(state, serverName) ?? 0;
+  const message = `Server "${serverName}" not available (last failed ${failedAgo}s ago)`;
+  return {
+    content: [{ type: "text" as const, text: message }],
+    details: { mode, error: "server_backoff", server: serverName },
+  };
+}
+
 function getSingleToolMatch(metadata: ToolMetadata[] | undefined, toolName: string): ToolMetadata | "ambiguous" | undefined {
   const exactMatches = getToolMatches(metadata, toolName, true);
   const matches = exactMatches.length > 0 ? exactMatches : getToolMatches(metadata, toolName, false);
   return matches.length > 1 ? "ambiguous" : matches[0];
 }
 
+type ServerScopedToolMatch = { tool: ToolMetadata; precedence: number } | "ambiguous";
+
+function getServerScopedToolMatch(metadata: ToolMetadata[] | undefined, toolName: string): ServerScopedToolMatch | undefined {
+  if (!metadata) return undefined;
+  const normalizedName = toolName.replace(/-/g, "_");
+  const matchesByPrecedence = [
+    metadata.filter((tool) => tool.name === toolName),
+    metadata.filter((tool) => tool.originalName === toolName),
+    metadata.filter((tool) => tool.name.replace(/-/g, "_") === normalizedName),
+    metadata.filter((tool) => tool.originalName.replace(/-/g, "_") === normalizedName),
+  ];
+  for (const [precedence, matches] of matchesByPrecedence.entries()) {
+    if (matches.length > 1) return "ambiguous";
+    if (matches.length === 1) return { tool: matches[0]!, precedence };
+  }
+  return undefined;
+}
+
 function ambiguousToolResult(mode: "call" | "describe", toolName: string): ProxyToolResult {
   const message = `Tool "${toolName}" matches multiple servers. Specify a server.`;
   return {
@@ -91,22 +143,30 @@ function getAuthFailedMessage(state: McpExtensionState, serverName: string, mess
   return `OAuth authentication failed for "${serverName}": ${message}. Run mcp({ action: "auth-start", server: "${serverName}" }) to get a browser URL, or /mcp-auth ${serverName} in an interactive local session.`;
 }
 
-function getRedirectPort(authorizationUrl: string): number | undefined {
+function getRedirectDetails(authorizationUrl: string): { port?: number; remote: boolean } {
   try {
     const redirectUri = new URL(authorizationUrl).searchParams.get("redirect_uri");
-    if (!redirectUri) return undefined;
-    const port = Number.parseInt(new URL(redirectUri).port, 10);
-    return Number.isInteger(port) ? port : undefined;
+    if (!redirectUri) return { remote: false };
+    const redirect = new URL(redirectUri);
+    const hostname = redirect.hostname.toLowerCase();
+    const local = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+    const port = Number.parseInt(redirect.port, 10);
+    return {
+      ...(Number.isInteger(port) ? { port } : {}),
+      remote: !local,
+    };
   } catch {
-    return undefined;
+    return { remote: false };
   }
 }
 
 function formatManualAuthInstructions(serverName: string, authorizationUrl: string): string {
-  const port = getRedirectPort(authorizationUrl);
-  const portNote = port
-    ? `\nThe redirect URL will use local port ${port}. On a remote server it is expected for that localhost page to fail locally; copy the address bar URL anyway.`
-    : "";
+  const redirect = getRedirectDetails(authorizationUrl);
+  const redirectNote = redirect.remote
+    ? "The provider uses a pre-registered HTTPS callback. Copy its full URL from the browser address bar, even if the destination page reports an error."
+    : redirect.port
+      ? `The redirect URL will use local port ${redirect.port}. On a remote server it is expected for that localhost page to fail locally; copy the address bar URL anyway.`
+      : "";
 
   return [
     `MCP OAuth required for "${serverName}".`,
@@ -115,11 +175,13 @@ function formatManualAuthInstructions(serverName: string, authorizationUrl: stri
     "",
     authorizationUrl,
     "",
-    "After approving, copy the full redirected localhost URL from your browser address bar and send it back with:",
+    "After approving, copy the full callback URL from your browser address bar and send it back with:",
     `mcp({ action: "auth-complete", server: "${serverName}", args: { redirectUrl: "PASTE_REDIRECT_URL_HERE" } })`,
     "",
-    'You can also pass just the `code` query parameter as `args: { code: "PASTE_CODE_HERE" }`. JSON-string args remain supported.',
-    portNote.trimEnd(),
+    redirect.remote
+      ? "Remote HTTPS callbacks must include the full callback URL so the OAuth state can be checked. JSON-string args remain supported."
+      : 'You can also pass just the `code` query parameter as `args: { code: "PASTE_CODE_HERE" }`. JSON-string args remain supported.',
+    redirectNote,
   ].filter(Boolean).join("\n");
 }
 
@@ -284,7 +346,6 @@ export function executeStatus(state: McpExtensionState): ProxyToolResult {
     const disabled = isServerDisabled(definition);
     const connection = disabled ? undefined : state.manager.getConnection(name);
     const metadata = disabled ? undefined : state.toolMetadata.get(name);
-    const toolCount = metadata?.length ?? 0;
     const failedAgo = disabled ? null : getFailureAgeSeconds(state, name);
     let status = disabled ? "disabled" : "not connected";
     if (!disabled && connection?.status === "connected") {
@@ -297,6 +358,8 @@ export function executeStatus(state: McpExtensionState): ProxyToolResult {
       status = "cached";
     }
 
+    const toolCount = status === "failed" ? 0 : metadata?.length ?? 0;
+
     servers.push({ name, status, toolCount, failedAgo, ...(disabled ? { disabled: true } : {}) });
   }
 
@@ -418,7 +481,7 @@ export async function executeAuthComplete(state: McpExtensionState, serverName:
     }
 
     await state.manager.close(serverName);
-    clearFailure(state, serverName);
+    clearFailure(state, serverName, "auth-complete");
     updateStatusBar(state);
     return {
       content: [{ type: "text" as const, text: `OAuth authentication successful for "${serverName}". Run mcp({ connect: "${serverName}" }) to connect with the new token.` }],
@@ -434,15 +497,17 @@ export async function executeAuthComplete(state: McpExtensionState, serverName:
 }
 
 export function executeDescribe(state: McpExtensionState, toolName: string): ProxyToolResult {
-  const exactMatches = getEnabledToolMatches(state, toolName, true);
+  const exactMatches = getEnabledToolMatches(state, toolName, true)
+    .filter((match) => !isServerInActiveFailureBackoff(state, match.server));
   if (exactMatches.length > 1) return ambiguousToolResult("describe", toolName);
-  if (exactMatches.length === 0 && getEnabledToolMatches(state, toolName, false).length > 1) {
+  if (exactMatches.length === 0 && getEnabledToolMatches(state, toolName, false).filter((match) => !isServerInActiveFailureBackoff(state, match.server)).length > 1) {
     return ambiguousToolResult("describe", toolName);
   }
 
   let serverName = exactMatches[0]?.server;
   let toolMeta = exactMatches[0]?.tool;
   let disabledMatch: string | undefined;
+  let failedMatch: string | undefined;
 
   if (!toolMeta) {
     for (const [server, metadata] of state.toolMetadata.entries()) {
@@ -452,6 +517,10 @@ export function executeDescribe(state: McpExtensionState, toolName: string): Pro
         disabledMatch ??= server;
         continue;
       }
+      if (isServerInActiveFailureBackoff(state, server)) {
+        failedMatch ??= server;
+        continue;
+      }
       serverName = server;
       toolMeta = found;
       break;
@@ -460,6 +529,7 @@ export function executeDescribe(state: McpExtensionState, toolName: string): Pro
 
   if (!serverName || !toolMeta) {
     if (disabledMatch) return disabledResult("describe", disabledMatch);
+    if (failedMatch) return serverBackoffResult(state, "describe", failedMatch);
     const suggestions = rankSuggestions(state, toolName, 5);
     const suggestionText = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : "";
     return {
@@ -504,6 +574,7 @@ export function executeSearch(
 ): ProxyToolResult {
   const showSchemas = includeSchemas !== false;
   if (server && isServerDisabled(state.config.mcpServers[server])) return disabledResult("search", server);
+  if (server && isServerInActiveFailureBackoff(state, server)) return serverBackoffResult(state, "search", server);
 
   let matches: Array<{ server: string; tool: ToolMetadata; score: number }>;
   if (regex) {
@@ -545,6 +616,7 @@ export function executeSearch(
     for (const [serverName, metadata] of state.toolMetadata.entries()) {
       const definition = state.config.mcpServers[serverName];
       if (isServerDisabled(definition)) continue;
+      if (isServerInActiveFailureBackoff(state, serverName)) continue;
       if (server && serverName !== server) continue;
       for (const tool of metadata) {
         const matched = pattern.test(tool.name) || pattern.test(tool.description)
@@ -644,6 +716,12 @@ export function executeList(state: McpExtensionState, server: string): ProxyTool
   const metadata = state.toolMetadata.get(server);
   const toolNames = metadata?.map(m => m.name) ?? [];
   const connection = state.manager.getConnection(server);
+  if (isServerInActiveFailureBackoff(state, server)) {
+    return {
+      ...serverBackoffResult(state, "list", server),
+      details: { mode: "list", server, tools: [], count: 0, error: "server_backoff" },
+    };
+  }
   const instructions = state.serverInstructions.get(server);
   let instructionsText = "";
   if (instructions) {
@@ -708,6 +786,7 @@ export function executeInstructions(state: McpExtensionState, server: string): P
     };
   }
   if (isServerDisabled(definition)) return disabledResult("instructions", server);
+  if (isServerInActiveFailureBackoff(state, server)) return serverBackoffResult(state, "instructions", server);
 
   const instructions = state.serverInstructions.get(server);
   if (instructions) {
@@ -787,9 +866,9 @@ export async function executeConnect(state: McpExtensionState, serverName: strin
       state.serverInstructions.delete(serverName);
     }
     updateMetadataCache(state, serverName);
-    notifyToolMetadataUpdated(state, serverName, "proxy-connect");
+    const restored = clearFailure(state, serverName, "proxy-connect");
+    if (!restored) notifyToolMetadataUpdated(state, serverName, "proxy-connect");
     markKeepAliveAfterConnect(state, serverName);
-    clearFailure(state, serverName);
     updateStatusBar(state);
     return executeList(state, serverName);
   } catch (error) {
@@ -843,9 +922,9 @@ export async function executeCall(
     };
   }
   if (serverName) {
-    const match = getSingleToolMatch(state.toolMetadata.get(serverName), toolName);
+    const match = getServerScopedToolMatch(state.toolMetadata.get(serverName), toolName);
     if (match === "ambiguous") return ambiguousToolResult("call", toolName);
-    toolMeta = match;
+    toolMeta = match?.tool;
     if (isServerDisabled(state.config.mcpServers[serverName])) {
       return disabledCallResult(serverName, toolMeta);
     }
@@ -887,9 +966,15 @@ export async function executeCall(
   if (serverName && !toolMeta) {
     const connected = await lazyConnect(state, serverName, ownedSignal);
     if (connected) {
-      const match = getSingleToolMatch(state.toolMetadata.get(serverName), toolName);
-      if (match === "ambiguous") return ambiguousToolResult("call", toolName);
-      toolMeta = match;
+      if (serverOverride) {
+        const match = getServerScopedToolMatch(state.toolMetadata.get(serverName), toolName);
+        if (match === "ambiguous") return ambiguousToolResult("call", toolName);
+        toolMeta = match?.tool;
+      } else {
+        const match = getSingleToolMatch(state.toolMetadata.get(serverName), toolName);
+        if (match === "ambiguous") return ambiguousToolResult("call", toolName);
+        toolMeta = match;
+      }
     } else {
       const needsAuthConnection = state.manager.getConnection(serverName);
       if (needsAuthConnection?.status === "needs-auth") {
@@ -907,9 +992,9 @@ export async function executeCall(
             clearFailure(state, serverName);
             const connectedAfterAuth = await lazyConnect(state, serverName, ownedSignal);
             if (connectedAfterAuth) {
-              const match = getSingleToolMatch(state.toolMetadata.get(serverName), toolName);
+              const match = getServerScopedToolMatch(state.toolMetadata.get(serverName), toolName);
               if (match === "ambiguous") return ambiguousToolResult("call", toolName);
-              toolMeta = match;
+              toolMeta = match?.tool;
               if (!toolMeta) {
                 const suggestions = rankSuggestions(state, toolName, 5);
                 const suggestionText = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}` : "";
@@ -1100,15 +1185,21 @@ export async function executeCall(
           };
         }
       }
-      clearFailure(state, serverName);
       updateServerMetadata(state, serverName);
       updateMetadataCache(state, serverName);
-      notifyToolMetadataUpdated(state, serverName, "proxy-call-reconnect");
+      const restored = clearFailure(state, serverName, "proxy-call-reconnect");
+      if (!restored) notifyToolMetadataUpdated(state, serverName, "proxy-call-reconnect");
       markKeepAliveAfterConnect(state, serverName);
       updateStatusBar(state);
-      const match = getSingleToolMatch(state.toolMetadata.get(serverName), toolName);
-      if (match === "ambiguous") return ambiguousToolResult("call", toolName);
-      toolMeta = match;
+      if (serverOverride) {
+        const match = getServerScopedToolMatch(state.toolMetadata.get(serverName), toolName);
+        if (match === "ambiguous") return ambiguousToolResult("call", toolName);
+        toolMeta = match?.tool;
+      } else {
+        const match = getSingleToolMatch(state.toolMetadata.get(serverName), toolName);
+        if (match === "ambiguous") return ambiguousToolResult("call", toolName);
+        toolMeta = match;
+      }
       if (!toolMeta) {
         const available = getToolNames(state, serverName);
         const hint = available.length > 0
@@ -1162,7 +1253,12 @@ export async function executeCall(
   }
 
   let uiSession: UiSessionRuntime | null = null;
-  const requestOptions = state.manager.getRequestOptions?.(serverName, ownedSignal) ?? (ownedSignal ? { signal: ownedSignal } : undefined);
+  const requestOptions = withUiProgressBridge(
+    state.manager.getRequestOptions?.(serverName, ownedSignal) ?? (ownedSignal ? { signal: ownedSignal } : undefined),
+    state.ui,
+    serverName,
+    toolMeta.originalName,
+  );
 
   const outputGuardOptions = resolveMcpOutputGuardOptions(state.config.settings);
   const recoverAuthConnection = async () => {

package/dist/humain/mcp-adapter/vendor/request-headers-command.ts

@@ -92,7 +92,7 @@ function killRequestHeadersCommand(child: ChildProcess, trackedPosixDescendantPi
       encoding: "utf8",
       windowsHide: true,
     });
-    if (result.status === 0 || isTaskkillNoSuchProcess(result)) return;
+    if (result.status === 0 || result.status === 128 || isTaskkillNoSuchProcess(result)) return;
     throw new Error(`HTTP request headers command cleanup failed: taskkill exited with code ${result.status ?? "unknown"}`);
   }
 

package/dist/humain/mcp-adapter/vendor/search-ranking.ts

@@ -1,6 +1,7 @@
 import type { McpExtensionState } from "./state.ts";
 import type { ServerEntry, ToolMetadata, ToolPrefix } from "./types.ts";
 import { getServerPrefix, getToolNameCandidates, isServerDisabled, matchesToolPattern, resolveToolPrefix } from "./types.ts";
+import { isServerInActiveFailureBackoff } from "./failure-backoff.ts";
 
 /**
  * Shortest field token allowed to stem-match a longer query token.
@@ -242,6 +243,7 @@ export function rankToolMatches(
     if (server && serverName !== server) continue;
     const definition = state.config.mcpServers[serverName];
     if (isServerDisabled(definition)) continue;
+    if (isServerInActiveFailureBackoff(state, serverName)) continue;
     for (const prepared of getPreparedTools(state, serverName, metadata, definition, globalPrefix, includeKeywords)) {
       const score = scorePreparedToolMatch(prepared, normalizedQuery, queryTokens);
       if (score !== null) matches.push({ server: serverName, tool: prepared.tool, score });

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

@@ -1,4 +1,4 @@
-import { mkdirSync } from "node:fs";
+import { mkdirSync, statSync } from "node:fs";
 import { isDeepStrictEqual } from "node:util";
 import {
   Client,
@@ -9,6 +9,7 @@ import {
   StreamableHTTPClientTransport,
   UnauthorizedError,
   type GetPromptResult,
+  type ListToolsResult,
   type ReadResourceResult,
   type CacheableRequestOptions,
   type RequestOptions,
@@ -33,6 +34,7 @@ import {
 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 { McpOAuthProvider } from "./mcp-oauth-provider.ts";
 import { extractOAuthConfig, supportsOAuth, type McpOAuthRuntime } from "./mcp-auth-flow.ts";
 import { invalidateAuthEntryCache, type AuthStorageOptions } from "./mcp-auth.ts";
@@ -128,6 +130,8 @@ export interface ServerConnection {
   transport: Transport;
   definition: ServerDefinition;
   tools: McpTool[];
+  /** Cache hints from the server's aggregated tools/list result. */
+  toolListHints?: Partial<Pick<ListToolsResult, "ttlMs" | "cacheScope">> | undefined;
   /** Monotonic guard against older refresh responses replacing newer notifications. */
   toolsRevision?: number;
   resources: McpResource[];
@@ -148,8 +152,20 @@ type MetadataListChangedListener = (serverName: string, reason: string) => void;
 
 export type ToolRefreshResult = "updated" | "unchanged" | "superseded" | "refresh-timeout";
 
+type ToolListCacheHints = Partial<Pick<ListToolsResult, "ttlMs" | "cacheScope">>;
+type ToolListResult = { tools: McpTool[]; hints?: ToolListCacheHints };
+
 const KEEP_ALIVE_REFRESH_TIMEOUT_MS = 5_000;
 
+export function isTransientHttpConnectError(error: unknown): boolean {
+  let current: unknown = error;
+  while (current instanceof Error) {
+    if (current instanceof SdkHttpError && current.status === 503) return true;
+    current = current.cause;
+  }
+  return false;
+}
+
 export class McpServerManager {
   private connections = new Map<string, ServerConnection>();
   private connectPromises = new Map<string, Promise<ServerConnection>>();
@@ -375,9 +391,9 @@ export class McpServerManager {
 
     const toolsRevision = expectedConnection.toolsRevision ?? 0;
     const refreshSignal = combineAbortSignals(healthOptions.signal, AbortSignal.timeout(timeout));
-    let tools: McpTool[];
+    let toolResult: ToolListResult;
     try {
-      tools = await this.fetchAllTools(expectedConnection.client, {
+      toolResult = await this.fetchAllTools(expectedConnection.client, {
         ...healthOptions,
         ...(refreshSignal ? { signal: refreshSignal } : {}),
         cacheMode: "refresh",
@@ -401,20 +417,30 @@ export class McpServerManager {
       return "superseded";
     }
 
-    if (isDeepStrictEqual(expectedConnection.tools, tools)) {
+    if (
+      isDeepStrictEqual(expectedConnection.tools, toolResult.tools) &&
+      isDeepStrictEqual(expectedConnection.toolListHints, toolResult.hints)
+    ) {
       this.retryPendingMetadataPublication(name, expectedConnection);
       return "unchanged";
     }
 
     const previousTools = expectedConnection.tools;
-    expectedConnection.tools = tools;
+    const previousToolListHints = expectedConnection.toolListHints;
+    expectedConnection.tools = toolResult.tools;
+    expectedConnection.toolListHints = toolResult.hints;
     expectedConnection.toolsRevision = toolsRevision + 1;
     try {
       await this.metadataListChangedListener?.(name, "keep-alive-refresh");
       this.pendingMetadataPublications.delete(name);
     } catch (error) {
-      if (this.connections.get(name) === expectedConnection && expectedConnection.tools === tools) {
+      if (
+        this.connections.get(name) === expectedConnection &&
+        expectedConnection.tools === toolResult.tools &&
+        expectedConnection.toolListHints === toolResult.hints
+      ) {
         expectedConnection.tools = previousTools;
+        expectedConnection.toolListHints = previousToolListHints;
         expectedConnection.toolsRevision = toolsRevision;
       }
       throw error;
@@ -488,7 +514,13 @@ export class McpServerManager {
     if (definition.command) {
       client = this.createClient(name, definition);
       let command = definition.command;
-      let args = (definition.args ?? []).map(interpolateEnvVars);
+      let args = (definition.args ?? []).map((argument) => interpolateEnvVars(argument));
+      const cwd = resolveConfigPath(definition.cwd) ?? this.defaultCwd;
+      if (cwd !== undefined) {
+        const cwdStats = statSync(cwd, { throwIfNoEntry: false });
+        if (!cwdStats) throw new Error(`MCP server "${name}" configured cwd does not exist: "${cwd}"`);
+        if (!cwdStats.isDirectory()) throw new Error(`MCP server "${name}" configured cwd is not a directory: "${cwd}"`);
+      }
 
       if (command === "npx" || command === "npm") {
         const resolved = await resolveNpxBinary(command, args, signal);
@@ -501,7 +533,6 @@ export class McpServerManager {
       throwIfAborted(signal);
 
       if (definition.pluginDataDir) mkdirSync(definition.pluginDataDir, { recursive: true });
-      const cwd = resolveConfigPath(definition.cwd) ?? this.defaultCwd;
       const stdioTransport = new StdioClientTransport({
         command,
         args,
@@ -588,12 +619,13 @@ export class McpServerManager {
 
       // Discover tools, resources, and prompts. Resource and prompt listing is
       // optional: only servers advertising the capability are queried.
-      const [tools, resources, promptResult] = await Promise.all([
+      const [toolResult, resources, promptResult] = await Promise.all([
         this.fetchAllTools(client, requestOptions),
         this.fetchAllResources(client, requestOptions),
         this.fetchAllPrompts(client, requestOptions),
       ]);
-      connection.tools = tools;
+      connection.tools = toolResult.tools;
+      connection.toolListHints = toolResult.hints;
       connection.resources = resources;
       connection.prompts = promptResult.prompts;
       connection.promptDiscoveryFailed = promptResult.failed;
@@ -651,6 +683,9 @@ export class McpServerManager {
 
   private async enrichHttpConnectionError(definition: ServerDefinition, error: unknown): Promise<Error> {
     const originalMessage = error instanceof Error ? error.message : String(error);
+    if (isTransientHttpConnectError(error)) {
+      return new Error(`${originalMessage} — endpoint is temporarily unavailable (HTTP 503)`, { cause: error });
+    }
     try {
       const probe = await probeMcpEndpoint(resolveServerUrl(definition)!);
       return new Error(`${originalMessage} — probe: ${probe.classification}`, { cause: error });
@@ -691,6 +726,11 @@ export class McpServerManager {
 
   private buildClientCapabilities() {
     return {
+      extensions: {
+        "io.modelcontextprotocol/ui": {
+          mimeTypes: [RESOURCE_MIME_TYPE],
+        },
+      },
       ...(this.samplingConfig ? { sampling: {} } : {}),
       ...(this.elicitationConfig
         ? {
@@ -987,17 +1027,34 @@ export class McpServerManager {
     }
   }
 
-  private async fetchAllTools(client: Client, requestOptions?: CacheableRequestOptions): Promise<McpTool[]> {
+  private async fetchAllTools(client: Client, requestOptions?: CacheableRequestOptions): Promise<ToolListResult> {
     const allTools: McpTool[] = [];
     let cursor: string | undefined;
+    let hints: ToolListCacheHints | undefined;
+    let firstPage = true;
 
     do {
       const result = await client.listTools(cursor ? { cursor } : undefined, requestOptions);
+      if (firstPage) {
+        const ttlMs = typeof result.ttlMs === "number" && Number.isSafeInteger(result.ttlMs) && result.ttlMs >= 0
+          ? result.ttlMs
+          : undefined;
+        const cacheScope = result.cacheScope === "public" || result.cacheScope === "private"
+          ? result.cacheScope
+          : undefined;
+        if (ttlMs !== undefined || cacheScope !== undefined) {
+          hints = {
+            ...(ttlMs !== undefined ? { ttlMs } : {}),
+            ...(cacheScope !== undefined ? { cacheScope } : {}),
+          };
+        }
+        firstPage = false;
+      }
       allTools.push(...(result.tools ?? []));
       cursor = result.nextCursor;
     } while (cursor);
 
-    return allTools;
+    return { tools: allTools, ...(hints !== undefined ? { hints } : {}) };
   }
 
   private async fetchAllPrompts(

package/dist/humain/mcp-adapter/vendor/state.ts

@@ -3,12 +3,10 @@ import type { ConsentManager } from "./consent-manager.ts";
 import type { McpLifecycleManager } from "./lifecycle.ts";
 import type { McpServerManager } from "./server-manager.ts";
 import type { AuthStorageOptions } from "./mcp-auth.ts";
-import type { ToolMetadata, PromptMetadata, McpConfig, UiSessionMessages, UiStreamSummary } from "./types.ts";
+import type { ToolMetadata, PromptMetadata, McpConfig, UiSessionMessages, UiStreamSummary, McpStatusEventBus, UiServerHandle } from "./types.ts";
 import type { UiResourceHandler } from "./ui-resource-handler.ts";
-import type { UiServerHandle } from "./ui-server.ts";
 import type { McpRuntimeOwner } from "./runtime-owner.ts";
 import type { McpOAuthRuntime } from "./mcp-auth-flow.ts";
-import type { McpStatusEventBus } from "./mcp-status.ts";
 
 export interface CompletedUiSession {
   serverName: string;

package/dist/humain/mcp-adapter/vendor/tool-result-renderer.ts

@@ -4,7 +4,7 @@ import { type Component, Text, truncateToWidth, visibleWidth } from "@earendil-w
 type McpToolResultDetails = Record<string, unknown> & { error?: unknown };
 type McpToolContentBlock = AgentToolResult<McpToolResultDetails>["content"][number];
 
-interface RenderTheme {
+export interface RenderTheme {
   fg: (name: string, text: string) => string;
   bold?: (text: string) => string;
 }
@@ -28,7 +28,7 @@ interface McpToolRenderState {
   compactInputPreview?: string;
 }
 
-interface McpToolRenderContext {
+export interface McpToolRenderContext {
   isError: boolean;
   isPartial?: boolean;
   expanded?: boolean;
@@ -250,6 +250,13 @@ export function formatMcpDirectToolCallLines(
   return [displayName, formatJsonish(args, maxInputChars)];
 }
 
+export function formatMcpScriptToolCallLines(
+  args: { code: string },
+  maxInputChars = DEFAULT_MAX_CALL_INPUT_CHARS,
+): string[] {
+  return ["mcpScript", truncateText(args.code, maxInputChars)];
+}
+
 function renderToolCallLines(lines: string[], theme?: RenderTheme) {
   const activeTheme = theme ?? plainTheme;
   const [title = "mcp", ...rest] = lines;
@@ -314,6 +321,13 @@ export function createMcpDirectToolCallRenderer(displayName: string, options = r
   };
 }
 
+export function createMcpScriptToolCallRenderer(options = resolveMcpToolRenderOptions()) {
+  return (args: { code: string }, theme?: RenderTheme, context?: McpToolRenderContext) => {
+    if (shouldUseCompactFinalRender(options, context)) return new EmptyComponent();
+    return renderToolCallLines(formatMcpScriptToolCallLines(args), theme);
+  };
+}
+
 function blockToLines(block: McpToolContentBlock): string[] {
   if (block.type === "text") {
     return block.text.split("\n");