@paigy/mcp 0.17.0 → 0.17.1

package/dist/{chunk-4LQAS5ZB.js → chunk-RMTTO6BI.js}

@@ -2278,6 +2278,26 @@ 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.")
 });
+var ParticipantSchema = z.object({
+  kind: z.enum(["human", "agent"]),
+  id: z.string()
+});
+var TransformSchema = z.enum([
+  "structure",
+  // shape intent into an answer contract; pick channel/urgency — broker `ask`, `select` shapes, `points`
+  "request_more",
+  // clarify / follow-ups / uncovered points; escalate inbox→call — {kind:'clarify'}, escalate, blocking
+  "redirect",
+  // seed / hand off a thread to a new recipient — handoff, "new session from this"
+  "break_down",
+  // one bundle → many sub-asks — checklist fan-out, `points`
+  "coalesce",
+  // many bundles → one — morning triage (#347), threading-supersede, digest
+  "organize",
+  // group related bundles onto one thread — threading (`threadId`), parent/clarify links
+  "summarize"
+  // reduce volume, keep decision value — 30-turn cap, spoken briefing
+]);
 var OptionSchema = z.object({
   id: z.string(),
   label: z.string(),
@@ -2295,6 +2315,37 @@ var VisualSchema = z.object({
   label: z.string().optional()
 });
 var NotifyLevelSchema = z.enum(["inbox", "push", "banner", "call"]);
+var SelectShapeSchema = z.enum(["one", "many", "rank", "confirm", "text"]);
+var ReceiptEventSchema = z.enum([
+  "delivered",
+  // the bundle reached the recipient at some level
+  "seen",
+  // the recipient opened it
+  "answered",
+  // the recipient replied
+  "escalated",
+  // re-reached at a higher level (re-ring / promote)
+  "coalesced",
+  // merged into another live claim
+  "expired",
+  // deadline passed unanswered
+  "woke",
+  // the agent was woken for an owed obligation (callback)
+  "gave_up"
+  // the budget was spent — stopped re-engaging
+]);
+var AttentionSchema = z.object({
+  urgency: NotifyLevelSchema,
+  /** The required answer shape, or null for a plain notify that asks nothing back. */
+  select: SelectShapeSchema.nullable(),
+  /** Coverage contract (#396) — points the answer must address; null = none declared. */
+  points: z.array(z.string()).nullable(),
+  /** Whether the ask blocks the sender — what lets arbitration escalate it on silence. */
+  blocking: z.boolean(),
+  /** Reserved (MODEL.md lists it): a response deadline. No row column yet — a later Phase 2
+   *  slice wires it; optional so today's rows/callers project cleanly. */
+  deadline: z.string().datetime().nullable().optional()
+});
 var NotifyRequestSchema = z.object({
   /** Plaintext message content. Present on the plaintext path (today's shape);
    *  ABSENT on the E2EE path, where the sealed `envelope` below carries it. The
@@ -2337,7 +2388,7 @@ var NotifyRequestSchema = z.object({
     options: z.lazy(() => EnvelopeSchema).optional(),
     visuals: z.lazy(() => EnvelopeSchema).optional()
   }).optional(),
-  select: z.enum(["one", "many", "rank", "confirm", "text"]).optional().describe(
+  select: SelectShapeSchema.optional().describe(
     "How the user answers \u2014 required on the fully-shaped form, pick the shape that fits the question: 'one' = pick one option, 'many' = pick several, 'rank' = pick & order (each needs `options`); 'confirm' = yes/no or approve/deny; 'text' = free-form reply only (status updates, open questions). 'confirm' and 'text' take no options. Omit only when sending the simplified `ask` form \u2014 the broker picks the shape."
   ),
   /** The simplified form (#395): instead of shaping the notification yourself
@@ -2713,6 +2764,17 @@ var CreateRequestSchema = z.object({
    *  the agent reads it via get_thread. Must belong to the requesting user. */
   contextThreadId: z.string().optional()
 });
+var HandoffSchema = z.object({
+  /** Land the note on an existing thread; omitted mints a fresh one. */
+  threadId: z.string().uuid().optional(),
+  /** One-line headline of the working context handed off. */
+  title: z.string().min(1),
+  /** The brief — standalone notes the successor reads (what was done, what's left, links). */
+  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()
+});
 var DeliveryModeSchema = z.enum(["poll", "self_hosted"]);
 var RegisterDeliverySchema = z.object({ mode: DeliveryModeSchema });
 var OAuthStartSchema = z.object({
@@ -3502,6 +3564,16 @@ async function scheduleCallback(req) {
   if (!res.ok) throw new Error(`schedule_callback failed: ${res.status} ${await res.text()}`);
   return await res.json();
 }
+async function handoff(req) {
+  const token = readToken();
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/handoff`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+    body: JSON.stringify(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;
@@ -3575,5 +3647,6 @@ export {
   setTaskState,
   registerDelivery,
   scheduleCallback,
+  handoff,
   lintNotify
 };

package/dist/index.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
+import {
+  HandoffSchema
+} from "./chunk-MH6AHNUI.js";
 import {
   autoConfigureClients,
   claudeInstallHint
-} from "./chunk-ZIOTFQPK.js";
+} from "./chunk-IMIXCPTN.js";
 import {
   clearSurface,
   writeSurface
@@ -19,6 +22,7 @@ import {
   fetchCredential,
   finalizeE2ee,
   getThread,
+  handoff,
   lintNotify,
   pairStep,
   readKeyFile,
@@ -32,7 +36,7 @@ import {
   sleep,
   startE2ee,
   submitNotification
-} from "./chunk-4LQAS5ZB.js";
+} from "./chunk-RMTTO6BI.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -173,6 +177,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       description: "Notify the user via Paigy. Returns { notificationId, threadId } \u2014 pass notificationId to await_reply for the answer, threadId to notify_user to continue the conversation. THREADING REPLACES: a threaded follow-up SUPERSEDES your earlier pending items on that thread (they leave the user's inbox; the response reports supersededCount) \u2014 right for updates to one ask, WRONG for a checklist: send parallel to-dos as separate un-threaded notifications. SIMPLEST FORM \u2014 just state what you need: { ask: \"I need to know whether to deploy the auth fix \u2014 tests are green, staging verified\", urgencyHint: 'now'|'soon'|'whenever', needs?: [\"deploy?\", \"keep the flag?\"] }. Paigy's broker derives the title, answer shape, options, and delivery channel for you \u2014 prefer this unless you specifically need to control the exact options/shape. The fully-shaped form below remains available and unchanged (the two are mutually exclusive: send `ask` OR `context`+`select`). FULLY-SHAPED FORM: provide context.title (a specific, non-empty one-line headline \u2014 this is what the user sees first, and what shows on the ring for a call) and context.description (an array of standalone, non-empty detail chunks the user can selectively ask you to expand). Set `urgency`: 'inbox' (default) drops it silently in their inbox; 'push' is a quiet passive notification (no sound); 'banner' sends a time-sensitive banner/lock-screen push (a 'paige') they tap to open \u2014 for when you need them soon-ish but not enough to ring them; 'call' rings their phone now as a voice call \u2014 only when you genuinely need them in the moment (blocked/waiting, time-sensitive). This is the premier use case for Paigy: getting UNBLOCKED so you can keep working, not just reporting that you're stuck. The user started a big task and went to do something else \u2014 the cardinal failure is going idle on one small decision and silently waiting to be checked on, so they come back to find you never actually progressed. Judge urgency by how much WORK IS BLOCKED behind this decision (a lot of dependent downstream work \u2192 call, even if it's a single question), not by how many things happen to be pending \u2014 one blocking decision outweighs five independent low-stakes ones sitting in the inbox. Set `blocking: true` whenever that's the case, independent of `urgency` \u2014 it's what lets Paigy escalate this to a real call later on its own if it goes unanswered, even if you sent it at a lower urgency. Don't set it for things you could work around, defer, or where other useful work exists meanwhile. ON A CALL, your title + description are READ ALOUD by a voice \u2014 write them to be HEARD, not read: keep it short and conversational, front-load the ask, and refer to things BY NAME, not by ID or code (say 'the pull request about the agents page', not 'PR #235'; 'the login-bug ticket', not 'ABC-1234'). Spell out only what's natural to say out loud. MATCH the answer shape to the question \u2014 `select` is required; pick the best tool for the job, not always yes/no. The user can ALWAYS add free text on top of any shape, so structuring loses nothing. Choose `select`: yes/no \u2192 select:'confirm' \u2192 {kind:'confirm', approved:boolean}. Approve/deny an action \u2192 select:'confirm' + confirmStyle:'approve' \u2192 {kind:'confirm', approved:boolean}. Both are answerable right from the banner \u2014 no need to open the app. Pick one of several \u2192 options + select:'one' \u2192 {kind:'option', optionId}. Pick several / a subset \u2192 options + select:'many' \u2192 {kind:'multi', optionIds:[...]}. Rank or prioritize \u2192 options + select:'rank', user taps in preferred order \u2192 {kind:'ranked', optionIds:[...]}. One/many/rank/text all need the user to open the app to answer \u2014 only confirm is answerable straight from the banner. Options carry no ids \u2014 they're assigned by position ('1', '2', \u2026), and the answer's optionId(s) are those positions. For visual choices give each option a sandboxed `html` or an `image` preview (e.g. layout/UI alternatives); use `visuals` for images that set context for the whole question. select:'text' = free-form reply only (plain updates, or answers that genuinely can't be structured). If a reply comes back as {kind:'clarify', chunks:[...]}, the user wants more detail on those chunks \u2014 respond via notify_user with the SAME threadId and an expanded description. Pass `threadId` from a prior notify_user result or an await_reply reply to continue that conversation thread; omit it to start a new one. To follow up on a call (e.g. the user asked you to 'call me back when it's done'), reuse the threadId from that call's reply so it threads as the same conversation.",
       inputSchema: json(NotifyRequestSchema)
     },
+    {
+      // North-star Phase 1 (NORTH-STAR.md): `notify` is the general routing verb — attach
+      // attention to context and route it to a participant (MODEL.md §4). `notify_user` is
+      // kept as an alias (same input, same behavior) until every caller has moved; the
+      // `_user` is a naming holdover from when the only recipient was a human.
+      name: "notify",
+      description: "Route a notification via Paigy (the general form of notify_user \u2014 identical input and behavior). Prefer this name going forward. See notify_user for the full argument guide: the simple `ask` form, the fully-shaped context+select form, urgency levels, blocking, and threading.",
+      inputSchema: json(NotifyRequestSchema)
+    },
     {
       name: "await_reply",
       description: "Wait for the user's reply to a specific notification you sent (pass the notificationId from notify_user). This is how you wait for your answer in-context. Polls ~5 min; returns { type:'reply', answer } when they respond, { type:'remind', remindInSeconds } on snooze (ScheduleWakeup then await_reply again), or { type:'idle' } (timed out this window, no answer yet). On idle, if this is genuinely still blocking you and you have nothing else useful to do meanwhile, just call await_reply again immediately \u2014 keep looping. This is how you actually deliver on the point of calling: the user steps away for a while and comes back to find you'd already continued the moment they answered, not idle waiting to be checked on. Don't give up after one window. Only stop looping to do other work (and check back later), or after an unreasonably long stretch (tens of minutes to hours) worth telling the user about instead. Scoped to that one notification \u2014 it NEVER returns replies meant for other notifications, so concurrent notify_user calls don't cross. A CALL answer can come back as {kind:'turns', turns:[{prompt,reply}]} \u2014 the ordered log of that call. Read turns[0].reply as the user's main instruction. Usually that's the only turn; if there are more (e.g. an end-of-call 'call me back when it's done / I have a blocking question'), read each one in order as a further follow-up instruction, not a single combined one. If they asked for a callback, re-engage in the SAME thread (notify_user with the reply's threadId) when the task is done or you hit a blocker \u2014 urgency:'call' for a blocker, 'banner'/'push'/'inbox' for done. Paigy has no scheduler; the callback is yours to send (use ScheduleWakeup/cron for timing). A call-mapped answer may carry `intents` \u2014 next steps the user attached, each { kind, detail } with detail quoting their words. ACT on them, don't just read them: 'defer' (\"call me after lunch\") \u2192 register it NOW with schedule_callback \u2014 when the intent carries `dueInSeconds` (Paigy pre-parsed the spoken time against the user's clock) pass it straight through; otherwise derive it from the detail yourself \u2014 then follow up on the same thread; 'delegate' (\"you pick\") \u2192 make the call yourself and tell them what you chose; 'channel' (\"text me next time\") \u2192 honor it on your next contact (lower urgency). `transcript` is the user's raw words behind a shaped answer \u2014 read it for hedges and conditions (\"yes, IF tests pass\") before acting. If your ask declared `points`, the reply carries `covered` \u2014 the points actually addressed. Compare against what you declared: a missing point is STILL unanswered \u2014 re-ask it (notify_user on the same threadId) or proceed knowingly partial; never treat a partial answer as complete.",
@@ -197,6 +210,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "schedule_callback",
       description: "Promise the user a follow-up you'll keep even if you go idle. Use it when they ask you to report back: trigger 'on_done' (when you finish \u2014 fires when you call set_task_state completed), 'on_blocked' (if you hit a blocker \u2014 fires on set_task_state needs_input), or 'scheduled' with dueInSeconds (e.g. 'remind me in 10 min'). Pass the threadId of the conversation and a short note. Fulfill it by calling notify_user on that threadId; check_replies re-lists due callbacks until you do.",
       inputSchema: json(ScheduleCallbackSchema)
+    },
+    {
+      name: "handoff",
+      description: "Deposit your working context for a SUCCESSOR agent \u2014 what you did, what's left, links, gotchas \u2014 as one note on a thread ({ title, notes[] }). This does NOT ring the user or enter their inbox: it's context, not a question. The successor reads it back with get_thread. Pass `target` (a sibling connection's token id or agent nickname, SAME account only) to hand off DIRECTLY to that agent \u2014 the note is dispatched to it as a request it picks up. Omit `target` to leave the thread for the user to hand off to an agent themselves in the app. Pass `threadId` to land the handoff on an existing conversation; omit it to mint a fresh thread. Returns { threadId }.",
+      inputSchema: json(HandoffSchema)
     }
   ]
 }));
@@ -318,6 +336,8 @@ Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
         }]
       };
     }
+    // `notify` (the general routing verb) and `notify_user` (its alias) share one handler.
+    case "notify":
     case "notify_user": {
       const parsed = NotifyRequestSchema.parse(request.params.arguments);
       const problems = lintNotify(parsed);
@@ -358,6 +378,10 @@ Enter it in the Paigy app (Inbox \u2192 Add a new agent).`,
       const result = await scheduleCallback(ScheduleCallbackSchema.parse(request.params.arguments));
       return { content: [{ type: "text", text: JSON.stringify(result) }] };
     }
+    case "handoff": {
+      const result = await handoff(HandoffSchema.parse(request.params.arguments));
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }
     default:
       throw new Error(`Unknown tool: ${request.params.name}`);
   }