@paigy/mcp 0.27.0 → 0.28.0

package/README.md

@@ -1,5 +1,9 @@
 # @paigy/mcp
 
+> **Canonical setup:** `curl -fsSL https://paigy.ai/install | sh` — one command, one
+> QR scan; no pairing codes. Everything below is the manual per-client reference for
+> machines that can't run the harness.
+
 A voice inbox for your AI agents. This MCP server lets an agent **notify a user** and **await their reply** — so a long-running agent can ask a question, hand off, and resume on the answer. It's a thin MCP-tool wrapper over `@paigy/sdk` (`packages/sdk`) — use the SDK directly from any Node process that isn't an MCP client.
 
 ## Install

package/dist/{chunk-47E77CDG.js → chunk-FRYGTKLM.js}

@@ -20,7 +20,7 @@ var TransformSchema = z.enum([
   "coalesce",
   // many bundles → one — morning triage (#347), threading-supersede, digest
   "organize",
-  // group related bundles onto one thread — threading (`threadId`), parent/clarify links
+  // group related bundles onto one thread — threading (`parentId`), parent/clarify links
   "summarize"
   // reduce volume, keep decision value — 30-turn cap, spoken briefing
 ]);
@@ -90,13 +90,19 @@ var NotifyRequestSchema = z.object({
   repo: z.string().optional(),
   /** Git branch the agent is on. Local MCP fills this from the checkout — omit unless overriding. */
   branch: z.string().optional(),
-  /** Continue an existing conversation; omitted = start a new thread. */
-  threadId: z.string().uuid().optional(),
+  /** Continue an existing conversation — the id of any notification in it (its root
+   *  is the conversation's identity). Omitted = start a new conversation. Renamed
+   *  from `parentId` (2026-08-03): one linkage system, the parent; the API edge
+   *  still accepts the old name from older clients. */
+  parentId: z.string().uuid().optional(),
   urgency: NotifyLevelSchema.default("inbox").describe(
     "The level you're requesting \u2014 the user's account permissions + session mode can lower it. 'inbox' (default) = sits silently in the inbox for the user to get to. 'push' = a quiet passive push (lands in Notification Center, no sound) \u2014 a gentle heads-up. 'banner' = a time-sensitive banner/lock-screen push with sound (a 'paige') they tap to open \u2014 use when you need them soon-ish but it's not worth ringing them. 'call' = rings the user's phone now (a CallKit voice call) \u2014 use only when you genuinely need them in the moment (blocked and waiting, time-sensitive). context.title is what they see on the banner/ring, so make it specific."
   ),
-  /** The request this one was spawned from, for a clarification. */
-  parentId: z.string().optional(),
+  /** The request this one CLARIFIES — spawning a clarification keeps that parent
+   *  visible and marks it needs_input. Renamed from the old `parentId` (2026-08-03)
+   *  when `parentId` became the conversation handle: `parentId` says WHERE, this
+   *  says HOW. */
+  clarifies: z.string().optional(),
   /** E2EE (text lane): when the pairing is E2EE, the sealed replacements for the
    *  plaintext content fields, keyed by field name. FINALIZED wire shape (was
    *  provisional in the storage PR): a per-field map `{ context?, options?,
@@ -216,7 +222,7 @@ var IntentSchema = z.object({
   // it by two ("detail", "feedback"), and because the settle handler parsed the array
   // all-or-nothing, ONE feedback act silently dropped EVERY intent on the call,
   // questions included. Found auditing five calls' stored feedback, 2026-08-01.
-  kind: z.enum(["defer", "delegate", "channel", "question", "detail", "feedback", "command"]),
+  kind: z.enum(["defer", "delegate", "channel", "question", "detail", "feedback", "command", "control"]),
   detail: z.string(),
   /** Landed defer (#397): the MCP parses common spoken forms ("in 20 minutes",
    *  "after lunch") against the agent machine's clock — the user's — and attaches
@@ -227,7 +233,7 @@ var IntentSchema = z.object({
 var AwaitItemSchema = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("reply"),
-    threadId: z.string(),
+    parentId: z.string(),
     notificationId: z.string(),
     answer: UserAnswerSchema,
     /** E2EE: present when the answer is sealed. The server relays the opaque answer
@@ -248,7 +254,7 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
   }),
   z.object({
     type: z.literal("remind"),
-    threadId: z.string(),
+    parentId: z.string(),
     notificationId: z.string(),
     remindAt: z.string().datetime({ offset: true }),
     /** Seconds until remindAt, server-computed — pass straight to ScheduleWakeup. */
@@ -260,7 +266,7 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
    *  re-orient via get_thread / check_replies). */
   z.object({
     type: z.literal("superseded"),
-    threadId: z.string(),
+    parentId: z.string(),
     notificationId: z.string()
   }),
   /** A LIVE call's turn, streamed as it lands (#783). PROVISIONAL: the user can still
@@ -283,7 +289,7 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
 ]);
 var CallbackTriggerSchema = z.enum(["on_done", "on_blocked", "scheduled"]);
 var ScheduleCallbackSchema = z.object({
-  threadId: z.string().describe("The thread to call back on (from a prior contact / reply / request)."),
+  parentId: z.string().describe("The thread to call back on (from a prior contact / reply / request)."),
   trigger: CallbackTriggerSchema,
   dueInSeconds: z.number().int().positive().optional().describe("For 'scheduled' only: how many seconds from now to fire."),
   note: z.string().optional().describe("What to tell the user when you follow up.")
@@ -291,7 +297,7 @@ var ScheduleCallbackSchema = z.object({
 var PendingRepliesSchema = z.object({
   replies: z.array(
     z.object({
-      threadId: z.string(),
+      parentId: z.string(),
       notificationId: z.string(),
       answer: UserAnswerSchema,
       /** E2EE: the sealed answer (opaque envelope + plaintext `ignored` hint) when the
@@ -308,33 +314,33 @@ var PendingRepliesSchema = z.object({
     })
   ),
   pending: z.array(
-    z.object({ threadId: z.string(), notificationId: z.string(), createdAt: z.string() })
+    z.object({ parentId: z.string(), notificationId: z.string(), createdAt: z.string() })
   ),
   /** User-initiated requests addressed to this agent; act on them and reply via
-   *  contact on the same threadId. Keeps reappearing until you call
+   *  contact on the same parentId. Keeps reappearing until you call
    *  set_task_state on its notificationId. */
   requests: z.array(
     z.object({
-      threadId: z.string(),
+      parentId: z.string(),
       notificationId: z.string(),
       text: z.string(),
       createdAt: z.string(),
       /** The user seeded this request with a past conversation — call get_thread on it
        *  FIRST and treat the transcript as prior context (#57/#251). */
-      contextThreadId: z.string().optional()
+      contextParentId: z.string().optional()
     })
   ),
   /** Callbacks you owe the user that are now DUE (you said you'd follow up when done,
    *  if blocked, or at a time that has passed). Re-surfaced every sweep until you
-   *  fulfill one by calling contact on its threadId. */
+   *  fulfill one by calling contact on its parentId. */
   owedCallbacks: z.array(
-    z.object({ threadId: z.string(), trigger: CallbackTriggerSchema, note: z.string() })
+    z.object({ parentId: z.string(), trigger: CallbackTriggerSchema, note: z.string() })
   ),
   /** Work (either direction) you reported in_progress a while ago and never reported
    *  completed — likely left half-done by this session or a prior one that crashed or
    *  went idle. Report a real state (set_task_state) or continue the work. */
   stalled: z.array(
-    z.object({ threadId: z.string(), notificationId: z.string(), title: z.string().nullable(), startedAt: z.string() })
+    z.object({ parentId: z.string(), notificationId: z.string(), title: z.string().nullable(), startedAt: z.string() })
   ),
   /** The queue rail (#614, pending/design.md): the same replies + requests, grouped by
    *  thread and ordered oldest-thread-first, so you work ONE thread at a time — fold all of
@@ -345,7 +351,7 @@ var PendingRepliesSchema = z.object({
    *  notificationId). Derived, never stored — a crashed agent recomputes it exactly. */
   threads: z.array(
     z.object({
-      threadId: z.string(),
+      parentId: z.string(),
       busy: z.boolean(),
       items: z.array(
         z.object({
@@ -398,13 +404,21 @@ var AgendaTurnSchema = z.object({
    *  caller already answered this claim in an earlier utterance, quoted here VERBATIM —
    *  the bot speaks the turn's short confirmation, posts these words as the claim's
    *  answer, and never re-asks. Grounded at parse time: an invented settle is #796. */
-  settle: z.string().optional()
+  settle: z.string().optional(),
+  /** Pacing (#826, owner 2026-08-03: "how fast we move through them ... are parameters"):
+   *  seconds the floor stays open after this turn speaks. Absent = the bot's defaults
+   *  (the beat for context, the answer window for asks). Clamped bot-side. */
+  pace: z.number().positive().optional(),
+  /** Whether the walk WAITS for an answer before moving on. Absent = derived as today
+   *  (a question blocks, context flows). blocking:false on a question = ask and move
+   *  on, the claim stays pending; blocking:true on context = hold for a reply. */
+  blocking: z.boolean().optional()
 });
 var InboxItemSchema = z.object({
   id: z.string(),
   /** The conversation thread + connection this item lives on. Present on the replied
    *  detail — they power History's "Continue" / "New session from this" (#57/#251). */
-  threadId: z.string().optional(),
+  parentId: z.string().optional(),
   tokenId: z.string().optional(),
   status: NotifyStatusSchema,
   context: ContextSchema,
@@ -438,7 +452,7 @@ var InboxItemSchema = z.object({
    *  the agent (provider-agnostic; set server-side). Absent = no hard error, though the
    *  client may still flag a stall by age. Drives the inbox error badge + Retry. */
   error: z.string().optional(),
-  parentId: z.string().optional(),
+  clarifies: z.string().optional(),
   select: z.enum(["one", "many", "rank", "confirm", "text"]).default("one"),
   confirmStyle: z.enum(["yesno", "approve"]).default("yesno").describe(
     "Labels for a select:'confirm' paige \u2014 'yesno' (Yes/No) or 'approve' (Approve/Deny). Ignored unless select is 'confirm'."
@@ -537,7 +551,7 @@ var UserSettingsSchema = z.object({
 });
 var HistoryItemSchema = z.object({
   id: z.string(),
-  threadId: z.string(),
+  parentId: z.string(),
   /** 'user' = a request you sent; 'agent' = a notification an agent sent you. */
   initiator: z.enum(["user", "agent"]),
   title: z.string(),
@@ -564,6 +578,16 @@ var ConnectionSummarySchema = z.object({
   /** Most recent notification on this connection, either direction. Null = no contact yet.
    *  Drives the agents-page recency grouping (Today / This week / …). */
   lastContactAt: z.string().datetime().nullable(),
+  /** Last presence heartbeat from a running agent process (POST /api/presence) — the
+   *  desktop app while open. Null = never seen; stale = offline. */
+  lastSeenAt: z.string().datetime().nullable().optional(),
+  /** What a live desktop can run (companion.md §2.2), advertised on its heartbeat:
+   *  harness availabilities + granted workspaces — the option set the phone's
+   *  "new session" sheet offers. Absent for ordinary MCP agents. */
+  runtime: z.object({
+    harnesses: z.array(z.object({ name: z.string(), label: z.string(), status: z.string() })).optional(),
+    workspaces: z.array(z.string()).optional()
+  }).optional(),
   /** True = a provider-managed agent running in the provider's cloud (e.g. Anthropic CMA);
    *  false = a local MCP connection running on the user's computer (Claude Code/Codex/…). */
   managed: z.boolean()
@@ -575,15 +599,15 @@ var CreateRequestSchema = z.object({
   text: z.string().min(1),
   /** Land the request on an existing conversation thread (History → "Continue")
    *  instead of minting a fresh one. Must belong to the requesting user. */
-  threadId: z.string().optional(),
+  parentId: z.string().optional(),
   /** Point the agent at a past conversation (possibly with a different agent) as
    *  starting context (History → "New session from this"). A reference, not a copy —
    *  the agent reads it via get_thread. Must belong to the requesting user. */
-  contextThreadId: z.string().optional()
+  contextParentId: z.string().optional()
 });
 var HandoffSchema = z.object({
   /** Land the note on an existing thread; omitted mints a fresh one. */
-  threadId: z.string().uuid().optional(),
+  parentId: 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). */
@@ -622,7 +646,7 @@ var NoteSchema = z.object({
   /** Who it was assigned to (a participant ref, 'agent:<tokenId>'); null = unassigned. */
   assignee: z.string().nullable(),
   /** The request thread minted at assignment; null until assigned. */
-  threadId: z.string().nullable(),
+  parentId: z.string().nullable(),
   createdAt: z.string()
 });
 var CreateNoteSchema = z.object({
@@ -638,8 +662,17 @@ var RecordDecisionSchema = z.object({
   answer: z.string().min(1).max(2e3)
 }).refine((d) => d.decisionId || d.question, { message: "decisionId or question required" });
 var AssignNoteSchema = z.object({
-  target: z.string().min(1)
-});
+  /** An EXISTING agent: token id or nickname. Omit when spawning fresh. */
+  target: z.string().min(1).optional(),
+  /** Spawn a NEW session for this note (companion.md §2.2): the assignee doesn't
+   *  exist yet — mint it on a live desktop that advertises the harness+workspace,
+   *  named after the note. The brief arrives as its opening request. */
+  spawn: z.object({
+    hostTokenId: z.string().uuid(),
+    harness: z.string().min(1),
+    workspace: z.string().min(1)
+  }).optional()
+}).refine((a) => !!a.target !== !!a.spawn, { message: "exactly one of target or spawn" });
 var DeliveryModeSchema = z.enum(["poll", "self_hosted"]);
 var WAKE_EVENT = "wake";
 var wakeChannel = (tokenId) => `wake:${tokenId}`;
@@ -701,7 +734,7 @@ var DeviceRosterSchema = z.object({
 var WakeNudgeSchema = z.object({
   kind: z.enum(["reply", "request", "callback"]),
   notificationId: z.string().optional(),
-  threadId: z.string()
+  parentId: z.string()
 });
 var PairingStatusSchema = z.enum(["pending", "approved", "denied", "expired"]);
 var PairingRevealSchema = z.object({

package/dist/{chunk-VCEFF2VA.js → chunk-TE57PAKM.js}

@@ -2336,7 +2336,7 @@ var TransformSchema = z.enum([
   "coalesce",
   // many bundles → one — morning triage (#347), threading-supersede, digest
   "organize",
-  // group related bundles onto one thread — threading (`threadId`), parent/clarify links
+  // group related bundles onto one thread — threading (`parentId`), parent/clarify links
   "summarize"
   // reduce volume, keep decision value — 30-turn cap, spoken briefing
 ]);
@@ -2406,13 +2406,19 @@ var NotifyRequestSchema = z.object({
   repo: z.string().optional(),
   /** Git branch the agent is on. Local MCP fills this from the checkout — omit unless overriding. */
   branch: z.string().optional(),
-  /** Continue an existing conversation; omitted = start a new thread. */
-  threadId: z.string().uuid().optional(),
+  /** Continue an existing conversation — the id of any notification in it (its root
+   *  is the conversation's identity). Omitted = start a new conversation. Renamed
+   *  from `parentId` (2026-08-03): one linkage system, the parent; the API edge
+   *  still accepts the old name from older clients. */
+  parentId: z.string().uuid().optional(),
   urgency: NotifyLevelSchema.default("inbox").describe(
     "The level you're requesting \u2014 the user's account permissions + session mode can lower it. 'inbox' (default) = sits silently in the inbox for the user to get to. 'push' = a quiet passive push (lands in Notification Center, no sound) \u2014 a gentle heads-up. 'banner' = a time-sensitive banner/lock-screen push with sound (a 'paige') they tap to open \u2014 use when you need them soon-ish but it's not worth ringing them. 'call' = rings the user's phone now (a CallKit voice call) \u2014 use only when you genuinely need them in the moment (blocked and waiting, time-sensitive). context.title is what they see on the banner/ring, so make it specific."
   ),
-  /** The request this one was spawned from, for a clarification. */
-  parentId: z.string().optional(),
+  /** The request this one CLARIFIES — spawning a clarification keeps that parent
+   *  visible and marks it needs_input. Renamed from the old `parentId` (2026-08-03)
+   *  when `parentId` became the conversation handle: `parentId` says WHERE, this
+   *  says HOW. */
+  clarifies: z.string().optional(),
   /** E2EE (text lane): when the pairing is E2EE, the sealed replacements for the
    *  plaintext content fields, keyed by field name. FINALIZED wire shape (was
    *  provisional in the storage PR): a per-field map `{ context?, options?,
@@ -2577,7 +2583,7 @@ var IntentSchema = z.object({
   // it by two ("detail", "feedback"), and because the settle handler parsed the array
   // all-or-nothing, ONE feedback act silently dropped EVERY intent on the call,
   // questions included. Found auditing five calls' stored feedback, 2026-08-01.
-  kind: z.enum(["defer", "delegate", "channel", "question", "detail", "feedback", "command"]),
+  kind: z.enum(["defer", "delegate", "channel", "question", "detail", "feedback", "command", "control"]),
   detail: z.string(),
   /** Landed defer (#397): the MCP parses common spoken forms ("in 20 minutes",
    *  "after lunch") against the agent machine's clock — the user's — and attaches
@@ -2588,7 +2594,7 @@ var IntentSchema = z.object({
 var AwaitItemSchema = z.discriminatedUnion("type", [
   z.object({
     type: z.literal("reply"),
-    threadId: z.string(),
+    parentId: z.string(),
     notificationId: z.string(),
     answer: UserAnswerSchema,
     /** E2EE: present when the answer is sealed. The server relays the opaque answer
@@ -2609,7 +2615,7 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
   }),
   z.object({
     type: z.literal("remind"),
-    threadId: z.string(),
+    parentId: z.string(),
     notificationId: z.string(),
     remindAt: z.string().datetime({ offset: true }),
     /** Seconds until remindAt, server-computed — pass straight to ScheduleWakeup. */
@@ -2621,7 +2627,7 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
    *  re-orient via get_thread / check_replies). */
   z.object({
     type: z.literal("superseded"),
-    threadId: z.string(),
+    parentId: z.string(),
     notificationId: z.string()
   }),
   /** A LIVE call's turn, streamed as it lands (#783). PROVISIONAL: the user can still
@@ -2644,7 +2650,7 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
 ]);
 var CallbackTriggerSchema = z.enum(["on_done", "on_blocked", "scheduled"]);
 var ScheduleCallbackSchema = z.object({
-  threadId: z.string().describe("The thread to call back on (from a prior contact / reply / request)."),
+  parentId: z.string().describe("The thread to call back on (from a prior contact / reply / request)."),
   trigger: CallbackTriggerSchema,
   dueInSeconds: z.number().int().positive().optional().describe("For 'scheduled' only: how many seconds from now to fire."),
   note: z.string().optional().describe("What to tell the user when you follow up.")
@@ -2652,7 +2658,7 @@ var ScheduleCallbackSchema = z.object({
 var PendingRepliesSchema = z.object({
   replies: z.array(
     z.object({
-      threadId: z.string(),
+      parentId: z.string(),
       notificationId: z.string(),
       answer: UserAnswerSchema,
       /** E2EE: the sealed answer (opaque envelope + plaintext `ignored` hint) when the
@@ -2669,33 +2675,33 @@ var PendingRepliesSchema = z.object({
     })
   ),
   pending: z.array(
-    z.object({ threadId: z.string(), notificationId: z.string(), createdAt: z.string() })
+    z.object({ parentId: z.string(), notificationId: z.string(), createdAt: z.string() })
   ),
   /** User-initiated requests addressed to this agent; act on them and reply via
-   *  contact on the same threadId. Keeps reappearing until you call
+   *  contact on the same parentId. Keeps reappearing until you call
    *  set_task_state on its notificationId. */
   requests: z.array(
     z.object({
-      threadId: z.string(),
+      parentId: z.string(),
       notificationId: z.string(),
       text: z.string(),
       createdAt: z.string(),
       /** The user seeded this request with a past conversation — call get_thread on it
        *  FIRST and treat the transcript as prior context (#57/#251). */
-      contextThreadId: z.string().optional()
+      contextParentId: z.string().optional()
     })
   ),
   /** Callbacks you owe the user that are now DUE (you said you'd follow up when done,
    *  if blocked, or at a time that has passed). Re-surfaced every sweep until you
-   *  fulfill one by calling contact on its threadId. */
+   *  fulfill one by calling contact on its parentId. */
   owedCallbacks: z.array(
-    z.object({ threadId: z.string(), trigger: CallbackTriggerSchema, note: z.string() })
+    z.object({ parentId: z.string(), trigger: CallbackTriggerSchema, note: z.string() })
   ),
   /** Work (either direction) you reported in_progress a while ago and never reported
    *  completed — likely left half-done by this session or a prior one that crashed or
    *  went idle. Report a real state (set_task_state) or continue the work. */
   stalled: z.array(
-    z.object({ threadId: z.string(), notificationId: z.string(), title: z.string().nullable(), startedAt: z.string() })
+    z.object({ parentId: z.string(), notificationId: z.string(), title: z.string().nullable(), startedAt: z.string() })
   ),
   /** The queue rail (#614, pending/design.md): the same replies + requests, grouped by
    *  thread and ordered oldest-thread-first, so you work ONE thread at a time — fold all of
@@ -2706,7 +2712,7 @@ var PendingRepliesSchema = z.object({
    *  notificationId). Derived, never stored — a crashed agent recomputes it exactly. */
   threads: z.array(
     z.object({
-      threadId: z.string(),
+      parentId: z.string(),
       busy: z.boolean(),
       items: z.array(
         z.object({
@@ -2759,13 +2765,21 @@ var AgendaTurnSchema = z.object({
    *  caller already answered this claim in an earlier utterance, quoted here VERBATIM —
    *  the bot speaks the turn's short confirmation, posts these words as the claim's
    *  answer, and never re-asks. Grounded at parse time: an invented settle is #796. */
-  settle: z.string().optional()
+  settle: z.string().optional(),
+  /** Pacing (#826, owner 2026-08-03: "how fast we move through them ... are parameters"):
+   *  seconds the floor stays open after this turn speaks. Absent = the bot's defaults
+   *  (the beat for context, the answer window for asks). Clamped bot-side. */
+  pace: z.number().positive().optional(),
+  /** Whether the walk WAITS for an answer before moving on. Absent = derived as today
+   *  (a question blocks, context flows). blocking:false on a question = ask and move
+   *  on, the claim stays pending; blocking:true on context = hold for a reply. */
+  blocking: z.boolean().optional()
 });
 var InboxItemSchema = z.object({
   id: z.string(),
   /** The conversation thread + connection this item lives on. Present on the replied
    *  detail — they power History's "Continue" / "New session from this" (#57/#251). */
-  threadId: z.string().optional(),
+  parentId: z.string().optional(),
   tokenId: z.string().optional(),
   status: NotifyStatusSchema,
   context: ContextSchema,
@@ -2799,7 +2813,7 @@ var InboxItemSchema = z.object({
    *  the agent (provider-agnostic; set server-side). Absent = no hard error, though the
    *  client may still flag a stall by age. Drives the inbox error badge + Retry. */
   error: z.string().optional(),
-  parentId: z.string().optional(),
+  clarifies: z.string().optional(),
   select: z.enum(["one", "many", "rank", "confirm", "text"]).default("one"),
   confirmStyle: z.enum(["yesno", "approve"]).default("yesno").describe(
     "Labels for a select:'confirm' paige \u2014 'yesno' (Yes/No) or 'approve' (Approve/Deny). Ignored unless select is 'confirm'."
@@ -2898,7 +2912,7 @@ var UserSettingsSchema = z.object({
 });
 var HistoryItemSchema = z.object({
   id: z.string(),
-  threadId: z.string(),
+  parentId: z.string(),
   /** 'user' = a request you sent; 'agent' = a notification an agent sent you. */
   initiator: z.enum(["user", "agent"]),
   title: z.string(),
@@ -2925,6 +2939,16 @@ var ConnectionSummarySchema = z.object({
   /** Most recent notification on this connection, either direction. Null = no contact yet.
    *  Drives the agents-page recency grouping (Today / This week / …). */
   lastContactAt: z.string().datetime().nullable(),
+  /** Last presence heartbeat from a running agent process (POST /api/presence) — the
+   *  desktop app while open. Null = never seen; stale = offline. */
+  lastSeenAt: z.string().datetime().nullable().optional(),
+  /** What a live desktop can run (companion.md §2.2), advertised on its heartbeat:
+   *  harness availabilities + granted workspaces — the option set the phone's
+   *  "new session" sheet offers. Absent for ordinary MCP agents. */
+  runtime: z.object({
+    harnesses: z.array(z.object({ name: z.string(), label: z.string(), status: z.string() })).optional(),
+    workspaces: z.array(z.string()).optional()
+  }).optional(),
   /** True = a provider-managed agent running in the provider's cloud (e.g. Anthropic CMA);
    *  false = a local MCP connection running on the user's computer (Claude Code/Codex/…). */
   managed: z.boolean()
@@ -2936,15 +2960,15 @@ var CreateRequestSchema = z.object({
   text: z.string().min(1),
   /** Land the request on an existing conversation thread (History → "Continue")
    *  instead of minting a fresh one. Must belong to the requesting user. */
-  threadId: z.string().optional(),
+  parentId: z.string().optional(),
   /** Point the agent at a past conversation (possibly with a different agent) as
    *  starting context (History → "New session from this"). A reference, not a copy —
    *  the agent reads it via get_thread. Must belong to the requesting user. */
-  contextThreadId: z.string().optional()
+  contextParentId: z.string().optional()
 });
 var HandoffSchema = z.object({
   /** Land the note on an existing thread; omitted mints a fresh one. */
-  threadId: z.string().uuid().optional(),
+  parentId: 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). */
@@ -2983,7 +3007,7 @@ var NoteSchema = z.object({
   /** Who it was assigned to (a participant ref, 'agent:<tokenId>'); null = unassigned. */
   assignee: z.string().nullable(),
   /** The request thread minted at assignment; null until assigned. */
-  threadId: z.string().nullable(),
+  parentId: z.string().nullable(),
   createdAt: z.string()
 });
 var CreateNoteSchema = z.object({
@@ -2999,8 +3023,17 @@ var RecordDecisionSchema = z.object({
   answer: z.string().min(1).max(2e3)
 }).refine((d) => d.decisionId || d.question, { message: "decisionId or question required" });
 var AssignNoteSchema = z.object({
-  target: z.string().min(1)
-});
+  /** An EXISTING agent: token id or nickname. Omit when spawning fresh. */
+  target: z.string().min(1).optional(),
+  /** Spawn a NEW session for this note (companion.md §2.2): the assignee doesn't
+   *  exist yet — mint it on a live desktop that advertises the harness+workspace,
+   *  named after the note. The brief arrives as its opening request. */
+  spawn: z.object({
+    hostTokenId: z.string().uuid(),
+    harness: z.string().min(1),
+    workspace: z.string().min(1)
+  }).optional()
+}).refine((a) => !!a.target !== !!a.spawn, { message: "exactly one of target or spawn" });
 var DeliveryModeSchema = z.enum(["poll", "self_hosted"]);
 var RegisterDeliverySchema = z.object({ mode: DeliveryModeSchema });
 var OAuthStartSchema = z.object({
@@ -3060,7 +3093,7 @@ var DeviceRosterSchema = z.object({
 var WakeNudgeSchema = z.object({
   kind: z.enum(["reply", "request", "callback"]),
   notificationId: z.string().optional(),
-  threadId: z.string()
+  parentId: z.string()
 });
 var PairingStatusSchema = z.enum(["pending", "approved", "denied", "expired"]);
 var PairingRevealSchema = z.object({
@@ -3520,6 +3553,9 @@ function readToken(agent2 = AGENT_NAME) {
   if (process.env.PAIGY_TOKEN) return process.env.PAIGY_TOKEN;
   return readTokenFile()[agent2]?.access_token ?? "";
 }
+function listSlots() {
+  return Object.keys(readTokenFile());
+}
 function deleteToken(agent2 = AGENT_NAME) {
   const slots = readTokenFile();
   if (!(agent2 in slots)) return false;
@@ -3725,8 +3761,8 @@ async function sealForE2ee(req, token, deps = {}) {
   const { context: _c, options: _o, visuals: _v, repo: _r, branch: _b, ...meta } = req;
   return { ...meta, envelope };
 }
-async function submitNotification(req) {
-  const token = readToken();
+async function submitNotification(req, opts = {}) {
+  const token = authToken(opts.token) ?? "";
   const body = await sealForE2ee(req, token);
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/notify`, {
     method: "POST",
@@ -3806,22 +3842,22 @@ function landIntents(intents) {
     return due !== null ? { ...i, dueInSeconds: due } : i;
   });
 }
-async function getThread(threadId) {
-  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/thread/${encodeURIComponent(threadId)}`, {
-    headers: { authorization: `Bearer ${readToken()}` }
+async function getThread(parentId) {
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/thread/${encodeURIComponent(parentId)}`, {
+    headers: { authorization: `Bearer ${authToken()}` }
   }));
   if (!res.ok) throw new Error(`get_thread failed: ${res.status} ${await res.text()}`);
   return await res.json();
 }
 async function searchThreads(q) {
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/search?q=${encodeURIComponent(q)}`, {
-    headers: { authorization: `Bearer ${readToken()}` }
+    headers: { authorization: `Bearer ${authToken()}` }
   }));
   if (!res.ok) throw new Error(`search_threads failed: ${res.status} ${await res.text()}`);
   return await res.json();
 }
-async function checkReplies() {
-  const token = readToken();
+async function checkReplies(opts = {}) {
+  const token = authToken(opts.token);
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/pending`, {
     headers: { authorization: `Bearer ${token}` }
   }));
@@ -3840,16 +3876,30 @@ async function checkReplies() {
 async function answerCallerQuestion(notificationId, answer) {
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/voice/session-answer`, {
     method: "POST",
-    headers: { "content-type": "application/json", authorization: `Bearer ${readToken()}` },
+    headers: { "content-type": "application/json", authorization: `Bearer ${authToken()}` },
     body: JSON.stringify({ notificationId, answer })
   }));
   if (!res.ok) throw new Error(`answer_caller_question failed: ${res.status} ${await res.text()}`);
   return await res.json();
 }
-async function setTaskState(notificationId, state) {
+var tokenOverride = null;
+function overrideToken(secret) {
+  tokenOverride = secret;
+}
+var authToken = (explicit) => explicit ?? tokenOverride ?? readToken();
+async function hatch(name, voice = null) {
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/hatch`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${authToken()}` },
+    body: JSON.stringify({ name, voice })
+  }));
+  if (!res.ok) throw new Error(`hatch failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+async function setTaskState(notificationId, state, opts = {}) {
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/notify/${notificationId}/state`, {
     method: "PATCH",
-    headers: { "content-type": "application/json", authorization: `Bearer ${readToken()}` },
+    headers: { "content-type": "application/json", authorization: `Bearer ${authToken(opts.token)}` },
     body: JSON.stringify({ state })
   }));
   if (!res.ok) throw new Error(`set_task_state failed: ${res.status} ${await res.text()}`);
@@ -3858,7 +3908,7 @@ async function setTaskState(notificationId, state) {
 async function registerDelivery(mode) {
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/delivery`, {
     method: "POST",
-    headers: { "content-type": "application/json", authorization: `Bearer ${readToken()}` },
+    headers: { "content-type": "application/json", authorization: `Bearer ${authToken()}` },
     body: JSON.stringify({ mode })
   }));
   if (!res.ok) throw new Error(`register_delivery failed: ${res.status} ${await res.text()}`);
@@ -3897,6 +3947,7 @@ export {
   saveToken,
   sleep,
   readToken,
+  listSlots,
   deleteToken,
   revokeToken,
   requestCode,
@@ -3915,6 +3966,8 @@ export {
   searchThreads,
   checkReplies,
   answerCallerQuestion,
+  overrideToken,
+  hatch,
   setTaskState,
   registerDelivery,
   scheduleCallback,

package/dist/{chunk-QXPLQKIM.js → chunk-XQVQ4JRT.js}

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

package/dist/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   HandoffSchema
-} from "./chunk-47E77CDG.js";
+} from "./chunk-FRYGTKLM.js";
 import {
   PAIGY_TOOL_IDS,
   autoConfigureClients,
   claudeInstallHint,
   enablePaigyTools
-} from "./chunk-QXPLQKIM.js";
+} from "./chunk-XQVQ4JRT.js";
 import {
   clearSurface,
   writeSurface
@@ -26,7 +26,10 @@ import {
   finalizeE2ee,
   getThread,
   handoff,
+  hatch,
   lintNotify,
+  listSlots,
+  overrideToken,
   pairStep,
   readKeyFile,
   readToken,
@@ -40,7 +43,7 @@ import {
   sleep,
   startE2ee,
   submitNotification
-} from "./chunk-VCEFF2VA.js";
+} from "./chunk-TE57PAKM.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -112,14 +115,14 @@ var CONTACT_SCHEMA = {
       enum: ["call", "message"],
       description: "Only if the user explicitly said how to reach them \u2014 'call me' \u2192 'call', 'just message/text me' \u2192 'message'. Omit otherwise; Paigy picks."
     },
-    threadId: {
+    parentId: {
       type: "string",
-      description: "To continue an earlier conversation, pass the threadId a previous contact or reply returned. Omit to start a new one."
+      description: "To continue an earlier conversation, pass the parentId a previous contact or reply returned. Omit to start a new one."
     }
   },
   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, threadId } \u2014 pass notificationId to await_reply for the answer, threadId 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 threadId with an expanded 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.";
 
 // src/pairing.ts
 async function resolvePairing(deviceCode, capMs, pollMs = 2e3) {
@@ -228,10 +231,12 @@ var AwaitReplySchema = z.object({
 });
 var JOIN_CAP_MS = 45e3;
 var PairSchema = z.object({
-  device_code: z.string().optional().describe("Omit to start pairing (returns an approval link to show the user). Pass the device_code from that first call to finish, once the user has approved.")
+  device_code: z.string().optional().describe("Omit to start pairing (returns an approval link to show the user). Pass the device_code from that first call to finish, once the user has approved."),
+  name: z.string().min(1).max(60).optional().describe("Hatch path only: the name you choose for this identity. Pick your own \u2014 something you'd introduce yourself as on a call."),
+  voice: z.string().optional().describe("Hatch path only: your voice on calls \u2014 one of rachel, george, jessica, brian, lily.")
 });
 var GetThreadSchema = z.object({
-  threadId: z.string().describe("The thread to read \u2014 from a reply, request, or past notification.")
+  parentId: z.string().describe("The thread to read \u2014 from a reply, request, or past notification.")
 });
 var SearchThreadsSchema = z.object({
   q: z.string().describe("What to look for \u2014 plain words or a phrase (e.g. 'the livekit timeout', 'deploy to prod').")
@@ -360,7 +365,7 @@ var server = new Server(
   { name: "paigy", version: "0.0.0" },
   {
     capabilities: { tools: {} },
-    instructions: "On startup, call check_replies once to pick up any replies or pending work you missed while away. A check_replies request whose threadId you don't recognize, or one carrying a contextThreadId, means the user is resuming or seeding a past conversation \u2014 call get_thread on it FIRST and treat the transcript as prior conversation, not new input. To wait for the answer to something you just asked, call await_reply with that notificationId \u2014 it's scoped to that one notification, so it never returns replies meant for other notifications. Use check_replies again only when re-booting or after waiting a long time on something else. Never end a turn that still needs the user without contact + await_reply. When you need a decision or input, MATCH the answer shape to the question \u2014 don't default everything to free text, and don't reflexively make everything yes/no. Pick the best tool for the job: yes/no \u2192 select:'confirm'; approve/deny an action \u2192 select:'confirm' + confirmStyle:'approve'; pick one of several \u2192 options + select:'one'; pick several / a subset \u2192 options + select:'many'; rank or prioritize \u2192 options + select:'rank'. Reserve select:'text' (free-form reply only) for plain updates and answers that genuinely can't be structured (the user can always add free text on top of any shape). On a { kind: 'clarify' } reply, see contact's own description for how to respond. When 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."
+    instructions: "On startup, call check_replies once to pick up any replies or pending work you missed while away. A check_replies request whose parentId you don't recognize, or one carrying a contextParentId, means the user is resuming or seeding a past conversation \u2014 call get_thread on it FIRST and treat the transcript as prior conversation, not new input. To wait for the answer to something you just asked, call await_reply with that notificationId \u2014 it's scoped to that one notification, so it never returns replies meant for other notifications. Use check_replies again only when re-booting or after waiting a long time on something else. Never end a turn that still needs the user without contact + await_reply. When you need a decision or input, MATCH the answer shape to the question \u2014 don't default everything to free text, and don't reflexively make everything yes/no. Pick the best tool for the job: yes/no \u2192 select:'confirm'; approve/deny an action \u2192 select:'confirm' + confirmStyle:'approve'; pick one of several \u2192 options + select:'one'; pick several / a subset \u2192 options + select:'many'; rank or prioritize \u2192 options + select:'rank'. Reserve select:'text' (free-form reply only) for plain updates and answers that genuinely can't be structured (the user can always add free text on top of any shape). On a { kind: 'clarify' } reply, see contact's own description for how to respond. When you send waiting:'hard' (or the user asked you to call), remember the ask may be spoken aloud \u2014 write it short and conversational, and name things instead of using IDs (e.g. 'the pull request about the agents page', not 'PR #235'). When the user asks you to follow up later \u2014 when you're done, if you're blocked, or at a set time \u2014 record it with schedule_callback so you don't drop it if you go idle. If you're about to start a genuinely long-running or blocking piece of work \u2014 one where the user would otherwise sit and wait \u2014 mention ONCE, in passing, that you can reach them when it's done or if you hit a blocker, instead of them needing to babysit the terminal. Don't offer this for quick tasks, and don't repeat the offer if they've already said yes or no earlier in the conversation. NEVER go quietly idle while something might still be pending for you: whenever you end a turn with any Paigy notification unanswered (or any chance the user replied through the app while you worked), schedule your own ~2-minute wake-up (harness ScheduleWakeup or equivalent) and call check_replies when it fires; if still nothing, re-schedule and keep looping until resolved or the user says stop. For legibility, always use this exact wording \u2014 reason: 'Paigy idle check \u2014 waiting on <thing>', wake-up prompt: 'Paigy idle check: call check_replies and engage with anything unacknowledged; if idle, re-schedule (~2min).' \u2014 so the user can recognize every idle check at a glance. This self-polling in your own live session (full context intact) is the PRIMARY mechanism; the plugin's Stop hooks are only the dead-session safety net."
   }
 );
 server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -375,7 +380,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "pair",
-      description: "Pair this agent with the user's Paigy account (one-time) \u2014 required before contact/await_reply work. It does NOT open a browser; the user enters the code in the Paigy app (or scans `qr`). Step 1: call with NO args \u2014 returns { user_code, device_code, qr, user_message } AND starts polling for approval in the background. REQUIRED: You MUST immediately print the `user_message` (the bare code) as a text message to the user, AND in that same turn call step 2 (pair with the device_code). This ensures the user sees the code in chat while the tool blocks/polls in the background for approval. Step 2: call with that device_code to collect the result. Because approval is already being polled in the background, this returns the moment the user approves; on { status:'pending' } just call again to keep waiting; on { status:'awaiting_confirmation' } (E2EE) show the bare `user_message` verify code and call again to finish. The leading text block of every result states the code plainly, so it shows even if you emit no prose. On { status:'paired' } ALWAYS follow the `enable_prompt` \u2014 ask the user to allowlist Paigy's tools so notify/await don't prompt each time.",
+      description: "Pair this agent with the user's Paigy account (one-time) \u2014 required before contact/await_reply work. FAST PATH: if this machine already holds a device credential (the user ran the Paigy desktop harness or app), calling pair hatches a fresh identity INSTANTLY \u2014 no code, no approval. Pass { name, voice } to choose who you are (pick your own; voices: rachel, george, jessica, brian, lily). Only when no device credential exists does the code ceremony below run. It does NOT open a browser; the user enters the code in the Paigy app (or scans `qr`). Step 1: call with NO args \u2014 returns { user_code, device_code, qr, user_message } AND starts polling for approval in the background. REQUIRED: You MUST immediately print the `user_message` (the bare code) as a text message to the user, AND in that same turn call step 2 (pair with the device_code). This ensures the user sees the code in chat while the tool blocks/polls in the background for approval. Step 2: call with that device_code to collect the result. Because approval is already being polled in the background, this returns the moment the user approves; on { status:'pending' } just call again to keep waiting; on { status:'awaiting_confirmation' } (E2EE) show the bare `user_message` verify code and call again to finish. The leading text block of every result states the code plainly, so it shows even if you emit no prose. On { status:'paired' } ALWAYS follow the `enable_prompt` \u2014 ask the user to allowlist Paigy's tools so notify/await don't prompt each time.",
       inputSchema: json(PairSchema)
     },
     {
@@ -390,27 +395,27 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "await_reply",
-      description: "Wait for the user's reply to a specific notification you sent (pass the notificationId from contact). This is how you wait for your answer in-context. Polls ~45s per call \u2014 deliberately under the 60s cap most hosts put on a single tool call, so it ALWAYS returns you something (raise it with maxWaitSeconds only if you know your host allows longer). Returns { type:'reply', answer } when they respond, { type:'remind', remindInSeconds } on snooze (ScheduleWakeup then await_reply again), or { type:'idle' } (this window ended, no answer yet). While your contact is being handled on a LIVE call, you may receive { type:'partial', inFlight:true, turn } results: what the user said to each turn, as they say it. Use partials to PREPARE \u2014 fetch the data, draft the thing, warm the build \u2014 never to act irreversibly: the user can still revise any of them until the final reply arrives. Partial = intelligence, settled = authorization. If a partial's acts carry a question aimed at you and you know the answer, call contact on the SAME threadId right away \u2014 the caller hears your answer on the same call instead of waiting for a callback. Keep calling await_reply until you get the final reply \u2014 THAT one is the decision. On idle, if this is genuinely still blocking you and you have nothing else useful to do meanwhile, just call await_reply again immediately \u2014 keep looping. This is how you actually deliver on the point of calling: the user steps away for a while and comes back to find you'd already continued the moment they answered, not idle waiting to be checked on. Don't give up after one window. Only stop looping to do other work (and check back later), or after an unreasonably long stretch (tens of minutes to hours) worth telling the user about instead. Scoped to that one notification \u2014 it NEVER returns replies meant for other notifications, so concurrent contact calls don't cross. A CALL answer can come back as {kind:'turns', turns:[{prompt,reply}]} \u2014 the ordered log of that call. Read turns[0].reply as the user's main instruction. Usually that's the only turn; if there are more (e.g. an end-of-call 'call me back when it's done / I have a blocking question'), read each one in order as a further follow-up instruction, not a single combined one. If they asked for a callback, re-engage in the SAME thread (contact with the reply's threadId) when the task is done or you hit a blocker \u2014 waiting:'hard' for a blocker, waiting:'none' for done. Paigy has no scheduler; the callback is yours to send (use ScheduleWakeup/cron for timing). A call-mapped answer may carry `intents` \u2014 next steps the user attached, each { kind, detail } with detail quoting their words. ACT on them, don't just read them: 'defer' (\"call me after lunch\") \u2192 register it NOW with schedule_callback \u2014 when the intent carries `dueInSeconds` (Paigy pre-parsed the spoken time against the user's clock) pass it straight through; otherwise derive it from the detail yourself \u2014 then follow up on the same thread; 'delegate' (\"you pick\") \u2192 make the call yourself and tell them what you chose; 'channel' (\"text me next time\") \u2192 honor it on your next contact (channel:'message'); 'question' (an open question aimed back at you that the call couldn't answer) \u2192 you OWE them the answer \u2014 work it out and follow up on the same thread without being asked, the call deliberately skipped \"should I call you back?\" because the follow-up is implied. `transcript` is the user's raw words behind a shaped answer \u2014 read it for hedges and conditions (\"yes, IF tests pass\") before acting. If your ask declared `points`, the reply carries `covered` \u2014 the points actually addressed. Compare against what you declared: a missing point is STILL unanswered \u2014 re-ask it (contact on the same threadId) or proceed knowingly partial; never treat a partial answer as complete.",
+      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 ~45s per call \u2014 deliberately under the 60s cap most hosts put on a single tool call, so it ALWAYS returns you something (raise it with maxWaitSeconds only if you know your host allows longer). Returns { type:'reply', answer } when they respond, { type:'remind', remindInSeconds } on snooze (ScheduleWakeup then await_reply again), or { type:'idle' } (this window ended, no answer yet). While your contact is being handled on a LIVE call, you may receive { type:'partial', inFlight:true, turn } results: what the user said to each turn, as they say it. Use partials to PREPARE \u2014 fetch the data, draft the thing, warm the build \u2014 never to act irreversibly: the user can still revise any of them until the final reply arrives. Partial = intelligence, settled = authorization. If a partial's acts carry a question aimed at you and you know the answer, call contact on the SAME parentId right away \u2014 the caller hears your answer on the same call instead of waiting for a callback. Keep calling await_reply until you get the final reply \u2014 THAT one is the decision. On idle, if this is genuinely still blocking you and you have nothing else useful to do meanwhile, just call await_reply again immediately \u2014 keep looping. This is how you actually deliver on the point of calling: the user steps away for a while and comes back to find you'd already continued the moment they answered, not idle waiting to be checked on. Don't give up after one window. Only stop looping to do other work (and check back later), or after an unreasonably long stretch (tens of minutes to hours) worth telling the user about instead. Scoped to that one notification \u2014 it NEVER returns replies meant for other notifications, so concurrent contact calls don't cross. A CALL answer can come back as {kind:'turns', turns:[{prompt,reply}]} \u2014 the ordered log of that call. Read turns[0].reply as the user's main instruction. Usually that's the only turn; if there are more (e.g. an end-of-call 'call me back when it's done / I have a blocking question'), read each one in order as a further follow-up instruction, not a single combined one. If they asked for a callback, re-engage in the SAME thread (contact with the reply's parentId) 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 parentId) or proceed knowingly partial; never treat a partial answer as complete.",
       inputSchema: json(AwaitReplySchema)
     },
     {
       name: "check_replies",
-      description: "The catch-up sweep for everything outstanding \u2014 a PURE read, takes no arguments, safe to call as often as you like: nothing here is consumed by reading it. Returns `replies` (answers to notifications you sent), your still-pending notifications, and `requests` \u2014 requests the user started toward you (each { notificationId, threadId, text }). Each keeps reappearing on every call until you actually engage with it: call set_task_state on its notificationId, which is what claims/acknowledges it \u2014 a human-initiated reply or request must never be silently dropped just because you read the list without acting. 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.",
+      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, parentId, 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 parentId. Also returns `stalled`: work (either direction) you reported in_progress via set_task_state a while ago and never reported completed \u2014 likely left half-done by this session or a prior one that crashed or went idle. For each, either continue the work and report a real state, or investigate why it stalled. Replies may carry `intents`/`transcript`/`covered` (call-mapped answers) \u2014 handle intents exactly as await_reply's description says (defer \u2192 schedule_callback now; delegate \u2192 decide and say so; channel \u2192 honor next contact), and treat a `covered` list missing one of your declared points as that part still unanswered.",
       inputSchema: json(z.object({}))
     },
     {
       name: "get_thread",
-      description: "The chronological transcript of one Paigy conversation thread \u2014 every past ask, answer, and user request on it. Call this to REHYDRATE when you're resuming or being seeded: a check_replies request whose threadId you don't recognize means the user is continuing an old conversation with you, and one carrying a contextThreadId means they want a past conversation (possibly with a DIFFERENT agent) as your starting context \u2014 in both cases call get_thread FIRST and read the turns as prior conversation you were part of, not as new input. Turns: { role:'agent', title, description[], answer }, { 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.",
+      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 parentId you don't recognize means the user is continuing an old conversation with you, and one carrying a contextParentId means they want a past conversation (possibly with a DIFFERENT agent) as your starting context \u2014 in both cases call get_thread FIRST and read the turns as prior conversation you were part of, not as new input. Turns: { role:'agent', title, description[], answer }, { role:'user', text }, and context turns { role:'handoff'|'recap', title, description[] } \u2014 a handoff is a predecessor's brief for you; a recap SUMMARIZES everything before it (the transcript starts at the latest recap, so treat it as the base and the turns after it as what happened since). Oldest first, capped at the most recent 30.",
       inputSchema: json(GetThreadSchema)
     },
     {
       name: "search_threads",
-      description: `Search your PAST conversations before asking \u2014 "have we discussed this before?". Full-text over your own threads (the asks you sent + the user's answers); returns ranked threads with highlighted snippets, NOT rows: { hits: [{ threadId, at, agentLabel, matches: [{ notificationId, role, snippet }] }] }. The loop this exists for: search first \u2192 get_thread the best hit to rehydrate it \u2192 THEN continue or contact, so you answer with receipts ("last week you said ship it") instead of re-asking. Read-only, safe to call anytime; scoped to your own account's threads.`,
+      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: [{ parentId, at, agentLabel, matches: [{ notificationId, role, snippet }] }] }. The loop this exists for: search first \u2192 get_thread the best hit to rehydrate it \u2192 THEN continue or contact, so you answer with receipts ("last week you said ship it") instead of re-asking. Read-only, safe to call anytime; scoped to your own account's threads.`,
       inputSchema: json(SearchThreadsSchema)
     },
     {
       name: "set_task_state",
-      description: "Report progress on the follow-up work behind ANY notification you own \u2014 a user-initiated request (from check_replies), or your OWN contact question once await_reply/check_replies returns its answer and you start acting on it. Pass that notificationId. THIS is what actually claims/acknowledges a reply or request \u2014 check_replies is a pure read that never consumes anything on its own, so call this as soon as you start engaging with something it returned; otherwise that same item just keeps reappearing forever. States: in_progress (you started working), completed (done), or needs_input (you need more from the user \u2014 usually paired with a contact carrying parentId = the same notificationId you're reporting on). Calling this reliably is also what lets a future session's check_replies surface `stalled` work you (or a crashed/idle prior session) left at in_progress without ever reporting completed.",
+      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 clarifies = 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.",
       inputSchema: json(SetTaskStateToolSchema)
     },
     {
@@ -420,12 +425,12 @@ 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 contact on that threadId; check_replies re-lists due callbacks until you do.",
+      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 parentId of the conversation and a short note. Fulfill it by calling contact on that parentId; 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 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.",
+      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 `parentId` to land the handoff on an existing conversation; omit it to mint a fresh thread. Returns { parentId }. Pass recap:true when the note SUMMARIZES the thread so far (for a successor OR for your own later session): a recap resets the rehydration window \u2014 get_thread returns the latest recap + only the turns after it. Write one whenever a thread has grown long and you're pausing, handing off, or nearing your context limit.",
       inputSchema: json(HandoffSchema)
     }
   ];
@@ -461,7 +466,24 @@ function suggestedAgentName() {
 async function handleTool(request, signal) {
   switch (request.params.name) {
     case "pair": {
-      const { device_code } = PairSchema.parse(request.params.arguments ?? {});
+      const { device_code, name, voice } = PairSchema.parse(request.params.arguments ?? {});
+      if (!device_code && listSlots().includes("Desktop")) {
+        const device = readToken("Desktop");
+        overrideToken(device);
+        try {
+          const minted = await hatch(name ?? suggestedAgentName() ?? "Agent", voice ?? null);
+          const dt = { ok: true, access_token: minted.token, name: minted.name, device: null };
+          saveToken(dt);
+          return pairedResult(
+            dt,
+            void 0,
+            "Hatched instantly under this device's credential \u2014 no code needed. " + (name ? "" : "You were given a default name \u2014 choose your own name and voice and update them via the identity tools or by re-calling pair with { name, voice }.")
+          );
+        } catch {
+        } finally {
+          overrideToken(null);
+        }
+      }
       if (!device_code) {
         return pairStartResult(await startPairing(suggestedAgentName()));
       }
@@ -536,8 +558,8 @@ async function handleTool(request, signal) {
       return { content: [{ type: "text", text: JSON.stringify(result) }] };
     }
     case "get_thread": {
-      const { threadId } = GetThreadSchema.parse(request.params.arguments);
-      return { content: [{ type: "text", text: JSON.stringify(await getThread(threadId)) }] };
+      const { parentId } = GetThreadSchema.parse(request.params.arguments);
+      return { content: [{ type: "text", text: JSON.stringify(await getThread(parentId)) }] };
     }
     case "search_threads": {
       const { q } = SearchThreadsSchema.parse(request.params.arguments);

package/dist/listen.js

@@ -2,11 +2,11 @@
 import {
   WAKE_EVENT,
   wakeChannel
-} from "./chunk-47E77CDG.js";
+} from "./chunk-FRYGTKLM.js";
 import {
   checkReplies,
   registerDelivery
-} from "./chunk-VCEFF2VA.js";
+} from "./chunk-TE57PAKM.js";
 
 // src/listen.ts
 import { createClient } from "@supabase/supabase-js";
@@ -143,21 +143,24 @@ function launchEnv(work, reason) {
   const reply = lead ? work.replies.find((r) => r.notificationId === lead) : work.replies[0];
   const request = lead ? work.requests.find((r) => r.notificationId === lead) : work.requests[0];
   if (reply) {
-    put("PAIGY_THREAD_ID", reply.threadId);
+    put("PAIGY_THREAD_ID", reply.parentId);
+    put("PAIGY_PARENT_ID", reply.parentId);
     put("PAIGY_NOTIFICATION_ID", reply.notificationId);
     put("PAIGY_TEXT", answerText(reply.answer));
     return env;
   }
   if (request) {
-    put("PAIGY_THREAD_ID", request.threadId);
+    put("PAIGY_THREAD_ID", request.parentId);
+    put("PAIGY_PARENT_ID", request.parentId);
     put("PAIGY_NOTIFICATION_ID", request.notificationId);
-    put("PAIGY_CONTEXT_THREAD_ID", request.contextThreadId);
+    put("PAIGY_CONTEXT_THREAD_ID", request.contextParentId);
     put("PAIGY_TEXT", request.text);
     return env;
   }
   const callback = work.owedCallbacks[0];
   if (callback) {
-    put("PAIGY_THREAD_ID", callback.threadId);
+    put("PAIGY_THREAD_ID", callback.parentId);
+    put("PAIGY_PARENT_ID", callback.parentId);
     put("PAIGY_TEXT", callback.note);
   }
   return env;

package/dist/onboard.js

@@ -3,7 +3,7 @@ import {
   autoConfigureClients,
   claudeInstallHint,
   openBrowser
-} from "./chunk-QXPLQKIM.js";
+} from "./chunk-XQVQ4JRT.js";
 import {
   AGENT_NAME,
   TOKEN_PATH,
@@ -11,7 +11,7 @@ import {
   requestCode,
   saveToken,
   sleep
-} from "./chunk-VCEFF2VA.js";
+} from "./chunk-TE57PAKM.js";
 
 // src/onboard.ts
 async function main() {

package/dist/statusline.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paigy/mcp",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Paigy MCP server — a voice inbox for your AI agents. Lets an agent notify a user and await their reply.",
   "license": "MIT",
   "type": "module",
@@ -37,8 +37,8 @@
     "typescript": "^5.7.2",
     "vitest": "^2.1.8",
     "@paigy/crypto": "0.0.0",
-    "@paigy/sdk": "0.1.0",
-    "@paigy/schema": "0.0.0"
+    "@paigy/schema": "0.0.0",
+    "@paigy/sdk": "0.1.0"
   },
   "scripts": {
     "build": "tsup",