@paigy/mcp 0.17.0 → 0.17.1

package/dist/{chunk-ZIOTFQPK.js → chunk-IMIXCPTN.js}

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

package/dist/chunk-MH6AHNUI.js

@@ -0,0 +1,633 @@
+// ../../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 ParticipantSchema = z.object({
+  kind: z.enum(["human", "agent"]),
+  id: z.string()
+});
+var TransformSchema = z.enum([
+  "structure",
+  // shape intent into an answer contract; pick channel/urgency — broker `ask`, `select` shapes, `points`
+  "request_more",
+  // clarify / follow-ups / uncovered points; escalate inbox→call — {kind:'clarify'}, escalate, blocking
+  "redirect",
+  // seed / hand off a thread to a new recipient — handoff, "new session from this"
+  "break_down",
+  // one bundle → many sub-asks — checklist fan-out, `points`
+  "coalesce",
+  // many bundles → one — morning triage (#347), threading-supersede, digest
+  "organize",
+  // group related bundles onto one thread — threading (`threadId`), parent/clarify links
+  "summarize"
+  // reduce volume, keep decision value — 30-turn cap, spoken briefing
+]);
+var OptionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  // .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 NotifyLevelSchema = z.enum(["inbox", "push", "banner", "call"]);
+var SelectShapeSchema = z.enum(["one", "many", "rank", "confirm", "text"]);
+var ReceiptEventSchema = z.enum([
+  "delivered",
+  // the bundle reached the recipient at some level
+  "seen",
+  // the recipient opened it
+  "answered",
+  // the recipient replied
+  "escalated",
+  // re-reached at a higher level (re-ring / promote)
+  "coalesced",
+  // merged into another live claim
+  "expired",
+  // deadline passed unanswered
+  "woke",
+  // the agent was woken for an owed obligation (callback)
+  "gave_up"
+  // the budget was spent — stopped re-engaging
+]);
+var AttentionSchema = z.object({
+  urgency: NotifyLevelSchema,
+  /** The required answer shape, or null for a plain notify that asks nothing back. */
+  select: SelectShapeSchema.nullable(),
+  /** Coverage contract (#396) — points the answer must address; null = none declared. */
+  points: z.array(z.string()).nullable(),
+  /** Whether the ask blocks the sender — what lets arbitration escalate it on silence. */
+  blocking: z.boolean(),
+  /** Reserved (MODEL.md lists it): a response deadline. No row column yet — a later Phase 2
+   *  slice wires it; optional so today's rows/callers project cleanly. */
+  deadline: z.string().datetime().nullable().optional()
+});
+var NotifyRequestSchema = z.object({
+  /** Plaintext message content. Present on the plaintext path (today's shape);
+   *  ABSENT on the E2EE path, where the sealed `envelope` below carries it. The
+   *  superRefine at the bottom enforces exactly one of the two. */
+  context: ContextSchema.optional(),
+  options: z.array(OptionSchema.omit({ id: true })).min(1).optional().describe(
+    "The choices, in order \u2014 required when select is 'one'/'many'/'rank', omitted otherwise. Ids are assigned automatically by position ('1', '2', \u2026); the user's answer references them as optionId(s)."
+  ),
+  points: z.array(z.string().min(1)).optional().describe(
+    "The distinct things you need answered, each a short phrase \u2014 on a call the broker keeps the conversation going until each is addressed, and the reply reports which were covered, so a half-answer is never silently returned as final. Omit for single-part asks."
+  ),
+  visuals: z.array(VisualSchema).optional().describe(
+    "Images attached to the message itself \u2014 context for the whole question (a screenshot, a chart). For a preview on one selectable choice, use that option's `html`/`image` instead."
+  ),
+  /** Git repo the agent is working in ("owner/name"). Local MCP fills this from the checkout — omit unless overriding. */
+  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(),
+  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(),
+  /** 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?,
+   *  visuals? }` of opaque Envelopes — one seal per present content field, so a
+   *  message with no options/visuals seals only `context`. It COEXISTS with the
+   *  plaintext fields by mutual exclusion: the superRefine below requires that
+   *  when `envelope` is present the plaintext `context`/`options`/`visuals` are
+   *  ABSENT (and vice-versa), so a row is either fully plaintext or fully sealed —
+   *  never a readable half. The server persists this OPAQUELY into
+   *  notifications.envelope and relays it blindly; it never decrypts. Absent =
+   *  today's plaintext path (context/options/visuals carry the cleartext).
+   *  z.lazy because EnvelopeSchema is declared further down (E2EE section). */
+  envelope: z.object({
+    context: z.lazy(() => EnvelopeSchema).optional(),
+    options: z.lazy(() => EnvelopeSchema).optional(),
+    visuals: z.lazy(() => EnvelopeSchema).optional()
+  }).optional(),
+  select: SelectShapeSchema.optional().describe(
+    "How the user answers \u2014 required on the fully-shaped form, pick the shape that fits the question: 'one' = pick one option, 'many' = pick several, 'rank' = pick & order (each needs `options`); 'confirm' = yes/no or approve/deny; 'text' = free-form reply only (status updates, open questions). 'confirm' and 'text' take no options. Omit only when sending the simplified `ask` form \u2014 the broker picks the shape."
+  ),
+  /** The simplified form (#395): instead of shaping the notification yourself
+   *  (context/select/options/urgency), state what you need to learn and why it
+   *  matters now — the broker derives the optimal shape and channel. Mutually
+   *  exclusive with `context` (and never sent alongside `envelope`: E2EE pairings
+   *  derive agent-side before sealing, so the server only ever shapes plaintext). */
+  ask: z.string().min(1).optional().describe(
+    'SIMPLIFIED FORM \u2014 state in plain prose what you need to learn from the user and why it matters now (e.g. "I need to know whether to deploy the auth fix \u2014 tests are green, staging verified"). Paigy derives the title, answer shape, options, and delivery channel for you. Mutually exclusive with context/select/options \u2014 send one form or the other.'
+  ),
+  needs: z.array(z.string().min(1)).optional().describe(
+    "With `ask` only: the distinct things you need answered when the ask is multi-part \u2014 becomes the coverage contract (`points`), so a half-answer is never silently final."
+  ),
+  urgencyHint: z.enum(["whenever", "soon", "now"]).optional().describe(
+    "With `ask` only: how urgently you need the answer \u2014 'whenever' (inbox), 'soon' (worth a heads-up), 'now' (you're blocked this minute). A hint, not a command: the user's settings still have the final word."
+  ),
+  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'."
+  ),
+  blocking: z.boolean().default(false).describe(
+    "Set true when real downstream work is stuck behind this specific decision \u2014 you can't make meaningful progress until it's answered. This is the real signal for how urgently the user should be reached; it's what the premier use case (an agent that stays unblocked instead of going idle) depends on. Independent of `urgency`: a `banner`-level question can still be `blocking` (something IS stuck, just not time-critical enough to ring for immediately) \u2014 if it goes unanswered a while, Paigy escalates it to a real call using this flag rather than guessing from how many other things happen to be pending. Leave false for anything you could work around, defer, or where other useful work exists meanwhile."
+  )
+}).superRefine((r, ctx) => {
+  const sealed = !!r.envelope;
+  if (sealed) {
+    if (!r.envelope?.context)
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["envelope", "context"], message: "sealed request must include envelope.context" });
+    for (const f of ["context", "options", "visuals"]) {
+      if (r[f] !== void 0)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: [f], message: `E2EE request must not carry plaintext ${f} \u2014 it's sealed in envelope.${f}` });
+    }
+    if (r.points !== void 0)
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["points"], message: "E2EE request must not carry plaintext points" });
+    if (r.ask !== void 0)
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["ask"], message: "E2EE request must not carry a plaintext ask \u2014 derive the shape agent-side and seal it" });
+    if (r.needs !== void 0)
+      ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["needs"], message: "E2EE request must not carry plaintext needs" });
+    return;
+  }
+  if (r.ask !== void 0) {
+    for (const f of ["context", "options", "select", "points", "visuals"]) {
+      if (r[f] !== void 0)
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: [f], message: `the simplified \`ask\` form takes no ${f} \u2014 the broker derives it (use \`needs\` for multi-part asks)` });
+    }
+    return;
+  }
+  if (r.needs !== void 0 || r.urgencyHint !== void 0)
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["needs"], message: "needs/urgencyHint belong to the simplified `ask` form \u2014 with a shaped request use points/urgency" });
+  if (!r.context)
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["context"], message: "context is required (plaintext path)" });
+  if (!r.select)
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["select"], message: "select is required on the shaped form" });
+  const needsOptions = r.select === "one" || r.select === "many" || r.select === "rank";
+  if (needsOptions && !r.options?.length)
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["options"], message: `select:'${r.select}' requires options` });
+  if (!needsOptions && r.options?.length)
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["options"], message: `select:'${r.select}' takes no options` });
+});
+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 IntentSchema = z.object({
+  kind: z.enum(["defer", "delegate", "channel"]),
+  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
+   *  the seconds, ready to pass straight to schedule_callback. Absent when the
+   *  detail didn't parse (the agent interprets it) or the kind isn't defer. */
+  dueInSeconds: z.number().int().positive().optional()
+});
+var AwaitItemSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("reply"),
+    threadId: z.string(),
+    notificationId: z.string(),
+    answer: UserAnswerSchema,
+    /** E2EE: present when the answer is sealed. The server relays the opaque answer
+     *  envelope + the plaintext `ignored` status hint; the receiving agent OPENS it
+     *  with its device key and re-derives the real UserAnswer, treating a mismatch
+     *  against `ignored` as tampering. Absent = today's plaintext answer (in `answer`).
+     *  On a sealed reply the plaintext `answer` is a placeholder (kind reflects only
+     *  the `ignored` bit) — never the real content, which stays sealed. */
+    sealed: z.lazy(() => SealedAnswerSchema).optional(),
+    /** Broker extras (#381), present when the answer was mapped from a call: next
+     *  steps the user attached ("call me after lunch" → defer — act on it via
+     *  schedule_callback) and the raw words the shaped answer was mapped from. */
+    intents: z.array(IntentSchema).optional(),
+    transcript: z.string().optional(),
+    /** Coverage report (#396), when the ask declared `points`: which of them this
+     *  answer addressed. Missing points = re-ask or proceed knowingly partial. */
+    covered: z.array(z.string()).optional()
+  }),
+  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,
+      /** E2EE: the sealed answer (opaque envelope + plaintext `ignored` hint) when the
+       *  pairing is E2EE — the agent opens it and re-derives the real answer. Absent =
+       *  plaintext answer (in `answer`). See AwaitItemSchema's reply variant. */
+      sealed: z.lazy(() => SealedAnswerSchema).optional(),
+      /** Broker extras (#381): next steps the user attached to a call-mapped answer
+       *  ("call me after lunch" → defer — act on it via schedule_callback) and the
+       *  raw words the shaped answer was mapped from. */
+      intents: z.array(IntentSchema).optional(),
+      transcript: z.string().optional(),
+      /** Coverage report (#396): which declared `points` this answer addressed. */
+      covered: z.array(z.string()).optional()
+    })
+  ),
+  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. Keeps reappearing until you call
+   *  set_task_state on its notificationId. */
+  requests: z.array(
+    z.object({
+      threadId: 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()
+    })
+  ),
+  /** 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() })
+  ),
+  /** 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() })
+  )
+});
+var NotifyResponseSchema = z.object({
+  notificationId: 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(),
+  intents: z.array(IntentSchema).optional(),
+  transcript: z.string().optional(),
+  /** E2EE: the sealed answer (opaque envelope + plaintext `ignored` hint) when the item was
+   *  E2EE-sealed. Present → the server persists it opaquely and branches status on `ignored`;
+   *  the plaintext `answer` is a placeholder (`{ kind: "ignored" }`) the server ignores for a
+   *  sealed row. Absent = today's plaintext answer, unchanged. */
+  sealed: z.lazy(() => SealedAnswerSchema).optional(),
+  /** Coverage report (#396): which of the ask's declared `points` were addressed. */
+  covered: z.array(z.string()).optional()
+});
+var VoiceKeySchema = z.enum(["rachel", "george", "jessica", "brian", "lily"]);
+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(),
+  tokenId: z.string().optional(),
+  status: NotifyStatusSchema,
+  context: ContextSchema,
+  options: z.array(OptionSchema).optional(),
+  /** The ask's declared coverage points (#396), when the agent sent them. */
+  points: z.array(z.string()).optional(),
+  /** Natural spoken questions for the points (#417 follow-up), phrased at ring time
+   *  and index-aligned — the call bot prefers these over the raw shorthand. */
+  pointsSpeak: z.array(z.string()).optional(),
+  /** On a replied detail (#397): the next steps the user attached to the answer
+   *  ("call back after lunch") — shown so they can see the commitment was captured. */
+  intents: z.array(IntentSchema).optional(),
+  visuals: z.array(VisualSchema).optional(),
+  agent: z.string(),
+  nickname: z.string(),
+  /** The pairing's assigned voice (#462); absent = the default voice. */
+  voice: VoiceKeySchema.optional(),
+  repo: z.string().optional(),
+  branch: z.string().optional(),
+  createdAt: z.string().datetime(),
+  snoozedUntil: z.string().datetime().optional(),
+  agentState: AgentStateSchema.default("idle"),
+  /** Whose action the item is waiting on: "you" = an agent asked you (the default,
+   *  every agent→user notification); "agent" = you sent a request and it's awaiting the
+   *  agent (held in the inbox until the agent replies on the thread). */
+  turn: z.enum(["you", "agent"]).default("you"),
+  /** Hard error reason on an awaiting request (turn="agent") — the wake failed to reach
+   *  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(),
+  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'."
+  ),
+  /** Real downstream work is stuck behind this one — set by the agent, independent of
+   *  urgency (see the main README's "premier use case" + notify/states.md). Drives the
+   *  inbox's blocking badge and the extra confirm step before dismissing it. */
+  blocking: z.boolean().default(false),
+  /** The user's locked-in answer; present only for replied items (GET /api/replied/:id). */
+  answer: UserAnswerSchema.optional(),
+  /** E2EE (text lane): the sealed content this item carries when the pairing is E2EE, in
+   *  place of the plaintext `context`/`options`/`visuals` (which the operator would
+   *  otherwise read). A per-field map of opaque Envelopes — the SAME shape as
+   *  NotifyRequest.envelope. The native app decrypts it locally via openNotification;
+   *  web / an un-enrolled device can't and renders a locked placeholder. Absent = today's
+   *  plaintext item (context carries the cleartext), so plaintext items are unchanged. */
+  envelope: z.object({
+    context: z.lazy(() => EnvelopeSchema).optional(),
+    options: z.lazy(() => EnvelopeSchema).optional(),
+    visuals: z.lazy(() => EnvelopeSchema).optional()
+  }).optional(),
+  /** E2EE: the agent's device X25519 public key to seal the user's answer BACK to (the
+   *  sender the phone replies to). Sourced server-side from this item's pairing credential.
+   *  Present only alongside `envelope`; the phone seals via sealAnswer(answer, this, id). */
+  agentX25519: z.string().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(),
+  fcmToken: z.string().min(1).optional(),
+  platform: z.enum(["ios", "android"])
+});
+var MissedCallSchema = z.enum([
+  "retry_10m",
+  "retry_30m",
+  "retry_60m",
+  "backoff_gentle",
+  "backoff_standard",
+  "backoff_aggressive",
+  "inbox",
+  "dismiss"
+]);
+var BrokerTuningSchema = z.object({
+  /** 'none' = skip the spoken ack after a mapped answer (power users find it slow). */
+  ackVerbosity: z.enum(["normal", "none"]).optional(),
+  /** How readily the mapper asks its one clarification: 'low' = only when truly
+   *  uninterpretable, 'high' = whenever not fully certain. */
+  clarifyEagerness: z.enum(["low", "normal", "high"]).optional(),
+  /** The user's own shorthand: when they say `say`, they mean `mean`. */
+  phrasebook: z.array(z.object({ say: z.string().min(1).max(60), mean: z.string().min(1).max(120) })).max(24).optional()
+});
+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(),
+  /** Opt-in (default false) to using your content to improve Paigy and train models. */
+  improveConsent: z.boolean(),
+  missedCall: MissedCallSchema.default("backoff_standard"),
+  /** Where voice audio is processed. 'hosted' (default) = Paigy's voice services
+   *  (ElevenLabs TTS, faster-whisper STT, the call bot); 'on_device' = the phone
+   *  synthesizes and transcribes locally — no audio or spoken text leaves it.
+   *  Optional, NOT defaulted: a stale client PATCHing the full settings object
+   *  must not silently reset this privacy choice. Absent = leave unchanged on
+   *  write, 'hosted' on read (see store.ts). */
+  voiceMode: z.enum(["hosted", "on_device"]).optional(),
+  /** Account E2EE state (text lane): 'off' (default) = today's plaintext; 'on' =
+   *  content is sealed end-to-end between the local agent and the phone. Like
+   *  voiceMode, OPTIONAL and NOT defaulted so a stale client PATCHing the full
+   *  settings object without it can't silently flip the account's E2EE state.
+   *  Absent = leave unchanged on write, 'off' on read (see store.ts). The demo
+   *  account is plaintext by construction and refuses any non-'off' value. */
+  e2eeMode: z.enum(["off", "on"]).optional(),
+  /** Rung-2 broker tuning (#381). Optional and NOT defaulted, same stale-client
+   *  clobber guard as voiceMode: absent = leave unchanged on write. */
+  broker: BrokerTuningSchema.optional()
+});
+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(),
+  /** The pairing's assigned voice (#462); null = the default voice. */
+  voice: VoiceKeySchema.nullable(),
+  createdAt: z.string().datetime(),
+  /** 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(),
+  /** 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()
+});
+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),
+  /** 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(),
+  /** 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()
+});
+var HandoffSchema = z.object({
+  /** Land the note on an existing thread; omitted mints a fresh one. */
+  threadId: z.string().uuid().optional(),
+  /** One-line headline of the working context handed off. */
+  title: z.string().min(1),
+  /** The brief — standalone notes the successor reads (what was done, what's left, links). */
+  notes: z.array(z.string().min(1)).min(1),
+  /** A sibling connection to dispatch directly to (token id or agent nickname). Same-account
+   *  only; omit to leave the thread for the user to hand off in the app. */
+  target: z.string().optional()
+});
+var DeliveryModeSchema = z.enum(["poll", "self_hosted"]);
+var 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 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 StatusSchema = z.object({
+  agent: z.string(),
+  nickname: z.string(),
+  sessionMode: z.enum(["default", "all_calls", "silent"]),
+  /** A phone is registered for push/ring (any push token on the account). */
+  phone: z.boolean()
+});
+var EnvelopeRecipientSchema = z.object({
+  keyId: z.string(),
+  epk: z.string(),
+  wnonce: z.string(),
+  wrap: z.string()
+});
+var EnvelopeHeaderSchema = z.object({
+  field: z.enum(["context", "options", "visuals", "answer"]),
+  kind: z.string(),
+  senderRole: z.enum(["agent", "user"]),
+  recipientKeyIds: z.array(z.string()),
+  seq: z.number().int().nonnegative()
+});
+var EnvelopeSchema = z.object({
+  v: z.literal(1),
+  alg: z.literal("x25519-xsalsa20poly1305"),
+  msgId: z.string(),
+  hdr: EnvelopeHeaderSchema,
+  recipients: z.array(EnvelopeRecipientSchema).min(1),
+  nonce: z.string(),
+  ct: z.string()
+});
+var SealedAnswerSchema = z.object({
+  ignored: z.boolean(),
+  envelope: EnvelopeSchema
+});
+var DeviceCredentialSchema = z.object({
+  deviceId: z.string(),
+  kind: z.enum(["phone", "web", "agent"]),
+  x25519Pub: z.string(),
+  ed25519Pub: z.string(),
+  sig: z.string()
+});
+var DeviceRosterSchema = z.object({
+  uikPub: z.string(),
+  devices: z.array(DeviceCredentialSchema)
+});
+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 PairingRevealSchema = z.object({
+  x25519: z.string(),
+  ed25519: z.string(),
+  nonce: z.string()
+});
+var DeviceCodeRequestSchema = z.object({
+  agent: z.union([z.string(), z.object({ name: z.string().optional() })]).optional(),
+  device: z.string().optional(),
+  proto: z.string().optional(),
+  // compiled-in tag, e.g. "paigy-pair-v2|sas=24"
+  commitment: z.string().optional()
+  // agent's Ca
+});
+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,
+  proto: z.string().nullable().optional(),
+  agent_commitment: z.string().nullable().optional(),
+  // Ca
+  agent_reveal: PairingRevealSchema.nullable().optional(),
+  // present once the agent reveals
+  agent_credential: DeviceCredentialSchema.nullable().optional(),
+  // the phone's UIK-signed cred over the agent's keys — the agent fetches it here to finalizeE2ee
+  // The phone's reveal + identity key, exposed here so a GATED agent (e2ee_mode='on', token
+  // withheld until e2ee=true) can compute the SAS WITHOUT a token. Public keys — same safety
+  // class as agent_reveal above. Present only once the phone reveals; null otherwise.
+  phone_reveal: PairingRevealSchema.nullable().optional(),
+  uik_pub: z.string().nullable().optional()
+});
+var DeviceTokenRequestSchema = z.object({
+  device_code: z.string(),
+  reveal: PairingRevealSchema.optional()
+  // agent's reveal {x25519, ed25519, nonce}
+});
+var DeviceTokenSchema = z.object({
+  access_token: z.string(),
+  nickname: z.string(),
+  agent: z.string(),
+  device: z.string().nullable(),
+  phone_reveal: PairingRevealSchema.nullable().optional(),
+  // present once the phone reveals
+  uik_pub: z.string().nullable().optional()
+});
+var DeviceCommitRequestSchema = z.object({
+  code: z.string(),
+  commitment: z.string()
+  // Cb
+});
+var DevicePeerCommitSchema = z.object({
+  commitment: z.string().nullable()
+});
+var SupportRequestSchema = z.object({
+  email: z.string().email().max(320),
+  message: z.string().trim().min(1).max(5e3),
+  name: z.string().trim().max(120).optional()
+});
+
+export {
+  HandoffSchema,
+  WAKE_EVENT,
+  wakeChannel
+};