@cosmovex/agentpager 0.1.5 → 0.1.6

package/dist/agentsetup.js

@@ -0,0 +1,67 @@
+// "Ping me on AgentPager when you're done" — teach the agents on this computer that they can.
+// `agentpager notify` already pages the phone from anything that can run a shell command; what was
+// missing is that Claude Code, Codex and Gemini do not know the command exists. One short, marked
+// block in each agent's own instruction file fixes that, and the markers make it idempotent and
+// removable without touching a word the user wrote.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const BEGIN = '<!-- agentpager:begin -->';
+const END = '<!-- agentpager:end -->';
+export const INSTRUCTION = `${BEGIN}
+## AgentPager (the user's phone pager)
+If the user says "ping me on agentpager", "tell me on my phone" or similar, then when you finish
+(or when you need their decision) run \`agentpager notify "<one-line summary, under 100 characters>"\`.
+When you need a yes/no before something risky, run \`agentpager ask "<question>"\`: it exits 0 if they
+approve, 1 if they deny, 2 if nobody answered, so treat 2 as "do not proceed".
+If \`agentpager\` is not installed, say so instead of failing silently.
+${END}
+`;
+export function targets(home = process.env.HOME || homedir()) {
+    const t = (agent, ...parts) => {
+        const file = join(home, ...parts);
+        return { agent, file, dir: dirname(file) };
+    };
+    return [
+        t('Claude Code', '.claude', 'CLAUDE.md'),
+        t('Codex', '.codex', 'AGENTS.md'),
+        t('Gemini CLI', '.gemini', 'GEMINI.md'),
+        t('OpenCode', '.config', 'opencode', 'AGENTS.md'),
+    ];
+}
+function strip(text) {
+    const a = text.indexOf(BEGIN);
+    const b = text.indexOf(END);
+    if (a < 0 || b < a)
+        return text;
+    // Trim what the block left around it, so add → remove gives back the original bytes and
+    // add → add gives back the same file.
+    const rest = (text.slice(0, a) + text.slice(b + END.length)).replace(/\s+$/, '');
+    return rest ? `${rest}\n` : '';
+}
+export function setup(all = targets()) {
+    return all.map((t) => {
+        if (!existsSync(t.dir))
+            return { agent: t.agent, file: t.file, outcome: 'not-installed' };
+        const old = existsSync(t.file) ? readFileSync(t.file, 'utf8') : '';
+        const had = old.includes(BEGIN);
+        const base = strip(old);
+        const next = base ? `${base.replace(/\s+$/, '')}\n\n${INSTRUCTION}` : INSTRUCTION;
+        if (next === old)
+            return { agent: t.agent, file: t.file, outcome: 'unchanged' };
+        mkdirSync(t.dir, { recursive: true });
+        writeFileSync(t.file, next);
+        return { agent: t.agent, file: t.file, outcome: had ? 'updated' : 'added' };
+    });
+}
+export function remove(all = targets()) {
+    return all.map((t) => {
+        if (!existsSync(t.file))
+            return { agent: t.agent, file: t.file, outcome: 'absent' };
+        const old = readFileSync(t.file, 'utf8');
+        if (!old.includes(BEGIN))
+            return { agent: t.agent, file: t.file, outcome: 'absent' };
+        writeFileSync(t.file, strip(old));
+        return { agent: t.agent, file: t.file, outcome: 'removed' };
+    });
+}

package/dist/cli.js

@@ -21,6 +21,8 @@ import { staleBuildWarning } from './freshness.js';
 import { runRuleCommand, USAGE as GUARD_USAGE } from './guard/cli.js';
 import { install as guardInstall, runDeskHook, runHook, status as guardStatus, uninstall as guardUninstall } from './guard/index.js';
 import { Channel } from './relay.js';
+import { remove as agentsRemove, setup as agentsSetup } from './agentsetup.js';
+import { serveMcp } from './mcp.js';
 import { installService, serviceInstalled, uninstallService } from './service.js';
 import { loadState, updateState } from './store.js';
 import { isNewer, latestVersion, UPDATE_COMMAND } from './update.js';
@@ -58,6 +60,11 @@ ${bold('Always on')}
   agentpager service install     start by itself at login
   agentpager service uninstall   turn that off
 
+${bold('Let your AI agents ping you')}
+  agentpager setup-agents        teach Claude, Codex, Gemini... to say "done" on your phone
+  agentpager setup-agents --remove
+  agentpager mcp                 the same as MCP tools (Cursor, Claude Desktop)
+
 ${bold('For scripts')}
   agentpager notify "text"       page your phone
   agentpager ask "question"      wait for your yes or no
@@ -335,6 +342,25 @@ async function main() {
             console.log(dim(running ? 'The running AgentPager drops it within a couple of seconds and tells the phone.' : 'Nothing is running here, so it is gone for good.'));
             process.exit(0);
         }
+        case 'setup-agents': {
+            const results = arg === '--remove' ? agentsRemove() : agentsSetup();
+            const say = {
+                added: 'added', updated: 'updated', unchanged: 'already set up', removed: 'removed', absent: 'nothing to remove', 'not-installed': 'not installed here, skipped',
+            };
+            for (const r of results)
+                console.log(`${r.outcome === 'not-installed' || r.outcome === 'absent' ? '○' : '●'} ${r.agent}  ${dim(say[r.outcome])}`);
+            if (arg !== '--remove' && results.some((r) => ['added', 'updated', 'unchanged'].includes(r.outcome))) {
+                console.log(`\nNow tell any of them ${bold('"ping me on agentpager when you are done"')} and your phone will buzz.`);
+                console.log(dim('Assistants without a shell (Cursor, Claude Desktop): add an MCP server that runs `agentpager mcp`.'));
+            }
+            else if (arg !== '--remove') {
+                console.log('\nNo supported agent found. Any script can still use `agentpager notify "text"`.');
+            }
+            process.exit(0);
+        }
+        case 'mcp':
+            serveMcp();
+            return; // keep the process alive: stdin drives it
         case 'help':
         case '--help':
         case '-h':

package/dist/mcp.js

@@ -0,0 +1,100 @@
+// `agentpager mcp` — the same two things `notify` and `ask` do, as MCP tools, for the assistants
+// that have no shell to run a command in (Claude Desktop, Cursor, …). A hand-rolled stdio JSON-RPC
+// loop: the surface is three methods, and a dependency for that would be more code than this file.
+import { createInterface } from 'node:readline';
+import { callControl } from './control.js';
+export const TOOLS = [
+    {
+        name: 'ping_phone',
+        description: "Send a short notification to the user's phone through AgentPager. Use it when the user asked to be pinged, on finishing a long task or when you are blocked.",
+        inputSchema: {
+            type: 'object',
+            properties: { message: { type: 'string', description: 'One line, under 100 characters.' } },
+            required: ['message'],
+        },
+    },
+    {
+        name: 'ask_phone',
+        description: "Ask the user a yes/no question on their phone and wait for the answer. Returns 'approved', 'denied' or 'no answer'. Treat 'no answer' as do not proceed.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                question: { type: 'string' },
+                timeout_seconds: { type: 'number', description: 'How long to wait. Default 600.' },
+            },
+            required: ['question'],
+        },
+    },
+];
+const text = (t, isError = false) => ({ content: [{ type: 'text', text: t }], ...(isError ? { isError: true } : {}) });
+export async function callTool(name, args, call = (r) => callControl(r)) {
+    try {
+        if (name === 'ping_phone') {
+            const message = String(args?.message ?? '').trim();
+            if (!message)
+                return text('message is required', true);
+            const res = await call({ kind: 'notify', title: 'Job finished', text: message, cwd: process.cwd() });
+            return res.phones ? text(`Sent to ${res.phone ?? 'the phone'}.`) : text('No phone is paired. Ask the user to run `agentpager pair`.', true);
+        }
+        if (name === 'ask_phone') {
+            const question = String(args?.question ?? '').trim();
+            if (!question)
+                return text('question is required', true);
+            const secs = Number(args?.timeout_seconds);
+            const res = await call({
+                kind: 'ask',
+                title: question.slice(0, 60),
+                text: question,
+                cwd: process.cwd(),
+                timeoutMs: Number.isFinite(secs) && secs > 0 ? secs * 1000 : undefined,
+            });
+            if (!res.phones)
+                return text('No phone is paired. Ask the user to run `agentpager pair`.', true);
+            return text(res.decision === 'allow' ? 'approved' : res.decision === 'deny' ? 'denied' : 'no answer');
+        }
+        return text(`unknown tool ${name}`, true);
+    }
+    catch (e) {
+        return text(String(e?.message ?? e), true);
+    }
+}
+/** One JSON-RPC message in, the reply out (or undefined for a notification). */
+export async function handle(msg, call) {
+    const reply = (result) => ({ jsonrpc: '2.0', id: msg.id, result });
+    switch (msg.method) {
+        case 'initialize':
+            return reply({
+                protocolVersion: msg.params?.protocolVersion ?? '2024-11-05',
+                capabilities: { tools: {} },
+                serverInfo: { name: 'agentpager', version: '1' },
+            });
+        case 'tools/list':
+            return reply({ tools: TOOLS });
+        case 'tools/call':
+            return reply(await callTool(msg.params?.name, msg.params?.arguments, call));
+        case 'ping':
+            return reply({});
+        default:
+            if (msg.id === undefined)
+                return undefined; // notifications/initialized and friends
+            return { jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: `Method not found: ${msg.method}` } };
+    }
+}
+export function serveMcp() {
+    const rl = createInterface({ input: process.stdin });
+    rl.on('line', async (line) => {
+        if (!line.trim())
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        const out = await handle(msg);
+        if (out)
+            process.stdout.write(JSON.stringify(out) + '\n');
+    });
+    rl.on('close', () => process.exit(0));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmovex/agentpager",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Pager for your AI coding agents — approve, reply and hear results on your phone. End-to-end encrypted.",
   "main": "dist/cli.js",
   "scripts": {