granttap-mcp 0.8.5 → 0.8.6

package/apps/bridge/src/attachment-store.ts

@@ -13,6 +13,9 @@ import type { UserAttachment, UserAttachmentUpload } from "../../../packages/pro
 import { configDir } from "./config";
 
 export const ATTACHMENT_TTL_MS = 2 * 60 * 60_000;
+/** How many attachments may wait for their messages at once, and how much disk they may take. */
+export const MAX_STAGED_ATTACHMENTS = 32;
+export const MAX_STAGED_BYTES = 48 * 1_024 * 1_024;
 
 function directory(): string {
   const dir = join(configDir(), "attachments");
@@ -39,10 +42,44 @@ export function storeAttachment(upload: UserAttachmentUpload, room?: string, now
     name: upload.name, mimeType: upload.mimeType, data: upload.data, receivedAt: now,
     ...(room ? { room } : {}),
   };
-  writeFileSync(join(dir, `${id}.json`), JSON.stringify(record), { mode: 0o600 });
+  const body = JSON.stringify(record);
+  // The staging area is bounded. One attachment too large for it is refused
+  // (the message that names it is rejected and the phone sends it inline);
+  // otherwise the oldest waiting ones make room, since a message that never
+  // came is the likeliest reason they are still here.
+  if (body.length > MAX_STAGED_BYTES) return false;
+  makeRoom(dir, body.length, id);
+  writeFileSync(join(dir, `${id}.json`), body, { mode: 0o600 });
   return true;
 }
 
+function makeRoom(dir: string, incoming: number, incomingId: string): void {
+  let staged: Array<{ path: string; size: number; mtimeMs: number }> = [];
+  try {
+    staged = readdirSync(dir)
+      .filter((name) => name.endsWith(".json") && name !== `${incomingId}.json`)
+      .flatMap((name) => {
+        try {
+          const stat = statSync(join(dir, name));
+          return [{ path: join(dir, name), size: stat.size, mtimeMs: stat.mtimeMs }];
+        } catch {
+          return [];
+        }
+      })
+      .sort((left, right) => left.mtimeMs - right.mtimeMs);
+  } catch {
+    return;
+  }
+  let count = staged.length;
+  let bytes = staged.reduce((total, item) => total + item.size, 0);
+  for (const item of staged) {
+    if (count < MAX_STAGED_ATTACHMENTS && bytes + incoming <= MAX_STAGED_BYTES) break;
+    rmSync(item.path, { force: true });
+    count -= 1;
+    bytes -= item.size;
+  }
+}
+
 /** The attachment the message named, taken off disk; nothing when it never came. */
 export function takeAttachment(attachmentId: string, room?: string, now = Date.now()): UserAttachment | undefined {
   const id = safeId(attachmentId);

package/apps/bridge/src/mesh/admin.ts

@@ -0,0 +1,37 @@
+/**
+ * What the person may do to the mesh that no agent may.
+ *
+ * A claim is released by its owner, and only its owner: that is what keeps
+ * one agent from clearing another's hold on a file. It also means a claim
+ * whose owner died, or will not let go, stays until it expires. The person
+ * is not an owner and is not bound by that rule; they are the authority the
+ * rule protects. A release from the phone is therefore a command of its
+ * own, checked against the Project it names, and written down.
+ */
+import type { MeshClaimRelease, ResourceClaim } from "../../../../packages/protocol/schema";
+import type { MeshStore } from "./store";
+
+export type PersonRelease =
+  | { released: true; claim: ResourceClaim }
+  | { released: false; reason: "unknown_claim" | "other_project" };
+
+export function releaseClaimByPerson(
+  store: MeshStore,
+  request: MeshClaimRelease,
+  log: (line: string) => void = (line) => process.stderr.write(`[monitor] mesh: ${line}\n`),
+): PersonRelease {
+  // The claim must be one of this Project's: a claim id is not a secret, and
+  // a Project's person does not reach into another Project with it.
+  const inProject = store.snapshot(request.projectId)?.claims.find((item) => item.claimId === request.claimId);
+  if (!inProject) {
+    const elsewhere = store.activeClaims().some((item) => item.claimId === request.claimId);
+    log(`release of ${request.claimId} refused: ${elsewhere ? "not in this Project" : "no such claim"}`);
+    return { released: false, reason: elsewhere ? "other_project" : "unknown_claim" };
+  }
+  store.releaseClaim(request.claimId);
+  log(
+    `claim ${request.claimId} on ${inProject.resource} held by ${inProject.ownerSessionId} `
+    + `released by the person${request.reason ? `: ${request.reason}` : ""}`,
+  );
+  return { released: true, claim: inProject };
+}

package/apps/bridge/src/monitor.ts

@@ -53,6 +53,7 @@ import { approvalsStatus } from "./approval-state";
 import { primeSessionKeys, sendSessionPayload } from "./session-keys";
 import { sendMeshPayload } from "./session-keys";
 import { handleMeshPayload, meshCatalog, meshSnapshots, prepareMeshHandoff } from "./mesh/runtime";
+import { releaseClaimByPerson } from "./mesh/admin";
 import { deriveObservedClaims } from "./mesh/observed-claims";
 import { localMeshStore } from "./mesh/local";
 import { cachedSessionActivity } from "./monitor-session-activity";
@@ -398,6 +399,11 @@ export function startSessionMonitor(client: RelayClient): SessionMonitor {
       const prepared = await prepareMeshHandoff(client, payload);
       if (prepared) void publish().catch(() => {});
       return prepared;
+    } else if (payload.type === "mesh.claim.release" && loadRuntimeConfig().meshEnabled) {
+      // The person's own authority, not an owner's event: written down, then applied.
+      const outcome = releaseClaimByPerson(localMeshStore(), payload);
+      if (outcome.released) void publish().catch(() => {});
+      return true;
     }
     return false;
   });

package/apps/mcp/src/mcp-tools/interaction.ts

@@ -19,6 +19,7 @@ import { handleMeshPayload } from "../../../bridge/src/mesh/runtime";
 import { sendMeshPayload } from "../../../bridge/src/session-keys";
 import { isMeshEnabled, isProviderEnabled } from "../../../bridge/src/config/runtime";
 import { sessionFromEnvironment } from "./mesh-resource";
+import { OperationLedger, type OperationRecord } from "./operation-ledger";
 import {
   askOpenQuestionOutcome,
   askYesNoOutcome,
@@ -31,6 +32,11 @@ import {
 const NOT_PAIRED =
   "GrantTap is not paired on this machine. Pair the desktop bridge with the GrantTap app first.";
 const question = z.string().min(1).max(8_000).describe("The question to ask");
+const operationId = z.string().trim().min(1).max(128).optional().describe(
+  "A name of your own for this call. Retrying with the same operationId repeats nothing that "
+  + "already happened: an event is not published twice, a person is not asked twice, and only "
+  + "the part that failed is done again.",
+);
 const meshEventInput = z.object({
   capability: z.string().trim().min(1).max(128).optional(),
   projectId: z.string().trim().min(1).max(128),
@@ -47,6 +53,9 @@ const UNATTRIBUTED =
   + "are published only for the execution that made the call, so its provider hook must "
   + "be installed and trusted (granttap setup).";
 
+/** One ledger per server, which is one per chat: a retry from the same chat finds its record. */
+const ledger = new OperationLedger();
+
 /**
  * What a call came to, in a form a model can branch on.
  *
@@ -54,84 +63,122 @@ const UNATTRIBUTED =
  * structured result is the contract: a status that keeps "sent", "published"
  * and "refused" apart, a decision that is null when nobody answered, and the
  * id of a recorded event so a retry can be told from a duplicate. A call
- * that errors changed nothing.
+ * that errors changed nothing; a call that changed something and then failed
+ * says exactly which part is still owed.
  */
 const notifyOutput = {
   status: z.enum(["sent", "published", "claim_rejected"]).describe(
     "sent: only a status text went to the phone; published: the Mesh event was recorded on this "
     + "computer and sent; claim_rejected: the claim conflicts with another execution's and was not recorded",
   ),
-  messageSent: z.boolean().describe("Whether a status text was handed to the relay for the phone"),
+  messageSent: z.boolean().describe("Whether the status text was handed to the relay for the phone"),
   meshEventId: z.string().optional().describe("The id of the Mesh event as recorded (for claim_rejected, the CONFLICT event)"),
   conflict: z.object({
     ownerSessionId: z.string(),
     resource: z.string(),
   }).optional().describe("Who holds the resource this claim collided with"),
   scopedResource: z.string().optional().describe("This execution's scoped Mesh resource URI, when the call was attributed"),
+  error: z.string().optional().describe("The part of the call that failed after the rest had happened; retry with the same operationId"),
+  replayed: z.boolean().optional().describe("This answer repeats an earlier call with the same operationId"),
 };
 const yesNoOutput = {
   status: z.enum(["answered", "timed_out"]).describe("timed_out: nobody answered before the wait ended"),
   decision: z.enum(["yes", "no"]).nullable().describe("The person's answer; null when nobody answered. A timeout is not a refusal."),
+  replayed: z.boolean().optional().describe("This answer repeats an earlier call with the same operationId"),
 };
 const openOutput = {
   status: z.enum(["answered", "timed_out"]).describe("timed_out: nobody answered before the wait ended"),
   answer: z.string().nullable().describe("The person's words; null when nobody answered"),
+  replayed: z.boolean().optional().describe("This answer repeats an earlier call with the same operationId"),
 };
 
+function answered(text: string, outcome: Record<string, unknown>) {
+  return { content: [{ type: "text" as const, text }], structuredContent: outcome };
+}
+
+function replayed(record: OperationRecord) {
+  return answered(`${record.text}\n(replayed: this operationId was already handled)`, { ...record.outcome, replayed: true });
+}
+
 export function registerInteractionTools(server: McpServer): void {
   server.registerTool(
     "notify",
     {
       description:
         "Send a non-blocking status to the user, or publish one bounded task-scoped Project Mesh event. "
-        + "The result says whether the text was sent and whether the event was recorded; an error means nothing happened. "
+        + "The result says whether the text was sent and whether the event was recorded; an error means nothing happened, "
+        + "and a result with an error field says which part is still owed. Give the call an operationId to make retries safe. "
         + "A handoff is started by the person from the phone, never by an event published here.",
       inputSchema: {
         message: z.string().min(1).max(2_000).describe("Optional text to show on the user's devices").optional(),
         meshEvent: meshEventInput.describe("Optional structured coordination event; never include hidden reasoning").optional(),
+        operationId,
       },
       outputSchema: notifyOutput,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
     },
-    async ({ message, meshEvent }) => {
+    async ({ message, meshEvent, operationId: operation }) => {
       if (!message && !meshEvent) return {
         isError: true,
         content: [{ type: "text" as const, text: "Provide message or meshEvent." }],
       };
       const client = await relay();
       if (!client) return notPaired();
-      // The provider hook already saw this exact call inside its own session.
-      const attributed = consumeAttributedCall("notify", { message, meshEvent }, Date.now(), sessionFromEnvironment());
-      // The event first: its checks can refuse the whole call, and a status
-      // sent before a refusal would report work that did not happen.
-      const published = meshEvent
-        ? await publishMeshEvent(client, meshEvent, attributed?.sessionId)
-        : undefined;
-      if (message) {
-        await client.send(
-          { type: "agent.event", text: message, kind: "status", createdAt: Date.now() },
-          "phone",
-          { ttlMs: 15 * 60_000, wake: true },
-        );
-      }
-      const capability = isMeshEnabled() && attributed
-        ? executionCapabilityFor(attributed.sessionId)
-        : undefined;
-      const scopedResource = capability ? `granttap://mesh/${capability.token}` : undefined;
-      const text = published?.text ?? "sent to phone";
-      return {
-        content: [{
-          type: "text",
-          text: scopedResource ? `${text}\nScoped Mesh state: ${scopedResource}` : text,
-        }],
-        structuredContent: {
+      const previous = operation ? ledger.recall("notify", operation) : undefined;
+      if (previous && (previous.pending !== "message" || !message)) return replayed(previous);
+      let outcome: Record<string, unknown>;
+      let text: string;
+      let changedSomething = Boolean(previous);
+      if (previous) {
+        // The event went out last time; only the status text is still owed.
+        outcome = { ...previous.outcome };
+        text = previous.text;
+      } else {
+        // The provider hook already saw this exact call inside its own session.
+        const attributed = consumeAttributedCall("notify", { message, meshEvent }, Date.now(), sessionFromEnvironment());
+        // The event first: its checks can refuse the whole call, and a status
+        // sent before a refusal would report work that did not happen.
+        const published = meshEvent
+          ? await publishMeshEvent(client, meshEvent, attributed?.sessionId)
+          : undefined;
+        changedSomething = published != null;
+        const capability = isMeshEnabled() && attributed
+          ? executionCapabilityFor(attributed.sessionId)
+          : undefined;
+        const scopedResource = capability ? `granttap://mesh/${capability.token}` : undefined;
+        text = published?.text ?? "sent to phone";
+        if (scopedResource) text = `${text}\nScoped Mesh state: ${scopedResource}`;
+        outcome = {
           status: published?.status ?? "sent",
-          messageSent: Boolean(message),
+          messageSent: false,
           ...(published ? { meshEventId: published.eventId } : {}),
           ...(published?.conflict ? { conflict: published.conflict } : {}),
           ...(scopedResource ? { scopedResource } : {}),
-        },
-      };
+        };
+      }
+      if (message) {
+        try {
+          await client.send(
+            { type: "agent.event", text: message, kind: "status", createdAt: Date.now() },
+            "phone",
+            { ttlMs: 15 * 60_000, wake: true },
+          );
+          outcome.messageSent = true;
+          delete outcome.error;
+        } catch (error) {
+          // Nothing else happened: the whole call failed, and says so.
+          if (!changedSomething) throw error;
+          const detail = error instanceof Error ? error.message : String(error);
+          outcome.messageSent = false;
+          outcome.error = `status text not sent: ${detail}`;
+          const partial = `${text}\nStatus text not sent (${detail}). The Mesh event is recorded; `
+            + "retry with the same operationId to send only the text.";
+          if (operation) ledger.remember("notify", operation, { text, outcome, pending: "message" });
+          return answered(partial, { ...outcome, ...(previous ? { replayed: true } : {}) });
+        }
+      }
+      if (operation) ledger.remember("notify", operation, { text, outcome });
+      return answered(text, { ...outcome, ...(previous ? { replayed: true } : {}) });
     },
   );
   server.registerTool(
@@ -140,12 +187,21 @@ export function registerInteractionTools(server: McpServer): void {
       description:
         "Ask the user a yes/no question on their phone/watch and wait for the tap. Returns 'yes' or 'no' "
         + "when they answered, or 'no-answer (timeout)' when nobody answered in time. A timeout is not a "
-        + "refusal: do not treat it as 'no', and do not treat it as permission.",
-      inputSchema: { question: question.describe("A question answerable with yes/no") },
+        + "refusal: do not treat it as 'no', and do not treat it as permission. With an operationId, a retry "
+        + "returns the answer already given instead of asking again.",
+      inputSchema: { question: question.describe("A question answerable with yes/no"), operationId },
       outputSchema: yesNoOutput,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
     },
-    async ({ question: text }) => answerYesNo(text, interactionScope("ask_yes_no", text)),
+    async ({ question: text, operationId: operation }) => {
+      const previous = operation ? ledger.recall("ask_yes_no", operation) : undefined;
+      if (previous) return replayed(previous);
+      const result = await answerYesNo(text, interactionScope("ask_yes_no", text));
+      if (operation && !result.isError && result.structuredContent) {
+        ledger.remember("ask_yes_no", operation, { text: result.content[0]!.text, outcome: result.structuredContent });
+      }
+      return result;
+    },
   );
   server.registerTool(
     "ask",
@@ -153,12 +209,20 @@ export function registerInteractionTools(server: McpServer): void {
       description:
         "Ask the user an open question on their phone/watch and wait for their spoken or typed reply. "
         + "Returns their answer text, or 'no-answer (timeout)' when nobody answered in time; a timeout is "
-        + "not an answer.",
-      inputSchema: { question },
+        + "not an answer. With an operationId, a retry returns the answer already given instead of asking again.",
+      inputSchema: { question, operationId },
       outputSchema: openOutput,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
     },
-    async ({ question: text }) => answerOpenQuestion(text, interactionScope("ask", text)),
+    async ({ question: text, operationId: operation }) => {
+      const previous = operation ? ledger.recall("ask", operation) : undefined;
+      if (previous) return replayed(previous);
+      const result = await answerOpenQuestion(text, interactionScope("ask", text));
+      if (operation && !result.isError && result.structuredContent) {
+        ledger.remember("ask", operation, { text: result.content[0]!.text, outcome: result.structuredContent });
+      }
+      return result;
+    },
   );
 }
 
@@ -271,7 +335,7 @@ async function publishMeshEvent(
 
 /** Not paired is an error, not an outcome: nothing was sent, nothing was asked. */
 function notPaired() {
-  return { isError: true, content: [{ type: "text" as const, text: NOT_PAIRED }] };
+  return { isError: true as const, content: [{ type: "text" as const, text: NOT_PAIRED }] };
 }
 
 function interactionScope(tool: "ask" | "ask_yes_no", text: string): TaskInteractionScope | undefined {
@@ -288,22 +352,22 @@ function interactionScope(tool: "ask" | "ask_yes_no", text: string): TaskInterac
   };
 }
 
-async function answerYesNo(questionText: string, scope?: TaskInteractionScope) {
+type ToolAnswer = {
+  isError?: boolean;
+  content: Array<{ type: "text"; text: string }>;
+  structuredContent?: Record<string, unknown>;
+};
+
+async function answerYesNo(questionText: string, scope?: TaskInteractionScope): Promise<ToolAnswer> {
   const client = await relay();
   if (!client) return notPaired();
   const outcome = await askYesNoOutcome(client, questionText, undefined, scope);
-  return {
-    content: [{ type: "text" as const, text: yesNoText(outcome) }],
-    structuredContent: outcome,
-  };
+  return answered(yesNoText(outcome), outcome);
 }
 
-async function answerOpenQuestion(questionText: string, scope?: TaskInteractionScope) {
+async function answerOpenQuestion(questionText: string, scope?: TaskInteractionScope): Promise<ToolAnswer> {
   const client = await relay();
   if (!client) return notPaired();
   const outcome = await askOpenQuestionOutcome(client, questionText, undefined, scope);
-  return {
-    content: [{ type: "text" as const, text: openAnswerText(outcome) }],
-    structuredContent: outcome,
-  };
+  return answered(openAnswerText(outcome), outcome);
 }

package/apps/mcp/src/mcp-tools/operation-ledger.ts

@@ -0,0 +1,53 @@
+/**
+ * What a call already did, by the name the model gave it.
+ *
+ * A tool call is not a transaction: a Mesh event can be recorded and sent
+ * before the status text fails on the wire, and a model that retries the
+ * whole call would publish the event twice — or ask the person the same
+ * question again. Given an operationId, the server remembers what each part
+ * of a call came to and, on the same id again, does only what is still
+ * undone, answering with the whole.
+ */
+export type OperationRecord = {
+  at: number;
+  tool: string;
+  text: string;
+  outcome: Record<string, unknown>;
+  /** The part of the call that has not happened yet, to be done on the retry. */
+  pending?: "message";
+};
+
+export const OPERATION_TTL_MS = 15 * 60_000;
+const MAX_OPERATIONS = 64;
+
+export class OperationLedger {
+  private readonly records = new Map<string, OperationRecord>();
+
+  constructor(private readonly ttlMs = OPERATION_TTL_MS) {}
+
+  private key(tool: string, operationId: string): string {
+    return `${tool}\0${operationId}`;
+  }
+
+  recall(tool: string, operationId: string, now = Date.now()): OperationRecord | undefined {
+    const record = this.records.get(this.key(tool, operationId));
+    if (!record) return undefined;
+    if (now - record.at > this.ttlMs) {
+      this.records.delete(this.key(tool, operationId));
+      return undefined;
+    }
+    return record;
+  }
+
+  remember(tool: string, operationId: string, record: Omit<OperationRecord, "at" | "tool">, now = Date.now()): void {
+    for (const [key, item] of this.records) {
+      if (now - item.at > this.ttlMs) this.records.delete(key);
+    }
+    this.records.set(this.key(tool, operationId), { ...record, at: now, tool });
+    while (this.records.size > MAX_OPERATIONS) {
+      const oldest = this.records.keys().next().value;
+      if (oldest == null) break;
+      this.records.delete(oldest);
+    }
+  }
+}

package/package.json

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

package/packages/protocol/messages/mesh.ts

@@ -247,6 +247,28 @@ export const MeshEvent = z.object({
 });
 export type MeshEvent = z.infer<typeof MeshEvent>;
 
+/**
+ * The person releases a claim that is nobody's to release by ownership: an
+ * agent that died holding a file, or one that will not let go. The phone
+ * sends it to each computer of the Project under the Project's key. It is
+ * not a RESOURCE_RELEASE event, which only an owner may make; it is the
+ * person's own authority, and the computer writes down that it was used.
+ */
+export const MeshClaimRelease = z.object({
+  type: z.literal("mesh.claim.release"),
+  sessionId: Identifier,
+  projectId: Identifier,
+  claimId: Identifier,
+  reason: Detail.optional(),
+  requestId: Identifier.optional(),
+  createdAt: z.number().nonnegative(),
+}).strict().superRefine((value, ctx) => {
+  if (value.sessionId !== value.projectId) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["sessionId"], message: "project scope mismatch" });
+  }
+});
+export type MeshClaimRelease = z.infer<typeof MeshClaimRelease>;
+
 export const MeshHandoffPrepare = z.object({
   type: z.literal("mesh.handoff.prepare"),
   sessionId: Identifier,

package/packages/protocol/schema.ts

@@ -21,6 +21,7 @@ import { AgentId, Role } from "./messages/primitives";
 import {
   MeshEndpointPolicy,
   MeshEvent,
+  MeshClaimRelease,
   MeshHandoffPrepare,
   MeshSnapshot,
 } from "./messages/mesh";
@@ -116,6 +117,7 @@ export const Payload = z.union([
   ToolUpdate,
   ToolUpdateResult,
   MeshEvent,
+  MeshClaimRelease,
   MeshHandoffPrepare,
   MeshSnapshot,
   MeshEndpointPolicy,