@paigy/mcp 0.17.1 → 0.19.0

package/README.md

@@ -92,8 +92,9 @@ Then pair: `npx -p @paigy/mcp@latest paigy-mcp-onboard`.
 
 ## Tools
 
-- **`pair`** — pair this agent with the user's Paigy account (one-time). No args to start (opens the approval link); pass the returned `device_code` to finish.
+- **`pair`** — pair this agent with the user's Paigy account (one-time). No args to start: returns the code to show the user **and begins polling for approval in the background**; pass the returned `device_code` to collect the result (it returns the moment the user approves). On success it prompts you to allowlist Paigy's notify/await tools so they run without an approval prompt each time.
 - **`unpair`** — log this agent out of the user's Paigy account; revokes the token server-side and deletes the local one.
+- **`enable_tools`** — after pairing (and only with the user's consent), allowlist Paigy's notify/await tools so they run without an approval prompt each time. Writes Claude Code's `permissions.allow` — `scope:'user'` (default, every project) or `scope:'project'` (this repo). Merges, never clobbers; leaves `pair`/`unpair` human-approved.
 - **`notify_user`** — notify the user (context: title + description chunks; a required `select` answer shape — `one`/`many`/`rank` take `options`, `confirm`/`text` don't; plus `visuals`, `urgency`, and `parentId` for a clarification). Options carry no ids — the backend assigns them by position ("1", "2", …) and answers reference those; each option can carry a sandboxed `html` or `image` preview for visual "pick one" decisions. Returns `{ notificationId, threadId }`. If a reply comes back as `{kind:'clarify', chunks:[...]}`, respond via notify_user with the SAME threadId and an expanded description.
 - **`await_reply`** — wait for the user's reply to a specific notification (pass its notificationId). Scoped: will not return replies meant for other notifications. Returns `reply` / `remind` / `idle`.
 - **`check_replies`** — catch-up sweep: returns replies you haven't consumed yet (now marked seen) plus still-pending notifications, new user-initiated requests, and owed callbacks.

package/dist/{chunk-IMIXCPTN.js → chunk-HO3OJHRA.js}

@@ -1,10 +1,10 @@
 import {
   AGENT_NAME
-} from "./chunk-RMTTO6BI.js";
+} from "./chunk-VWQQ3VJF.js";
 
 // src/clients.ts
 import { execFile } from "child_process";
-import { existsSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir, platform } from "os";
 import { join, dirname } from "path";
 function openBrowser(url) {
@@ -81,9 +81,73 @@ function claudeInstallHint(skip = AGENT_NAME) {
   if (!existsSync(join(homedir(), ".claude"))) return null;
   return "Claude Code detected \u2014 to add Paigy there, run /plugin marketplace add paigy-ai/claude then /plugin install paigy (pairing carries over; no need to pair again).";
 }
+var PAIGY_TOOL_IDS = [
+  "mcp__paigy__notify_user",
+  "mcp__paigy__notify",
+  "mcp__paigy__await_reply",
+  "mcp__paigy__check_replies",
+  "mcp__paigy__set_task_state",
+  "mcp__paigy__schedule_callback",
+  "mcp__paigy__get_thread"
+];
+function withPaigyAllowlist(existing, tools) {
+  let config = {};
+  if (existing) {
+    try {
+      config = JSON.parse(existing);
+    } catch {
+      return null;
+    }
+  }
+  const permissions = config.permissions && typeof config.permissions === "object" ? config.permissions : {};
+  const allow = Array.isArray(permissions.allow) ? [...permissions.allow] : [];
+  for (const t of tools) if (!allow.includes(t)) allow.push(t);
+  config.permissions = { ...permissions, allow };
+  return JSON.stringify(config, null, 2);
+}
+function enablePaigyTools(scope = "user", cwd = process.cwd()) {
+  if (scope === "user" && !existsSync(join(homedir(), ".claude"))) {
+    return {
+      ok: false,
+      reason: `No ~/.claude on this machine \u2014 the hosting tool uses its own permission allowlist. Add these ids there by hand: ${PAIGY_TOOL_IDS.join(", ")}.`
+    };
+  }
+  const path = scope === "project" ? join(cwd, ".claude", "settings.json") : join(homedir(), ".claude", "settings.json");
+  let existing = null;
+  try {
+    existing = existsSync(path) ? readFileSync(path, "utf8") : null;
+  } catch {
+    existing = null;
+  }
+  let prevAllow = [];
+  if (existing) {
+    try {
+      const parsed = JSON.parse(existing);
+      if (Array.isArray(parsed.permissions?.allow)) prevAllow = parsed.permissions.allow;
+    } catch {
+      return { ok: false, reason: `${path} didn't parse as JSON \u2014 not overwriting it. Add the ids by hand.` };
+    }
+  }
+  const updated = withPaigyAllowlist(existing, PAIGY_TOOL_IDS);
+  if (updated === null) return { ok: false, reason: `${path} didn't parse as JSON \u2014 not overwriting it. Add the ids by hand.` };
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, updated + "\n");
+  } catch (e) {
+    return { ok: false, reason: `Couldn't write ${path}: ${e.message}` };
+  }
+  return {
+    ok: true,
+    path,
+    added: PAIGY_TOOL_IDS.filter((t) => !prevAllow.includes(t)),
+    already: PAIGY_TOOL_IDS.filter((t) => prevAllow.includes(t))
+  };
+}
 
 export {
   openBrowser,
   autoConfigureClients,
-  claudeInstallHint
+  claudeInstallHint,
+  PAIGY_TOOL_IDS,
+  enablePaigyTools
 };

package/dist/{chunk-MH6AHNUI.js → chunk-SLWESECN.js}

@@ -329,8 +329,9 @@ var InboxItemSchema = z.object({
    *  ("call back after lunch") — shown so they can see the commitment was captured. */
   intents: z.array(IntentSchema).optional(),
   visuals: z.array(VisualSchema).optional(),
-  agent: z.string(),
-  nickname: z.string(),
+  /** The connected agent's name (the single pairing name — user-typed, or the
+   *  agent's suggestion, or a default silly name). */
+  name: z.string(),
   /** The pairing's assigned voice (#462); absent = the default voice. */
   voice: VoiceKeySchema.optional(),
   repo: z.string().optional(),
@@ -438,8 +439,8 @@ var HistoryItemSchema = z.object({
   /** 'user' = a request you sent; 'agent' = a notification an agent sent you. */
   initiator: z.enum(["user", "agent"]),
   title: z.string(),
-  /** The agent on the other end (nickname). */
-  agent: z.string(),
+  /** The agent on the other end (its name). */
+  name: z.string(),
   createdAt: z.string(),
   /** When the agent fetched your request (user→agent only). */
   agentAckedAt: z.string().nullable(),
@@ -449,9 +450,12 @@ var HistoryItemSchema = z.object({
 var ConnectionSummarySchema = z.object({
   /** The connection = the agent's token id (used to address a request). */
   id: z.string(),
-  agent: z.string(),
   device: z.string().nullable(),
-  nickname: z.string(),
+  /** The agent's display name (the single pairing name). */
+  name: z.string(),
+  /** For a managed connection, the provider key (e.g. "cma") that agentOrigin maps to a
+   *  label; null for a local connection. Sourced from the token's provider, not the name. */
+  provider: z.string().nullable(),
   /** The pairing's assigned voice (#462); null = the default voice. */
   voice: VoiceKeySchema.nullable(),
   createdAt: z.string().datetime(),
@@ -502,8 +506,7 @@ var DeliveryConfigSchema = z.object({
   realtime: z.object({ url: z.string(), anonKey: z.string() }).nullable()
 });
 var StatusSchema = z.object({
-  agent: z.string(),
-  nickname: z.string(),
+  name: z.string(),
   sessionMode: z.enum(["default", "all_calls", "silent"]),
   /** A phone is registered for push/ring (any push token on the account). */
   phone: z.boolean()
@@ -550,14 +553,6 @@ var WakeNudgeSchema = z.object({
   notificationId: z.string().optional(),
   threadId: z.string()
 });
-var DeviceAgentTokenSchema = z.object({
-  token: z.string(),
-  deviceId: z.string(),
-  agentName: z.string(),
-  /** User-chosen session label; defaults to `<agent> <device>`. */
-  nickname: z.string(),
-  createdAt: z.string().datetime()
-});
 var PairingStatusSchema = z.enum(["pending", "approved", "denied", "expired"]);
 var PairingRevealSchema = z.object({
   x25519: z.string(),
@@ -565,6 +560,12 @@ var PairingRevealSchema = z.object({
   nonce: z.string()
 });
 var DeviceCodeRequestSchema = z.object({
+  /** The agent's suggested name for the pairing — the human sees it pre-filled at
+   *  approval and can override. Optional; blank → a default silly name server-side. */
+  suggestedName: z.string().optional(),
+  /** Legacy alias for suggestedName (older MCPs sent `agent`). Accepted for
+   *  back-compat; `suggestedName` wins when both are present. ponytail: drop once no
+   *  pre-`name` MCP is in the wild. */
   agent: z.union([z.string(), z.object({ name: z.string().optional() })]).optional(),
   device: z.string().optional(),
   proto: z.string().optional(),
@@ -582,7 +583,9 @@ var DeviceCodeSchema = z.object({
 });
 var DeviceInfoSchema = z.object({
   code: z.string(),
-  agent: z.string(),
+  /** The agent's suggested name (from /device/code) — shown on the approval screen,
+   *  pre-filling the name field the human can edit. */
+  name: z.string(),
   device: z.string().nullable(),
   status: PairingStatusSchema,
   proto: z.string().nullable().optional(),
@@ -605,8 +608,9 @@ var DeviceTokenRequestSchema = z.object({
 });
 var DeviceTokenSchema = z.object({
   access_token: z.string(),
-  nickname: z.string(),
-  agent: z.string(),
+  /** The pairing's single name (user-typed at approval, the agent's suggestion, or
+   *  a default silly name). */
+  name: z.string(),
   device: z.string().nullable(),
   phone_reveal: PairingRevealSchema.nullable().optional(),
   // present once the phone reveals

package/dist/{chunk-RMTTO6BI.js → chunk-VWQQ3VJF.js}

@@ -2618,8 +2618,9 @@ var InboxItemSchema = z.object({
    *  ("call back after lunch") — shown so they can see the commitment was captured. */
   intents: z.array(IntentSchema).optional(),
   visuals: z.array(VisualSchema).optional(),
-  agent: z.string(),
-  nickname: z.string(),
+  /** The connected agent's name (the single pairing name — user-typed, or the
+   *  agent's suggestion, or a default silly name). */
+  name: z.string(),
   /** The pairing's assigned voice (#462); absent = the default voice. */
   voice: VoiceKeySchema.optional(),
   repo: z.string().optional(),
@@ -2727,8 +2728,8 @@ var HistoryItemSchema = z.object({
   /** 'user' = a request you sent; 'agent' = a notification an agent sent you. */
   initiator: z.enum(["user", "agent"]),
   title: z.string(),
-  /** The agent on the other end (nickname). */
-  agent: z.string(),
+  /** The agent on the other end (its name). */
+  name: z.string(),
   createdAt: z.string(),
   /** When the agent fetched your request (user→agent only). */
   agentAckedAt: z.string().nullable(),
@@ -2738,9 +2739,12 @@ var HistoryItemSchema = z.object({
 var ConnectionSummarySchema = z.object({
   /** The connection = the agent's token id (used to address a request). */
   id: z.string(),
-  agent: z.string(),
   device: z.string().nullable(),
-  nickname: z.string(),
+  /** The agent's display name (the single pairing name). */
+  name: z.string(),
+  /** For a managed connection, the provider key (e.g. "cma") that agentOrigin maps to a
+   *  label; null for a local connection. Sourced from the token's provider, not the name. */
+  provider: z.string().nullable(),
   /** The pairing's assigned voice (#462); null = the default voice. */
   voice: VoiceKeySchema.nullable(),
   createdAt: z.string().datetime(),
@@ -2789,8 +2793,7 @@ var DeliveryConfigSchema = z.object({
   realtime: z.object({ url: z.string(), anonKey: z.string() }).nullable()
 });
 var StatusSchema = z.object({
-  agent: z.string(),
-  nickname: z.string(),
+  name: z.string(),
   sessionMode: z.enum(["default", "all_calls", "silent"]),
   /** A phone is registered for push/ring (any push token on the account). */
   phone: z.boolean()
@@ -2837,14 +2840,6 @@ var WakeNudgeSchema = z.object({
   notificationId: z.string().optional(),
   threadId: z.string()
 });
-var DeviceAgentTokenSchema = z.object({
-  token: z.string(),
-  deviceId: z.string(),
-  agentName: z.string(),
-  /** User-chosen session label; defaults to `<agent> <device>`. */
-  nickname: z.string(),
-  createdAt: z.string().datetime()
-});
 var PairingStatusSchema = z.enum(["pending", "approved", "denied", "expired"]);
 var PairingRevealSchema = z.object({
   x25519: z.string(),
@@ -2852,6 +2847,12 @@ var PairingRevealSchema = z.object({
   nonce: z.string()
 });
 var DeviceCodeRequestSchema = z.object({
+  /** The agent's suggested name for the pairing — the human sees it pre-filled at
+   *  approval and can override. Optional; blank → a default silly name server-side. */
+  suggestedName: z.string().optional(),
+  /** Legacy alias for suggestedName (older MCPs sent `agent`). Accepted for
+   *  back-compat; `suggestedName` wins when both are present. ponytail: drop once no
+   *  pre-`name` MCP is in the wild. */
   agent: z.union([z.string(), z.object({ name: z.string().optional() })]).optional(),
   device: z.string().optional(),
   proto: z.string().optional(),
@@ -2869,7 +2870,9 @@ var DeviceCodeSchema = z.object({
 });
 var DeviceInfoSchema = z.object({
   code: z.string(),
-  agent: z.string(),
+  /** The agent's suggested name (from /device/code) — shown on the approval screen,
+   *  pre-filling the name field the human can edit. */
+  name: z.string(),
   device: z.string().nullable(),
   status: PairingStatusSchema,
   proto: z.string().nullable().optional(),
@@ -2892,8 +2895,9 @@ var DeviceTokenRequestSchema = z.object({
 });
 var DeviceTokenSchema = z.object({
   access_token: z.string(),
-  nickname: z.string(),
-  agent: z.string(),
+  /** The pairing's single name (user-typed at approval, the agent's suggestion, or
+   *  a default silly name). */
+  name: z.string(),
   device: z.string().nullable(),
   phone_reveal: PairingRevealSchema.nullable().optional(),
   // present once the phone reveals
@@ -3266,11 +3270,13 @@ async function revokeToken(token) {
   });
   return res.ok;
 }
-async function requestCode(agent2 = AGENT_NAME, e2ee) {
+async function requestCode(suggestedName = AGENT_NAME, e2ee) {
   const res = await reach(`${BACKEND_URL}/api/device/code`, {
     method: "POST",
     headers: { "content-type": "application/json" },
-    body: JSON.stringify(e2ee ? { agent: agent2, proto: e2ee.proto, commitment: e2ee.commitment } : { agent: agent2 })
+    body: JSON.stringify(
+      e2ee ? { suggestedName, proto: e2ee.proto, commitment: e2ee.commitment } : { suggestedName }
+    )
   });
   if (!res.ok) throw new Error(`/api/device/code failed: ${res.status} ${await res.text()}`);
   return await res.json();

package/dist/index.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
 import {
   HandoffSchema
-} from "./chunk-MH6AHNUI.js";
+} from "./chunk-SLWESECN.js";
 import {
+  PAIGY_TOOL_IDS,
   autoConfigureClients,
-  claudeInstallHint
-} from "./chunk-IMIXCPTN.js";
+  claudeInstallHint,
+  enablePaigyTools
+} from "./chunk-HO3OJHRA.js";
 import {
   clearSurface,
   writeSurface
@@ -36,7 +38,7 @@ import {
   sleep,
   startE2ee,
   submitNotification
-} from "./chunk-RMTTO6BI.js";
+} from "./chunk-VWQQ3VJF.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -74,6 +76,81 @@ function json(s) {
   return draft2020(schema);
 }
 
+// src/pairing.ts
+async function resolvePairing(deviceCode, capMs, pollMs = 2e3) {
+  let kf = readKeyFile();
+  const start = Date.now();
+  while (Date.now() - start < capMs) {
+    let step;
+    try {
+      step = await pairStep(deviceCode, kf);
+    } catch (e) {
+      return { kind: "error", message: e.message };
+    }
+    if (step.kind === "e2ee_aborted") {
+      deleteKeyFile();
+      kf = null;
+      await sleep(pollMs);
+      continue;
+    }
+    if (step.kind === "awaiting_confirm") {
+      return { kind: "awaiting_confirm", sas: step.sas };
+    }
+    if (step.kind === "paired") {
+      saveToken(step.token);
+      if (!step.sas || !kf) {
+        deleteKeyFile();
+        return { kind: "paired", token: step.token };
+      }
+      const finalDeadline = Math.min(Date.now() + 1e4, start + capMs);
+      let e2ee = false;
+      while (Date.now() < finalDeadline) {
+        const cred = kf.userCode ? await fetchCredential(kf.userCode) : null;
+        if (cred && step.uikPub) {
+          e2ee = finalizeE2ee(kf, cred, step.uikPub);
+          break;
+        }
+        await sleep(pollMs);
+      }
+      if (!e2ee) deleteKeyFile();
+      return { kind: "paired", token: step.token, sas: step.sas, e2ee };
+    }
+    await sleep(pollMs);
+  }
+  return { kind: "pending" };
+}
+var bg = null;
+function startBackgroundPair(deviceCode, budgetMs) {
+  const promise = resolvePairing(deviceCode, budgetMs).catch((e) => ({ kind: "error", message: e.message })).then((o) => {
+    if (bg?.deviceCode === deviceCode) bg.settled = o;
+    return o;
+  });
+  bg = { deviceCode, promise };
+}
+async function joinBackgroundPair(deviceCode, capMs) {
+  if (!bg || bg.deviceCode !== deviceCode) return null;
+  if (bg.settled) {
+    const s = bg.settled;
+    bg = null;
+    return s;
+  }
+  const TIMEOUT = /* @__PURE__ */ Symbol("timeout");
+  const raced = await Promise.race([bg.promise, sleep(capMs).then(() => TIMEOUT)]);
+  if (raced !== TIMEOUT) {
+    bg = null;
+    return raced;
+  }
+  if (bg?.settled) {
+    const s = bg.settled;
+    bg = null;
+    return s;
+  }
+  return { kind: "pending" };
+}
+function cancelBackgroundPair() {
+  bg = null;
+}
+
 // src/index.ts
 var ONBOARD_MSG = "Not paired with Paigy yet \u2014 call the `pair` tool to connect this agent (it returns an approval link to show the user), then retry. Manual fallback: `npx -y -p @paigy/mcp paigy-mcp-onboard`.";
 var AwaitReplySchema = z.object({
@@ -85,6 +162,9 @@ var PairSchema = z.object({
 var GetThreadSchema = z.object({
   threadId: z.string().describe("The thread to read \u2014 from a reply, request, or past notification.")
 });
+var EnableToolsSchema = z.object({
+  scope: z.enum(["user", "project"]).optional().describe("'user' (default) allowlists Paigy's tools for every project (~/.claude/settings.json); 'project' scopes them to this repo (.claude/settings.json).")
+});
 var SetTaskStateToolSchema = z.object({
   notificationId: z.string(),
   state: SetTaskStateSchema.shape.state
@@ -109,8 +189,7 @@ function pairedResult(token, sas, note, e2ee) {
   clearSurface();
   const base = {
     status: "paired",
-    nickname: token.nickname,
-    agent: token.agent,
+    name: token.name,
     device: token.device
   };
   if (sas) {
@@ -129,7 +208,9 @@ function pairedResult(token, sas, note, e2ee) {
     if (hint) base.claude_hint = hint;
   } catch {
   }
-  base.permissions_hint = "Offer the user ONCE: allowlist Paigy's tools so they run without prompting (in Claude Code, add mcp__paigy__notify_user, mcp__paigy__await_reply, mcp__paigy__check_replies, mcp__paigy__set_task_state, mcp__paigy__schedule_callback, mcp__paigy__get_thread to permissions.allow in ~/.claude/settings.json \u2014 or the project's .claude/settings.json if they prefer; other tools have their own allowlist). Merge into the existing file, never clobber it. Leave pair/unpair human-approved. If they decline, drop it.";
+  base.enable_tool_ids = PAIGY_TOOL_IDS;
+  base.enable_prompt = `REQUIRED \u2014 before you do anything else, ask the user now: "Want me to let Paigy's tools run without an approval prompt each time? I'll only allowlist the notify/await tools \u2014 pair and unpair still ask." Prompt every time you pair; don't skip it.`;
+  base.enable_apply = "On yes: call the `enable_tools` tool \u2014 it writes the allowlist for you (scope:'user' = every project, the default; scope:'project' = just this repo). No hand-editing. If it returns ok:false (the host isn't Claude Code), fall back to adding `enable_tool_ids` to that tool's own allowlist by hand, merging \u2014 never clobbering. pair/unpair stay out, so they remain human-approved. On no: drop it, don't ask again this session.";
   return { content: [{ type: "text", text: JSON.stringify(base) }] };
 }
 function awaitingConfirmResult(sas, device_code) {
@@ -153,6 +234,28 @@ Check it matches the code on the phone, then type it there to confirm.` },
     ]
   };
 }
+function renderPairOutcome(outcome, device_code) {
+  switch (outcome.kind) {
+    case "error":
+      clearSurface();
+      throw new Error(outcome.message);
+    case "awaiting_confirm":
+      return awaitingConfirmResult(outcome.sas, device_code);
+    case "paired":
+      return pairedResult(outcome.token, outcome.sas, void 0, outcome.e2ee);
+    case "pending":
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            status: "pending",
+            device_code,
+            message: "Still awaiting approval. Call pair again with this device_code to keep waiting."
+          })
+        }]
+      };
+  }
+}
 var server = new Server(
   { name: "paigy", version: "0.0.0" },
   {
@@ -164,7 +267,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
   tools: [
     {
       name: "pair",
-      description: "Pair this agent with the user's Paigy account (one-time) \u2014 required before notify_user/await_reply work. It does NOT open a browser; the user enters the code in the Paigy app (or scans `qr`). Step 1: call with NO args \u2014 returns { user_code, device_code, qr, user_message }. Then END YOUR TURN immediately, replying with `user_message` (the bare code) as your ENTIRE message \u2014 do NOT chain the step-2 call in the same turn, or the code text is dropped before the user ever sees it (this is the #1 pairing bug). Step 2 (a SEPARATE later turn, after the user says they've entered it): call with that device_code to poll for approval; on { status:'pending' } call again to keep waiting; on { status:'awaiting_confirmation' } (E2EE) show the bare `user_message` verify code and end the turn again, polling on the next. The leading text block of every result already states the code plainly, so it shows even if you emit no prose.",
+      description: "Pair this agent with the user's Paigy account (one-time) \u2014 required before notify_user/await_reply work. It does NOT open a browser; the user enters the code in the Paigy app (or scans `qr`). Step 1: call with NO args \u2014 returns { user_code, device_code, qr, user_message } AND starts polling for approval in the background. SHOW the user `user_message` (the bare code) so it isn't buried in prose, THEN call step 2 \u2014 you can do both in the same turn (emit the code text first, then call pair). Step 2: call with that device_code to collect the result. Because approval is already being polled in the background, this returns the moment the user approves; on { status:'pending' } just call again to keep waiting; on { status:'awaiting_confirmation' } (E2EE) show the bare `user_message` verify code and call again to finish. The leading text block of every result states the code plainly, so it shows even if you emit no prose. On { status:'paired' } ALWAYS follow the `enable_prompt` \u2014 ask the user to allowlist Paigy's tools so notify/await don't prompt each time.",
       inputSchema: json(PairSchema)
     },
     {
@@ -172,6 +275,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       description: "Log out / unpair this agent from the user's Paigy account: revokes the token server-side (it stops working everywhere) and deletes the local ~/.paigy/token.json. Takes no arguments. After this, notify_user/await_reply won't work until the user pairs again with the pair tool.",
       inputSchema: json(z.object({}))
     },
+    {
+      name: "enable_tools",
+      description: "Allowlist Paigy's notify/await tools so they run WITHOUT an approval prompt each time \u2014 call this AFTER pairing, once the user has said yes to the `enable_prompt` (never without their consent). It writes the hosting tool's permission allowlist for you: `scope:'user'` (default) covers every project (~/.claude/settings.json), `scope:'project'` scopes it to this repo (.claude/settings.json). Merges into the existing file (never clobbers) and leaves pair/unpair OUT so they stay human-approved. Returns { ok, path, added, already } on success, or { ok:false, reason } when the host isn't Claude Code (add the ids to that tool's own allowlist by hand). Idempotent \u2014 re-running just reports everything already present.",
+      inputSchema: json(EnableToolsSchema)
+    },
     {
       name: "notify_user",
       description: "Notify the user via Paigy. Returns { notificationId, threadId } \u2014 pass notificationId to await_reply for the answer, threadId to notify_user to continue the conversation. THREADING REPLACES: a threaded follow-up SUPERSEDES your earlier pending items on that thread (they leave the user's inbox; the response reports supersededCount) \u2014 right for updates to one ask, WRONG for a checklist: send parallel to-dos as separate un-threaded notifications. SIMPLEST FORM \u2014 just state what you need: { ask: \"I need to know whether to deploy the auth fix \u2014 tests are green, staging verified\", urgencyHint: 'now'|'soon'|'whenever', needs?: [\"deploy?\", \"keep the flag?\"] }. Paigy's broker derives the title, answer shape, options, and delivery channel for you \u2014 prefer this unless you specifically need to control the exact options/shape. The fully-shaped form below remains available and unchanged (the two are mutually exclusive: send `ask` OR `context`+`select`). FULLY-SHAPED FORM: provide context.title (a specific, non-empty one-line headline \u2014 this is what the user sees first, and what shows on the ring for a call) and context.description (an array of standalone, non-empty detail chunks the user can selectively ask you to expand). Set `urgency`: 'inbox' (default) drops it silently in their inbox; 'push' is a quiet passive notification (no sound); 'banner' sends a time-sensitive banner/lock-screen push (a 'paige') they tap to open \u2014 for when you need them soon-ish but not enough to ring them; 'call' rings their phone now as a voice call \u2014 only when you genuinely need them in the moment (blocked/waiting, time-sensitive). This is the premier use case for Paigy: getting UNBLOCKED so you can keep working, not just reporting that you're stuck. The user started a big task and went to do something else \u2014 the cardinal failure is going idle on one small decision and silently waiting to be checked on, so they come back to find you never actually progressed. Judge urgency by how much WORK IS BLOCKED behind this decision (a lot of dependent downstream work \u2192 call, even if it's a single question), not by how many things happen to be pending \u2014 one blocking decision outweighs five independent low-stakes ones sitting in the inbox. Set `blocking: true` whenever that's the case, independent of `urgency` \u2014 it's what lets Paigy escalate this to a real call later on its own if it goes unanswered, even if you sent it at a lower urgency. Don't set it for things you could work around, defer, or where other useful work exists meanwhile. ON A CALL, your title + description are READ ALOUD by a voice \u2014 write them to be HEARD, not read: keep it short and conversational, front-load the ask, and refer to things BY NAME, not by ID or code (say 'the pull request about the agents page', not 'PR #235'; 'the login-bug ticket', not 'ABC-1234'). Spell out only what's natural to say out loud. MATCH the answer shape to the question \u2014 `select` is required; pick the best tool for the job, not always yes/no. The user can ALWAYS add free text on top of any shape, so structuring loses nothing. Choose `select`: yes/no \u2192 select:'confirm' \u2192 {kind:'confirm', approved:boolean}. Approve/deny an action \u2192 select:'confirm' + confirmStyle:'approve' \u2192 {kind:'confirm', approved:boolean}. Both are answerable right from the banner \u2014 no need to open the app. Pick one of several \u2192 options + select:'one' \u2192 {kind:'option', optionId}. Pick several / a subset \u2192 options + select:'many' \u2192 {kind:'multi', optionIds:[...]}. Rank or prioritize \u2192 options + select:'rank', user taps in preferred order \u2192 {kind:'ranked', optionIds:[...]}. One/many/rank/text all need the user to open the app to answer \u2014 only confirm is answerable straight from the banner. Options carry no ids \u2014 they're assigned by position ('1', '2', \u2026), and the answer's optionId(s) are those positions. For visual choices give each option a sandboxed `html` or an `image` preview (e.g. layout/UI alternatives); use `visuals` for images that set context for the whole question. select:'text' = free-form reply only (plain updates, or answers that genuinely can't be structured). If a reply comes back as {kind:'clarify', chunks:[...]}, the user wants more detail on those chunks \u2014 respond via notify_user with the SAME threadId and an expanded description. Pass `threadId` from a prior notify_user result or an await_reply reply to continue that conversation thread; omit it to start a new one. To follow up on a call (e.g. the user asked you to 'call me back when it's done'), reuse the threadId from that call's reply so it threads as the same conversation.",
@@ -213,7 +321,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "handoff",
-      description: "Deposit your working context for a SUCCESSOR agent \u2014 what you did, what's left, links, gotchas \u2014 as one note on a thread ({ title, notes[] }). This does NOT ring the user or enter their inbox: it's context, not a question. The successor reads it back with get_thread. Pass `target` (a sibling connection's token id or agent nickname, SAME account only) to hand off DIRECTLY to that agent \u2014 the note is dispatched to it as a request it picks up. Omit `target` to leave the thread for the user to hand off to an agent themselves in the app. Pass `threadId` to land the handoff on an existing conversation; omit it to mint a fresh thread. Returns { threadId }.",
+      description: "Deposit your working context for a SUCCESSOR agent \u2014 what you did, what's left, links, gotchas \u2014 as one note on a thread ({ title, notes[] }). This does NOT ring the user or enter their inbox: it's context, not a question. The successor reads it back with get_thread. Pass `target` (a sibling connection's token id or agent name, SAME account only) to hand off DIRECTLY to that agent \u2014 the note is dispatched to it as a request it picks up. Omit `target` to leave the thread for the user to hand off to an agent themselves in the app. Pass `threadId` to land the handoff on an existing conversation; omit it to mint a fresh thread. Returns { threadId }.",
       inputSchema: json(HandoffSchema)
     }
   ]
@@ -235,6 +343,7 @@ async function handleTool(request) {
         const code = await requestCode(void 0, offer);
         saveKeyFile({ ...keyFile, userCode: code.user_code });
         writeSurface("pairing code", code.user_code, code.expires_in);
+        startBackgroundPair(code.device_code, code.expires_in * 1e3);
         const qr = qrcode(0, "M");
         qr.addData(code.verification_uri_complete);
         qr.make();
@@ -254,63 +363,15 @@ Enter it in the Paigy app: Inbox \u2192 Add a new agent.` },
                 user_message: `# ${code.user_code}
 
 Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
-                message: `STOP HERE: end your turn now with \`user_message\` as your entire reply (the bare code, nothing else) \u2014 do NOT call pair again in this same turn, or the code text is dropped before the user sees it. Do NOT open a browser. Poll for approval by calling pair with this device_code on your NEXT turn, after you've shown the code. The user may prefer scanning \`qr\` (print it verbatim in a fenced code block on request).`
+                message: `SHOW the user \`user_message\` now (the bare code) so it isn't buried in prose, then call pair again with this device_code to finish \u2014 I'm ALREADY polling for approval in the background, so that call returns the moment they approve (it may still be pending, just call it again). You can do both in this same turn: emit the code text first, THEN call pair. Do NOT open a browser. The user may prefer scanning \`qr\` (print it verbatim in a fenced code block on request).`
               })
             }
           ]
         };
       }
-      let kf = readKeyFile();
-      const start = Date.now();
       const capMs = 9e4;
-      while (Date.now() - start < capMs) {
-        let step;
-        try {
-          step = await pairStep(device_code, kf);
-        } catch (e) {
-          clearSurface();
-          throw e;
-        }
-        if (step.kind === "e2ee_aborted") {
-          deleteKeyFile();
-          kf = null;
-          await sleep(2e3);
-          continue;
-        }
-        if (step.kind === "awaiting_confirm") {
-          return awaitingConfirmResult(step.sas, device_code);
-        }
-        if (step.kind === "paired") {
-          saveToken(step.token);
-          if (!step.sas || !kf) {
-            deleteKeyFile();
-            return pairedResult(step.token);
-          }
-          const finalDeadline = Math.min(Date.now() + 1e4, start + capMs);
-          let e2ee = false;
-          while (Date.now() < finalDeadline) {
-            const cred = kf.userCode ? await fetchCredential(kf.userCode) : null;
-            if (cred && step.uikPub) {
-              e2ee = finalizeE2ee(kf, cred, step.uikPub);
-              break;
-            }
-            await sleep(2e3);
-          }
-          if (!e2ee) deleteKeyFile();
-          return pairedResult(step.token, step.sas, void 0, e2ee);
-        }
-        await sleep(2e3);
-      }
-      return {
-        content: [{
-          type: "text",
-          text: JSON.stringify({
-            status: "pending",
-            device_code,
-            message: "Still awaiting approval after ~90s. Call pair again with this device_code to keep waiting."
-          })
-        }]
-      };
+      const outcome = await joinBackgroundPair(device_code, capMs) ?? await resolvePairing(device_code, capMs);
+      return renderPairOutcome(outcome, device_code);
     }
     case "unpair": {
       const token = readToken();
@@ -324,6 +385,7 @@ Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
       }
       const removed = deleteToken();
       deleteKeyFile();
+      cancelBackgroundPair();
       return {
         content: [{
           type: "text",
@@ -336,6 +398,12 @@ Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
         }]
       };
     }
+    case "enable_tools": {
+      const { scope } = EnableToolsSchema.parse(request.params.arguments ?? {});
+      const result = enablePaigyTools(scope ?? "user");
+      const message = result.ok ? `Allowlisted ${result.added.length} Paigy tool(s) in ${result.path}` + (result.already.length ? ` (${result.already.length} already present).` : ".") + " They now run without an approval prompt; restart/reload the tool if it caches settings. pair/unpair stay human-approved." : result.reason;
+      return { content: [{ type: "text", text: JSON.stringify({ ...result, message }) }] };
+    }
     // `notify` (the general routing verb) and `notify_user` (its alias) share one handler.
     case "notify":
     case "notify_user": {

package/dist/listen.js

@@ -2,11 +2,11 @@
 import {
   WAKE_EVENT,
   wakeChannel
-} from "./chunk-MH6AHNUI.js";
+} from "./chunk-SLWESECN.js";
 import {
   checkReplies,
   registerDelivery
-} from "./chunk-RMTTO6BI.js";
+} from "./chunk-VWQQ3VJF.js";
 
 // src/listen.ts
 import { createClient } from "@supabase/supabase-js";

package/dist/onboard.js

@@ -3,7 +3,7 @@ import {
   autoConfigureClients,
   claudeInstallHint,
   openBrowser
-} from "./chunk-IMIXCPTN.js";
+} from "./chunk-HO3OJHRA.js";
 import {
   AGENT_NAME,
   TOKEN_PATH,
@@ -11,7 +11,7 @@ import {
   requestCode,
   saveToken,
   sleep
-} from "./chunk-RMTTO6BI.js";
+} from "./chunk-VWQQ3VJF.js";
 
 // src/onboard.ts
 async function main() {
@@ -39,9 +39,8 @@ Paigy MCP onboarding (agent: "${AGENT_NAME}")
 
 Paired! Token saved to ${TOKEN_PATH} (mode 0600).`);
         console.log("Treat this token like a password \u2014 it grants account access. Never log, echo, or commit it.");
-        console.log(`  Nickname : ${token.nickname}`);
-        console.log(`  Agent    : ${token.agent}`);
-        console.log(`  Device   : ${token.device ?? "(none)"}
+        console.log(`  Name   : ${token.name}`);
+        console.log(`  Device : ${token.device ?? "(none)"}
 `);
         const registered = autoConfigureClients();
         if (registered.length) {

package/dist/statusline.js

@@ -6,7 +6,7 @@ import {
   BACKEND_URL,
   reach,
   readToken
-} from "./chunk-RMTTO6BI.js";
+} from "./chunk-VWQQ3VJF.js";
 
 // src/statusline.ts
 import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paigy/mcp",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "description": "Paigy MCP server — a voice inbox for your AI agents. Lets an agent notify a user and await their reply.",
   "license": "MIT",
   "type": "module",
@@ -22,13 +22,6 @@
     "url": "git+https://github.com/mauurda/paigy.git",
     "directory": "apps/mcp"
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "prepublishOnly": "pnpm --filter @paigy/schema build && pnpm --filter @paigy/crypto build && pnpm --filter @paigy/sdk build && pnpm build"
-  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
     "@supabase/supabase-js": "^2.47.10",
@@ -38,13 +31,19 @@
     "zod-to-json-schema": "^3.24.1"
   },
   "devDependencies": {
-    "@paigy/crypto": "workspace:*",
-    "@paigy/schema": "workspace:*",
-    "@paigy/sdk": "workspace:*",
     "@types/node": "^22.0.0",
     "@types/qrcode-generator": "^1.0.6",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "vitest": "^2.1.8",
+    "@paigy/crypto": "0.0.0",
+    "@paigy/sdk": "0.1.0",
+    "@paigy/schema": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
 }