@cosmovex/agentpager 0.1.0

package/dist/guard/index.js

@@ -0,0 +1,341 @@
+// The guard: a PreToolUse hook that can actually say no.
+//
+//   agentpager guard            read a hook payload on stdin, print a decision
+//   agentpager guard install    register it in ~/.claude/settings.json
+//   agentpager guard uninstall  remove it again
+//   agentpager guard status     what this machine's config is
+//
+// The contract is Claude Code's: JSON in on stdin, JSON out on stdout, exit 0. Exit 2 would also
+// block, but we never use it — a non-zero exit is indistinguishable from the hook having crashed,
+// and a guard that looks broken gets uninstalled.
+//
+// FAILING OPEN IS DELIBERATE. If this program throws, times out, or cannot read anything it expects,
+// it prints an allow and gets out of the way. A guard that blocks work when IT is broken teaches
+// people to remove it, and then they have no guard at all on the day it mattered.
+import { execFileSync } from 'node:child_process';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { callControl } from '../control.js';
+import { touchDesk } from './desk.js';
+import { read as readLimits, worstUsedPct } from './limits.js';
+import { subjectOf } from './match.js';
+import { decide, hookOutput, presetModes } from './decide.js';
+import { defaultRules, loadRules, PRESET_IDS, rulesPath, saveRules } from './rules.js';
+import { loadPriceOverrides, money, PRICES_AS_OF, spendOf, ZERO } from './spend.js';
+const CONFIG = rulesPath();
+const CLAUDE_SETTINGS = join(homedir(), '.claude', 'settings.json');
+const ALLOW = hookOutput({ decision: 'allow' });
+const DESK_EVENTS = ['UserPromptSubmit', 'Stop'];
+/**
+ * Which agents this computer actually has — and, separately, which of them the guard can govern.
+ *
+ * Our own machine has everything, which is exactly why this was wrong: `install` wrote
+ * ~/.claude/settings.json and reported success on a machine with no Claude Code at all, where the
+ * guard governs precisely nothing. Somebody with only Codex would install it, be told it was on,
+ * and find out otherwise the first time an agent deleted something.
+ *
+ * Rules are a PreToolUse hook, and today only Claude Code has one. That is a platform limit, not a
+ * decision of ours — but saying so is.
+ */
+/**
+ * The absolute path to this very binary.
+ *
+ * 🧨 The hook used to be registered as the bare name `agentpager-guard`, which resolves only if the
+ * PATH that Claude Code runs hooks with happens to contain it. On this machine the binary lives in
+ * an nvm directory, which a GUI-launched or login-service process does not have — so the hook would
+ * fail to execute, the guard fails OPEN by design, and the result is a safety feature that reports
+ * itself installed and silently protects nothing. Verified: under PATH=/usr/bin:/bin it is not found.
+ *
+ * An absolute path resolved at install time cannot drift the way PATH does.
+ */
+export function guardCommand() {
+    const self = fileURLToPath(import.meta.url); // …/dist/guard/index.js
+    const bin = join(dirname(self), 'bin.js');
+    // node is named explicitly so the shebang and the executable bit stop mattering too.
+    return `${JSON.stringify(process.execPath)} ${JSON.stringify(bin)}`;
+}
+export function agentsHere() {
+    const known = [
+        { name: 'Claude Code', cmd: 'claude', governed: true },
+        { name: 'Codex', cmd: 'codex', governed: false },
+        { name: 'Gemini CLI', cmd: 'gemini', governed: false },
+        { name: 'OpenCode', cmd: 'opencode', governed: false },
+        { name: 'Cursor CLI', cmd: 'cursor-agent', governed: false },
+    ];
+    return known.filter((a) => {
+        try {
+            execFileSync('command', ['-v', a.cmd], { shell: true, stdio: 'ignore' });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+export function loadConfig() {
+    const cfg = loadRules();
+    // The env var wins, because it is how you scope a budget to one run without editing a file:
+    //   AGENTPAGER_BUDGET_USD=2 claude -p "do the risky thing"
+    const env = Number(process.env.AGENTPAGER_BUDGET_USD);
+    if (Number.isFinite(env) && env > 0)
+        cfg.budgetUsd = env;
+    return cfg;
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const c of process.stdin)
+        chunks.push(Buffer.from(c));
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * Is nobody at a keyboard? `claude -p` sets CLAUDE_CODE_ENTRYPOINT=sdk-cli (measured on Claude Code
+ * 2.1.283; docs/GUARD_HEADLESS.md). The desk sets `cli`, and sessions the bridge itself drives are
+ * SDK sessions that answer through the phone already, so neither counts.
+ */
+export function isHeadless(env = process.env) {
+    return env.CLAUDE_CODE_ENTRYPOINT === 'sdk-cli';
+}
+/**
+ * The decision for one hook payload, including the trip to the phone. Exposed so the tests can
+ * drive the whole path — budget, danger, phone, fallback — without a subprocess or a real phone.
+ */
+export async function runHookOn(payload, cfg, spendOverride, headless = isHeadless()) {
+    const needSpend = (cfg.budgetUsd ?? 0) > 0;
+    const spend = spendOverride ?? (needSpend && payload.transcript_path ? await spendOf(payload.transcript_path) : ZERO);
+    const result = decide(payload.tool_name ?? '', payload.tool_input ?? {}, spend, cfg);
+    return result.decision === 'ask' ? maybeAskPhone(result, payload.tool_input ?? {}, cfg, headless) : result;
+}
+/** The hook itself. Always prints exactly one JSON object, always exits 0. */
+export async function runHook() {
+    let out = ALLOW;
+    try {
+        const raw = await readStdin();
+        const payload = JSON.parse(raw);
+        // The desk heartbeat: "someone is working in this session on this computer". Sessions the
+        // bridge drives for the phone say so (AGENTPAGER_BRIDGE=1) and must not
+        // count, or the phone would lock itself out of its own session.
+        if (!process.env.AGENTPAGER_BRIDGE)
+            touchDesk(payload.session_id);
+        out = hookOutput(await runHookOn(payload, loadConfig()));
+    }
+    catch {
+        out = ALLOW; // see the note at the top: broken guard must not mean blocked work
+    }
+    process.stdout.write(out);
+}
+/** `agentpager-guard desk`: the Stop / UserPromptSubmit hook. Records the heartbeat, prints nothing. */
+export async function runDeskHook() {
+    try {
+        const payload = JSON.parse(await readStdin());
+        if (!process.env.AGENTPAGER_BRIDGE)
+            touchDesk(payload.session_id);
+    }
+    catch {
+        /* never block a prompt over a heartbeat */
+    }
+}
+/**
+ * The point of the phone.
+ *
+ * A guard that can only ask in the terminal is a guard that only works while you are sitting at the
+ * terminal — which is exactly when you least need it. The damage stories are all unattended: a
+ * scheduled job that force-pushed, subagents that ran at 3am, "the job ran on a schedule with nobody
+ * watching." So when a bridge is running and a phone is paired, the question goes to the phone and
+ * this call waits for a real human answer.
+ *
+ * Every failure path falls back to `ask`, which is Claude Code's own prompt: no bridge, no phone,
+ * no answer in time, socket error. The phone is an upgrade to the question, never a new way to be
+ * blocked — and `deny` from the phone is honoured exactly as typed.
+ */
+async function maybeAskPhone(result, input, cfg, headless = false) {
+    // Interactive: any failure falls back to Claude Code's own terminal prompt. Headless there IS no
+    // terminal prompt — and under bypassPermissions/--dangerously-skip-permissions a hook's `ask` is
+    // silently ignored and the command RUNS (measured; docs/GUARD_HEADLESS.md). So a headless run that
+    // cannot reach a human is refused, out loud, with the way out.
+    const asAsk = { decision: 'ask', reason: result.reason };
+    const blocked = (why) => ({
+        decision: 'deny',
+        rule: result.rule,
+        reason: `${result.reason ?? 'This needs approval.'} Blocked: ${why} ${HEADLESS_WAYS_OUT(result.rule)}`,
+    });
+    if (cfg.phone === 'never')
+        return headless ? blocked('this is an unattended run (claude -p) and phone approvals are switched off.') : asAsk;
+    const waitMs = Math.max(10, cfg.phoneTimeoutSec ?? 120) * 1000;
+    const subject = subjectOf(input);
+    try {
+        const res = await callControl({
+            kind: 'ask',
+            title: 'Approve this command?',
+            text: `${result.reason ?? 'Needs your approval.'}\n\n${subject}`.slice(0, 1500),
+            risk: 'danger',
+            cwd: process.cwd(),
+            timeoutMs: waitMs,
+        }, waitMs);
+        if (res.decision === 'allow')
+            return { decision: 'allow', context: 'Approved from your phone.' };
+        if (res.decision === 'deny')
+            return { decision: 'deny', rule: result.rule, reason: 'Denied from your phone.' };
+        if (!headless)
+            return asAsk; // timeout: the person never saw it, so fall through to the terminal
+        return blocked(res.phones === 0
+            ? 'this is an unattended run (claude -p) and no phone is paired with this computer.'
+            : `this is an unattended run (claude -p) and nobody answered on your phone within ${Math.round(waitMs / 1000)} seconds.`);
+    }
+    catch {
+        // no bridge, or the socket is gone
+        return headless ? blocked('this is an unattended run (claude -p) and the AgentPager bridge is not running, so there is no one to ask.') : asAsk;
+    }
+}
+/** What a person can do about a refused headless call: pair, or decide the rule should not fire. */
+function HEADLESS_WAYS_OUT(rule) {
+    const off = rule && PRESET_IDS.includes(rule)
+        ? `To stop asking about this: agentpager guard preset ${rule} off (or allow just this: agentpager guard allow "<text>").`
+        : rule && rule !== 'always_ask' && rule !== 'budget'
+            ? `To stop asking about this: agentpager guard remove ${rule}.`
+            : 'To allow just this: agentpager guard allow "<text>".';
+    return `To have it ask your phone instead: run "agentpager pair" once and keep "agentpager" running. ${off}`;
+}
+/**
+ * Registers the hook for every tool, merging into whatever is already there. Existing hooks are
+ * never dropped — someone else's `PreToolUse` entry is somebody's working setup.
+ */
+/**
+ * Running from npx's throwaway cache?
+ *
+ * `npx agentpager` is the right way to try this — it needs no commitment and leaves nothing behind.
+ * But "leaves nothing behind" is fatal for a hook: the absolute path we register would point into a
+ * directory npx is free to delete, and the guard would stop running without ever saying so. Rules
+ * need the package to still exist tomorrow.
+ */
+export function isEphemeral(p = fileURLToPath(import.meta.url)) {
+    return /[\\/]_npx[\\/]/.test(p) || /[\\/]\.npm[\\/]_cacache[\\/]/.test(p);
+}
+export function install() {
+    if (isEphemeral()) {
+        console.log('✖ This copy is running from npx\u2019s temporary cache, which gets deleted.');
+        console.log('  A hook pointing there would stop working silently, so it is not written.');
+        console.log('  Install it properly first, then rules will stick:');
+        console.log('     npm install -g agentpager');
+        console.log('     agentpager-guard install');
+        process.exitCode = 1;
+        return;
+    }
+    const entry = {
+        matcher: '*',
+        hooks: [{ type: 'command', command: guardCommand(), timeout: 180 }],
+    };
+    let settings = {};
+    if (existsSync(CLAUDE_SETTINGS)) {
+        try {
+            settings = JSON.parse(readFileSync(CLAUDE_SETTINGS, 'utf8'));
+        }
+        catch {
+            throw new Error(`${CLAUDE_SETTINGS} is not valid JSON. Fix or move it first — refusing to overwrite a file I cannot read.`);
+        }
+    }
+    settings.hooks ??= {};
+    settings.hooks.PreToolUse ??= [];
+    const already = JSON.stringify(settings.hooks.PreToolUse).match(/agentpager-guard|guard\/bin\.js/);
+    if (!already)
+        settings.hooks.PreToolUse.push(entry);
+    // The desk heartbeat: typing a prompt or finishing a turn at this computer marks the session as
+    // "in use here", so the phone will not resume it underneath you. Cheap, prints nothing.
+    for (const event of DESK_EVENTS) {
+        settings.hooks[event] ??= [];
+        if (!JSON.stringify(settings.hooks[event]).match(/agentpager-guard|guard\/bin\.js/)) {
+            settings.hooks[event].push({ hooks: [{ type: 'command', command: `${guardCommand()} desk`, timeout: 10 }] });
+        }
+    }
+    mkdirSync(dirname(CLAUDE_SETTINGS), { recursive: true });
+    writeFileSync(CLAUDE_SETTINGS, `${JSON.stringify(settings, null, 2)}\n`);
+    const fresh = !existsSync(rulesPath());
+    if (fresh)
+        saveRules(defaultRules()); // an existing file is somebody's config: never overwritten
+    const here = agentsHere();
+    const governed = here.filter((a) => a.governed);
+    const ungoverned = here.filter((a) => !a.governed);
+    if (!governed.length) {
+        // The honest headline on a machine we cannot actually protect.
+        console.log('⚠️  Installed, but nothing on this computer is governed yet.');
+        console.log(here.length
+            ? `   Found ${here.map((a) => a.name).join(', ')}. Rules work through a PreToolUse hook, and`
+            : '   No agents found on this computer. Rules work through a PreToolUse hook, and');
+        console.log('   today only Claude Code has one. The settings file is ready for when you add it.');
+    }
+    else {
+        console.log(already ? 'Guard already installed.' : `Guard installed into ${CLAUDE_SETTINGS}`);
+        console.log(`Governing: ${governed.map((a) => a.name).join(', ')}`);
+        if (ungoverned.length) {
+            console.log(`Not governed: ${ungoverned.map((a) => a.name).join(', ')} — no hook to attach to yet.`);
+        }
+    }
+    console.log(`Config: ${rulesPath()}`);
+    if (fresh) {
+        const d = defaultRules();
+        console.log(`Defaults: ${money(d.budgetUsd)} budget per session (warns at ${money(d.budgetUsd * d.warnAt)}); asks before force-pushes, deletes, secret reads, deploys, publishes; refuses to send secrets off this computer.`);
+    }
+    console.log('See it all:  agentpager guard rules      Try a command:  agentpager guard test "cat .env"');
+    console.log('Change it:   agentpager guard preset deploy off | agentpager guard budget 50');
+}
+export function uninstall() {
+    if (!existsSync(CLAUDE_SETTINGS))
+        return console.log('Nothing to remove.');
+    let settings;
+    try {
+        settings = JSON.parse(readFileSync(CLAUDE_SETTINGS, 'utf8'));
+    }
+    catch {
+        return console.log(`${CLAUDE_SETTINGS} is not valid JSON — leaving it alone.`);
+    }
+    const before = JSON.stringify(settings.hooks ?? {});
+    for (const event of ['PreToolUse', ...DESK_EVENTS]) {
+        if (!Array.isArray(settings.hooks?.[event]))
+            continue;
+        settings.hooks[event] = settings.hooks[event].filter((e) => !JSON.stringify(e).match(/agentpager-guard|guard\/bin\.js/));
+        if (!settings.hooks[event].length)
+            delete settings.hooks[event];
+    }
+    writeFileSync(CLAUDE_SETTINGS, `${JSON.stringify(settings, null, 2)}\n`);
+    console.log(before === JSON.stringify(settings.hooks ?? {}) ? 'Guard was not installed.' : 'Guard removed.');
+}
+export async function status() {
+    const cfg = loadRules();
+    const modes = presetModes(cfg);
+    const installed = existsSync(CLAUDE_SETTINGS) && readFileSync(CLAUDE_SETTINGS, 'utf8').match(/agentpager-guard|guard\/bin\.js/);
+    console.log(`hook        ${installed ? 'installed' : 'NOT installed  (run: agentpager guard install)'}`);
+    // Our machine has every agent, which is why this was missing: on a Codex-only computer the guard
+    // installs, reports success, and governs nothing. Say which agents are actually covered.
+    const here = agentsHere();
+    const governed = here.filter((a) => a.governed).map((a) => a.name);
+    const loose = here.filter((a) => !a.governed).map((a) => a.name);
+    console.log(`governing   ${governed.length ? governed.join(', ') : 'NOTHING — no agent here has a hook to attach to'}`);
+    if (loose.length)
+        console.log(`unguarded   ${loose.join(', ')} — no PreToolUse hook exists for these yet`);
+    console.log(`config      ${rulesPath()}${existsSync(rulesPath()) ? '' : '  (not written yet — defaults apply)'}`);
+    console.log(`budget      ${cfg.budgetUsd ? `${money(cfg.budgetUsd)} per session, warns at ${money(cfg.budgetUsd * cfg.warnAt)}, denies at the limit` : 'off'}`);
+    const snap = readLimits();
+    const usedPct = worstUsedPct(snap);
+    console.log(`plan cap    ${cfg.planCapPercent ? `${cfg.planCapPercent}% of the plan window — denies past it` : 'off'}` +
+        (usedPct !== null ? `  (now ${usedPct}% used)` : snap ? '  (last reading is stale)' : '  (no reading yet)'));
+    console.log(`prices      built-in table as of ${PRICES_AS_OF}${loadPriceOverrides().length ? `, plus ${loadPriceOverrides().length} from prices.json` : ''}`);
+    for (const id of PRESET_IDS)
+        console.log(`  ${id.padEnd(14)} ${modes[id]}`);
+    console.log(`always ask  ${cfg.askOnDanger === false ? 'OFF (unsafe): sudo, git reset --hard, plain git push …' : 'on: sudo, git reset --hard, plain git push, mkfs, chmod -R'}`);
+    console.log(`your rules  ${cfg.custom.length ? cfg.custom.map((c) => `${c.id}=${c.action}`).join(', ') : 'none'}`);
+    let phones = -1;
+    try {
+        phones = (await callControl({ kind: 'ping', title: '', text: '' }, 1500)).phones;
+    }
+    catch {
+        /* no bridge running */
+    }
+    const reach = phones < 0
+        ? 'bridge is NOT running — questions stay in the terminal (headless runs are refused; run: agentpager)'
+        : phones === 0
+            ? 'bridge is running but no phone is paired (run: agentpager pair)'
+            : `${phones} phone${phones === 1 ? '' : 's'} paired and reachable`;
+    console.log(`phone       ${cfg.phone === 'never' ? 'off — always asks in the terminal' : `asks your phone first, ${cfg.phoneTimeoutSec}s, then falls back to the terminal`}; ${reach}`);
+    console.log('\nMore:  agentpager guard rules   ·   agentpager guard test "<command>"');
+}

package/dist/guard/limits.js

@@ -0,0 +1,74 @@
+// What a subscription actually runs out of.
+//
+// The budget started in dollars, and for most people dollars are a fiction. A Claude Pro or Max
+// subscriber pays $20/$100/$200 a month and then spends *windows*: a rolling five-hour allowance and
+// a weekly one. Telling them a session "cost $6.84" describes money that never moved. Codex on a
+// ChatGPT plan is the same. Dollars are real only for API keys billed per token.
+//
+// So the cap has to be available in the currency the person is actually running out of. The problem
+// is that the guard is a PreToolUse hook and the transcript it can read holds token counts and
+// nothing else — checked, there is no rate-limit field in there at all. The live numbers arrive on
+// the SDK stream, which only the bridge sees.
+//
+// So the bridge writes down what it last saw, and the guard reads it. That makes the reading as old
+// as the last session, which is why every consumer here has to reason about [fresh].
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { stateDir } from '../store.js';
+const FILE = join(stateDir, 'limits.json');
+/**
+ * A reading older than this is not used for anything that blocks work.
+ *
+ * Erring towards letting a call through is deliberate: a stale number can only be wrong in two ways,
+ * and refusing somebody's work because of a figure from yesterday morning is the one they would
+ * never forgive.
+ */
+export const MAX_AGE_MS = 30 * 60 * 1000;
+export function record(snap) {
+    try {
+        mkdirSync(dirname(FILE), { recursive: true, mode: 0o700 });
+        writeFileSync(FILE, JSON.stringify({ ...snap, at: Date.now() }), { mode: 0o600 });
+    }
+    catch {
+        /* never let bookkeeping break a session */
+    }
+}
+export function read() {
+    try {
+        const s = JSON.parse(readFileSync(FILE, 'utf8'));
+        return typeof s?.at === 'number' ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const fresh = (s, now = Date.now()) => !!s && now - s.at <= MAX_AGE_MS;
+/** The window closest to running out, as a percentage, or null when we cannot say. */
+export function worstUsedPct(s, now = Date.now()) {
+    if (!fresh(s, now))
+        return null;
+    const vals = [s.fiveHour?.used, s.sevenDay?.used].filter((v) => typeof v === 'number');
+    if (!vals.length)
+        return null;
+    return Math.round(Math.max(...vals) * 100);
+}
+/** Which window is the one running out, for a message that tells you something you can act on. */
+export function worstWindow(s, now = Date.now()) {
+    if (!fresh(s, now))
+        return null;
+    const five = s.fiveHour?.used ?? -1;
+    const seven = s.sevenDay?.used ?? -1;
+    if (five < 0 && seven < 0)
+        return null;
+    return five >= seven ? 'fiveHour' : 'sevenDay';
+}
+export function whenBack(s) {
+    const w = worstWindow(s);
+    if (!w)
+        return null;
+    const at = s[w]?.resetsAt;
+    if (!at)
+        return null;
+    const d = new Date(at);
+    return Number.isNaN(d.getTime()) ? null : d.toLocaleString();
+}