@paigy/mcp 0.29.0 → 0.30.0

package/dist/{chunk-BJW6Z2OY.js → chunk-3QSGCROD.js}

@@ -1,8 +1,9 @@
 // ../../packages/sdk/dist/index.js
 import { createRequire as __sdkCreateRequire } from "module";
+import { randomUUID } from "crypto";
 import { z } from "zod";
 import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "fs";
-import { randomUUID } from "crypto";
+import { randomUUID as randomUUID2 } from "crypto";
 import { homedir } from "os";
 import { join } from "path";
 var require2 = __sdkCreateRequire(import.meta.url);
@@ -2268,9 +2269,16 @@ async function proxy() {
   if (!PROXY_ENV.some((k) => process.env[k])) return void 0;
   return agent ??= new (await import("undici")).EnvHttpProxyAgent();
 }
+var INSTANCE_ID = randomUUID();
+var SESSION_ID = process.env.PAIGY_SESSION_ID ?? process.env.CLAUDE_CODE_SESSION_ID ?? INSTANCE_ID;
 async function reach(url, init) {
   try {
-    return await fetch(url, { ...init, dispatcher: await proxy() });
+    const headers = {
+      ...init?.headers,
+      "x-paigy-instance": INSTANCE_ID,
+      "x-paigy-session": SESSION_ID
+    };
+    return await fetch(url, { ...init, headers, dispatcher: await proxy() });
   } catch (e) {
     throw new Error(`${NETWORK_MSG} (${e?.message ?? String(e)})`);
   }
@@ -2333,7 +2341,9 @@ function lintNotify(req) {
 }
 var ContextSchema = z.object({
   title: z.string().min(1).describe("One-line headline of what you need (required, non-empty)."),
-  description: z.array(z.string().min(1)).min(1).describe("Semantic chunks of detail (each a standalone, non-empty piece). The user can select chunks to ask you to expand.")
+  description: z.array(z.string().min(1)).describe(
+    "Semantic chunks of detail (each a standalone, non-empty piece). The user can select chunks to ask you to expand. MAY BE EMPTY: a claim whose whole content is its heading \u2014 a single sentence \u2014 has no body, and saying so beats repeating the heading underneath itself. That repeat is what `min(1)` used to force, at 2x the storage, with every reader subtracting it back out at render time."
+  )
 });
 var ParticipantSchema = z.object({
   kind: z.enum(["human", "agent"]),
@@ -2538,35 +2548,45 @@ 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);
+function unitsOf(text) {
+  const spans = [];
+  const re = /\n\s*\n+/g;
+  let cursor = 0;
+  const push = (from, to) => {
+    const slice = text.slice(from, to);
+    const lead = slice.length - slice.trimStart().length;
+    const tail = slice.length - slice.trimEnd().length;
+    if (from + lead < to - tail) spans.push({ start: from + lead, end: to - tail });
+  };
+  for (let m = re.exec(text); m; m = re.exec(text)) {
+    push(cursor, m.index);
+    cursor = m.index + m[0].length;
   }
-  if (chunks.length <= cap) return chunks;
-  return [...chunks.slice(0, cap - 1), chunks.slice(cap - 1).join(" ")];
+  push(cursor, text.length);
+  return spans;
+}
+function headline(text) {
+  const line = text.split("\n").map((l) => l.trim()).filter((l) => l && !/^`{3,}/.test(l)).map((l) => l.replace(/^(?:#{1,6}|[-*>]|\d{1,3}\.)\s+/, "")).find(Boolean) ?? "";
+  return (/^[^.!?\n]+[.!?]?/.exec(line)?.[0] ?? line).trim();
+}
+function bodyAfterHeadline(text) {
+  const body = text.trim();
+  const title = headline(body);
+  const rest = body.slice(title.length).replace(/^[\s.!?—–-]+/, "").trim();
+  if (!rest) return { title, description: [] };
+  const chunks = unitsOf(rest).map((u) => rest.slice(u.start, u.end)).filter(Boolean);
+  return { title, description: chunks.length ? chunks : [rest] };
 }
 function deriveAsk(req) {
   req = normalizeWaiting(req);
   if (!req.ask) return req;
   const text = req.ask.trim();
-  const firstSentence = (/^[^.!?\n]+[.!?]?/.exec(text)?.[0] ?? text).trim();
-  const title = firstSentence.length > 90 ? `${firstSentence.slice(0, 87).trimEnd()}\u2026` : firstSentence;
   const hinted = req.urgencyHint === "now" ? "call" : req.urgencyHint === "soon" ? "banner" : req.urgencyHint === "whenever" ? "inbox" : req.urgency;
   const urgency = req.channel === "call" ? "call" : req.channel === "message" && hinted === "call" ? "banner" : hinted;
   const { ask: _ask, needs, urgencyHint: _hint, channel: _channel, ...rest } = req;
   return {
     ...rest,
-    context: { title, description: chunkAsk(text) },
+    context: bodyAfterHeadline(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",
@@ -2820,6 +2840,11 @@ var InboxItemSchema = z.object({
    *  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. */
+  /** Does this claim want an ANSWER, or is it telling you something? Written per row from
+   *  `requestAsks` — the agent's own declaration, not a guess. `false` is what earns a card
+   *  its acknowledge affordance: without it a status update offers a text box and a dismiss,
+   *  and neither of those is "got it" (owner, 2026-08-10). */
+  asks: z.boolean().optional(),
   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. */
@@ -2844,6 +2869,23 @@ var InboxItemSchema = z.object({
    *  client may still flag a stall by age. Drives the inbox error badge + Retry. */
   error: z.string().optional(),
   clarifies: z.string().optional(),
+  /** The ring ladder ran out while this was still pending — we tried to reach you and
+   *  STOPPED trying (`arbitration/arbitrate.ts` `nextRing` → `stop`). Distinct from an
+   *  agent with nothing to say, which the roster drew identically until now: "nothing to
+   *  say" and "gave up saying it" are opposite situations wearing the same face
+   *  (navigation-design.md, gap 1). False for anything that never rang. */
+  gaveUp: z.boolean().default(false),
+  /** Why this arrived the way it did, read back off the delivery receipt (`notify/why.ts`).
+   *  Absent for anything never delivered through a push, and for older rows written before
+   *  the reason was recorded. Deliberately a debug affordance, shown small (owner,
+   *  2026-08-07) — its real job is to give "this didn't need a call" something to be
+   *  feedback ABOUT. */
+  why: z.object({
+    asked: NotifyLevelSchema,
+    got: NotifyLevelSchema,
+    because: z.enum(["unresponsive", "dismissed", "not_permitted", "silent", "coalesced", "agent_capped", "unplanned"]).optional(),
+    line: z.string()
+  }).optional(),
   select: z.enum(["one", "many", "rank", "confirm", "text"]).default("one"),
   confirmStyle: z.enum(["yesno", "approve"]).default("yesno").describe(
     "Labels for a select:'confirm' paige \u2014 'yesno' (Yes/No) or 'approve' (Approve/Deny). Ignored unless select is 'confirm'."
@@ -2965,6 +3007,14 @@ var ConnectionSummarySchema = z.object({
   provider: z.string().nullable(),
   /** The pairing's assigned voice (#462); null = the default voice. */
   voice: VoiceKeySchema.nullable(),
+  /** The LOUDEST this agent may ever reach you — a ceiling on `NOTIFY_LADDER`, set by the
+   *  user on the agent's own page. null = no ceiling (today's behaviour for every
+   *  connection). Android binds importance to a relationship rather than to each message,
+   *  and that is the thing our roster could not say: "Marlow may always call me; Otto
+   *  never may" (navigation-design.md, gap 2). Clamped in `arbitrateLevel`, so it binds
+   *  every surface at once and outranks even `sessionMode: all_calls` — a mode the user
+   *  set once must not overrule a rule they set about one agent. */
+  reach: NotifyLevelSchema.nullable().optional(),
   createdAt: z.string().datetime(),
   /** Most recent notification on this connection, either direction. Null = no contact yet.
    *  Drives the agents-page recency grouping (Today / This week / …). */
@@ -2983,6 +3033,40 @@ var ConnectionSummarySchema = z.object({
    *  false = a local MCP connection running on the user's computer (Claude Code/Codex/…). */
   managed: z.boolean()
 });
+var MoveRingSchema = z.enum(["home", "travels", "retired", "quarantined"]);
+var MoveSchema = z.object({
+  id: z.string(),
+  /** The reusable question, as distill normalized it. */
+  question: z.string(),
+  /** The operative ruling. Editable by the user (PATCH) — which resets the ledger. */
+  answer: z.string(),
+  /** The user's stated reason, when they gave one. Null = inherently narrow: the judge is
+   *  told so, and the ruling only derives essentially the same question in the same scope. */
+  rationale: z.string().nullable(),
+  /** Where the ruling lives: a repo/workspace, or 'global'. */
+  scope: z.string(),
+  ring: MoveRingSchema,
+  /** True = the user pinned it with `always` (travel granted by hand, not by evidence). */
+  pinned: z.boolean(),
+  /** True = a pin the user placed was BROKEN by later counter-evidence. Surfaced so the
+   *  break is visible instead of a pin silently disappearing. */
+  pinBroken: z.boolean(),
+  /** When the ruling was distilled. */
+  learnedAt: z.string(),
+  /** Last time it answered an ask. Null = never fired. */
+  lastUsedAt: z.string().nullable(),
+  /** How many asks it has answered. Instrumentation — deliberately NOT an input to the
+   *  evidence curve: firing says the question keeps arising, not that the ruling is right. */
+  usedCount: z.number(),
+  /** Ledger: outcomes that said it held up. Saturating — the tenth is worth almost nothing. */
+  confirms: z.number(),
+  /** Ledger: contradictions, in signal units (a full override = 1, weaker signals less).
+   *  Linear and priced above the entire confirmation budget, so any full counter wins. */
+  counters: z.number(),
+  /** The agent that asked the question this move came from, when known. Null for a move
+   *  distilled from a clarify ruling (those carry no agent) or one whose source rows are gone. */
+  learnedFrom: z.object({ id: z.string(), name: z.string() }).nullable()
+});
 var CreateRequestSchema = z.object({
   /** The connection (token id) to send to, from GET /api/tokens. */
   tokenId: z.string(),
@@ -3189,6 +3273,12 @@ var DeviceTokenSchema = z.object({
    *  a default silly name). */
   name: z.string(),
   device: z.string().nullable(),
+  /** The pairing's assigned voice, cached so the desktop can seed the SAME face the phone
+   *  draws — voice is the third ingredient of a hatchling's build (party/traits.ts). */
+  voice: z.string().nullable().optional(),
+  /** The token's server-side id — the face's COLOUR anchor, and the only seed ingredient
+   *  that survives a rename. Cached by the host's identity beat. */
+  token_id: z.string().nullable().optional(),
   phone_reveal: PairingRevealSchema.nullable().optional(),
   // present once the phone reveals
   uik_pub: z.string().nullable().optional()
@@ -3215,6 +3305,8 @@ var NotificationFeedbackKindSchema = z.enum([
   // "There should be a picture or design here."
   "should_have_called",
   // "Don't put this in a banner — ring me for something like this."
+  "should_have_messaged",
+  // the inverse: "that didn't deserve a ring — a message would do."
   "other"
   // anything else — the note carries it.
 ]);
@@ -3557,7 +3649,7 @@ function verifyPairingCommit(commitment, proto, role, x25519Pub, ed25519Pub, non
   }
 }
 function sessionSlot(sessionId) {
-  const id = sessionId ?? process.env.PAIGY_SESSION_ID ?? process.env.CLAUDE_CODE_SESSION_ID ?? randomUUID();
+  const id = sessionId ?? process.env.PAIGY_SESSION_ID ?? process.env.CLAUDE_CODE_SESSION_ID ?? randomUUID2();
   return `session:${id.slice(0, 8)}`;
 }
 var AGENT_NAME = process.env.PAIGY_AGENT || sessionSlot();
@@ -3956,6 +4048,25 @@ async function hatch(name, voice = null) {
   if (!res.ok) throw new Error(`hatch failed: ${res.status} ${await res.text()}`);
   return await res.json();
 }
+async function whoAmI(opts = {}) {
+  try {
+    const res = await reach(`${BACKEND_URL}/api/identity`, {
+      headers: { authorization: `Bearer ${authToken(opts.token)}` }
+    });
+    return res.ok ? await res.json() : null;
+  } catch {
+    return null;
+  }
+}
+async function setIdentity(patch, opts = {}) {
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/identity`, {
+    method: "PATCH",
+    headers: { "content-type": "application/json", authorization: `Bearer ${authToken(opts.token)}` },
+    body: JSON.stringify(patch)
+  }));
+  if (!res.ok) throw new Error(`set_identity failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
 async function setTaskState(notificationId, state, opts = {}) {
   const res = ensureAuthed(await reach(`${BACKEND_URL}/api/notify/${notificationId}/state`, {
     method: "PATCH",
@@ -4030,6 +4141,8 @@ export {
   answerCallerQuestion,
   overrideToken,
   hatch,
+  whoAmI,
+  setIdentity,
   setTaskState,
   registerDelivery,
   scheduleCallback,

package/dist/{chunk-JG2XL7Y3.js → chunk-57N3NFYG.js}

@@ -1,6 +1,6 @@
 import {
   AGENT_NAME
-} from "./chunk-BJW6Z2OY.js";
+} from "./chunk-3QSGCROD.js";
 
 // src/clients.ts
 import { execFile } from "child_process";
@@ -112,6 +112,20 @@ function withPaigyAllowlist(existing, tools) {
   config.permissions = { ...permissions, allow };
   return JSON.stringify(config, null, 2);
 }
+function settingsPathFor(scope, cwd) {
+  return scope === "project" ? join(cwd, ".claude", "settings.json") : join(homedir(), ".claude", "settings.json");
+}
+function paigyToolsAllowlisted(scope = "user", cwd = process.cwd()) {
+  try {
+    const path = settingsPathFor(scope, cwd);
+    if (!path || !existsSync(path)) return false;
+    const config = JSON.parse(readFileSync(path, "utf8"));
+    const allow = Array.isArray(config.permissions?.allow) ? config.permissions.allow : [];
+    return PAIGY_TOOL_IDS.every((t) => allow.includes(t));
+  } catch {
+    return false;
+  }
+}
 function enablePaigyTools(scope = "user", cwd = process.cwd()) {
   if (scope === "user" && !existsSync(join(homedir(), ".claude"))) {
     return {
@@ -119,7 +133,7 @@ function enablePaigyTools(scope = "user", cwd = process.cwd()) {
       reason: `No ~/.claude on this machine \u2014 the hosting tool uses its own permission allowlist. Add these ids there by hand: ${PAIGY_TOOL_IDS.join(", ")}.`
     };
   }
-  const path = scope === "project" ? join(cwd, ".claude", "settings.json") : join(homedir(), ".claude", "settings.json");
+  const path = settingsPathFor(scope, cwd);
   let existing = null;
   try {
     existing = existsSync(path) ? readFileSync(path, "utf8") : null;
@@ -156,5 +170,6 @@ export {
   autoConfigureClients,
   claudeInstallHint,
   PAIGY_TOOL_IDS,
+  paigyToolsAllowlisted,
   enablePaigyTools
 };

package/dist/{chunk-ZFBYZWK7.js → chunk-KMPAFUT6.js}

@@ -2,7 +2,9 @@
 import { z } from "zod";
 var ContextSchema = z.object({
   title: z.string().min(1).describe("One-line headline of what you need (required, non-empty)."),
-  description: z.array(z.string().min(1)).min(1).describe("Semantic chunks of detail (each a standalone, non-empty piece). The user can select chunks to ask you to expand.")
+  description: z.array(z.string().min(1)).describe(
+    "Semantic chunks of detail (each a standalone, non-empty piece). The user can select chunks to ask you to expand. MAY BE EMPTY: a claim whose whole content is its heading \u2014 a single sentence \u2014 has no body, and saying so beats repeating the heading underneath itself. That repeat is what `min(1)` used to force, at 2x the storage, with every reader subtracting it back out at render time."
+  )
 });
 var ParticipantSchema = z.object({
   kind: z.enum(["human", "agent"]),
@@ -444,6 +446,11 @@ var InboxItemSchema = z.object({
    *  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. */
+  /** Does this claim want an ANSWER, or is it telling you something? Written per row from
+   *  `requestAsks` — the agent's own declaration, not a guess. `false` is what earns a card
+   *  its acknowledge affordance: without it a status update offers a text box and a dismiss,
+   *  and neither of those is "got it" (owner, 2026-08-10). */
+  asks: z.boolean().optional(),
   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. */
@@ -468,6 +475,23 @@ var InboxItemSchema = z.object({
    *  client may still flag a stall by age. Drives the inbox error badge + Retry. */
   error: z.string().optional(),
   clarifies: z.string().optional(),
+  /** The ring ladder ran out while this was still pending — we tried to reach you and
+   *  STOPPED trying (`arbitration/arbitrate.ts` `nextRing` → `stop`). Distinct from an
+   *  agent with nothing to say, which the roster drew identically until now: "nothing to
+   *  say" and "gave up saying it" are opposite situations wearing the same face
+   *  (navigation-design.md, gap 1). False for anything that never rang. */
+  gaveUp: z.boolean().default(false),
+  /** Why this arrived the way it did, read back off the delivery receipt (`notify/why.ts`).
+   *  Absent for anything never delivered through a push, and for older rows written before
+   *  the reason was recorded. Deliberately a debug affordance, shown small (owner,
+   *  2026-08-07) — its real job is to give "this didn't need a call" something to be
+   *  feedback ABOUT. */
+  why: z.object({
+    asked: NotifyLevelSchema,
+    got: NotifyLevelSchema,
+    because: z.enum(["unresponsive", "dismissed", "not_permitted", "silent", "coalesced", "agent_capped", "unplanned"]).optional(),
+    line: z.string()
+  }).optional(),
   select: z.enum(["one", "many", "rank", "confirm", "text"]).default("one"),
   confirmStyle: z.enum(["yesno", "approve"]).default("yesno").describe(
     "Labels for a select:'confirm' paige \u2014 'yesno' (Yes/No) or 'approve' (Approve/Deny). Ignored unless select is 'confirm'."
@@ -589,6 +613,14 @@ var ConnectionSummarySchema = z.object({
   provider: z.string().nullable(),
   /** The pairing's assigned voice (#462); null = the default voice. */
   voice: VoiceKeySchema.nullable(),
+  /** The LOUDEST this agent may ever reach you — a ceiling on `NOTIFY_LADDER`, set by the
+   *  user on the agent's own page. null = no ceiling (today's behaviour for every
+   *  connection). Android binds importance to a relationship rather than to each message,
+   *  and that is the thing our roster could not say: "Marlow may always call me; Otto
+   *  never may" (navigation-design.md, gap 2). Clamped in `arbitrateLevel`, so it binds
+   *  every surface at once and outranks even `sessionMode: all_calls` — a mode the user
+   *  set once must not overrule a rule they set about one agent. */
+  reach: NotifyLevelSchema.nullable().optional(),
   createdAt: z.string().datetime(),
   /** Most recent notification on this connection, either direction. Null = no contact yet.
    *  Drives the agents-page recency grouping (Today / This week / …). */
@@ -607,6 +639,40 @@ var ConnectionSummarySchema = z.object({
    *  false = a local MCP connection running on the user's computer (Claude Code/Codex/…). */
   managed: z.boolean()
 });
+var MoveRingSchema = z.enum(["home", "travels", "retired", "quarantined"]);
+var MoveSchema = z.object({
+  id: z.string(),
+  /** The reusable question, as distill normalized it. */
+  question: z.string(),
+  /** The operative ruling. Editable by the user (PATCH) — which resets the ledger. */
+  answer: z.string(),
+  /** The user's stated reason, when they gave one. Null = inherently narrow: the judge is
+   *  told so, and the ruling only derives essentially the same question in the same scope. */
+  rationale: z.string().nullable(),
+  /** Where the ruling lives: a repo/workspace, or 'global'. */
+  scope: z.string(),
+  ring: MoveRingSchema,
+  /** True = the user pinned it with `always` (travel granted by hand, not by evidence). */
+  pinned: z.boolean(),
+  /** True = a pin the user placed was BROKEN by later counter-evidence. Surfaced so the
+   *  break is visible instead of a pin silently disappearing. */
+  pinBroken: z.boolean(),
+  /** When the ruling was distilled. */
+  learnedAt: z.string(),
+  /** Last time it answered an ask. Null = never fired. */
+  lastUsedAt: z.string().nullable(),
+  /** How many asks it has answered. Instrumentation — deliberately NOT an input to the
+   *  evidence curve: firing says the question keeps arising, not that the ruling is right. */
+  usedCount: z.number(),
+  /** Ledger: outcomes that said it held up. Saturating — the tenth is worth almost nothing. */
+  confirms: z.number(),
+  /** Ledger: contradictions, in signal units (a full override = 1, weaker signals less).
+   *  Linear and priced above the entire confirmation budget, so any full counter wins. */
+  counters: z.number(),
+  /** The agent that asked the question this move came from, when known. Null for a move
+   *  distilled from a clarify ruling (those carry no agent) or one whose source rows are gone. */
+  learnedFrom: z.object({ id: z.string(), name: z.string() }).nullable()
+});
 var CreateRequestSchema = z.object({
   /** The connection (token id) to send to, from GET /api/tokens. */
   tokenId: z.string(),
@@ -815,6 +881,12 @@ var DeviceTokenSchema = z.object({
    *  a default silly name). */
   name: z.string(),
   device: z.string().nullable(),
+  /** The pairing's assigned voice, cached so the desktop can seed the SAME face the phone
+   *  draws — voice is the third ingredient of a hatchling's build (party/traits.ts). */
+  voice: z.string().nullable().optional(),
+  /** The token's server-side id — the face's COLOUR anchor, and the only seed ingredient
+   *  that survives a rename. Cached by the host's identity beat. */
+  token_id: z.string().nullable().optional(),
   phone_reveal: PairingRevealSchema.nullable().optional(),
   // present once the phone reveals
   uik_pub: z.string().nullable().optional()
@@ -841,6 +913,8 @@ var NotificationFeedbackKindSchema = z.enum([
   // "There should be a picture or design here."
   "should_have_called",
   // "Don't put this in a banner — ring me for something like this."
+  "should_have_messaged",
+  // the inverse: "that didn't deserve a ring — a message would do."
   "other"
   // anything else — the note carries it.
 ]);

package/dist/index.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 import {
   HandoffSchema
-} from "./chunk-ZFBYZWK7.js";
+} from "./chunk-KMPAFUT6.js";
 import {
   PAIGY_TOOL_IDS,
   autoConfigureClients,
   claudeInstallHint,
-  enablePaigyTools
-} from "./chunk-JG2XL7Y3.js";
+  enablePaigyTools,
+  paigyToolsAllowlisted
+} from "./chunk-57N3NFYG.js";
 import {
   clearSurface,
   writeSurface
@@ -41,12 +42,14 @@ import {
   saveToken,
   scheduleCallback,
   searchThreads,
+  setIdentity,
   setTaskState,
   sleep,
   slotName,
   startE2ee,
-  submitNotification
-} from "./chunk-BJW6Z2OY.js";
+  submitNotification,
+  whoAmI
+} from "./chunk-3QSGCROD.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -90,7 +93,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 \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)."
+      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). Contact at exactly two moments: BLOCKED on a decision only they can make, or DONE (one short report \u2014 what shipped, how you verified it, what you flagged). Progress is never a contact: set_task_state carries it, and working narration stays in your own terminal \u2014 the user sees you're working without being interrupted by it."
     },
     waiting: {
       type: "string",
@@ -126,6 +129,7 @@ var CONTACT_SCHEMA = {
   required: ["ask"]
 };
 var CONTACT_DESCRIPTION = "Reach the user through Paigy \u2014 tell them something, or ask and get their answer. State what you need in `ask`, say what happens to your work while you wait in `waiting`, and Paigy handles the rest (channel, phrasing, answer format). If the user explicitly asks you to CALL them, send waiting:'hard' and say so in the ask. Returns { notificationId, parentId } \u2014 pass notificationId to await_reply for the answer, parentId to a later contact to continue the conversation. THREADING REPLACES: a threaded follow-up SUPERSEDES your earlier pending items on that thread \u2014 right for updates to one ask, WRONG for a checklist (send independent to-dos un-threaded). A threaded re-send with IDENTICAL content escalates the pending ask in place. If a reply comes back as {kind:'clarify', chunks:[...]}, the user wants more detail \u2014 contact again on the SAME parentId with an expanded ask. ONE ASK, ONE ROW: never restate a still-pending ask's question inside a NEW contact (e.g. weaving it into a briefing) \u2014 the whole answer settles on the new row and the original can never receive it. Keep waiting on the original (a live call reads every pending ask out separately, each answer routes to its own row), and use `needs` for a genuinely multi-part NEW ask.";
+var ONBOARD_DESCRIPTION = "Get this agent talking to Paigy \u2014 call it FIRST, before contact/await_reply, 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_prompt`, ask the user that question and call `enable_tools` on yes.";
 
 // src/pairing.ts
 async function resolvePairing(deviceCode, capMs, pollMs = 2e3) {
@@ -233,6 +237,14 @@ var AwaitReplySchema = z.object({
   )
 });
 var JOIN_CAP_MS = 45e3;
+var OnboardSchema = z.object({
+  name: z.string().max(60).optional(),
+  voice: z.string().max(40).optional(),
+  /** Continue a code ceremony already in flight — same meaning as `pair`'s. */
+  device_code: z.string().optional(),
+  /** Which allowlist to REPORT on (never written by `start`). */
+  scope: z.enum(["user", "project"]).optional()
+});
 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."),
   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."),
@@ -378,6 +390,35 @@ var server = new Server(
     instructions: "On startup, call check_replies once to pick up any replies or pending work you missed while away. A check_replies request whose parentId you don't recognize, or one carrying a contextParentId, means the user is resuming or seeding a past conversation \u2014 call get_thread on it FIRST and treat the transcript as prior conversation, not new input. To wait for the answer to something you just asked, call await_reply with that notificationId \u2014 it's scoped to that one notification, so it never returns replies meant for other notifications. Use check_replies again only when re-booting or after waiting a long time on something else. Never end a turn that still needs the user without contact + await_reply. When you need a decision or input, MATCH the answer shape to the question \u2014 don't default everything to free text, and don't reflexively make everything yes/no. Pick the best tool for the job: yes/no \u2192 select:'confirm'; approve/deny an action \u2192 select:'confirm' + confirmStyle:'approve'; pick one of several \u2192 options + select:'one'; pick several / a subset \u2192 options + select:'many'; rank or prioritize \u2192 options + select:'rank'. Reserve select:'text' (free-form reply only) for plain updates and answers that genuinely can't be structured (the user can always add free text on top of any shape). On a { kind: 'clarify' } reply, see contact's own description for how to respond. When you send waiting:'hard' (or the user asked you to call), remember the ask may be spoken aloud \u2014 write it short and conversational, and name things instead of using IDs (e.g. 'the pull request about the agents page', not 'PR #235'). When the user asks you to follow up later \u2014 when you're done, if you're blocked, or at a set time \u2014 record it with schedule_callback so you don't drop it if you go idle. If you're about to start a genuinely long-running or blocking piece of work \u2014 one where the user would otherwise sit and wait \u2014 mention ONCE, in passing, that you can reach them when it's done or if you hit a blocker, instead of them needing to babysit the terminal. Don't offer this for quick tasks, and don't repeat the offer if they've already said yes or no earlier in the conversation. NEVER go quietly idle while something might still be pending for you: whenever you end a turn with any Paigy notification unanswered (or any chance the user replied through the app while you worked), schedule your own ~2-minute wake-up (harness ScheduleWakeup or equivalent) and call check_replies when it fires; if still nothing, re-schedule and keep looping until resolved or the user says stop. For legibility, always use this exact wording \u2014 reason: 'Paigy idle check \u2014 waiting on <thing>', wake-up prompt: 'Paigy idle check: call check_replies and engage with anything unacknowledged; if idle, re-schedule (~2min).' \u2014 so the user can recognize every idle check at a glance. This self-polling in your own live session (full context intact) is the PRIMARY mechanism; the plugin's Stop hooks are only the dead-session safety net."
   }
 );
+function prependNote(result, note) {
+  return { content: [{ type: "text", text: note }, ...result.content] };
+}
+async function runPair(device_code, name, voice, note) {
+  if (!device_code && listSlots().includes("Desktop")) {
+    const device = readToken("Desktop");
+    overrideToken(device);
+    try {
+      const minted = await hatch(name ?? suggestedAgentName() ?? "Agent", voice ?? null);
+      const dt = { ok: true, access_token: minted.token, name: minted.name, device: null };
+      saveToken(dt);
+      return pairedResult(
+        dt,
+        void 0,
+        "Hatched instantly under this device's credential \u2014 no code needed. " + (name ? "" : "You were given a default name \u2014 choose your own name and voice and update them via the identity tools or by re-calling pair with { name, voice }.")
+      );
+    } catch {
+    } finally {
+      overrideToken(null);
+    }
+  }
+  if (!device_code) {
+    const started2 = pairStartResult(await startPairing(suggestedAgentName()));
+    return note ? prependNote(started2, note) : started2;
+  }
+  const capMs = JOIN_CAP_MS;
+  const outcome = await joinBackgroundPair(device_code, capMs) ?? await resolvePairing(device_code, capMs);
+  return renderPairOutcome(outcome, device_code);
+}
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   const tools = [
     {
@@ -388,6 +429,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       description: CONTACT_DESCRIPTION,
       inputSchema: CONTACT_SCHEMA
     },
+    {
+      // 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
+      // reached for attached to the tool that did the least. It's the door now.
+      name: "onboard",
+      description: ONBOARD_DESCRIPTION,
+      inputSchema: json(OnboardSchema)
+    },
     {
       name: "pair",
       description: "Pair this agent with the user's Paigy account (one-time) \u2014 required before contact/await_reply work. FAST PATH: if this machine already holds a device credential (the user ran the Paigy desktop harness or app), calling pair hatches a fresh identity INSTANTLY \u2014 no code, no approval. Pass { name, voice } to choose who you are (pick your own; voices: rachel, george, jessica, brian, lily). Only when no device credential exists does the code ceremony below run. It does NOT open a browser; the user enters the code in the Paigy app (or scans `qr`). Step 1: call with NO args \u2014 returns { user_code, device_code, qr, user_message } AND starts polling for approval in the background. REQUIRED: You MUST immediately print the `user_message` (the bare code) as a text message to the user, AND in that same turn call step 2 (pair with the device_code). This ensures the user sees the code in chat while the tool blocks/polls in the background for approval. Step 2: call with that device_code to collect the result. Because approval is already being polled in the background, this returns the moment the user approves; on { status:'pending' } just call again to keep waiting; on { status:'awaiting_confirmation' } (E2EE) show the bare `user_message` verify code and call again to finish. The leading text block of every result states the code plainly, so it shows even if you emit no prose. On { status:'paired' } ALWAYS follow the `enable_prompt` \u2014 ask the user to allowlist Paigy's tools so notify/await don't prompt each time.",
@@ -479,30 +528,64 @@ function suggestedAgentName() {
 async function handleTool(request, signal) {
   switch (request.params.name) {
     case "pair": {
-      const { device_code, name, voice } = PairSchema.parse(request.params.arguments ?? {});
-      if (!device_code && listSlots().includes("Desktop")) {
-        const device = readToken("Desktop");
-        overrideToken(device);
-        try {
-          const minted = await hatch(name ?? suggestedAgentName() ?? "Agent", voice ?? null);
-          const dt = { ok: true, access_token: minted.token, name: minted.name, device: null };
-          saveToken(dt);
-          return pairedResult(
-            dt,
-            void 0,
-            "Hatched instantly under this device's credential \u2014 no code needed. " + (name ? "" : "You were given a default name \u2014 choose your own name and voice and update them via the identity tools or by re-calling pair with { name, voice }.")
-          );
-        } catch {
-        } finally {
-          overrideToken(null);
+      const a = PairSchema.parse(request.params.arguments ?? {});
+      return runPair(a.device_code, a.name, a.voice);
+    }
+    // ONE rail for "get this agent talking to Paigy" (#875). `pair`, the `paigy-mcp-onboard`
+    // CLI and `enable_tools` were three doors into one flow, each knowing a different slice
+    // of the state — so "onboard" was the word people reached for and the tool that did the
+    // least, and a half-configured agent (paired but not allowlisted, or holding a token for
+    // a slot it can no longer resolve) had nothing to ask.
+    //
+    // It reports state and does the next thing, and it is IDEMPOTENT: calling it when
+    // everything is fine costs one round trip and returns who you are. Reporting never
+    // mutates — the allowlist check is read-only on purpose, because a status call that
+    // quietly edits the user's settings is the opposite of what this is for.
+    // `start` stays accepted, unlisted — it shipped under that name for one afternoon.
+    case "start":
+    case "onboard": {
+      const { name, voice, device_code, scope } = OnboardSchema.parse(request.params.arguments ?? {});
+      if (device_code) return runPair(device_code, name, voice);
+      const slot = AGENT_NAME;
+      const secret = readToken();
+      if (secret) {
+        let who = await whoAmI().catch(() => null);
+        if (who) {
+          let renamed = false;
+          if (name || voice) {
+            try {
+              who = await setIdentity({ ...name ? { name } : {}, ...voice ? { voice } : {} });
+              renamed = true;
+            } catch {
+            }
+          }
+          const allowlisted = paigyToolsAllowlisted(scope ?? "user");
+          const display = who?.name ?? slotName(slot) ?? slot;
+          return {
+            content: [{ type: "text", text: JSON.stringify({
+              status: "ready",
+              slot,
+              name: display,
+              voice: who?.voice ?? null,
+              tools_allowlisted: allowlisted,
+              ...allowlisted ? {} : {
+                enable_tool_ids: PAIGY_TOOL_IDS,
+                enable_prompt: "Ask the user: \"Want me to let Paigy's tools run without an approval prompt each time? I'll only allowlist the notify/await tools \u2014 pair and unpair still ask.\" On yes, call `enable_tools`."
+              },
+              // Setup is done, so the only things left are the user's to decide. Named here
+              // rather than left implicit: an agent that reports "ready" and stops gives the
+              // user no way to act on an identity they may not want.
+              actions: {
+                rename: "Call onboard again with { name } (and optionally { voice }) to change it.",
+                unpair: "Call the `unpair` tool to disconnect this agent from the account."
+              },
+              message: renamed ? `Renamed \u2014 this agent is "${display}" now.` : `Already set up as "${display}". Ask the user if they want to rename it or unpair; otherwise carry on.`
+            }) }]
+          };
         }
+        return runPair(void 0, name, voice, "The token in this session's slot is no longer valid \u2014 re-pairing.");
       }
-      if (!device_code) {
-        return pairStartResult(await startPairing(suggestedAgentName()));
-      }
-      const capMs = JOIN_CAP_MS;
-      const outcome = await joinBackgroundPair(device_code, capMs) ?? await resolvePairing(device_code, capMs);
-      return renderPairOutcome(outcome, device_code);
+      return runPair(void 0, name, voice);
     }
     case "unpair": {
       const token = readToken();

package/dist/listen.js

@@ -2,11 +2,11 @@
 import {
   WAKE_EVENT,
   wakeChannel
-} from "./chunk-ZFBYZWK7.js";
+} from "./chunk-KMPAFUT6.js";
 import {
   checkReplies,
   registerDelivery
-} from "./chunk-BJW6Z2OY.js";
+} from "./chunk-3QSGCROD.js";
 
 // src/listen.ts
 import { createClient } from "@supabase/supabase-js";

package/dist/onboard.js

@@ -3,21 +3,73 @@ import {
   autoConfigureClients,
   claudeInstallHint,
   openBrowser
-} from "./chunk-JG2XL7Y3.js";
+} from "./chunk-57N3NFYG.js";
 import {
   AGENT_NAME,
   TOKEN_PATH,
+  hatch,
+  listSlots,
+  overrideToken,
   pollToken,
+  readToken,
   requestCode,
   saveToken,
-  sleep
-} from "./chunk-BJW6Z2OY.js";
+  setIdentity,
+  sleep,
+  whoAmI
+} from "./chunk-3QSGCROD.js";
 
 // src/onboard.ts
 async function main() {
   console.log(`
 Paigy MCP onboarding (agent: "${AGENT_NAME}")
 `);
+  if (readToken()) {
+    let who = await whoAmI().catch(() => null);
+    if (who) {
+      const wanted = process.env.PAIGY_NAME;
+      const wantedVoice = process.env.PAIGY_VOICE;
+      if (wanted || wantedVoice) {
+        try {
+          who = await setIdentity({ ...wanted ? { name: wanted } : {}, ...wantedVoice ? { voice: wantedVoice } : {} });
+          console.log(`Renamed \u2014 this agent is "${who.name}"${who.voice ? ` (voice: ${who.voice})` : ""} now.
+`);
+          return;
+        } catch (err) {
+          console.log(`Couldn't rename it: ${err.message}
+`);
+        }
+      }
+      console.log(`Already set up as "${who.name}"${who.voice ? ` (voice: ${who.voice})` : ""}.
+`);
+      console.log("Nothing to do. What's left is yours to decide:");
+      console.log('  rename  \u2014 PAIGY_NAME="New name" paigy-mcp-onboard  (or the `onboard` MCP tool)');
+      console.log("  unpair  \u2014 the MCP `unpair` tool, or delete this slot from ~/.paigy/token.json\n");
+      return;
+    }
+    console.log("The saved token is no longer valid \u2014 re-pairing.\n");
+  }
+  if (listSlots().includes("Desktop")) {
+    overrideToken(readToken("Desktop"));
+    try {
+      const minted = await hatch(process.env.PAIGY_NAME ?? "Agent", null);
+      saveToken({ ok: true, access_token: minted.token, name: minted.name, device: null });
+      console.log(`Hatched instantly under this machine's credential \u2014 no code needed.`);
+      console.log(`  Name   : ${minted.name}
+`);
+      const auto = autoConfigureClients();
+      if (auto.length) {
+        console.log("Also registered the Paigy MCP server in:");
+        for (const r of auto) console.log(`  - ${r}`);
+        console.log("(Restart those tools to pick it up.)\n");
+      }
+      return;
+    } catch {
+      console.log("(This machine's saved credential didn't work \u2014 falling back to a code.)\n");
+    } finally {
+      overrideToken(null);
+    }
+  }
   const code = await requestCode();
   console.log("Open this URL in your browser to approve the connection:\n");
   console.log(`  ${code.verification_uri_complete}

package/dist/statusline.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paigy/mcp",
-  "version": "0.29.0",
+  "version": "0.30.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",