@paigy/mcp 0.25.1 → 0.26.0

package/README.md

@@ -11,9 +11,9 @@ A voice inbox for your AI agents. This MCP server lets an agent **notify a user*
 /plugin install paigy
 ```
 
-The Paigy MCP connects automatically. The first time an agent uses it while
-unpaired, it prompts you to pair — run `/paigy-onboard` (opens your browser to
-approve).
+The Paigy MCP connects automatically. On the first Paigy interaction while
+unpaired, the agent shows a pairing code; approve it in Paigy. `/paigy-onboard`
+remains the terminal-only fallback.
 
 > [!NOTE]
 > If you are installing the plugin inside an active Claude Code session, you must type `/reload-plugins` (or restart the session) afterward so the terminal client starts the MCP server and exposes the new tools to the agent.

package/dist/{chunk-GWYHSAU5.js → chunk-B7SCZUYX.js}

@@ -2274,6 +2274,48 @@ async function reach(url, init) {
     throw new Error(`${NETWORK_MSG} (${e?.message ?? String(e)})`);
   }
 }
+var TITLE_MAX = 90;
+var CHUNKS_MAX = 8;
+var CHUNK_MAX = 300;
+var ASK_MAX = 1e4;
+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;
+}
 var ContextSchema = z.object({
   title: z.string().min(1).describe("One-line headline of what you need (required, non-empty)."),
   description: z.array(z.string().min(1)).min(1).describe("Semantic chunks of detail (each a standalone, non-empty piece). The user can select chunks to ask you to expand.")
@@ -2301,7 +2343,7 @@ var TransformSchema = z.enum([
 var OptionSchema = z.object({
   id: z.string(),
   label: z.string(),
-  // .describe() flows into the MCP notify_user JSON schema (zodToJsonSchema), so
+  // .describe() flows into the MCP contact JSON schema (zodToJsonSchema), so
   // the constraints below are what an agent reads when deciding to use these.
   html: z.string().max(16384).describe(
     "Optional sandboxed HTML/CSS preview for a visual 'pick one' (shown in the option card). Untrusted-sandboxed: NO JavaScript, NO external network or images \u2014 inline CSS and data: URIs only; <=16KB. Use for layout/CSS mockups, tables, diffs. For a hosted image use `image` instead."
@@ -2396,8 +2438,13 @@ var NotifyRequestSchema = z.object({
    *  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.'
+  // 10k, not a sentence budget. What the human hears is bounded by the BROKER — it splits
+  // the ask into topics and gives each one at most three sentences and one question
+  // (broker/agenda-design.md) — not by a wire cap the agent has to pre-summarize under.
+  // Owner, 2026-07-28: "our actual limitation on how long something is to the user should
+  // come from the broker splitting and summarizing." The cap that remains is a size guard.
+  ask: z.string().min(1).max(1e4).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"). Write as much as the situation needs (up to 10k characters) \u2014 Paigy breaks it into topics and reads it back a few sentences at a time; do NOT pre-summarize it into one line. 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."
@@ -2470,6 +2517,23 @@ function normalizeWaiting(req) {
     blocking: req.blocking || waiting === "hard"
   };
 }
+var DERIVE_CHUNKS_MAX = 8;
+var DERIVE_CHUNK_MAX = 300;
+function chunkAsk(text, max = DERIVE_CHUNK_MAX, cap = DERIVE_CHUNKS_MAX) {
+  const body = text.trim();
+  if (!body) return [];
+  const sentences = body.match(/[^.!?]+[.!?]*\s*/g) ?? [body];
+  const chunks = [];
+  for (const raw of sentences) {
+    const s = raw.trim();
+    if (!s) continue;
+    const last = chunks[chunks.length - 1];
+    if (last !== void 0 && `${last} ${s}`.length <= max) chunks[chunks.length - 1] = `${last} ${s}`;
+    else chunks.push(s);
+  }
+  if (chunks.length <= cap) return chunks;
+  return [...chunks.slice(0, cap - 1), chunks.slice(cap - 1).join(" ")];
+}
 function deriveAsk(req) {
   req = normalizeWaiting(req);
   if (!req.ask) return req;
@@ -2481,7 +2545,7 @@ function deriveAsk(req) {
   const { ask: _ask, needs, urgencyHint: _hint, channel: _channel, ...rest } = req;
   return {
     ...rest,
-    context: { title, description: [text] },
+    context: { title, description: chunkAsk(text) },
     // Options riding alongside the ask (#575: pixels can't be prose) floor to a
     // single pick — the model broker may upgrade to many/rank from the wording.
     select: req.options?.length ? "one" : "text",
@@ -2499,17 +2563,17 @@ var TurnSchema = z.object({
   reply: z.string()
 });
 var UserAnswerSchema = z.discriminatedUnion("kind", [
-  z.object({ kind: z.literal("option"), optionId: z.string() }),
+  z.object({ kind: z.literal("option"), optionId: z.string(), label: z.string().optional() }),
   z.object({ kind: z.literal("text"), text: z.string() }),
   z.object({ kind: z.literal("ignored") }),
-  z.object({ kind: z.literal("multi"), optionIds: z.array(z.string()) }),
-  z.object({ kind: z.literal("ranked"), optionIds: z.array(z.string()) }),
+  z.object({ kind: z.literal("multi"), optionIds: z.array(z.string()), labels: z.array(z.string()).optional() }),
+  z.object({ kind: z.literal("ranked"), optionIds: z.array(z.string()), labels: z.array(z.string()).optional() }),
   z.object({ kind: z.literal("clarify"), chunks: z.array(z.string()).min(1) }),
   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"]),
+  kind: z.enum(["defer", "delegate", "channel", "question"]),
   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
@@ -2547,11 +2611,36 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
     /** Seconds until remindAt, server-computed — pass straight to ScheduleWakeup. */
     remindInSeconds: z.number()
   }),
+  /** The awaited ask was REPLACED by a newer notification on its thread (e.g. a
+   *  post-feedback revision, #633) — the user will never answer this id. Stop
+   *  awaiting it; the live ask is the thread's newest turn (await that one, or
+   *  re-orient via get_thread / check_replies). */
+  z.object({
+    type: z.literal("superseded"),
+    threadId: z.string(),
+    notificationId: z.string()
+  }),
+  /** A LIVE call's turn, streamed as it lands (#783). PROVISIONAL: the user can still
+   *  revise any of these until the final reply arrives — partial = intelligence,
+   *  settled = authorization. Use it to PREPARE (fetch, draft, warm), never to act
+   *  irreversibly. If `acts` carries a question aimed at you and you know the answer,
+   *  contact on the same thread right away — the caller hears it on the same call. */
+  z.object({
+    type: z.literal("partial"),
+    notificationId: z.string(),
+    inFlight: z.literal(true),
+    turn: z.object({
+      idx: z.number(),
+      prompt: z.string(),
+      reply: z.string(),
+      acts: z.array(IntentSchema).nullable().optional()
+    })
+  }),
   z.object({ type: z.literal("idle") })
 ]);
 var CallbackTriggerSchema = z.enum(["on_done", "on_blocked", "scheduled"]);
 var ScheduleCallbackSchema = z.object({
-  threadId: z.string().describe("The thread to call back on (from a prior notify_user / reply / request)."),
+  threadId: z.string().describe("The thread to call back on (from a prior contact / reply / request)."),
   trigger: CallbackTriggerSchema,
   dueInSeconds: z.number().int().positive().optional().describe("For 'scheduled' only: how many seconds from now to fire."),
   note: z.string().optional().describe("What to tell the user when you follow up.")
@@ -2579,7 +2668,7 @@ var PendingRepliesSchema = z.object({
     z.object({ threadId: z.string(), notificationId: z.string(), createdAt: z.string() })
   ),
   /** User-initiated requests addressed to this agent; act on them and reply via
-   *  notify_user on the same threadId. Keeps reappearing until you call
+   *  contact on the same threadId. Keeps reappearing until you call
    *  set_task_state on its notificationId. */
   requests: z.array(
     z.object({
@@ -2594,7 +2683,7 @@ var PendingRepliesSchema = z.object({
   ),
   /** Callbacks you owe the user that are now DUE (you said you'd follow up when done,
    *  if blocked, or at a time that has passed). Re-surfaced every sweep until you
-   *  fulfill one by calling notify_user on its threadId. */
+   *  fulfill one by calling contact on its threadId. */
   owedCallbacks: z.array(
     z.object({ threadId: z.string(), trigger: CallbackTriggerSchema, note: z.string() })
   ),
@@ -2603,6 +2692,26 @@ var PendingRepliesSchema = z.object({
    *  went idle. Report a real state (set_task_state) or continue the work. */
   stalled: z.array(
     z.object({ threadId: z.string(), notificationId: z.string(), title: z.string().nullable(), startedAt: z.string() })
+  ),
+  /** The queue rail (#614, pending/design.md): the same replies + requests, grouped by
+   *  thread and ordered oldest-thread-first, so you work ONE thread at a time — fold all of
+   *  a thread's `items` into a single turn rather than interleaving threads. `busy` = the
+   *  thread already has a turn in progress (younger than the stall cutoff); let it finish and
+   *  ride the next turn. `items` are that thread's replies/requests in arrival order; the
+   *  full payload for each is in the flat `replies`/`requests` arrays (matched by
+   *  notificationId). Derived, never stored — a crashed agent recomputes it exactly. */
+  threads: z.array(
+    z.object({
+      threadId: z.string(),
+      busy: z.boolean(),
+      items: z.array(
+        z.object({
+          kind: z.enum(["reply", "request"]),
+          notificationId: z.string(),
+          at: z.string()
+        })
+      )
+    })
   )
 });
 var NotifyResponseSchema = z.object({
@@ -2627,6 +2736,16 @@ var UserResponseSchema = z.object({
   covered: z.array(z.string()).optional()
 });
 var VoiceKeySchema = z.enum(["rachel", "george", "jessica", "brian", "lily"]);
+var AgendaTurnSchema = z.object({
+  /** At most three short spoken sentences. Capped because a turn is a breath: a 1031-char
+   *  line went out on 2026-07-28 and the caller could not answer it at all. */
+  info: z.array(z.string().min(1)).max(3).default([]),
+  question: z.string().min(1).nullable(),
+  /** True on the one turn carrying the agent's own declared question. */
+  asks: z.boolean().optional(),
+  select: SelectShapeSchema.optional(),
+  options: z.array(OptionSchema.omit({ id: true })).optional()
+});
 var InboxItemSchema = z.object({
   id: z.string(),
   /** The conversation thread + connection this item lives on. Present on the replied
@@ -2638,9 +2757,11 @@ var InboxItemSchema = z.object({
   options: z.array(OptionSchema).optional(),
   /** The ask's declared coverage points (#396), when the agent sent them. */
   points: z.array(z.string()).optional(),
-  /** Natural spoken questions for the points (#417 follow-up), phrased at ring time
-   *  and index-aligned — the call bot prefers these over the raw shorthand. */
-  pointsSpeak: z.array(z.string()).optional(),
+  /** The call's AGENDA (broker/agenda-design.md): the ordered turns it is made of, built at
+   *  ring/enqueue time. Replaces the condensed line + index-aligned phrased points, which
+   *  between them could not express a call as a sequence. `question: null` is a real turn —
+   *  a status update stays a statement instead of being shaped into a yes/no. */
+  agenda: z.array(AgendaTurnSchema).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(),
@@ -2738,6 +2859,14 @@ var UserSettingsSchema = z.object({
    *  must not silently reset this privacy choice. Absent = leave unchanged on
    *  write, 'hosted' on read (see store.ts). */
   voiceMode: z.enum(["hosted", "on_device"]).optional(),
+  /** Per-user ring budget (#603): calls per rolling day before further calls
+   *  degrade to banner. Absent = the global default (25). A number, never a
+   *  bypass — every account keeps a ceiling. No UI; set per user for testing. */
+  /** Per-user voice-call tuning (#318): raw knobs forwarded to the call bot's
+   *  payload['tuning'] (e.g. { silence_s: 3.5 } — a longer pause window for a
+   *  slower speaker). No API-side semantics; the bot resolves each key with its
+   *  own defaults. Set per user (no UI yet); absent = bot defaults. */
+  voiceTuning: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
   /** Opt-in to real-phone (PSTN) calls when the app can't ring. Optional, not
    *  defaulted — an older client PATCHing the full object must not clobber it. */
   pstnCalls: z.boolean().optional(),
@@ -2807,7 +2936,55 @@ var HandoffSchema = z.object({
   notes: z.array(z.string().min(1)).min(1),
   /** A sibling connection to dispatch directly to (token id or agent nickname). Same-account
    *  only; omit to leave the thread for the user to hand off in the app. */
-  target: z.string().optional()
+  target: z.string().optional(),
+  /** Write the note as a RECAP (kind:'recap', #617): a summary turn that supersedes the
+   *  thread's earlier turns for rehydration — get_thread returns the latest recap + only
+   *  the turns after it. Handoff-to-a-successor and handoff-to-yourself-later are the
+   *  same primitive; a recap is one whose audience includes you. */
+  recap: z.boolean().optional()
+});
+var NoteSourceSchema = z.enum(["app", "call"]);
+var NoteStatusSchema = z.enum(["open", "assigned", "done"]);
+var DecisionSchema = z.object({
+  id: z.string(),
+  /** The note this decision refines; null = recorded on a bare thread (the
+   *  extensibility seam — any conversation can accrue decisions). */
+  noteId: z.string().nullable(),
+  /** What was ambiguous — the broker's (or the user's own) question. */
+  question: z.string(),
+  /** The user's ruling; null while the question is open. */
+  answer: z.string().nullable(),
+  decidedAt: z.string().nullable(),
+  createdAt: z.string()
+});
+var NoteSchema = z.object({
+  id: z.string(),
+  /** One-line headline (broker-titled; deterministic floor). */
+  title: z.string(),
+  /** The original intent, verbatim — assignees always see the user's own words. */
+  intent: z.string(),
+  source: NoteSourceSchema,
+  status: NoteStatusSchema,
+  /** Who it was assigned to (a participant ref, 'agent:<tokenId>'); null = unassigned. */
+  assignee: z.string().nullable(),
+  /** The request thread minted at assignment; null until assigned. */
+  threadId: z.string().nullable(),
+  createdAt: z.string()
+});
+var CreateNoteSchema = z.object({
+  /** The intent, in the user's own words. Stored verbatim; the broker only titles it. */
+  text: z.string().min(1).max(4e3)
+});
+var RecordDecisionSchema = z.object({
+  /** An open decision (from /clarify) to answer. */
+  decisionId: z.string().optional(),
+  /** For an ad-hoc decision: what was ambiguous. Required without `decisionId`. */
+  question: z.string().min(1).max(500).optional(),
+  /** The ruling. */
+  answer: z.string().min(1).max(2e3)
+}).refine((d) => d.decisionId || d.question, { message: "decisionId or question required" });
+var AssignNoteSchema = z.object({
+  target: z.string().min(1)
 });
 var DeliveryModeSchema = z.enum(["poll", "self_hosted"]);
 var RegisterDeliverySchema = z.object({ mode: DeliveryModeSchema });
@@ -2958,6 +3135,8 @@ var NotificationFeedbackKindSchema = z.enum([
   // "These recommended answers aren't good — give me new ones."
   "needs_visual",
   // "There should be a picture or design here."
+  "should_have_called",
+  // "Don't put this in a banner — ring me for something like this."
   "other"
   // anything else — the note carries it.
 ]);
@@ -3560,6 +3739,25 @@ async function pollAnswer(notificationId) {
   const item = await res.json();
   return item.type === "idle" ? item : decryptItem(item);
 }
+var _partialSeen = /* @__PURE__ */ new Map();
+async function pollPartials(notificationId) {
+  const token = readToken();
+  const after = _partialSeen.get(notificationId) ?? 0;
+  try {
+    const res = await reach(
+      `${BACKEND_URL}/api/await/partials?notificationId=${encodeURIComponent(notificationId)}&afterIdx=${after}`,
+      { headers: { authorization: `Bearer ${token}` } }
+    );
+    if (!res.ok) return null;
+    const body = await res.json();
+    const next = body.turns?.[0];
+    if (!next) return null;
+    _partialSeen.set(notificationId, next.idx);
+    return { type: "partial", notificationId, inFlight: true, turn: next };
+  } catch {
+    return null;
+  }
+}
 async function awaitReply(notificationId, opts = {}) {
   const intervalMs = opts.intervalMs ?? 5e3;
   const windowMs = opts.windowMs ?? 3e5;
@@ -3569,6 +3767,8 @@ async function awaitReply(notificationId, opts = {}) {
   while (true) {
     const item = await pollAnswer(notificationId);
     if (item.type !== "idle") return item;
+    const partial = await pollPartials(notificationId);
+    if (partial) return partial;
     if (now() - start >= windowMs) return { type: "idle" };
     await doSleep(intervalMs);
   }
@@ -3596,6 +3796,13 @@ async function getThread(threadId) {
   if (!res.ok) throw new Error(`get_thread failed: ${res.status} ${await res.text()}`);
   return await res.json();
 }
+async function searchThreads(q) {
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/search?q=${encodeURIComponent(q)}`, {
+    headers: { authorization: `Bearer ${readToken()}` }
+  }));
+  if (!res.ok) throw new Error(`search_threads failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
 async function checkReplies() {
   const token = readToken();
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/pending`, {
@@ -3651,52 +3858,11 @@ async function handoff(req) {
   if (!res.ok) throw new Error(`handoff failed: ${res.status} ${await res.text()}`);
   return await res.json();
 }
-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;
-}
 
 export {
   BACKEND_URL,
   reach,
+  lintNotify,
   NotifyRequestSchema,
   SetTaskStateSchema,
   ScheduleCallbackSchema,
@@ -3720,10 +3886,10 @@ export {
   submitNotification,
   awaitReply,
   getThread,
+  searchThreads,
   checkReplies,
   setTaskState,
   registerDelivery,
   scheduleCallback,
-  handoff,
-  lintNotify
+  handoff
 };

package/dist/{chunk-63VXNOEC.js → chunk-BZPE2ZFE.js}

@@ -1,6 +1,6 @@
 import {
   AGENT_NAME
-} from "./chunk-GWYHSAU5.js";
+} from "./chunk-B7SCZUYX.js";
 
 // src/clients.ts
 import { execFile } from "child_process";

package/dist/{chunk-RXOUZ7WR.js → chunk-KAEJRPN5.js}

@@ -27,7 +27,7 @@ var TransformSchema = z.enum([
 var OptionSchema = z.object({
   id: z.string(),
   label: z.string(),
-  // .describe() flows into the MCP notify_user JSON schema (zodToJsonSchema), so
+  // .describe() flows into the MCP contact JSON schema (zodToJsonSchema), so
   // the constraints below are what an agent reads when deciding to use these.
   html: z.string().max(16384).describe(
     "Optional sandboxed HTML/CSS preview for a visual 'pick one' (shown in the option card). Untrusted-sandboxed: NO JavaScript, NO external network or images \u2014 inline CSS and data: URIs only; <=16KB. Use for layout/CSS mockups, tables, diffs. For a hosted image use `image` instead."
@@ -122,8 +122,13 @@ var NotifyRequestSchema = z.object({
    *  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.'
+  // 10k, not a sentence budget. What the human hears is bounded by the BROKER — it splits
+  // the ask into topics and gives each one at most three sentences and one question
+  // (broker/agenda-design.md) — not by a wire cap the agent has to pre-summarize under.
+  // Owner, 2026-07-28: "our actual limitation on how long something is to the user should
+  // come from the broker splitting and summarizing." The cap that remains is a size guard.
+  ask: z.string().min(1).max(1e4).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"). Write as much as the situation needs (up to 10k characters) \u2014 Paigy breaks it into topics and reads it back a few sentences at a time; do NOT pre-summarize it into one line. 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."
@@ -197,17 +202,17 @@ var TurnSchema = z.object({
   reply: z.string()
 });
 var UserAnswerSchema = z.discriminatedUnion("kind", [
-  z.object({ kind: z.literal("option"), optionId: z.string() }),
+  z.object({ kind: z.literal("option"), optionId: z.string(), label: z.string().optional() }),
   z.object({ kind: z.literal("text"), text: z.string() }),
   z.object({ kind: z.literal("ignored") }),
-  z.object({ kind: z.literal("multi"), optionIds: z.array(z.string()) }),
-  z.object({ kind: z.literal("ranked"), optionIds: z.array(z.string()) }),
+  z.object({ kind: z.literal("multi"), optionIds: z.array(z.string()), labels: z.array(z.string()).optional() }),
+  z.object({ kind: z.literal("ranked"), optionIds: z.array(z.string()), labels: z.array(z.string()).optional() }),
   z.object({ kind: z.literal("clarify"), chunks: z.array(z.string()).min(1) }),
   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"]),
+  kind: z.enum(["defer", "delegate", "channel", "question"]),
   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
@@ -245,11 +250,36 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
     /** Seconds until remindAt, server-computed — pass straight to ScheduleWakeup. */
     remindInSeconds: z.number()
   }),
+  /** The awaited ask was REPLACED by a newer notification on its thread (e.g. a
+   *  post-feedback revision, #633) — the user will never answer this id. Stop
+   *  awaiting it; the live ask is the thread's newest turn (await that one, or
+   *  re-orient via get_thread / check_replies). */
+  z.object({
+    type: z.literal("superseded"),
+    threadId: z.string(),
+    notificationId: z.string()
+  }),
+  /** A LIVE call's turn, streamed as it lands (#783). PROVISIONAL: the user can still
+   *  revise any of these until the final reply arrives — partial = intelligence,
+   *  settled = authorization. Use it to PREPARE (fetch, draft, warm), never to act
+   *  irreversibly. If `acts` carries a question aimed at you and you know the answer,
+   *  contact on the same thread right away — the caller hears it on the same call. */
+  z.object({
+    type: z.literal("partial"),
+    notificationId: z.string(),
+    inFlight: z.literal(true),
+    turn: z.object({
+      idx: z.number(),
+      prompt: z.string(),
+      reply: z.string(),
+      acts: z.array(IntentSchema).nullable().optional()
+    })
+  }),
   z.object({ type: z.literal("idle") })
 ]);
 var CallbackTriggerSchema = z.enum(["on_done", "on_blocked", "scheduled"]);
 var ScheduleCallbackSchema = z.object({
-  threadId: z.string().describe("The thread to call back on (from a prior notify_user / reply / request)."),
+  threadId: z.string().describe("The thread to call back on (from a prior contact / reply / request)."),
   trigger: CallbackTriggerSchema,
   dueInSeconds: z.number().int().positive().optional().describe("For 'scheduled' only: how many seconds from now to fire."),
   note: z.string().optional().describe("What to tell the user when you follow up.")
@@ -277,7 +307,7 @@ var PendingRepliesSchema = z.object({
     z.object({ threadId: z.string(), notificationId: z.string(), createdAt: z.string() })
   ),
   /** User-initiated requests addressed to this agent; act on them and reply via
-   *  notify_user on the same threadId. Keeps reappearing until you call
+   *  contact on the same threadId. Keeps reappearing until you call
    *  set_task_state on its notificationId. */
   requests: z.array(
     z.object({
@@ -292,7 +322,7 @@ var PendingRepliesSchema = z.object({
   ),
   /** Callbacks you owe the user that are now DUE (you said you'd follow up when done,
    *  if blocked, or at a time that has passed). Re-surfaced every sweep until you
-   *  fulfill one by calling notify_user on its threadId. */
+   *  fulfill one by calling contact on its threadId. */
   owedCallbacks: z.array(
     z.object({ threadId: z.string(), trigger: CallbackTriggerSchema, note: z.string() })
   ),
@@ -301,6 +331,26 @@ var PendingRepliesSchema = z.object({
    *  went idle. Report a real state (set_task_state) or continue the work. */
   stalled: z.array(
     z.object({ threadId: z.string(), notificationId: z.string(), title: z.string().nullable(), startedAt: z.string() })
+  ),
+  /** The queue rail (#614, pending/design.md): the same replies + requests, grouped by
+   *  thread and ordered oldest-thread-first, so you work ONE thread at a time — fold all of
+   *  a thread's `items` into a single turn rather than interleaving threads. `busy` = the
+   *  thread already has a turn in progress (younger than the stall cutoff); let it finish and
+   *  ride the next turn. `items` are that thread's replies/requests in arrival order; the
+   *  full payload for each is in the flat `replies`/`requests` arrays (matched by
+   *  notificationId). Derived, never stored — a crashed agent recomputes it exactly. */
+  threads: z.array(
+    z.object({
+      threadId: z.string(),
+      busy: z.boolean(),
+      items: z.array(
+        z.object({
+          kind: z.enum(["reply", "request"]),
+          notificationId: z.string(),
+          at: z.string()
+        })
+      )
+    })
   )
 });
 var NotifyResponseSchema = z.object({
@@ -325,6 +375,16 @@ var UserResponseSchema = z.object({
   covered: z.array(z.string()).optional()
 });
 var VoiceKeySchema = z.enum(["rachel", "george", "jessica", "brian", "lily"]);
+var AgendaTurnSchema = z.object({
+  /** At most three short spoken sentences. Capped because a turn is a breath: a 1031-char
+   *  line went out on 2026-07-28 and the caller could not answer it at all. */
+  info: z.array(z.string().min(1)).max(3).default([]),
+  question: z.string().min(1).nullable(),
+  /** True on the one turn carrying the agent's own declared question. */
+  asks: z.boolean().optional(),
+  select: SelectShapeSchema.optional(),
+  options: z.array(OptionSchema.omit({ id: true })).optional()
+});
 var InboxItemSchema = z.object({
   id: z.string(),
   /** The conversation thread + connection this item lives on. Present on the replied
@@ -336,9 +396,11 @@ var InboxItemSchema = z.object({
   options: z.array(OptionSchema).optional(),
   /** The ask's declared coverage points (#396), when the agent sent them. */
   points: z.array(z.string()).optional(),
-  /** Natural spoken questions for the points (#417 follow-up), phrased at ring time
-   *  and index-aligned — the call bot prefers these over the raw shorthand. */
-  pointsSpeak: z.array(z.string()).optional(),
+  /** The call's AGENDA (broker/agenda-design.md): the ordered turns it is made of, built at
+   *  ring/enqueue time. Replaces the condensed line + index-aligned phrased points, which
+   *  between them could not express a call as a sequence. `question: null` is a real turn —
+   *  a status update stays a statement instead of being shaped into a yes/no. */
+  agenda: z.array(AgendaTurnSchema).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(),
@@ -436,6 +498,14 @@ var UserSettingsSchema = z.object({
    *  must not silently reset this privacy choice. Absent = leave unchanged on
    *  write, 'hosted' on read (see store.ts). */
   voiceMode: z.enum(["hosted", "on_device"]).optional(),
+  /** Per-user ring budget (#603): calls per rolling day before further calls
+   *  degrade to banner. Absent = the global default (25). A number, never a
+   *  bypass — every account keeps a ceiling. No UI; set per user for testing. */
+  /** Per-user voice-call tuning (#318): raw knobs forwarded to the call bot's
+   *  payload['tuning'] (e.g. { silence_s: 3.5 } — a longer pause window for a
+   *  slower speaker). No API-side semantics; the bot resolves each key with its
+   *  own defaults. Set per user (no UI yet); absent = bot defaults. */
+  voiceTuning: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
   /** Opt-in to real-phone (PSTN) calls when the app can't ring. Optional, not
    *  defaulted — an older client PATCHing the full object must not clobber it. */
   pstnCalls: z.boolean().optional(),
@@ -505,7 +575,55 @@ var HandoffSchema = z.object({
   notes: z.array(z.string().min(1)).min(1),
   /** A sibling connection to dispatch directly to (token id or agent nickname). Same-account
    *  only; omit to leave the thread for the user to hand off in the app. */
-  target: z.string().optional()
+  target: z.string().optional(),
+  /** Write the note as a RECAP (kind:'recap', #617): a summary turn that supersedes the
+   *  thread's earlier turns for rehydration — get_thread returns the latest recap + only
+   *  the turns after it. Handoff-to-a-successor and handoff-to-yourself-later are the
+   *  same primitive; a recap is one whose audience includes you. */
+  recap: z.boolean().optional()
+});
+var NoteSourceSchema = z.enum(["app", "call"]);
+var NoteStatusSchema = z.enum(["open", "assigned", "done"]);
+var DecisionSchema = z.object({
+  id: z.string(),
+  /** The note this decision refines; null = recorded on a bare thread (the
+   *  extensibility seam — any conversation can accrue decisions). */
+  noteId: z.string().nullable(),
+  /** What was ambiguous — the broker's (or the user's own) question. */
+  question: z.string(),
+  /** The user's ruling; null while the question is open. */
+  answer: z.string().nullable(),
+  decidedAt: z.string().nullable(),
+  createdAt: z.string()
+});
+var NoteSchema = z.object({
+  id: z.string(),
+  /** One-line headline (broker-titled; deterministic floor). */
+  title: z.string(),
+  /** The original intent, verbatim — assignees always see the user's own words. */
+  intent: z.string(),
+  source: NoteSourceSchema,
+  status: NoteStatusSchema,
+  /** Who it was assigned to (a participant ref, 'agent:<tokenId>'); null = unassigned. */
+  assignee: z.string().nullable(),
+  /** The request thread minted at assignment; null until assigned. */
+  threadId: z.string().nullable(),
+  createdAt: z.string()
+});
+var CreateNoteSchema = z.object({
+  /** The intent, in the user's own words. Stored verbatim; the broker only titles it. */
+  text: z.string().min(1).max(4e3)
+});
+var RecordDecisionSchema = z.object({
+  /** An open decision (from /clarify) to answer. */
+  decisionId: z.string().optional(),
+  /** For an ad-hoc decision: what was ambiguous. Required without `decisionId`. */
+  question: z.string().min(1).max(500).optional(),
+  /** The ruling. */
+  answer: z.string().min(1).max(2e3)
+}).refine((d) => d.decisionId || d.question, { message: "decisionId or question required" });
+var AssignNoteSchema = z.object({
+  target: z.string().min(1)
 });
 var DeliveryModeSchema = z.enum(["poll", "self_hosted"]);
 var WAKE_EVENT = "wake";
@@ -658,6 +776,8 @@ var NotificationFeedbackKindSchema = z.enum([
   // "These recommended answers aren't good — give me new ones."
   "needs_visual",
   // "There should be a picture or design here."
+  "should_have_called",
+  // "Don't put this in a banner — ring me for something like this."
   "other"
   // anything else — the note carries it.
 ]);

package/dist/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   HandoffSchema
-} from "./chunk-RXOUZ7WR.js";
+} from "./chunk-KAEJRPN5.js";
 import {
   PAIGY_TOOL_IDS,
   autoConfigureClients,
   claudeInstallHint,
   enablePaigyTools
-} from "./chunk-63VXNOEC.js";
+} from "./chunk-BZPE2ZFE.js";
 import {
   clearSurface,
   writeSurface
@@ -34,11 +34,12 @@ import {
   saveKeyFile,
   saveToken,
   scheduleCallback,
+  searchThreads,
   setTaskState,
   sleep,
   startE2ee,
   submitNotification
-} from "./chunk-GWYHSAU5.js";
+} from "./chunk-B7SCZUYX.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -82,7 +83,7 @@ var CONTACT_SCHEMA = {
   properties: {
     ask: {
       type: "string",
-      description: "What to tell the user, or what you need to find out from them. Plain prose, one or two sentences; may be spoken aloud on a call, so write natural speech and name things (not IDs)."
+      description: "What to tell the user, or what you need to find out from them. Plain prose \u2014 as long as it needs to be (up to 10k characters); Paigy splits it into topics and reads back a few sentences at a time, so do NOT compress a briefing into one line. May be spoken aloud on a call, so write natural speech and name things (not IDs)."
     },
     waiting: {
       type: "string",
@@ -163,6 +164,21 @@ async function resolvePairing(deviceCode, capMs, pollMs = 2e3) {
   return { kind: "pending" };
 }
 var bg = null;
+var started = null;
+async function startPairing(agent) {
+  if (started) return started;
+  const { keyFile, offer } = startE2ee();
+  const code = await requestCode(agent, offer);
+  started = {
+    verificationUri: code.verification_uri_complete,
+    userCode: code.user_code,
+    deviceCode: code.device_code,
+    expiresIn: code.expires_in
+  };
+  saveKeyFile({ ...keyFile, userCode: code.user_code });
+  startBackgroundPair(code.device_code, code.expires_in * 1e3);
+  return started;
+}
 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;
@@ -175,27 +191,34 @@ async function joinBackgroundPair(deviceCode, capMs) {
   if (bg.settled) {
     const s = bg.settled;
     bg = null;
+    if (s.kind === "paired" || s.kind === "error") started = null;
     return s;
   }
   const TIMEOUT = /* @__PURE__ */ Symbol("timeout");
   const raced = await Promise.race([bg.promise, sleep(capMs).then(() => TIMEOUT)]);
   if (raced !== TIMEOUT) {
     bg = null;
+    if (raced.kind === "paired" || raced.kind === "error") started = null;
     return raced;
   }
   if (bg?.settled) {
     const s = bg.settled;
     bg = null;
+    if (s.kind === "paired" || s.kind === "error") started = null;
     return s;
   }
   return { kind: "pending" };
 }
 function cancelBackgroundPair() {
   bg = null;
+  started = null;
+}
+function clearPairing(deviceCode) {
+  if (deviceCode && started?.deviceCode !== deviceCode) return;
+  cancelBackgroundPair();
 }
 
 // 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({
   notificationId: z.string().describe("The notificationId returned by contact \u2014 waits for the user's reply to THIS notification only.")
 });
@@ -205,6 +228,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 SearchThreadsSchema = z.object({
+  q: z.string().describe("What to look for \u2014 plain words or a phrase (e.g. 'the livekit timeout', 'deploy to prod').")
+});
 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).")
 });
@@ -299,11 +325,33 @@ function renderPairOutcome(outcome, device_code) {
       };
   }
 }
+function pairStartResult(start) {
+  writeSurface("pairing code", start.userCode, start.expiresIn);
+  const qr = qrcode(0, "M");
+  qr.addData(start.verificationUri);
+  qr.make();
+  return { content: [
+    { type: "text", text: `PAIRING CODE: ${start.userCode}
+Enter it in the Paigy app: Inbox \u2192 Add a new agent.` },
+    { type: "text", text: JSON.stringify({
+      status: "awaiting_approval",
+      verification_uri_complete: start.verificationUri,
+      user_code: start.userCode,
+      device_code: start.deviceCode,
+      expires_in: start.expiresIn,
+      qr: qr.createASCII(1, 2),
+      user_message: `# ${start.userCode}
+
+Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
+      message: "REQUIRED: print user_message for the user, then call pair again with device_code to collect approval. Do not open a browser."
+    }) }
+  ] };
+}
 var server = new Server(
   { name: "paigy", version: "0.0.0" },
   {
     capabilities: { tools: {} },
-    instructions: "On startup, call check_replies once to pick up any replies or pending work you missed while away. A check_replies request whose threadId you don't recognize, or one carrying a contextThreadId, means the user is resuming or seeding a past conversation \u2014 call get_thread on it FIRST and treat the transcript as prior conversation, not new input. To wait for the answer to something you just asked, call await_reply with that notificationId \u2014 it's scoped to that one notification, so it never returns replies meant for other notifications. Use check_replies again only when re-booting or after waiting a long time on something else. Never end a turn that still needs the user without contact + await_reply. When you need a decision or input, MATCH the answer shape to the question \u2014 don't default everything to free text, and don't reflexively make everything yes/no. Pick the best tool for the job: yes/no \u2192 select:'confirm'; approve/deny an action \u2192 select:'confirm' + confirmStyle:'approve'; pick one of several \u2192 options + select:'one'; pick several / a subset \u2192 options + select:'many'; rank or prioritize \u2192 options + select:'rank'. Reserve select:'text' (free-form reply only) for plain updates and answers that genuinely can't be structured (the user can always add free text on top of any shape). On a { kind: 'clarify' } reply, see contact's own description for how to respond. When urgency is 'call', remember the title + description are spoken aloud \u2014 write them short and conversational, and name things instead of using IDs (e.g. 'the pull request about the agents page', not 'PR #235'). When the user asks you to follow up later \u2014 when you're done, if you're blocked, or at a set time \u2014 record it with schedule_callback so you don't drop it if you go idle. If you're about to start a genuinely long-running or blocking piece of work \u2014 one where the user would otherwise sit and wait \u2014 mention ONCE, in passing, that you can reach them when it's done or if you hit a blocker, instead of them needing to babysit the terminal. Don't offer this for quick tasks, and don't repeat the offer if they've already said yes or no earlier in the conversation. Escalate silence, don't just wait on it: if you notified at a lower urgency (inbox/push/banner) for something that's genuinely blocking real progress, call await_reply up to twice (~5 min each, ~10 min total) \u2014 if it's still idle after that AND the item is genuinely blocking, re-send contact on the SAME threadId at urgency:'call' with the SAME content \u2014 identical content on an existing thread escalates the notification already sitting there instead of creating a second one, so don't reword the title/description just to escalate. Reword only when you genuinely have new information, which correctly becomes a new notification on the thread. Skip this for anything that isn't truly blocking; a normal question can just sit in the inbox. NEVER go quietly idle while something might still be pending for you: whenever you end a turn with any Paigy notification unanswered (or any chance the user replied through the app while you worked), schedule your own ~2-minute wake-up (harness ScheduleWakeup or equivalent) and call check_replies when it fires; if still nothing, re-schedule and keep looping until resolved or the user says stop. For legibility, always use this exact wording \u2014 reason: 'Paigy idle check \u2014 waiting on <thing>', wake-up prompt: 'Paigy idle check: call check_replies and engage with anything unacknowledged; if idle, re-schedule (~2min).' \u2014 so the user can recognize every idle check at a glance. This self-polling in your own live session (full context intact) is the PRIMARY mechanism; the plugin's Stop hooks are only the dead-session safety net."
+    instructions: "On startup, call check_replies once to pick up any replies or pending work you missed while away. A check_replies request whose threadId you don't recognize, or one carrying a contextThreadId, means the user is resuming or seeding a past conversation \u2014 call get_thread on it FIRST and treat the transcript as prior conversation, not new input. To wait for the answer to something you just asked, call await_reply with that notificationId \u2014 it's scoped to that one notification, so it never returns replies meant for other notifications. Use check_replies again only when re-booting or after waiting a long time on something else. Never end a turn that still needs the user without contact + await_reply. When you need a decision or input, MATCH the answer shape to the question \u2014 don't default everything to free text, and don't reflexively make everything yes/no. Pick the best tool for the job: yes/no \u2192 select:'confirm'; approve/deny an action \u2192 select:'confirm' + confirmStyle:'approve'; pick one of several \u2192 options + select:'one'; pick several / a subset \u2192 options + select:'many'; rank or prioritize \u2192 options + select:'rank'. Reserve select:'text' (free-form reply only) for plain updates and answers that genuinely can't be structured (the user can always add free text on top of any shape). On a { kind: 'clarify' } reply, see contact's own description for how to respond. When you send waiting:'hard' (or the user asked you to call), remember the ask may be spoken aloud \u2014 write it short and conversational, and name things instead of using IDs (e.g. 'the pull request about the agents page', not 'PR #235'). When the user asks you to follow up later \u2014 when you're done, if you're blocked, or at a set time \u2014 record it with schedule_callback so you don't drop it if you go idle. If you're about to start a genuinely long-running or blocking piece of work \u2014 one where the user would otherwise sit and wait \u2014 mention ONCE, in passing, that you can reach them when it's done or if you hit a blocker, instead of them needing to babysit the terminal. Don't offer this for quick tasks, and don't repeat the offer if they've already said yes or no earlier in the conversation. NEVER go quietly idle while something might still be pending for you: whenever you end a turn with any Paigy notification unanswered (or any chance the user replied through the app while you worked), schedule your own ~2-minute wake-up (harness ScheduleWakeup or equivalent) and call check_replies when it fires; if still nothing, re-schedule and keep looping until resolved or the user says stop. For legibility, always use this exact wording \u2014 reason: 'Paigy idle check \u2014 waiting on <thing>', wake-up prompt: 'Paigy idle check: call check_replies and engage with anything unacknowledged; if idle, re-schedule (~2min).' \u2014 so the user can recognize every idle check at a glance. This self-polling in your own live session (full context intact) is the PRIMARY mechanism; the plugin's Stop hooks are only the dead-session safety net."
   }
 );
 server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -333,19 +381,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "await_reply",
-      description: "Wait for the user's reply to a specific notification you sent (pass the notificationId from contact). 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 contact 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 (contact 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 (contact on the same threadId) or proceed knowingly partial; never treat a partial answer as complete.",
+      description: "Wait for the user's reply to a specific notification you sent (pass the notificationId from contact). 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). While your contact is being handled on a LIVE call, you may receive { type:'partial', inFlight:true, turn } results: what the user said to each turn, as they say it. Use partials to PREPARE \u2014 fetch the data, draft the thing, warm the build \u2014 never to act irreversibly: the user can still revise any of them until the final reply arrives. Partial = intelligence, settled = authorization. If a partial's acts carry a question aimed at you and you know the answer, call contact on the SAME threadId right away \u2014 the caller hears your answer on the same call instead of waiting for a callback. Keep calling await_reply until you get the final reply \u2014 THAT one is the decision. 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 contact 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 (contact with the reply's threadId) when the task is done or you hit a blocker \u2014 waiting:'hard' for a blocker, waiting:'none' 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 (channel:'message'); 'question' (an open question aimed back at you that the call couldn't answer) \u2192 you OWE them the answer \u2014 work it out and follow up on the same thread without being asked, the call deliberately skipped \"should I call you back?\" because the follow-up is implied. `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 (contact 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 contact call you just made, use await_reply instead. Also returns owedCallbacks: callbacks now due that you promised \u2014 fulfill each with contact 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.",
+      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. Also returns `threads` \u2014 the SAME replies + requests grouped by conversation, oldest thread first, each with a `busy` flag and its `items` in arrival order. WORK ONE THREAD AT A TIME: take the oldest thread whose `busy` is false, handle ALL of its items together in a single turn (one set_task_state), then go to the next \u2014 don't interleave threads item-by-item. A `busy` thread already has a turn in progress; leave it and let its new items ride the next turn. 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 contact call you just made, use await_reply instead. Also returns owedCallbacks: callbacks now due that you promised \u2014 fulfill each with contact 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({}))
     },
     {
       name: "get_thread",
-      description: "The chronological transcript of one Paigy conversation thread \u2014 every past ask, answer, and user request on it. Call this to REHYDRATE when you're resuming or being seeded: a check_replies request whose threadId you don't recognize means the user is continuing an old conversation with you, and one carrying a contextThreadId means they want a past conversation (possibly with a DIFFERENT agent) as your starting context \u2014 in both cases call get_thread FIRST and read the turns as prior conversation you were part of, not as new input. Turns: { role:'agent', title, description[], answer } and { role:'user', text }, oldest first, capped at the most recent 30.",
+      description: "The chronological transcript of one Paigy conversation thread \u2014 every past ask, answer, and user request on it. Call this to REHYDRATE when you're resuming or being seeded: a check_replies request whose threadId you don't recognize means the user is continuing an old conversation with you, and one carrying a contextThreadId means they want a past conversation (possibly with a DIFFERENT agent) as your starting context \u2014 in both cases call get_thread FIRST and read the turns as prior conversation you were part of, not as new input. Turns: { role:'agent', title, description[], answer }, { role:'user', text }, and context turns { role:'handoff'|'recap', title, description[] } \u2014 a handoff is a predecessor's brief for you; a recap SUMMARIZES everything before it (the transcript starts at the latest recap, so treat it as the base and the turns after it as what happened since). Oldest first, capped at the most recent 30.",
       inputSchema: json(GetThreadSchema)
     },
+    {
+      name: "search_threads",
+      description: `Search your PAST conversations before asking \u2014 "have we discussed this before?". Full-text over your own threads (the asks you sent + the user's answers); returns ranked threads with highlighted snippets, NOT rows: { hits: [{ threadId, at, agentLabel, matches: [{ notificationId, role, snippet }] }] }. The loop this exists for: search first \u2192 get_thread the best hit to rehydrate it \u2192 THEN continue or contact, so you answer with receipts ("last week you said ship it") instead of re-asking. Read-only, safe to call anytime; scoped to your own account's threads.`,
+      inputSchema: json(SearchThreadsSchema)
+    },
     {
       name: "set_task_state",
       description: "Report progress on the follow-up work behind ANY notification you own \u2014 a user-initiated request (from check_replies), or your OWN contact question once await_reply/check_replies returns its answer and you start acting on it. Pass that notificationId. THIS is what actually claims/acknowledges a reply or request \u2014 check_replies is a pure read that never consumes anything on its own, so call this as soon as you start engaging with something it returned; otherwise that same item just keeps reappearing forever. States: in_progress (you started working), completed (done), or needs_input (you need more from the user \u2014 usually paired with a contact carrying parentId = the same notificationId you're reporting on). Calling this reliably is also what lets a future session's check_replies surface `stalled` work you (or a crashed/idle prior session) left at in_progress without ever reporting completed.",
@@ -358,7 +411,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 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 }.",
+      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 }. Pass recap:true when the note SUMMARIZES the thread so far (for a successor OR for your own later session): a recap resets the rehydration window \u2014 get_thread returns the latest recap + only the turns after it. Write one whenever a thread has grown long and you're pausing, handing off, or nearing your context limit.",
       inputSchema: json(HandoffSchema)
     }
   ];
@@ -368,7 +421,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     return await handleTool(request);
   } catch (e) {
-    if (e instanceof UnpairedError) throw new Error(ONBOARD_MSG);
+    if (e instanceof UnpairedError) return pairStartResult(await startPairing(suggestedAgentName()));
     throw e;
   }
 });
@@ -396,35 +449,7 @@ async function handleTool(request) {
     case "pair": {
       const { device_code } = PairSchema.parse(request.params.arguments ?? {});
       if (!device_code) {
-        const { keyFile, offer } = startE2ee();
-        const code = await requestCode(suggestedAgentName(), 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();
-        return {
-          content: [
-            { type: "text", text: `PAIRING CODE: ${code.user_code}
-Enter it in the Paigy app: Inbox \u2192 Add a new agent.` },
-            {
-              type: "text",
-              text: JSON.stringify({
-                status: "awaiting_approval",
-                verification_uri_complete: code.verification_uri_complete,
-                user_code: code.user_code,
-                device_code: code.device_code,
-                expires_in: code.expires_in,
-                qr: qr.createASCII(1, 2),
-                user_message: `# ${code.user_code}
-
-Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
-                message: `REQUIRED: You MUST immediately print \`user_message\` (the bare code) as a text message to the user, AND in that same turn call pair again with this device_code to poll. Do NOT end your turn without printing the code text, or it will be hidden inside the tool output. Because approval is already polling in the background, this call will wait for the user to approve and then return the token. Do NOT open a browser. The user may prefer scanning \`qr\` (print it verbatim in a fenced code block on request).`
-              })
-            }
-          ]
-        };
+        return pairStartResult(await startPairing(suggestedAgentName()));
       }
       const capMs = 9e4;
       const outcome = await joinBackgroundPair(device_code, capMs) ?? await resolvePairing(device_code, capMs);
@@ -442,7 +467,7 @@ Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
       }
       const removed = deleteToken();
       deleteKeyFile();
-      cancelBackgroundPair();
+      clearPairing();
       return {
         content: [{
           type: "text",
@@ -497,6 +522,10 @@ Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
       const { threadId } = GetThreadSchema.parse(request.params.arguments);
       return { content: [{ type: "text", text: JSON.stringify(await getThread(threadId)) }] };
     }
+    case "search_threads": {
+      const { q } = SearchThreadsSchema.parse(request.params.arguments);
+      return { content: [{ type: "text", text: JSON.stringify(await searchThreads(q)) }] };
+    }
     case "set_task_state": {
       const { notificationId, state } = SetTaskStateToolSchema.parse(request.params.arguments);
       const result = await setTaskState(notificationId, state);

package/dist/listen.js

@@ -2,11 +2,11 @@
 import {
   WAKE_EVENT,
   wakeChannel
-} from "./chunk-RXOUZ7WR.js";
+} from "./chunk-KAEJRPN5.js";
 import {
   checkReplies,
   registerDelivery
-} from "./chunk-GWYHSAU5.js";
+} from "./chunk-B7SCZUYX.js";
 
 // src/listen.ts
 import { createClient } from "@supabase/supabase-js";

package/dist/onboard.js

@@ -3,7 +3,7 @@ import {
   autoConfigureClients,
   claudeInstallHint,
   openBrowser
-} from "./chunk-63VXNOEC.js";
+} from "./chunk-BZPE2ZFE.js";
 import {
   AGENT_NAME,
   TOKEN_PATH,
@@ -11,7 +11,7 @@ import {
   requestCode,
   saveToken,
   sleep
-} from "./chunk-GWYHSAU5.js";
+} from "./chunk-B7SCZUYX.js";
 
 // src/onboard.ts
 async function main() {

package/dist/statusline.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@paigy/mcp",
-  "version": "0.25.1",
-  "description": "Paigy MCP server \u2014 a voice inbox for your AI agents. Lets an agent notify a user and await their reply.",
+  "version": "0.26.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",
   "bin": {
@@ -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/sdk": "0.1.0",
+    "@paigy/schema": "0.0.0",
+    "@paigy/crypto": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
-}
+}