@paigy/mcp 0.13.0 → 0.14.1

package/dist/{chunk-KNCXKXUG.js → chunk-OSQ3UXY6.js}

@@ -8,7 +8,7 @@ import {
   readKeyFile,
   sealFields,
   verifiedRecipients
-} from "./chunk-O6W2T6D2.js";
+} from "./chunk-WGOGS2JC.js";
 
 // src/client.ts
 import { existsSync, readFileSync } from "fs";

package/dist/{chunk-O6W2T6D2.js → chunk-WGOGS2JC.js}

@@ -2597,6 +2597,15 @@ var MissedCallSchema = z.enum([
   "inbox",
   "dismiss"
 ]);
+var BrokerTuningSchema = z.object({
+  /** 'none' = skip the spoken ack after a mapped answer (power users find it slow). */
+  ackVerbosity: z.enum(["normal", "none"]).optional(),
+  /** How readily the mapper asks its one clarification: 'low' = only when truly
+   *  uninterpretable, 'high' = whenever not fully certain. */
+  clarifyEagerness: z.enum(["low", "normal", "high"]).optional(),
+  /** The user's own shorthand: when they say `say`, they mean `mean`. */
+  phrasebook: z.array(z.object({ say: z.string().min(1).max(60), mean: z.string().min(1).max(120) })).max(24).optional()
+});
 var UserSettingsSchema = z.object({
   permissions: z.object({
     call: z.boolean(),
@@ -2622,7 +2631,10 @@ var UserSettingsSchema = z.object({
    *  settings object without it can't silently flip the account's E2EE state.
    *  Absent = leave unchanged on write, 'off' on read (see store.ts). The demo
    *  account is plaintext by construction and refuses any non-'off' value. */
-  e2eeMode: z.enum(["off", "on"]).optional()
+  e2eeMode: z.enum(["off", "on"]).optional(),
+  /** Rung-2 broker tuning (#381). Optional and NOT defaulted, same stale-client
+   *  clobber guard as voiceMode: absent = leave unchanged on write. */
+  broker: BrokerTuningSchema.optional()
 });
 var HistoryItemSchema = z.object({
   id: z.string(),
@@ -3091,6 +3103,32 @@ var PROTO = "paigy-pair-v2|sas=24";
 var SAS_BITS = 24;
 var TOKEN_PATH = join(homedir(), ".paigy", "token.json");
 var KEY_PATH = join(homedir(), ".paigy", "key.json");
+var SURFACE_PATH = join(homedir(), ".paigy", "surface.json");
+function writeSurface(label, code, ttlSeconds) {
+  try {
+    mkdirSync(join(homedir(), ".paigy"), { recursive: true });
+    writeFileSync(
+      SURFACE_PATH,
+      JSON.stringify({ label, code, expiresAt: Date.now() + ttlSeconds * 1e3 }),
+      { mode: 384 }
+    );
+  } catch {
+  }
+}
+function clearSurface() {
+  try {
+    rmSync(SURFACE_PATH, { force: true });
+  } catch {
+  }
+}
+function readSurface(now = Date.now) {
+  try {
+    const { label, code, expiresAt } = JSON.parse(readFileSync(SURFACE_PATH, "utf8"));
+    return label && code && typeof expiresAt === "number" && expiresAt > now() ? { label, code } : null;
+  } catch {
+    return null;
+  }
+}
 function openBrowser(url) {
   const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
   const args = platform() === "win32" ? ["/c", "start", url] : [url];
@@ -3290,6 +3328,9 @@ export {
   reach,
   AGENT_NAME,
   TOKEN_PATH,
+  writeSurface,
+  clearSurface,
+  readSurface,
   openBrowser,
   saveToken,
   sleep,

package/dist/index.js

@@ -6,16 +6,16 @@ import {
   scheduleCallback,
   setTaskState,
   submitNotification
-} from "./chunk-KNCXKXUG.js";
+} from "./chunk-OSQ3UXY6.js";
 import {
   NotifyRequestSchema,
   ScheduleCallbackSchema,
   SetTaskStateSchema,
+  clearSurface,
   deleteKeyFile,
   deleteToken,
   fetchCredential,
   finalizeE2ee,
-  openBrowser,
   pairStep,
   readKeyFile,
   readToken,
@@ -24,8 +24,9 @@ import {
   saveKeyFile,
   saveToken,
   sleep,
-  startE2ee
-} from "./chunk-O6W2T6D2.js";
+  startE2ee,
+  writeSurface
+} from "./chunk-WGOGS2JC.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -137,6 +138,7 @@ function detectGit() {
   };
 }
 function pairedResult(token, sas, note, e2ee) {
+  clearSurface();
   const base = {
     status: "paired",
     nickname: token.nickname,
@@ -152,6 +154,7 @@ function pairedResult(token, sas, note, e2ee) {
   return { content: [{ type: "text", text: JSON.stringify(base) }] };
 }
 function awaitingConfirmResult(sas, device_code) {
+  writeSurface("verify code", sas, 600);
   return {
     content: [{
       type: "text",
@@ -160,8 +163,9 @@ function awaitingConfirmResult(sas, device_code) {
         e2ee: true,
         sas,
         device_code,
-        verify_message: `This account requires end-to-end encryption, so no access token is issued until you confirm the pairing. Ask the user to check that this code matches the one on their phone and CONFIRM it there: ${sas}. Pairing is NOT complete yet.`,
-        message: "The user must compare the SAS above and confirm on their phone. Once they do, call pair again with this device_code to finish \u2014 the token is granted only after they confirm."
+        user_message: `# ${sas}`,
+        verify_message: `Send \`user_message\` to the user VERBATIM as your entire next message \u2014 it is pre-composed; do not rewrite or wrap it. YOUR NEXT MESSAGE TO THE USER MUST BE EXACTLY THIS CODE AND NOTHING ELSE, displayed large (a markdown heading): ${sas} \u2014 it is the verification code they must compare and type on their phone. Do not wrap it in explanation; every extra sentence buries it. This code REPLACES any earlier one (older pairing attempts are now stale).`,
+        message: "No token is issued until the user confirms the code match on their phone (E2EE account). After sending the bare code, call pair again with this device_code to keep waiting \u2014 the token arrives only after they confirm."
       })
     }]
   };
@@ -187,7 +191,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       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. 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.",
+      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.",
       inputSchema: json(NotifyRequestSchema)
     },
     {
@@ -220,7 +224,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const { keyFile, offer } = startE2ee();
         const code = await requestCode(void 0, offer);
         saveKeyFile({ ...keyFile, userCode: code.user_code });
-        openBrowser(code.verification_uri_complete);
+        writeSurface("pairing code", code.user_code, code.expires_in);
         const qr = qrcode(0, "M");
         qr.addData(code.verification_uri_complete);
         qr.make();
@@ -234,7 +238,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
               device_code: code.device_code,
               expires_in: code.expires_in,
               qr: qr.createASCII(1, 2),
-              message: "Show the user verification_uri_complete and user_code (their browser should have opened). If they'd rather scan than switch to a browser themselves, print `qr` verbatim in a fenced code block (monospace, no extra indentation) \u2014 it's a scannable QR code for the same link. After they approve, call pair again with this device_code to finish."
+              user_message: `# ${code.user_code}
+
+Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
+              message: `Send \`user_message\` to the user VERBATIM as your entire next message \u2014 it is pre-composed; do not rewrite or wrap it. YOUR NEXT MESSAGE TO THE USER MUST BE EXACTLY THIS CODE displayed large (a markdown heading): ${code.user_code} \u2014 plus ONE short line: enter it in the Paigy app (Inbox \u2192 Add a new agent). No other prose. Do NOT open a browser for the user. If their phone is handy they may prefer scanning \`qr\` (print it verbatim in a fenced code block on request). Then immediately call pair again with this device_code \u2014 it polls for the approval.`
             })
           }]
         };
@@ -243,7 +250,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const start = Date.now();
       const capMs = 9e4;
       while (Date.now() - start < capMs) {
-        const step = await pairStep(device_code, kf);
+        let step;
+        try {
+          step = await pairStep(device_code, kf);
+        } catch (e) {
+          clearSurface();
+          throw e;
+        }
         if (step.kind === "e2ee_aborted") {
           deleteKeyFile();
           kf = null;

package/dist/listen.js

@@ -3,11 +3,11 @@ import { createRequire as __createRequire } from 'node:module'; const require =
 import {
   checkReplies,
   registerDelivery
-} from "./chunk-KNCXKXUG.js";
+} from "./chunk-OSQ3UXY6.js";
 import {
   WAKE_EVENT,
   wakeChannel
-} from "./chunk-O6W2T6D2.js";
+} from "./chunk-WGOGS2JC.js";
 
 // src/listen.ts
 import { createClient } from "@supabase/supabase-js";

package/dist/onboard.js

@@ -8,7 +8,7 @@ import {
   requestCode,
   saveToken,
   sleep
-} from "./chunk-O6W2T6D2.js";
+} from "./chunk-WGOGS2JC.js";
 
 // src/onboard.ts
 async function main() {

package/dist/statusline.js

@@ -2,8 +2,9 @@
 import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   BACKEND_URL,
+  readSurface,
   readToken
-} from "./chunk-O6W2T6D2.js";
+} from "./chunk-WGOGS2JC.js";
 
 // src/statusline.ts
 import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
@@ -18,7 +19,8 @@ var MODE_LABEL = {
   all_calls: "all calls",
   silent: "silent"
 };
-function render(status) {
+function render(status, surface = null) {
+  if (surface) return `paigy \u26A0 ${surface.label}: ${surface.code}`;
   if (!status) return "paigy: unpaired";
   return `paigy: ${MODE_LABEL[status.sessionMode]} \xB7 ${status.phone ? "phone \u2713" : "no phone"}`;
 }
@@ -44,6 +46,8 @@ async function fetchStatus(token) {
   return await res.json();
 }
 async function main() {
+  const surface = readSurface();
+  if (surface) return render(null, surface);
   const token = readToken();
   if (!token) return render(null);
   const cached = readCache();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paigy/mcp",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "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",