@paigy/mcp 0.6.0 → 0.7.0

package/dist/chunk-4MRCUW5I.js

@@ -0,0 +1,362 @@
+// ../../packages/schema/dist/index.js
+import { z } from "zod";
+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 OptionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  // .describe() flows into the MCP notify_user JSON schema (zodToJsonSchema), so
+  // the constraints below are what an agent reads when deciding to use these.
+  html: z.string().max(16384).describe(
+    "Optional sandboxed HTML/CSS preview for a visual 'pick one' (shown in the option card). Untrusted-sandboxed: NO JavaScript, NO external network or images \u2014 inline CSS and data: URIs only; <=16KB. Use for layout/CSS mockups, tables, diffs. For a hosted image use `image` instead."
+  ).optional(),
+  image: z.string().url().describe(
+    "Optional image URL rendered as the option's preview (plain image, not sandboxed). For agent-generated HTML/CSS mockups, use `html` instead."
+  ).optional()
+});
+var VisualSchema = z.object({
+  url: z.string().url(),
+  label: z.string().optional()
+});
+var AgentSchema = z.object({
+  name: z.string()
+});
+var NotifyLevelSchema = z.enum(["inbox", "push", "banner", "call"]);
+var NotifyRequestSchema = z.object({
+  context: ContextSchema,
+  options: z.array(OptionSchema).optional(),
+  visuals: z.array(VisualSchema).optional(),
+  agent: AgentSchema,
+  /** Git repo the agent is working in ("owner/name"), when applicable. */
+  repo: z.string().optional(),
+  /** Git branch the agent is on, when applicable. */
+  branch: z.string().optional(),
+  /** Continue an existing conversation; omitted = start a new thread. */
+  threadId: z.string().uuid().optional(),
+  createdAt: z.string().datetime(),
+  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(),
+  /** How the user answers the options: pick one (default), pick several, pick & order, or yes/no confirm. */
+  select: z.enum(["one", "many", "rank", "confirm"]).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'."
+  )
+});
+var NotifyStatusSchema = z.enum(["pending", "answered", "ignored"]);
+var AgentStateSchema = z.enum(["idle", "in_progress", "completed", "needs_input"]);
+var SetTaskStateSchema = z.object({
+  state: z.enum(["in_progress", "completed", "needs_input"])
+});
+var TurnSchema = z.object({
+  prompt: z.string(),
+  reply: z.string()
+});
+var UserAnswerSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("option"), optionId: z.string() }),
+  z.object({ kind: z.literal("text"), text: z.string() }),
+  z.object({ kind: z.literal("ignored") }),
+  z.object({ kind: z.literal("multi"), optionIds: z.array(z.string()) }),
+  z.object({ kind: z.literal("ranked"), optionIds: z.array(z.string()) }),
+  z.object({ kind: z.literal("clarify"), chunks: z.array(z.string()).min(1) }),
+  z.object({ kind: z.literal("confirm"), approved: z.boolean() }),
+  z.object({ kind: z.literal("turns"), turns: z.array(TurnSchema).min(1) })
+]);
+var AwaitItemSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("reply"),
+    threadId: z.string(),
+    notificationId: z.string(),
+    answer: UserAnswerSchema
+  }),
+  z.object({
+    type: z.literal("remind"),
+    threadId: z.string(),
+    notificationId: z.string(),
+    remindAt: z.string().datetime({ offset: true }),
+    /** Seconds until remindAt, server-computed — pass straight to ScheduleWakeup. */
+    remindInSeconds: z.number()
+  }),
+  z.object({ type: z.literal("idle") })
+]);
+var CallbackTriggerSchema = z.enum(["on_done", "on_blocked", "scheduled"]);
+var ScheduleCallbackSchema = z.object({
+  threadId: z.string().describe("The thread to call back on (from a prior notify_user / reply / request)."),
+  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.")
+});
+var PendingRepliesSchema = z.object({
+  replies: z.array(
+    z.object({ threadId: z.string(), notificationId: z.string(), answer: UserAnswerSchema })
+  ),
+  pending: z.array(
+    z.object({ threadId: z.string(), notificationId: z.string(), createdAt: z.string() })
+  ),
+  /** User-initiated requests addressed to this agent; act on them and reply via
+   *  notify_user on the same threadId. Each is returned once (claimed on read). */
+  requests: z.array(
+    z.object({ threadId: z.string(), notificationId: z.string(), text: z.string(), createdAt: z.string() })
+  ),
+  /** Callbacks you owe the user that are now DUE (you said you'd follow up when done,
+   *  if blocked, or at a time that has passed). Re-surfaced every sweep until you
+   *  fulfill one by calling notify_user on its threadId. */
+  owedCallbacks: z.array(
+    z.object({ threadId: z.string(), trigger: CallbackTriggerSchema, note: z.string() })
+  )
+});
+var NotifyResponseSchema = z.object({
+  id: z.string(),
+  status: NotifyStatusSchema,
+  createdAt: z.string().datetime(),
+  answer: UserAnswerSchema.optional(),
+  answeredAt: z.string().datetime().optional()
+});
+var UserResponseSchema = z.object({
+  requestId: z.string(),
+  answer: UserAnswerSchema,
+  answeredAt: z.string().datetime()
+});
+var InboxItemSchema = z.object({
+  id: z.string(),
+  status: NotifyStatusSchema,
+  context: ContextSchema,
+  options: z.array(OptionSchema).optional(),
+  visuals: z.array(VisualSchema).optional(),
+  agent: z.string(),
+  nickname: z.string(),
+  repo: z.string().optional(),
+  branch: z.string().optional(),
+  createdAt: z.string().datetime(),
+  snoozedUntil: z.string().datetime().optional(),
+  agentState: AgentStateSchema.default("idle"),
+  parentId: z.string().optional(),
+  select: z.enum(["one", "many", "rank", "confirm"]).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'."
+  ),
+  /** The user's locked-in answer; present only for replied items (GET /api/replied/:id). */
+  answer: UserAnswerSchema.optional()
+});
+var SnoozeRequestSchema = z.object({
+  requestId: z.string(),
+  until: z.string().datetime()
+});
+var PushTokenSchema = z.object({
+  voipToken: z.string().min(1).optional(),
+  alertToken: z.string().min(1).optional(),
+  platform: z.literal("ios")
+});
+var UserSettingsSchema = z.object({
+  permissions: z.object({
+    call: z.boolean(),
+    banner: z.boolean(),
+    push: z.boolean()
+  }),
+  sessionMode: z.enum(["default", "all_calls", "silent"]),
+  silentPush: z.boolean(),
+  autoCallback: z.boolean()
+});
+var HistoryItemSchema = z.object({
+  id: z.string(),
+  threadId: z.string(),
+  /** 'user' = a request you sent; 'agent' = a notification an agent sent you. */
+  initiator: z.enum(["user", "agent"]),
+  title: z.string(),
+  /** The agent on the other end (nickname). */
+  agent: z.string(),
+  createdAt: z.string(),
+  /** When the agent fetched your request (user→agent only). */
+  agentAckedAt: z.string().nullable(),
+  /** When you answered the agent's notification (agent→user only). */
+  humanAckedAt: z.string().nullable()
+});
+var ConnectionSummarySchema = z.object({
+  /** The connection = the agent's token id (used to address a request). */
+  id: z.string(),
+  agent: z.string(),
+  device: z.string().nullable(),
+  nickname: z.string(),
+  createdAt: z.string().datetime()
+});
+var CreateRequestSchema = z.object({
+  /** The connection (token id) to send to, from GET /api/tokens. */
+  tokenId: z.string(),
+  /** The user's message to the agent. */
+  text: z.string().min(1)
+});
+var DeliveryModeSchema = z.enum(["poll", "self_hosted"]);
+var WAKE_EVENT = "wake";
+var wakeChannel = (tokenId) => `wake:${tokenId}`;
+var RegisterDeliverySchema = z.object({ mode: DeliveryModeSchema });
+var OAuthStartSchema = z.object({
+  provider: z.enum(["cma"]),
+  returnTo: z.string().min(1)
+});
+var SetProviderSchema = z.object({
+  provider: z.enum(["cma"]),
+  /** Provider-side agent id (e.g. CMA `agent_…`). */
+  agentRef: z.string().min(1),
+  /** Provider-side environment id (e.g. CMA `env_…`). */
+  environmentId: z.string().min(1),
+  /** The delegated API key Paigy holds (in Vault) to spawn sessions on the user's behalf. */
+  apiKey: z.string().min(1)
+});
+var DeliveryConfigSchema = z.object({
+  tokenId: z.string(),
+  mode: DeliveryModeSchema,
+  /** null when the server has no SUPABASE_ANON_KEY set — the listener then falls
+   *  back to its own PAIGY_SUPABASE_URL / PAIGY_SUPABASE_ANON_KEY env. */
+  realtime: z.object({ url: z.string(), anonKey: z.string() }).nullable()
+});
+var WakeNudgeSchema = z.object({
+  kind: z.enum(["reply", "request", "callback"]),
+  notificationId: z.string().optional(),
+  threadId: z.string()
+});
+var DeviceAgentTokenSchema = z.object({
+  token: z.string(),
+  deviceId: z.string(),
+  agentName: z.string(),
+  /** User-chosen session label; defaults to `<agent> <device>`. */
+  nickname: z.string(),
+  createdAt: z.string().datetime()
+});
+var PairingStatusSchema = z.enum(["pending", "approved", "denied", "expired"]);
+var DeviceCodeSchema = z.object({
+  device_code: z.string(),
+  user_code: z.string(),
+  verification_uri: z.string().url(),
+  verification_uri_complete: z.string().url(),
+  interval: z.number(),
+  expires_in: z.number()
+});
+var DeviceInfoSchema = z.object({
+  code: z.string(),
+  agent: z.string(),
+  device: z.string().nullable(),
+  status: PairingStatusSchema
+});
+var DeviceTokenSchema = z.object({
+  access_token: z.string(),
+  nickname: z.string(),
+  agent: z.string(),
+  device: z.string().nullable()
+});
+
+// src/client.ts
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var BACKEND_URL = process.env.PAIGY_BACKEND_URL ?? "https://paigy.ai";
+var TOKEN_PATH = join(homedir(), ".paigy", "token.json");
+function loadToken() {
+  if (process.env.PAIGY_TOKEN) return process.env.PAIGY_TOKEN;
+  if (existsSync(TOKEN_PATH)) {
+    try {
+      const raw = readFileSync(TOKEN_PATH, "utf8");
+      const parsed = JSON.parse(raw);
+      if (parsed.access_token) return parsed.access_token;
+    } catch {
+    }
+  }
+  return "";
+}
+var ONBOARD_MSG = "Not paired with Paigy yet \u2014 call the `pair` tool to connect this agent (it returns an approval link to show the user), then retry. Manual fallback: `npx -y @paigy/mcp paigy-mcp-onboard`.";
+function ensureAuthed(res) {
+  if (res.status === 401) throw new Error(ONBOARD_MSG);
+  return res;
+}
+async function submitNotification(req) {
+  const token = loadToken();
+  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/notify`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+    body: JSON.stringify(req)
+  }));
+  if (!res.ok) throw new Error(`notify failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function awaitReply(notificationId, opts = {}) {
+  const intervalMs = opts.intervalMs ?? 5e3;
+  const windowMs = opts.windowMs ?? 3e5;
+  const doSleep = opts.sleep ?? sleep;
+  const now = opts.now ?? Date.now;
+  const token = loadToken();
+  const start = now();
+  while (true) {
+    const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/await?notificationId=${encodeURIComponent(notificationId)}`, {
+      headers: { authorization: `Bearer ${token}` }
+    }));
+    if (!res.ok) throw new Error(`await failed: ${res.status} ${await res.text()}`);
+    const item = await res.json();
+    if (item.type !== "idle") return item;
+    if (now() - start >= windowMs) return { type: "idle" };
+    await doSleep(intervalMs);
+  }
+}
+async function checkReplies() {
+  const token = loadToken();
+  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/pending`, {
+    headers: { authorization: `Bearer ${token}` }
+  }));
+  if (!res.ok) throw new Error(`check_replies failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+async function setTaskState(id, state) {
+  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/notify/${id}/state`, {
+    method: "PATCH",
+    headers: { "content-type": "application/json", authorization: `Bearer ${loadToken()}` },
+    body: JSON.stringify({ state })
+  }));
+  if (!res.ok) throw new Error(`set_task_state failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+async function registerDelivery(mode) {
+  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/delivery`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${loadToken()}` },
+    body: JSON.stringify({ mode })
+  }));
+  if (!res.ok) throw new Error(`register_delivery failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+async function scheduleCallback(req) {
+  const token = loadToken();
+  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/callback`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+    body: JSON.stringify(req)
+  }));
+  if (!res.ok) throw new Error(`schedule_callback failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+async function pollAnswer(id) {
+  const token = loadToken();
+  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/poll/${id}`, {
+    headers: { authorization: `Bearer ${token}` }
+  }));
+  if (!res.ok) throw new Error(`poll failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+
+export {
+  NotifyRequestSchema,
+  SetTaskStateSchema,
+  ScheduleCallbackSchema,
+  DeliveryModeSchema,
+  WAKE_EVENT,
+  wakeChannel,
+  submitNotification,
+  awaitReply,
+  checkReplies,
+  setTaskState,
+  registerDelivery,
+  scheduleCallback,
+  pollAnswer
+};

package/dist/index.js

@@ -1,4 +1,17 @@
 #!/usr/bin/env node
+import {
+  DeliveryModeSchema,
+  NotifyRequestSchema,
+  ScheduleCallbackSchema,
+  SetTaskStateSchema,
+  awaitReply,
+  checkReplies,
+  pollAnswer,
+  registerDelivery,
+  scheduleCallback,
+  setTaskState,
+  submitNotification
+} from "./chunk-4MRCUW5I.js";
 import {
   deleteToken,
   openBrowser,
@@ -18,256 +31,27 @@ import {
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { execSync } from "child_process";
-
-// ../../packages/schema/dist/index.js
 import { z } from "zod";
-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 OptionSchema = z.object({
-  id: z.string(),
-  label: z.string(),
-  // .describe() flows into the MCP notify_user JSON schema (zodToJsonSchema), so
-  // the constraints below are what an agent reads when deciding to use these.
-  html: z.string().max(16384).describe(
-    "Optional sandboxed HTML/CSS preview for a visual 'pick one' (shown in the option card). Untrusted-sandboxed: NO JavaScript, NO external network or images \u2014 inline CSS and data: URIs only; <=16KB. Use for layout/CSS mockups, tables, diffs. For a hosted image use `image` instead."
-  ).optional(),
-  image: z.string().url().describe(
-    "Optional image URL rendered as the option's preview (plain image, not sandboxed). For agent-generated HTML/CSS mockups, use `html` instead."
-  ).optional()
-});
-var VisualSchema = z.object({
-  url: z.string().url(),
-  label: z.string().optional()
-});
-var AgentSchema = z.object({
-  name: z.string()
-});
-var NotifyRequestSchema = z.object({
-  context: ContextSchema,
-  options: z.array(OptionSchema).optional(),
-  visuals: z.array(VisualSchema).optional(),
-  agent: AgentSchema,
-  /** Git repo the agent is working in ("owner/name"), when applicable. */
-  repo: z.string().optional(),
-  /** Git branch the agent is on, when applicable. */
-  branch: z.string().optional(),
-  /** Continue an existing conversation; omitted = start a new thread. */
-  threadId: z.string().uuid().optional(),
-  createdAt: z.string().datetime(),
-  urgency: z.enum(["inbox", "call"]).default("inbox").describe(
-    "'inbox' (default) = sits silently in the inbox for the user to get to. '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 becomes what they see on the ring, so make it specific."
-  ),
-  /** The request this one was spawned from, for a clarification. */
-  parentId: z.string().optional(),
-  /** How the user answers the options: pick one (default), pick several, or pick & order. */
-  select: z.enum(["one", "many", "rank"]).default("one")
-});
-var NotifyStatusSchema = z.enum(["pending", "answered", "ignored"]);
-var AgentStateSchema = z.enum(["idle", "in_progress", "completed", "needs_input"]);
-var SetTaskStateSchema = z.object({
-  state: z.enum(["in_progress", "completed", "needs_input"])
-});
-var UserAnswerSchema = z.discriminatedUnion("kind", [
-  z.object({ kind: z.literal("option"), optionId: z.string() }),
-  z.object({ kind: z.literal("text"), text: z.string() }),
-  z.object({ kind: z.literal("ignored") }),
-  z.object({ kind: z.literal("multi"), optionIds: z.array(z.string()) }),
-  z.object({ kind: z.literal("ranked"), optionIds: z.array(z.string()) }),
-  z.object({ kind: z.literal("clarify"), chunks: z.array(z.string()).min(1) })
-]);
-var AwaitItemSchema = z.discriminatedUnion("type", [
-  z.object({
-    type: z.literal("reply"),
-    threadId: z.string(),
-    notificationId: z.string(),
-    answer: UserAnswerSchema
-  }),
-  z.object({
-    type: z.literal("remind"),
-    threadId: z.string(),
-    notificationId: z.string(),
-    remindAt: z.string().datetime({ offset: true }),
-    /** Seconds until remindAt, server-computed — pass straight to ScheduleWakeup. */
-    remindInSeconds: z.number()
-  }),
-  z.object({ type: z.literal("idle") })
-]);
-var PendingRepliesSchema = z.object({
-  replies: z.array(
-    z.object({ threadId: z.string(), notificationId: z.string(), answer: UserAnswerSchema })
-  ),
-  pending: z.array(
-    z.object({ threadId: z.string(), notificationId: z.string(), createdAt: z.string() })
-  )
-});
-var NotifyResponseSchema = z.object({
-  id: z.string(),
-  status: NotifyStatusSchema,
-  createdAt: z.string().datetime(),
-  answer: UserAnswerSchema.optional(),
-  answeredAt: z.string().datetime().optional()
-});
-var UserResponseSchema = z.object({
-  requestId: z.string(),
-  answer: UserAnswerSchema,
-  answeredAt: z.string().datetime()
-});
-var InboxItemSchema = z.object({
-  id: z.string(),
-  status: NotifyStatusSchema,
-  context: ContextSchema,
-  options: z.array(OptionSchema).optional(),
-  visuals: z.array(VisualSchema).optional(),
-  agent: z.string(),
-  nickname: z.string(),
-  repo: z.string().optional(),
-  branch: z.string().optional(),
-  createdAt: z.string().datetime(),
-  snoozedUntil: z.string().datetime().optional(),
-  agentState: AgentStateSchema.default("idle"),
-  parentId: z.string().optional(),
-  select: z.enum(["one", "many", "rank"]).default("one")
-});
-var SnoozeRequestSchema = z.object({
-  requestId: z.string(),
-  until: z.string().datetime()
-});
-var PushTokenSchema = z.object({
-  voipToken: z.string().min(1),
-  platform: z.enum(["ios"])
-});
-var UserSettingsSchema = z.object({
-  callsEnabled: z.boolean()
-});
-var DeviceAgentTokenSchema = z.object({
-  token: z.string(),
-  deviceId: z.string(),
-  agentName: z.string(),
-  /** User-chosen session label; defaults to `<agent> <device>`. */
-  nickname: z.string(),
-  createdAt: z.string().datetime()
-});
-var PairingStatusSchema = z.enum(["pending", "approved", "denied", "expired"]);
-var DeviceCodeSchema = z.object({
-  device_code: z.string(),
-  user_code: z.string(),
-  verification_uri: z.string().url(),
-  verification_uri_complete: z.string().url(),
-  interval: z.number(),
-  expires_in: z.number()
-});
-var DeviceInfoSchema = z.object({
-  code: z.string(),
-  agent: z.string(),
-  device: z.string().nullable(),
-  status: PairingStatusSchema
-});
-var DeviceTokenSchema = z.object({
-  access_token: z.string(),
-  nickname: z.string(),
-  agent: z.string(),
-  device: z.string().nullable()
-});
-
-// src/index.ts
-import { z as z2 } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
-
-// src/client.ts
-import { existsSync, readFileSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
-var BACKEND_URL = process.env.PAIGY_BACKEND_URL ?? "https://paigy.ai";
-var TOKEN_PATH = join(homedir(), ".paigy", "token.json");
-function loadToken() {
-  if (process.env.PAIGY_TOKEN) return process.env.PAIGY_TOKEN;
-  if (existsSync(TOKEN_PATH)) {
-    try {
-      const raw = readFileSync(TOKEN_PATH, "utf8");
-      const parsed = JSON.parse(raw);
-      if (parsed.access_token) return parsed.access_token;
-    } catch {
-    }
-  }
-  return "";
-}
-var ONBOARD_MSG = "Not paired with Paigy yet \u2014 call the `pair` tool to connect this agent (it returns an approval link to show the user), then retry. Manual fallback: `npx -y @paigy/mcp paigy-mcp-onboard`.";
-function ensureAuthed(res) {
-  if (res.status === 401) throw new Error(ONBOARD_MSG);
-  return res;
-}
-async function submitNotification(req) {
-  const token = loadToken();
-  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/notify`, {
-    method: "POST",
-    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
-    body: JSON.stringify(req)
-  }));
-  if (!res.ok) throw new Error(`notify failed: ${res.status} ${await res.text()}`);
-  return await res.json();
-}
-var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
-async function awaitReply(notificationId, opts = {}) {
-  const intervalMs = opts.intervalMs ?? 5e3;
-  const windowMs = opts.windowMs ?? 3e5;
-  const doSleep = opts.sleep ?? sleep2;
-  const now = opts.now ?? Date.now;
-  const token = loadToken();
-  const start = now();
-  while (true) {
-    const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/await?notificationId=${encodeURIComponent(notificationId)}`, {
-      headers: { authorization: `Bearer ${token}` }
-    }));
-    if (!res.ok) throw new Error(`await failed: ${res.status} ${await res.text()}`);
-    const item = await res.json();
-    if (item.type !== "idle") return item;
-    if (now() - start >= windowMs) return { type: "idle" };
-    await doSleep(intervalMs);
-  }
-}
-async function checkReplies() {
-  const token = loadToken();
-  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/pending`, {
-    headers: { authorization: `Bearer ${token}` }
-  }));
-  if (!res.ok) throw new Error(`check_replies failed: ${res.status} ${await res.text()}`);
-  return await res.json();
-}
-async function setTaskState(id, state) {
-  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/notify/${id}/state`, {
-    method: "PATCH",
-    headers: { "content-type": "application/json", authorization: `Bearer ${loadToken()}` },
-    body: JSON.stringify({ state })
-  }));
-  if (!res.ok) throw new Error(`set_task_state failed: ${res.status} ${await res.text()}`);
-  return await res.json();
-}
-async function pollAnswer(id) {
-  const token = loadToken();
-  const res = ensureAuthed(await fetch(`${BACKEND_URL}/api/poll/${id}`, {
-    headers: { authorization: `Bearer ${token}` }
-  }));
-  if (!res.ok) throw new Error(`poll failed: ${res.status} ${await res.text()}`);
-  return await res.json();
-}
-
-// src/index.ts
-var PollAnswerSchema = z2.object({
-  id: z2.string().describe("Request id returned by notify_user.")
+var PollAnswerSchema = z.object({
+  id: z.string().describe("Request id returned by notify_user.")
 });
-var AwaitReplySchema = z2.object({
-  notificationId: z2.string().describe("The id returned by notify_user \u2014 waits for the user's reply to THIS notification only.")
+var AwaitReplySchema = z.object({
+  notificationId: z.string().describe("The id returned by notify_user \u2014 waits for the user's reply to THIS notification only.")
 });
-var CheckRepliesSchema = z2.object({});
-var PairSchema = z2.object({
-  device_code: z2.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.")
+var CheckRepliesSchema = z.object({});
+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.")
 });
-var SetTaskStateToolSchema = z2.object({
-  notificationId: z2.string(),
+var SetTaskStateToolSchema = z.object({
+  notificationId: z.string(),
   state: SetTaskStateSchema.shape.state
 });
+var RegisterDeliveryToolSchema = z.object({
+  mode: DeliveryModeSchema.describe(
+    "'self_hosted' = the API pushes the moment work lands (requires `npx -y @paigy/mcp paigy-listen` running); 'poll' = the default, you catch up via check_replies/await_reply."
+  )
+});
 function detectGit() {
   const run = (cmd) => {
     try {
@@ -288,7 +72,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. To wait for the answer to something you just asked, call await_reply with that notification's id \u2014 it's scoped to that one request, so it never returns replies meant for other requests. 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 notify_user + await_reply. If a reply comes back as { kind: 'clarify', chunks: [...] }, the user wants more detail on those chunks \u2014 respond by calling notify_user again with the SAME threadId and an expanded description covering them."
+    instructions: "On startup, call check_replies once to pick up any replies or pending work you missed while away. To wait for the answer to something you just asked, call await_reply with that notification's id \u2014 it's scoped to that one request, so it never returns replies meant for other requests. 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 notify_user + await_reply. When you need a decision or input, PREFER a structured answer (select:'confirm', 'one', 'many', or 'rank') over an open-ended free-text ask \u2014 structured options save the user a tap, and they can always add free text on top. If a reply comes back as { kind: 'clarify', chunks: [...] }, the user wants more detail on those chunks \u2014 respond by calling notify_user again with the SAME threadId and an expanded description covering them. When urgency is 'call', remember the title + description are spoken aloud \u2014 write them short and conversational, and name things instead of using IDs (e.g. 'the pull request about the agents page', not 'PR #235'). When the user asks you to follow up later \u2014 when you're done, if you're blocked, or at a set time \u2014 record it with schedule_callback so you don't drop it if you go idle."
   }
 );
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -301,11 +85,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: "unpair",
       description: "Log out / unpair this agent from the user's Paigy account: revokes the token server-side (it stops working everywhere) and deletes the local ~/.paigy/token.json. Takes no arguments. After this, notify_user/await_reply won't work until the user pairs again with the pair tool.",
-      inputSchema: zodToJsonSchema(z2.object({}), { target: "openApi3" })
+      inputSchema: zodToJsonSchema(z.object({}), { target: "openApi3" })
     },
     {
       name: "notify_user",
-      description: "Notify the user via Paigy and get a request id to poll for their answer. 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; 'call' rings their phone now as a voice call \u2014 use 'call' only when you genuinely need them in the moment (blocked/waiting, time-sensitive), not for routine FYIs. Plus optional options (answerable choices; each may carry a sandboxed `html` or an `image` preview for a visual 'pick one' \u2014 e.g. show layout/UI alternatives) and visuals. Use `select` to control how the user answers options: 'one' (default) = pick a single option; 'many' = multi-select, user checks any subset \u2192 answer arrives as {kind:'multi', optionIds:[...]}; 'rank' = select and order, user taps options in preferred order \u2192 answer arrives as {kind:'ranked', optionIds:[...]} (ordered by choice). 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.",
+      description: "Notify the user via Paigy and get a request id to poll for their answer. 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). 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. DEFAULT to a structured answer shape \u2014 structured options save the user a tap, and they can ALWAYS add free text on top of any structured paige, so you lose nothing by structuring it. Pick the answer shape with `select` \u2014 DON'T leave a decision as open-ended free text: a yes/no or approve/deny \u2192 select:'confirm' (set confirmStyle:'approve' for Approve/Deny); it's answerable right from the banner and arrives as {kind:'confirm', approved:boolean}. Pick one of several \u2192 options + select:'one' (default) \u2192 {kind:'option', optionId}. Pick several \u2192 select:'many' \u2192 {kind:'multi', optionIds:[...]}. Rank/order a subset \u2192 select:'rank', user taps in preferred order \u2192 {kind:'ranked', optionIds:[...]}. For visual choices give each option a sandboxed `html` or an `image` preview (e.g. layout/UI alternatives). Only leave options off (pure free text / voice) when the answer genuinely can't be structured. Plus optional visuals. 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: zodToJsonSchema(NotifyRequestSchema, { target: "openApi3" })
     },
     {
@@ -315,18 +99,28 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     },
     {
       name: "await_reply",
-      description: "Wait for the user's reply to THE specific notification you sent for the current request (pass its id 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' }. Scoped to that one notification \u2014 it NEVER returns replies meant for other notifications/requests, so concurrent requests don't cross.",
+      description: "Wait for the user's reply to THE specific notification you sent for the current request (pass its id 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' }. Scoped to that one notification \u2014 it NEVER returns replies meant for other notifications/requests, so concurrent requests 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 and any later turns as their follow-up (e.g. the end-of-call 'call me back when it's done / I have a blocking question' reply). 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).",
       inputSchema: zodToJsonSchema(AwaitReplySchema, { target: "openApi3" })
     },
     {
       name: "check_replies",
-      description: "The catch-up router for everything NOT tied to your current request: returns replies the user sent that you haven't seen yet (now marked seen) plus still-pending notifications you sent. Use it when booting up / starting a session, or when you've been waiting a long time on something else, to discover acks or work you're unaware of. To wait on a request you just sent, use await_reply instead.",
+      description: "The catch-up router for everything NOT tied to your current request: returns replies the user sent that you haven't seen yet (now marked seen), still-pending notifications you sent, and `requests` \u2014 new requests the user started toward you (each { notificationId, threadId, text }, returned once). Act on each request and reply with notify_user on the SAME threadId. Use it when booting up / starting a session, or when you've been waiting a long time on something else, to discover acks or work you're unaware of. To wait on a request you just sent, use await_reply instead. Also returns owedCallbacks: callbacks now due that you promised \u2014 fulfill each with notify_user on its threadId.",
       inputSchema: zodToJsonSchema(CheckRepliesSchema, { target: "openApi3" })
     },
     {
       name: "set_task_state",
       description: "Report progress on a request you received: in_progress (you started working), completed (done), or needs_input (you need more from the user \u2014 usually paired with a notify_user carrying parentId = this request's id).",
       inputSchema: zodToJsonSchema(SetTaskStateToolSchema, { target: "openApi3" })
+    },
+    {
+      name: "register_delivery",
+      description: "Choose how Paigy reaches you when a reply or new request lands. 'self_hosted' makes Paigy PUSH it instantly over a realtime channel instead of you polling \u2014 but it only helps if a `paigy listen` daemon is running (npx -y @paigy/mcp paigy-listen), which the user runs once. 'poll' (default) keeps the catch-up model (check_replies / await_reply). Either way no work is ever lost: a missed push is reconciled by your next check_replies sweep.",
+      inputSchema: zodToJsonSchema(RegisterDeliveryToolSchema, { target: "openApi3" })
+    },
+    {
+      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: zodToJsonSchema(ScheduleCallbackSchema, { target: "openApi3" })
     }
   ]
 }));
@@ -431,6 +225,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const result = await setTaskState(notificationId, state);
       return { content: [{ type: "text", text: JSON.stringify(result) }] };
     }
+    case "register_delivery": {
+      const { mode } = RegisterDeliveryToolSchema.parse(request.params.arguments);
+      const result = await registerDelivery(mode);
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }
+    case "schedule_callback": {
+      const result = await scheduleCallback(ScheduleCallbackSchema.parse(request.params.arguments));
+      return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }
     default:
       throw new Error(`Unknown tool: ${request.params.name}`);
   }

package/dist/listen.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import {
+  WAKE_EVENT,
+  checkReplies,
+  registerDelivery,
+  wakeChannel
+} from "./chunk-4MRCUW5I.js";
+
+// src/listen.ts
+import { createClient } from "@supabase/supabase-js";
+import { spawn } from "child_process";
+var emit = (obj) => void process.stdout.write(JSON.stringify(obj) + "\n");
+async function sweep(reason) {
+  try {
+    const work = await checkReplies();
+    emit({ type: "sweep", reason, ...work });
+    const cmd = process.env.PAIGY_ON_WAKE;
+    if (cmd && (work.replies.length > 0 || work.requests.length > 0 || work.owedCallbacks.length > 0)) {
+      spawn(cmd, { shell: true, stdio: "inherit" });
+    }
+  } catch (e) {
+    emit({ type: "error", reason, message: e.message });
+  }
+}
+async function main() {
+  const cfg = await registerDelivery("self_hosted");
+  const url = cfg.realtime?.url ?? process.env.PAIGY_SUPABASE_URL;
+  const anonKey = cfg.realtime?.anonKey ?? process.env.PAIGY_SUPABASE_ANON_KEY;
+  if (!url || !anonKey) {
+    throw new Error(
+      "No Realtime credentials \u2014 set SUPABASE_ANON_KEY on the server, or PAIGY_SUPABASE_URL + PAIGY_SUPABASE_ANON_KEY locally."
+    );
+  }
+  const channel = wakeChannel(cfg.tokenId);
+  emit({ type: "listening", channel });
+  await sweep("boot");
+  const sb = createClient(url, anonKey, { auth: { persistSession: false } });
+  sb.channel(channel).on(
+    "broadcast",
+    { event: WAKE_EVENT },
+    (msg) => void sweep(`wake:${msg.payload?.kind ?? "?"}`)
+  ).subscribe();
+  const shutdown = async () => {
+    try {
+      await registerDelivery("poll");
+    } catch {
+    }
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown());
+  process.on("SIGTERM", () => void shutdown());
+}
+if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/^file:\/\//, ""))) {
+  main().catch((e) => {
+    emit({ type: "fatal", message: e.message });
+    process.exit(1);
+  });
+}
+export {
+  sweep
+};

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@paigy/mcp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Paigy MCP server — a voice inbox for your AI agents. Lets an agent notify a user and await their reply.",
   "license": "MIT",
   "type": "module",
   "bin": {
     "mcp": "./dist/index.js",
     "paigy-mcp": "./dist/index.js",
-    "paigy-mcp-onboard": "./dist/onboard.js"
+    "paigy-mcp-onboard": "./dist/onboard.js",
+    "paigy-listen": "./dist/listen.js"
   },
   "files": [
     "dist"
@@ -21,14 +22,15 @@
     "directory": "apps/mcp"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/onboard.ts --format esm --clean",
-    "dev": "tsup src/index.ts src/onboard.ts --format esm --watch",
+    "build": "tsup src/index.ts src/onboard.ts src/listen.ts --format esm --clean",
+    "dev": "tsup src/index.ts src/onboard.ts src/listen.ts --format esm --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "prepublishOnly": "pnpm --filter @paigy/schema build && pnpm build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
+    "@supabase/supabase-js": "^2.47.10",
     "zod": "^3.24.1",
     "zod-to-json-schema": "^3.24.1"
   },
@@ -39,4 +41,4 @@
     "typescript": "^5.7.2",
     "vitest": "^2.1.8"
   }
-}
+}