@paigy/mcp 0.25.2 → 0.27.0

package/README.md

@@ -141,22 +141,51 @@ wake channel and sweeps on every nudge. Keep it alive past the terminal with
 removes it).
 
 To launch an agent — any agent, not just Claude — when work arrives, set
-`PAIGY_ON_WAKE` to a command before `--install`. The daemon runs it with the swept
-work in `$PAIGY_WORK` (JSON: `replies`, `requests`, `owedCallbacks`); the sweep has
-already claimed the work, so read `$PAIGY_WORK` rather than calling `check_replies`
-again. A request carrying a `contextThreadId` (or an unfamiliar `threadId`) means
-the user is resuming/seeding a past conversation — rehydrate with `get_thread` first.
+`PAIGY_ON_WAKE` to a command before `--install`. The sweep has already claimed the
+work, so the launcher reads it from the environment rather than calling
+`check_replies` again:
+
+| Variable | What it holds |
+| --- | --- |
+| `PAIGY_WORK` | the whole swept payload as JSON (`replies`, `requests`, `owedCallbacks`, `stalled`, `threads`) |
+| `PAIGY_EVENT` | the wake that caused this run — `boot`, `wake:reply`, `cron:callback`… |
+| `PAIGY_THREAD_ID` | the thread to continue on |
+| `PAIGY_NOTIFICATION_ID` | the notification being answered or acted on (unset for an owed callback) |
+| `PAIGY_CONTEXT_THREAD_ID` | a past conversation the user seeded this with — `get_thread` it **first** |
+| `PAIGY_TEXT` | what the user said (or the callback note you owe them), in prose |
+
+Hand `$PAIGY_WORK` to a harness that can read JSON and decide for itself; use the
+scalars for a plain shell launcher that shouldn't need `jq`. They describe **one**
+item — the oldest thread without a turn already in flight — because the queue rail's
+contract is one thread at a time. An absent fact is unset rather than empty, so
+`${PAIGY_CONTEXT_THREAD_ID:-}` distinguishes "no seed" from "seeded with nothing".
 
 ```sh
-# Claude Code:
+# Claude Code — hand it everything and let it plan:
 PAIGY_ON_WAKE='claude -p "Handle the Paigy work in $PAIGY_WORK — rehydrate threads you do not recognize via get_thread first."' \
   npx -y -p @paigy/mcp paigy-listen --install
 
-# Codex (or any CLI harness) works the same way:
-PAIGY_ON_WAKE='codex exec "Handle the Paigy work in $PAIGY_WORK ..."' \
+# Codex (or any CLI harness) — the scalars are enough for a one-liner:
+PAIGY_ON_WAKE='codex exec "Continue Paigy thread $PAIGY_THREAD_ID. The user said: $PAIGY_TEXT. Call get_thread on it first if you do not recognize it, then reply with contact."' \
   npx -y -p @paigy/mcp paigy-listen --install
 ```
 
+`$PAIGY_TEXT` is whatever the user said, expanded inside a shell command — keep it
+quoted, as above. For anything longer than a one-liner, point `PAIGY_ON_WAKE` at a
+script and branch on `$PAIGY_EVENT` there:
+
+```sh
+#!/bin/sh
+# ~/.paigy/on-wake.sh — chmod +x, then PAIGY_ON_WAKE=~/.paigy/on-wake.sh
+seed=""
+[ -n "${PAIGY_CONTEXT_THREAD_ID:-}" ] && seed="It continues thread $PAIGY_CONTEXT_THREAD_ID — get_thread that first."
+
+case "$PAIGY_EVENT" in
+  cron:callback*) codex exec "You owe the user a callback on thread $PAIGY_THREAD_ID: $PAIGY_TEXT. Deliver it with contact." ;;
+  *)              codex exec "Paigy thread $PAIGY_THREAD_ID. The user said: $PAIGY_TEXT. $seed Reply with contact when done." ;;
+esac
+```
+
 ## Statusline (Claude Code)
 
 `paigy-statusline` prints a one-line connection status — the account's session

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

@@ -122,8 +122,13 @@ var NotifyRequestSchema = z.object({
    *  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.'
+  // 10k, not a sentence budget. What the human hears is bounded by the BROKER — it splits
+  // the ask into topics and gives each one at most three sentences and one question
+  // (broker/agenda-design.md) — not by a wire cap the agent has to pre-summarize under.
+  // Owner, 2026-07-28: "our actual limitation on how long something is to the user should
+  // come from the broker splitting and summarizing." The cap that remains is a size guard.
+  ask: z.string().min(1).max(1e4).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"). Write as much as the situation needs (up to 10k characters) \u2014 Paigy breaks it into topics and reads it back a few sentences at a time; do NOT pre-summarize it into one line. 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."
@@ -207,7 +212,11 @@ var UserAnswerSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("turns"), turns: z.array(TurnSchema).min(1) })
 ]);
 var IntentSchema = z.object({
-  kind: z.enum(["defer", "delegate", "channel", "question"]),
+  // The full vocabulary the bot's mapper emits (mapper.INTENT_KINDS) — the schema lagged
+  // 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"]),
   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
@@ -254,6 +263,22 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
     threadId: z.string(),
     notificationId: z.string()
   }),
+  /** A LIVE call's turn, streamed as it lands (#783). PROVISIONAL: the user can still
+   *  revise any of these until the final reply arrives — partial = intelligence,
+   *  settled = authorization. Use it to PREPARE (fetch, draft, warm), never to act
+   *  irreversibly. If `acts` carries a question aimed at you and you know the answer,
+   *  contact on the same thread right away — the caller hears it on the same call. */
+  z.object({
+    type: z.literal("partial"),
+    notificationId: z.string(),
+    inFlight: z.literal(true),
+    turn: z.object({
+      idx: z.number(),
+      prompt: z.string(),
+      reply: z.string(),
+      acts: z.array(IntentSchema).nullable().optional()
+    })
+  }),
   z.object({ type: z.literal("idle") })
 ]);
 var CallbackTriggerSchema = z.enum(["on_done", "on_blocked", "scheduled"]);
@@ -354,6 +379,27 @@ var UserResponseSchema = z.object({
   covered: z.array(z.string()).optional()
 });
 var VoiceKeySchema = z.enum(["rachel", "george", "jessica", "brian", "lily"]);
+var AgendaTurnSchema = z.object({
+  /** At most three short spoken sentences. Capped because a turn is a breath: a 1031-char
+   *  line went out on 2026-07-28 and the caller could not answer it at all. */
+  info: z.array(z.string().min(1)).max(3).default([]),
+  question: z.string().min(1).nullable(),
+  /** True on the one turn carrying the agent's own declared question. */
+  asks: z.boolean().optional(),
+  /** The claim this turn belongs to (#781) — the RETURN identity: answers route by it.
+   *  Absent on a single-claim plan (the session's own claim) and on shared context turns,
+   *  which route nothing. */
+  claimId: z.string().optional(),
+  /** The claim's voice key (#462) — the OUTBOUND identity, audible who-is-asking. */
+  voice: z.string().optional(),
+  select: SelectShapeSchema.optional(),
+  options: z.array(OptionSchema.omit({ id: true })).optional(),
+  /** The seat was satisfied by the call's own ACCOUNT (replan-design.md, user_info): the
+   *  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()
+});
 var InboxItemSchema = z.object({
   id: z.string(),
   /** The conversation thread + connection this item lives on. Present on the replied
@@ -365,9 +411,11 @@ var InboxItemSchema = z.object({
   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(),
+  /** The call's AGENDA (broker/agenda-design.md): the ordered turns it is made of, built at
+   *  ring/enqueue time. Replaces the condensed line + index-aligned phrased points, which
+   *  between them could not express a call as a sequence. `question: null` is a real turn —
+   *  a status update stays a statement instead of being shaped into a yes/no. */
+  agenda: z.array(AgendaTurnSchema).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(),
@@ -468,7 +516,6 @@ var UserSettingsSchema = z.object({
   /** Per-user ring budget (#603): calls per rolling day before further calls
    *  degrade to banner. Absent = the global default (25). A number, never a
    *  bypass — every account keeps a ceiling. No UI; set per user for testing. */
-  callBudget: z.number().int().min(1).max(500).optional(),
   /** Per-user voice-call tuning (#318): raw knobs forwarded to the call bot's
    *  payload['tuning'] (e.g. { silence_s: 3.5 } — a longer pause window for a
    *  slower speaker). No API-side semantics; the bot resolves each key with its
@@ -550,6 +597,49 @@ var HandoffSchema = z.object({
    *  same primitive; a recap is one whose audience includes you. */
   recap: z.boolean().optional()
 });
+var NoteSourceSchema = z.enum(["app", "call"]);
+var NoteStatusSchema = z.enum(["open", "assigned", "done"]);
+var DecisionSchema = z.object({
+  id: z.string(),
+  /** The note this decision refines; null = recorded on a bare thread (the
+   *  extensibility seam — any conversation can accrue decisions). */
+  noteId: z.string().nullable(),
+  /** What was ambiguous — the broker's (or the user's own) question. */
+  question: z.string(),
+  /** The user's ruling; null while the question is open. */
+  answer: z.string().nullable(),
+  decidedAt: z.string().nullable(),
+  createdAt: z.string()
+});
+var NoteSchema = z.object({
+  id: z.string(),
+  /** One-line headline (broker-titled; deterministic floor). */
+  title: z.string(),
+  /** The original intent, verbatim — assignees always see the user's own words. */
+  intent: z.string(),
+  source: NoteSourceSchema,
+  status: NoteStatusSchema,
+  /** 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(),
+  createdAt: z.string()
+});
+var CreateNoteSchema = z.object({
+  /** The intent, in the user's own words. Stored verbatim; the broker only titles it. */
+  text: z.string().min(1).max(4e3)
+});
+var RecordDecisionSchema = z.object({
+  /** An open decision (from /clarify) to answer. */
+  decisionId: z.string().optional(),
+  /** For an ad-hoc decision: what was ambiguous. Required without `decisionId`. */
+  question: z.string().min(1).max(500).optional(),
+  /** The ruling. */
+  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)
+});
 var DeliveryModeSchema = z.enum(["poll", "self_hosted"]);
 var WAKE_EVENT = "wake";
 var wakeChannel = (tokenId) => `wake:${tokenId}`;
@@ -701,6 +791,8 @@ var NotificationFeedbackKindSchema = z.enum([
   // "These recommended answers aren't good — give me new ones."
   "needs_visual",
   // "There should be a picture or design here."
+  "should_have_called",
+  // "Don't put this in a banner — ring me for something like this."
   "other"
   // anything else — the note carries it.
 ]);

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

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

package/dist/{chunk-2374V6WK.js → chunk-VCEFF2VA.js}

@@ -2277,7 +2277,7 @@ async function reach(url, init) {
 var TITLE_MAX = 90;
 var CHUNKS_MAX = 8;
 var CHUNK_MAX = 300;
-var ASK_MAX = 1e3;
+var ASK_MAX = 1e4;
 var OPTION_MAX = 80;
 var NEEDS_MAX = 6;
 var UNSPEAKABLE = /```|\n/;
@@ -2438,8 +2438,13 @@ var NotifyRequestSchema = z.object({
    *  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.'
+  // 10k, not a sentence budget. What the human hears is bounded by the BROKER — it splits
+  // the ask into topics and gives each one at most three sentences and one question
+  // (broker/agenda-design.md) — not by a wire cap the agent has to pre-summarize under.
+  // Owner, 2026-07-28: "our actual limitation on how long something is to the user should
+  // come from the broker splitting and summarizing." The cap that remains is a size guard.
+  ask: z.string().min(1).max(1e4).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"). Write as much as the situation needs (up to 10k characters) \u2014 Paigy breaks it into topics and reads it back a few sentences at a time; do NOT pre-summarize it into one line. 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."
@@ -2512,6 +2517,23 @@ function normalizeWaiting(req) {
     blocking: req.blocking || waiting === "hard"
   };
 }
+var DERIVE_CHUNKS_MAX = 8;
+var DERIVE_CHUNK_MAX = 300;
+function chunkAsk(text, max = DERIVE_CHUNK_MAX, cap = DERIVE_CHUNKS_MAX) {
+  const body = text.trim();
+  if (!body) return [];
+  const sentences = body.match(/[^.!?]+[.!?]*\s*/g) ?? [body];
+  const chunks = [];
+  for (const raw of sentences) {
+    const s = raw.trim();
+    if (!s) continue;
+    const last = chunks[chunks.length - 1];
+    if (last !== void 0 && `${last} ${s}`.length <= max) chunks[chunks.length - 1] = `${last} ${s}`;
+    else chunks.push(s);
+  }
+  if (chunks.length <= cap) return chunks;
+  return [...chunks.slice(0, cap - 1), chunks.slice(cap - 1).join(" ")];
+}
 function deriveAsk(req) {
   req = normalizeWaiting(req);
   if (!req.ask) return req;
@@ -2523,7 +2545,7 @@ function deriveAsk(req) {
   const { ask: _ask, needs, urgencyHint: _hint, channel: _channel, ...rest } = req;
   return {
     ...rest,
-    context: { title, description: [text] },
+    context: { title, description: chunkAsk(text) },
     // Options riding alongside the ask (#575: pixels can't be prose) floor to a
     // single pick — the model broker may upgrade to many/rank from the wording.
     select: req.options?.length ? "one" : "text",
@@ -2551,7 +2573,11 @@ var UserAnswerSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("turns"), turns: z.array(TurnSchema).min(1) })
 ]);
 var IntentSchema = z.object({
-  kind: z.enum(["defer", "delegate", "channel", "question"]),
+  // The full vocabulary the bot's mapper emits (mapper.INTENT_KINDS) — the schema lagged
+  // 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"]),
   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
@@ -2598,6 +2624,22 @@ var AwaitItemSchema = z.discriminatedUnion("type", [
     threadId: z.string(),
     notificationId: z.string()
   }),
+  /** A LIVE call's turn, streamed as it lands (#783). PROVISIONAL: the user can still
+   *  revise any of these until the final reply arrives — partial = intelligence,
+   *  settled = authorization. Use it to PREPARE (fetch, draft, warm), never to act
+   *  irreversibly. If `acts` carries a question aimed at you and you know the answer,
+   *  contact on the same thread right away — the caller hears it on the same call. */
+  z.object({
+    type: z.literal("partial"),
+    notificationId: z.string(),
+    inFlight: z.literal(true),
+    turn: z.object({
+      idx: z.number(),
+      prompt: z.string(),
+      reply: z.string(),
+      acts: z.array(IntentSchema).nullable().optional()
+    })
+  }),
   z.object({ type: z.literal("idle") })
 ]);
 var CallbackTriggerSchema = z.enum(["on_done", "on_blocked", "scheduled"]);
@@ -2698,6 +2740,27 @@ var UserResponseSchema = z.object({
   covered: z.array(z.string()).optional()
 });
 var VoiceKeySchema = z.enum(["rachel", "george", "jessica", "brian", "lily"]);
+var AgendaTurnSchema = z.object({
+  /** At most three short spoken sentences. Capped because a turn is a breath: a 1031-char
+   *  line went out on 2026-07-28 and the caller could not answer it at all. */
+  info: z.array(z.string().min(1)).max(3).default([]),
+  question: z.string().min(1).nullable(),
+  /** True on the one turn carrying the agent's own declared question. */
+  asks: z.boolean().optional(),
+  /** The claim this turn belongs to (#781) — the RETURN identity: answers route by it.
+   *  Absent on a single-claim plan (the session's own claim) and on shared context turns,
+   *  which route nothing. */
+  claimId: z.string().optional(),
+  /** The claim's voice key (#462) — the OUTBOUND identity, audible who-is-asking. */
+  voice: z.string().optional(),
+  select: SelectShapeSchema.optional(),
+  options: z.array(OptionSchema.omit({ id: true })).optional(),
+  /** The seat was satisfied by the call's own ACCOUNT (replan-design.md, user_info): the
+   *  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()
+});
 var InboxItemSchema = z.object({
   id: z.string(),
   /** The conversation thread + connection this item lives on. Present on the replied
@@ -2709,9 +2772,11 @@ var InboxItemSchema = z.object({
   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(),
+  /** The call's AGENDA (broker/agenda-design.md): the ordered turns it is made of, built at
+   *  ring/enqueue time. Replaces the condensed line + index-aligned phrased points, which
+   *  between them could not express a call as a sequence. `question: null` is a real turn —
+   *  a status update stays a statement instead of being shaped into a yes/no. */
+  agenda: z.array(AgendaTurnSchema).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(),
@@ -2812,7 +2877,6 @@ var UserSettingsSchema = z.object({
   /** Per-user ring budget (#603): calls per rolling day before further calls
    *  degrade to banner. Absent = the global default (25). A number, never a
    *  bypass — every account keeps a ceiling. No UI; set per user for testing. */
-  callBudget: z.number().int().min(1).max(500).optional(),
   /** Per-user voice-call tuning (#318): raw knobs forwarded to the call bot's
    *  payload['tuning'] (e.g. { silence_s: 3.5 } — a longer pause window for a
    *  slower speaker). No API-side semantics; the bot resolves each key with its
@@ -2894,6 +2958,49 @@ var HandoffSchema = z.object({
    *  same primitive; a recap is one whose audience includes you. */
   recap: z.boolean().optional()
 });
+var NoteSourceSchema = z.enum(["app", "call"]);
+var NoteStatusSchema = z.enum(["open", "assigned", "done"]);
+var DecisionSchema = z.object({
+  id: z.string(),
+  /** The note this decision refines; null = recorded on a bare thread (the
+   *  extensibility seam — any conversation can accrue decisions). */
+  noteId: z.string().nullable(),
+  /** What was ambiguous — the broker's (or the user's own) question. */
+  question: z.string(),
+  /** The user's ruling; null while the question is open. */
+  answer: z.string().nullable(),
+  decidedAt: z.string().nullable(),
+  createdAt: z.string()
+});
+var NoteSchema = z.object({
+  id: z.string(),
+  /** One-line headline (broker-titled; deterministic floor). */
+  title: z.string(),
+  /** The original intent, verbatim — assignees always see the user's own words. */
+  intent: z.string(),
+  source: NoteSourceSchema,
+  status: NoteStatusSchema,
+  /** 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(),
+  createdAt: z.string()
+});
+var CreateNoteSchema = z.object({
+  /** The intent, in the user's own words. Stored verbatim; the broker only titles it. */
+  text: z.string().min(1).max(4e3)
+});
+var RecordDecisionSchema = z.object({
+  /** An open decision (from /clarify) to answer. */
+  decisionId: z.string().optional(),
+  /** For an ad-hoc decision: what was ambiguous. Required without `decisionId`. */
+  question: z.string().min(1).max(500).optional(),
+  /** The ruling. */
+  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)
+});
 var DeliveryModeSchema = z.enum(["poll", "self_hosted"]);
 var RegisterDeliverySchema = z.object({ mode: DeliveryModeSchema });
 var OAuthStartSchema = z.object({
@@ -3043,6 +3150,8 @@ var NotificationFeedbackKindSchema = z.enum([
   // "These recommended answers aren't good — give me new ones."
   "needs_visual",
   // "There should be a picture or design here."
+  "should_have_called",
+  // "Don't put this in a banner — ring me for something like this."
   "other"
   // anything else — the note carries it.
 ]);
@@ -3645,15 +3754,38 @@ async function pollAnswer(notificationId) {
   const item = await res.json();
   return item.type === "idle" ? item : decryptItem(item);
 }
+var AWAIT_WINDOW_MS = 45e3;
+var _partialSeen = /* @__PURE__ */ new Map();
+async function pollPartials(notificationId) {
+  const token = readToken();
+  const after = _partialSeen.get(notificationId) ?? 0;
+  try {
+    const res = await reach(
+      `${BACKEND_URL}/api/await/partials?notificationId=${encodeURIComponent(notificationId)}&afterIdx=${after}`,
+      { headers: { authorization: `Bearer ${token}` } }
+    );
+    if (!res.ok) return null;
+    const body = await res.json();
+    const next = body.turns?.[0];
+    if (!next) return null;
+    _partialSeen.set(notificationId, next.idx);
+    return { type: "partial", notificationId, inFlight: true, turn: next };
+  } catch {
+    return null;
+  }
+}
 async function awaitReply(notificationId, opts = {}) {
   const intervalMs = opts.intervalMs ?? 5e3;
-  const windowMs = opts.windowMs ?? 3e5;
+  const windowMs = opts.windowMs ?? AWAIT_WINDOW_MS;
   const doSleep = opts.sleep ?? sleep2;
   const now = opts.now ?? Date.now;
   const start = now();
   while (true) {
+    if (opts.signal?.aborted) return { type: "idle" };
     const item = await pollAnswer(notificationId);
     if (item.type !== "idle") return item;
+    const partial = await pollPartials(notificationId);
+    if (partial) return partial;
     if (now() - start >= windowMs) return { type: "idle" };
     await doSleep(intervalMs);
   }
@@ -3705,6 +3837,15 @@ 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()}` },
+    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) {
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/notify/${notificationId}/state`, {
     method: "PATCH",
@@ -3773,6 +3914,7 @@ export {
   getThread,
   searchThreads,
   checkReplies,
+  answerCallerQuestion,
   setTaskState,
   registerDelivery,
   scheduleCallback,

package/dist/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   HandoffSchema
-} from "./chunk-LUY5MXDM.js";
+} from "./chunk-47E77CDG.js";
 import {
   PAIGY_TOOL_IDS,
   autoConfigureClients,
   claudeInstallHint,
   enablePaigyTools
-} from "./chunk-FEAIZ6DA.js";
+} from "./chunk-QXPLQKIM.js";
 import {
   clearSurface,
   writeSurface
@@ -17,6 +17,7 @@ import {
   ScheduleCallbackSchema,
   SetTaskStateSchema,
   UnpairedError,
+  answerCallerQuestion,
   awaitReply,
   checkReplies,
   deleteKeyFile,
@@ -39,7 +40,7 @@ import {
   sleep,
   startE2ee,
   submitNotification
-} from "./chunk-2374V6WK.js";
+} from "./chunk-VCEFF2VA.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -83,7 +84,7 @@ var CONTACT_SCHEMA = {
   properties: {
     ask: {
       type: "string",
-      description: "What to tell the user, or what you need to find out from them. Plain prose, one or two sentences; may be spoken aloud on a call, so write natural speech and name things (not IDs)."
+      description: "What to tell the user, or what you need to find out from them. Plain prose \u2014 as long as it needs to be (up to 10k characters); Paigy splits it into topics and reads back a few sentences at a time, so do NOT compress a briefing into one line. May be spoken aloud on a call, so write natural speech and name things (not IDs)."
     },
     waiting: {
       type: "string",
@@ -220,8 +221,12 @@ function clearPairing(deviceCode) {
 
 // src/index.ts
 var AwaitReplySchema = z.object({
-  notificationId: z.string().describe("The notificationId returned by contact \u2014 waits for the user's reply to THIS notification only.")
+  notificationId: z.string().describe("The notificationId returned by contact \u2014 waits for the user's reply to THIS notification only."),
+  maxWaitSeconds: z.number().int().min(5).max(300).optional().describe(
+    "How long to hold this ONE call before returning { type:'idle' } so you can loop. Default 45 \u2014 safely under the 60s cap most MCP hosts put on a single tool call. Raise it only if you know your host allows longer; a value past the cap means the call is killed and you get nothing."
+  )
 });
+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.")
 });
@@ -238,6 +243,10 @@ var SetTaskStateToolSchema = z.object({
   notificationId: z.string(),
   state: SetTaskStateSchema.shape.state
 });
+var AnswerCallerQuestionSchema = z.object({
+  notificationId: z.string().describe("The notification whose call carried the caller's question \u2014 from the partial turn or the settled reply."),
+  answer: z.string().min(1).max(1500).describe("The answer, as one or two short SPOKEN sentences \u2014 it may be read aloud on the live call.")
+});
 function detectGit() {
   const run = (cmd) => {
     try {
@@ -319,7 +328,7 @@ function renderPairOutcome(outcome, device_code) {
           text: JSON.stringify({
             status: "pending",
             device_code,
-            message: "Still awaiting approval. Call pair again with this device_code to keep waiting."
+            message: "Still awaiting approval \u2014 the user hasn't entered the code yet. Call pair again with this device_code RIGHT NOW to keep waiting; each call returns after ~45s so it can't be killed by a host tool-call timeout. Nothing is lost between calls: the code stays valid and approval keeps being polled in the background, so a re-call returns the instant they approve."
           })
         }]
       };
@@ -381,7 +390,7 @@ 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 ~5 min; returns { type:'reply', answer } when they respond, { type:'remind', remindInSeconds } on snooze (ScheduleWakeup then await_reply again), or { type:'idle' } (timed out this window, no answer yet). On idle, if this is genuinely still blocking you and you have nothing else useful to do meanwhile, just call await_reply again immediately \u2014 keep looping. This is how you actually deliver on the point of calling: the user steps away for a while and comes back to find you'd already continued the moment they answered, not idle waiting to be checked on. Don't give up after one window. Only stop looping to do other work (and check back later), or after an unreasonably long stretch (tens of minutes to hours) worth telling the user about instead. Scoped to that one notification \u2014 it NEVER returns replies meant for other notifications, so concurrent 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 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.",
       inputSchema: json(AwaitReplySchema)
     },
     {
@@ -404,6 +413,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       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.",
       inputSchema: json(SetTaskStateToolSchema)
     },
+    {
+      name: "answer_caller_question",
+      description: "Answer a question the user asked DURING a live call, while they're still on it. When a partial turn or a settled reply carries a `question` intent aimed at you, answer it here immediately: if their call is still live, your answer is spoken to them on that same call (returns live: true). If the call already ended (live: false), send the answer as a threaded contact instead \u2014 never drop it. Short spoken sentences only; this may be read aloud.",
+      inputSchema: json(AnswerCallerQuestionSchema)
+    },
     {
       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.",
@@ -417,9 +431,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   ];
   return { tools };
 });
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
+server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
   try {
-    return await handleTool(request);
+    return await handleTool(request, extra?.signal);
   } catch (e) {
     if (e instanceof UnpairedError) return pairStartResult(await startPairing(suggestedAgentName()));
     throw e;
@@ -444,14 +458,14 @@ function suggestedAgentName() {
   if (!raw) return void 0;
   return CLIENT_LABELS[raw.toLowerCase()] ?? raw.replace(/[-_]+/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
-async function handleTool(request) {
+async function handleTool(request, signal) {
   switch (request.params.name) {
     case "pair": {
       const { device_code } = PairSchema.parse(request.params.arguments ?? {});
       if (!device_code) {
         return pairStartResult(await startPairing(suggestedAgentName()));
       }
-      const capMs = 9e4;
+      const capMs = JOIN_CAP_MS;
       const outcome = await joinBackgroundPair(device_code, capMs) ?? await resolvePairing(device_code, capMs);
       return renderPairOutcome(outcome, device_code);
     }
@@ -510,8 +524,11 @@ async function handleTool(request) {
       return { content: [{ type: "text", text: JSON.stringify(result) }] };
     }
     case "await_reply": {
-      const { notificationId } = AwaitReplySchema.parse(request.params.arguments);
-      const item = await awaitReply(notificationId);
+      const { notificationId, maxWaitSeconds } = AwaitReplySchema.parse(request.params.arguments);
+      const item = await awaitReply(notificationId, {
+        ...maxWaitSeconds !== void 0 ? { windowMs: maxWaitSeconds * 1e3 } : {},
+        ...signal ? { signal } : {}
+      });
       return { content: [{ type: "text", text: JSON.stringify(item) }] };
     }
     case "check_replies": {
@@ -526,6 +543,14 @@ async function handleTool(request) {
       const { q } = SearchThreadsSchema.parse(request.params.arguments);
       return { content: [{ type: "text", text: JSON.stringify(await searchThreads(q)) }] };
     }
+    case "answer_caller_question": {
+      const { notificationId, answer } = AnswerCallerQuestionSchema.parse(request.params.arguments);
+      const result = await answerCallerQuestion(notificationId, answer);
+      return { content: [{ type: "text", text: JSON.stringify({
+        ...result,
+        ...result.live ? {} : { note: "The call already ended \u2014 send this as a threaded contact instead so the answer still reaches them." }
+      }) }] };
+    }
     case "set_task_state": {
       const { notificationId, state } = SetTaskStateToolSchema.parse(request.params.arguments);
       const result = await setTaskState(notificationId, state);

package/dist/listen.js

@@ -2,11 +2,11 @@
 import {
   WAKE_EVENT,
   wakeChannel
-} from "./chunk-LUY5MXDM.js";
+} from "./chunk-47E77CDG.js";
 import {
   checkReplies,
   registerDelivery
-} from "./chunk-2374V6WK.js";
+} from "./chunk-VCEFF2VA.js";
 
 // src/listen.ts
 import { createClient } from "@supabase/supabase-js";
@@ -113,6 +113,55 @@ function uninstallService() {
 
 // src/listen.ts
 var emit = (obj) => void process.stdout.write(JSON.stringify(obj) + "\n");
+function answerText(answer) {
+  switch (answer.kind) {
+    case "text":
+      return answer.text;
+    case "option":
+      return answer.label ?? answer.optionId;
+    case "multi":
+    case "ranked":
+      return (answer.labels ?? answer.optionIds).join(", ");
+    case "confirm":
+      return answer.approved ? "approved" : "declined";
+    case "clarify":
+      return answer.chunks.join(" ");
+    // A call log — PAIGY_TEXT is what the USER said, so the bot's prompts stay out
+    // (the full exchange is in PAIGY_WORK for a launcher that wants it).
+    case "turns":
+      return answer.turns.map((t) => t.reply).join(" ");
+    case "ignored":
+      return "";
+  }
+}
+function launchEnv(work, reason) {
+  const env = { PAIGY_WORK: JSON.stringify(work), PAIGY_EVENT: reason };
+  const put = (key, value) => {
+    if (value) env[key] = value;
+  };
+  const lead = work.threads?.find((t) => !t.busy)?.items[0]?.notificationId;
+  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_NOTIFICATION_ID", reply.notificationId);
+    put("PAIGY_TEXT", answerText(reply.answer));
+    return env;
+  }
+  if (request) {
+    put("PAIGY_THREAD_ID", request.threadId);
+    put("PAIGY_NOTIFICATION_ID", request.notificationId);
+    put("PAIGY_CONTEXT_THREAD_ID", request.contextThreadId);
+    put("PAIGY_TEXT", request.text);
+    return env;
+  }
+  const callback = work.owedCallbacks[0];
+  if (callback) {
+    put("PAIGY_THREAD_ID", callback.threadId);
+    put("PAIGY_TEXT", callback.note);
+  }
+  return env;
+}
 async function sweep(reason) {
   try {
     const work = await checkReplies();
@@ -121,7 +170,7 @@ async function sweep(reason) {
     const inbound = work.replies.length > 0 || work.requests.length > 0;
     const reengage = work.owedCallbacks.length > 0 && (reason === "boot" || reason.includes("callback"));
     if (cmd && (inbound || reengage)) {
-      spawn(cmd, { shell: true, stdio: "inherit", env: { ...process.env, PAIGY_WORK: JSON.stringify(work) } });
+      spawn(cmd, { shell: true, stdio: "inherit", env: { ...process.env, ...launchEnv(work, reason) } });
     }
   } catch (e) {
     emit({ type: "error", reason, message: e.message });
@@ -178,5 +227,6 @@ if (isEntry()) {
   }
 }
 export {
+  launchEnv,
   sweep
 };

package/dist/onboard.js

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

package/dist/statusline.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paigy/mcp",
-  "version": "0.25.2",
+  "version": "0.27.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/schema": "0.0.0",
-    "@paigy/sdk": "0.1.0"
+    "@paigy/sdk": "0.1.0",
+    "@paigy/schema": "0.0.0"
   },
   "scripts": {
     "build": "tsup",