@hafla/intelligence-mcp-bridge 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to `@hafla/intelligence-mcp-bridge` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] — 2026-05-16
+
+### Added
+
+- Initial public release. Extracted from the private monorepo's `hafla-intelligence/mcp-gateway/scripts/mcp-gateway-bridge.js`.
+- stdio↔HTTPS bridge with 60-minute Google ID token minting via `gcloud auth print-identity-token`, in-memory cache with 5-min refresh-ahead window, and 401-triggered cache invalidation.
+- Pre-flight checks: gcloud installed, an `@hafla.com` account is the active one.
+- Runtime diagnostic banners for the four most common failure modes (gcloud not found, wrong-domain account, 401 audience mismatch, 403 employee_inactive).
+- Cross-platform support — Windows is handled by a `GCLOUD_BIN` constant that picks `gcloud.cmd` over `gcloud` based on `process.platform`.
+- Zero npm runtime dependencies — Node ≥20 stdlib only.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hafla (Evinops Limited)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# @hafla/intelligence-mcp-bridge
+
+A small stdio↔HTTPS shim that lets Claude Code, Claude Desktop, Cursor, and Gemini CLI reach the **Hafla MCP Gateway** at `mcp.hafla.com`.
+
+The bridge mints a fresh 60-minute Google ID token via your own `gcloud` session, caches it, refreshes it ~55 minutes before expiry, and forwards every JSON-RPC request to the gateway with a `Bearer` header. No shared secret, no per-user token to issue or rotate — authorisation is your Google Workspace identity.
+
+---
+
+## Prerequisites
+
+Ops must have done two one-time things for you:
+
+1. Added you to the `team@hafla.com` Google Workspace group.
+2. Flagged your account `isEmployeeActive=true` in `haflaCore.OpsUsers`.
+
+If you have not received confirmation from Ops, the bridge will start, but the gateway will return `403 employee_inactive` on the first request.
+
+---
+
+## Install — 3 steps
+
+### 1. Install the Google Cloud SDK (one-time, skip if you already have `gcloud`)
+
+| OS            | Command                                                                                                                                                                                |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **macOS**     | `brew install --cask google-cloud-sdk`                                                                                                                                                 |
+| **Windows**   | `winget install Google.CloudSDK`  _(or)_ `choco install gcloudsdk`  _(or)_ download the installer at [cloud.google.com/sdk/docs/install#windows](https://cloud.google.com/sdk/docs/install#windows) |
+| **Linux**     | Follow [cloud.google.com/sdk/docs/install#linux](https://cloud.google.com/sdk/docs/install#linux)                                                                                      |
+
+### 2. Sign in with your `@hafla.com` account
+
+```bash
+gcloud auth login                              # browser opens → log in with @hafla.com
+gcloud config set account <you>@hafla.com      # only needed if you have other gcloud accounts
+gcloud auth list                               # confirm @hafla.com row shows "*"
+```
+
+The bridge's pre-flight rejects any non-`@hafla.com` active account before sending traffic, so the `gcloud config set account` step matters if you already use `gcloud` for personal projects.
+
+### 3. Add this MCP server block to your client config
+
+The JSON block is identical on every OS — only the file path differs.
+
+| Client          | Config file (macOS / Linux)     | Config file (Windows)                       |
+| --------------- | ------------------------------- | ------------------------------------------- |
+| Claude Code     | `~/.claude.json`                | `%USERPROFILE%\.claude.json`                |
+| Claude Code (project-scoped) | `<project>/.mcp.json` | `<project>\.mcp.json`                       |
+| Claude Desktop  | `~/Library/Application Support/Claude/claude_desktop_config.json` | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Gemini CLI      | `~/.gemini/settings.json`       | `%USERPROFILE%\.gemini\settings.json`       |
+
+Add (or replace) the `hafla-evwa-idl-gateway` block under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "hafla-evwa-idl-gateway": {
+      "command": "npx",
+      "args": ["-y", "@hafla/intelligence-mcp-bridge@1.0.0"]
+    }
+  }
+}
+```
+
+Restart the MCP client. Done.
+
+---
+
+## What tools you get
+
+Five read-only tools, all backed by Hafla's data lakes + identity layer (live at `mcp.hafla.com`):
+
+| Tool                        | What it does                                                       |
+| --------------------------- | ------------------------------------------------------------------ |
+| `safe_sql_sandbox`          | Parameterised read-only AlloyDB SQL across all lakes               |
+| `safe_cypher_sandbox`       | Parameterised read-only Neo4j Cypher over the identity graph      |
+| `analyze_identity_graph`    | Cross-lake identity resolution — one unified profile per person   |
+| `get_ticket_360`            | Full Zendesk ticket with linked WhatsApp chats and Slack threads  |
+| `search_internal_knowledge` | Semantic search over the WhatsApp / Slack conversation corpus     |
+
+All five are read-only at the database layer — the bridge cannot write.
+
+---
+
+## Verify
+
+Restart your client and ask it:
+
+> Run `safe_sql_sandbox` with `SELECT COUNT(*) FROM "haflaCore"."OpsUsers"`.
+
+A row count comes back, you're done. The very first request takes ~1–2 s longer while the bridge mints your first Google ID token; subsequent calls reuse the cached token.
+
+---
+
+## Troubleshooting
+
+The bridge writes actionable diagnostic banners to stderr. Where you see "MCP client logs" below, that's:
+
+- **Claude Code / Claude Desktop:** the client's own log file (varies by OS — check the client's documentation)
+- **Gemini CLI:** the terminal where you launched the client
+
+| Symptom / banner                                                                  | Cause                                                                                | Fix                                                                                                                                                                                                                                |
+| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `gcloud CLI not found`                                                            | Google Cloud SDK isn't installed (or not on PATH)                                    | Re-run the install command from Step 1. On Windows, may need a restart for PATH to take effect.                                                                                                                                    |
+| `Active gcloud account is X — must be an @hafla.com account`                      | You're logged into `gcloud` with a personal account                                  | `gcloud config set account <you>@hafla.com` — then `gcloud auth list` to confirm the `*` is on your @hafla.com row. If your @hafla.com account is missing, `gcloud auth login` first.                                              |
+| `gateway returned 401 — token audience likely mismatched`                         | Cloud Run edge rejected the token                                                    | Most common cause: you're not yet in the `team@hafla.com` Google Group — ping Ops. Less common: the gateway deploy is missing `https://mcp.hafla.com` in `customAudiences` — that's an Ops fix. Sometimes a cached token pre-dates your group add — re-run `gcloud auth login` to mint a fresh one. |
+| `gateway returned 403 employee_inactive`                                          | You're in the group but not active in OpsUsers                                       | Ping Ops to set `isEmployeeActive=true` on your `haflaCore.OpsUsers` row.                                                                                                                                                          |
+| `Failed to mint Google ID token`                                                  | `gcloud` could not produce an identity token                                         | Usual causes (the banner lists them): (1) credentials expired → `gcloud auth login`; (2) wrong active project → `gcloud config get-value project`; (3) older gcloud SDK → `gcloud components update`.                              |
+| Silent failure / no response in the client                                        | MCP client cannot spawn `npx` or `node`                                              | Verify `node` is on PATH (`node --version`) and is **20.0 or newer**. To get more diagnostics, add `"env": { "DEBUG": "1" }` to the server block and tail the MCP client's log.                                                    |
+| **(Windows)** `gcloud CLI not found` even though gcloud is installed              | gcloud's `bin/` isn't on PATH (the installer doesn't always add it)                  | In PowerShell: `where.exe gcloud`. If empty, add `%LOCALAPPDATA%\Google\Cloud SDK\google-cloud-sdk\bin\` to PATH via **System → Environment Variables**, then restart the MCP client.                                              |
+| **(Windows)** MCP client fails to spawn the bridge — no stderr at all             | `npx.cmd` not on PATH, or Node ≥20 not available                                     | In PowerShell: `where.exe npx` and `node --version`. Under nvm-windows, run `nvm use <version>` first; the bridge requires Node ≥20.                                                                                                |
+
+---
+
+## Upgrading
+
+Because `npx -y @hafla/intelligence-mcp-bridge@1.0.0` is **pinned to an exact version**, npm caches that specifier under `~/.npm/_npx/<hash>/` and keeps re-using the cached copy across restarts. New versions ship via three steps:
+
+1. Edit the `args` in your `.mcp.json` / `settings.json` to the new version, e.g. `"@hafla/intelligence-mcp-bridge@1.0.1"`.
+2. Restart the MCP client.
+3. `npx` pulls the new tarball on first invocation; the previous cache entry stays put under the old hash.
+
+Optional: `npx clear-npx-cache` or remove `~/.npm/_npx/<hash>/` if you want to force a re-download for the same version.
+
+**Do not switch to `@latest`** — pinning is the supply-chain hygiene boundary. Ops announces every version bump in Slack so the team can update on their own cadence.
+
+---
+
+## What this bridge does NOT do
+
+- Store credentials of any kind. It runs as your user, uses your gcloud session.
+- Open inbound ports. It's stdio↔HTTPS, the client launches it on demand.
+- Write to anything. Authorisation at the gateway is read-only; SQL/Cypher writes are rejected at the database layer.
+- Contact a server other than `https://mcp.hafla.com` (unless you override `GATEWAY_URL` for local dev).
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@hafla/intelligence-mcp-bridge",
+  "version": "1.0.0",
+  "description": "stdio↔HTTPS bridge to the Hafla MCP Gateway at mcp.hafla.com, with gcloud-minted Google ID token auth.",
+  "type": "module",
+  "bin": {
+    "intelligence-mcp-bridge": "src/index.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/index.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evinops-hafla/hafla-intelligence-gateway.git",
+    "directory": "packages/intelligence-mcp-bridge"
+  },
+  "homepage": "https://github.com/evinops-hafla/hafla-intelligence-gateway/tree/main/packages/intelligence-mcp-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/evinops-hafla/hafla-intelligence-gateway/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "gemini-cli",
+    "stdio",
+    "bridge",
+    "cloud-run",
+    "google-oidc",
+    "hafla"
+  ],
+  "author": "Hafla (Evinops Limited)",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.js

@@ -0,0 +1,533 @@
+#!/usr/bin/env node
+/**
+ * MCP stdio bridge for the Hafla Intelligence Gateway at mcp.hafla.com.
+ *
+ * stdio↔HTTPS forwarder with Google ID token minting + caching + diagnostics,
+ * used by Claude Code / Claude Desktop / Cursor / Gemini CLI to reach the
+ * Cloud Run IAM-gated production service.
+ *
+ * Why this exists:
+ *   MCP HTTP clients take only static headers in their config. Cloud Run IAM
+ *   requires a fresh 60-min Google ID token. The bridge runs as a long-lived
+ *   stdio child process, mints + caches the token via gcloud, refreshes ~55 min
+ *   before expiry, and forwards JSON-RPC over HTTPS with a fresh Bearer
+ *   header on every request.
+ *
+ * Pre-flight diagnostics (run once at startup):
+ *   (a) gcloud CLI installed + at least one ACTIVE account
+ *   (b) active account is on the required Workspace domain (default: hafla.com)
+ * Runtime diagnostics (on 401 / 403 from gateway):
+ *   (c) 401 = likely audience mismatch — points to --add-custom-audiences
+ *   (d) 403 employee_inactive = OpsUsers.isEmployeeActive=false — contact ops
+ *
+ * Environment:
+ * - GATEWAY_URL: gateway base URL (default https://mcp.hafla.com)
+ * - GATEWAY_PATH: MCP endpoint path (default /mcp)
+ * - GATEWAY_AUDIENCE: JWT aud claim (default GATEWAY_URL)
+ * - REQUIRED_DOMAIN: required Workspace domain for active gcloud account (default hafla.com)
+ * - REQUEST_TIMEOUT_MS: HTTP request timeout in ms (default 30000)
+ * - TOKEN_REFRESH_BEFORE_MS: refresh-ahead window in ms (default 300000 = 5 min)
+ * - DEBUG: set to "1" for verbose logging
+ *
+ * The script exits non-zero with an actionable diagnostic banner on any
+ * pre-flight failure or on a hard runtime error. The diagnostic banner
+ * is printed to stderr (stdout is reserved for MCP JSON-RPC traffic).
+ */
+
+import { request as httpsRequest } from 'node:https';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { pipeline } from 'node:stream/promises';
+import { Transform } from 'node:stream';
+
+const execFileAsync = promisify(execFile);
+
+// Windows ships gcloud as gcloud.cmd; Node's execFile doesn't apply PATHEXT.
+const GCLOUD_BIN = process.platform === 'win32' ? 'gcloud.cmd' : 'gcloud';
+
+// ── Configuration ────────────────────────────────────────────────────────────
+
+const rawGatewayUrl = process.env.GATEWAY_URL || 'https://mcp.hafla.com';
+
+// HTTPS enforcement — the bridge mints Google ID tokens; sending them over
+// plaintext HTTP would expose them on the wire. Allow http:// only for local
+// dev hostnames (localhost, 127.0.0.1) where there's no network exposure.
+{
+  const u = (() => {
+    try {
+      return new URL(rawGatewayUrl);
+    } catch {
+      process.stderr.write(
+        `\n┌── intelligence-mcp-bridge: invalid GATEWAY_URL\n│ Could not parse: ${rawGatewayUrl}\n└──\n\n`
+      );
+      process.exit(1);
+    }
+  })();
+  const isLocalDev =
+    u.hostname === 'localhost' ||
+    u.hostname === '127.0.0.1' ||
+    u.hostname === '0.0.0.0';
+  if (u.protocol !== 'https:' && !isLocalDev) {
+    process.stderr.write(
+      `\n┌── intelligence-mcp-bridge: refusing plaintext HTTP for non-local GATEWAY_URL\n│ Got: ${rawGatewayUrl}\n│ Fix: set GATEWAY_URL to https:// (or localhost for dev)\n└──\n\n`
+    );
+    process.exit(1);
+  }
+}
+
+const config = {
+  gatewayUrl: rawGatewayUrl,
+  gatewayPath: process.env.GATEWAY_PATH || '/mcp',
+  audience:
+    process.env.GATEWAY_AUDIENCE ||
+    process.env.GATEWAY_URL ||
+    'https://mcp.hafla.com',
+  requiredDomain: process.env.REQUIRED_DOMAIN || 'hafla.com',
+  requestTimeoutMs: Number.parseInt(
+    process.env.REQUEST_TIMEOUT_MS || '30000',
+    10
+  ),
+  tokenRefreshBeforeMs: Number.parseInt(
+    process.env.TOKEN_REFRESH_BEFORE_MS || '300000', // 5 min
+    10
+  ),
+  // Google ID tokens have a fixed 60-min lifetime.
+  tokenLifetimeMs: 60 * 60_000,
+  debug: process.env.DEBUG === '1'
+};
+
+// ── Logging (stderr only — stdout is the MCP channel) ───────────────────────
+
+const log = {
+  info: (msg, data) =>
+    process.stderr.write(
+      JSON.stringify({ level: 'info', msg, ...data }) + '\n'
+    ),
+  warn: (msg, data) =>
+    process.stderr.write(
+      JSON.stringify({ level: 'warn', msg, ...data }) + '\n'
+    ),
+  error: (msg, data) =>
+    process.stderr.write(
+      JSON.stringify({ level: 'error', msg, ...data }) + '\n'
+    ),
+  debug: (msg, data) => {
+    if (config.debug) {
+      process.stderr.write(
+        JSON.stringify({ level: 'debug', msg, ...data }) + '\n'
+      );
+    }
+  }
+};
+
+// ── Diagnostic banner — actionable failure messages to stderr ───────────────
+
+export function diagnosticBanner(title, ...lines) {
+  process.stderr.write(`\n┌── intelligence-mcp-bridge: ${title}\n`);
+  for (const l of lines) process.stderr.write(`│ ${l}\n`);
+  process.stderr.write(`└──\n\n`);
+}
+
+function fail(title, ...lines) {
+  diagnosticBanner(title, ...lines);
+  process.exit(1);
+}
+
+// ── gcloud invocation — injectable for tests ────────────────────────────────
+
+/**
+ * Execute a gcloud command. Returns trimmed stdout.
+ * Throws {message, stderr, code} on failure.
+ *
+ * Exported for unit-test injection; tests replace it with a stub.
+ */
+export async function execGcloud(args, { execFn = execFileAsync } = {}) {
+  try {
+    const { stdout } = await execFn(GCLOUD_BIN, args, { timeout: 15_000 });
+    return stdout.toString().trim();
+  } catch (err) {
+    const stderr = err.stderr?.toString?.() ?? '';
+    const wrapped = new Error(err.message);
+    wrapped.stderr = stderr;
+    wrapped.code = err.code;
+    throw wrapped;
+  }
+}
+
+// ── Pre-flight diagnostics ───────────────────────────────────────────────────
+
+/**
+ * Verify gcloud is installed, an account is active, and that account
+ * is on the required Workspace domain. Exits non-zero with a banner on
+ * any failure. Returns the active account email on success.
+ */
+export async function preFlight({ execGcloudFn = execGcloud } = {}) {
+  // (a) gcloud installed + an active account exists
+  let activeAccount;
+  try {
+    activeAccount = await execGcloudFn([
+      'auth',
+      'list',
+      '--filter=status:ACTIVE',
+      '--format=value(account)'
+    ]);
+  } catch (err) {
+    if (err.code === 'ENOENT' || /not found|not installed/i.test(err.stderr)) {
+      fail(
+        'gcloud CLI not found.',
+        'Install Google Cloud SDK: https://cloud.google.com/sdk/docs/install',
+        'Then run: gcloud auth login'
+      );
+    }
+    fail(`gcloud auth check failed: ${err.message}`, 'Try: gcloud auth login');
+  }
+
+  if (!activeAccount) {
+    fail(
+      'No active gcloud account.',
+      'Run: gcloud auth login',
+      `Then ensure your @${config.requiredDomain} account is the active one.`
+    );
+  }
+
+  // (b) active account must be on the required Workspace domain
+  if (!activeAccount.endsWith(`@${config.requiredDomain}`)) {
+    fail(
+      `Active gcloud account is "${activeAccount}" — must be an @${config.requiredDomain} account.`,
+      `Run: gcloud config set account <your-${config.requiredDomain}-email>`,
+      `(If you have not yet logged in with your ${config.requiredDomain} account:`,
+      `   gcloud auth login)`
+    );
+  }
+
+  log.info('Pre-flight OK', {
+    account: activeAccount,
+    audience: config.audience,
+    domain: config.requiredDomain
+  });
+  return activeAccount;
+}
+
+// ── Token cache + minting ────────────────────────────────────────────────────
+
+/**
+ * Internal token cache state. Exposed via a factory so tests can reset
+ * between cases.
+ */
+export function createTokenCache({
+  execGcloudFn = execGcloud,
+  audience = config.audience,
+  lifetimeMs = config.tokenLifetimeMs,
+  refreshBeforeMs = config.tokenRefreshBeforeMs,
+  now = () => Date.now()
+} = {}) {
+  let cachedToken = null;
+  let mintedAt = 0;
+
+  return {
+    /** Returns a fresh token, minting + caching as needed. */
+    async getToken() {
+      const t = now();
+      if (cachedToken && t - mintedAt < lifetimeMs - refreshBeforeMs) {
+        return cachedToken;
+      }
+
+      let token;
+      try {
+        token = await execGcloudFn([
+          'auth',
+          'print-identity-token',
+          `--audiences=${audience}`
+        ]);
+      } catch (err) {
+        log.error('Failed to mint identity token', {
+          error: err.message,
+          stderr: err.stderr
+        });
+        fail(
+          `Failed to mint Google ID token: ${err.message}`,
+          'Common causes:',
+          `  1. Expired credentials — run: gcloud auth login`,
+          `  2. Wrong active project — check: gcloud config get-value project`,
+          `  3. Missing --audiences support — older gcloud SDK; upgrade: gcloud components update`
+        );
+      }
+
+      cachedToken = token;
+      mintedAt = t;
+      log.info('Identity token minted', {
+        ttlMs: lifetimeMs,
+        nextRefreshInMs: lifetimeMs - refreshBeforeMs
+      });
+      return cachedToken;
+    },
+
+    /** Force-invalidate the cache (used after a 401 from the gateway). */
+    invalidate() {
+      cachedToken = null;
+      mintedAt = 0;
+    },
+
+    /** Test/diagnostic accessor. */
+    _state() {
+      return { cached: !!cachedToken, mintedAt };
+    }
+  };
+}
+
+// ── HTTP forwarder ───────────────────────────────────────────────────────────
+
+/**
+ * Forward a single JSON-RPC message to the gateway. Returns the parsed
+ * JSON-RPC response object. Handles 401/403 with diagnostic banners.
+ *
+ * Exported with injectable cache + httpRequest for testing.
+ */
+export async function forwardRequest(
+  message,
+  {
+    tokenCache,
+    httpRequestFn = httpsRequest,
+    gatewayUrl = config.gatewayUrl,
+    gatewayPath = config.gatewayPath,
+    requestTimeoutMs = config.requestTimeoutMs
+  }
+) {
+  if (!message || typeof message !== 'object') {
+    return {
+      jsonrpc: '2.0',
+      error: { code: -32600, message: 'Invalid Request' },
+      id: message?.id ?? null
+    };
+  }
+
+  const token = await tokenCache.getToken();
+  const messageStr = JSON.stringify(message);
+  const url = new URL(gatewayPath, gatewayUrl);
+
+  return new Promise((resolve) => {
+    const timeoutId = setTimeout(() => {
+      req.destroy();
+      log.warn('Request timeout', {
+        method: message.method,
+        id: message.id,
+        timeoutMs: requestTimeoutMs
+      });
+      resolve({
+        jsonrpc: '2.0',
+        error: {
+          code: -32000,
+          message: `Request timeout after ${requestTimeoutMs}ms`
+        },
+        id: message.id ?? null
+      });
+    }, requestTimeoutMs);
+
+    const options = {
+      hostname: url.hostname,
+      port: url.port || (url.protocol === 'https:' ? 443 : 80),
+      path: url.pathname,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(messageStr),
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json, text/event-stream',
+        'User-Agent': 'intelligence-mcp-bridge/1.0'
+      }
+    };
+
+    const req = httpRequestFn(options, (res) => {
+      let body = '';
+      res.on('data', (chunk) => {
+        body += chunk.toString();
+      });
+      res.on('end', () => {
+        clearTimeout(timeoutId);
+
+        // 401 — likely audience mismatch (Cloud Run rejected the token).
+        if (res.statusCode === 401) {
+          diagnosticBanner(
+            'gateway returned 401 — token audience likely mismatched',
+            `The gateway expects tokens whose "aud" claim matches a configured custom-audience.`,
+            `Confirm the service has https://mcp.hafla.com in customAudiences:`,
+            `  gcloud run services describe mcp-gateway --format='value(spec.template.metadata.annotations,spec.customAudiences)'`,
+            `If absent, the operator must redeploy with:`,
+            `  --add-custom-audiences=https://mcp.hafla.com`,
+            `Bridge will invalidate cached token and retry on the next request.`
+          );
+          tokenCache.invalidate();
+        }
+
+        // 403 employee_inactive — OpsUsers.isEmployeeActive=false.
+        if (res.statusCode === 403 && /employee_inactive/.test(body)) {
+          diagnosticBanner(
+            'gateway returned 403 employee_inactive',
+            `Your account is not flagged as an active Hafla employee in OpsUsers.`,
+            `Contact ops to verify your isEmployeeActive flag in haflaCore.OpsUsers.`
+          );
+        }
+
+        if (res.statusCode !== 200) {
+          log.warn('Gateway non-200', {
+            statusCode: res.statusCode,
+            id: message.id,
+            bodyPreview: body.slice(0, 200)
+          });
+          resolve({
+            jsonrpc: '2.0',
+            error: {
+              code: -32000,
+              message: `Gateway returned ${res.statusCode}`
+            },
+            id: message.id ?? null
+          });
+          return;
+        }
+
+        try {
+          resolve(JSON.parse(body));
+        } catch (e) {
+          log.error('Failed to parse gateway response', {
+            parseError: e.message,
+            id: message.id,
+            bodyLength: body.length
+          });
+          resolve({
+            jsonrpc: '2.0',
+            error: { code: -32700, message: 'Parse error' },
+            id: message.id ?? null
+          });
+        }
+      });
+    });
+
+    req.on('error', (err) => {
+      clearTimeout(timeoutId);
+      log.error('Gateway request failed', {
+        error: err.message,
+        code: err.code,
+        id: message.id,
+        host: url.hostname
+      });
+      resolve({
+        jsonrpc: '2.0',
+        error: {
+          code: -32603,
+          message: `Connection failed: ${err.code || err.message}`
+        },
+        id: message.id ?? null
+      });
+    });
+
+    req.write(messageStr);
+    req.end();
+  });
+}
+
+// ── Main pipeline (line-based stdio) ─────────────────────────────────────────
+
+async function main() {
+  await preFlight();
+  const tokenCache = createTokenCache();
+
+  log.info('intelligence-mcp-bridge started', {
+    gatewayUrl: config.gatewayUrl,
+    gatewayPath: config.gatewayPath,
+    audience: config.audience,
+    requestTimeoutMs: config.requestTimeoutMs
+  });
+
+  const lineSplitter = new Transform({
+    transform(chunk, encoding, callback) {
+      const str = (this.lastLine || '') + chunk.toString();
+      this.lastLine = '';
+      const lines = str.split('\n');
+      this.lastLine = lines.pop();
+      for (const line of lines) {
+        if (line.trim()) this.push(line + '\n');
+      }
+      callback();
+    },
+    flush(callback) {
+      if (this.lastLine?.trim()) {
+        this.push(this.lastLine + '\n');
+      }
+      callback();
+    }
+  });
+
+  const lineTransform = new Transform({
+    transform(chunk, encoding, callback) {
+      const line = chunk.toString();
+      if (!line.trim()) {
+        callback();
+        return;
+      }
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch (parseErr) {
+        log.error('Failed to parse stdin line', {
+          error: parseErr.message,
+          line: line.slice(0, 100)
+        });
+        const errorResponse = {
+          jsonrpc: '2.0',
+          error: { code: -32700, message: 'Parse error' },
+          id: null
+        };
+        callback(null, JSON.stringify(errorResponse) + '\n');
+        return;
+      }
+
+      forwardRequest(message, { tokenCache })
+        .then((response) => {
+          callback(null, JSON.stringify(response) + '\n');
+        })
+        .catch((err) => {
+          log.error('Unexpected forwardRequest error', { error: err.message });
+          callback(
+            null,
+            JSON.stringify({
+              jsonrpc: '2.0',
+              error: { code: -32603, message: 'Internal error' },
+              id: message.id ?? null
+            }) + '\n'
+          );
+        });
+    }
+  });
+
+  try {
+    await pipeline(process.stdin, lineSplitter, lineTransform, process.stdout);
+    log.info('Pipeline closed normally');
+    process.exit(0);
+  } catch (err) {
+    log.error('Pipeline error', { error: err.message });
+    process.exit(1);
+  }
+}
+
+// ── Graceful shutdown ────────────────────────────────────────────────────────
+
+process.on('SIGTERM', () => {
+  log.info('SIGTERM received');
+  process.exit(0);
+});
+process.on('SIGINT', () => {
+  log.info('SIGINT received');
+  process.exit(0);
+});
+
+// ── Execution guard — skip when imported as a module by tests ───────────────
+
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  try {
+    await main();
+  } catch (err) {
+    log.error('Uncaught error', { error: err.message, stack: err.stack });
+    process.exit(1);
+  }
+}