Merge pull request #187 from jayleaton/fix/gateway-bridge-health-20261104

fix(mcp): the gateway gets a durable token and agents see every device's environments

Author: jayleaton

apps/desktop/src/ipc/DesktopIpcHandlers.ts

@@ -37,6 +37,7 @@ import {
   getAppBranding,
   getClientDeviceName,
   getMcpGatewayBridgeToken,
+  ensureMcpGatewayBridgeToken,
   getMcpGatewayLaunchConfig,
   getLocalEnvironmentBootstraps,
   getLocalEnvironmentBearerToken,
@@ -97,6 +98,7 @@ export const installDesktopIpcHandlers = Effect.fn("desktop.ipc.installHandlers"
   yield* ipc.handleSync(getAppBranding);
   yield* ipc.handleSync(getClientDeviceName);
   yield* ipc.handleSync(getMcpGatewayBridgeToken);
+  yield* ipc.handleSync(ensureMcpGatewayBridgeToken);
   yield* ipc.handleSync(getMcpGatewayLaunchConfig);
   yield* ipc.handle(McpGatewayIpc.configureManagedMcpGateway);
   yield* ipc.handleSync(getRelayTelemetryEnabled);

apps/desktop/src/ipc/channels.ts

@@ -33,6 +33,7 @@ export const CLI_COMMAND_UNINSTALL_CHANNEL = "desktop:cli-command-uninstall";
 export const GET_APP_BRANDING_CHANNEL = "desktop:get-app-branding";
 export const GET_MCP_GATEWAY_LAUNCH_CONFIG_CHANNEL = "desktop:get-mcp-gateway-launch-config";
 export const GET_MCP_GATEWAY_BRIDGE_TOKEN_CHANNEL = "desktop:get-mcp-gateway-bridge-token";
+export const ENSURE_MCP_GATEWAY_BRIDGE_TOKEN_CHANNEL = "desktop:ensure-mcp-gateway-bridge-token";
 export const GET_CLIENT_DEVICE_NAME_CHANNEL = "desktop:get-client-device-name";
 export const GET_RELAY_TELEMETRY_ENABLED_CHANNEL = "desktop:get-relay-telemetry-enabled";
 export const GET_SYSTEM_LOCALE_CHANNEL = "desktop:get-system-locale";

apps/desktop/src/ipc/methods/window.ts

@@ -43,7 +43,10 @@ import { safariPermissionCheck } from "../../preview/BrowserImport/SafariPermiss
 import * as IpcChannels from "../channels.ts";
 import * as DesktopIpc from "../DesktopIpc.ts";
 import { resolveMcpGatewayLaunchConfig } from "../../mcpGatewayLaunchConfig.ts";
-import { readMcpGatewayBridgeTokenFromProcess } from "../../mcpGatewayCredential.ts";
+import {
+  ensureMcpGatewayBridgeTokenFromProcess,
+  readMcpGatewayBridgeTokenFromProcess,
+} from "../../mcpGatewayCredential.ts";
 import {
   extractDistroFromUncPath,
   resolveWslPickFolderDefaultPath,
@@ -105,6 +108,15 @@ export const getMcpGatewayBridgeToken = DesktopIpc.makeSyncIpcMethod({
   }),
 });
 
+export const ensureMcpGatewayBridgeToken = DesktopIpc.makeSyncIpcMethod({
+  channel: IpcChannels.ENSURE_MCP_GATEWAY_BRIDGE_TOKEN_CHANNEL,
+  result: Schema.NullOr(Schema.String),
+  handler: Effect.fn("desktop.ipc.window.ensureMcpGatewayBridgeToken")(function* () {
+    const environment = yield* DesktopEnvironment.DesktopEnvironment;
+    return ensureMcpGatewayBridgeTokenFromProcess(environment.homeDirectory);
+  }),
+});
+
 /** The machine's hostname, so agents can tell this desktop apart from the user's other devices. */
 export const getClientDeviceName = DesktopIpc.makeSyncIpcMethod({
   channel: IpcChannels.GET_CLIENT_DEVICE_NAME_CHANNEL,

apps/desktop/src/mcpGatewayCredential.test.ts

@@ -1,6 +1,6 @@
 import { assert, describe, it } from "@effect/vitest";
 
-import { readMcpGatewayBridgeToken } from "./mcpGatewayCredential.ts";
+import { ensureMcpGatewayBridgeToken, readMcpGatewayBridgeToken } from "./mcpGatewayCredential.ts";
 
 const secureFile = {
   isFile: () => true,
@@ -84,3 +84,43 @@ describe("readMcpGatewayBridgeToken", () => {
     }
   });
 });
+
+describe("ensureMcpGatewayBridgeToken", () => {
+  const store = (files: Map<string, { contents: string; mode: number }>) => ({
+    env: {},
+    homeDirectory: "/home/tester",
+    userId: 1000,
+    statFile: (path: string) => {
+      const file = files.get(path);
+      if (file === undefined) throw new Error("ENOENT");
+      return { ...secureFile, mode: file.mode };
+    },
+    readFileString: (path: string) => files.get(path)!.contents,
+    makeDirectory: () => undefined,
+    createFileExclusive: (path: string, contents: string) => {
+      if (files.has(path)) throw new Error("EEXIST");
+      files.set(path, { contents, mode: 0o100600 });
+    },
+    newToken: () => "generated-token-0123456789abcdef",
+  });
+
+  it("creates the protected env file once, so the token survives a restart", () => {
+    const files = new Map<string, { contents: string; mode: number }>();
+    assert.strictEqual(
+      ensureMcpGatewayBridgeToken(store(files)),
+      "generated-token-0123456789abcdef",
+    );
+    assert.deepStrictEqual([...files.keys()], ["/home/tester/.config/t3code/mcp-gateway.env"]);
+    // A new app session reads the same token without generating another.
+    assert.strictEqual(readMcpGatewayBridgeToken(store(files)), "generated-token-0123456789abcdef");
+  });
+
+  it("leaves an existing but unusable env file for its owner to fix", () => {
+    const path = "/home/tester/.config/t3code/mcp-gateway.env";
+    const files = new Map([
+      [path, { contents: "T3_MCP_BRIDGE_TOKEN=shared-token-123456\n", mode: 0o100644 }],
+    ]);
+    assert.isNull(ensureMcpGatewayBridgeToken(store(files)));
+    assert.strictEqual(files.get(path)?.contents, "T3_MCP_BRIDGE_TOKEN=shared-token-123456\n");
+  });
+});

apps/desktop/src/mcpGatewayCredential.ts

@@ -1,4 +1,5 @@
 // @effect-diagnostics nodeBuiltinImport:off - the synchronous preload bootstrap needs a synchronous, fail-closed credential read.
+import * as NodeCrypto from "node:crypto";
 import * as NodeFS from "node:fs";
 import * as NodePath from "node:path";
 
@@ -43,16 +44,14 @@ function parseTokenEnvironmentFile(contents: string): string | null {
   return null;
 }
 
+const credentialFile = (homeDirectory: string) =>
+  NodePath.join(homeDirectory, ".config", "t3code", "mcp-gateway.env");
+
 export function readMcpGatewayBridgeToken(source: McpGatewayCredentialSource): string | null {
   const environmentToken = validateToken(source.env.T3_MCP_BRIDGE_TOKEN);
   if (environmentToken !== null) return environmentToken;
 
-  const credentialPath = NodePath.join(
-    source.homeDirectory,
-    ".config",
-    "t3code",
-    "mcp-gateway.env",
-  );
+  const credentialPath = credentialFile(source.homeDirectory);
   try {
     const file = source.statFile(credentialPath);
     if (!file.isFile() || (source.userId !== null && file.uid !== source.userId)) return null;
@@ -63,12 +62,49 @@ export function readMcpGatewayBridgeToken(source: McpGatewayCredentialSource): s
   }
 }
 
+export interface McpGatewayCredentialStore extends McpGatewayCredentialSource {
+  readonly makeDirectory: (path: string) => void;
+  /** Creates the file only if it does not exist yet. */
+  readonly createFileExclusive: (path: string, contents: string) => void;
+  readonly newToken: () => string;
+}
+
+/**
+ * The token, creating the protected env file when there is none, so an enabled gateway keeps
+ * the same token across restarts. A file that exists but is unusable is left for its owner to fix.
+ */
+export function ensureMcpGatewayBridgeToken(store: McpGatewayCredentialStore): string | null {
+  const existing = readMcpGatewayBridgeToken(store);
+  if (existing !== null) return existing;
+  const credentialPath = credentialFile(store.homeDirectory);
+  try {
+    store.makeDirectory(NodePath.dirname(credentialPath));
+    store.createFileExclusive(
+      credentialPath,
+      `${TOKEN_ENVIRONMENT_VARIABLE}=${store.newToken()}\n`,
+    );
+  } catch {
+    // Another window created it first, or it cannot be written; the read below decides.
+  }
+  return readMcpGatewayBridgeToken(store);
+}
+
+const processCredentialSource = (homeDirectory: string): McpGatewayCredentialStore => ({
+  env: process.env,
+  homeDirectory,
+  userId: typeof process.getuid === "function" ? process.getuid() : null,
+  statFile: NodeFS.statSync,
+  readFileString: (path) => NodeFS.readFileSync(path, "utf8"),
+  makeDirectory: (path) => NodeFS.mkdirSync(path, { recursive: true, mode: 0o700 }),
+  createFileExclusive: (path, contents) =>
+    NodeFS.writeFileSync(path, contents, { flag: "wx", mode: 0o600 }),
+  newToken: () => NodeCrypto.randomBytes(32).toString("hex"),
+});
+
 export function readMcpGatewayBridgeTokenFromProcess(homeDirectory: string): string | null {
-  return readMcpGatewayBridgeToken({
-    env: process.env,
-    homeDirectory,
-    userId: typeof process.getuid === "function" ? process.getuid() : null,
-    statFile: NodeFS.statSync,
-    readFileString: (path) => NodeFS.readFileSync(path, "utf8"),
-  });
+  return readMcpGatewayBridgeToken(processCredentialSource(homeDirectory));
+}
+
+export function ensureMcpGatewayBridgeTokenFromProcess(homeDirectory: string): string | null {
+  return ensureMcpGatewayBridgeToken(processCredentialSource(homeDirectory));
 }

apps/desktop/src/preload.ts

@@ -91,6 +91,10 @@ contextBridge.exposeInMainWorld("desktopBridge", {
     const result = ipcRenderer.sendSync(IpcChannels.GET_MCP_GATEWAY_BRIDGE_TOKEN_CHANNEL);
     return typeof result === "string" ? result : null;
   },
+  ensureMcpGatewayBridgeToken: () => {
+    const result = ipcRenderer.sendSync(IpcChannels.ENSURE_MCP_GATEWAY_BRIDGE_TOKEN_CHANNEL);
+    return typeof result === "string" ? result : null;
+  },
   getRelayTelemetryEnabled: () =>
     ipcRenderer.sendSync(IpcChannels.GET_RELAY_TELEMETRY_ENABLED_CHANNEL) === true,
   getPathForFile: (file: File) => webUtils.getPathForFile(file),

apps/server/src/mcp/McpGatewayBroker.test.ts

@@ -12,6 +12,7 @@ import * as Exit from "effect/Exit";
 import * as Fiber from "effect/Fiber";
 import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
+import * as TestClock from "effect/testing/TestClock";
 import { make } from "./McpGatewayBroker.ts";
 
 type Broker = Effect.Success<typeof make>;
@@ -61,6 +62,45 @@ it.effect("runs calls on the newest app that reaches every environment in them",
   ).pipe(Effect.provide(NodeServices.layer)),
 );
 
+it.effect(
+  "lists every connected app's environments and routes around an app that stopped answering",
+  () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const broker = yield* make;
+        const summary = (environmentId: string, connectionState: string) => ({
+          environmentId,
+          label: environmentId,
+          connectionState,
+          targetKind: "remote",
+        });
+        yield* serve(broker, "studio", { studio: ["read"] }, () => ({
+          result: [summary("studio", "connected")],
+        }));
+        yield* serve(broker, "laptop", { laptop: ["read"], studio: ["read"] }, () => ({
+          result: [summary("laptop", "connected"), summary("studio", "connecting")],
+        }));
+        // An app that stopped answering must not hold up the others' environments.
+        yield* broker
+          .connect("asleep", { asleep: ["read"], laptop: ["read"] })
+          .pipe(Stream.runDrain, Effect.forkScoped({ startImmediately: true }));
+        const listing = yield* broker
+          .forward("listEnvironments", [], [])
+          .pipe(Effect.forkScoped({ startImmediately: true }));
+        yield* TestClock.adjust("10 seconds");
+        expect(yield* Fiber.join(listing)).toEqual([
+          summary("laptop", "connected"),
+          summary("studio", "connected"),
+        ]);
+        // Having timed out, the silent app no longer takes calls another app can run.
+        expect(yield* broker.forward("listProjects", ["laptop"], ["laptop"])).toEqual([
+          summary("laptop", "connected"),
+          summary("studio", "connecting"),
+        ]);
+      }),
+    ).pipe(Effect.provide(NodeServices.layer)),
+);
+
 it.effect("fails calls no connected app can run, and reports app errors", () =>
   Effect.scoped(
     Effect.gen(function* () {