@omercnet/paseo-omp 2.0.0-next.248.1 → 2.0.0-next.251.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omercnet/paseo-omp",
-  "version": "2.0.0-next.248.1",
+  "version": "2.0.0-next.251.1",
   "type": "module",
   "description": "Paseo integration for OMP, including its direct provider and workspace tooling.",
   "license": "MIT",

package/server/operational-failure-diagnostics.ts

@@ -1,6 +1,7 @@
 export const OMP_OPERATIONAL_FAILURES = [
   { category: "session-open", stage: "startup" },
   { category: "session-open", stage: "catalog" },
+  { category: "session-open", stage: "optional-mcp" },
   { category: "replay-recovery", stage: "persisted-replay" },
   { category: "replay-recovery", stage: "runtime-recovery" },
   { category: "replay-recovery", stage: "rewind" },

package/server/package-version.ts

@@ -1,2 +1,2 @@
 /** Release Please keeps this bundle-safe constant aligned with package.json. */
-export const PASEO_OMP_PACKAGE_VERSION = "2.0.0-next.248.1"; // x-release-please-version
+export const PASEO_OMP_PACKAGE_VERSION = "2.0.0-next.251.1"; // x-release-please-version

package/server/provider/host-tools.ts

@@ -58,6 +58,10 @@ const RESULT_TRUNCATED_NOTICE = "[MCP content truncated; details omitted]";
 const MAX_PENDING_HOST_TOOL_CALLS = 64;
 const MAX_PENDING_HOST_TOOL_BYTES = 8 * 1024 * 1024;
 const DEFAULT_INITIALIZATION_TIMEOUT_MS = 20_000;
+// Cold npx-style servers can take several seconds; 10 s leaves headroom under the 20 s ceiling.
+const OPTIONAL_MCP_SERVER_TIMEOUT_MS = 10_000;
+const MAX_DEGRADED_NOTICE_NAMES = 5;
+const MAX_DEGRADED_NAME_BYTES = 64;
 const DEFAULT_MCP_CALL_LIFETIME_MS = 5 * 60 * 1000;
 const MAX_DIRECT_BROWSER_CALLS = 4;
 const BROWSER_CALL_TIMEOUT_MS = 20_000;
@@ -85,6 +89,8 @@ const DEFAULT_CALL_SCHEDULER: OmpHostToolScheduler = {
 
 export interface OmpHostToolsOpenOptions {
   connectMcp?: OmpMcpConnector;
+  /** Per-server cap for non-Paseo servers. Defaults to 10 s. */
+  optionalServerTimeoutMs?: number;
   signal?: AbortSignal;
   initializationTimeoutMs?: number;
   callTimeoutMs?: number;
@@ -92,6 +98,33 @@ export interface OmpHostToolsOpenOptions {
   reportOperationalFailure?: OmpOperationalFailureReporter;
 }
 
+export type OmpDegradedMcpServer = {
+  name: string;
+  reason: "unavailable" | "timed-out" | "invalid-tools";
+};
+
+const DEGRADED_REASON_TEXT: Record<OmpDegradedMcpServer["reason"], string> = {
+  unavailable: "unavailable",
+  "timed-out": "timed out",
+  "invalid-tools": "invalid tool list",
+};
+
+/** Fixed reason vocabulary and bounded names only: never raw error text. */
+export function describeDegradedMcpServers(degraded: readonly OmpDegradedMcpServer[]): string {
+  const shown = degraded.slice(0, MAX_DEGRADED_NOTICE_NAMES).map((server) => {
+    const name = boundedText(
+      server.name.replace(/[^\p{L}\p{N}_.:@/ -]/gu, ""),
+      MAX_DEGRADED_NAME_BYTES,
+      "server",
+    );
+    return `${name} (${DEGRADED_REASON_TEXT[server.reason]})`;
+  });
+  const more = degraded.length - shown.length;
+  const list = more > 0 ? `${shown.join(", ")}, and ${more} more` : shown.join(", ");
+  const noun = degraded.length === 1 ? "server was" : "servers were";
+  return `${degraded.length} MCP ${noun} skipped: ${list}. Their tools are missing from this session. Reopen the agent after fixing them.`;
+}
+
 type ClassifiedServer = {
   name: string;
   config: ProviderMcpServerConfig;
@@ -508,6 +541,7 @@ export class OmpHostToolsBridge {
     private readonly callTimeoutMs: number,
     private readonly callScheduler: OmpHostToolScheduler,
     private readonly reportOperationalFailure: OmpOperationalFailureReporter,
+    readonly degraded: readonly OmpDegradedMcpServer[],
   ) {
     this.labels = new Map(definitions.map(({ name, label }) => [name, label ?? name]));
   }
@@ -535,89 +569,143 @@ export class OmpHostToolsBridge {
     const connections: OmpMcpConnection[] = [];
     const definitions: OmpHostToolDefinition[] = [];
     const targets = new Map<string, ToolTarget>();
+    const degraded: OmpDegradedMcpServer[] = [];
+    const report = (failure: OmpOperationalFailure) => {
+      try {
+        options.reportOperationalFailure?.(failure);
+      } catch {
+        // Diagnostics must never affect session open.
+      }
+    };
     try {
       for (const server of servers) {
         initialization.signal.throwIfAborted();
-        const connecting = connectMcp(
-          server.name,
-          server.config,
-          config.cwd,
-          initialization.signal,
-        );
-        let connection: OmpMcpConnection;
+        // Only Paseo-owned servers are required. Any other server that fails is skipped whole.
+        const optional = !server.internal;
+        const timeout = optional ? new AbortController() : undefined;
+        const timer = timeout
+          ? setTimeout(
+              () => timeout.abort(),
+              options.optionalServerTimeoutMs ?? OPTIONAL_MCP_SERVER_TIMEOUT_MS,
+            )
+          : undefined;
+        const signal = timeout
+          ? AbortSignal.any([initialization.signal, timeout.signal])
+          : initialization.signal;
+        const connectionCount = connections.length;
+        const definitionCount = definitions.length;
+        const added: string[] = [];
+        let reason: OmpDegradedMcpServer["reason"] = "unavailable";
         try {
-          connection =
-            connectMcp === connectMcpServer
-              ? await connecting
-              : await abortable(connecting, initialization.signal);
-        } catch (error) {
-          if (connectMcp !== connectMcpServer && initialization.signal.aborted) {
-            const cleanup = connecting.then(
-              (lateConnection) => lateConnection.close(),
-              () => undefined,
-            );
-            throw new OmpCleanupFailure(
-              "OMP MCP connection initialization was interrupted",
-              cleanup,
-            );
+          const connecting = connectMcp(server.name, server.config, config.cwd, signal);
+          let connection: OmpMcpConnection;
+          try {
+            connection =
+              connectMcp === connectMcpServer
+                ? await connecting
+                : await abortable(connecting, signal);
+          } catch (error) {
+            if (connectMcp !== connectMcpServer && signal.aborted) {
+              const cleanup = connecting.then(
+                (lateConnection) => lateConnection.close(),
+                (rejection) =>
+                  rejection instanceof OmpCleanupFailure ? rejection.cleanup : undefined,
+              );
+              throw new OmpCleanupFailure(
+                "OMP MCP connection initialization was interrupted",
+                cleanup,
+              );
+            }
+            throw error;
+          }
+          connections.push(connection);
+          const tools = (await discoverMcpTools(connection, signal)).sort((left, right) =>
+            left.name.localeCompare(right.name),
+          );
+          reason = "invalid-tools";
+          const namespace = namespaces.get(server.name);
+          if (!namespace) throw new Error("MCP server namespace is unavailable");
+          for (const tool of tools) {
+            if (
+              !tool.name ||
+              utf8Bytes(tool.name) > MAX_HOST_TOOL_NAME_BYTES ||
+              utf8Bytes(tool.description ?? "") > MAX_HOST_TOOL_DESCRIPTION_BYTES ||
+              !tool.inputSchema ||
+              typeof tool.inputSchema !== "object" ||
+              Array.isArray(tool.inputSchema) ||
+              boundedJsonBytes(tool.inputSchema, MAX_HOST_TOOL_SCHEMA_BYTES) ===
+                Number.POSITIVE_INFINITY
+            ) {
+              throw new Error("MCP server exposed an invalid host tool definition");
+            }
+            if (definitions.length >= MAX_HOST_TOOLS) {
+              throw new Error("MCP servers exposed too many host tools");
+            }
+            let name = exposedToolName(server, namespace, tool.name);
+            if (targets.has(name)) {
+              const suffix = digest(`${server.name}\0${tool.name}`);
+              name = `${name.slice(0, MAX_HOST_TOOL_NAME_BYTES - suffix.length - 1)}_${suffix}`;
+            }
+            if (targets.has(name)) throw new Error("MCP host tool names collide");
+            const normalizedServerName = safeName(server.name, "server");
+            const normalizedToolName = safeName(tool.name, "tool");
+            const friendlyToolName = normalizedToolName.startsWith(`${normalizedServerName}_`)
+              ? normalizedToolName.slice(normalizedServerName.length + 1)
+              : tool.name;
+            const fallbackLabel = `${humanizeName(server.name)}: ${humanizeName(friendlyToolName)}`;
+            definitions.push({
+              name,
+              label: boundedText(tool.title ?? fallbackLabel, MAX_HOST_TOOL_LABEL_BYTES, name),
+              description: boundedText(
+                tool.description ?? `MCP tool from ${server.name}`,
+                MAX_HOST_TOOL_DESCRIPTION_BYTES,
+                "MCP tool",
+              ),
+              loadMode:
+                server.internal || server.config.alwaysLoad === true ? "essential" : "discoverable",
+              parameters: structuredClone(tool.inputSchema),
+            });
+            targets.set(name, { toolName: tool.name, connection });
+            added.push(name);
           }
-          throw error;
-        }
-        connections.push(connection);
-        const tools = (await discoverMcpTools(connection, initialization.signal)).sort(
-          (left, right) => left.name.localeCompare(right.name),
-        );
-        const namespace = namespaces.get(server.name);
-        if (!namespace) throw new Error("MCP server namespace is unavailable");
-        for (const tool of tools) {
           if (
-            !tool.name ||
-            utf8Bytes(tool.name) > MAX_HOST_TOOL_NAME_BYTES ||
-            utf8Bytes(tool.description ?? "") > MAX_HOST_TOOL_DESCRIPTION_BYTES ||
-            !tool.inputSchema ||
-            typeof tool.inputSchema !== "object" ||
-            Array.isArray(tool.inputSchema) ||
-            boundedJsonBytes(tool.inputSchema, MAX_HOST_TOOL_SCHEMA_BYTES) ===
-              Number.POSITIVE_INFINITY
+            boundedJsonBytes(
+              definitions,
+              MAX_HOST_TOOL_CATALOG_BYTES,
+              MAX_HOST_TOOLS,
+              64 * 1024,
+            ) === Number.POSITIVE_INFINITY
           ) {
-            throw new Error("MCP server exposed an invalid host tool definition");
-          }
-          if (definitions.length >= MAX_HOST_TOOLS) {
-            throw new Error("MCP servers exposed too many host tools");
+            throw new OmpPublicError("OMP host tool catalog exceeds the RPC frame limit");
           }
-          let name = exposedToolName(server, namespace, tool.name);
-          if (targets.has(name)) {
-            const suffix = digest(`${server.name}\0${tool.name}`);
-            name = `${name.slice(0, MAX_HOST_TOOL_NAME_BYTES - suffix.length - 1)}_${suffix}`;
+        } catch (error) {
+          if (!optional || initialization.signal.aborted) throw error;
+          if (error instanceof OmpCleanupFailure) {
+            try {
+              await abortable(error.cleanup, initialization.signal);
+            } catch {
+              throw error;
+            }
+          } else if (connections.length > connectionCount) {
+            const failed = connections.pop() as OmpMcpConnection;
+            const closing = Promise.resolve().then(() => failed.close());
+            try {
+              await abortable(closing, initialization.signal);
+            } catch {
+              throw new OmpCleanupFailure("OMP MCP host tool cleanup failed", closing);
+            }
           }
-          if (targets.has(name)) throw new Error("MCP host tool names collide");
-          const normalizedServerName = safeName(server.name, "server");
-          const normalizedToolName = safeName(tool.name, "tool");
-          const friendlyToolName = normalizedToolName.startsWith(`${normalizedServerName}_`)
-            ? normalizedToolName.slice(normalizedServerName.length + 1)
-            : tool.name;
-          const fallbackLabel = `${humanizeName(server.name)}: ${humanizeName(friendlyToolName)}`;
-          definitions.push({
-            name,
-            label: boundedText(tool.title ?? fallbackLabel, MAX_HOST_TOOL_LABEL_BYTES, name),
-            description: boundedText(
-              tool.description ?? `MCP tool from ${server.name}`,
-              MAX_HOST_TOOL_DESCRIPTION_BYTES,
-              "MCP tool",
-            ),
-            loadMode:
-              server.internal || server.config.alwaysLoad === true ? "essential" : "discoverable",
-            parameters: structuredClone(tool.inputSchema),
+          definitions.length = definitionCount;
+          for (const name of added) targets.delete(name);
+          degraded.push({
+            name: server.name,
+            reason: timeout?.signal.aborted ? "timed-out" : reason,
           });
-          targets.set(name, { toolName: tool.name, connection });
+          report({ category: "session-open", stage: "optional-mcp" });
+        } finally {
+          clearTimeout(timer);
         }
       }
-      if (
-        boundedJsonBytes(definitions, MAX_HOST_TOOL_CATALOG_BYTES, MAX_HOST_TOOLS, 64 * 1024) ===
-        Number.POSITIVE_INFINITY
-      ) {
-        throw new OmpPublicError("OMP host tool catalog exceeds the RPC frame limit");
-      }
       return new OmpHostToolsBridge(
         connections,
         definitions,
@@ -625,6 +713,7 @@ export class OmpHostToolsBridge {
         callTimeoutMs,
         callScheduler,
         options.reportOperationalFailure ?? (() => {}),
+        degraded,
       );
     } catch (error) {
       const cleanupTasks = [

package/server/provider/session.ts

@@ -24,7 +24,13 @@ import {
   type OmpRecoveryOptions,
   withCommittedOmpSelection,
 } from "./config-normalization";
-import { OmpHostToolsBridge, type OmpMcpConnector, validateOmpHostToolConfig } from "./host-tools";
+import {
+  describeDegradedMcpServers,
+  type OmpDegradedMcpServer,
+  OmpHostToolsBridge,
+  type OmpMcpConnector,
+  validateOmpHostToolConfig,
+} from "./host-tools";
 import { isOmpImageMimeType, OmpImageMaterializer } from "./image";
 import type { OmpRuntime, OmpRuntimeSession } from "./omp-rpc";
 import { buildOmpSpawnRequest, type OmpStartOptions } from "./omp-rpc-environment";
@@ -331,6 +337,7 @@ export class OmpProviderSession implements OmpOpenedSession {
   private readonly permissions: OmpSessionPermissions;
   private unsupportedThinkingNoticePending = false;
   private unsupportedThinkingNoticePublished = false;
+  private degradedMcpServers: readonly OmpDegradedMcpServer[] = [];
 
   private constructor(
     id: string,
@@ -685,6 +692,7 @@ export class OmpProviderSession implements OmpOpenedSession {
         scheduler,
       );
       session.unsupportedThinkingNoticePending = unsupportedThinkingLevel;
+      session.degradedMcpServers = hostTools.degraded;
 
       if (bootstrapConfigRevision !== reconciledConfigRevision) {
         session.configRefreshDirty = true;
@@ -744,6 +752,7 @@ export class OmpProviderSession implements OmpOpenedSession {
       ...(this.config.title ? { title: this.dataFilter.text(this.config.title, 256) } : {}),
     });
     this.publishUnsupportedThinkingNotice();
+    this.publishDegradedMcpNotice();
     this.emit({ type: "session.config", sessionId: this.id, config: this.configState });
     if (this.replayHistoryOnOpen) await this.replayHistory(true);
     this.publishCommands(this.commandCatalog);
@@ -767,6 +776,19 @@ export class OmpProviderSession implements OmpOpenedSession {
       },
     });
   }
+  private publishDegradedMcpNotice(): void {
+    if (this.degradedMcpServers.length === 0) return;
+    this.emit({
+      type: "session.notice",
+      sessionId: this.id,
+      notice: {
+        id: "omp:mcp-servers-unavailable",
+        severity: "warning",
+        title: "MCP servers unavailable",
+        description: describeDegradedMcpServers(this.degradedMcpServers),
+      },
+    });
+  }
 
   private async replayHistory(preferPersistedTranscript = false): Promise<void> {
     if (!this.runtime.canReplayHistory) {