granttap-mcp 0.8.18 → 0.8.19

package/README.md

@@ -185,6 +185,14 @@ and from then on that computer takes part in the mesh like any other: its
 chats are the Project's, its claims are seen by every other computer, and a
 Task can be handed to it.
 
+A Project can pin new tasks to one confirmed computer. The endpoint id is
+the stored computer identity, not the display name. Models offered on the
+phone come from that host's catalog. If the pinned host is offline, the
+Project either refuses the create or queues it until a deadline — it does
+not silently start the task elsewhere. A command issued for a previous
+instance of the computer (a restore or clone that kept pairing keys) is
+rejected. A pin is not a secure VM.
+
 ### A claim released by the person
 
 A claim outlives an agent that crashed or was closed, and the files it names
@@ -247,16 +255,20 @@ grok plugin install granttap --trust
 ```
 
 For Cursor, use the reviewed **GrantTap** Marketplace listing when it is visible
-to your account, or import the public `sergii-ziborov/granttap-mcp` repository
-once. Reload Cursor, then open
-**Cursor Customize → MCPs → GrantTap → Authenticate**. Complete authorization
-and any one-time QR pairing on `https://granttap.com/connect`.
-
-Open GrantTap from the plugin page or ask `Show my GrantTap pairing QR.` Codex
-renders an interactive connection card with pairing status, a one-time QR,
-copy-link fallback, and confirmed reconnect controls. The same tools still
-return readable MCP content in clients that do not render app UI. Detailed
-plugin instructions are in
+to your account. Reload Cursor. On this computer, run `granttap setup`. Pair
+and change settings on [granttap.com/connect](https://granttap.com/connect)
+and in the GrantTap app. Authenticate opens that page even when this Mac is
+already paired — Approve the coding app, Reconnect, or Add another. A scan in
+GrantTap authorizes a new device; a saved pairing does not skip the page.
+Do not add GrantTap in Cursor Customize → MCPs. Cloud **Error · fetch
+failed** is leftover HTTP at `http://127.0.0.1:17342/mcp` — a user MCP row
+or an old plugin `mcp.json`. The Cursor plugin is stdio (`node -e`).
+
+Open GrantTap from the plugin connection card. Pairing status, a one-time QR
+when needed, and confirmed reconnect stay on that card, on
+`granttap.com/connect`, and in the GrantTap app. Do not ask an agent to print
+a pairing QR in chat. The same tools still return readable MCP content in
+clients that do not render app UI. Detailed plugin instructions are in
 [`plugins/granttap/README.md`](plugins/granttap/README.md).
 
 For the full background helper and provider hooks, install the CLI and run
@@ -268,8 +280,8 @@ granttap setup
 ```
 
 `granttap setup` detects supported local agents, installs or repairs their
-hooks, installs the background helper, configures Cursor's persistent local
-OAuth service when Cursor is present, and starts phone pairing when run in an
+hooks, installs the background helper, removes a leftover user GrantTap MCP
+entry when Cursor is present, and starts phone pairing when run in an
 interactive terminal. It ends with one exact next action.
 
 Setup also declares the separately distributed GrantTap Engine, which Project

package/apps/bridge/src/approvals/api.ts

@@ -0,0 +1,306 @@
+import { randomUUID } from "node:crypto";
+import type { RelayClient } from "../../../../packages/core/relay-client";
+import {
+  approvalAction,
+  type ApprovalDecision,
+  type ApprovalRequest,
+  type ApprovalResolved,
+  type ApprovalsStatus,
+} from "../../../../packages/protocol/schema";
+import {
+  MAX_PENDING_AGE_MS,
+  MAX_RECORDS,
+  TERMINAL_RETENTION_MS,
+  claimApprovalWinner,
+  effectiveFingerprint,
+  matchesRegistration,
+  normalizedSessionId,
+  pruneRecords,
+  readRawRecord,
+  readRecordPath,
+  recordFiles,
+  recordOutcome,
+  recordWinner,
+  registrationHandle,
+  requestDigest,
+  requestFingerprint,
+  terminalApproval,
+  writeRecord,
+  type ApprovalAcceptance,
+  type ApprovalOutcome,
+  type ApprovalRecord,
+  type ApprovalRegistration,
+  type ApprovalRegistrationHandle,
+  type ApprovalTerminalState,
+  type PendingApprovalRegistration,
+} from "./records";
+
+export function registerPendingApproval(
+  request: ApprovalRequest,
+  now = Date.now(),
+): ApprovalRegistration {
+  const fingerprint = requestFingerprint(request);
+  const existing = readRawRecord(request.requestId);
+  const existingWinner = existing ? recordWinner(existing) : null;
+  const effectiveAt = existingWinner?.acceptedAt ?? existing?.updatedAt;
+  if (existing && effectiveAt != null && now - effectiveAt <= TERMINAL_RETENTION_MS) {
+    if (effectiveFingerprint(existing) !== fingerprint) {
+      return {
+        matched: false,
+        newlyRegistered: false,
+        reason: "conflicting_request",
+      };
+    }
+    return {
+      matched: true,
+      newlyRegistered: false,
+      handle: registrationHandle(existing),
+    };
+  }
+  const record: ApprovalRecord = {
+    request,
+    state: "pending",
+    updatedAt: now,
+    generation: randomUUID(),
+    fingerprint,
+  };
+  writeRecord(record);
+  return {
+    matched: true,
+    newlyRegistered: true,
+    handle: registrationHandle(record),
+  };
+}
+
+export function acceptApprovalDecision(
+  decision: ApprovalDecision,
+  now = Date.now(),
+  expectedRegistration?: ApprovalRegistrationHandle,
+): ApprovalAcceptance {
+  const record = readRawRecord(decision.requestId);
+  if (!record || !matchesRegistration(record, expectedRegistration)) {
+    return { matched: false, newlyResolved: false };
+  }
+  const requestSessionId = normalizedSessionId(record.request.sessionId);
+  const decisionSessionId = normalizedSessionId(decision.sessionId);
+  if (requestSessionId !== decisionSessionId) {
+    return { matched: false, newlyResolved: false };
+  }
+  const existingOutcome = recordOutcome(record);
+  if (existingOutcome) return acceptance(record, existingOutcome, false);
+  if (record.state !== "pending") return { matched: false, newlyResolved: false };
+  if (now - record.updatedAt > MAX_PENDING_AGE_MS) {
+    return markApprovalTerminal(
+      decision.requestId,
+      "expired",
+      {
+        decision: "deny",
+        decidedBy: "system",
+        note: "Approval request expired before the decision arrived",
+        sessionId: requestSessionId,
+      },
+      now,
+      expectedRegistration,
+    );
+  }
+  const storedDecision: ApprovalDecision = {
+    ...decision,
+    sessionId: requestSessionId,
+    decidedAt: decision.decidedAt || now,
+  };
+  const outcome: ApprovalOutcome = { kind: "decision", decision: storedDecision };
+  const claim = claimApprovalWinner(record, outcome, now);
+  if (!claim.winner) {
+    // A corrupt/unreadable winner is fail-closed: do not ACK either contender.
+    return { matched: false, newlyResolved: false };
+  }
+  if (!claim.won) {
+    return acceptance(record, claim.winner.outcome, false);
+  }
+  return acceptance(record, claim.winner.outcome, true);
+}
+
+function acceptance(
+  record: ApprovalRecord,
+  outcome: ApprovalOutcome,
+  newlyResolved: boolean,
+): ApprovalAcceptance {
+  return {
+    matched: true,
+    newlyResolved,
+    request: record.request,
+    outcome,
+    decision: outcome.kind === "decision" ? outcome.decision : undefined,
+  };
+}
+
+/** Read the exact-scope outcome durably accepted by another process. */
+export function resolvedApprovalOutcome(
+  requestId: string,
+  expectedSessionId: string | null | undefined,
+  expectedRegistration?: ApprovalRegistrationHandle,
+): ApprovalOutcome | null {
+  const record = readRawRecord(requestId);
+  if (
+    !record ||
+    normalizedSessionId(record.request.sessionId) !== normalizedSessionId(expectedSessionId) ||
+    !matchesRegistration(record, expectedRegistration)
+  ) {
+    return null;
+  }
+  return recordOutcome(record);
+}
+
+/** Read a decision only when the current request generation and exact scope match. */
+export function resolvedApprovalDecision(
+  requestId: string,
+  expectedSessionId: string | null | undefined,
+  expectedRegistration?: ApprovalRegistrationHandle,
+): ApprovalDecision | null {
+  const outcome = resolvedApprovalOutcome(
+    requestId,
+    expectedSessionId,
+    expectedRegistration,
+  );
+  return outcome?.kind === "decision" ? outcome.decision : null;
+}
+
+export function markApprovalTerminal(
+  requestId: string,
+  state: ApprovalTerminalState,
+  options: {
+    decision?: ApprovalDecision["decision"] | null;
+    decidedBy?: string | null;
+    note?: string | null;
+    sessionId?: string | null;
+    resolvedAt?: number;
+  } = {},
+  now = Date.now(),
+  expectedRegistration?: ApprovalRegistrationHandle,
+): ApprovalAcceptance {
+  const record = readRawRecord(requestId);
+  if (!record || !matchesRegistration(record, expectedRegistration)) {
+    return { matched: false, newlyResolved: false };
+  }
+  const requestSessionId = normalizedSessionId(record.request.sessionId);
+  if (requestSessionId !== normalizedSessionId(options.sessionId)) {
+    return { matched: false, newlyResolved: false };
+  }
+  const existingOutcome = recordOutcome(record);
+  if (existingOutcome) return acceptance(record, existingOutcome, false);
+  if (record.state !== "pending") return { matched: false, newlyResolved: false };
+  const resolved = terminalApproval(requestId, state, {
+    ...options,
+    sessionId: requestSessionId,
+    resolvedAt: options.resolvedAt ?? now,
+  });
+  const outcome: ApprovalOutcome = { kind: "terminal", status: state, resolved };
+  const claim = claimApprovalWinner(record, outcome, now);
+  if (!claim.winner) return { matched: false, newlyResolved: false };
+  if (!claim.won) return acceptance(record, claim.winner.outcome, false);
+  return acceptance(record, claim.winner.outcome, true);
+}
+
+export function pendingApprovalRegistrations(
+  now = Date.now(),
+): PendingApprovalRegistration[] {
+  return recordFiles()
+    .map(readRecordPath)
+    .filter((record): record is ApprovalRecord =>
+      record != null &&
+      record.state === "pending" &&
+      now - record.updatedAt <= MAX_PENDING_AGE_MS &&
+      recordWinner(record) == null,
+    )
+    .sort((a, b) => b.updatedAt - a.updatedAt)
+    .slice(0, 100)
+    .map((record) => ({
+      request: record.request,
+      handle: registrationHandle(record),
+    }));
+}
+
+/** Compatibility wrapper for callers that only render pending requests. */
+export function pendingApprovalRequests(now = Date.now()): ApprovalRequest[] {
+  return pendingApprovalRegistrations(now).map((item) => item.request);
+}
+
+function approvalScopeKey(request: Pick<ApprovalRequest, "requestId" | "sessionId">): string {
+  return `${request.requestId}\u0000${normalizedSessionId(request.sessionId) ?? ""}`;
+}
+
+function coveredApprovalScopes(
+  pending: ApprovalRequest[],
+  now: number,
+): Array<{ requestId: string; sessionId?: string }> {
+  const includedPending = new Set(pending.map(approvalScopeKey));
+  const covered = new Map<string, { requestId: string; sessionId?: string }>();
+  for (const path of recordFiles()) {
+    const record = readRecordPath(path);
+    if (!record) continue;
+    const winner = recordWinner(record);
+    if (now - (winner?.acceptedAt ?? record.updatedAt) > TERMINAL_RETENTION_MS) continue;
+    const isLivePending =
+      record.state === "pending" &&
+      winner == null &&
+      now - record.updatedAt <= MAX_PENDING_AGE_MS;
+    // Never claim an omitted live request as closed when the wire cap is hit.
+    if (isLivePending && !includedPending.has(approvalScopeKey(record.request))) continue;
+    const scope = {
+      requestId: record.request.requestId,
+      sessionId: normalizedSessionId(record.request.sessionId),
+    };
+    covered.set(approvalScopeKey(record.request), scope);
+  }
+  return [...covered.values()].slice(0, MAX_RECORDS);
+}
+
+let lastStatusGeneratedAt = 0;
+
+export function approvalsStatus(now = Date.now()): ApprovalsStatus {
+  pruneRecords(now);
+  const pending = pendingApprovalRequests(now);
+  const generatedAt = Math.max(Math.trunc(now), lastStatusGeneratedAt + 1);
+  lastStatusGeneratedAt = generatedAt;
+  return {
+    type: "approvals.status",
+    pending,
+    complete: false,
+    covered: coveredApprovalScopes(pending, now),
+    actions: pending.map(approvalAction),
+    generatedAt,
+  };
+}
+
+export function resolvedFromDecision(
+  decision: ApprovalDecision,
+  request?: ApprovalRequest,
+): ApprovalResolved {
+  return terminalApproval(decision.requestId, "applied", {
+    decision: decision.decision,
+    decidedBy: decision.decidedBy,
+    note: decision.note,
+    sessionId: request?.sessionId ?? decision.sessionId,
+    resolvedAt: decision.decidedAt,
+  });
+}
+
+export function resolvedFromOutcome(
+  outcome: ApprovalOutcome,
+  request?: ApprovalRequest,
+): ApprovalResolved {
+  return outcome.kind === "decision"
+    ? resolvedFromDecision(outcome.decision, request)
+    : outcome.resolved;
+}
+
+export async function sendApprovalResolved(
+  client: RelayClient,
+  payload: ApprovalResolved,
+): Promise<void> {
+  await client.send(payload, "phone", {
+    ttlMs: 15 * 60_000,
+    wake: false,
+    deliveryId: `approval-resolved-${requestDigest(payload.requestId)}`,
+  });
+}

package/apps/bridge/src/{approval.ts → approvals/index.ts}

@@ -5,9 +5,9 @@
  * replies with a matching ApprovalDecision (or the timeout fires — fail closed,
  * i.e. deny). This is what makes a phone tap gate a real tool call.
  */
-import type { PeerConfig } from "../../../packages/core/relay-client";
-import { RelayClient } from "../../../packages/core/relay-client";
-import type { ApprovalDecision, ApprovalRequest, Payload } from "../../../packages/protocol/schema";
+import type { PeerConfig } from "../../../../packages/core/relay-client";
+import { RelayClient } from "../../../../packages/core/relay-client";
+import type { ApprovalDecision, ApprovalRequest, Payload } from "../../../../packages/protocol/schema";
 import {
   acceptApprovalDecision,
   markApprovalTerminal,
@@ -16,8 +16,9 @@ import {
   resolvedFromOutcome,
   sendApprovalResolved,
   type ApprovalOutcome,
-} from "./approval-state";
-import { primeSessionKeys, sendSessionPayload } from "./session-keys";
+  type ApprovalRegistrationHandle,
+} from "./state";
+import { primeSessionKeys, sendSessionPayload } from "../host/session-keys";
 
 /**
  * Nobody answered — relay unreachable, or the phone never responded before the
@@ -77,7 +78,72 @@ export async function requestApproval(
             };
       }
     }
-    const decisionP = new Promise<ApprovalDecision | null>((resolve) => {
+    const waiting = waitForDecision(client, req, timeoutMs, registrationHandle);
+    cancelDecisionWait = waiting.cancel;
+    await sendRequest(client, req, timeoutMs);
+    const decision = await waiting.promise;
+
+    if (decision) return decision;
+    // `expired`, not `system`: nobody denied anything — the phone was asleep,
+    // offline, or the app was killed. Hooks hand `expired` back to the agent's
+    // own permission prompt. Reporting it as a plain deny bricks the agent:
+    // every tool call stalls for the full timeout and then fails.
+    const expired = markApprovalTerminal(req.requestId, "expired", {
+      decision: "deny",
+      decidedBy: "expired",
+      note: "No response from phone before timeout",
+      sessionId: req.sessionId,
+    }, Date.now(), registrationHandle);
+    if (!expired.outcome) {
+      return {
+        ...failClosed(req, "No response from phone before timeout"),
+        decidedBy: "expired",
+      };
+    }
+    await sendApprovalResolved(
+      client,
+      resolvedFromOutcome(expired.outcome, expired.request),
+    ).catch(() => {});
+    return decisionFromOutcome(expired.outcome, req);
+  } catch (err) {
+    // Transport blew up mid-flight (socket dropped, peer never attached). Like a
+    // failed connect this is `unreachable`: no human ever saw the request.
+    const expired = markApprovalTerminal(req.requestId, "expired", {
+      decision: "deny",
+      decidedBy: "unreachable",
+      note: "Approval channel error",
+      sessionId: req.sessionId,
+    }, Date.now(), registrationHandle);
+    if (!expired.outcome) {
+      return {
+        ...failClosed(req, `Approval channel error: ${(err as Error).message}`),
+        decidedBy: "unreachable",
+      };
+    }
+    await sendApprovalResolved(
+      client,
+      resolvedFromOutcome(expired.outcome, expired.request),
+    ).catch(() => {});
+    return decisionFromOutcome(expired.outcome, req);
+  } finally {
+    cancelDecisionWait();
+    if (ownsClient) client.close();
+  }
+}
+
+async function sendRequest(client: RelayClient, req: ApprovalRequest, timeoutMs: number): Promise<void> {
+  // The id carries no task content and lets APNs answer before iOS decrypts the card.
+  const options = { ttlMs: timeoutMs, wake: true, deliveryId: req.requestId };
+  if (req.sessionId) await sendSessionPayload(client, req, req.sessionId, "phone", options);
+  else await client.send(req, "phone", options);
+}
+
+function waitForDecision(
+  client: RelayClient, req: ApprovalRequest, timeoutMs: number,
+  registrationHandle?: ApprovalRegistrationHandle,
+): { promise: Promise<ApprovalDecision | null>; cancel: () => void } {
+  let cancel = () => {};
+  const promise = new Promise<ApprovalDecision | null>((resolve) => {
       let settled = false;
       let durablePoll: NodeJS.Timeout | undefined;
       let off = () => {};
@@ -89,7 +155,7 @@ export async function requestApproval(
         off();
         resolve(decision);
       };
-      cancelDecisionWait = () => finish(null);
+      cancel = () => finish(null);
       const timer = setTimeout(() => finish(null), timeoutMs);
       // The long-running desktop monitor may receive and durably accept the
       // same relay envelope first. Poll the shared registry so this one-shot
@@ -127,67 +193,7 @@ export async function requestApproval(
         return terminalSent;
       });
     });
-    // The request id is random and carries no task content. Reusing it as the
-    // opaque delivery id lets a generic APNs action answer the request even if
-    // iOS has not yet pulled and decrypted the full card.
-    const sendOptions = {
-      ttlMs: timeoutMs,
-      wake: true,
-      deliveryId: req.requestId,
-    };
-    if (req.sessionId) {
-      await sendSessionPayload(client, req, req.sessionId, "phone", sendOptions);
-    } else {
-      await client.send(req, "phone", sendOptions);
-    }
-    const decision = await decisionP;
-
-    if (decision) return decision;
-    // `expired`, not `system`: nobody denied anything — the phone was asleep,
-    // offline, or the app was killed. Hooks hand `expired` back to the agent's
-    // own permission prompt. Reporting it as a plain deny bricks the agent:
-    // every tool call stalls for the full timeout and then fails.
-    const expired = markApprovalTerminal(req.requestId, "expired", {
-      decision: "deny",
-      decidedBy: "expired",
-      note: "No response from phone before timeout",
-      sessionId: req.sessionId,
-    }, Date.now(), registrationHandle);
-    if (!expired.outcome) {
-      return {
-        ...failClosed(req, "No response from phone before timeout"),
-        decidedBy: "expired",
-      };
-    }
-    await sendApprovalResolved(
-      client,
-      resolvedFromOutcome(expired.outcome, expired.request),
-    ).catch(() => {});
-    return decisionFromOutcome(expired.outcome, req);
-  } catch (err) {
-    // Transport blew up mid-flight (socket dropped, peer never attached). Like a
-    // failed connect this is `unreachable`: no human ever saw the request.
-    const expired = markApprovalTerminal(req.requestId, "expired", {
-      decision: "deny",
-      decidedBy: "unreachable",
-      note: "Approval channel error",
-      sessionId: req.sessionId,
-    }, Date.now(), registrationHandle);
-    if (!expired.outcome) {
-      return {
-        ...failClosed(req, `Approval channel error: ${(err as Error).message}`),
-        decidedBy: "unreachable",
-      };
-    }
-    await sendApprovalResolved(
-      client,
-      resolvedFromOutcome(expired.outcome, expired.request),
-    ).catch(() => {});
-    return decisionFromOutcome(expired.outcome, req);
-  } finally {
-    cancelDecisionWait();
-    if (ownsClient) client.close();
-  }
+  return { promise, cancel };
 }
 
 function decisionFromOutcome(