@paigy/mcp 0.40.41 → 0.40.42

package/README.md

@@ -119,8 +119,10 @@ Then pair: `PAIGY_AGENT=gemini npx -p @paigy/mcp@latest paigy-mcp-onboard`.
 
 One catalog, on every transport (2026-09-11): the agent tools are `AGENT_TOOLS` in
 `packages/schema/src/tools.ts` (configure, contact, manage_goals, get_delivery, get_goals, search, check_activity,
-send_feedback), and both this server and the hosted MCP
+send_feedback, help), and both this server and the hosted MCP
 (`apps/api/src/mcp`) publish that list and dispatch it through the SDK's one `runTool`.
+`help` serves the Paigy skill's guide (`packs/skill/paigy/SKILL.md`, bundled at build time), whole or by `topic`,
+with no setup; both servers also offer it and a `welcome` as prompts (`/mcp__paigy__help`, `/mcp__paigy__welcome`).
 This server extends `configure`, the one identity tool, which on the hosted MCP only reports who you are: here it also pairs,
 renames and logs this agent out (`logOut: true`) over the token file this machine holds. It adds `listen`.
 `onboard` is now `configure`; `pair` and `unpair` are folded into it (2026-10-07). See the [SDK contract](../../packages/sdk/README.md) for the
@@ -163,6 +165,22 @@ the same `receive` as `contact({})`, as the next section says.
 
 ## Wake any harness (`paigy-listen`)
 
+**To start listening in a session, run this with your harness's Monitor tool** (in Claude Code:
+Monitor, not a background Bash command, which tells you only when it exits), and start it again
+when the monitor expires:
+
+```sh
+npx -y -p @paigy/mcp@latest paigy-listen --brief
+```
+
+It prints one line for each new thing addressed to you: a Delivery with the person's newest words,
+an answer to one of your questions (the question, what was chosen and who decided), something new
+on one of your Goals, a Goal assigned to you, and any waiting kind it does not know yet. Read the
+Goal it names with `get_goals`, answer with `contact`. Do not filter its output yourself: answers
+arrive as reviews, not Deliveries, and a filter that watched only Deliveries missed two of them.
+The `listen` tool hands you the same command bound to your session; the SessionStart hook prints
+it, and refreshes itself whenever the MCP server starts at a newer version.
+
 `paigy-listen` is the self-hosted push daemon: it subscribes to this connection's
 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;

package/dist/{chunk-AX55W57P.js → chunk-6V4X3EFA.js}

@@ -7,7 +7,7 @@ import {
   saveToken,
   setIdentity,
   sleep
-} from "./chunk-CPDYOHSY.js";
+} from "./chunk-W3FK4FD6.js";
 
 // src/identity.ts
 var CLIENT_LABELS = {

package/dist/{chunk-UVVW32KH.js → chunk-I3WDI2JV.js}

@@ -5,12 +5,12 @@ import {
   serverInstructions,
   sessionStartHook,
   withSessionStartHook
-} from "./chunk-NYSDESST.js";
+} from "./chunk-NNB3HQTF.js";
 import {
   CODEX_ENV,
   agentName,
   withCodexEnv
-} from "./chunk-CPDYOHSY.js";
+} from "./chunk-W3FK4FD6.js";
 
 // src/toolset.ts
 var CONFIGURE_DESCRIPTION = "Set this agent up with Paigy \u2014 call it FIRST, before contact, and any time you're unsure who you are. One call does whatever the situation needs: NOT SET UP \u2192 if this machine holds a device credential (the user ran the Paigy desktop app or harness) it hatches an identity INSTANTLY, no code and no approval; otherwise it starts the code ceremony. ALREADY SET UP \u2192 returns your current identity and the two things left to decide, renaming it or logging out. 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 (pick your own; voices: rachel, george, jessica, brian, lily). Safe to call any time: idempotent, and it never writes settings.\n\nTHE CODE CEREMONY does not open a browser; the user enters the code in the Paigy app (or scans `qr`). A result with { user_code, device_code, qr, user_message } has already started polling for approval in the background: you MUST immediately print the `user_message` (the bare code) to the user, AND in that same turn call configure again with that `device_code` to collect the result. It returns the moment the user approves; on { status:'pending' } call again to keep waiting; on { status:'awaiting_confirmation' } (E2EE) show the bare `user_message` verify code and call again to finish. Every result's first text block states the code plainly.\n\nOn { status:'paired' }, or whenever it returns `enable_command`, ALWAYS follow the `enable_prompt`: PRINT that command for the user to run, so Paigy's tools stop prompting each time. 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.\n\nLOG OUT with { logOut: true }: it logs out THIS agent only \u2014 its token is revoked server-side and its local entry removed. Other agents and this device's credential are untouched, and a later configure re-hatches instantly while the device credential exists. Disconnecting the device itself is not an agent tool.";
@@ -36,7 +36,7 @@ var IDENTITY_TOOLS = [
   },
   {
     name: "listen",
-    description: "Am I listening for answers, and can Paigy resume this session? Takes no arguments. Returns status `listening` for harness delivery or a running listener with a ready wake adapter; `receiving` means a process is running but automatic resume is not confirmed (read its wake error or watch its output); `unpaired` means call configure; `start` gives the exact command to run NOW as a watched background task for this session. Start it once. Codex queues into CODEX_THREAD_ID automatically when its CLI supports queue; PAIGY_ON_WAKE overrides it. A successful queue is not evidence the agent handled the answer: receive with contact({ wait: false }) and read the relevant Goal, then respond with contact. This tool never subscribes or starts anything itself.",
+    description: "Am I listening for answers, and can Paigy resume this session? Takes no arguments. Returns status `listening` for harness delivery or a running listener with a ready wake adapter; `receiving` means a process is running but automatic resume is not confirmed (read its wake error or watch its output); `unpaired` means call configure; `start` gives the exact command to run NOW with your harness's Monitor tool (not a background command, which speaks only when it exits). Start it once. Codex queues into CODEX_THREAD_ID automatically when its CLI supports queue; PAIGY_ON_WAKE overrides it. A successful queue is not evidence the agent handled the answer: receive with contact({ wait: false }) and read the relevant Goal, then respond with contact. This tool never subscribes or starts anything itself.",
     inputSchema: mcpInputSchema(z.object({}))
   }
 ];