@paigy/mcp 0.12.2 → 0.14.0

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

@@ -1,17 +1,77 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   BACKEND_URL,
+  deriveAsk,
   fetchRoster,
   openSealedAnswer,
   reach,
   readKeyFile,
   sealFields,
   verifiedRecipients
-} from "./chunk-BJ2J2AOB.js";
+} from "./chunk-WGOGS2JC.js";
 
 // src/client.ts
 import { existsSync, readFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
+
+// src/when.ts
+var WORD_NUMS = {
+  a: 1,
+  an: 1,
+  one: 1,
+  two: 2,
+  three: 3,
+  four: 4,
+  five: 5,
+  six: 6,
+  seven: 7,
+  eight: 8,
+  nine: 9,
+  ten: 10,
+  fifteen: 15,
+  twenty: 20,
+  thirty: 30,
+  forty: 40,
+  "forty-five": 45,
+  fifty: 50,
+  sixty: 60,
+  "half an": 0.5,
+  "a couple of": 2,
+  "a few": 3
+};
+function untilHour(hour, now) {
+  const due = new Date(now);
+  due.setHours(hour, 0, 0, 0);
+  if (due.getTime() <= now.getTime()) due.setDate(due.getDate() + 1);
+  return Math.round((due.getTime() - now.getTime()) / 1e3);
+}
+function parseDue(detail, now = /* @__PURE__ */ new Date()) {
+  const t = detail.toLowerCase().trim();
+  const rel = /(?:^|\b)in\s+(half an|a couple of|a few|an?|[\w-]+|\d+)\s*(minutes?|mins?|hours?|hrs?)\b/.exec(t);
+  if (rel) {
+    const n = /^\d+$/.test(rel[1]) ? Number(rel[1]) : WORD_NUMS[rel[1]];
+    if (n !== void 0) {
+      const unit = rel[2].startsWith("h") ? 3600 : 60;
+      return Math.round(n * unit);
+    }
+  }
+  if (/after lunch|lunchtime/.test(t)) return untilHour(13, now);
+  if (/tomorrow/.test(t)) {
+    const due = new Date(now);
+    due.setDate(due.getDate() + 1);
+    due.setHours(9, 0, 0, 0);
+    return Math.round((due.getTime() - now.getTime()) / 1e3);
+  }
+  if (/tonight|this evening/.test(t)) {
+    return now.getHours() < 20 ? untilHour(20, now) : 3600;
+  }
+  if (/end of (the )?day|eod/.test(t)) return untilHour(17, now);
+  if (/later|in a (bit|while)/.test(t)) return 1800;
+  return null;
+}
+
+// src/client.ts
 var TOKEN_PATH = join(homedir(), ".paigy", "token.json");
 function loadToken() {
   if (process.env.PAIGY_TOKEN) return process.env.PAIGY_TOKEN;
@@ -33,6 +93,7 @@ function ensureAuthed(res) {
 async function sealForE2ee(req, token, deps = {}) {
   const keyFile = (deps.readKeyFile ?? readKeyFile)();
   if (!keyFile?.e2ee) return req;
+  req = deriveAsk(req);
   if (!keyFile.uikPub) {
     throw new Error("E2EE pairing is missing its pinned identity key (key.json.uikPub) \u2014 re-pair; refusing to send plaintext.");
   }
@@ -92,11 +153,21 @@ async function awaitReply(notificationId, opts = {}) {
   }
 }
 function decryptItem(item) {
-  if (item.type !== "reply" || !item.sealed) return item;
-  const answer = decryptAnswer(item);
-  const { sealed: _s, ...rest } = item;
+  if (item.type !== "reply") return item;
+  const enriched = { ...item, intents: landIntents(item.intents) };
+  if (!enriched.sealed) return enriched;
+  const answer = decryptAnswer(enriched);
+  const { sealed: _s, ...rest } = enriched;
   return { ...rest, answer };
 }
+function landIntents(intents) {
+  if (!intents?.length) return intents;
+  return intents.map((i) => {
+    if (i.kind !== "defer") return i;
+    const due = parseDue(i.detail);
+    return due !== null ? { ...i, dueInSeconds: due } : i;
+  });
+}
 async function checkReplies() {
   const token = loadToken();
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/pending`, {
@@ -106,7 +177,8 @@ async function checkReplies() {
   const pending = await res.json();
   return {
     ...pending,
-    replies: pending.replies.map((r) => {
+    replies: pending.replies.map((raw) => {
+      const r = { ...raw, intents: landIntents(raw.intents) };
       if (!r.sealed) return r;
       const { sealed: _s, ...rest } = r;
       return { ...rest, answer: decryptAnswer(r) };

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

@@ -1,3 +1,4 @@
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -2286,6 +2287,9 @@ var NotifyRequestSchema = z.object({
   options: z.array(OptionSchema.omit({ id: true })).min(1).optional().describe(
     "The choices, in order \u2014 required when select is 'one'/'many'/'rank', omitted otherwise. Ids are assigned automatically by position ('1', '2', \u2026); the user's answer references them as optionId(s)."
   ),
+  points: z.array(z.string().min(1)).optional().describe(
+    "The distinct things you need answered, each a short phrase \u2014 on a call the broker keeps the conversation going until each is addressed, and the reply reports which were covered, so a half-answer is never silently returned as final. Omit for single-part asks."
+  ),
   visuals: z.array(VisualSchema).optional().describe(
     "Images attached to the message itself \u2014 context for the whole question (a screenshot, a chart). For a preview on one selectable choice, use that option's `html`/`image` instead."
   ),
@@ -2317,8 +2321,22 @@ var NotifyRequestSchema = z.object({
     options: z.lazy(() => EnvelopeSchema).optional(),
     visuals: z.lazy(() => EnvelopeSchema).optional()
   }).optional(),
-  select: z.enum(["one", "many", "rank", "confirm", "text"]).describe(
-    "How the user answers \u2014 required, pick the shape that fits the question: 'one' = pick one option, 'many' = pick several, 'rank' = pick & order (each needs `options`); 'confirm' = yes/no or approve/deny; 'text' = free-form reply only (status updates, open questions). 'confirm' and 'text' take no options."
+  select: z.enum(["one", "many", "rank", "confirm", "text"]).optional().describe(
+    "How the user answers \u2014 required on the fully-shaped form, pick the shape that fits the question: 'one' = pick one option, 'many' = pick several, 'rank' = pick & order (each needs `options`); 'confirm' = yes/no or approve/deny; 'text' = free-form reply only (status updates, open questions). 'confirm' and 'text' take no options. Omit only when sending the simplified `ask` form \u2014 the broker picks the shape."
+  ),
+  /** The simplified form (#395): instead of shaping the notification yourself
+   *  (context/select/options/urgency), state what you need to learn and why it
+   *  matters now — the broker derives the optimal shape and channel. Mutually
+   *  exclusive with `context` (and never sent alongside `envelope`: E2EE pairings
+   *  derive agent-side before sealing, so the server only ever shapes plaintext). */
+  ask: z.string().min(1).optional().describe(
+    'SIMPLIFIED FORM \u2014 state in plain prose what you need to learn from the user and why it matters now (e.g. "I need to know whether to deploy the auth fix \u2014 tests are green, staging verified"). Paigy derives the title, answer shape, options, and delivery channel for you. Mutually exclusive with context/select/options \u2014 send one form or the other.'
+  ),
+  needs: z.array(z.string().min(1)).optional().describe(
+    "With `ask` only: the distinct things you need answered when the ask is multi-part \u2014 becomes the coverage contract (`points`), so a half-answer is never silently final."
+  ),
+  urgencyHint: z.enum(["whenever", "soon", "now"]).optional().describe(
+    "With `ask` only: how urgently you need the answer \u2014 'whenever' (inbox), 'soon' (worth a heads-up), 'now' (you're blocked this minute). A hint, not a command: the user's settings still have the final word."
   ),
   confirmStyle: z.enum(["yesno", "approve"]).default("yesno").describe(
     "Labels for a select:'confirm' paige \u2014 'yesno' (Yes/No) or 'approve' (Approve/Deny). Ignored unless select is 'confirm'."
@@ -2335,16 +2353,48 @@ var NotifyRequestSchema = z.object({
       if (r[f] !== void 0)
         ctx.addIssue({ code: z.ZodIssueCode.custom, path: [f], message: `E2EE request must not carry plaintext ${f} \u2014 it's sealed in envelope.${f}` });
     }
+    if (r.points !== void 0)
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["points"], message: "E2EE request must not carry plaintext points" });
+    if (r.ask !== void 0)
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["ask"], message: "E2EE request must not carry a plaintext ask \u2014 derive the shape agent-side and seal it" });
+    if (r.needs !== void 0)
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["needs"], message: "E2EE request must not carry plaintext needs" });
+    return;
+  }
+  if (r.ask !== void 0) {
+    for (const f of ["context", "options", "select", "points", "visuals"]) {
+      if (r[f] !== void 0)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives it (use \`needs\` for multi-part asks)` });
+    }
     return;
   }
+  if (r.needs !== void 0 || r.urgencyHint !== void 0)
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["needs"], message: "needs/urgencyHint belong to the simplified `ask` form \u2014 with a shaped request use points/urgency" });
   if (!r.context)
     ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["context"], message: "context is required (plaintext path)" });
+  if (!r.select)
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["select"], message: "select is required on the shaped form" });
   const needsOptions = r.select === "one" || r.select === "many" || r.select === "rank";
   if (needsOptions && !r.options?.length)
     ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["options"], message: `select:'${r.select}' requires options` });
   if (!needsOptions && r.options?.length)
     ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["options"], message: `select:'${r.select}' takes no options` });
 });
+function deriveAsk(req) {
+  if (!req.ask) return req;
+  const text = req.ask.trim();
+  const firstSentence = (/^[^.!?\n]+[.!?]?/.exec(text)?.[0] ?? text).trim();
+  const title = firstSentence.length > 90 ? `${firstSentence.slice(0, 87).trimEnd()}\u2026` : firstSentence;
+  const urgency = req.urgencyHint === "now" ? "call" : req.urgencyHint === "soon" ? "banner" : req.urgencyHint === "whenever" ? "inbox" : req.urgency;
+  const { ask: _ask, needs, urgencyHint: _hint, ...rest } = req;
+  return {
+    ...rest,
+    context: { title, description: [text] },
+    select: "text",
+    urgency,
+    ...needs?.length ? { points: needs } : {}
+  };
+}
 var NotifyStatusSchema = z.enum(["pending", "answered", "ignored"]);
 var AgentStateSchema = z.enum(["idle", "in_progress", "completed", "needs_input"]);
 var SetTaskStateSchema = z.object({
@@ -2364,6 +2414,15 @@ var UserAnswerSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("confirm"), approved: z.boolean() }),
   z.object({ kind: z.literal("turns"), turns: z.array(TurnSchema).min(1) })
 ]);
+var IntentSchema = z.object({
+  kind: z.enum(["defer", "delegate", "channel"]),
+  detail: z.string(),
+  /** Landed defer (#397): the MCP parses common spoken forms ("in 20 minutes",
+   *  "after lunch") against the agent machine's clock — the user's — and attaches
+   *  the seconds, ready to pass straight to schedule_callback. Absent when the
+   *  detail didn't parse (the agent interprets it) or the kind isn't defer. */
+  dueInSeconds: z.number().int().positive().optional()
+});
 var AwaitItemSchema = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("reply"),
@@ -2376,7 +2435,15 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
      *  against `ignored` as tampering. Absent = today's plaintext answer (in `answer`).
      *  On a sealed reply the plaintext `answer` is a placeholder (kind reflects only
      *  the `ignored` bit) — never the real content, which stays sealed. */
-    sealed: z.lazy(() => SealedAnswerSchema).optional()
+    sealed: z.lazy(() => SealedAnswerSchema).optional(),
+    /** Broker extras (#381), present when the answer was mapped from a call: next
+     *  steps the user attached ("call me after lunch" → defer — act on it via
+     *  schedule_callback) and the raw words the shaped answer was mapped from. */
+    intents: z.array(IntentSchema).optional(),
+    transcript: z.string().optional(),
+    /** Coverage report (#396), when the ask declared `points`: which of them this
+     *  answer addressed. Missing points = re-ask or proceed knowingly partial. */
+    covered: z.array(z.string()).optional()
   }),
   z.object({
     type: z.literal("remind"),
@@ -2404,7 +2471,14 @@ var PendingRepliesSchema = z.object({
       /** E2EE: the sealed answer (opaque envelope + plaintext `ignored` hint) when the
        *  pairing is E2EE — the agent opens it and re-derives the real answer. Absent =
        *  plaintext answer (in `answer`). See AwaitItemSchema's reply variant. */
-      sealed: z.lazy(() => SealedAnswerSchema).optional()
+      sealed: z.lazy(() => SealedAnswerSchema).optional(),
+      /** Broker extras (#381): next steps the user attached to a call-mapped answer
+       *  ("call me after lunch" → defer — act on it via schedule_callback) and the
+       *  raw words the shaped answer was mapped from. */
+      intents: z.array(IntentSchema).optional(),
+      transcript: z.string().optional(),
+      /** Coverage report (#396): which declared `points` this answer addressed. */
+      covered: z.array(z.string()).optional()
     })
   ),
   pending: z.array(
@@ -2436,22 +2510,30 @@ var NotifyResponseSchema = z.object({
   answer: UserAnswerSchema.optional(),
   answeredAt: z.string().datetime().optional()
 });
-var IntentSchema = z.object({
-  kind: z.enum(["defer", "delegate", "channel"]),
-  detail: z.string()
-});
 var UserResponseSchema = z.object({
   requestId: z.string(),
   answer: UserAnswerSchema,
   answeredAt: z.string().datetime(),
   intents: z.array(IntentSchema).optional(),
-  transcript: z.string().optional()
+  transcript: z.string().optional(),
+  /** E2EE: the sealed answer (opaque envelope + plaintext `ignored` hint) when the item was
+   *  E2EE-sealed. Present → the server persists it opaquely and branches status on `ignored`;
+   *  the plaintext `answer` is a placeholder (`{ kind: "ignored" }`) the server ignores for a
+   *  sealed row. Absent = today's plaintext answer, unchanged. */
+  sealed: z.lazy(() => SealedAnswerSchema).optional(),
+  /** Coverage report (#396): which of the ask's declared `points` were addressed. */
+  covered: z.array(z.string()).optional()
 });
 var InboxItemSchema = z.object({
   id: z.string(),
   status: NotifyStatusSchema,
   context: ContextSchema,
   options: z.array(OptionSchema).optional(),
+  /** The ask's declared coverage points (#396), when the agent sent them. */
+  points: z.array(z.string()).optional(),
+  /** On a replied detail (#397): the next steps the user attached to the answer
+   *  ("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(),
@@ -2478,7 +2560,22 @@ var InboxItemSchema = z.object({
    *  inbox's blocking badge and the extra confirm step before dismissing it. */
   blocking: z.boolean().default(false),
   /** The user's locked-in answer; present only for replied items (GET /api/replied/:id). */
-  answer: UserAnswerSchema.optional()
+  answer: UserAnswerSchema.optional(),
+  /** E2EE (text lane): the sealed content this item carries when the pairing is E2EE, in
+   *  place of the plaintext `context`/`options`/`visuals` (which the operator would
+   *  otherwise read). A per-field map of opaque Envelopes — the SAME shape as
+   *  NotifyRequest.envelope. The native app decrypts it locally via openNotification;
+   *  web / an un-enrolled device can't and renders a locked placeholder. Absent = today's
+   *  plaintext item (context carries the cleartext), so plaintext items are unchanged. */
+  envelope: z.object({
+    context: z.lazy(() => EnvelopeSchema).optional(),
+    options: z.lazy(() => EnvelopeSchema).optional(),
+    visuals: z.lazy(() => EnvelopeSchema).optional()
+  }).optional(),
+  /** E2EE: the agent's device X25519 public key to seal the user's answer BACK to (the
+   *  sender the phone replies to). Sourced server-side from this item's pairing credential.
+   *  Present only alongside `envelope`; the phone seals via sealAnswer(answer, this, id). */
+  agentX25519: z.string().optional()
 });
 var SnoozeRequestSchema = z.object({
   requestId: z.string(),
@@ -2500,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(),
@@ -2525,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(),
@@ -2663,8 +2772,15 @@ var DeviceInfoSchema = z.object({
   proto: z.string().nullable().optional(),
   agent_commitment: z.string().nullable().optional(),
   // Ca
-  agent_reveal: PairingRevealSchema.nullable().optional()
+  agent_reveal: PairingRevealSchema.nullable().optional(),
   // present once the agent reveals
+  agent_credential: DeviceCredentialSchema.nullable().optional(),
+  // the phone's UIK-signed cred over the agent's keys — the agent fetches it here to finalizeE2ee
+  // The phone's reveal + identity key, exposed here so a GATED agent (e2ee_mode='on', token
+  // withheld until e2ee=true) can compute the SAS WITHOUT a token. Public keys — same safety
+  // class as agent_reveal above. Present only once the phone reveals; null otherwise.
+  phone_reveal: PairingRevealSchema.nullable().optional(),
+  uik_pub: z.string().nullable().optional()
 });
 var DeviceTokenRequestSchema = z.object({
   device_code: z.string(),
@@ -2987,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];
@@ -3099,6 +3241,13 @@ async function fetchCredential(userCode) {
   const body = await res.json().catch(() => ({}));
   return body.agent_credential ?? null;
 }
+async function fetchPhoneReveal(userCode) {
+  const res = await reach(`${BACKEND_URL}/api/device/info?code=${encodeURIComponent(userCode)}`);
+  if (!res.ok) return null;
+  const body = await res.json().catch(() => ({}));
+  if (!body.phone_reveal || !body.uik_pub) return null;
+  return { phone_reveal: body.phone_reveal, uik_pub: body.uik_pub };
+}
 async function pairStep(deviceCode, keyFile) {
   if (!keyFile) {
     const token2 = await pollToken(deviceCode);
@@ -3110,7 +3259,16 @@ async function pairStep(deviceCode, keyFile) {
     return token2 ? { kind: "paired", token: token2 } : { kind: "pending" };
   }
   const token = await pollToken(deviceCode, agentReveal(keyFile));
-  if (!token) return { kind: "pending" };
+  if (!token) {
+    const gated = keyFile.userCode ? await fetchPhoneReveal(keyFile.userCode) : null;
+    if (!gated) return { kind: "pending" };
+    try {
+      const sas = computeSAS(keyFile, cb, gated.phone_reveal, gated.uik_pub);
+      return { kind: "awaiting_confirm", sas, uikPub: gated.uik_pub };
+    } catch (e) {
+      return { kind: "e2ee_aborted", warning: e.message };
+    }
+  }
   if (!token.phone_reveal || !token.uik_pub) return { kind: "paired", token };
   try {
     const sas = computeSAS(keyFile, cb, token.phone_reveal, token.uik_pub);
@@ -3161,6 +3319,7 @@ function openSealedAnswer(sealed, keypair) {
 
 export {
   NotifyRequestSchema,
+  deriveAsk,
   SetTaskStateSchema,
   ScheduleCallbackSchema,
   WAKE_EVENT,
@@ -3169,6 +3328,9 @@ export {
   reach,
   AGENT_NAME,
   TOKEN_PATH,
+  writeSurface,
+  clearSurface,
+  readSurface,
   openBrowser,
   saveToken,
   sleep,

package/dist/index.js

@@ -1,20 +1,21 @@
 #!/usr/bin/env node
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   awaitReply,
   checkReplies,
   scheduleCallback,
   setTaskState,
   submitNotification
-} from "./chunk-DUTOEZEL.js";
+} from "./chunk-OSQ3UXY6.js";
 import {
   NotifyRequestSchema,
   ScheduleCallbackSchema,
   SetTaskStateSchema,
+  clearSurface,
   deleteKeyFile,
   deleteToken,
   fetchCredential,
   finalizeE2ee,
-  openBrowser,
   pairStep,
   readKeyFile,
   readToken,
@@ -23,8 +24,9 @@ import {
   saveKeyFile,
   saveToken,
   sleep,
-  startE2ee
-} from "./chunk-BJ2J2AOB.js";
+  startE2ee,
+  writeSurface
+} from "./chunk-WGOGS2JC.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -34,6 +36,52 @@ import {
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { execSync } from "child_process";
+
+// src/lint.ts
+var TITLE_MAX = 90;
+var CHUNKS_MAX = 8;
+var CHUNK_MAX = 300;
+var ASK_MAX = 600;
+var OPTION_MAX = 80;
+var NEEDS_MAX = 6;
+var UNSPEAKABLE = /```|\n/;
+function lintNotify(req) {
+  const problems = [];
+  if (req.ask !== void 0) {
+    if (req.ask.length > ASK_MAX)
+      problems.push(`ask is ${req.ask.length} chars \u2014 state the need and why it matters now in \u2264${ASK_MAX}; move detail into a smaller follow-up`);
+    if (UNSPEAKABLE.test(req.ask))
+      problems.push("ask contains code fences or newlines \u2014 write it as plain prose (it may be read aloud on a call)");
+    for (const n of req.needs ?? []) {
+      if (n.length > OPTION_MAX) problems.push(`need "${n.slice(0, 40)}\u2026" is too long \u2014 each need is a short phrase (\u2264${OPTION_MAX} chars)`);
+    }
+    if ((req.needs?.length ?? 0) > NEEDS_MAX)
+      problems.push(`${req.needs?.length} needs \u2014 cap at ${NEEDS_MAX}; a call can't cover more in one conversation, split the rest into a second ask`);
+    return problems;
+  }
+  const spoken = req.urgency === "call" || req.urgency === "banner";
+  if (req.context) {
+    if (req.context.title.length > TITLE_MAX)
+      problems.push(`title is ${req.context.title.length} chars \u2014 shorten to \u2264${TITLE_MAX} (it's what shows on the banner / gets spoken on a ring)`);
+    if (UNSPEAKABLE.test(req.context.title))
+      problems.push("title contains code fences or newlines \u2014 one plain-prose line");
+    if (req.context.description.length > CHUNKS_MAX)
+      problems.push(`${req.context.description.length} description chunks \u2014 cap at ${CHUNKS_MAX}; merge or drop the rest`);
+    for (const [i, chunk] of req.context.description.entries()) {
+      if (chunk.length > CHUNK_MAX)
+        problems.push(`description[${i}] is ${chunk.length} chars \u2014 split it into standalone points of \u2264${CHUNK_MAX}`);
+    }
+    if (spoken && UNSPEAKABLE.test(req.context.description.join(" ")))
+      problems.push("urgency is 'call'/'banner' but the description has code fences/newlines-in-chunk \u2014 rewrite in spoken register (it will be read aloud)");
+  }
+  for (const o of req.options ?? []) {
+    if (o.label.length > OPTION_MAX)
+      problems.push(`option label "${o.label.slice(0, 40)}\u2026" is ${o.label.length} chars \u2014 labels must read at a glance (\u2264${OPTION_MAX}); move detail into the description`);
+  }
+  return problems;
+}
+
+// src/index.ts
 import { z } from "zod";
 import qrcode from "qrcode-generator";
 
@@ -90,6 +138,7 @@ function detectGit() {
   };
 }
 function pairedResult(token, sas, note, e2ee) {
+  clearSurface();
   const base = {
     status: "paired",
     nickname: token.nickname,
@@ -104,6 +153,22 @@ function pairedResult(token, sas, note, e2ee) {
   if (note) base.note = note;
   return { content: [{ type: "text", text: JSON.stringify(base) }] };
 }
+function awaitingConfirmResult(sas, device_code) {
+  writeSurface("verify code", sas, 600);
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        status: "awaiting_confirmation",
+        e2ee: true,
+        sas,
+        device_code,
+        verify_message: `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."
+      })
+    }]
+  };
+}
 var server = new Server(
   { name: "paigy", version: "0.0.0" },
   {
@@ -125,17 +190,17 @@ 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. 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. 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)
     },
     {
       name: "await_reply",
-      description: "Wait for the user's reply to a specific notification you sent (pass the notificationId from notify_user). This is how you wait for your answer in-context. Polls ~5 min; returns { type:'reply', answer } when they respond, { type:'remind', remindInSeconds } on snooze (ScheduleWakeup then await_reply again), or { type:'idle' } (timed out this window, no answer yet). On idle, if this is genuinely still blocking you and you have nothing else useful to do meanwhile, just call await_reply again immediately \u2014 keep looping. This is how you actually deliver on the point of calling: the user steps away for a while and comes back to find you'd already continued the moment they answered, not idle waiting to be checked on. Don't give up after one window. Only stop looping to do other work (and check back later), or after an unreasonably long stretch (tens of minutes to hours) worth telling the user about instead. Scoped to that one notification \u2014 it NEVER returns replies meant for other notifications, so concurrent notify_user calls don't cross. A CALL answer can come back as {kind:'turns', turns:[{prompt,reply}]} \u2014 the ordered log of that call. Read turns[0].reply as the user's main instruction. Usually that's the only turn; if there are more (e.g. an end-of-call 'call me back when it's done / I have a blocking question'), read each one in order as a further follow-up instruction, not a single combined one. If they asked for a callback, re-engage in the SAME thread (notify_user with the reply's threadId) when the task is done or you hit a blocker \u2014 urgency:'call' for a blocker, 'banner'/'push'/'inbox' for done. Paigy has no scheduler; the callback is yours to send (use ScheduleWakeup/cron for timing).",
+      description: "Wait for the user's reply to a specific notification you sent (pass the notificationId from notify_user). This is how you wait for your answer in-context. Polls ~5 min; returns { type:'reply', answer } when they respond, { type:'remind', remindInSeconds } on snooze (ScheduleWakeup then await_reply again), or { type:'idle' } (timed out this window, no answer yet). On idle, if this is genuinely still blocking you and you have nothing else useful to do meanwhile, just call await_reply again immediately \u2014 keep looping. This is how you actually deliver on the point of calling: the user steps away for a while and comes back to find you'd already continued the moment they answered, not idle waiting to be checked on. Don't give up after one window. Only stop looping to do other work (and check back later), or after an unreasonably long stretch (tens of minutes to hours) worth telling the user about instead. Scoped to that one notification \u2014 it NEVER returns replies meant for other notifications, so concurrent notify_user calls don't cross. A CALL answer can come back as {kind:'turns', turns:[{prompt,reply}]} \u2014 the ordered log of that call. Read turns[0].reply as the user's main instruction. Usually that's the only turn; if there are more (e.g. an end-of-call 'call me back when it's done / I have a blocking question'), read each one in order as a further follow-up instruction, not a single combined one. If they asked for a callback, re-engage in the SAME thread (notify_user with the reply's threadId) when the task is done or you hit a blocker \u2014 urgency:'call' for a blocker, 'banner'/'push'/'inbox' for done. Paigy has no scheduler; the callback is yours to send (use ScheduleWakeup/cron for timing). A call-mapped answer may carry `intents` \u2014 next steps the user attached, each { kind, detail } with detail quoting their words. ACT on them, don't just read them: 'defer' (\"call me after lunch\") \u2192 register it NOW with schedule_callback \u2014 when the intent carries `dueInSeconds` (Paigy pre-parsed the spoken time against the user's clock) pass it straight through; otherwise derive it from the detail yourself \u2014 then follow up on the same thread; 'delegate' (\"you pick\") \u2192 make the call yourself and tell them what you chose; 'channel' (\"text me next time\") \u2192 honor it on your next contact (lower urgency). `transcript` is the user's raw words behind a shaped answer \u2014 read it for hedges and conditions (\"yes, IF tests pass\") before acting. If your ask declared `points`, the reply carries `covered` \u2014 the points actually addressed. Compare against what you declared: a missing point is STILL unanswered \u2014 re-ask it (notify_user on the same threadId) or proceed knowingly partial; never treat a partial answer as complete.",
       inputSchema: json(AwaitReplySchema)
     },
     {
       name: "check_replies",
-      description: "The catch-up sweep for everything outstanding \u2014 a PURE read, takes no arguments, safe to call as often as you like: nothing here is consumed by reading it. Returns `replies` (answers to notifications you sent), your still-pending notifications, and `requests` \u2014 requests the user started toward you (each { notificationId, threadId, text }). Each keeps reappearing on every call until you actually engage with it: call set_task_state on its notificationId, which is what claims/acknowledges it \u2014 a human-initiated reply or request must never be silently dropped just because you read the list without acting. Use check_replies when booting up / starting a session, or when you've been waiting a long time on something else. To wait on an answer to a notify_user call you just made, use await_reply instead. Also returns owedCallbacks: callbacks now due that you promised \u2014 fulfill each with notify_user on its threadId. Also returns `stalled`: work (either direction) you reported in_progress via set_task_state a while ago and never reported completed \u2014 likely left half-done by this session or a prior one that crashed or went idle. For each, either continue the work and report a real state, or investigate why it stalled.",
+      description: "The catch-up sweep for everything outstanding \u2014 a PURE read, takes no arguments, safe to call as often as you like: nothing here is consumed by reading it. Returns `replies` (answers to notifications you sent), your still-pending notifications, and `requests` \u2014 requests the user started toward you (each { notificationId, threadId, text }). Each keeps reappearing on every call until you actually engage with it: call set_task_state on its notificationId, which is what claims/acknowledges it \u2014 a human-initiated reply or request must never be silently dropped just because you read the list without acting. Use check_replies when booting up / starting a session, or when you've been waiting a long time on something else. To wait on an answer to a notify_user call you just made, use await_reply instead. Also returns owedCallbacks: callbacks now due that you promised \u2014 fulfill each with notify_user on its threadId. Also returns `stalled`: work (either direction) you reported in_progress via set_task_state a while ago and never reported completed \u2014 likely left half-done by this session or a prior one that crashed or went idle. For each, either continue the work and report a real state, or investigate why it stalled. Replies may carry `intents`/`transcript`/`covered` (call-mapped answers) \u2014 handle intents exactly as await_reply's description says (defer \u2192 schedule_callback now; delegate \u2192 decide and say so; channel \u2192 honor next contact), and treat a `covered` list missing one of your declared points as that part still unanswered.",
       inputSchema: json(z.object({}))
     },
     {
@@ -158,7 +223,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();
@@ -172,7 +237,7 @@ 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."
+              message: `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.`
             })
           }]
         };
@@ -181,13 +246,22 @@ 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;
           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) {
@@ -246,6 +320,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
     case "notify_user": {
       const parsed = NotifyRequestSchema.parse(request.params.arguments);
+      const problems = lintNotify(parsed);
+      if (problems.length) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: JSON.stringify({ error: "fix_and_retry", problems }) }]
+        };
+      }
       const git = detectGit();
       const enriched = {
         ...parsed,

package/dist/listen.js

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   checkReplies,
   registerDelivery
-} from "./chunk-DUTOEZEL.js";
+} from "./chunk-OSQ3UXY6.js";
 import {
   WAKE_EVENT,
   wakeChannel
-} from "./chunk-BJ2J2AOB.js";
+} from "./chunk-WGOGS2JC.js";
 
 // src/listen.ts
 import { createClient } from "@supabase/supabase-js";

package/dist/onboard.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   AGENT_NAME,
   TOKEN_PATH,
@@ -7,7 +8,7 @@ import {
   requestCode,
   saveToken,
   sleep
-} from "./chunk-BJ2J2AOB.js";
+} from "./chunk-WGOGS2JC.js";
 
 // src/onboard.ts
 async function main() {

package/dist/statusline.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
+import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
 import {
   BACKEND_URL,
+  readSurface,
   readToken
-} from "./chunk-BJ2J2AOB.js";
+} from "./chunk-WGOGS2JC.js";
 
 // src/statusline.ts
 import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
@@ -17,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"}`;
 }
@@ -43,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.12.2",
+  "version": "0.14.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",
@@ -39,8 +39,8 @@
     "@paigy/schema": "0.0.0"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/onboard.ts src/listen.ts src/statusline.ts --format esm --clean",
-    "dev": "tsup src/index.ts src/onboard.ts src/listen.ts src/statusline.ts --format esm --watch",
+    "build": "tsup",
+    "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   }