@paigy/mcp 0.40.11 → 0.40.15

package/README.md

@@ -117,8 +117,8 @@ Then pair: `PAIGY_AGENT=gemini npx -p @paigy/mcp@latest paigy-mcp-onboard`.
 ## Tools
 
 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
+`packages/schema/src/tools.ts` — contact, check_replies, 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
@@ -171,18 +171,17 @@ To launch an agent — any agent, not just Claude — when work arrives, set
 | `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 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".
+absent fact is unset rather than empty, so `${PAIGY_GOAL_ID:-}` distinguishes "no
+Goal" from "an empty id".
 
 ```sh
 # Claude Code — hand it everything and let it plan:
-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."' \
+PAIGY_ON_WAKE='claude -p "Handle the Paigy work in $PAIGY_WORK — claim_goal first, and read a Goal you do not recognize with get_goal."' \
   npx -y -p @paigy/mcp paigy-listen --install
 
 # Codex (or any CLI harness) — the scalars are enough for a one-liner:
@@ -190,6 +189,22 @@ PAIGY_ON_WAKE='codex exec "Claim Paigy goal $PAIGY_GOAL_ID and continue thread $
   npx -y -p @paigy/mcp paigy-listen --install
 ```
 
+### A session that starts listening (`listen`, #2265)
+
+Nothing pushes an answer into a session started in a terminal — it waits for that
+session's next `check_replies`. What can reach a running session mid-turn is a watched
+background task, so a terminal session runs `paigy-listen --brief` as its own watched task
+(one human line per event: `Paigy · wake:reply · 2 waiting · lead <deliveryId> on Goal
+<goalId>: "…"`). The `listen` tool is how a session asked to "start listening" gets there
+in one call: it decides and hands over — `listening` (nothing to do), `unpaired` (call
+`onboard`), or `start` with the exact command (this server's own node and `listen.js`,
+`PAIGY_AGENT` and `PAIGY_SESSION_ID` set to this session's slot and id — a session-bound
+identity is refused from any other) for the agent to run as its background task in the
+same turn. It never subscribes, spawns or writes settings. "Already running" is a fact: the
+daemon marks its pid under `~/.paigy/listen/<slot>.pid` while it runs. A session started by
+the Paigy harness (`paigy-harness host` / `run`) needs none of this — its pump types each
+answer in as it lands, and `listen` says so.
+
 `$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:
@@ -197,12 +212,23 @@ 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."
+codex exec "Paigy goal $PAIGY_GOAL_ID. claim_goal it first. The user said: $PAIGY_TEXT. Reply with contact when done."
+```
+
+## Stalled work (Claude Code stop hook)
 
-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."
+An agent that goes quiet leaves its Goals behind. Three things hand it that work back, all
+reading one rule (no progress for 3 days, `COLD_AFTER_MS`): `check_replies` lists it under
+`stalled`, `paigy-listen` carries it in `PAIGY_WORK` (and launches for it on boot), and this
+hook holds a Claude Code session's stop once a day to list it:
+
+```json
+{ "hooks": { "Stop": [{ "hooks": [{ "type": "command", "command": "npx -y -p @paigy/mcp paigy-stalled" }] }] } }
 ```
 
+It is silent when nothing is stalled, when the stop is already being continued by a hook, and
+after it has reminded that session once today.
+
 ## Statusline (Claude Code)
 
 `paigy-statusline` prints which Paigy identity this Claude Code session is, for the

package/dist/{chunk-FQVK7SO4.js → chunk-37FS33UP.js}

@@ -1,11 +1,13 @@
 import {
   AGENT_TOOLS,
   mcpInputSchema,
-  serverInstructions
-} from "./chunk-I5QINUN6.js";
+  serverInstructions,
+  sessionStartHook,
+  withSessionStartHook
+} from "./chunk-SE2JCKDI.js";
 import {
   agentName
-} from "./chunk-H5GGWCPS.js";
+} from "./chunk-PHTQITTC.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.";
@@ -44,6 +46,15 @@ var IDENTITY_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({}))
+  },
+  {
+    // A session asked to "start listening" can, in one call (#2265). Nothing can push an
+    // answer into a session started in a terminal — an answer waits for its next check_replies —
+    // and the only thing that reaches a running session mid-turn is a watched background task.
+    // So this tool decides and hands over: it never subscribes, spawns or writes settings.
+    name: "listen",
+    description: "Am I listening for answers, and if not, how do I start? Call it when the user asks you to start listening (or to stay reachable), and whenever you are unsure whether you are. Takes no arguments. Returns `status`: `listening` \u2014 nothing to do (a session started by the Paigy harness is ALWAYS listening: its pump types each answer in as it lands; or your own paigy-listen is already running, with its pid); `unpaired` \u2014 call onboard first; `start` \u2014 a `command` you MUST run NOW, in this same turn, as a watched BACKGROUND task (your harness's background-task/monitor tool), and leave running for the session. Each line that task prints is a Delivery waiting for you: claim_goal the Goal it names, read it, answer with contact. Start it once. This tool never subscribes or starts anything itself \u2014 the listener has to be YOUR watched task, or its lines reach no one.",
+    inputSchema: mcpInputSchema(z.object({}))
   }
 ];
 var TOOLS = [...AGENT_TOOLS, ...IDENTITY_TOOLS];
@@ -52,7 +63,7 @@ var HIDDEN_ALIASES = [];
 
 // src/clients.ts
 import { execFile } from "child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir, platform } from "os";
 import { join, dirname } from "path";
 function openBrowser(url) {
@@ -208,6 +219,45 @@ function enablePaigyTools(scope = "user", cwd = process.cwd()) {
     already: PAIGY_TOOL_IDS.filter((t) => prevAllow.includes(t))
   };
 }
+var HOOK_CONFIGS = [
+  { harness: "Claude Code", path: () => join(homedir(), ".claude", "settings.json") },
+  { harness: "Codex", path: () => join(homedir(), ".codex", "hooks.json") }
+];
+function installSessionListening() {
+  const script = join(homedir(), ".paigy", "hooks", "session-start.sh");
+  try {
+    mkdirSync(dirname(script), { recursive: true });
+    writeFileSync(script, sessionStartHook(), { mode: 493 });
+    chmodSync(script, 493);
+  } catch (e) {
+    return [{ harness: "all", path: script, ok: false, why: e.message }];
+  }
+  const out = [];
+  for (const { harness, path: at } of HOOK_CONFIGS) {
+    const path = at();
+    if (!existsSync(dirname(path))) continue;
+    let existing = null;
+    try {
+      existing = existsSync(path) ? readFileSync(path, "utf8") : null;
+    } catch (e) {
+      out.push({ harness, path, ok: false, why: e.message });
+      continue;
+    }
+    const already = existing?.includes(script) ?? false;
+    const updated = withSessionStartHook(existing, script);
+    if (updated === null) {
+      out.push({ harness, path, ok: false, why: `${path} didn't parse as JSON \u2014 not overwriting it` });
+      continue;
+    }
+    try {
+      writeFileSync(path, updated + "\n");
+      out.push({ harness, path, ok: true, already });
+    } catch (e) {
+      out.push({ harness, path, ok: false, why: e.message });
+    }
+  }
+  return out;
+}
 
 export {
   SERVER_INSTRUCTIONS,
@@ -220,5 +270,6 @@ export {
   ENABLE_COMMAND,
   PAIGY_TOOL_IDS,
   paigyToolsAllowlisted,
-  enablePaigyTools
+  enablePaigyTools,
+  installSessionListening
 };