@ractive-ch/tab-mcp 0.1.0-alpha.1 → 0.2.0

package/index.js

@@ -38,6 +38,7 @@ function shortAddress(id) {
 }
 // src/config.ts
 var MIN_MESSAGE_BYTES = 16384;
+var MAX_PAGE_WAIT_MS = 60000;
 var MAX_APP_NAME = 64;
 var DEFAULT_CONFIG = {
   port: 8080,
@@ -59,6 +60,7 @@ var DEFAULT_CONFIG = {
   heartbeatMs: 25000,
   helloTimeoutMs: 1e4,
   bodyTimeoutMs: 1e4,
+  pageWaitMs: 1e4,
   maxMessageBytes: 1048576,
   accessTokenTtlMs: 3600000,
   refreshTokenTtlMs: 2592000000,
@@ -142,6 +144,9 @@ function resolveConfig(input = {}) {
       throw new ConfigError(`${key} must be a positive number`);
     }
   }
+  if (typeof config.pageWaitMs !== "number" || !Number.isFinite(config.pageWaitMs) || config.pageWaitMs < 0 || config.pageWaitMs > MAX_PAGE_WAIT_MS) {
+    throw new ConfigError(`pageWaitMs must be 0-${MAX_PAGE_WAIT_MS} (0-${MAX_PAGE_WAIT_MS / 1000} seconds)`);
+  }
   if (config.maxMessageBytes < MIN_MESSAGE_BYTES) {
     throw new ConfigError(`maxMessageBytes must be at least ${MIN_MESSAGE_BYTES} (16 KiB)`);
   }
@@ -265,6 +270,16 @@ function seconds(env, name) {
   }
   return Math.round(n * 1000);
 }
+function secondsOrZero(env, name) {
+  const raw = env[name];
+  if (raw === undefined || raw === "")
+    return;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) {
+    throw new ConfigError(`${name} must be 0 or a positive number of seconds`);
+  }
+  return Math.round(n * 1000);
+}
 function integer(env, name) {
   const raw = env[name];
   if (raw === undefined || raw === "")
@@ -341,6 +356,7 @@ function configFromEnv(env) {
   set("sessionLifetimeMs", seconds(env, "TAB_MCP_SESSION_LIFETIME_S"));
   set("heartbeatMs", seconds(env, "TAB_MCP_HEARTBEAT_S"));
   set("bodyTimeoutMs", seconds(env, "TAB_MCP_BODY_TIMEOUT_S"));
+  set("pageWaitMs", secondsOrZero(env, "TAB_MCP_PAGE_WAIT_S"));
   set("maxMessageBytes", integer(env, "TAB_MCP_MAX_MESSAGE_BYTES"));
   set("accessTokenTtlMs", seconds(env, "TAB_MCP_ACCESS_TOKEN_TTL_S"));
   set("refreshTokenTtlMs", seconds(env, "TAB_MCP_REFRESH_TOKEN_TTL_S"));
@@ -708,7 +724,7 @@ function parseTabMessage(text) {
   }
 }
 // package.json
-var version = "0.1.0-alpha.1";
+var version = "0.2.0";
 
 // src/exchange.ts
 var RelayErrorCode = {
@@ -866,6 +882,31 @@ class Exchange {
     this.#options.cancel("client_closed");
     this.#finish("client_closed", false);
   }
+  tabGone() {
+    if (this.#state === "done")
+      return;
+    const waiting = this.#state === "waiting";
+    const reply = this.#options.pageGone?.(waiting);
+    if (reply?.retry === true && waiting) {
+      clearTimeout(this.#startTimer);
+      this.#finish("page_gone_retry");
+      return;
+    }
+    const body = reply?.retry === false ? reply.body : undefined;
+    if (body === undefined) {
+      this.fail(503, RelayErrorCode.tabGone, "The page closed its connection to the relay.", false);
+      return;
+    }
+    if (waiting) {
+      this.#respond(new Response(body, {
+        status: 200,
+        headers: this.#headers({ "content-type": "application/json" })
+      }), 200);
+    } else if (this.#atBoundary) {
+      this.#write(sseEvent(body));
+    }
+    this.#finish("page_gone");
+  }
   fail(status, code, message, cancelTab) {
     if (this.#state === "done")
       return;
@@ -1004,6 +1045,67 @@ class Exchange {
   }
 }
 
+// src/notopen.ts
+var RETRYABLE = new Set(["tools/list"]);
+function isRetryable(method) {
+  return typeof method === "string" && RETRYABLE.has(method);
+}
+function pageName(appName) {
+  return appName ?? "the web page";
+}
+function notOpenText(appName) {
+  return `The page is not open, or not in front. Ask the user to open ${pageName(appName)} and keep it in front (on a phone, in split screen), then try again.`;
+}
+function goneDuringCallText(appName) {
+  return `The page closed while the tool was running, so it may or may not have finished. Ask the user to open ${pageName(appName)} and keep it in front (on a phone, in split screen), then check the result before trying again.`;
+}
+function notOpenAnswer(body, rpcId, appName, phase, relay) {
+  if (rpcId === undefined)
+    return;
+  const id = rpcId;
+  const method = body["method"];
+  if (method === "tools/call") {
+    const text = phase === "gone" ? goneDuringCallText(appName) : notOpenText(appName);
+    return JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      result: {
+        resultType: "complete",
+        content: [{ type: "text", text }],
+        isError: true
+      }
+    });
+  }
+  if (method === "server/discover") {
+    return JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      result: {
+        resultType: "complete",
+        supportedVersions: [MCP_PROTOCOL_VERSION],
+        capabilities: { tools: { listChanged: true } },
+        instructions: notOpenText(appName),
+        ttlMs: 0,
+        cacheScope: "private",
+        _meta: {
+          "io.modelcontextprotocol/serverInfo": {
+            name: relay.name,
+            version: relay.version
+          }
+        }
+      }
+    });
+  }
+  return JSON.stringify({
+    jsonrpc: "2.0",
+    id,
+    error: {
+      code: phase === "gone" ? RelayErrorCode.tabGone : RelayErrorCode.pageNotOpen,
+      message: notOpenText(appName)
+    }
+  });
+}
+
 // src/oauth/server.ts
 import { timingSafeEqual as timingSafeEqual2 } from "crypto";
 
@@ -1461,7 +1563,7 @@ function renderPage(title, body) {
 <body>
 <main>
 ${body}
-<footer>tab-mcp relay. It passes requests between AI tools and web pages and does not store their contents.</footer>
+<footer>tab-mcp relay. It passes requests between AI apps and web pages and does not store their contents.</footer>
 </main>
 </body>
 </html>`;
@@ -1562,7 +1664,7 @@ var MESSAGES = {
   wrong: "That code is not right. Check the code shown in the page and try again.",
   expired: "That code has expired. The page now shows a new code: enter that one.",
   locked: "Too many wrong codes. The page now shows a new code: enter that one.",
-  inactive: "The page is not showing a code right now. In the page, open \u201CConnect your AI tool\u201D to see one, then enter it here.",
+  inactive: "The page is not showing a code right now. In the page, open \u201CConnect your AI app\u201D to see one, then enter it here.",
   malformed: "Enter the 6 digits shown in the page.",
   limited: "Too many attempts for this page. Wait a few minutes and try again. If it keeps happening, someone else may be guessing: use \u201CNew address\u201D in the page."
 };
@@ -1571,7 +1673,7 @@ var codePairing = {
   render() {
     return `<p><label for="code">Code shown in the page</label>
 <input id="code" name="code" type="text" inputmode="numeric" autocomplete="one-time-code" pattern="[0-9 ]{6,7}" maxlength="7" required autofocus aria-describedby="code-help"></p>
-<p id="code-help" class="help">In the page, \u201CConnect your AI tool\u201D shows a 6-digit code. It changes every 2 minutes.</p>`;
+<p id="code-help" class="help">In the page, \u201CConnect your AI app\u201D shows a 6-digit code. It changes every 2 minutes.</p>`;
   },
   check(target, form, admit) {
     const result = target.codes.check(form.get("code") ?? "", Date.now(), admit);
@@ -1768,7 +1870,7 @@ class AuthorizationServer {
   #errorPage(status, message) {
     return this.#page(status, "This connection cannot be made", `<h1>This connection cannot be made</h1>
 <p role="alert">${escapeHtml(message)}</p>
-<p>Go back to your AI tool and try again. If it keeps happening, the AI tool may not work with this relay.</p>`);
+<p>Go back to your AI app and try again. If it keeps happening, the AI app may not work with this relay.</p>`);
   }
   #errorUrl(redirectUri, state, error, description) {
     const url = new URL(redirectUri);
@@ -1786,8 +1888,8 @@ class AuthorizationServer {
     const url = this.#errorUrl(redirectUri, state, error, description);
     const host = hostOf(redirectUri);
     return this.#page(400, "This connection cannot be made", `<h1>This connection cannot be made</h1>
-<p role="alert">The AI tool sent a request this relay cannot accept: ${escapeHtml(description)} (${escapeHtml(error)}).</p>
-<p>You can go back to the AI tool at ${escapeHtml(host)} to tell it, or close this page.</p>
+<p role="alert">The AI app sent a request this relay cannot accept: ${escapeHtml(description)} (${escapeHtml(error)}).</p>
+<p>You can go back to the AI app at ${escapeHtml(host)} to tell it, or close this page.</p>
 <div class="actions"><a class="button" href="${escapeHtml(url)}">Go back to ${escapeHtml(host)}</a></div>`);
   }
   #redirectError(redirectUri, state, error, description) {
@@ -1937,7 +2039,7 @@ class AuthorizationServer {
     const body = `<h1>Open the page first</h1>
 ${errorHtml}
 <p><strong>${escapeHtml(client.name)}</strong> (${escapeHtml(client.host)}) wants to use the tools of a web page, but that page is not open right now.</p>
-<p>Open the page, click \u201CConnect your AI tool\u201D, then try again here.</p>
+<p>Open the page, click \u201CConnect your AI app\u201D, then try again here.</p>
 <div class="actions">
 <a class="button primary" href="${escapeHtml(retryUrl)}">Try again</a>
 <a class="button" href="${escapeHtml(cancelUrl)}">Cancel</a>
@@ -1951,7 +2053,7 @@ ${errorHtml}
       return this.#errorPage(403, "This form can only be sent from this page.");
     }
     if (!this.#attemptsPerIp.take(ip)) {
-      return this.#errorPage(429, "Too many attempts from your network. Wait a few minutes, then start again from your AI tool.");
+      return this.#errorPage(429, "Too many attempts from your network. Wait a few minutes, then start again from your AI app.");
     }
     const type = (req.headers.get("content-type") ?? "").split(";")[0]?.trim();
     if (type !== "application/x-www-form-urlencoded") {
@@ -2090,7 +2192,7 @@ ${errorHtml}
       const body = `<h1>Open the page first</h1>
 ${errorHtml}
 <p>${clientLabel} wants to use the tools of a web page, but that page is not open right now.</p>
-<p>Open the page, click \u201CConnect your AI tool\u201D, then try again here.</p>
+<p>Open the page, click \u201CConnect your AI app\u201D, then try again here.</p>
 <form method="post" action="/authorize">
 ${hidden}
 <div class="actions">
@@ -2119,7 +2221,7 @@ ${method.render(session)}
 ${cancel}
 </div>
 </form>
-<p class="help">After you connect, your browser goes back to ${escapeHtml(hostOf(pending.redirectUri))}. Only connect AI tools you started yourself.</p>`;
+<p class="help">After you connect, your browser goes back to ${escapeHtml(hostOf(pending.redirectUri))}. Only connect AI apps you started yourself.</p>`;
     return this.#page(status, heading, body, targets, extra);
   }
   async token(req, ip) {
@@ -2669,6 +2771,7 @@ class TabSession {
       library: `${library.name}@${library.version}`,
       replaced: replaced !== undefined
     });
+    this.#host.ready?.(this);
   }
   #tick() {
     if (this.#state !== "ready")
@@ -2707,7 +2810,8 @@ class TabSession {
         this.pending.delete(id);
         this.#lastRequestAt = Date.now();
         input.onDone(e);
-      }
+      },
+      ...input.pageGone === undefined ? {} : { pageGone: input.pageGone }
     });
     this.pending.set(id, exchange);
     const sent = this.send({
@@ -2746,10 +2850,9 @@ class TabSession {
     clearTimeout(this.#helloTimer);
     clearInterval(this.#heartbeatTimer);
     clearTimeout(this.#lifetimeTimer);
-    for (const exchange of [...this.pending.values()]) {
-      exchange.fail(503, RelayErrorCode.tabGone, "The page closed its connection to the relay.", false);
-    }
     this.#host.released(this);
+    for (const exchange of [...this.pending.values()])
+      exchange.tabGone();
     if (wasReady) {
       this.#host.logger.info("tab.closed", {
         session: this.sessionId,
@@ -3001,6 +3104,8 @@ class SqliteTokenStore {
 
 // src/relay.ts
 var VERSION = version;
+var RELAY_INFO = { name: "tab-mcp", version };
+var RETRY = Symbol("retry");
 var CLAUDE_MISMATCHED_HEADER = "2025-11-25";
 var FORWARDED_HEADERS = new Set([
   "content-type",
@@ -3061,6 +3166,9 @@ function startRelay(options, hooks) {
   const sessions = new Map;
   const allSessions = new Set;
   const perIp = new Map;
+  const waiters = new Map;
+  let waitingCount = 0;
+  const appNames = new Map;
   let claudeWorkarounds = 0;
   let publicUrl = config.publicUrl ?? "";
   const corsHeaders = config.cors ? {
@@ -3124,8 +3232,68 @@ function startRelay(options, hooks) {
         sessions.delete(session.addressId);
       }
       releaseIp(session.ip);
+    },
+    ready(session) {
+      const id = session.addressId;
+      if (id === undefined)
+        return;
+      if (session.appName !== undefined) {
+        appNames.delete(id);
+        appNames.set(id, session.appName);
+        if (appNames.size > config.maxSessions * 2) {
+          const oldest = appNames.keys().next().value;
+          if (oldest !== undefined)
+            appNames.delete(oldest);
+        }
+      }
+      const waiting = waiters.get(id);
+      if (waiting !== undefined)
+        for (const wake of [...waiting])
+          wake(session);
     }
   };
+  function readySession(addressId) {
+    const s = sessions.get(addressId);
+    return s?.ready === true ? s : undefined;
+  }
+  function waitForPage(addressId, signal, waitMs) {
+    const now = readySession(addressId);
+    if (now !== undefined)
+      return Promise.resolve(now);
+    if (waitMs === 0 || stopping !== undefined) {
+      return Promise.resolve(undefined);
+    }
+    const set = waiters.get(addressId) ?? new Set;
+    if (set.size >= config.maxConcurrentRequests || waitingCount >= config.maxSessions) {
+      return Promise.resolve(undefined);
+    }
+    return new Promise((resolve) => {
+      let timer;
+      let settled = false;
+      const done = (result) => {
+        if (settled)
+          return;
+        settled = true;
+        clearTimeout(timer);
+        signal.removeEventListener("abort", onAbort);
+        set.delete(wake);
+        waitingCount--;
+        if (set.size === 0 && waiters.get(addressId) === set) {
+          waiters.delete(addressId);
+        }
+        resolve(result);
+      };
+      const wake = (session) => done(session);
+      const onAbort = () => done("aborted");
+      set.add(wake);
+      waiters.set(addressId, set);
+      waitingCount++;
+      timer = setTimeout(() => done(undefined), waitMs);
+      signal.addEventListener("abort", onAbort, { once: true });
+      if (signal.aborted)
+        onAbort();
+    });
+  }
   function releaseIp(ip) {
     const n = (perIp.get(ip) ?? 1) - 1;
     if (n <= 0)
@@ -3329,15 +3497,6 @@ function startRelay(options, hooks) {
         "www-authenticate": wwwAuthenticate(addressId, auth === "invalid")
       });
     }
-    const session = sessions.get(addressId);
-    if (session === undefined || !session.ready) {
-      logDone(503, method, { reason: "page_not_open" });
-      return rpcError(503, rpcId, RelayErrorCode.pageNotOpen, 'The page is not open. Open the web page that offers these tools and click "Connect your AI tool".', corsHeaders);
-    }
-    if (session.pending.size >= session.limits.maxConcurrentRequests) {
-      logDone(429, method);
-      return rpcError(429, rpcId, RelayErrorCode.overloaded, "Too many requests at once for this page.", corsHeaders);
-    }
     const headers = {};
     for (const [k, v] of req.headers) {
       const key = k.toLowerCase();
@@ -3352,33 +3511,89 @@ function startRelay(options, hooks) {
         return "";
       }
     })();
-    if (req.signal.aborted) {
+    const isListen = body.value["method"] === "subscriptions/listen";
+    const waitMs = body.value["method"] === "server/discover" || Buffer.byteLength(body.text) > MIN_MESSAGE_BYTES ? 0 : config.pageWaitMs;
+    const closed = () => {
       logDone(499, method, { outcome: "client_closed" });
       return new Response(null, { status: 499 });
+    };
+    if (readySession(addressId) === undefined && waitMs > 0) {
+      server.timeout(req, 0);
     }
-    server.timeout(req, 0);
-    const exchange = session.forward({
-      method: "POST",
-      headers,
-      body: body.text,
-      rpcId,
-      isListen: body.value["method"] === "subscriptions/listen",
-      grant: {
-        grantId: auth.grantId,
-        clientId: auth.clientId,
-        scopes: auth.scopes
-      },
-      extraHeaders: corsHeaders,
-      onDone: (e) => logDone(e.status, method, {
-        session: session.sessionId,
-        client: clientHostName,
-        outcome: e.outcome
-      })
-    });
-    req.signal.addEventListener("abort", () => exchange.clientClosed(), {
-      once: true
+    let retried = false;
+    for (;; ) {
+      const found = await waitForPage(addressId, req.signal, waitMs);
+      if (found === "aborted" || req.signal.aborted)
+        return closed();
+      if (found === undefined) {
+        return pageNotOpen(body.value, rpcId, addressId, logDone, method);
+      }
+      const session = found;
+      if (Buffer.byteLength(body.text) > session.limits.maxMessageBytes) {
+        logDone(413, method);
+        return rpcError(413, rpcId, -32600, "Request body too large.", corsHeaders);
+      }
+      if (session.pending.size >= session.limits.maxConcurrentRequests) {
+        logDone(429, method);
+        return rpcError(429, rpcId, RelayErrorCode.overloaded, "Too many requests at once for this page.", corsHeaders);
+      }
+      server.timeout(req, 0);
+      let retry = () => {};
+      const retrying = new Promise((resolve) => {
+        retry = () => resolve(RETRY);
+      });
+      const mayRetry = !retried && waitMs > 0 && isRetryable(body.value["method"]);
+      const exchange = session.forward({
+        method: "POST",
+        headers,
+        body: body.text,
+        rpcId,
+        isListen,
+        grant: {
+          grantId: auth.grantId,
+          clientId: auth.clientId,
+          scopes: auth.scopes
+        },
+        extraHeaders: corsHeaders,
+        onDone: (e) => {
+          if (e.outcome === "page_gone_retry")
+            return;
+          logDone(e.status, method, {
+            session: session.sessionId,
+            client: clientHostName,
+            outcome: e.outcome,
+            ...e.outcome === "page_gone" ? { reason: "page_not_open" } : {}
+          });
+        },
+        pageGone: (waiting) => {
+          if (waiting && mayRetry && !req.signal.aborted) {
+            retry();
+            return { retry: true };
+          }
+          const answer = notOpenAnswer(body.value, rpcId, session.appName, "gone", RELAY_INFO);
+          return answer === undefined ? { retry: false } : { retry: false, body: answer };
+        }
+      });
+      const onAbort = () => exchange.clientClosed();
+      req.signal.addEventListener("abort", onAbort, { once: true });
+      const result = await Promise.race([exchange.response, retrying]);
+      if (result !== RETRY)
+        return result;
+      req.signal.removeEventListener("abort", onAbort);
+      retried = true;
+    }
+  }
+  function pageNotOpen(value, rpcId, addressId, logDone, method) {
+    const answer = notOpenAnswer(value, rpcId, appNames.get(addressId), "not_open", RELAY_INFO);
+    if (answer === undefined) {
+      logDone(503, method, { reason: "page_not_open" });
+      return rpcError(503, rpcId, RelayErrorCode.pageNotOpen, "The page is not open.", corsHeaders);
+    }
+    logDone(200, method, { reason: "page_not_open" });
+    return new Response(answer, {
+      status: 200,
+      headers: { ...corsHeaders, "content-type": "application/json" }
     });
-    return exchange.response;
   }
   function preflight(req) {
     if (!config.cors)
@@ -3484,6 +3699,7 @@ function startRelay(options, hooks) {
       }
     }
   });
+  let stopping;
   const port = server.port ?? config.port;
   if (publicUrl === "")
     publicUrl = `http://localhost:${port}`;
@@ -3514,7 +3730,6 @@ function startRelay(options, hooks) {
     store: ownsStore ? config.store : "custom",
     origins: siteCount
   });
-  let stopping;
   return {
     url: publicUrl,
     port,
@@ -3526,6 +3741,10 @@ function startRelay(options, hooks) {
     stop() {
       stopping ??= (async () => {
         clearInterval(sweep);
+        for (const set of [...waiters.values()]) {
+          for (const wake of [...set])
+            wake(undefined);
+        }
         for (const session of [...allSessions]) {
           session.end(CloseCode.shuttingDown, "relay shutting down", "shutdown");
         }
@@ -3554,5 +3773,5 @@ export {
   resolveConfig
 };
 
-//# debugId=5AAD754DD6F4F7B264756E2164756E21
+//# debugId=50BF7EDE9EC7441F64756E2164756E21
 //# sourceMappingURL=index.js.map