@paigy/mcp 0.25.1 → 0.25.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,9 +11,9 @@ A voice inbox for your AI agents. This MCP server lets an agent **notify a user*
11
11
  /plugin install paigy
12
12
  ```
13
13
 
14
- The Paigy MCP connects automatically. The first time an agent uses it while
15
- unpaired, it prompts you to pair — run `/paigy-onboard` (opens your browser to
16
- approve).
14
+ The Paigy MCP connects automatically. On the first Paigy interaction while
15
+ unpaired, the agent shows a pairing code; approve it in Paigy. `/paigy-onboard`
16
+ remains the terminal-only fallback.
17
17
 
18
18
  > [!NOTE]
19
19
  > 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.
@@ -2274,6 +2274,48 @@ async function reach(url, init) {
2274
2274
  throw new Error(`${NETWORK_MSG} (${e?.message ?? String(e)})`);
2275
2275
  }
2276
2276
  }
2277
+ var TITLE_MAX = 90;
2278
+ var CHUNKS_MAX = 8;
2279
+ var CHUNK_MAX = 300;
2280
+ var ASK_MAX = 1e3;
2281
+ var OPTION_MAX = 80;
2282
+ var NEEDS_MAX = 6;
2283
+ var UNSPEAKABLE = /```|\n/;
2284
+ function lintNotify(req) {
2285
+ const problems = [];
2286
+ if (req.ask !== void 0) {
2287
+ if (req.ask.length > ASK_MAX)
2288
+ 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`);
2289
+ if (UNSPEAKABLE.test(req.ask))
2290
+ problems.push("ask contains code fences or newlines \u2014 write it as plain prose (it may be read aloud on a call)");
2291
+ for (const n of req.needs ?? []) {
2292
+ 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)`);
2293
+ }
2294
+ if ((req.needs?.length ?? 0) > NEEDS_MAX)
2295
+ 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`);
2296
+ return problems;
2297
+ }
2298
+ const spoken = req.urgency === "call" || req.urgency === "banner";
2299
+ if (req.context) {
2300
+ if (req.context.title.length > TITLE_MAX)
2301
+ 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)`);
2302
+ if (UNSPEAKABLE.test(req.context.title))
2303
+ problems.push("title contains code fences or newlines \u2014 one plain-prose line");
2304
+ if (req.context.description.length > CHUNKS_MAX)
2305
+ problems.push(`${req.context.description.length} description chunks \u2014 cap at ${CHUNKS_MAX}; merge or drop the rest`);
2306
+ for (const [i, chunk] of req.context.description.entries()) {
2307
+ if (chunk.length > CHUNK_MAX)
2308
+ problems.push(`description[${i}] is ${chunk.length} chars \u2014 split it into standalone points of \u2264${CHUNK_MAX}`);
2309
+ }
2310
+ if (spoken && UNSPEAKABLE.test(req.context.description.join(" ")))
2311
+ 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)");
2312
+ }
2313
+ for (const o of req.options ?? []) {
2314
+ if (o.label.length > OPTION_MAX)
2315
+ 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`);
2316
+ }
2317
+ return problems;
2318
+ }
2277
2319
  var ContextSchema = z.object({
2278
2320
  title: z.string().min(1).describe("One-line headline of what you need (required, non-empty)."),
2279
2321
  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([
2301
2343
  var OptionSchema = z.object({
2302
2344
  id: z.string(),
2303
2345
  label: z.string(),
2304
- // .describe() flows into the MCP notify_user JSON schema (zodToJsonSchema), so
2346
+ // .describe() flows into the MCP contact JSON schema (zodToJsonSchema), so
2305
2347
  // the constraints below are what an agent reads when deciding to use these.
2306
2348
  html: z.string().max(16384).describe(
2307
2349
  "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."
@@ -2499,17 +2541,17 @@ var TurnSchema = z.object({
2499
2541
  reply: z.string()
2500
2542
  });
2501
2543
  var UserAnswerSchema = z.discriminatedUnion("kind", [
2502
- z.object({ kind: z.literal("option"), optionId: z.string() }),
2544
+ z.object({ kind: z.literal("option"), optionId: z.string(), label: z.string().optional() }),
2503
2545
  z.object({ kind: z.literal("text"), text: z.string() }),
2504
2546
  z.object({ kind: z.literal("ignored") }),
2505
- z.object({ kind: z.literal("multi"), optionIds: z.array(z.string()) }),
2506
- z.object({ kind: z.literal("ranked"), optionIds: z.array(z.string()) }),
2547
+ z.object({ kind: z.literal("multi"), optionIds: z.array(z.string()), labels: z.array(z.string()).optional() }),
2548
+ z.object({ kind: z.literal("ranked"), optionIds: z.array(z.string()), labels: z.array(z.string()).optional() }),
2507
2549
  z.object({ kind: z.literal("clarify"), chunks: z.array(z.string()).min(1) }),
2508
2550
  z.object({ kind: z.literal("confirm"), approved: z.boolean() }),
2509
2551
  z.object({ kind: z.literal("turns"), turns: z.array(TurnSchema).min(1) })
2510
2552
  ]);
2511
2553
  var IntentSchema = z.object({
2512
- kind: z.enum(["defer", "delegate", "channel"]),
2554
+ kind: z.enum(["defer", "delegate", "channel", "question"]),
2513
2555
  detail: z.string(),
2514
2556
  /** Landed defer (#397): the MCP parses common spoken forms ("in 20 minutes",
2515
2557
  * "after lunch") against the agent machine's clock — the user's — and attaches
@@ -2547,11 +2589,20 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
2547
2589
  /** Seconds until remindAt, server-computed — pass straight to ScheduleWakeup. */
2548
2590
  remindInSeconds: z.number()
2549
2591
  }),
2592
+ /** The awaited ask was REPLACED by a newer notification on its thread (e.g. a
2593
+ * post-feedback revision, #633) — the user will never answer this id. Stop
2594
+ * awaiting it; the live ask is the thread's newest turn (await that one, or
2595
+ * re-orient via get_thread / check_replies). */
2596
+ z.object({
2597
+ type: z.literal("superseded"),
2598
+ threadId: z.string(),
2599
+ notificationId: z.string()
2600
+ }),
2550
2601
  z.object({ type: z.literal("idle") })
2551
2602
  ]);
2552
2603
  var CallbackTriggerSchema = z.enum(["on_done", "on_blocked", "scheduled"]);
2553
2604
  var ScheduleCallbackSchema = z.object({
2554
- threadId: z.string().describe("The thread to call back on (from a prior notify_user / reply / request)."),
2605
+ threadId: z.string().describe("The thread to call back on (from a prior contact / reply / request)."),
2555
2606
  trigger: CallbackTriggerSchema,
2556
2607
  dueInSeconds: z.number().int().positive().optional().describe("For 'scheduled' only: how many seconds from now to fire."),
2557
2608
  note: z.string().optional().describe("What to tell the user when you follow up.")
@@ -2579,7 +2630,7 @@ var PendingRepliesSchema = z.object({
2579
2630
  z.object({ threadId: z.string(), notificationId: z.string(), createdAt: z.string() })
2580
2631
  ),
2581
2632
  /** User-initiated requests addressed to this agent; act on them and reply via
2582
- * notify_user on the same threadId. Keeps reappearing until you call
2633
+ * contact on the same threadId. Keeps reappearing until you call
2583
2634
  * set_task_state on its notificationId. */
2584
2635
  requests: z.array(
2585
2636
  z.object({
@@ -2594,7 +2645,7 @@ var PendingRepliesSchema = z.object({
2594
2645
  ),
2595
2646
  /** Callbacks you owe the user that are now DUE (you said you'd follow up when done,
2596
2647
  * if blocked, or at a time that has passed). Re-surfaced every sweep until you
2597
- * fulfill one by calling notify_user on its threadId. */
2648
+ * fulfill one by calling contact on its threadId. */
2598
2649
  owedCallbacks: z.array(
2599
2650
  z.object({ threadId: z.string(), trigger: CallbackTriggerSchema, note: z.string() })
2600
2651
  ),
@@ -2603,6 +2654,26 @@ var PendingRepliesSchema = z.object({
2603
2654
  * went idle. Report a real state (set_task_state) or continue the work. */
2604
2655
  stalled: z.array(
2605
2656
  z.object({ threadId: z.string(), notificationId: z.string(), title: z.string().nullable(), startedAt: z.string() })
2657
+ ),
2658
+ /** The queue rail (#614, pending/design.md): the same replies + requests, grouped by
2659
+ * thread and ordered oldest-thread-first, so you work ONE thread at a time — fold all of
2660
+ * a thread's `items` into a single turn rather than interleaving threads. `busy` = the
2661
+ * thread already has a turn in progress (younger than the stall cutoff); let it finish and
2662
+ * ride the next turn. `items` are that thread's replies/requests in arrival order; the
2663
+ * full payload for each is in the flat `replies`/`requests` arrays (matched by
2664
+ * notificationId). Derived, never stored — a crashed agent recomputes it exactly. */
2665
+ threads: z.array(
2666
+ z.object({
2667
+ threadId: z.string(),
2668
+ busy: z.boolean(),
2669
+ items: z.array(
2670
+ z.object({
2671
+ kind: z.enum(["reply", "request"]),
2672
+ notificationId: z.string(),
2673
+ at: z.string()
2674
+ })
2675
+ )
2676
+ })
2606
2677
  )
2607
2678
  });
2608
2679
  var NotifyResponseSchema = z.object({
@@ -2738,6 +2809,15 @@ var UserSettingsSchema = z.object({
2738
2809
  * must not silently reset this privacy choice. Absent = leave unchanged on
2739
2810
  * write, 'hosted' on read (see store.ts). */
2740
2811
  voiceMode: z.enum(["hosted", "on_device"]).optional(),
2812
+ /** Per-user ring budget (#603): calls per rolling day before further calls
2813
+ * degrade to banner. Absent = the global default (25). A number, never a
2814
+ * bypass — every account keeps a ceiling. No UI; set per user for testing. */
2815
+ callBudget: z.number().int().min(1).max(500).optional(),
2816
+ /** Per-user voice-call tuning (#318): raw knobs forwarded to the call bot's
2817
+ * payload['tuning'] (e.g. { silence_s: 3.5 } — a longer pause window for a
2818
+ * slower speaker). No API-side semantics; the bot resolves each key with its
2819
+ * own defaults. Set per user (no UI yet); absent = bot defaults. */
2820
+ voiceTuning: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
2741
2821
  /** Opt-in to real-phone (PSTN) calls when the app can't ring. Optional, not
2742
2822
  * defaulted — an older client PATCHing the full object must not clobber it. */
2743
2823
  pstnCalls: z.boolean().optional(),
@@ -2807,7 +2887,12 @@ var HandoffSchema = z.object({
2807
2887
  notes: z.array(z.string().min(1)).min(1),
2808
2888
  /** A sibling connection to dispatch directly to (token id or agent nickname). Same-account
2809
2889
  * only; omit to leave the thread for the user to hand off in the app. */
2810
- target: z.string().optional()
2890
+ target: z.string().optional(),
2891
+ /** Write the note as a RECAP (kind:'recap', #617): a summary turn that supersedes the
2892
+ * thread's earlier turns for rehydration — get_thread returns the latest recap + only
2893
+ * the turns after it. Handoff-to-a-successor and handoff-to-yourself-later are the
2894
+ * same primitive; a recap is one whose audience includes you. */
2895
+ recap: z.boolean().optional()
2811
2896
  });
2812
2897
  var DeliveryModeSchema = z.enum(["poll", "self_hosted"]);
2813
2898
  var RegisterDeliverySchema = z.object({ mode: DeliveryModeSchema });
@@ -3596,6 +3681,13 @@ async function getThread(threadId) {
3596
3681
  if (!res.ok) throw new Error(`get_thread failed: ${res.status} ${await res.text()}`);
3597
3682
  return await res.json();
3598
3683
  }
3684
+ async function searchThreads(q) {
3685
+ const res = ensureAuthed(await reach(`${BACKEND_URL}/api/search?q=${encodeURIComponent(q)}`, {
3686
+ headers: { authorization: `Bearer ${readToken()}` }
3687
+ }));
3688
+ if (!res.ok) throw new Error(`search_threads failed: ${res.status} ${await res.text()}`);
3689
+ return await res.json();
3690
+ }
3599
3691
  async function checkReplies() {
3600
3692
  const token = readToken();
3601
3693
  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/pending`, {
@@ -3651,52 +3743,11 @@ async function handoff(req) {
3651
3743
  if (!res.ok) throw new Error(`handoff failed: ${res.status} ${await res.text()}`);
3652
3744
  return await res.json();
3653
3745
  }
3654
- var TITLE_MAX = 90;
3655
- var CHUNKS_MAX = 8;
3656
- var CHUNK_MAX = 300;
3657
- var ASK_MAX = 600;
3658
- var OPTION_MAX = 80;
3659
- var NEEDS_MAX = 6;
3660
- var UNSPEAKABLE = /```|\n/;
3661
- function lintNotify(req) {
3662
- const problems = [];
3663
- if (req.ask !== void 0) {
3664
- if (req.ask.length > ASK_MAX)
3665
- 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`);
3666
- if (UNSPEAKABLE.test(req.ask))
3667
- problems.push("ask contains code fences or newlines \u2014 write it as plain prose (it may be read aloud on a call)");
3668
- for (const n of req.needs ?? []) {
3669
- 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)`);
3670
- }
3671
- if ((req.needs?.length ?? 0) > NEEDS_MAX)
3672
- 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`);
3673
- return problems;
3674
- }
3675
- const spoken = req.urgency === "call" || req.urgency === "banner";
3676
- if (req.context) {
3677
- if (req.context.title.length > TITLE_MAX)
3678
- 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)`);
3679
- if (UNSPEAKABLE.test(req.context.title))
3680
- problems.push("title contains code fences or newlines \u2014 one plain-prose line");
3681
- if (req.context.description.length > CHUNKS_MAX)
3682
- problems.push(`${req.context.description.length} description chunks \u2014 cap at ${CHUNKS_MAX}; merge or drop the rest`);
3683
- for (const [i, chunk] of req.context.description.entries()) {
3684
- if (chunk.length > CHUNK_MAX)
3685
- problems.push(`description[${i}] is ${chunk.length} chars \u2014 split it into standalone points of \u2264${CHUNK_MAX}`);
3686
- }
3687
- if (spoken && UNSPEAKABLE.test(req.context.description.join(" ")))
3688
- 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)");
3689
- }
3690
- for (const o of req.options ?? []) {
3691
- if (o.label.length > OPTION_MAX)
3692
- 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`);
3693
- }
3694
- return problems;
3695
- }
3696
3746
 
3697
3747
  export {
3698
3748
  BACKEND_URL,
3699
3749
  reach,
3750
+ lintNotify,
3700
3751
  NotifyRequestSchema,
3701
3752
  SetTaskStateSchema,
3702
3753
  ScheduleCallbackSchema,
@@ -3720,10 +3771,10 @@ export {
3720
3771
  submitNotification,
3721
3772
  awaitReply,
3722
3773
  getThread,
3774
+ searchThreads,
3723
3775
  checkReplies,
3724
3776
  setTaskState,
3725
3777
  registerDelivery,
3726
3778
  scheduleCallback,
3727
- handoff,
3728
- lintNotify
3779
+ handoff
3729
3780
  };
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  AGENT_NAME
3
- } from "./chunk-GWYHSAU5.js";
3
+ } from "./chunk-2374V6WK.js";
4
4
 
5
5
  // src/clients.ts
6
6
  import { execFile } from "child_process";
@@ -27,7 +27,7 @@ var TransformSchema = z.enum([
27
27
  var OptionSchema = z.object({
28
28
  id: z.string(),
29
29
  label: z.string(),
30
- // .describe() flows into the MCP notify_user JSON schema (zodToJsonSchema), so
30
+ // .describe() flows into the MCP contact JSON schema (zodToJsonSchema), so
31
31
  // the constraints below are what an agent reads when deciding to use these.
32
32
  html: z.string().max(16384).describe(
33
33
  "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."
@@ -197,17 +197,17 @@ var TurnSchema = z.object({
197
197
  reply: z.string()
198
198
  });
199
199
  var UserAnswerSchema = z.discriminatedUnion("kind", [
200
- z.object({ kind: z.literal("option"), optionId: z.string() }),
200
+ z.object({ kind: z.literal("option"), optionId: z.string(), label: z.string().optional() }),
201
201
  z.object({ kind: z.literal("text"), text: z.string() }),
202
202
  z.object({ kind: z.literal("ignored") }),
203
- z.object({ kind: z.literal("multi"), optionIds: z.array(z.string()) }),
204
- z.object({ kind: z.literal("ranked"), optionIds: z.array(z.string()) }),
203
+ z.object({ kind: z.literal("multi"), optionIds: z.array(z.string()), labels: z.array(z.string()).optional() }),
204
+ z.object({ kind: z.literal("ranked"), optionIds: z.array(z.string()), labels: z.array(z.string()).optional() }),
205
205
  z.object({ kind: z.literal("clarify"), chunks: z.array(z.string()).min(1) }),
206
206
  z.object({ kind: z.literal("confirm"), approved: z.boolean() }),
207
207
  z.object({ kind: z.literal("turns"), turns: z.array(TurnSchema).min(1) })
208
208
  ]);
209
209
  var IntentSchema = z.object({
210
- kind: z.enum(["defer", "delegate", "channel"]),
210
+ kind: z.enum(["defer", "delegate", "channel", "question"]),
211
211
  detail: z.string(),
212
212
  /** Landed defer (#397): the MCP parses common spoken forms ("in 20 minutes",
213
213
  * "after lunch") against the agent machine's clock — the user's — and attaches
@@ -245,11 +245,20 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
245
245
  /** Seconds until remindAt, server-computed — pass straight to ScheduleWakeup. */
246
246
  remindInSeconds: z.number()
247
247
  }),
248
+ /** The awaited ask was REPLACED by a newer notification on its thread (e.g. a
249
+ * post-feedback revision, #633) — the user will never answer this id. Stop
250
+ * awaiting it; the live ask is the thread's newest turn (await that one, or
251
+ * re-orient via get_thread / check_replies). */
252
+ z.object({
253
+ type: z.literal("superseded"),
254
+ threadId: z.string(),
255
+ notificationId: z.string()
256
+ }),
248
257
  z.object({ type: z.literal("idle") })
249
258
  ]);
250
259
  var CallbackTriggerSchema = z.enum(["on_done", "on_blocked", "scheduled"]);
251
260
  var ScheduleCallbackSchema = z.object({
252
- threadId: z.string().describe("The thread to call back on (from a prior notify_user / reply / request)."),
261
+ threadId: z.string().describe("The thread to call back on (from a prior contact / reply / request)."),
253
262
  trigger: CallbackTriggerSchema,
254
263
  dueInSeconds: z.number().int().positive().optional().describe("For 'scheduled' only: how many seconds from now to fire."),
255
264
  note: z.string().optional().describe("What to tell the user when you follow up.")
@@ -277,7 +286,7 @@ var PendingRepliesSchema = z.object({
277
286
  z.object({ threadId: z.string(), notificationId: z.string(), createdAt: z.string() })
278
287
  ),
279
288
  /** User-initiated requests addressed to this agent; act on them and reply via
280
- * notify_user on the same threadId. Keeps reappearing until you call
289
+ * contact on the same threadId. Keeps reappearing until you call
281
290
  * set_task_state on its notificationId. */
282
291
  requests: z.array(
283
292
  z.object({
@@ -292,7 +301,7 @@ var PendingRepliesSchema = z.object({
292
301
  ),
293
302
  /** Callbacks you owe the user that are now DUE (you said you'd follow up when done,
294
303
  * if blocked, or at a time that has passed). Re-surfaced every sweep until you
295
- * fulfill one by calling notify_user on its threadId. */
304
+ * fulfill one by calling contact on its threadId. */
296
305
  owedCallbacks: z.array(
297
306
  z.object({ threadId: z.string(), trigger: CallbackTriggerSchema, note: z.string() })
298
307
  ),
@@ -301,6 +310,26 @@ var PendingRepliesSchema = z.object({
301
310
  * went idle. Report a real state (set_task_state) or continue the work. */
302
311
  stalled: z.array(
303
312
  z.object({ threadId: z.string(), notificationId: z.string(), title: z.string().nullable(), startedAt: z.string() })
313
+ ),
314
+ /** The queue rail (#614, pending/design.md): the same replies + requests, grouped by
315
+ * thread and ordered oldest-thread-first, so you work ONE thread at a time — fold all of
316
+ * a thread's `items` into a single turn rather than interleaving threads. `busy` = the
317
+ * thread already has a turn in progress (younger than the stall cutoff); let it finish and
318
+ * ride the next turn. `items` are that thread's replies/requests in arrival order; the
319
+ * full payload for each is in the flat `replies`/`requests` arrays (matched by
320
+ * notificationId). Derived, never stored — a crashed agent recomputes it exactly. */
321
+ threads: z.array(
322
+ z.object({
323
+ threadId: z.string(),
324
+ busy: z.boolean(),
325
+ items: z.array(
326
+ z.object({
327
+ kind: z.enum(["reply", "request"]),
328
+ notificationId: z.string(),
329
+ at: z.string()
330
+ })
331
+ )
332
+ })
304
333
  )
305
334
  });
306
335
  var NotifyResponseSchema = z.object({
@@ -436,6 +465,15 @@ var UserSettingsSchema = z.object({
436
465
  * must not silently reset this privacy choice. Absent = leave unchanged on
437
466
  * write, 'hosted' on read (see store.ts). */
438
467
  voiceMode: z.enum(["hosted", "on_device"]).optional(),
468
+ /** Per-user ring budget (#603): calls per rolling day before further calls
469
+ * degrade to banner. Absent = the global default (25). A number, never a
470
+ * bypass — every account keeps a ceiling. No UI; set per user for testing. */
471
+ callBudget: z.number().int().min(1).max(500).optional(),
472
+ /** Per-user voice-call tuning (#318): raw knobs forwarded to the call bot's
473
+ * payload['tuning'] (e.g. { silence_s: 3.5 } — a longer pause window for a
474
+ * slower speaker). No API-side semantics; the bot resolves each key with its
475
+ * own defaults. Set per user (no UI yet); absent = bot defaults. */
476
+ voiceTuning: z.record(z.string(), z.union([z.number(), z.string()])).optional(),
439
477
  /** Opt-in to real-phone (PSTN) calls when the app can't ring. Optional, not
440
478
  * defaulted — an older client PATCHing the full object must not clobber it. */
441
479
  pstnCalls: z.boolean().optional(),
@@ -505,7 +543,12 @@ var HandoffSchema = z.object({
505
543
  notes: z.array(z.string().min(1)).min(1),
506
544
  /** A sibling connection to dispatch directly to (token id or agent nickname). Same-account
507
545
  * only; omit to leave the thread for the user to hand off in the app. */
508
- target: z.string().optional()
546
+ target: z.string().optional(),
547
+ /** Write the note as a RECAP (kind:'recap', #617): a summary turn that supersedes the
548
+ * thread's earlier turns for rehydration — get_thread returns the latest recap + only
549
+ * the turns after it. Handoff-to-a-successor and handoff-to-yourself-later are the
550
+ * same primitive; a recap is one whose audience includes you. */
551
+ recap: z.boolean().optional()
509
552
  });
510
553
  var DeliveryModeSchema = z.enum(["poll", "self_hosted"]);
511
554
  var WAKE_EVENT = "wake";
package/dist/index.js CHANGED
@@ -1,13 +1,13 @@
1
1
  #!/usr/bin/env node
2
2
  import {
3
3
  HandoffSchema
4
- } from "./chunk-RXOUZ7WR.js";
4
+ } from "./chunk-LUY5MXDM.js";
5
5
  import {
6
6
  PAIGY_TOOL_IDS,
7
7
  autoConfigureClients,
8
8
  claudeInstallHint,
9
9
  enablePaigyTools
10
- } from "./chunk-63VXNOEC.js";
10
+ } from "./chunk-FEAIZ6DA.js";
11
11
  import {
12
12
  clearSurface,
13
13
  writeSurface
@@ -34,11 +34,12 @@ import {
34
34
  saveKeyFile,
35
35
  saveToken,
36
36
  scheduleCallback,
37
+ searchThreads,
37
38
  setTaskState,
38
39
  sleep,
39
40
  startE2ee,
40
41
  submitNotification
41
- } from "./chunk-GWYHSAU5.js";
42
+ } from "./chunk-2374V6WK.js";
42
43
 
43
44
  // src/index.ts
44
45
  import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -163,6 +164,21 @@ async function resolvePairing(deviceCode, capMs, pollMs = 2e3) {
163
164
  return { kind: "pending" };
164
165
  }
165
166
  var bg = null;
167
+ var started = null;
168
+ async function startPairing(agent) {
169
+ if (started) return started;
170
+ const { keyFile, offer } = startE2ee();
171
+ const code = await requestCode(agent, offer);
172
+ started = {
173
+ verificationUri: code.verification_uri_complete,
174
+ userCode: code.user_code,
175
+ deviceCode: code.device_code,
176
+ expiresIn: code.expires_in
177
+ };
178
+ saveKeyFile({ ...keyFile, userCode: code.user_code });
179
+ startBackgroundPair(code.device_code, code.expires_in * 1e3);
180
+ return started;
181
+ }
166
182
  function startBackgroundPair(deviceCode, budgetMs) {
167
183
  const promise = resolvePairing(deviceCode, budgetMs).catch((e) => ({ kind: "error", message: e.message })).then((o) => {
168
184
  if (bg?.deviceCode === deviceCode) bg.settled = o;
@@ -175,27 +191,34 @@ async function joinBackgroundPair(deviceCode, capMs) {
175
191
  if (bg.settled) {
176
192
  const s = bg.settled;
177
193
  bg = null;
194
+ if (s.kind === "paired" || s.kind === "error") started = null;
178
195
  return s;
179
196
  }
180
197
  const TIMEOUT = /* @__PURE__ */ Symbol("timeout");
181
198
  const raced = await Promise.race([bg.promise, sleep(capMs).then(() => TIMEOUT)]);
182
199
  if (raced !== TIMEOUT) {
183
200
  bg = null;
201
+ if (raced.kind === "paired" || raced.kind === "error") started = null;
184
202
  return raced;
185
203
  }
186
204
  if (bg?.settled) {
187
205
  const s = bg.settled;
188
206
  bg = null;
207
+ if (s.kind === "paired" || s.kind === "error") started = null;
189
208
  return s;
190
209
  }
191
210
  return { kind: "pending" };
192
211
  }
193
212
  function cancelBackgroundPair() {
194
213
  bg = null;
214
+ started = null;
215
+ }
216
+ function clearPairing(deviceCode) {
217
+ if (deviceCode && started?.deviceCode !== deviceCode) return;
218
+ cancelBackgroundPair();
195
219
  }
196
220
 
197
221
  // src/index.ts
198
- 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`.";
199
222
  var AwaitReplySchema = z.object({
200
223
  notificationId: z.string().describe("The notificationId returned by contact \u2014 waits for the user's reply to THIS notification only.")
201
224
  });
@@ -205,6 +228,9 @@ var PairSchema = z.object({
205
228
  var GetThreadSchema = z.object({
206
229
  threadId: z.string().describe("The thread to read \u2014 from a reply, request, or past notification.")
207
230
  });
231
+ var SearchThreadsSchema = z.object({
232
+ q: z.string().describe("What to look for \u2014 plain words or a phrase (e.g. 'the livekit timeout', 'deploy to prod').")
233
+ });
208
234
  var EnableToolsSchema = z.object({
209
235
  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).")
210
236
  });
@@ -299,11 +325,33 @@ function renderPairOutcome(outcome, device_code) {
299
325
  };
300
326
  }
301
327
  }
328
+ function pairStartResult(start) {
329
+ writeSurface("pairing code", start.userCode, start.expiresIn);
330
+ const qr = qrcode(0, "M");
331
+ qr.addData(start.verificationUri);
332
+ qr.make();
333
+ return { content: [
334
+ { type: "text", text: `PAIRING CODE: ${start.userCode}
335
+ Enter it in the Paigy app: Inbox \u2192 Add a new agent.` },
336
+ { type: "text", text: JSON.stringify({
337
+ status: "awaiting_approval",
338
+ verification_uri_complete: start.verificationUri,
339
+ user_code: start.userCode,
340
+ device_code: start.deviceCode,
341
+ expires_in: start.expiresIn,
342
+ qr: qr.createASCII(1, 2),
343
+ user_message: `# ${start.userCode}
344
+
345
+ Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
346
+ message: "REQUIRED: print user_message for the user, then call pair again with device_code to collect approval. Do not open a browser."
347
+ }) }
348
+ ] };
349
+ }
302
350
  var server = new Server(
303
351
  { name: "paigy", version: "0.0.0" },
304
352
  {
305
353
  capabilities: { tools: {} },
306
- 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."
354
+ 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."
307
355
  }
308
356
  );
309
357
  server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -333,19 +381,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
333
381
  },
334
382
  {
335
383
  name: "await_reply",
336
- 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.",
384
+ 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 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.",
337
385
  inputSchema: json(AwaitReplySchema)
338
386
  },
339
387
  {
340
388
  name: "check_replies",
341
- 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.",
389
+ 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.",
342
390
  inputSchema: json(z.object({}))
343
391
  },
344
392
  {
345
393
  name: "get_thread",
346
- 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.",
394
+ 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.",
347
395
  inputSchema: json(GetThreadSchema)
348
396
  },
397
+ {
398
+ name: "search_threads",
399
+ 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.`,
400
+ inputSchema: json(SearchThreadsSchema)
401
+ },
349
402
  {
350
403
  name: "set_task_state",
351
404
  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 () => {
358
411
  },
359
412
  {
360
413
  name: "handoff",
361
- 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 }.",
414
+ 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.",
362
415
  inputSchema: json(HandoffSchema)
363
416
  }
364
417
  ];
@@ -368,7 +421,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
368
421
  try {
369
422
  return await handleTool(request);
370
423
  } catch (e) {
371
- if (e instanceof UnpairedError) throw new Error(ONBOARD_MSG);
424
+ if (e instanceof UnpairedError) return pairStartResult(await startPairing(suggestedAgentName()));
372
425
  throw e;
373
426
  }
374
427
  });
@@ -396,35 +449,7 @@ async function handleTool(request) {
396
449
  case "pair": {
397
450
  const { device_code } = PairSchema.parse(request.params.arguments ?? {});
398
451
  if (!device_code) {
399
- const { keyFile, offer } = startE2ee();
400
- const code = await requestCode(suggestedAgentName(), offer);
401
- saveKeyFile({ ...keyFile, userCode: code.user_code });
402
- writeSurface("pairing code", code.user_code, code.expires_in);
403
- startBackgroundPair(code.device_code, code.expires_in * 1e3);
404
- const qr = qrcode(0, "M");
405
- qr.addData(code.verification_uri_complete);
406
- qr.make();
407
- return {
408
- content: [
409
- { type: "text", text: `PAIRING CODE: ${code.user_code}
410
- Enter it in the Paigy app: Inbox \u2192 Add a new agent.` },
411
- {
412
- type: "text",
413
- text: JSON.stringify({
414
- status: "awaiting_approval",
415
- verification_uri_complete: code.verification_uri_complete,
416
- user_code: code.user_code,
417
- device_code: code.device_code,
418
- expires_in: code.expires_in,
419
- qr: qr.createASCII(1, 2),
420
- user_message: `# ${code.user_code}
421
-
422
- Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
423
- 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).`
424
- })
425
- }
426
- ]
427
- };
452
+ return pairStartResult(await startPairing(suggestedAgentName()));
428
453
  }
429
454
  const capMs = 9e4;
430
455
  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).`,
442
467
  }
443
468
  const removed = deleteToken();
444
469
  deleteKeyFile();
445
- cancelBackgroundPair();
470
+ clearPairing();
446
471
  return {
447
472
  content: [{
448
473
  type: "text",
@@ -497,6 +522,10 @@ Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
497
522
  const { threadId } = GetThreadSchema.parse(request.params.arguments);
498
523
  return { content: [{ type: "text", text: JSON.stringify(await getThread(threadId)) }] };
499
524
  }
525
+ case "search_threads": {
526
+ const { q } = SearchThreadsSchema.parse(request.params.arguments);
527
+ return { content: [{ type: "text", text: JSON.stringify(await searchThreads(q)) }] };
528
+ }
500
529
  case "set_task_state": {
501
530
  const { notificationId, state } = SetTaskStateToolSchema.parse(request.params.arguments);
502
531
  const result = await setTaskState(notificationId, state);
package/dist/listen.js CHANGED
@@ -2,11 +2,11 @@
2
2
  import {
3
3
  WAKE_EVENT,
4
4
  wakeChannel
5
- } from "./chunk-RXOUZ7WR.js";
5
+ } from "./chunk-LUY5MXDM.js";
6
6
  import {
7
7
  checkReplies,
8
8
  registerDelivery
9
- } from "./chunk-GWYHSAU5.js";
9
+ } from "./chunk-2374V6WK.js";
10
10
 
11
11
  // src/listen.ts
12
12
  import { createClient } from "@supabase/supabase-js";
package/dist/onboard.js CHANGED
@@ -3,7 +3,7 @@ import {
3
3
  autoConfigureClients,
4
4
  claudeInstallHint,
5
5
  openBrowser
6
- } from "./chunk-63VXNOEC.js";
6
+ } from "./chunk-FEAIZ6DA.js";
7
7
  import {
8
8
  AGENT_NAME,
9
9
  TOKEN_PATH,
@@ -11,7 +11,7 @@ import {
11
11
  requestCode,
12
12
  saveToken,
13
13
  sleep
14
- } from "./chunk-GWYHSAU5.js";
14
+ } from "./chunk-2374V6WK.js";
15
15
 
16
16
  // src/onboard.ts
17
17
  async function main() {
@@ -6,7 +6,7 @@ import {
6
6
  BACKEND_URL,
7
7
  reach,
8
8
  readToken
9
- } from "./chunk-GWYHSAU5.js";
9
+ } from "./chunk-2374V6WK.js";
10
10
 
11
11
  // src/statusline.ts
12
12
  import { mkdirSync, readFileSync, realpathSync, writeFileSync } from "fs";
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@paigy/mcp",
3
- "version": "0.25.1",
4
- "description": "Paigy MCP server \u2014 a voice inbox for your AI agents. Lets an agent notify a user and await their reply.",
3
+ "version": "0.25.2",
4
+ "description": "Paigy MCP server — a voice inbox for your AI agents. Lets an agent notify a user and await their reply.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "bin": {
@@ -22,13 +22,6 @@
22
22
  "url": "git+https://github.com/mauurda/paigy.git",
23
23
  "directory": "apps/mcp"
24
24
  },
25
- "scripts": {
26
- "build": "tsup",
27
- "dev": "tsup --watch",
28
- "typecheck": "tsc --noEmit",
29
- "test": "vitest run",
30
- "prepublishOnly": "pnpm --filter @paigy/schema build && pnpm --filter @paigy/crypto build && pnpm --filter @paigy/sdk build && pnpm build"
31
- },
32
25
  "dependencies": {
33
26
  "@modelcontextprotocol/sdk": "^1.0.4",
34
27
  "@supabase/supabase-js": "^2.47.10",
@@ -38,13 +31,19 @@
38
31
  "zod-to-json-schema": "^3.24.1"
39
32
  },
40
33
  "devDependencies": {
41
- "@paigy/crypto": "workspace:*",
42
- "@paigy/schema": "workspace:*",
43
- "@paigy/sdk": "workspace:*",
44
34
  "@types/node": "^22.0.0",
45
35
  "@types/qrcode-generator": "^1.0.6",
46
36
  "tsup": "^8.3.5",
47
37
  "typescript": "^5.7.2",
48
- "vitest": "^2.1.8"
38
+ "vitest": "^2.1.8",
39
+ "@paigy/crypto": "0.0.0",
40
+ "@paigy/schema": "0.0.0",
41
+ "@paigy/sdk": "0.1.0"
42
+ },
43
+ "scripts": {
44
+ "build": "tsup",
45
+ "dev": "tsup --watch",
46
+ "typecheck": "tsc --noEmit",
47
+ "test": "vitest run"
49
48
  }
50
- }
49
+ }