@paigy/mcp 0.14.2 → 0.16.0

package/README.md

@@ -1,6 +1,6 @@
 # @paigy/mcp
 
-A voice inbox for your AI agents. This MCP server lets an agent **notify a user** and **await their reply** — so a long-running agent can ask a question, hand off, and resume on the answer.
+A voice inbox for your AI agents. This MCP server lets an agent **notify a user** and **await their reply** — so a long-running agent can ask a question, hand off, and resume on the answer. It's a thin MCP-tool wrapper over `@paigy/sdk` (`packages/sdk`) — use the SDK directly from any Node process that isn't an MCP client.
 
 ## Install
 
@@ -103,6 +103,14 @@ Then pair: `npx -p @paigy/mcp@latest paigy-mcp-onboard`.
 ## Configuration
 
 - `PAIGY_BACKEND_URL` — the Paigy API base (defaults to the hosted backend).
+- `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` — honored for every REST call, with
+  curl's semantics. Node's `fetch` ignores these (unlike curl), so the server
+  wires them up itself; in environments where egress only flows through a proxy
+  (Claude Code on the web, corporate CI), calls route through it automatically —
+  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.
 
 ## Statusline (Claude Code)
 

package/dist/chunk-3SVNPJPN.js

@@ -0,0 +1,36 @@
+// src/surface.ts
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var SURFACE_PATH = join(homedir(), ".paigy", "surface.json");
+function writeSurface(label, code, ttlSeconds) {
+  try {
+    mkdirSync(join(homedir(), ".paigy"), { recursive: true });
+    writeFileSync(
+      SURFACE_PATH,
+      JSON.stringify({ label, code, expiresAt: Date.now() + ttlSeconds * 1e3 }),
+      { mode: 384 }
+    );
+  } catch {
+  }
+}
+function clearSurface() {
+  try {
+    rmSync(SURFACE_PATH, { force: true });
+  } catch {
+  }
+}
+function readSurface(now = Date.now) {
+  try {
+    const { label, code, expiresAt } = JSON.parse(readFileSync(SURFACE_PATH, "utf8"));
+    return label && code && typeof expiresAt === "number" && expiresAt > now() ? { label, code } : null;
+  } catch {
+    return null;
+  }
+}
+
+export {
+  writeSurface,
+  clearSurface,
+  readSurface
+};

package/dist/{chunk-WGOGS2JC.js → chunk-R3YGSGPX.js}

@@ -1,14 +1,20 @@
-import { createRequire as __createRequire } from 'node:module'; const require = __createRequire(import.meta.url);
+// ../../packages/sdk/dist/index.js
+import { createRequire as __sdkCreateRequire } from "module";
+import { z } from "zod";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var require2 = __sdkCreateRequire(import.meta.url);
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+var __require = /* @__PURE__ */ ((x) => typeof require2 !== "undefined" ? require2 : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require2 !== "undefined" ? require2 : a)[b]
 }) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
+  if (typeof require2 !== "undefined") return require2.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 var __commonJS = (cb, mod) => function __require2() {
@@ -30,8 +36,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
   mod
 ));
-
-// ../../node_modules/.pnpm/tweetnacl@1.0.3/node_modules/tweetnacl/nacl-fast.js
 var require_nacl_fast = __commonJS({
   "../../node_modules/.pnpm/tweetnacl@1.0.3/node_modules/tweetnacl/nacl-fast.js"(exports, module) {
     "use strict";
@@ -2255,9 +2259,21 @@ var require_nacl_fast = __commonJS({
     })(typeof module !== "undefined" && module.exports ? module.exports : self.nacl = self.nacl || {});
   }
 });
-
-// ../../packages/schema/dist/index.js
-import { z } from "zod";
+var BACKEND_URL = process.env.PAIGY_BACKEND_URL ?? "https://paigy.ai";
+var NETWORK_MSG = `Can't reach ${BACKEND_URL} \u2014 the connection was blocked or dropped before an HTTP response. If this agent runs in a sandboxed environment with a network allowlist (e.g. Claude Code on the web, CI), ask the user to add the Paigy domain (paigy.ai) to the environment's allowed domains, then retry.`;
+var PROXY_ENV = ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"];
+var agent;
+async function proxy() {
+  if (!PROXY_ENV.some((k) => process.env[k])) return void 0;
+  return agent ??= new (await import("undici")).EnvHttpProxyAgent();
+}
+async function reach(url, init) {
+  try {
+    return await fetch(url, { ...init, dispatcher: await proxy() });
+  } catch (e) {
+    throw new Error(`${NETWORK_MSG} (${e?.message ?? String(e)})`);
+  }
+}
 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.")
@@ -2531,6 +2547,9 @@ var InboxItemSchema = z.object({
   options: z.array(OptionSchema).optional(),
   /** The ask's declared coverage points (#396), when the agent sent them. */
   points: z.array(z.string()).optional(),
+  /** Natural spoken questions for the points (#417 follow-up), phrased at ring time
+   *  and index-aligned — the call bot prefers these over the raw shorthand. */
+  pointsSpeak: z.array(z.string()).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. */
   intents: z.array(IntentSchema).optional(),
@@ -2671,8 +2690,6 @@ var CreateRequestSchema = z.object({
   text: z.string().min(1)
 });
 var DeliveryModeSchema = z.enum(["poll", "self_hosted"]);
-var WAKE_EVENT = "wake";
-var wakeChannel = (tokenId) => `wake:${tokenId}`;
 var RegisterDeliverySchema = z.object({ mode: DeliveryModeSchema });
 var OAuthStartSchema = z.object({
   provider: z.enum(["cma"]),
@@ -2809,25 +2826,60 @@ var SupportRequestSchema = z.object({
   message: z.string().trim().min(1).max(5e3),
   name: z.string().trim().max(120).optional()
 });
-
-// src/http.ts
-var BACKEND_URL = process.env.PAIGY_BACKEND_URL ?? "https://paigy.ai";
-var NETWORK_MSG = `Can't reach ${BACKEND_URL} \u2014 the connection was blocked or dropped before an HTTP response. If this agent runs in a sandboxed environment with a network allowlist (e.g. Claude Code on the web, CI), ask the user to add the Paigy domain (paigy.ai) to the environment's allowed domains, then retry.`;
-async function reach(url, init) {
-  try {
-    return await fetch(url, init);
-  } catch (e) {
-    throw new Error(`${NETWORK_MSG} (${e?.message ?? String(e)})`);
+var WORD_NUMS = {
+  a: 1,
+  an: 1,
+  one: 1,
+  two: 2,
+  three: 3,
+  four: 4,
+  five: 5,
+  six: 6,
+  seven: 7,
+  eight: 8,
+  nine: 9,
+  ten: 10,
+  fifteen: 15,
+  twenty: 20,
+  thirty: 30,
+  forty: 40,
+  "forty-five": 45,
+  fifty: 50,
+  sixty: 60,
+  "half an": 0.5,
+  "a couple of": 2,
+  "a few": 3
+};
+function untilHour(hour, now) {
+  const due = new Date(now);
+  due.setHours(hour, 0, 0, 0);
+  if (due.getTime() <= now.getTime()) due.setDate(due.getDate() + 1);
+  return Math.round((due.getTime() - now.getTime()) / 1e3);
+}
+function parseDue(detail, now = /* @__PURE__ */ new Date()) {
+  const t = detail.toLowerCase().trim();
+  const rel = /(?:^|\b)in\s+(half an|a couple of|a few|an?|[\w-]+|\d+)\s*(minutes?|mins?|hours?|hrs?)\b/.exec(t);
+  if (rel) {
+    const n = /^\d+$/.test(rel[1]) ? Number(rel[1]) : WORD_NUMS[rel[1]];
+    if (n !== void 0) {
+      const unit = rel[2].startsWith("h") ? 3600 : 60;
+      return Math.round(n * unit);
+    }
+  }
+  if (/after lunch|lunchtime/.test(t)) return untilHour(13, now);
+  if (/tomorrow/.test(t)) {
+    const due = new Date(now);
+    due.setDate(due.getDate() + 1);
+    due.setHours(9, 0, 0, 0);
+    return Math.round((due.getTime() - now.getTime()) / 1e3);
   }
+  if (/tonight|this evening/.test(t)) {
+    return now.getHours() < 20 ? untilHour(20, now) : 3600;
+  }
+  if (/end of (the )?day|eod/.test(t)) return untilHour(17, now);
+  if (/later|in a (bit|while)/.test(t)) return 1800;
+  return null;
 }
-
-// src/device.ts
-import { execFile } from "child_process";
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
-import { homedir, platform } from "os";
-import { join } from "path";
-
-// ../../packages/crypto/dist/index.js
 var import_tweetnacl = __toESM(require_nacl_fast(), 1);
 var import_tweetnacl2 = __toESM(require_nacl_fast(), 1);
 var import_tweetnacl3 = __toESM(require_nacl_fast(), 1);
@@ -3096,45 +3148,11 @@ function verifyPairingCommit(commitment, proto, role, x25519Pub, ed25519Pub, non
     return false;
   }
 }
-
-// src/device.ts
 var AGENT_NAME = process.env.PAIGY_AGENT ?? "mcp-agent";
 var PROTO = "paigy-pair-v2|sas=24";
 var SAS_BITS = 24;
 var TOKEN_PATH = join(homedir(), ".paigy", "token.json");
 var KEY_PATH = join(homedir(), ".paigy", "key.json");
-var SURFACE_PATH = join(homedir(), ".paigy", "surface.json");
-function writeSurface(label, code, ttlSeconds) {
-  try {
-    mkdirSync(join(homedir(), ".paigy"), { recursive: true });
-    writeFileSync(
-      SURFACE_PATH,
-      JSON.stringify({ label, code, expiresAt: Date.now() + ttlSeconds * 1e3 }),
-      { mode: 384 }
-    );
-  } catch {
-  }
-}
-function clearSurface() {
-  try {
-    rmSync(SURFACE_PATH, { force: true });
-  } catch {
-  }
-}
-function readSurface(now = Date.now) {
-  try {
-    const { label, code, expiresAt } = JSON.parse(readFileSync(SURFACE_PATH, "utf8"));
-    return label && code && typeof expiresAt === "number" && expiresAt > now() ? { label, code } : null;
-  } catch {
-    return null;
-  }
-}
-function openBrowser(url) {
-  const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
-  const args = platform() === "win32" ? ["/c", "start", url] : [url];
-  execFile(cmd, args, () => {
-  });
-}
 function saveToken(token) {
   mkdirSync(join(homedir(), ".paigy"), { recursive: true });
   writeFileSync(TOKEN_PATH, JSON.stringify(token, null, 2) + "\n", { mode: 384 });
@@ -3162,11 +3180,11 @@ async function revokeToken(token) {
   });
   return res.ok;
 }
-async function requestCode(agent = AGENT_NAME, e2ee) {
+async function requestCode(agent2 = AGENT_NAME, e2ee) {
   const res = await reach(`${BACKEND_URL}/api/device/code`, {
     method: "POST",
     headers: { "content-type": "application/json" },
-    body: JSON.stringify(e2ee ? { agent, proto: e2ee.proto, commitment: e2ee.commitment } : { agent })
+    body: JSON.stringify(e2ee ? { agent: agent2, proto: e2ee.proto, commitment: e2ee.commitment } : { agent: agent2 })
   });
   if (!res.ok) throw new Error(`/api/device/code failed: ${res.status} ${await res.text()}`);
   return await res.json();
@@ -3316,22 +3334,194 @@ function openSealedAnswer(sealed, keypair) {
   }
   return answer;
 }
+var UnpairedError = class extends Error {
+  constructor() {
+    super("Not paired with Paigy \u2014 no valid token (the API answered 401). Run the pairing flow, then retry.");
+    this.name = "UnpairedError";
+  }
+};
+function ensureAuthed(res) {
+  if (res.status === 401) throw new UnpairedError();
+  return res;
+}
+async function sealForE2ee(req, token, deps = {}) {
+  const keyFile = (deps.readKeyFile ?? readKeyFile)();
+  if (!keyFile?.e2ee) return req;
+  req = deriveAsk(req);
+  if (!keyFile.uikPub) {
+    throw new Error("E2EE pairing is missing its pinned identity key (key.json.uikPub) \u2014 re-pair; refusing to send plaintext.");
+  }
+  const roster = await (deps.fetchRoster ?? fetchRoster)(token);
+  if (!roster) {
+    throw new Error("E2EE pairing has no device roster to seal to \u2014 refusing to send plaintext. Approve a device on your phone, then retry.");
+  }
+  const recipients = verifiedRecipients(roster, keyFile.uikPub);
+  if (recipients.length === 0) {
+    throw new Error("No roster device verified against the pinned identity key \u2014 refusing to send plaintext (a server-injected device is dropped).");
+  }
+  const sealedContext = {
+    ...req.context,
+    ...req.repo !== void 0 ? { repo: req.repo } : {},
+    ...req.branch !== void 0 ? { branch: req.branch } : {}
+  };
+  const envelope = sealFields({ context: sealedContext, options: req.options, visuals: req.visuals }, recipients);
+  const { context: _c, options: _o, visuals: _v, repo: _r, branch: _b, ...meta } = req;
+  return { ...meta, envelope };
+}
+async function submitNotification(req) {
+  const token = readToken();
+  const body = await sealForE2ee(req, token);
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/notify`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+    body: JSON.stringify(body)
+  }));
+  if (!res.ok) throw new Error(`notify failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+var sleep2 = (ms) => new Promise((r) => setTimeout(r, ms));
+function decryptAnswer(reply, deps = {}) {
+  if (!reply.sealed) return reply.answer;
+  const keyFile = (deps.readKeyFile ?? readKeyFile)();
+  if (!keyFile?.keypair) {
+    throw new Error("received a sealed answer but this agent has no device key to open it \u2014 re-pair.");
+  }
+  return openSealedAnswer(reply.sealed, keyFile.keypair);
+}
+async function pollAnswer(notificationId) {
+  const token = readToken();
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/await?notificationId=${encodeURIComponent(notificationId)}`, {
+    headers: { authorization: `Bearer ${token}` }
+  }));
+  if (!res.ok) throw new Error(`await failed: ${res.status} ${await res.text()}`);
+  const item = await res.json();
+  return item.type === "idle" ? item : decryptItem(item);
+}
+async function awaitReply(notificationId, opts = {}) {
+  const intervalMs = opts.intervalMs ?? 5e3;
+  const windowMs = opts.windowMs ?? 3e5;
+  const doSleep = opts.sleep ?? sleep2;
+  const now = opts.now ?? Date.now;
+  const start = now();
+  while (true) {
+    const item = await pollAnswer(notificationId);
+    if (item.type !== "idle") return item;
+    if (now() - start >= windowMs) return { type: "idle" };
+    await doSleep(intervalMs);
+  }
+}
+function decryptItem(item) {
+  if (item.type !== "reply") return item;
+  const enriched = { ...item, intents: landIntents(item.intents) };
+  if (!enriched.sealed) return enriched;
+  const answer = decryptAnswer(enriched);
+  const { sealed: _s, ...rest } = enriched;
+  return { ...rest, answer };
+}
+function landIntents(intents) {
+  if (!intents?.length) return intents;
+  return intents.map((i) => {
+    if (i.kind !== "defer") return i;
+    const due = parseDue(i.detail);
+    return due !== null ? { ...i, dueInSeconds: due } : i;
+  });
+}
+async function checkReplies() {
+  const token = readToken();
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/pending`, {
+    headers: { authorization: `Bearer ${token}` }
+  }));
+  if (!res.ok) throw new Error(`check_replies failed: ${res.status} ${await res.text()}`);
+  const pending = await res.json();
+  return {
+    ...pending,
+    replies: pending.replies.map((raw) => {
+      const r = { ...raw, intents: landIntents(raw.intents) };
+      if (!r.sealed) return r;
+      const { sealed: _s, ...rest } = r;
+      return { ...rest, answer: decryptAnswer(r) };
+    })
+  };
+}
+async function setTaskState(notificationId, state) {
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/notify/${notificationId}/state`, {
+    method: "PATCH",
+    headers: { "content-type": "application/json", authorization: `Bearer ${readToken()}` },
+    body: JSON.stringify({ state })
+  }));
+  if (!res.ok) throw new Error(`set_task_state failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+async function registerDelivery(mode) {
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/delivery`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${readToken()}` },
+    body: JSON.stringify({ mode })
+  }));
+  if (!res.ok) throw new Error(`register_delivery failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+async function scheduleCallback(req) {
+  const token = readToken();
+  const res = ensureAuthed(await reach(`${BACKEND_URL}/api/callback`, {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+    body: JSON.stringify(req)
+  }));
+  if (!res.ok) throw new Error(`schedule_callback failed: ${res.status} ${await res.text()}`);
+  return await res.json();
+}
+var TITLE_MAX = 90;
+var CHUNKS_MAX = 8;
+var CHUNK_MAX = 300;
+var ASK_MAX = 600;
+var OPTION_MAX = 80;
+var NEEDS_MAX = 6;
+var UNSPEAKABLE = /```|\n/;
+function lintNotify(req) {
+  const problems = [];
+  if (req.ask !== void 0) {
+    if (req.ask.length > ASK_MAX)
+      problems.push(`ask is ${req.ask.length} chars \u2014 state the need and why it matters now in \u2264${ASK_MAX}; move detail into a smaller follow-up`);
+    if (UNSPEAKABLE.test(req.ask))
+      problems.push("ask contains code fences or newlines \u2014 write it as plain prose (it may be read aloud on a call)");
+    for (const n of req.needs ?? []) {
+      if (n.length > OPTION_MAX) problems.push(`need "${n.slice(0, 40)}\u2026" is too long \u2014 each need is a short phrase (\u2264${OPTION_MAX} chars)`);
+    }
+    if ((req.needs?.length ?? 0) > NEEDS_MAX)
+      problems.push(`${req.needs?.length} needs \u2014 cap at ${NEEDS_MAX}; a call can't cover more in one conversation, split the rest into a second ask`);
+    return problems;
+  }
+  const spoken = req.urgency === "call" || req.urgency === "banner";
+  if (req.context) {
+    if (req.context.title.length > TITLE_MAX)
+      problems.push(`title is ${req.context.title.length} chars \u2014 shorten to \u2264${TITLE_MAX} (it's what shows on the banner / gets spoken on a ring)`);
+    if (UNSPEAKABLE.test(req.context.title))
+      problems.push("title contains code fences or newlines \u2014 one plain-prose line");
+    if (req.context.description.length > CHUNKS_MAX)
+      problems.push(`${req.context.description.length} description chunks \u2014 cap at ${CHUNKS_MAX}; merge or drop the rest`);
+    for (const [i, chunk] of req.context.description.entries()) {
+      if (chunk.length > CHUNK_MAX)
+        problems.push(`description[${i}] is ${chunk.length} chars \u2014 split it into standalone points of \u2264${CHUNK_MAX}`);
+    }
+    if (spoken && UNSPEAKABLE.test(req.context.description.join(" ")))
+      problems.push("urgency is 'call'/'banner' but the description has code fences/newlines-in-chunk \u2014 rewrite in spoken register (it will be read aloud)");
+  }
+  for (const o of req.options ?? []) {
+    if (o.label.length > OPTION_MAX)
+      problems.push(`option label "${o.label.slice(0, 40)}\u2026" is ${o.label.length} chars \u2014 labels must read at a glance (\u2264${OPTION_MAX}); move detail into the description`);
+  }
+  return problems;
+}
 
 export {
+  BACKEND_URL,
+  reach,
   NotifyRequestSchema,
-  deriveAsk,
   SetTaskStateSchema,
   ScheduleCallbackSchema,
-  WAKE_EVENT,
-  wakeChannel,
-  BACKEND_URL,
-  reach,
   AGENT_NAME,
   TOKEN_PATH,
-  writeSurface,
-  clearSurface,
-  readSurface,
-  openBrowser,
   saveToken,
   sleep,
   readToken,
@@ -3346,8 +3536,12 @@ export {
   finalizeE2ee,
   fetchCredential,
   pairStep,
-  fetchRoster,
-  verifiedRecipients,
-  sealFields,
-  openSealedAnswer
+  UnpairedError,
+  submitNotification,
+  awaitReply,
+  checkReplies,
+  setTaskState,
+  registerDelivery,
+  scheduleCallback,
+  lintNotify
 };

package/dist/chunk-U3WODCOE.js

@@ -0,0 +1,89 @@
+import {
+  AGENT_NAME
+} from "./chunk-R3YGSGPX.js";
+
+// src/clients.ts
+import { execFile } from "child_process";
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { homedir, platform } from "os";
+import { join, dirname } from "path";
+function openBrowser(url) {
+  const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "cmd" : "xdg-open";
+  const args = platform() === "win32" ? ["/c", "start", url] : [url];
+  execFile(cmd, args, () => {
+  });
+}
+function withPaigyMcpJson(existing, agent) {
+  let config = {};
+  if (existing) {
+    try {
+      config = JSON.parse(existing);
+    } catch {
+      return null;
+    }
+  }
+  config.mcpServers = {
+    ...config.mcpServers ?? {},
+    paigy: { command: "npx", args: ["-y", "@paigy/mcp@latest"], env: { PAIGY_AGENT: agent } }
+  };
+  return JSON.stringify(config, null, 2);
+}
+function withPaigyMcpToml(existing, agent) {
+  if (existing.includes("[mcp_servers.paigy]")) return null;
+  const entry = [
+    "",
+    "[mcp_servers.paigy]",
+    'command = "npx"',
+    'args = ["-y", "@paigy/mcp@latest"]',
+    `env = { PAIGY_AGENT = "${agent}" }`,
+    ""
+  ].join("\n");
+  return existing + entry;
+}
+function autoConfigureClients(skip = AGENT_NAME) {
+  const home = homedir();
+  const registered = [];
+  if (skip !== "antigravity") {
+    const antigravityConfigs = [
+      join(home, ".gemini", "config", "mcp_config.json"),
+      join(home, ".gemini", "antigravity-cli", "mcp_config.json")
+    ];
+    for (const path of antigravityConfigs) {
+      try {
+        if (!existsSync(dirname(path))) continue;
+        const existing = existsSync(path) ? readFileSync(path, "utf8") : null;
+        const updated = withPaigyMcpJson(existing, "antigravity");
+        if (updated === null) continue;
+        writeFileSync(path, updated);
+        registered.push(`Google Antigravity (${path})`);
+      } catch {
+      }
+    }
+  }
+  if (skip !== "codex") {
+    const codexConfig = join(home, ".codex", "config.toml");
+    try {
+      if (existsSync(dirname(codexConfig))) {
+        const existing = existsSync(codexConfig) ? readFileSync(codexConfig, "utf8") : "";
+        const updated = withPaigyMcpToml(existing, "codex");
+        if (updated !== null) {
+          writeFileSync(codexConfig, updated);
+          registered.push(`OpenAI Codex (${codexConfig})`);
+        }
+      }
+    } catch {
+    }
+  }
+  return registered;
+}
+function claudeInstallHint(skip = AGENT_NAME) {
+  if (skip.startsWith("claude")) return null;
+  if (!existsSync(join(homedir(), ".claude"))) return null;
+  return "Claude Code detected \u2014 to add Paigy there, run /plugin marketplace add paigy-ai/claude then /plugin install paigy (pairing carries over; no need to pair again).";
+}
+
+export {
+  openBrowser,
+  autoConfigureClients,
+  claudeInstallHint
+};