@paigy/mcp 0.40.40 → 0.40.42

package/README.md

@@ -109,19 +109,22 @@ Or add the entry to `~/.gemini/settings.json`:
 
 Then pair: `PAIGY_AGENT=gemini npx -p @paigy/mcp@latest paigy-mcp-onboard`.
 
-> `PAIGY_AGENT` names the agent AND keys its token slot (defaults to
-> `mcp-agent`). Each client reads only its own slot, so pair with the same
-> `PAIGY_AGENT` the client's config uses — and set it per client so you can
-> tell your connected agents apart.
+> `PAIGY_AGENT` names the agent AND keys its token slot. Without it, each session gets a private slot
+> (`session:<id>`); the shared `mcp-agent` default went on 2026-08-07. Each client reads only its own slot, so pair with the same
+> `PAIGY_AGENT` the client's config uses. A fixed `PAIGY_AGENT` makes every session of that client one agent: two running at once
+> collide, and the copy set aside is refused `holder_conflict` when it acts (#2933). `paigy-harness setup` wires clients without it,
+> so each session hatches its own identity.
 
 ## Tools
 
 One catalog, on every transport (2026-09-11): the agent tools are `AGENT_TOOLS` in
-`packages/schema/src/tools.ts` — contact, manage_goals, get_goals, search, check_activity,
-send_feedback — and both this server and the hosted MCP
+`packages/schema/src/tools.ts` (configure, contact, manage_goals, get_delivery, get_goals, search, check_activity,
+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`.
-This server adds only `configure`, the one identity tool, which pairs, reports who you are,
-renames and logs this agent out (`logOut: true`) over the token file this machine holds, and listen.
+`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
 contact shape. Sending returns immediately unless it asks to `wait`: `wait: true` holds one
 cancellable ~45-second window here for a response to what was sent (the hosted transport
@@ -145,9 +148,8 @@ time. Bookkeeping (`operationId`, the manage request id, the revision an edit wa
 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.
+Until 2026-09-13 the standalone listener below was a legacy host with its own reply intake. Since #1957 it reads
+the same `receive` as `contact({})`, as the next section says.
 
 ## Configuration
 
@@ -163,6 +165,22 @@ not a compatibility fallback for target MCP tools.
 
 ## 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;
@@ -305,12 +323,12 @@ machine is paired and this session's identity is minted by its first tool call;
 
 ## Publishing (maintainers)
 
-Tool input schemas are generated from zod in `src/schema.ts` as draft-2020-12 JSON
+Tool input schemas are generated from zod by `mcpInputSchema` (`packages/schema/src/mcp-schema.ts`) as draft-2020-12 JSON
 Schema, and `src/schema.test.ts` guards that every tool stays valid (strict clients
 like the Anthropic API reject anything else). **A schema fix only reaches agents once
 a new version is published to npm** — 0.8.0 once shipped *without* a committed fix and
-400'd strict clients for weeks. So after any change under `src/schema*` or the tool
-definitions: **bump the version and `pnpm publish`** (don't rely on the commit alone).
+400'd strict clients for weeks. So after any change to the tool schemas (`packages/schema`) or the tool
+definitions: **bump the version in `apps/mcp/package.json`**; publishing is `pnpm release` from the repo root, which the owner runs (`docs/infra/releasing.md`). Don't rely on the commit alone.
 Install recipes pin `@paigy/mcp@latest` so a fresh `npx` picks up the new version; if a
 stale one sticks, `rm -rf ~/.npm/_npx` and restart the client.
 

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

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

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

@@ -5,12 +5,12 @@ import {
   serverInstructions,
   sessionStartHook,
   withSessionStartHook
-} from "./chunk-H2EBILBE.js";
+} from "./chunk-NNB3HQTF.js";
 import {
   CODEX_ENV,
   agentName,
   withCodexEnv
-} from "./chunk-V4OVLFMP.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({}))
   }
 ];