@paigy/mcp 0.40.0 → 0.40.2

package/README.md

@@ -116,14 +116,24 @@ Then pair: `PAIGY_AGENT=gemini npx -p @paigy/mcp@latest paigy-mcp-onboard`.
 
 ## Tools
 
-- **`pair`** — pair this agent with the user's Paigy account (one-time). No args to start: returns the code to show the user **and begins polling for approval in the background**; pass the returned `device_code` to collect the result (it returns the moment the user approves). On success it prompts you to allowlist Paigy's notify/await tools so they run without an approval prompt each time.
-- **`unpair`** — log this agent out of the user's Paigy account; revokes the token server-side and deletes the local one.
-- **`paigy-enable-tools`** (a CLI, *not* a tool) — allowlist Paigy's notify/await tools so they run without an approval prompt each time. `npx -y -p @paigy/mcp@latest paigy-enable-tools` (or `paigy-harness enable-tools`); `--scope project` limits it to the current repo instead of `~/.claude/settings.json`. Merges, never clobbers; leaves `pair`/`unpair` human-approved. **This is deliberately not an MCP tool.** It writes the calling agent's own permission allowlist, which every host worth trusting treats as privilege escalation — Claude Code's auto mode denies it outright, and the user's consent inside Paigy is invisible to the classifier making that call. `pair` returns the command for the agent to print; a human runs it.
-- **`contact`** — THE way to reach the user: tell them something, or ask and get their answer. Core form is two fields — `ask` (plain prose: what you need to tell them or find out) and `waiting` (what happens to your work meanwhile: `none` = just informing, `soft` = want an answer but can keep working, `hard` = stopped until answered — reaches them urgently and escalates to a real phone call). Paigy's broker picks the channel, phrasing, and answer format. When the choices themselves must be *seen*, attach `options` (each may carry a sandboxed `html` or `image` preview); attach `visuals` for context screenshots. Returns `{ notificationId, threadId }`; a threaded follow-up supersedes that thread's pending items, and an identical threaded re-send escalates in place. If a reply comes back as `{kind:'clarify', chunks:[...]}`, contact again on the SAME threadId with an expanded ask. (The former `notify_user`/`notify` names remain accepted as hidden aliases for older setups, and the fully-shaped wire form — context/select/urgency — is still accepted from code; neither is part of the model surface anymore.)
-- **Waiting is part of `contact`.** A contact that rings holds its first ~45 s window itself and returns the outcome in `wait` (`reply` / `partial` / `remind` / `idle`); to keep waiting on that call, call `contact` again with only `{ wait: notificationId }` — nothing is sent. A message delivery is never polled for; its reply arrives through `check_replies` or the wake. (There is no separate `await_reply` tool since 0.40.0.)
-- **`check_replies`** — catch-up sweep: returns replies you haven't consumed yet (now marked seen) plus still-pending notifications, new user-initiated requests, and owed callbacks.
-- **`set_task_state`** — report progress on a request: `in_progress` / `completed` / `needs_input`.
-- **`schedule_callback`** — promise the user a follow-up (`on_done` / `on_blocked` / `scheduled`) so it's not dropped if you go idle.
+One catalog, on every transport (2026-09-11): the agent tools are `AGENT_TOOLS` in
+`packages/schema/src/tools.ts` — contact, check_replies, get_thread, search_threads,
+create_goal, claim_goal, get_goal, update_goal — and both this server and the hosted MCP
+(`apps/api/src/mcp`) publish that list and dispatch it through the SDK's one `runTool`.
+This server adds only onboard, pair and unpair, the tools that mint and delete the token
+file this machine holds. See the [SDK contract](../../packages/sdk/README.md) for the
+single-Goal start shape. Notification returns immediately. Call holds one cancellable
+~45-second window here (the hosted transport returns after one read); continue with
+contact({deliveryId}) without sending another ask. Durable Entries and accepted answers can
+repeat on reads; check_replies lists every open Delivery addressed to you (a request the
+user started toward you, an answer relayed to something you asked, a handoff) without
+consuming any of it, and claim_goal is the catch-up for your own Goals. Bookkeeping ids
+(`operationId`, `idempotencyKey`) are minted here, never asked of the model. Retired
+reply-lease/ACK/work/callback tools and hidden notification aliases are rejected.
+
+The standalone listener below is still a **legacy host and target-release blocker**.
+Its old reply intake must migrate before enabling it against the target runtime; it is
+not a compatibility fallback for target MCP tools.
 
 ## Configuration
 
@@ -135,42 +145,48 @@ Then pair: `PAIGY_AGENT=gemini npx -p @paigy/mcp@latest paigy-mcp-onboard`.
   no extra setup. Two edges: with `HTTP_PROXY` set, an `http://localhost` backend
   proxies too unless `NO_PROXY=localhost` (hostname entries work; CIDR ranges are
   ignored), and `paigy-listen`'s realtime wake channel is a websocket that doesn't
-  proxy — its REST sweeps do.
+  proxy — its REST reads do.
 
 ## Wake any harness (`paigy-listen`)
 
 `paigy-listen` is the self-hosted push daemon: it subscribes to this connection's
-wake channel and sweeps on every nudge. Keep it alive past the terminal with
-`paigy-listen --install` (launchd on macOS, systemd user unit on Linux; `--uninstall`
-removes it).
+wake channel and reads what is waiting on every nudge. Keep it alive past the terminal
+with `paigy-listen --install` (launchd on macOS, systemd user unit on Linux;
+`--uninstall` removes it).
+
+The read is `check_replies` — the open Deliveries addressed to this agent — and it
+**consumes nothing**: no lease, no acknowledgement, and the same read twice returns the
+same list. So the daemon hands the launcher what it found and stops there; claiming is
+the agent's own first act (`claim_goal`), because the daemon shares this machine's
+token with the agent it launches and a second claimer on one identity eats the first
+one's claim.
 
 To launch an agent — any agent, not just Claude — when work arrives, set
-`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:
+`PAIGY_ON_WAKE` to a command before `--install`:
 
 | 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 |
+| `PAIGY_WORK` | everything the wake found, as JSON (`deliveries`, `goal`) |
+| `PAIGY_EVENT` | the wake that caused this run — `boot`, `wake:reply`, `wake:request`… |
+| `PAIGY_PARENT_ID` | the thread to continue on (`PAIGY_THREAD_ID` is the same value, for existing scripts) |
+| `PAIGY_DELIVERY_ID` | the Delivery being acted on — `contact({deliveryId})` rereads it |
+| `PAIGY_GOAL_ID` | the Goal it belongs to — `claim_goal` it **first** |
+| `PAIGY_CONTEXT_THREAD_ID` | a past conversation this Goal names — `get_thread` it **first** |
+| `PAIGY_TEXT` | what the person said, 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".
+item — the oldest open Delivery — because the 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 — 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."' \
+PAIGY_ON_WAKE='claude -p "Handle the Paigy work in $PAIGY_WORK — claim_goal first, and rehydrate threads you do not recognize via get_thread."' \
   npx -y -p @paigy/mcp paigy-listen --install
 
 # 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."' \
+PAIGY_ON_WAKE='codex exec "Claim Paigy goal $PAIGY_GOAL_ID and continue thread $PAIGY_THREAD_ID. The user said: $PAIGY_TEXT. Reply with contact."' \
   npx -y -p @paigy/mcp paigy-listen --install
 ```
 
@@ -184,10 +200,7 @@ script and branch on `$PAIGY_EVENT` there:
 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
+codex exec "Paigy goal $PAIGY_GOAL_ID on thread $PAIGY_THREAD_ID. claim_goal it first. The user said: $PAIGY_TEXT. $seed Reply with contact when done."
 ```
 
 ## Statusline (Claude Code)

package/dist/{chunk-FYH6FW2D.js → chunk-647HS22P.js}

@@ -1,22 +1,11 @@
 import {
-  CHECK_REPLIES_DESCRIPTION,
-  CONTACT_DESCRIPTION,
-  CONTACT_SCHEMA,
-  CREATE_GOAL_DESCRIPTION,
-  CreateGoalSchema,
-  HandoffSchema,
-  SCHEDULE_CALLBACK_DESCRIPTION,
-  SEARCH_THREADS_DESCRIPTION,
-  SET_WORK_STATE_DESCRIPTION,
-  ScheduleCallbackSchema,
-  SetTaskStateSchema,
-  SetWorkStateSchema,
+  AGENT_TOOLS,
   mcpInputSchema,
   serverInstructions
-} from "./chunk-DM6YPBQH.js";
+} from "./chunk-FFI3AIZE.js";
 import {
   AGENT_NAME
-} from "./chunk-CWGZVTPZ.js";
+} from "./chunk-YJEJZT56.js";
 
 // src/toolset.ts
 var ONBOARD_DESCRIPTION = "Get this agent talking to Paigy \u2014 call it FIRST, before contact, and any time you're unsure who you are. One call, and it does whatever the situation needs: NOT SET UP \u2192 hatches an identity instantly if this machine holds a device credential (the user ran the Paigy desktop app or harness), otherwise starts the code ceremony; ALREADY SET UP \u2192 returns your current identity and offers the two things left to decide, renaming it or unpairing; TOKEN NO LONGER VALID \u2192 says so, then re-pairs. Pass { name, voice } to choose who you are when hatching, or to RENAME yourself when already set up (voices: rachel, george, jessica, brian, lily). Safe to call any time: idempotent, and it never writes settings \u2014 the tool-allowlist state it reports is read-only. If it returns a `user_code`, print it to the user immediately and call onboard again with the `device_code`. If it returns `enable_command`, PRINT that command for the user to run \u2014 you cannot apply it yourself (it writes your own permission allowlist, which hosts block as privilege escalation), so print it, don't wait for it, and carry on.";
@@ -24,8 +13,6 @@ var SERVER_INSTRUCTIONS = serverInstructions({ waits: true });
 
 // src/tools.ts
 import { z } from "zod";
-var UpdateGoalToolSchema = z.object({ goalId: z.string().uuid(), revision: z.number().int().positive(), changes: z.record(z.unknown()), reason: z.string().min(1) });
-var ClaimGoalSchema = z.object({ goalId: z.string().uuid() });
 var OnboardSchema = z.object({
   name: z.string().max(60).optional(),
   voice: z.string().max(40).optional(),
@@ -39,29 +26,7 @@ var PairSchema = z.object({
   name: z.string().min(1).max(60).optional().describe("Hatch path only: the name you choose for this identity. Pick your own \u2014 ONE or TWO words, the way you'd introduce yourself on a call (it is spoken aloud and shown in lists). 'Piper', 'Blue Heron' \u2014 never a sentence or a task description."),
   voice: z.string().optional().describe("Hatch path only: your voice on calls \u2014 one of rachel, george, jessica, brian, lily.")
 });
-var GetThreadSchema = z.object({
-  parentId: z.string().describe("The thread to read \u2014 from a reply, request, or past notification.")
-});
-var SearchThreadsSchema = z.object({
-  q: z.string().describe("What to look for \u2014 plain words or a phrase (e.g. 'the livekit timeout', 'deploy to prod').")
-});
-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.")
-});
-var TOOLS = [
-  {
-    // #575: THE attention verb — the one model-facing surface, every agent.
-    // The retired names (notify/notify_user) stay callable as hidden aliases
-    // for stale prompts and cached servers; see toolset.ts for the design.
-    name: "contact",
-    description: CONTACT_DESCRIPTION,
-    inputSchema: CONTACT_SCHEMA
-  },
+var IDENTITY_TOOLS = [
   {
     // ONE rail for starting a session (#875). `pair`, the `paigy-mcp-onboard` CLI and
     // `enable_tools` were three doors into one flow, and "onboard" was the word people
@@ -79,55 +44,11 @@ var TOOLS = [
     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, contact won't work until the user pairs again with the pair tool.",
     inputSchema: mcpInputSchema(z.object({}))
-  },
-  // `await_reply` is GONE (owner, 2026-09-06, hard cutover): the wait is contact's — it holds
-  // the first window of a call it placed, and `contact({ wait: notificationId })` holds the
-  // next. One tool, one loop; the reply-reading guidance moved into CONTACT_DESCRIPTION.
-  {
-    name: "check_replies",
-    description: CHECK_REPLIES_DESCRIPTION,
-    inputSchema: mcpInputSchema(z.object({}))
-  },
-  {
-    name: "get_thread",
-    description: "The chronological transcript of one Paigy conversation thread \u2014 every past ask, answer, and user request on it. Call this to REHYDRATE when you're resuming or being seeded: a check_replies request whose parentId you don't recognize means the user is continuing an old conversation with you, and one carrying a contextParentId means they want a past conversation (possibly with a DIFFERENT agent) as your starting context \u2014 in both cases call get_thread FIRST and read the turns as prior conversation you were part of, not as new input. Turns: { role:'agent', title, description[], answer }, { role:'user', text }, and context turns { role:'handoff'|'recap', title, description[] } \u2014 a handoff is a predecessor's brief for you; a recap SUMMARIZES everything before it (the transcript starts at the latest recap, so treat it as the base and the turns after it as what happened since). Oldest first, capped at the most recent 30.",
-    inputSchema: mcpInputSchema(GetThreadSchema)
-  },
-  {
-    name: "search_threads",
-    description: SEARCH_THREADS_DESCRIPTION,
-    inputSchema: mcpInputSchema(SearchThreadsSchema)
-  },
-  {
-    name: "create_goal",
-    description: CREATE_GOAL_DESCRIPTION,
-    inputSchema: mcpInputSchema(CreateGoalSchema)
-  },
-  { name: "claim_goal", description: "Claim a ready Goal you own and begin work. Returns its active revision.", inputSchema: mcpInputSchema(ClaimGoalSchema) },
-  { name: "update_goal", description: "Update an owned Goal at an exact revision; stale revisions are rejected.", inputSchema: mcpInputSchema(UpdateGoalToolSchema) },
-  {
-    name: "set_work_state",
-    description: SET_WORK_STATE_DESCRIPTION,
-    inputSchema: mcpInputSchema(SetWorkStateSchema)
-  },
-  {
-    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: mcpInputSchema(AnswerCallerQuestionSchema)
-  },
-  {
-    name: "schedule_callback",
-    description: SCHEDULE_CALLBACK_DESCRIPTION,
-    inputSchema: mcpInputSchema(ScheduleCallbackSchema)
-  },
-  {
-    name: "handoff",
-    description: "Deposit your working context for a SUCCESSOR agent \u2014 what you did, what's left, links, gotchas \u2014 as one note on a thread ({ title, notes[] }). This does NOT ring the user or enter their inbox: it's context, not a question. The successor reads it back with get_thread. Pass `target` (a sibling connection's token id or agent name, SAME account only) to hand off DIRECTLY to that agent \u2014 the note is dispatched to it as a request it picks up. Pass `workId` to move that existing outcome and its pending replies to the successor without reminting it; a target is required in that form. Omit `target` to leave the thread for the user to hand off to an agent themselves in the app. Pass `parentId` to land the handoff on an existing conversation; omit it to mint a fresh thread. Returns { parentId }. Pass recap:true when the note SUMMARIZES the thread so far (for a successor OR for your own later session): a recap resets the rehydration window \u2014 get_thread returns the latest recap + only the turns after it. Write one whenever a thread has grown long and you're pausing, handing off, or nearing your context limit.",
-    inputSchema: mcpInputSchema(HandoffSchema)
   }
 ];
+var TOOLS = [...AGENT_TOOLS, ...IDENTITY_TOOLS];
 var TOOL_NAMES = TOOLS.map((t) => t.name);
-var HIDDEN_ALIASES = ["notify", "notify_user", "set_task_state"];
+var HIDDEN_ALIASES = [];
 
 // src/clients.ts
 import { execFile } from "child_process";
@@ -290,14 +211,8 @@ function enablePaigyTools(scope = "user", cwd = process.cwd()) {
 
 export {
   SERVER_INSTRUCTIONS,
-  UpdateGoalToolSchema,
-  ClaimGoalSchema,
   OnboardSchema,
   PairSchema,
-  GetThreadSchema,
-  SearchThreadsSchema,
-  SetTaskStateToolSchema,
-  AnswerCallerQuestionSchema,
   TOOLS,
   openBrowser,
   autoConfigureClients,

package/dist/{chunk-BOLKVO6W.js → chunk-BUTCP2ED.js}

@@ -10,7 +10,7 @@ import {
   saveToken,
   sleep,
   startE2ee
-} from "./chunk-CWGZVTPZ.js";
+} from "./chunk-YJEJZT56.js";
 
 // src/identity.ts
 var CLIENT_LABELS = {