@cosmovex/agentpager 0.1.0

package/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2026 Cosmovex. All rights reserved.
+
+You may install and run this software unmodified, free of charge, to connect your own
+computers to the AgentPager app. Redistribution, modification, or use with any other
+client is not permitted without written permission.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. IN NO EVENT SHALL THE
+AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM ITS USE.

package/README.md

@@ -0,0 +1,98 @@
+# agentpager
+
+A pager for your AI coding agents. Approve what they want to do, reply, and hear results —
+on your phone, with the [AgentPager Android app](https://play.google.com/store/apps/details?id=com.cosmovex.mdpilot).
+
+```bash
+npx agentpager
+```
+
+A QR code appears. Scan it in the app. Your sessions show up in a few seconds.
+
+## What it does
+
+- **Continues the sessions you already have.** Claude Code and Codex are driven natively, so the
+  phone picks up the session you started at your desk, with its history.
+- **Every other agent through the Agent Client Protocol (ACP):** Gemini CLI, OpenCode (including
+  DeepSeek), Qwen Code, Goose. Installed agents are detected automatically.
+- **Forwards every permission prompt to your phone.** Destructive commands — push, delete, deploy —
+  need a press-and-hold there. Nothing is auto-approved.
+- **Notifies you** when an agent needs you, finishes, or fails.
+
+## Any job can page you, not just agents
+
+```bash
+agentpager notify "AAB built"                      # a notification on your phone
+agentpager ask "Deploy build 412 to prod?"         # waits for you, up to 10 minutes
+agentpager ask "Drop the staging DB?" --danger     # needs press-and-hold on the phone
+agentpager ask "Ship it?" --timeout 30s            # 90s · 5m · 2h · bare number = seconds
+```
+
+`ask` exit codes, so a script can tell the three apart:
+
+| Code | Meaning |
+|---|---|
+| `0` | you approved |
+| `1` | you denied |
+| `2` | nobody could answer — no phone paired, the bridge isn't running, or the deadline passed |
+
+Nothing blocks forever: when the deadline passes, the request is **taken back off your phone** with
+a reason, so a card can't be approved an hour after the script gave up. `notify` tells you which
+phone it reached, and says so plainly when notifications are off or no phone is paired.
+
+Use it in build scripts, deploy steps, long test runs or training jobs:
+
+```bash
+npm run build && agentpager ask "Ship it?" && ./deploy.sh
+```
+
+## Your agent, not just ours
+
+Claude Code and Codex are driven natively. Everything else goes through the Agent Client Protocol,
+and **nothing is trusted from a list** — a candidate has to exist on your PATH *and* answer a real
+ACP `initialize` before it is offered to your phone, so an agent that appears is an agent that works.
+
+```bash
+agentpager doctor      # what was found, what was tried, and why something is missing
+```
+
+Known out of the box: Gemini CLI · OpenCode · Qwen Code · Goose · Cursor CLI · GitHub Copilot CLI ·
+Kiro CLI · Cline · Factory Droid · Kimi CLI · Mistral Vibe · OpenHands · Pi.
+
+Using something else? Teach it, without waiting for a release of ours:
+
+```json
+// ~/.agentpager/agents.json
+[{ "id": "mine", "name": "My Agent", "command": "my-agent", "args": ["acp"] }]
+```
+
+## Privacy
+
+Your code never leaves your computer. Your phone and this bridge talk **end-to-end encrypted**
+(X25519 + ChaCha20-Poly1305): the relay stores only ciphertext it cannot read, and each message is
+deleted once delivered. No account, no sign-up, and it never gets a raw shell.
+
+**Which folders the phone can reach.** It can start an agent in your home folder, in the folder you
+started the bridge in, or beside a project you already have a session in — never anywhere else on the
+disk, never in a hidden directory (`.ssh`, `.aws`, …), and never outside those trees. Browsing shows
+folder names only, so the picker can list your projects without sending any of their contents.
+
+## Keep it running
+
+```bash
+npm install -g agentpager
+agentpager service install     # starts at login: macOS LaunchAgent, systemd user unit, Windows task
+agentpager service uninstall
+```
+
+## Commands
+
+| | |
+|---|---|
+| `agentpager` | pair (first run) and stay connected |
+| `agentpager pair` | pair another phone |
+| `agentpager devices` · `agentpager unpair <id>` | list or remove paired phones |
+| `agentpager doctor` | which agents this computer can drive |
+| `agentpager notify <text>` · `agentpager ask <text>` | page your phone from any script |
+
+Requires Node 20+ and at least one agent signed in on this computer.

package/dist/agents/acp.js

@@ -0,0 +1,311 @@
+// Every other agent, through one integration: the Agent Client Protocol (ACP).
+// Gemini CLI, OpenCode (which can run DeepSeek), Qwen Code and Goose all speak it, so
+// AgentPager is not a Claude Code + Codex accessory — those two just have native adapters.
+import { explainAgentError } from './explain.js';
+import { execFile, spawn } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { Readable, Writable } from 'node:stream';
+import { promisify } from 'node:util';
+import { ClientSideConnection, ndJsonStream } from '@zed-industries/agent-client-protocol';
+import { SHELL, clip, killTree, withDeadline } from './types.js';
+import { readable } from '../risk.js';
+const run = promisify(execFile);
+const PROTOCOL_VERSION = 1;
+const FLUSH_MS = 700;
+/**
+ * Agents we know how to start over ACP.
+ *
+ * ⭐ Nothing here is trusted. Every entry is CHECKED before the phone ever sees it: the binary has
+ * to exist and then actually answer an ACP `initialize`. That matters because these commands and
+ * flags move — "--experimental-acp" is in the name of its own instability — and a list we merely
+ * believed would put agents on someone's phone that fail the moment they tap Start. A wrong guess
+ * here costs nothing: the agent simply never appears. So the list can be generous.
+ *
+ * `agentpager doctor` prints what was found AND what was tried, so a missing agent is diagnosable
+ * rather than mysterious. Anything we have not heard of goes in ~/.agentpager/agents.json — see
+ * `userAgents()`; "support MY agent" is the single most requested thing in this category and
+ * waiting for us to ship a release is the wrong answer to it.
+ */
+export const ACP_AGENTS = [
+    { id: 'gemini', name: 'Gemini CLI', command: 'gemini', args: ['--experimental-acp'] },
+    { id: 'opencode', name: 'OpenCode', command: 'opencode', args: ['acp'] },
+    { id: 'qwen', name: 'Qwen Code', command: 'qwen', args: ['--experimental-acp'] },
+    { id: 'goose', name: 'Goose', command: 'goose', args: ['acp'] },
+    { id: 'cursor', name: 'Cursor CLI', command: 'cursor-agent', args: ['acp'] },
+    { id: 'copilot', name: 'GitHub Copilot CLI', command: 'copilot', args: ['acp'] },
+    { id: 'kiro', name: 'Kiro CLI', command: 'kiro', args: ['acp'] },
+    { id: 'cline', name: 'Cline', command: 'cline', args: ['acp'] },
+    { id: 'droid', name: 'Factory Droid', command: 'droid', args: ['acp'] },
+    { id: 'kimi', name: 'Kimi CLI', command: 'kimi', args: ['--acp'] },
+    { id: 'vibe', name: 'Mistral Vibe', command: 'vibe', args: ['acp'] },
+    { id: 'openhands', name: 'OpenHands', command: 'openhands', args: ['acp'] },
+    { id: 'pi', name: 'Pi', command: 'pi-acp', args: [] },
+];
+/**
+ * Agents the user taught us about, from ~/.agentpager/agents.json:
+ *   [{ "id": "mine", "name": "My Agent", "command": "my-agent", "args": ["acp"] }]
+ * Unreadable or malformed file: we say so and carry on with the built-in list, because a typo in an
+ * optional config must never cost someone the agents that do work.
+ */
+export function userAgents(log) {
+    const file = join(homedir(), '.agentpager', 'agents.json');
+    if (!existsSync(file))
+        return [];
+    try {
+        const raw = JSON.parse(readFileSync(file, 'utf8'));
+        const list = Array.isArray(raw) ? raw : [];
+        const out = [];
+        for (const a of list) {
+            if (typeof a?.command !== 'string' || !a.command.trim())
+                continue;
+            out.push({
+                id: String(a.id ?? a.command).slice(0, 32),
+                name: String(a.name ?? a.command).slice(0, 48),
+                command: a.command,
+                args: Array.isArray(a.args) ? a.args.map(String) : [],
+                versionArgs: Array.isArray(a.versionArgs) ? a.versionArgs.map(String) : undefined,
+            });
+        }
+        if (out.length)
+            log?.(`${out.length} agent${out.length === 1 ? '' : 's'} from ${file}`);
+        return out;
+    }
+    catch (e) {
+        log?.(`ignoring ${file}: ${e?.message ?? e}`);
+        return [];
+    }
+}
+/** ACP labels the kind of work; that is enough to decide how much friction an approval needs. */
+function riskOf(kind, title) {
+    switch (kind) {
+        case 'read':
+        case 'search':
+        case 'think':
+        case 'fetch':
+            return 'low';
+        case 'edit':
+        case 'move':
+            return 'edit';
+        case 'delete':
+            return 'danger';
+        case 'execute':
+            return /\b(rm|push|deploy|publish|reset --hard|force)\b/i.test(title) ? 'danger' : 'shell';
+        default:
+            return 'shell';
+    }
+}
+export class AcpAgent {
+    spec;
+    constructor(spec) {
+        this.spec = spec;
+    }
+    get id() {
+        return this.spec.id;
+    }
+    get name() {
+        return this.spec.name;
+    }
+    async status() {
+        const missing = { id: this.id, name: this.name, available: false, reason: `${this.name} is not installed on this computer` };
+        return withDeadline((async () => {
+            let version = '';
+            try {
+                const { stdout } = await run(this.spec.command, this.spec.versionArgs ?? ['--version'], { timeout: 8000, killSignal: 'SIGKILL', shell: SHELL });
+                version = stdout.trim().split('\n')[0].slice(0, 24);
+            }
+            catch {
+                return missing; // not installed: the ordinary case, and not worth a word
+            }
+            // Installed is not the same as usable. These ACP flags move between releases, so we ask the
+            // binary to answer a real `initialize` before offering it — otherwise the phone shows an
+            // agent that dies the moment someone taps Start.
+            if (!(await this.speaksAcp())) {
+                return {
+                    id: this.id,
+                    name: this.name,
+                    available: false,
+                    reason: `${this.name} is installed but did not answer as an ACP agent (\`${[this.spec.command, ...this.spec.args].join(' ')}\`). Updating it usually fixes this.`,
+                };
+            }
+            return { id: this.id, name: this.name, available: true, version };
+        })(), 15000, missing);
+    }
+    /** Start it, say hello, and see if anything says hello back. Killed either way. */
+    speaksAcp() {
+        return new Promise((resolve) => {
+            let proc;
+            try {
+                proc = spawn(this.spec.command, this.spec.args, { stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, TERM: 'dumb' }, shell: SHELL });
+            }
+            catch {
+                return resolve(false);
+            }
+            let done = false;
+            const finish = (ok) => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                try {
+                    killTree(proc);
+                }
+                catch {
+                    /* already gone */
+                }
+                resolve(ok);
+            };
+            const timer = setTimeout(() => finish(false), 6000);
+            proc.on('error', () => finish(false));
+            proc.on('exit', () => finish(false));
+            proc.stderr.on('data', () => { });
+            let buf = '';
+            proc.stdout.on('data', (d) => {
+                buf += String(d);
+                // Any JSON-RPC reply to our id means something on the other end speaks the protocol.
+                if (buf.includes('"id":1') && (buf.includes('protocolVersion') || buf.includes('"result"')))
+                    finish(true);
+                if (buf.length > 64_000)
+                    finish(false);
+            });
+            try {
+                proc.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: PROTOCOL_VERSION, clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } } } })}\n`);
+            }
+            catch {
+                finish(false);
+            }
+        });
+    }
+    /** ACP has no "list my past sessions" call; these agents start fresh from a project folder. */
+    async list() {
+        return [];
+    }
+    async history() {
+        return [];
+    }
+    async open(id, cwd, sink) {
+        const proc = spawn(this.spec.command, this.spec.args, {
+            cwd: cwd ?? process.cwd(),
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, TERM: 'dumb' },
+            shell: SHELL,
+        });
+        proc.stderr.on('data', () => { }); // agents log freely to stderr; not ours to surface
+        let buffer = '';
+        let flushTimer;
+        const flush = () => {
+            if (flushTimer)
+                clearTimeout(flushTimer);
+            flushTimer = undefined;
+            const text = buffer;
+            buffer = '';
+            // Was sink.text(): every flush became a NEW bubble on the phone, so a streamed reply arrived
+            // as a wall of fragments instead of one message filling in. Not trimmed either — trimming a
+            // mid-sentence flush eats the space between "the" and "file".
+            if (text.trim())
+                sink.delta(text);
+        };
+        const chunk = (text) => {
+            buffer += text;
+            if (!flushTimer)
+                flushTimer = setTimeout(flush, FLUSH_MS);
+        };
+        const client = {
+            async requestPermission(params) {
+                const call = params.toolCall ?? {};
+                const title = String(call.title ?? 'Do something');
+                // Gemini CLI, OpenCode, Qwen and Goose all arrive here. Sending their raw JSON to a phone
+                // is asking someone to approve a wall of braces at a traffic light.
+                const detail = call.rawInput ? clip(readable(call.rawInput), 1200) : '';
+                flush();
+                const answer = await sink.ask({ tool: String(call.kind ?? 'tool'), summary: title, detail, risk: riskOf(call.kind, `${title} ${detail}`) });
+                const want = answer.decision === 'deny'
+                    ? ['reject_once', 'reject_always']
+                    : answer.decision === 'allow_session'
+                        ? ['allow_always', 'allow_once']
+                        : ['allow_once', 'allow_always'];
+                const option = want.map((k) => params.options.find((o) => o.kind === k)).find(Boolean) ?? params.options[0];
+                if (!option)
+                    return { outcome: { outcome: 'cancelled' } };
+                return { outcome: { outcome: 'selected', optionId: option.optionId } };
+            },
+            async sessionUpdate(params) {
+                const u = params.update;
+                switch (u.sessionUpdate) {
+                    case 'agent_message_chunk':
+                        if (u.content?.type === 'text')
+                            chunk(u.content.text);
+                        break;
+                    case 'tool_call':
+                        flush();
+                        sink.tool(String(u.kind ?? 'tool'), clip(String(u.title ?? ''), 300));
+                        break;
+                    case 'tool_call_update':
+                        if (u.status === 'failed')
+                            sink.state('failed');
+                        break;
+                }
+            },
+            async writeTextFile() {
+                throw new Error('AgentPager does not give agents file access of its own');
+            },
+            async readTextFile() {
+                throw new Error('AgentPager does not give agents file access of its own');
+            },
+        };
+        const stream = ndJsonStream(Writable.toWeb(proc.stdin), Readable.toWeb(proc.stdout));
+        const conn = new ClientSideConnection(() => client, stream);
+        const init = await conn.initialize({
+            protocolVersion: PROTOCOL_VERSION,
+            clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
+        });
+        let sessionId;
+        const canLoad = init?.agentCapabilities?.loadSession === true;
+        if (id && canLoad) {
+            await conn.loadSession({ sessionId: id, cwd: cwd ?? process.cwd(), mcpServers: [] });
+            sessionId = id;
+        }
+        else {
+            const created = await conn.newSession({ cwd: cwd ?? process.cwd(), mcpServers: [] });
+            sessionId = created.sessionId;
+            sink.identified(sessionId);
+        }
+        proc.on('exit', () => {
+            flush();
+            sink.error(`${this.name} stopped on this computer.`);
+        });
+        let usedTokens = 0;
+        return {
+            send: (text) => {
+                sink.state('running');
+                conn
+                    .prompt({ sessionId, prompt: [{ type: 'text', text }] })
+                    .then((res) => {
+                    flush();
+                    // ACP's (still unstable) per-turn usage. Not every agent sends it; when one does, the
+                    // numbers are added up here so the hub sees a running total.
+                    const u = res?.usage;
+                    const turnTokens = Number(u?.totalTokens ?? u?.total_tokens ?? 0);
+                    if (Number.isFinite(turnTokens) && turnTokens > 0) {
+                        usedTokens += turnTokens;
+                        sink.usage({ tokens: usedTokens });
+                    }
+                    const stop = res?.stopReason;
+                    sink.done(stop === 'end_turn' || stop === 'max_tokens', stop === 'refusal' ? 'The agent refused this request.' : '');
+                })
+                    .catch((e) => {
+                    flush();
+                    const x = explainAgentError(e, this.name);
+                    sink.error(x.message, x.code);
+                });
+            },
+            interrupt: async () => {
+                await conn.cancel({ sessionId }).catch(() => { });
+            },
+            close: () => {
+                killTree(proc);
+            },
+        };
+    }
+}