@cosmovex/agentpager 0.1.4 → 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,7 +21,9 @@ 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 { installService, uninstallService } from './service.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';
 const dim = (s) => `\x1b[2m${s}\x1b[0m`;
@@ -41,6 +43,34 @@ function printPhones(devices, indent = '  ') {
         console.log(`${indent}${bold(d.name)}  ${dim(`id ${d.id} · paired ${new Date(d.pairedAt).toLocaleDateString()}`)}`);
     }
 }
+const HELP = `
+${bold('AgentPager')} — your phone, one tap from your coding agents.
+
+${bold('Everyday')}
+  agentpager            start it (keep the window open)
+  agentpager stop       stop it
+  agentpager status     is it running, who is paired, is there an update
+
+${bold('Phones')}
+  agentpager pair       add a phone (or the same one after a reinstall)
+  agentpager devices    who is paired
+  agentpager unpair     remove a phone
+
+${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
+
+More: agentpager doctor · agentpager guard
+`;
 const UNPAIR_HINT = 'Remove a phone: `agentpager unpair <id>` (or `agentpager unpair --all`). List them: `agentpager devices`.';
 async function pair(state) {
     // Re-read: this snapshot may be as old as the terminal. "Paired" with no way to see what, or to
@@ -172,6 +202,7 @@ async function serve(state, keepAwake) {
             }
         }
     }, 2000);
+    hub.onStop = () => void quit();
     hub.onUnpair = (ch) => {
         // The phone forgot us in the app: drop it from disk first, then close the channel.
         updateState((s) => {
@@ -202,16 +233,14 @@ async function serve(state, keepAwake) {
     if (process.argv[1]?.includes('_npx')) {
         // Started with npx: this window IS AgentPager. Say so before someone closes it.
         console.log(`\n${bold('Keep this window open.')} Closing it (or Ctrl+C) disconnects your phone until you start it again.`);
-        console.log(dim('Want it always on, even after a restart?  npm install -g @cosmovex/agentpager   then:  agentpager service install'));
+        console.log(dim('Always on, even after a restart: npm install -g @cosmovex/agentpager, then agentpager service install'));
     }
     else {
         console.log(dim('\nKeep this running (or run `agentpager service install` to start it at login).'));
     }
     // Someone who reinstalls the app, or picks up a second phone, reasonably runs `agentpager` again
     // and waits for a code that never comes — this is the only place they will look for why.
-    console.log(dim('Pairing another phone (or the same one after a reinstall)? Run `agentpager pair`.'));
-    console.log(dim(UNPAIR_HINT));
-    console.log(dim('Your sessions stay on this computer; the relay only sees encrypted bytes.\n'));
+    console.log(dim('Need anything else? Run `agentpager help`.\n'));
     // Tell the terminal AND the phone when a newer AgentPager is out.
     const checkUpdate = async () => {
         const latest = await latestVersion();
@@ -313,6 +342,51 @@ 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':
+            console.log(HELP);
+            process.exit(0);
+        case 'status': {
+            const up = await callControl({ kind: 'ping', title: '', text: '' }, 1500).catch(() => null);
+            console.log(up ? `● Running on ${bold(state.machineName)}` : `○ Not running. Start it: ${bold('agentpager')} (keep the window open)`);
+            console.log(`  ${state.devices.length} phone${state.devices.length === 1 ? '' : 's'} paired${state.devices.length ? ':' : ''}`);
+            printPhones(state.devices, '    ');
+            console.log(`  Starts by itself at login: ${serviceInstalled() ? 'yes' : 'no'}`);
+            const latest = await latestVersion();
+            console.log(latest && isNewer(latest, BRIDGE_VERSION) ? `  ⬆️  ${latest} is available (you have ${BRIDGE_VERSION}): ${bold(UPDATE_COMMAND)}` : `  Version ${BRIDGE_VERSION}, up to date`);
+            process.exit(0);
+        }
+        case 'stop': {
+            const up = await callControl({ kind: 'stop', title: '', text: '' }, 3000).catch(() => null);
+            if (!up)
+                console.log('AgentPager is not running.');
+            else {
+                console.log('Stopped. Your phone will say so.');
+                if (serviceInstalled())
+                    console.log(dim('It is set to start at login and may restart by itself. To turn that off: agentpager service uninstall'));
+            }
+            process.exit(0);
+        }
         case 'notify':
         case 'ask': {
             // Parse flags properly: a flag's VALUE must not leak into the message body.
@@ -443,7 +517,7 @@ async function main() {
             process.exit(0);
         }
         default:
-            console.log('Usage: agentpager [start | pair | devices | unpair <id> | doctor | guard install|status|rules|test | notify <text> | ask <text> | service install|uninstall]');
+            console.log(HELP);
             process.exit(1);
     }
 }

package/dist/hub.js

@@ -60,6 +60,8 @@ export class Hub {
     detach(channel) {
         this.channels = this.channels.filter((c) => c !== channel);
     }
+    /** `agentpager stop` from another terminal. */
+    onStop;
     /** Called with the phone that asked to be unpaired; the CLI owns the state file. */
     onUnpair;
     /** Newest version on npm, once known. Sent with every hello so the phone can say "update". */
@@ -343,6 +345,10 @@ export class Hub {
         };
         if (req.kind === 'ping')
             return { decision: 'allow', ...reach };
+        if (req.kind === 'stop') {
+            setTimeout(() => this.onStop?.(), 150); // answer first, then go
+            return { decision: 'allow', ...reach };
+        }
         // Nobody to ask is not a denial and not a wait — it's a setup problem, and the script must
         // learn that in milliseconds, not after an hour of blocking a deploy.
         if (!reach.phones)

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/dist/service.js

@@ -115,3 +115,21 @@ export function uninstallService() {
     }
     return 'Nothing to remove.';
 }
+/** Is the start-at-login service set up? Cheap and offline: it only looks for the file we wrote. */
+export function serviceInstalled() {
+    const os = platform();
+    if (os === 'darwin')
+        return existsSync(join(homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`));
+    if (os === 'linux')
+        return existsSync(join(homedir(), '.config', 'systemd', 'user', 'agentpager.service'));
+    if (os === 'win32') {
+        try {
+            execFileSync('schtasks', ['/Query', '/TN', 'AgentPager'], { stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmovex/agentpager",
-  "version": "0.1.4",
+  "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": {