granttap-mcp 0.8.37 → 0.8.38

package/README.md

@@ -170,7 +170,8 @@ decided by the runtime after receipt verification.
 
 The first executable handoff path is Claude Code ↔ Codex across linked
 computers. GrantTap builds a bounded Task Capsule from explicit task/git facts,
-requires local phone authorization, creates a separate target branch/worktree,
+requires authorization from the phone or the owning Mac's local desktop channel,
+creates a separate target branch/worktree,
 starts the target execution, and returns a receipt bound to the exact capsule.
 Cursor uses the same provider-neutral schema and trusted caller attribution.
 Grok Build remains observable where available, but does not
@@ -192,6 +193,10 @@ the commit fetches that branch once before refusing. A handoff can also stay on
 one computer: the same Task continues with another agent there, in a worktree
 of its own from the same commit, taken up at once by the computer that
 prepared it.
+The person can select an advertised destination model and add a bounded comment.
+Both travel inside the encrypted capsule; the destination includes the comment
+in the new execution's opening message and starts the selected model. A model
+change on the same computer and provider is a new execution of the same Task.
 
 ### Pause and resume
 

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

@@ -70,6 +70,8 @@ export function buildTaskCapsule(
     targetProvider: request.targetProvider,
     targetActorId: request.targetActorId,
     targetComputer: request.targetComputer,
+    targetModel: request.targetModel,
+    userComment: request.userComment,
     repository: project.canonicalRepositoryId,
     baseSha: head,
     branch: session.branch ?? git(cwd, ["branch", "--show-current"]),

package/apps/bridge/src/mesh/runtime/dependencies.ts

@@ -22,7 +22,7 @@ export type MeshRuntimeDependencies = {
   now: () => number;
   eventId: () => string;
   providerEnabled: (provider: Exclude<MeshProvider, "grok_bot">) => boolean;
-  start: (provider: MeshProvider, prompt: string, cwd: string) => Promise<StartResult>;
+  start: (provider: MeshProvider, prompt: string, cwd: string, model?: string) => Promise<StartResult>;
   deliver: typeof deliverToSession;
   send: (
     client: RelayClient,

package/apps/bridge/src/mesh/runtime/handoff.ts

@@ -19,6 +19,7 @@ function capsulePrompt(capsule: TaskCapsule): string {
     `Base SHA: ${capsule.baseSha}`,
   ];
   if (capsule.latestCommit) lines.push(`Latest commit: ${capsule.latestCommit}`);
+  if (capsule.userComment) lines.push(`User comment: ${capsule.userComment}`);
   if (capsule.checkpoint) {
     const { status, files, excluded } = capsule.checkpoint;
     const line = status === "complete"
@@ -138,7 +139,9 @@ async function acceptHandoff(
     revision,
   );
   if (!worktree) return rejectHandoff(deps, client, event, "A separate handoff worktree could not be created.");
-  const result = await deps.start(capsule.targetProvider, capsulePrompt(capsule), worktree.path);
+  const result = await deps.start(
+    capsule.targetProvider, capsulePrompt(capsule), worktree.path, capsule.targetModel,
+  );
   if (!result.ok || !result.sessionId) {
     const reason = result.ok ? "The target agent did not create a session." : result.error;
     return rejectHandoff(deps, client, event, reason);

package/apps/bridge/src/mesh/runtime/index.ts

@@ -62,11 +62,11 @@ const defaultDependencies: MeshRuntimeDependencies = {
   now: Date.now,
   eventId: randomUUID,
   providerEnabled: isProviderEnabled,
-  start: async (provider, prompt, cwd) => {
-    if (provider === "claude") return createClaudeSession(prompt, cwd);
-    if (provider === "codex") return createCodexSession(prompt, cwd);
-    if (provider === "cursor") return createCursorSession(prompt, cwd);
-    return createGrokSession(prompt, cwd);
+  start: async (provider, prompt, cwd, model) => {
+    if (provider === "claude") return createClaudeSession(prompt, cwd, 240_000, [], model);
+    if (provider === "codex") return createCodexSession(prompt, cwd, 240_000, [], model);
+    if (provider === "cursor") return createCursorSession(prompt, cwd, 240_000, [], model);
+    return createGrokSession(prompt, cwd, 240_000, [], model);
   },
   deliver: deliverToSession,
   hasCommit: repositoryHasCommit,

package/apps/mcp/src/connection-center/widget.html

@@ -37,7 +37,7 @@ details{border-top:1px solid #8884;padding-top:14px}summary{cursor:pointer;font-
     <dt>Last encrypted message from iPhone</dt><dd id="phone">Not observed</dd></dl>
     <h3>Provider readiness</h3><ul id="providers"></ul>
     <p>QR pairs a phone directly. A passkey links this Mac to your GrantTap account so your signed-in phone can discover its computers. Provider sign-in is separate.</p>
-    <p>Missing hooks or background sync? Run <code>npm install -g granttap-mcp@0.8.37</code> and <code>granttap setup</code> locally.
+    <p>Missing hooks or background sync? Run <code>npm install -g granttap-mcp@0.8.38</code> and <code>granttap setup</code> locally.
     A saved pairing alone does not prove your phone or the background helper is online.</p>
     <p><a href="https://granttap.com" target="_blank" rel="noopener noreferrer">Website</a> ·
     <a href="https://granttap.com/privacy" target="_blank" rel="noopener noreferrer">Privacy</a> ·

package/apps/mcp/src/desktop/delivery/README.md

@@ -10,7 +10,13 @@ same limits as encrypted phone messages. Invalid batches are rejected rather
 than silently losing files. The existing provider attachment pipeline stages
 images and arbitrary documents; the native client removes its batch after reply.
 
-Tests: `tests/desktop/desktop-task-send.test.ts`, local `tests/attachments.test.ts`.
+`desktop.task_handoff` accepts a bounded handoff request from the authenticated
+Mac desktop channel. It verifies the exact owning local execution, then asks the
+canonical Mesh runtime to prepare the encrypted Task Capsule. A destination
+model and user comment are carried with the Task, including for another computer.
+
+Tests: `tests/desktop/desktop-task-send.test.ts`,
+`tests/desktop/delivery/task-handoff.test.ts`, local `tests/attachments.test.ts`.
 Parent: [Desktop local channel](../README.md).
 
 This MCP component is covered by the repository [MIT License](../../../../../LICENSE).

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

@@ -0,0 +1,57 @@
+import { join } from "node:path";
+import { RelayClient } from "../../../../../packages/core/relay-client";
+import { MeshHandoffPrepare, type MeshHandoffPrepare as HandoffRequest } from "../../../../../packages/protocol/schema";
+import { configDir, loadConfig, machineConfigPath } from "../../../../bridge/src/config";
+import { applyNetworkRoute } from "../../../../bridge/src/device-network/settings";
+import { observedComputerId } from "../../../../bridge/src/mesh/identity/computer";
+import { prepareMeshHandoff } from "../../../../bridge/src/mesh/runtime";
+import { readStoreState } from "../../../../bridge/src/mesh/store/state";
+import { controllerPeerGate } from "../../../../bridge/src/pairing/controllers";
+
+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) });
+  try {
+    await client.connect();
+    return await prepareMeshHandoff(client, request);
+  } finally {
+    client.close();
+  }
+}
+
+/** Same-user Mac request, limited to the exact Task owner on this computer. */
+export async function desktopTaskHandoff(
+  input: unknown,
+  storePath = join(configDir(), "project-mesh.json"),
+  prepare: Prepare = prepareThroughRelay,
+  localComputer = observedComputerId(),
+): Promise<unknown> {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return undefined;
+  const row = input as Record<string, unknown>;
+  const request = MeshHandoffPrepare.safeParse({
+    type: "mesh.handoff.prepare",
+    sessionId: row.session_id, projectId: row.project_id, taskId: row.task_id,
+    targetProvider: row.target_provider, targetComputer: row.target_computer,
+    targetModel: row.target_model, userComment: row.user_comment,
+    checkpoint: row.checkpoint, push: row.push, createdAt: Date.now(),
+  });
+  if (!request.success) return undefined;
+  const loaded = readStoreState(storePath);
+  if (loaded.status !== "ok") return undefined;
+  const task = loaded.state.tasks.find((item) => item.taskId === request.data.taskId);
+  const execution = loaded.state.executions.find((item) =>
+    item.taskId === request.data.taskId && item.sessionId === request.data.sessionId
+      && item.endedAt == null && item.computerId === localComputer);
+  if (task?.projectId !== request.data.projectId || task.ownerSessionId !== request.data.sessionId
+    || !execution?.workspace) return undefined;
+  try {
+    const accepted = await prepare(request.data);
+    return { operation: "desktop.task_handoff", accepted,
+      error: accepted ? null : "The handoff was not ready. Check the Task and its repository." };
+  } catch {
+    return { operation: "desktop.task_handoff", accepted: false,
+      error: "The local relay or handoff service is unavailable." };
+  }
+}

package/apps/mcp/src/desktop/engine-bridge.ts

@@ -22,6 +22,7 @@ export const DESKTOP_OPERATIONS = new Set([
   "desktop.installed_skills", "desktop.policy_status", "desktop.policy_set", "desktop.project_auto_accept",
   "desktop.mesh_snapshots",
   "desktop.task_send",
+  "desktop.task_handoff",
   "desktop.task_create",
   "desktop.mesh_create",
   "desktop.invocation_history",
@@ -48,7 +49,7 @@ export function desktopOperationTimeout(operation: unknown, input: unknown): num
     || operation === "desktop.mesh_snapshots") return 75_000;
   if (operation === "desktop.task_activity"
     || operation === "desktop.task_image" || operation === "desktop.live_catalog") return 45_000;
-  if (operation === "desktop.task_send"
+  if (operation === "desktop.task_send" || operation === "desktop.task_handoff"
     || operation === "desktop.task_create") return 250_000;
   if (operation === "desktop.mesh_snapshot"
     && (input as { enrich?: unknown } | undefined)?.enrich === "true") return 45_000;

package/apps/mcp/src/desktop/operations/index.ts

@@ -10,6 +10,7 @@ import type { DesktopTaskActivityRunner } from "../task-activity-runner";
 import type { EngineClient } from "../../../../bridge/src/engine/runtime/engine-client";
 import type { EngineOperation } from "../../../../bridge/src/engine/protocol/engine-protocol";
 import { desktopTaskSend } from "../delivery/task-send";
+import { desktopTaskHandoff } from "../delivery/task-handoff";
 import { desktopTaskCreate } from "../delivery/task-create";
 import { desktopMeshCreate } from "../delivery/mesh-create";
 import { desktopInvocationHistory } from "../invocation";
@@ -54,6 +55,7 @@ export function desktopReadOperation(input: {
   if (operation === "desktop.task_activity") return activity.read(queryInput, storePath);
   if (operation === "desktop.task_image") return activity.image(queryInput, storePath);
   if (operation === "desktop.task_send") return desktopTaskSend(queryInput, storePath);
+  if (operation === "desktop.task_handoff") return desktopTaskHandoff(queryInput, storePath);
   if (operation === "desktop.task_create") return desktopTaskCreate(queryInput, storePath);
   if (operation === "desktop.mesh_create") return Promise.resolve(desktopMeshCreate(queryInput, storePath));
   if (operation === "desktop.invocation_history") {

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.37
+npm install -g granttap-mcp@0.8.38
 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.37\";\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.38\";\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.37";
+const PACKAGE = "granttap-mcp@0.8.38";
 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.37",
+  "version": "0.8.38",
   "description": "Personal live control center runtime for local coding agents on iPhone and Apple Watch.",
   "type": "module",
   "bin": {

package/packages/protocol/messages/mesh/events.ts

@@ -18,6 +18,8 @@ export const TaskCapsule = z.object({
   targetProvider: MeshExecutionProvider,
   targetActorId: Identifier.optional(),
   targetComputer: Identifier,
+  targetModel: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,159}$/).optional(),
+  userComment: Detail.optional(),
   repository: z.string().trim().min(1).max(1_024),
   baseSha: GitSha,
   branch: z.string().trim().min(1).max(512).optional(),
@@ -206,6 +208,8 @@ export const MeshHandoffPrepare = z.object({
   targetProvider: MeshExecutionProvider,
   targetActorId: Identifier.optional(),
   targetComputer: Identifier,
+  targetModel: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,159}$/).optional(),
+  userComment: Detail.optional(),
   createdAt: z.number().nonnegative(),
   /**
    * Commit uncommitted work to a checkpoint branch first, so the Task can