@paigy/mcp 0.30.0 → 0.31.1

package/dist/{chunk-3QSGCROD.js → chunk-2WPQJYJH.js}

@@ -2490,6 +2490,14 @@ var NotifyRequestSchema = z.object({
   waiting: z.enum(["none", "soft", "hard"]).optional().describe(
     "With `ask`: what happens to your work while you wait. 'none' = you're just informing the user. 'soft' = you'd like an answer but can keep working. 'hard' = you are stopped until they answer (reaches them urgently and escalates to a real phone call if unanswered). Replaces urgencyHint + blocking \u2014 send this one field."
   ),
+  /** Δ9b (#895): HOLD this claim so the sender can correct the plan before anyone is
+   *  interrupted. Opt-in per claim, because the fail-open is a minute-granularity cron —
+   *  holding by default would charge every quiet claim that minute before any agent could
+   *  correct anything. Ignored for `waiting: 'hard'`: a blocking ask rings on what we have,
+   *  and the enrichment can still land mid-call (#781 re-plans the unspoken tail). */
+  confirm: z.boolean().optional().describe(
+    "Hold this one so you can correct the plan before the user is interrupted. The response comes back with `held: true` and the plan; POST the confirm route to release it (with options/visuals/urgency corrections, or nothing at all). If you never do, it is announced anyway a couple of minutes later. Ignored when waiting is 'hard'."
+  ),
   /** #575: a RELAY of the user's explicitly stated preference, never the agent's
    *  choice. Outranks waiting in both directions: 'call' rings even for a
    *  waiting:'none' "call me when it's done"; 'message' never rings even for
@@ -2776,6 +2784,25 @@ var NotifyResponseSchema = z.object({
   answer: UserAnswerSchema.optional(),
   answeredAt: z.string().datetime().optional()
 });
+var NotifyPlanUnitSchema = z.object({
+  notificationId: z.string(),
+  /** The unit's own heading, so the agent can tell which of its paragraphs this became. */
+  title: z.string(),
+  /** How loudly this unit was arbitrated to arrive — per unit, which is the point of units. */
+  level: NotifyLevelSchema,
+  /** Answered from something the user already decided: nobody is interrupted, and a trail card
+   *  says so. The agent should not wait on this one. */
+  settled: z.literal(true).optional(),
+  /** What this unit would need to be answerable and does not carry (#894). A PROPOSAL to the
+   *  agent — nothing here changed the ask, and ignoring it costs nothing. */
+  needs: z.array(z.enum(["options", "visuals"])).optional()
+});
+var NotifyPlanSchema = z.object({
+  units: z.array(NotifyPlanUnitSchema),
+  /** Which unit is this arrival's ONE interruption (units-design.md D23). Absent means nobody
+   *  was interrupted — every unit was either settled or quiet enough to sit in the inbox. */
+  speaks: z.string().optional()
+});
 var UserResponseSchema = z.object({
   requestId: z.string(),
   answer: UserAnswerSchema,
@@ -2830,6 +2857,20 @@ var InboxItemSchema = z.object({
   /** The conversation thread + connection this item lives on. Present on the replied
    *  detail — they power History's "Continue" / "New session from this" (#57/#251). */
   parentId: z.string().optional(),
+  /** THE ARRIVAL this row is one unit of (`notifications.ask_id` → `asks`). A claim is one
+   *  arrival and its units are N rows of it, so this — not `parentId` — is what makes a
+   *  multi-part notification one thing on screen. The thread is the whole CONVERSATION: it
+   *  accumulates every message an agent ever sent, so grouping by it renders a day of
+   *  unrelated updates as a single "12-part request". Absent on rows written before the
+   *  `asks` table, and on anything that never went through `notify` — both fall back to the
+   *  thread, which is what the client did for all rows until now. */
+  askId: z.string().optional(),
+  /** WHERE this unit sat in the message it was cut from (`notifications.seq`). The batch
+   *  shares one `created_at` to the microsecond, so without it the author's order is
+   *  unrecoverable client-side — a four-paragraph briefing rendered opening-paragraph-last
+   *  (live 2026-08-10, D35). The API already orders by it; this lets a reader that
+   *  re-sorts (grouping, filtering) put an arrival back in the order it was written. */
+  seq: z.number().int().optional(),
   tokenId: z.string().optional(),
   status: NotifyStatusSchema,
   context: ContextSchema,
@@ -3279,6 +3320,11 @@ var DeviceTokenSchema = z.object({
   /** The token's server-side id — the face's COLOUR anchor, and the only seed ingredient
    *  that survives a rename. Cached by the host's identity beat. */
   token_id: z.string().nullable().optional(),
+  /** WHERE this identity works — the folder a wake should land it in. Written by the host
+   *  at spawn and by `paigy-harness handoff` from a live terminal. Without it every wake
+   *  landed in the FIRST granted workspace and the agent rediscovered its own repo from
+   *  the thread each time (host.ts, live catch 2026-08-06 — prompt-papered until now). */
+  workspace: z.string().nullable().optional(),
   phone_reveal: PairingRevealSchema.nullable().optional(),
   // present once the phone reveals
   uik_pub: z.string().nullable().optional()
@@ -4067,6 +4113,14 @@ async function setIdentity(patch, opts = {}) {
   if (!res.ok) throw new Error(`set_identity failed: ${res.status} ${await res.text()}`);
   return await res.json();
 }
+async function heartbeat(runtime, opts = {}) {
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/presence`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${authToken(opts.token)}` },
+    ...runtime !== void 0 ? { body: JSON.stringify({ runtime }) } : {}
+  }));
+  if (!res.ok) throw new Error(`heartbeat failed: ${res.status}`);
+}
 async function setTaskState(notificationId, state, opts = {}) {
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/notify/${notificationId}/state`, {
     method: "PATCH",
@@ -4143,6 +4197,7 @@ export {
   hatch,
   whoAmI,
   setIdentity,
+  heartbeat,
   setTaskState,
   registerDelivery,
   scheduleCallback,

package/dist/{chunk-57N3NFYG.js → chunk-ENE65M5Y.js}

@@ -1,6 +1,6 @@
 import {
   AGENT_NAME
-} from "./chunk-3QSGCROD.js";
+} from "./chunk-2WPQJYJH.js";
 
 // src/clients.ts
 import { execFile } from "child_process";

package/dist/{chunk-KMPAFUT6.js → chunk-PYORUJ7Q.js}

@@ -151,6 +151,14 @@ var NotifyRequestSchema = z.object({
   waiting: z.enum(["none", "soft", "hard"]).optional().describe(
     "With `ask`: what happens to your work while you wait. 'none' = you're just informing the user. 'soft' = you'd like an answer but can keep working. 'hard' = you are stopped until they answer (reaches them urgently and escalates to a real phone call if unanswered). Replaces urgencyHint + blocking \u2014 send this one field."
   ),
+  /** Δ9b (#895): HOLD this claim so the sender can correct the plan before anyone is
+   *  interrupted. Opt-in per claim, because the fail-open is a minute-granularity cron —
+   *  holding by default would charge every quiet claim that minute before any agent could
+   *  correct anything. Ignored for `waiting: 'hard'`: a blocking ask rings on what we have,
+   *  and the enrichment can still land mid-call (#781 re-plans the unspoken tail). */
+  confirm: z.boolean().optional().describe(
+    "Hold this one so you can correct the plan before the user is interrupted. The response comes back with `held: true` and the plan; POST the confirm route to release it (with options/visuals/urgency corrections, or nothing at all). If you never do, it is announced anyway a couple of minutes later. Ignored when waiting is 'hard'."
+  ),
   /** #575: a RELAY of the user's explicitly stated preference, never the agent's
    *  choice. Outranks waiting in both directions: 'call' rings even for a
    *  waiting:'none' "call me when it's done"; 'message' never rings even for
@@ -382,6 +390,25 @@ var NotifyResponseSchema = z.object({
   answer: UserAnswerSchema.optional(),
   answeredAt: z.string().datetime().optional()
 });
+var NotifyPlanUnitSchema = z.object({
+  notificationId: z.string(),
+  /** The unit's own heading, so the agent can tell which of its paragraphs this became. */
+  title: z.string(),
+  /** How loudly this unit was arbitrated to arrive — per unit, which is the point of units. */
+  level: NotifyLevelSchema,
+  /** Answered from something the user already decided: nobody is interrupted, and a trail card
+   *  says so. The agent should not wait on this one. */
+  settled: z.literal(true).optional(),
+  /** What this unit would need to be answerable and does not carry (#894). A PROPOSAL to the
+   *  agent — nothing here changed the ask, and ignoring it costs nothing. */
+  needs: z.array(z.enum(["options", "visuals"])).optional()
+});
+var NotifyPlanSchema = z.object({
+  units: z.array(NotifyPlanUnitSchema),
+  /** Which unit is this arrival's ONE interruption (units-design.md D23). Absent means nobody
+   *  was interrupted — every unit was either settled or quiet enough to sit in the inbox. */
+  speaks: z.string().optional()
+});
 var UserResponseSchema = z.object({
   requestId: z.string(),
   answer: UserAnswerSchema,
@@ -436,6 +463,20 @@ var InboxItemSchema = z.object({
   /** The conversation thread + connection this item lives on. Present on the replied
    *  detail — they power History's "Continue" / "New session from this" (#57/#251). */
   parentId: z.string().optional(),
+  /** THE ARRIVAL this row is one unit of (`notifications.ask_id` → `asks`). A claim is one
+   *  arrival and its units are N rows of it, so this — not `parentId` — is what makes a
+   *  multi-part notification one thing on screen. The thread is the whole CONVERSATION: it
+   *  accumulates every message an agent ever sent, so grouping by it renders a day of
+   *  unrelated updates as a single "12-part request". Absent on rows written before the
+   *  `asks` table, and on anything that never went through `notify` — both fall back to the
+   *  thread, which is what the client did for all rows until now. */
+  askId: z.string().optional(),
+  /** WHERE this unit sat in the message it was cut from (`notifications.seq`). The batch
+   *  shares one `created_at` to the microsecond, so without it the author's order is
+   *  unrecoverable client-side — a four-paragraph briefing rendered opening-paragraph-last
+   *  (live 2026-08-10, D35). The API already orders by it; this lets a reader that
+   *  re-sorts (grouping, filtering) put an arrival back in the order it was written. */
+  seq: z.number().int().optional(),
   tokenId: z.string().optional(),
   status: NotifyStatusSchema,
   context: ContextSchema,
@@ -887,6 +928,11 @@ var DeviceTokenSchema = z.object({
   /** The token's server-side id — the face's COLOUR anchor, and the only seed ingredient
    *  that survives a rename. Cached by the host's identity beat. */
   token_id: z.string().nullable().optional(),
+  /** WHERE this identity works — the folder a wake should land it in. Written by the host
+   *  at spawn and by `paigy-harness handoff` from a live terminal. Without it every wake
+   *  landed in the FIRST granted workspace and the agent rediscovered its own repo from
+   *  the thread each time (host.ts, live catch 2026-08-06 — prompt-papered until now). */
+  workspace: z.string().nullable().optional(),
   phone_reveal: PairingRevealSchema.nullable().optional(),
   // present once the phone reveals
   uik_pub: z.string().nullable().optional()

package/dist/index.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 import {
   HandoffSchema
-} from "./chunk-KMPAFUT6.js";
+} from "./chunk-PYORUJ7Q.js";
 import {
   PAIGY_TOOL_IDS,
   autoConfigureClients,
   claudeInstallHint,
   enablePaigyTools,
   paigyToolsAllowlisted
-} from "./chunk-57N3NFYG.js";
+} from "./chunk-ENE65M5Y.js";
 import {
   clearSurface,
   writeSurface
@@ -29,6 +29,7 @@ import {
   getThread,
   handoff,
   hatch,
+  heartbeat,
   lintNotify,
   listSlots,
   normalizeSpeech,
@@ -49,7 +50,7 @@ import {
   startE2ee,
   submitNotification,
   whoAmI
-} from "./chunk-3QSGCROD.js";
+} from "./chunk-2WPQJYJH.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -128,7 +129,7 @@ var CONTACT_SCHEMA = {
   },
   required: ["ask"]
 };
-var CONTACT_DESCRIPTION = "Reach the user through Paigy \u2014 tell them something, or ask and get their answer. State what you need in `ask`, say what happens to your work while you wait in `waiting`, and Paigy handles the rest (channel, phrasing, answer format). If the user explicitly asks you to CALL them, send waiting:'hard' and say so in the ask. Returns { notificationId, parentId } \u2014 pass notificationId to await_reply for the answer, parentId to a later contact to continue the conversation. THREADING REPLACES: a threaded follow-up SUPERSEDES your earlier pending items on that thread \u2014 right for updates to one ask, WRONG for a checklist (send independent to-dos un-threaded). A threaded re-send with IDENTICAL content escalates the pending ask in place. If a reply comes back as {kind:'clarify', chunks:[...]}, the user wants more detail \u2014 contact again on the SAME parentId with an expanded ask. ONE ASK, ONE ROW: never restate a still-pending ask's question inside a NEW contact (e.g. weaving it into a briefing) \u2014 the whole answer settles on the new row and the original can never receive it. Keep waiting on the original (a live call reads every pending ask out separately, each answer routes to its own row), and use `needs` for a genuinely multi-part NEW ask.";
+var CONTACT_DESCRIPTION = "Reach the user through Paigy \u2014 tell them something, or ask and get their answer. State what you need in `ask`, say what happens to your work while you wait in `waiting`, and Paigy handles the rest (channel, phrasing, answer format). If the user explicitly asks you to CALL them, send waiting:'hard' and say so in the ask. Returns { notificationId, parentId } \u2014 pass notificationId to await_reply for the answer, parentId to a later contact to continue the conversation. When it rang, the reply also carries { ifMissed: { mode, means } }: what the user's own policy does with a call they don't take (\"Rings again 10 min, 30 min and 2 hr after the missed call, then leaves it in your inbox\"), so a no-answer tells you how long to wait before coming back. THREADING REPLACES: a threaded follow-up SUPERSEDES your earlier pending items on that thread \u2014 right for updates to one ask, WRONG for a checklist (send independent to-dos un-threaded). A threaded re-send with IDENTICAL content escalates the pending ask in place. If a reply comes back as {kind:'clarify', chunks:[...]}, the user wants more detail \u2014 contact again on the SAME parentId with an expanded ask. ONE ASK, ONE ROW: never restate a still-pending ask's question inside a NEW contact (e.g. weaving it into a briefing) \u2014 the whole answer settles on the new row and the original can never receive it. Keep waiting on the original (a live call reads every pending ask out separately, each answer routes to its own row), and use `needs` for a genuinely multi-part NEW ask.";
 var ONBOARD_DESCRIPTION = "Get this agent talking to Paigy \u2014 call it FIRST, before contact/await_reply, and any time you're unsure who you are. One call, and it does whatever the situation needs: NOT SET UP \u2192 hatches an identity instantly if this machine holds a device credential (the user ran the Paigy desktop app or harness), otherwise starts the code ceremony; ALREADY SET UP \u2192 returns your current identity and offers the two things left to decide, renaming it or unpairing; TOKEN NO LONGER VALID \u2192 says so, then re-pairs. Pass { name, voice } to choose who you are when hatching, or to RENAME yourself when already set up (voices: rachel, george, jessica, brian, lily). Safe to call any time: idempotent, and it never writes settings \u2014 the tool-allowlist state it reports is read-only. If it returns a `user_code`, print it to the user immediately and call onboard again with the `device_code`. If it returns `enable_prompt`, ask the user that question and call `enable_tools` on yes.";
 
 // src/pairing.ts
@@ -687,5 +688,21 @@ async function handleTool(request, signal) {
       throw new Error(`Unknown tool: ${request.params.name}`);
   }
 }
+var beatDown = false;
+async function beat() {
+  try {
+    const token = readToken();
+    if (!token) return;
+    await heartbeat(void 0, { token });
+    if (beatDown) console.error("paigy: presence restored \u2014 the live dot is honest again");
+    beatDown = false;
+  } catch (err) {
+    if (err instanceof UnpairedError) return;
+    if (!beatDown) console.error(`paigy: presence beat failed \u2014 the phone may show this agent offline (${String(err)})`);
+    beatDown = true;
+  }
+}
+void beat();
+setInterval(() => void beat(), 6e4).unref();
 var transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/listen.js

@@ -2,11 +2,11 @@
 import {
   WAKE_EVENT,
   wakeChannel
-} from "./chunk-KMPAFUT6.js";
+} from "./chunk-PYORUJ7Q.js";
 import {
   checkReplies,
   registerDelivery
-} from "./chunk-3QSGCROD.js";
+} from "./chunk-2WPQJYJH.js";
 
 // src/listen.ts
 import { createClient } from "@supabase/supabase-js";

package/dist/onboard.js

@@ -3,7 +3,7 @@ import {
   autoConfigureClients,
   claudeInstallHint,
   openBrowser
-} from "./chunk-57N3NFYG.js";
+} from "./chunk-ENE65M5Y.js";
 import {
   AGENT_NAME,
   TOKEN_PATH,
@@ -17,7 +17,7 @@ import {
   setIdentity,
   sleep,
   whoAmI
-} from "./chunk-3QSGCROD.js";
+} from "./chunk-2WPQJYJH.js";
 
 // src/onboard.ts
 async function main() {

package/dist/statusline.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paigy/mcp",
-  "version": "0.30.0",
+  "version": "0.31.1",
   "description": "Paigy MCP server — a voice inbox for your AI agents. Lets an agent notify a user and await their reply.",
   "license": "MIT",
   "type": "module",