granttap-mcp 0.8.59 → 0.8.61

package/apps/bridge/src/managed-admission/README.md

@@ -6,6 +6,10 @@ chooses the stable computer identity and enforces Personal seats; QR rooms and
 native agent sessions do not take additional seats. Own-relay connections never
 call billing. Tickets are transport headers and are not prompt content.
 
+The background monitor, MCP tool connection, desktop Task handoff, agent hooks
+and machine-role Mesh connections all use this entry point. Their leases renew
+on the existing socket; the provider conversation and task keys remain intact.
+
 Legacy free beta servers may not issue leases. Commercial relay mode requires
 a valid signed lease independently, including when a modified client omits it.
 Expiry/refund stops hosted delivery; local provider approval remains available,

package/apps/bridge/src/managed-admission/index.ts

@@ -3,10 +3,12 @@ import { loadAccountLink } from "../account-recovery/link";
 
 /** Account computer identity is stable across QR rooms and provider sessions. */
 export function managedAdmissionOptions(config: PeerConfig,
-  request: typeof fetch = fetch): Pick<RelayClientOptions, "upgradeHeaders"> {
+  request: typeof fetch = fetch): Pick<RelayClientOptions, "upgradeHeaders" | "connectionLeaseExpiresAt"> {
   const url = new URL(config.relayUrl);
   if (config.role !== "machine" || url.protocol !== "wss:" || url.hostname !== "relay.granttap.com") return {};
-  return { upgradeHeaders: async (): Promise<Record<string, string>> => {
+  let expiresAt: number | null = null;
+  return { connectionLeaseExpiresAt: () => expiresAt,
+    upgradeHeaders: async (): Promise<Record<string, string>> => {
     const account = loadAccountLink();
     if (!account) return {};
     const response = await request("https://granttap.com/api/account/machine/admission", {
@@ -25,6 +27,7 @@ export function managedAdmissionOptions(config: PeerConfig,
       || body.expiresAt <= Date.now() || body.expiresAt > Date.now() + 360_000) {
       throw new Error("Managed admission returned an invalid lease.");
     }
+    expiresAt = body.expiresAt;
     return { "X-GrantTap-Admission": body.ticket };
   } };
 }

package/apps/mcp/src/desktop/delivery/task-handoff.ts

@@ -7,12 +7,14 @@ import { observedComputerId } from "../../../../bridge/src/mesh/identity/compute
 import { prepareMeshHandoff } from "../../../../bridge/src/mesh/runtime";
 import { readStoreState } from "../../../../bridge/src/mesh/store/state";
 import { controllerPeerGate } from "../../../../bridge/src/pairing/controllers";
+import { managedAdmissionOptions } from "../../../../bridge/src/managed-admission";
 
 type Prepare = (request: HandoffRequest) => Promise<boolean>;
 
 async function prepareThroughRelay(request: HandoffRequest): Promise<boolean> {
   const config = applyNetworkRoute(loadConfig(machineConfigPath()));
-  const client = new RelayClient(config, { peerAllowed: controllerPeerGate(config) });
+  const client = new RelayClient(config, { ...managedAdmissionOptions(config),
+    peerAllowed: controllerPeerGate(config) });
   try {
     await client.connect();
     return await prepareMeshHandoff(client, request);

package/apps/mcp/src/mcp-tools/connect/relay.ts

@@ -14,6 +14,7 @@ import { completeEnrollment } from "../../connection-center/enrollment";
 import { confirmPendingController, controllerPeerGate } from "../../../../bridge/src/pairing/controllers";
 import { applyNetworkRoute } from "../../../../bridge/src/device-network/settings";
 import { startEndpointPublisher } from "../../../../bridge/src/device-network/directory";
+import { managedAdmissionOptions } from "../../../../bridge/src/managed-admission";
 
 const ASK_TIMEOUT_MS = Number(
   process.env.GRANTTAP_ASK_TIMEOUT_MS ?? process.env.NODVOX_ASK_TIMEOUT_MS ?? 180_000,
@@ -35,7 +36,8 @@ export async function relay(): Promise<RelayClient | null> {
   try {
     if (!client) {
       const config = applyNetworkRoute(loadConfig(machineConfigPath()));
-      client = new RelayClient(config, { autoReconnect: true, peerAllowed: controllerPeerGate(config) });
+      client = new RelayClient(config, { ...managedAdmissionOptions(config),
+        autoReconnect: true, peerAllowed: controllerPeerGate(config) });
       client.onMessage((payload, peerPublicKey) => {
         if (payload.type === "pairing.join") {
           const result = applyPairingJoin(payload);

package/apps/mcp/src/mcp-tools/mesh/relay.ts

@@ -6,6 +6,7 @@ import {
   loadGrokBotEndpoint,
 } from "../../../../bridge/src/mesh/identity/endpoint";
 import { localMeshStore } from "../../../../bridge/src/mesh/local-remote/local";
+import { managedAdmissionOptions } from "../../../../bridge/src/managed-admission";
 
 let client: RelayClient | null = null;
 let credentialId: string | null = null;
@@ -43,7 +44,7 @@ export async function grokBotRelay(): Promise<RelayClient> {
   });
   if (!client || credentialId !== bundle.credential.credentialId) {
     client?.close();
-    client = new RelayClient(bundle.pairing, { autoReconnect: true });
+    client = new RelayClient(bundle.pairing, { ...managedAdmissionOptions(bundle.pairing), autoReconnect: true });
     credentialId = bundle.credential.credentialId;
     client.onMessage(receive);
   }

package/cursor-plugin/README.md

@@ -10,7 +10,7 @@ keeps each phone response tied to the exact originating chat and prompt.
 Install the supported CLI on this computer, then run:
 
 ```bash
-npm install -g granttap-mcp@0.8.59
+npm install -g granttap-mcp@0.8.61
 granttap setup
 granttap status
 ```

package/cursor-plugin/mcp.json

@@ -4,7 +4,7 @@
       "command": "node",
       "args": [
         "-e",
-        "\"use strict\";\n\n// Cursor may start this MCP from any cwd. Execute JavaScript entry points with\n// Node itself: Windows batch shims require shell quoting that differs by host.\nconst { spawn } = require(\"node:child_process\");\nconst { existsSync } = require(\"node:fs\");\nconst { delimiter, dirname, join } = require(\"node:path\");\n\nconst PACKAGE = \"granttap-mcp@0.8.59\";\nconst dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === \"1\";\nconst platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM\n  ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;\nconst nodeRoot = dryRun && process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT\n  ? process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT : dirname(process.execPath);\nconst pathRoots = (process.env.PATH || \"\").split(delimiter).filter(Boolean);\nconst appData = process.env.APPDATA;\nconst roots = [nodeRoot, ...pathRoots, ...(appData ? [join(appData, \"npm\")] : [])];\nconst first = (paths) => paths.find((path) => existsSync(path));\n\nfunction launch() {\n  if (platform !== \"win32\") {\n    const installed = first(roots.map((root) => join(root, \"granttap-mcp\")));\n    if (installed) return { command: installed, args: [] };\n    const npx = first(roots.map((root) => join(root, \"npx\"))) || \"npx\";\n    return { command: npx, args: [\"-y\", PACKAGE] };\n  }\n  const installed = first(roots.map((root) =>\n    join(root, \"node_modules\", \"granttap-mcp\", \"bin\", \"granttap-mcp.mjs\")));\n  if (installed) return { command: process.execPath, args: [installed] };\n  const npx = first(roots.map((root) =>\n    join(root, \"node_modules\", \"npm\", \"bin\", \"npx-cli.js\")));\n  if (npx) return { command: process.execPath, args: [npx, \"-y\", PACKAGE] };\n  throw new Error(\"Node.js/npm 20+ is required on this Windows device. Install npm and retry GrantTap.\");\n}\n\nlet target;\ntry { target = launch(); }\ncatch (error) {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n}\n\nif (dryRun) {\n  process.stdout.write(JSON.stringify(target));\n  process.exit(0);\n}\n\nconst child = spawn(target.command, target.args, { stdio: \"inherit\", windowsHide: true });\nchild.on(\"error\", (error) => {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n});\nchild.on(\"exit\", (code, signal) => {\n  if (signal && platform !== \"win32\") {\n    try { process.kill(process.pid, signal); } catch { process.exit(code ?? 1); }\n    return;\n  }\n  process.exit(code ?? 1);\n});\n"
+        "\"use strict\";\n\n// Cursor may start this MCP from any cwd. Execute JavaScript entry points with\n// Node itself: Windows batch shims require shell quoting that differs by host.\nconst { spawn } = require(\"node:child_process\");\nconst { existsSync } = require(\"node:fs\");\nconst { delimiter, dirname, join } = require(\"node:path\");\n\nconst PACKAGE = \"granttap-mcp@0.8.61\";\nconst dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === \"1\";\nconst platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM\n  ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;\nconst nodeRoot = dryRun && process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT\n  ? process.env.GRANTTAP_BOOTSTRAP_NODE_ROOT : dirname(process.execPath);\nconst pathRoots = (process.env.PATH || \"\").split(delimiter).filter(Boolean);\nconst appData = process.env.APPDATA;\nconst roots = [nodeRoot, ...pathRoots, ...(appData ? [join(appData, \"npm\")] : [])];\nconst first = (paths) => paths.find((path) => existsSync(path));\n\nfunction launch() {\n  if (platform !== \"win32\") {\n    const installed = first(roots.map((root) => join(root, \"granttap-mcp\")));\n    if (installed) return { command: installed, args: [] };\n    const npx = first(roots.map((root) => join(root, \"npx\"))) || \"npx\";\n    return { command: npx, args: [\"-y\", PACKAGE] };\n  }\n  const installed = first(roots.map((root) =>\n    join(root, \"node_modules\", \"granttap-mcp\", \"bin\", \"granttap-mcp.mjs\")));\n  if (installed) return { command: process.execPath, args: [installed] };\n  const npx = first(roots.map((root) =>\n    join(root, \"node_modules\", \"npm\", \"bin\", \"npx-cli.js\")));\n  if (npx) return { command: process.execPath, args: [npx, \"-y\", PACKAGE] };\n  throw new Error(\"Node.js/npm 20+ is required on this Windows device. Install npm and retry GrantTap.\");\n}\n\nlet target;\ntry { target = launch(); }\ncatch (error) {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n}\n\nif (dryRun) {\n  process.stdout.write(JSON.stringify(target));\n  process.exit(0);\n}\n\nconst child = spawn(target.command, target.args, { stdio: \"inherit\", windowsHide: true });\nchild.on(\"error\", (error) => {\n  process.stderr.write(`[granttap] ${error.message}\\n`);\n  process.exit(1);\n});\nchild.on(\"exit\", (code, signal) => {\n  if (signal && platform !== \"win32\") {\n    try { process.kill(process.pid, signal); } catch { process.exit(code ?? 1); }\n    return;\n  }\n  process.exit(code ?? 1);\n});\n"
       ]
     }
   }

package/cursor-plugin/stdio-bootstrap.cjs

@@ -7,7 +7,7 @@ const { spawn } = require("node:child_process");
 const { existsSync } = require("node:fs");
 const { delimiter, dirname, join } = require("node:path");
 
-const PACKAGE = "granttap-mcp@0.8.59";
+const PACKAGE = "granttap-mcp@0.8.61";
 const dryRun = process.env.GRANTTAP_BOOTSTRAP_DRY_RUN === "1";
 const platform = dryRun && process.env.GRANTTAP_BOOTSTRAP_PLATFORM
   ? process.env.GRANTTAP_BOOTSTRAP_PLATFORM : process.platform;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "granttap-mcp",
-  "version": "0.8.59",
+  "version": "0.8.61",
   "description": "Personal live control center runtime for local coding agents on iPhone and Apple Watch.",
   "type": "module",
   "bin": {

package/packages/core/relay-client-types.ts

@@ -22,6 +22,8 @@ export type PeerConfig = {
 export type RelayClientOptions = {
   /** Fresh managed admission at each socket upgrade; own relays need no ticket. */
   upgradeHeaders?: () => Promise<Record<string, string>>;
+  /** Verified server lease deadline, refreshed without reconnecting the socket. */
+  connectionLeaseExpiresAt?: () => number | null;
   autoReconnect?: boolean;
   minReconnectMs?: number;
   maxReconnectMs?: number;

package/packages/core/relay-client.ts

@@ -10,6 +10,7 @@
  * the Cloudflare Durable Object deployment.
  */
 import WebSocket from "ws";
+import { ManagedRelayLease, RelaySocketHealth } from "./socket-lifecycle";
 import { OutboundFrameQueue, sendEncryptedPayload } from "./outbound-scheduler";
 import { createHash } from "node:crypto";
 import { Envelope, Payload, type Role } from "../protocol/schema";
@@ -31,8 +32,8 @@ export class RelayClient {
   private connectPromise?: Promise<void>;
   private reconnectTimer?: NodeJS.Timeout;
   private reconnectDelay: number;
-  private livenessTimer?: NodeJS.Timeout;
-  private awaitingPong = false;
+  private readonly socketHealth = new RelaySocketHealth();
+  private readonly admissionLease = new ManagedRelayLease();
   private readonly sessionKeys = new Map<string, string>();
   /**
    * Delivery ids are relay-controlled metadata, so replay protection is bound
@@ -96,14 +97,12 @@ export class RelayClient {
         reject(new Error(`relay connect timeout (${this.cfg.relayUrl})`));
       }, timeoutMs);
 
-      ws.on("pong", () => {
-        if (this.ws === ws) this.awaitingPong = false;
-      });
       ws.on("open", () => {
         opened = true;
         clearTimeout(timer);
         this.reconnectDelay = this.opts.minReconnectMs ?? 1_000;
-        this.startLivenessChecks(ws);
+        this.socketHealth.start(ws, this.opts.pingIntervalMs ?? 20_000);
+        this.admissionLease.start(ws, this.opts);
         // Announce ourselves. The envelope's cleartext (room, from) is what the
         // relay uses to register this socket; the Hello body stays encrypted.
         void this
@@ -122,7 +121,8 @@ export class RelayClient {
       ws.on("close", () => {
         frames.cancel();
         clearTimeout(timer);
-        this.stopLivenessChecks();
+        this.socketHealth.stop(ws);
+        this.admissionLease.stop(ws);
         if (this.ws === ws) this.ws = undefined;
         if (!opened) reject(new Error(`relay connection closed (${this.cfg.relayUrl})`));
         this.scheduleReconnect();
@@ -317,7 +317,8 @@ export class RelayClient {
 
   close(): void {
     this.frames?.cancel();
-    this.stopLivenessChecks();
+    this.socketHealth.stop();
+    this.admissionLease.stop();
     this.intentionalClose = true;
     if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
     this.reconnectTimer = undefined;
@@ -329,48 +330,6 @@ export class RelayClient {
     return this.ws?.readyState === WebSocket.OPEN;
   }
 
-  /**
-   * Prove the socket is still there, rather than trusting `readyState`.
-   *
-   * A machine that changes network — joining a hotspot, waking on another
-   * Wi-Fi — leaves its relay socket half-open. No close event arrives, so
-   * nothing reconnects, and the computer keeps reporting itself as connected
-   * while everything it sends goes nowhere. A ping with a deadline is the only
-   * thing that tells the two apart.
-   */
-  private startLivenessChecks(ws: WebSocket): void {
-    this.stopLivenessChecks();
-    const interval = this.opts.pingIntervalMs ?? 20_000;
-    this.awaitingPong = false;
-    this.livenessTimer = setInterval(() => {
-      if (this.ws !== ws || ws.readyState !== WebSocket.OPEN) {
-        this.stopLivenessChecks();
-        return;
-      }
-      if (this.awaitingPong) {
-        // The previous ping was never answered. Terminating fires `close`,
-        // which is what schedules the reconnect.
-        this.stopLivenessChecks();
-        ws.terminate();
-        return;
-      }
-      this.awaitingPong = true;
-      try {
-        ws.ping();
-      } catch {
-        this.stopLivenessChecks();
-        ws.terminate();
-      }
-    }, interval);
-    this.livenessTimer.unref?.();
-  }
-
-  private stopLivenessChecks(): void {
-    if (this.livenessTimer) clearInterval(this.livenessTimer);
-    this.livenessTimer = undefined;
-    this.awaitingPong = false;
-  }
-
   private scheduleReconnect(): void {
     if (!this.opts.autoReconnect || this.intentionalClose || this.reconnectTimer) return;
     const delay = this.reconnectDelay;

package/packages/core/socket-lifecycle/README.md

@@ -0,0 +1,11 @@
+# Relay socket lifecycle
+
+Public entry point: `index.ts`. `RelayClient` uses this module for network health
+and short managed admission leases. Admission refresh stays on the existing
+socket and does not rotate task keys or reload transcript state. A failed lookup
+cannot extend the server's signed expiry. Closing or replacing a socket cancels
+only its own timers.
+
+The real WebSocket integration is in `tests/core/managed-relay-renewal.test.ts`.
+
+Licensed under the MIT License in the repository root.

package/packages/core/socket-lifecycle/index.ts

@@ -0,0 +1,2 @@
+export { ManagedRelayLease } from "./managed-relay-lease";
+export { RelaySocketHealth } from "./relay-socket-health";

package/packages/core/socket-lifecycle/managed-relay-lease.ts

@@ -0,0 +1,49 @@
+import WebSocket from "ws";
+import type { RelayClientOptions } from "../relay-client-types";
+
+/** Renew a computer's signed admission on its existing socket; no chat keys change. */
+export class ManagedRelayLease {
+  private socket?: WebSocket;
+  private timer?: NodeJS.Timeout;
+
+  start(socket: WebSocket, options: RelayClientOptions): void {
+    this.stop();
+    this.socket = socket;
+    socket.once("close", () => this.stop(socket));
+    this.schedule(socket, options);
+  }
+
+  stop(socket?: WebSocket): void {
+    if (socket && this.socket !== socket) return;
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = undefined;
+    this.socket = undefined;
+  }
+
+  private schedule(socket: WebSocket, options: RelayClientOptions, retry = false): void {
+    const expiry = options.connectionLeaseExpiresAt?.();
+    if (!expiry || !Number.isFinite(expiry) || !options.upgradeHeaders) return;
+    const remaining = expiry - Date.now();
+    const margin = Math.min(30_000, Math.max(10, remaining * 0.15));
+    const delay = retry ? 10_000 : Math.max(10, remaining - margin);
+    this.timer = setTimeout(() => void this.renew(socket, options), delay);
+    this.timer.unref();
+  }
+
+  private async renew(socket: WebSocket, options: RelayClientOptions): Promise<void> {
+    this.timer = undefined;
+    if (this.socket !== socket || socket.readyState !== WebSocket.OPEN) return;
+    try {
+      const headers = await options.upgradeHeaders!();
+      if (this.socket !== socket || socket.readyState !== WebSocket.OPEN) return;
+      const ticket = headers["X-GrantTap-Admission"];
+      if (!ticket) throw new Error("No refreshed relay admission");
+      await new Promise<void>((resolve, reject) => socket.send(
+        JSON.stringify({ type: "relay.admission", ticket }), error => error ? reject(error) : resolve()));
+      this.schedule(socket, options);
+    } catch {
+      // The relay's signed expiry remains authoritative; a failed lookup cannot extend it.
+      if (this.socket === socket && socket.readyState === WebSocket.OPEN) this.schedule(socket, options, true);
+    }
+  }
+}

package/packages/core/socket-lifecycle/relay-socket-health.ts

@@ -0,0 +1,31 @@
+import WebSocket from "ws";
+
+/** Detect half-open network sockets independently of managed authorization. */
+export class RelaySocketHealth {
+  private socket?: WebSocket;
+  private timer?: NodeJS.Timeout;
+  private awaitingPong = false;
+
+  start(socket: WebSocket, interval: number): void {
+    this.stop();
+    this.socket = socket;
+    socket.on("pong", () => { if (this.socket === socket) this.awaitingPong = false; });
+    this.timer = setInterval(() => {
+      if (this.socket !== socket || socket.readyState !== WebSocket.OPEN) { this.stop(socket); return; }
+      if (this.awaitingPong) { this.stop(socket); socket.terminate(); return; }
+      this.awaitingPong = true;
+      try { socket.ping(); }
+      catch { this.stop(socket); socket.terminate(); }
+    }, interval);
+    this.timer.unref();
+    socket.once("close", () => this.stop(socket));
+  }
+
+  stop(socket?: WebSocket): void {
+    if (socket && this.socket !== socket) return;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+    this.socket = undefined;
+    this.awaitingPong = false;
+  }
+}