feat(core): surface mid-session transport failures via lastError (#1489)

Closes #1323. Adds an `error`-event-driven `lastError` on useInspectorClient and a mid-session failure toast in App.tsx; the transport onerror is scoped to non-handshake (status !== connecting) so handshake failures stay on the connect() rejection path. Follow-up: #1490.

core/mcp/inspectorClient.ts

@@ -436,6 +436,22 @@ export class InspectorClient extends InspectorClientEventTarget {
       }
     };
     baseTransport.onerror = (error: Error) => {
+      // Suppress ONLY the handshake case. These listeners are attached before
+      // the handshake runs (see connect()), so an SDK transport that reports a
+      // connect-time error via `onerror` — in addition to rejecting connect()
+      // — would otherwise dispatch the `error` event for a failure the awaited
+      // connect() rejection already surfaces, double-reporting it. "connecting"
+      // is precisely that state: the only one with a pending awaited connect()
+      // that will reject.
+      //
+      // We deliberately do NOT guard on `!== "connected"`: on a real
+      // mid-session crash many transports fire BOTH `onclose` and `onerror`,
+      // and the order is transport-dependent. If `onclose` lands first it flips
+      // status to "disconnected", so a "connected"-only guard would swallow the
+      // reason that the trailing `onerror` carries (its sole surface). Firing
+      // from any non-"connecting" state captures the reason regardless of
+      // ordering.
+      if (this.status === "connecting") return;
       this.status = "error";
       this.dispatchTypedEvent("statusChange", this.status);
       this.dispatchTypedEvent("error", error);
@@ -1021,10 +1037,11 @@ export class InspectorClient extends InspectorClientEventTarget {
     } catch (error) {
       this.status = "error";
       this.dispatchTypedEvent("statusChange", this.status);
-      this.dispatchTypedEvent(
-        "error",
-        error instanceof Error ? error : new Error(String(error)),
-      );
+      // Deliberately do NOT dispatch the `error` event here: this is the
+      // awaited `connect()` path, so re-throwing hands the reason straight to
+      // the caller. The `error` event is reserved for non-awaited transitions
+      // (the transport `onerror` above), where there is no promise to reject.
+      // Dispatching here too would double-report a handshake failure.
       throw error;
     }
   }

core/mcp/inspectorClientEventTarget.ts

@@ -61,6 +61,17 @@ export interface InspectorClientEventMap {
   fetchRequest: FetchRequestEntry;
   /** Fired when an in-flight fetch's response body is read asynchronously. */
   fetchRequestBodyUpdate: { id: string; responseBody: string };
+  /**
+   * Fired whenever the client transitions `status` to `"error"` from a path
+   * that is NOT an awaited promise — i.e. a mid-session transport failure
+   * (stdio subprocess crash, SSE stream drop, HTTP 5xx) surfaced via the
+   * transport's `onerror`. The `Error` carries the reason (`.message`,
+   * optional `.cause`). Handshake failures are NOT dispatched here: they
+   * reject the awaited `connect()` promise, so the caller already has the
+   * error and a second surface would double-report it. Consumers that don't
+   * subscribe directly can read the last error via `useInspectorClient`'s
+   * `lastError`.
+   */
   error: Error;
   resourceUpdated: { uri: string };
   progressNotification: Progress & { progressToken?: ProgressToken };

core/react/useInspectorClient.ts

@@ -22,6 +22,14 @@ export interface UseInspectorClientResult {
   serverInfo?: Implementation;
   instructions?: string;
   protocolVersion?: string;
+  /**
+   * Message from the most recent mid-session transport failure (the client's
+   * `error` event — stdio crash, SSE drop, HTTP 5xx). Stays set until the next
+   * connection attempt (`status` → `"connecting"`) clears it, so consumers can
+   * render it without subscribing to the event directly. Handshake failures do
+   * NOT populate this — they reject the `connect()` promise instead.
+   */
+  lastError?: string;
   appRendererClient: AppRendererClient | null;
   connect: () => Promise<void>;
   disconnect: () => Promise<void>;
@@ -58,6 +66,7 @@ export function useInspectorClient(
   const [protocolVersion, setProtocolVersion] = useState<string | undefined>(
     inspectorClient?.getProtocolVersion(),
   );
+  const [lastError, setLastError] = useState<string | undefined>(undefined);
 
   useEffect(() => {
     if (!inspectorClient) {
@@ -66,6 +75,7 @@ export function useInspectorClient(
       setServerInfo(undefined);
       setInstructions(undefined);
       setProtocolVersion(undefined);
+      setLastError(undefined);
       return;
     }
 
@@ -74,9 +84,18 @@ export function useInspectorClient(
     setServerInfo(inspectorClient.getServerInfo());
     setInstructions(inspectorClient.getInstructions());
     setProtocolVersion(inspectorClient.getProtocolVersion());
+    setLastError(undefined);
 
     const onStatusChange = (event: TypedEvent<"statusChange">) => {
       setStatus(event.detail);
+      // A fresh connection attempt clears any stale error from the prior
+      // session so the UI doesn't keep showing why the last transport died.
+      if (event.detail === "connecting") {
+        setLastError(undefined);
+      }
+    };
+    const onError = (event: TypedEvent<"error">) => {
+      setLastError(event.detail.message);
     };
     const onCapabilitiesChange = (event: TypedEvent<"capabilitiesChange">) => {
       setCapabilities(event.detail);
@@ -94,6 +113,7 @@ export function useInspectorClient(
     };
 
     inspectorClient.addEventListener("statusChange", onStatusChange);
+    inspectorClient.addEventListener("error", onError);
     inspectorClient.addEventListener(
       "capabilitiesChange",
       onCapabilitiesChange,
@@ -110,6 +130,7 @@ export function useInspectorClient(
 
     return () => {
       inspectorClient.removeEventListener("statusChange", onStatusChange);
+      inspectorClient.removeEventListener("error", onError);
       inspectorClient.removeEventListener(
         "capabilitiesChange",
         onCapabilitiesChange,
@@ -152,6 +173,7 @@ export function useInspectorClient(
     serverInfo,
     instructions,
     protocolVersion,
+    lastError,
     appRendererClient: inspectorClient?.getAppRendererClient() ?? null,
     connect,
     disconnect,