@cosmovex/agentpager 0.1.0 → 0.1.2

package/README.md

@@ -4,7 +4,7 @@ A pager for your AI coding agents. Approve what they want to do, reply, and hear
 on your phone, with the [AgentPager Android app](https://play.google.com/store/apps/details?id=com.cosmovex.mdpilot).
 
 ```bash
-npx agentpager
+npx @cosmovex/agentpager
 ```
 
 A QR code appears. Scan it in the app. Your sessions show up in a few seconds.
@@ -80,7 +80,7 @@ folder names only, so the picker can list your projects without sending any of t
 ## Keep it running
 
 ```bash
-npm install -g agentpager
+npm install -g @cosmovex/agentpager
 agentpager service install     # starts at login: macOS LaunchAgent, systemd user unit, Windows task
 agentpager service uninstall
 ```

package/dist/agents/acp.js

@@ -261,6 +261,17 @@ export class AcpAgent {
             clientCapabilities: { fs: { readTextFile: false, writeTextFile: false } },
         });
         let sessionId;
+        /** The agent's own model state, when it publishes one. Null means: this agent has no models API. */
+        let newModels = null;
+        const reportModels = () => {
+            const rows = newModels?.availableModels ?? [];
+            const items = rows
+                .filter((m) => m && typeof m.modelId === 'string')
+                .map((m) => ({ id: m.modelId, name: m.name || m.modelId, description: m.description ?? undefined }));
+            if (!items.length)
+                return;
+            sink.models({ items, current: newModels?.currentModelId ?? null, canSet: true });
+        };
         const canLoad = init?.agentCapabilities?.loadSession === true;
         if (id && canLoad) {
             await conn.loadSession({ sessionId: id, cwd: cwd ?? process.cwd(), mcpServers: [] });
@@ -270,7 +281,12 @@ export class AcpAgent {
             const created = await conn.newSession({ cwd: cwd ?? process.cwd(), mcpServers: [] });
             sessionId = created.sessionId;
             sink.identified(sessionId);
+            // ACP carries the model state on the session it just made, when the agent supports it at all
+            // (it is an unstable part of the protocol, so most do not). Unlike Codex there IS a verifiable
+            // setter here — session/set_model — so where the agent offers the state, the phone may choose.
+            newModels = created?.models ?? null;
         }
+        reportModels();
         proc.on('exit', () => {
             flush();
             sink.error(`${this.name} stopped on this computer.`);
@@ -300,6 +316,13 @@ export class AcpAgent {
                     sink.error(x.message, x.code);
                 });
             },
+            setModel: async (id) => {
+                await conn.setSessionModel({ sessionId, modelId: id });
+                // Believe the agent, not the tap: re-publish from our own state only after it accepted.
+                if (newModels)
+                    newModels.currentModelId = id;
+                reportModels();
+            },
             interrupt: async () => {
                 await conn.cancel({ sessionId }).catch(() => { });
             },

package/dist/agents/claude.js

@@ -7,6 +7,40 @@ import { findTranscript, spendOf } from '../guard/spend.js';
 import { classify, describe } from '../risk.js';
 import { SHELL, clip, withDeadline } from './types.js';
 const run = promisify(execFile);
+/**
+ * Claude's own multi-question tool (up to 4 questions, single- or multi-select each), driven
+ * headlessly: there is no terminal here to prompt, so `canUseTool`'s `updatedInput` — whatever
+ * effect it has on this ONE tool's own execution — is unverified territory. `deny` + a message the
+ * model reads as data is not a guess: it is the exact mechanism every OTHER denial in this file
+ * already relies on, so the model already knows to treat it as an answer, not a rejection.
+ */
+export async function askUserQuestion(sink, input) {
+    const raw = Array.isArray(input.questions) ? (input.questions) : [];
+    const questions = raw.slice(0, 4).map((q) => {
+        const qq = q;
+        const opts = Array.isArray(qq.options) ? qq.options : [];
+        return {
+            question: String(qq.question ?? '').slice(0, 300),
+            header: String(qq.header ?? '').slice(0, 20),
+            multiSelect: qq.multiSelect === true,
+            options: opts.slice(0, 4).map((o) => {
+                const oo = o;
+                return { label: String(oo.label ?? '').slice(0, 80), description: oo.description ? String(oo.description).slice(0, 300) : undefined };
+            }),
+        };
+    });
+    if (!questions.length)
+        return { behavior: 'deny', message: 'No questions were readable.' };
+    const summary = questions.length === 1 ? questions[0].question : `${questions.length} questions for you`;
+    const answer = await sink.ask({ tool: 'AskUserQuestion', summary, detail: '', risk: 'low', questions });
+    if (answer.decision === 'deny' || !answer.answers) {
+        return { behavior: 'deny', message: answer.message || 'The user closed this without answering.' };
+    }
+    const said = Object.entries(answer.answers)
+        .map(([q, a]) => `${q} ${a}`)
+        .join('\n');
+    return { behavior: 'deny', message: `The user answered:\n${said}` };
+}
 /** An async queue the SDK reads prompts from, so one live query takes many turns. */
 class PromptQueue {
     items = [];
@@ -138,6 +172,35 @@ export class ClaudeAgent {
         let lastText = '';
         /** What the deltas have already sent for the message currently being written. */
         let streamed = '';
+        /** The model in use, from the init message and from a switch the CLI accepted. */
+        let current = null;
+        // A resumed session's model, read from its own transcript.
+        //
+        // The SDK emits `system`/`init` — the one message that states the model — only when the first
+        // turn starts. So a session you opened and have not typed into yet would show no model at all,
+        // which is exactly the complaint this feature answers. Every assistant message in the transcript
+        // records the model that produced it, so the last one is what this session last ran on: a fact,
+        // not a guess, and init overwrites it the moment the real thing arrives.
+        if (id) {
+            void (async () => {
+                try {
+                    const messages = await getSessionMessages(id);
+                    for (let i = messages.length - 1; i >= 0; i--) {
+                        const model = messages[i]?.message?.model;
+                        if (typeof model === 'string' && model) {
+                            if (!current)
+                                current = model; // never clobber an init that already landed
+                            break;
+                        }
+                    }
+                    if (current)
+                        await reportModels();
+                }
+                catch {
+                    /* no transcript, or an unreadable one: the model simply shows up after the first turn */
+                }
+            })();
+        }
         const q = query({
             prompt: prompts,
             options: {
@@ -158,6 +221,8 @@ export class ClaudeAgent {
                 promptSuggestions: true,
                 systemPrompt: { type: 'preset', preset: 'claude_code' },
                 canUseTool: async (tool, input, opts) => {
+                    if (tool === 'AskUserQuestion')
+                        return askUserQuestion(sink, input);
                     const { summary, detail } = describe(tool, input);
                     const answer = await sink.ask({ tool, summary, detail, risk: classify(tool, input) });
                     if (answer.decision === 'deny') {
@@ -193,10 +258,28 @@ export class ClaudeAgent {
                     const msg = m;
                     if (msg.type === 'system' && msg.subtype === 'init' && msg.session_id) {
                         sink.identified(msg.session_id);
+                        // The only message that states which model this session is on. The initialize RESPONSE
+                        // lists the available models but not the chosen one, so this is the source of truth.
+                        if (typeof msg.model === 'string' && msg.model) {
+                            current = msg.model;
+                            void reportModels();
+                        }
                     }
                     else if (msg.type === 'system' && msg.subtype === 'session_state_changed') {
                         sink.state(msg.state === 'requires_action' ? 'needs_you' : msg.state === 'running' ? 'running' : 'idle');
                     }
+                    else if (msg.type === 'system' && msg.subtype === 'compact_boundary') {
+                        // The SDK auto-summarizes older turns to keep going near the context limit — silently,
+                        // until now. "I lose context when I come back" (Sumanth's survey, 2026-09-28) is partly
+                        // THIS: the agent's own memory of earlier turns just became a summary, and nothing said
+                        // so. pre/post_tokens are on the message itself; no hook needed for that much.
+                        const meta = msg.compact_metadata ?? {};
+                        const auto = meta.trigger !== 'manual';
+                        const pre = typeof meta.pre_tokens === 'number' ? meta.pre_tokens : null;
+                        const post = typeof meta.post_tokens === 'number' ? meta.post_tokens : null;
+                        const shrink = pre != null && post != null ? ` (${pre.toLocaleString()} → ${post.toLocaleString()} tokens)` : '';
+                        sink.tool('Context', `${auto ? 'Auto-compacted' : 'Compacted'} — older turns summarized to keep working${shrink}.`);
+                    }
                     else if (msg.type === 'prompt_suggestion' || msg.subtype === 'prompt_suggestion') {
                         const t = String(msg.suggestion ?? msg.text ?? msg.prompt ?? '').trim();
                         if (t)
@@ -229,8 +312,10 @@ export class ClaudeAgent {
                         }
                         if (Array.isArray(content)) {
                             for (const b of content) {
-                                if (b?.type === 'tool_use')
-                                    sink.tool(b.name, describe(b.name, b.input ?? {}).detail);
+                                if (b?.type === 'tool_use') {
+                                    const d = describe(b.name, b.input ?? {});
+                                    sink.tool(b.name, d.detail, d.path);
+                                }
                             }
                         }
                     }
@@ -242,14 +327,19 @@ export class ClaudeAgent {
                         // The one number people are desperate for. "I used up Max 5 in 1 hour of working,
                         // before I could work 8 hours" — the agent knew all along; nothing told the phone.
                         const rl = msg.rate_limits;
-                        if (msg.rate_limits_available && rl) {
-                            const win = (w) => (w ? { used: w.utilization ?? null, resetsAt: w.resets_at ?? null } : null);
-                            sink.limits({
-                                plan: msg.subscription_type ?? null,
-                                fiveHour: win(rl.five_hour),
-                                sevenDay: win(rl.seven_day),
-                            });
-                        }
+                        // Report the PLAN on every result, even when there are no rate-limit windows to report.
+                        //
+                        // This used to be inside `if (rate_limits_available)`, which made an API key — the one
+                        // case where dollars are real money — indistinguishable from "this session has not said
+                        // anything yet". The phone then fell back to showing a dollar estimate, and a $200/month
+                        // Max subscriber was told "$2092.12 of your $20.00 limit" in red. A plan of null now
+                        // positively means an API key, and no message at all means we do not know yet.
+                        const win = (w) => (w ? { used: w.utilization ?? null, resetsAt: w.resets_at ?? null } : null);
+                        sink.limits({
+                            plan: msg.subscription_type ?? null,
+                            fiveHour: msg.rate_limits_available && rl ? win(rl.five_hour) : null,
+                            sevenDay: msg.rate_limits_available && rl ? win(rl.seven_day) : null,
+                        });
                         const ok = msg.subtype === 'success' && !msg.is_error;
                         sink.done(ok, clip(String(msg.result ?? lastText ?? ''), 1200));
                     }
@@ -262,11 +352,61 @@ export class ClaudeAgent {
                 }
             }
         })();
+        /**
+         * Ask Claude Code what it can run, and report it.
+         *
+         * The list comes from the SDK every time rather than from anything we keep: model names change
+         * under us, and offering a model this account cannot run is worse than offering none. Failure is
+         * silent on purpose — not knowing the model must never stop a session from starting.
+         */
+        async function reportModels() {
+            try {
+                const models = await q.supportedModels();
+                if (!models?.length)
+                    return;
+                sink.models({
+                    items: models.map((m) => ({ id: m.value, name: m.displayName, description: m.description })),
+                    // Match the alias row's resolved id too: a session pinned to 'claude-sonnet-5' has to light
+                    // up the 'sonnet' row that covers it, or the picker shows nothing selected at all.
+                    current: current ? (models.find((m) => m.value === current || m.resolvedModel === current)?.value ?? current) : null,
+                    canSet: true,
+                });
+            }
+            catch {
+                /* an older CLI without supportedModels: no picker, everything else unaffected */
+            }
+        }
+        if (!id) {
+            // A session that has just been created has no pinned model, so the row the CLI itself labels
+            // `default` IS what it will run — a fact about a new session, not a guess. Without this the
+            // model bar stays empty until the first turn, which is the same "no model anywhere" the
+            // feature exists to fix.
+            void (async () => {
+                try {
+                    const models = await q.supportedModels();
+                    if (models?.some((m) => m.value === 'default') && !current) {
+                        current = 'default';
+                        await reportModels();
+                    }
+                }
+                catch {
+                    /* older CLI: the model appears after the first turn instead */
+                }
+            })();
+        }
         return {
             send: (text) => {
                 sink.state('running');
                 prompts.push(text);
             },
+            setModel: async (id) => {
+                // A control request the CLI resolves is its acceptance — it rejects a model the account
+                // cannot run, which is the difference from Codex, where the equivalent call returns {} for
+                // a bogus name and for `banana: 1` alike and is therefore not offered at all.
+                await q.setModel(id);
+                current = id;
+                await reportModels();
+            },
             interrupt: async () => {
                 await q.interrupt();
             },

package/dist/agents/codex.js

@@ -149,6 +149,26 @@ export class CodexAgent {
         this.lastRoute = created;
         if (!id)
             sink.identified(threadId);
+        // Which model this thread runs. Reported, never offered as a choice: `model/list` is real and
+        // honest, but the only way to change it — thread/settings/update — answers {} to a model that
+        // does not exist AND to `banana: 1`, and nothing Codex reports afterwards names a model. A
+        // switch that cannot be verified must not be presented as one, so canSet is false and the phone
+        // shows the model as a fact rather than a control. (Probed against codex-cli 0.138.0.)
+        void (async () => {
+            try {
+                const list = await rpc.request('model/list', {});
+                const rows = list?.data ?? [];
+                const items = rows
+                    .filter((m) => m && !m.hidden && typeof m.id === 'string')
+                    .map((m) => ({ id: m.id, name: m.displayName || m.id, description: m.description }));
+                if (!items.length)
+                    return;
+                sink.models({ items, current: items.length === 1 ? items[0].id : null, canSet: false });
+            }
+            catch {
+                /* an older codex without model/list: no model shown, nothing else affected */
+            }
+        })();
         return {
             send: (text) => {
                 sink.state('running');

package/dist/cli.js

@@ -93,6 +93,31 @@ async function serve(state, keepAwake) {
         hub.attach(c);
         c.start();
     }
+    // `agentpager pair` (a SEPARATE process, e.g. re-pairing after a reinstall while this one keeps
+    // running) writes the new device straight to disk. Without this, that pairing succeeds — the phone
+    // gets its "ok" — and then never connects, because this process's channel list was built once at
+    // startup and nothing ever told it a new device exists. The phone just sits on "Connecting…"
+    // forever with no way to know a restart was the missing step. Poll instead of a restart: cheap,
+    // and it means pairing a second (or reinstalled) phone never requires touching this window.
+    setInterval(() => {
+        let onDisk;
+        try {
+            onDisk = loadState();
+        }
+        catch {
+            return; // mid-write on another process; try again next tick
+        }
+        const known = new Set(state.devices.map((d) => d.id));
+        for (const d of onDisk.devices) {
+            if (known.has(d.id))
+                continue;
+            state.devices.push(d);
+            const c = new Channel(d, persist, (msg, ch) => hub.handle(msg, ch));
+            hub.attach(c);
+            c.start();
+            log(`paired while running: ${d.name}`);
+        }
+    }, 5000);
     const stopControl = serveControl((req) => hub.job(req));
     // Detect the ACP agents in the background and announce them as they appear.
     void (async () => {

package/dist/guard/limits.js

@@ -43,14 +43,23 @@ export function read() {
     }
 }
 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. */
+/**
+ * The window closest to running out, as a percentage, or null when we cannot say.
+ *
+ * 🧨 This used to multiply by 100, on the assumption that `utilization` was a 0..1 fraction. It is
+ * not — the SDK says 0-100, and the phone has always read it that way (a 77 shows as "23% of your
+ * plan left"). So a real reading of 45 became 4500, and ANY planCapPercent denied every tool call
+ * the moment one usage reading existed: the feature built for "claude has usage limit, it is not in
+ * dollars" would have bricked the agent instead of capping it. The unit tests missed it because they
+ * fed fractions and asserted the product — they agreed with the bug rather than with the provider.
+ */
 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);
+    return Math.round(Math.max(...vals));
 }
 /** 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()) {

package/dist/hub.js

@@ -6,7 +6,7 @@ import { basename } from 'node:path';
 import { random, b64u } from './crypto.js';
 import { record as recordLimits } from './guard/limits.js';
 import { PROTOCOL } from './protocol.js';
-import { addRoot, allowedCwd, browseFolders, discoverProjects } from './projects.js';
+import { addRoot, allowedCwd, browseFolders, discoverProjects, MAX_PHONE_FILE_BYTES, readFileForPhone, writeUploadedFile } from './projects.js';
 import { AwakeLock } from './awake.js';
 import { deskActive, pruneDesk } from './guard/desk.js';
 import { loadRules, PRESETS, saveRules, validateRules } from './guard/rules.js';
@@ -22,6 +22,11 @@ export class Hub {
     channels = [];
     live = new Map();
     known = new Map(); // last list, for cwd lookups
+    // In-flight uploads FROM the phone, keyed by reqId — the mirror of `sendFile`'s chunking, going
+    // the other way. Cleared on completion or error; a reqId that never completes just ages out with
+    // the process (no size cap consequence: file_put_start's own `size` already came from
+    // MAX_PHONE_FILE_BYTES-checked FilePicker output on the phone, not from anything the bridge trusts blindly here — see receiveUploadChunk).
+    uploads = new Map();
     projects = new Set();
     discovered; // git repos on this computer; scanned once, on the first hello
     projectCache;
@@ -71,6 +76,8 @@ export class Hub {
                     return;
                 case 'new':
                     return await this.startNew(msg.agent, msg.cwd, from, msg.ref);
+                case 'set_model':
+                    return await this.setModel(msg, from);
                 case 'rules_get':
                     return from.send(this.rulesReply());
                 case 'rules_set':
@@ -85,6 +92,15 @@ export class Hub {
                 }
                 case 'browse':
                     return from.send({ type: 'folders', ...browseFolders(msg.path) });
+                case 'file_get':
+                    return this.sendFile(msg.reqId, msg.path, from);
+                case 'file_put_start':
+                    // `.fill(undefined)`, not a bare `new Array(n)`: a sparse array's holes are invisible to
+                    // `.some()`/`.reduce()` below, so a 2-chunk upload looked "complete" after just chunk 0.
+                    this.uploads.set(msg.reqId, { sid: msg.sid, name: msg.name, size: msg.size, chunks: msg.chunks, received: new Array(msg.chunks).fill(undefined) });
+                    return;
+                case 'file_put_chunk':
+                    return this.receiveUploadChunk(msg.reqId, msg.index, msg.data, from);
                 case 'prompt': {
                     // Two processes writing one Claude session corrupt it. If the desk touched this session in
                     // the last 20 s (the guard's heartbeat), refuse — never touch a session with no heartbeat.
@@ -112,7 +128,7 @@ export class Hub {
                         return from.send({ type: 'asked', sid: msg.sid, reqId: msg.reqId });
                     live.asks.delete(msg.reqId);
                     this.log(`${msg.decision} → ${ask.msg.summary}`);
-                    ask.resolve({ decision: msg.decision, message: msg.message });
+                    ask.resolve({ decision: msg.decision, message: msg.message, answers: msg.answers });
                     this.broadcast({ type: 'asked', sid: msg.sid, reqId: msg.reqId });
                     this.setState(live, live.asks.size ? 'needs_you' : 'running');
                     return;
@@ -358,6 +374,63 @@ export class Hub {
             clearTimeout(timer);
         return result;
     }
+    /**
+     * "Claude made a PDF, how do I read it" — one named file, base64-chunked over the same small
+     * encrypted channel everything else uses (the relay's own rules cap one message's ciphertext at
+     * 24,000 chars; 10,000 raw bytes per chunk leaves room for the base64 + encryption overhead on
+     * top of that, twice — once for the chunk data, once for the envelope). Fire-and-forget: the
+     * phone reassembles by `index`, and a chunk arriving out of order costs nothing to wait for.
+     */
+    sendFile(reqId, path, from) {
+        const CHUNK_BYTES = 10_000;
+        const file = readFileForPhone(path);
+        if (!file.ok) {
+            from.send({ type: 'file_error', reqId, message: file.message });
+            return;
+        }
+        const chunks = Math.max(1, Math.ceil(file.bytes.length / CHUNK_BYTES));
+        from.send({ type: 'file_start', reqId, name: file.name, mime: file.mime, size: file.bytes.length, chunks });
+        for (let i = 0; i < chunks; i++) {
+            const slice = file.bytes.subarray(i * CHUNK_BYTES, (i + 1) * CHUNK_BYTES);
+            from.send({ type: 'file_chunk', reqId, index: i, data: slice.toString('base64') });
+        }
+        this.log(`sent ${file.name} (${(file.bytes.length / 1024).toFixed(0)} KB, ${chunks} chunk${chunks === 1 ? '' : 's'})`);
+    }
+    /** One chunk of a phone upload. Never trusts the phone's own claimed `size` for enforcement —
+     * counts real received bytes against the same cap `readFileForPhone` uses the other way. */
+    receiveUploadChunk(reqId, index, data, from) {
+        const up = this.uploads.get(reqId);
+        if (!up || index < 0 || index >= up.chunks)
+            return; // unknown or stale transfer: say nothing, ask nothing
+        up.received[index] = Buffer.from(data, 'base64');
+        const soFar = up.received.reduce((n, b) => n + (b?.length ?? 0), 0);
+        if (soFar > MAX_PHONE_FILE_BYTES) {
+            this.uploads.delete(reqId);
+            from.send({ type: 'file_put_error', reqId, message: 'That file is too big to send this way.' });
+            return;
+        }
+        if (up.received.some((b) => !b))
+            return; // still waiting on other chunks
+        this.uploads.delete(reqId);
+        const cwd = this.known.get(up.sid)?.cwd;
+        if (!cwd) {
+            from.send({ type: 'file_put_error', reqId, message: 'That session is not open on this computer right now.' });
+            return;
+        }
+        const bytes = Buffer.concat(up.received);
+        const result = writeUploadedFile(cwd, up.name, bytes);
+        if (!result.ok) {
+            from.send({ type: 'file_put_error', reqId, message: result.message });
+            return;
+        }
+        this.log(`received ${up.name} from the phone (${(bytes.length / 1024).toFixed(0)} KB) → ${result.path}`);
+        from.send({ type: 'file_put_done', reqId, sid: up.sid, path: result.path });
+        // Tell the agent, if one is actually running here — a file sitting on disk it was never told
+        // about is indistinguishable from a file that does not exist.
+        const live = this.live.get(up.sid);
+        if (live?.session)
+            void live.session.send(`[The user sent a file from their phone: ${result.path}]`);
+    }
     /** Take a pending request off the phone and say why it is gone. */
     withdraw(live, reqId, reason) {
         const ask = live.asks.get(reqId);
@@ -486,9 +559,9 @@ export class Hub {
                 if (!live.flush)
                     live.flush = setTimeout(() => this.flush(live), FLUSH_MS);
             },
-            tool: (tool, detail) => {
+            tool: (tool, detail, path) => {
                 this.flush(live);
-                this.broadcast({ type: 'tool', sid: live.sid, tool, detail: detail.slice(0, 300) }, true);
+                this.broadcast({ type: 'tool', sid: live.sid, tool, detail: detail.slice(0, 300), path }, true);
             },
             state: (state) => this.setState(live, state),
             limits: (l) => {
@@ -500,6 +573,12 @@ export class Hub {
                 // and it is a tiny message.
                 this.broadcast({ type: 'limits', sid: live.sid, plan: l.plan, fiveHour: l.fiveHour, sevenDay: l.sevenDay });
             },
+            models: (m) => {
+                // Not onlyActive: this is small, it changes rarely, and it is the first thing the session
+                // header shows when the app comes back — a phone that reopens to "model: —" looks broken.
+                live.models = m;
+                this.broadcast({ type: 'models', sid: live.sid, items: m.items.slice(0, 40), current: m.current, canSet: m.canSet });
+            },
             commands: (items) => {
                 this.flush(live);
                 this.broadcast({ type: 'commands', sid: live.sid, items: items.slice(0, 120) }, true);
@@ -542,6 +621,31 @@ export class Hub {
             },
         };
     }
+    /**
+     * Change a live session's model, then say what is actually in use.
+     *
+     * The reply is always a fresh `models` read back from the agent rather than an echo of what was
+     * asked for: a switch that silently did not take must show as the old model, or the phone reports
+     * a change that never happened — and the model is the one setting that decides how fast the plan
+     * window empties.
+     */
+    async setModel(msg, from) {
+        const live = this.live.get(msg.sid);
+        if (!live?.session?.setModel) {
+            return from.send({ type: 'error', sid: msg.sid, code: 'model', message: 'This agent cannot change model from the phone.' });
+        }
+        try {
+            await live.session.setModel(msg.model);
+            this.log(`model → ${msg.model}`);
+        }
+        catch (e) {
+            from.send({ type: 'error', sid: msg.sid, code: 'model', message: `Could not switch model: ${String(e?.message ?? e)}` });
+            // Fall through: re-report anyway, so the phone snaps back to the model still in use.
+        }
+        if (live.models) {
+            this.broadcast({ type: 'models', sid: live.sid, items: live.models.items.slice(0, 40), current: live.models.current, canSet: live.models.canSet });
+        }
+    }
     drop(live) {
         if (Hub.busy(live.state))
             this.awake.release();

package/dist/projects.js

@@ -12,9 +12,9 @@
 // Roots are your home folder, the folder you started the bridge in, and the parent of any folder
 // you already have a session in. That last one matters: this machine keeps its projects on an
 // external drive, where a home-folder-only scan finds nothing at all.
-import { readdirSync, realpathSync, statSync } from 'node:fs';
+import { mkdirSync, readdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join, resolve, sep } from 'node:path';
+import { extname, join, resolve, sep } from 'node:path';
 // The REAL path of the home folder: every check below compares against realpath()s, so a home that
 // sits behind a symlink (macOS /tmp, Fedora Silverblue's /home -> /var/home) would otherwise reject
 // its own owner's home folder as "outside your home folder".
@@ -127,6 +127,24 @@ export function allowedCwd(p, known = []) {
         .split(sep)
         .some((part) => part && (hidden(part) || SKIP.has(part)));
 }
+/**
+ * A file the phone may read (not browse — a specific path, e.g. one it just watched an agent
+ * write): not a directory, and its own folder inside the same roots and hidden/SKIP rules as
+ * `allowedCwd`. One promise, checked one way, so the two can never quietly drift apart.
+ */
+export function allowedFile(p) {
+    const full = real(resolve(p));
+    if (!full)
+        return false;
+    try {
+        if (!statSync(full).isFile())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    return allowedCwd(resolve(full, '..'));
+}
 /** Git repositories in your roots, most recently touched first. */
 export function discoverProjects() {
     const found = [];
@@ -193,3 +211,80 @@ export function browseFolders(path) {
     return { path: at, parent: atRoot ? (all.length > 1 ? '' : undefined) : resolve(at, '..'), dirs };
 }
 export const homeFolder = () => HOME;
+/** "Claude made a PDF, how do I read it" (real request, 2026-09-29) — not a file browser, one
+ * named file at a time, and never bigger than what the relay's small encrypted messages can carry
+ * chunked. Bump this only alongside the chunk math in hub.ts; they are the same promise. */
+export const MAX_PHONE_FILE_BYTES = 4 * 1024 * 1024;
+const MIME_BY_EXT = {
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.md': 'text/markdown',
+    '.txt': 'text/plain',
+    '.json': 'application/json',
+    '.csv': 'text/csv',
+    '.html': 'text/html',
+    '.svg': 'image/svg+xml',
+};
+/** The file behind a "get this file" tap. Never anything `allowedFile` refuses — checked the same
+ * way as every other path this bridge reads, not a second guess at the rule. */
+export function readFileForPhone(p) {
+    if (!allowedFile(p)) {
+        return { ok: false, reason: 'not_allowed', message: "That file is outside what this computer lets the phone reach." };
+    }
+    const full = real(resolve(p));
+    let bytes;
+    try {
+        bytes = readFileSync(full);
+    }
+    catch {
+        return { ok: false, reason: 'unreadable', message: 'Could not read that file.' };
+    }
+    if (bytes.length > MAX_PHONE_FILE_BYTES) {
+        const mb = (n) => (n / (1024 * 1024)).toFixed(1);
+        return {
+            ok: false,
+            reason: 'too_big',
+            message: `That file is ${mb(bytes.length)} MB — too big to send this way (limit ${mb(MAX_PHONE_FILE_BYTES)} MB).`,
+        };
+    }
+    const ext = extname(full).toLowerCase();
+    return { ok: true, name: full.split(sep).pop() || full, mime: MIME_BY_EXT[ext] ?? 'application/octet-stream', bytes };
+}
+/**
+ * The other direction: a file the phone picked, landed where the agent can actually find it.
+ * `cwd` is the session's own folder — never chosen by the phone — so this can only ever write
+ * inside a folder that folder's own session already had. `name` is untrusted input from the phone;
+ * `basename()`-only strips any `../` before it ever touches a path.
+ */
+export function writeUploadedFile(cwd, name, bytes) {
+    const full = real(cwd);
+    if (!full || !isDir(full))
+        return { ok: false, message: 'That session has no folder to put a file into.' };
+    const safeName = (name.split(/[\\/]/).pop() || 'file').replace(/^\.+/, '') || 'file';
+    const dir = join(full, '.agentpager-uploads');
+    try {
+        mkdirSync(dir, { recursive: true });
+        // Never silently overwrite: two screenshots named the same thing an hour apart are both real.
+        let path = join(dir, safeName);
+        if (entries(dir).includes(safeName) || (() => { try {
+            statSync(path);
+            return true;
+        }
+        catch {
+            return false;
+        } })()) {
+            const dot = safeName.lastIndexOf('.');
+            const stamp = Date.now();
+            path = join(dir, dot > 0 ? `${safeName.slice(0, dot)}-${stamp}${safeName.slice(dot)}` : `${safeName}-${stamp}`);
+        }
+        writeFileSync(path, bytes);
+        return { ok: true, path };
+    }
+    catch (e) {
+        return { ok: false, message: `Could not save that file: ${String(e?.message ?? e)}` };
+    }
+}

package/dist/risk.js

@@ -26,20 +26,64 @@ export function classify(tool, input) {
         return 'danger';
     return 'shell';
 }
-/** One short line a person can read at a glance (or hear): never a whole file. */
+/**
+ * One short line a person can read at a glance (or hear): never a whole file.
+ *
+ * The summary carries the *point* of the call, not its syntax. This used to say "Run a command" for
+ * every single Bash approval — so a page at a red light read "Run a command" over a line of shell,
+ * and deciding meant parsing the shell yourself. Sumanth: "claude asked for approval for execution
+ * but it should tell context of what the command does".
+ *
+ * The context was already in the payload: Claude Code's Bash tool takes a `description` written by
+ * the model in plain English for exactly this reader ("Discard all local changes and match remote
+ * main"), and we were dropping it on the floor. Prefer it, always — the command still travels as
+ * the detail for anyone who wants to read it.
+ */
 export function describe(tool, input) {
     const clip = (s, n) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
     const path = String(input.file_path ?? input.path ?? input.notebook_path ?? '');
+    /** The agent's own one-line account of what it is about to do, if it wrote one. */
+    const said = () => {
+        for (const key of ['description', 'reason', 'explanation', 'justification']) {
+            const v = input[key];
+            if (typeof v !== 'string')
+                continue;
+            // One line only: a paragraph is not a summary, and the card has a detail pane for the rest.
+            const line = v.replace(/\s+/g, ' ').trim();
+            if (line.length > 2)
+                return clip(line, 140);
+        }
+        return null;
+    };
     switch (tool) {
         case 'Bash':
         case 'shell':
-            return { summary: 'Run a command', detail: clip(String(input.command ?? ''), 2000) };
+            return { summary: said() ?? 'Run a command', detail: clip(String(input.command ?? ''), 2000) };
         case 'Edit':
         case 'MultiEdit':
-        case 'edit':
-            return { summary: `Edit ${basename(path) || 'files'}`, detail: clip(String(input.detail ?? '') || path, 2000) };
-        case 'Write':
-            return { summary: `Write ${basename(path)}`, detail: clip(path, 2000) };
+        case 'edit': {
+            const file = basename(path) || 'files';
+            return {
+                summary: said() ?? `Edit ${file}`,
+                // What the edit actually changes, not just which file it lands in. Approving a change you
+                // cannot see is a tap, not a decision.
+                detail: clip(String(input.detail ?? '') || diffOf(input) || path, 2000),
+                // "Claude made a PDF, how do I read it" — a real path, not re-parsed out of `detail` later,
+                // is what lets the phone offer "Get file" on the row that actually produced one.
+                path: path || undefined,
+            };
+        }
+        case 'Write': {
+            const file = basename(path);
+            const body = String(input.content ?? '');
+            return {
+                summary: said() ?? `Write ${file}`,
+                // The path alone was the whole detail here, so the card named a file and showed nothing of
+                // what was going into it.
+                detail: clip(body ? `${path}\n\n${body}` : path, 2000),
+                path: path || undefined,
+            };
+        }
         case 'WebFetch':
             return { summary: 'Fetch a web page', detail: clip(String(input.url ?? ''), 500) };
         default:
@@ -76,3 +120,12 @@ export function readable(input) {
         .join('\n');
 }
 const basename = (p) => p.split(/[\\/]/).filter(Boolean).pop() ?? '';
+/** An Edit's before/after, short enough to read on a phone. */
+function diffOf(input) {
+    const before = typeof input.old_string === 'string' ? input.old_string : '';
+    const after = typeof input.new_string === 'string' ? input.new_string : '';
+    if (!before && !after)
+        return '';
+    const side = (s) => (s.length > 400 ? `${s.slice(0, 399)}…` : s);
+    return `- ${side(before)}\n+ ${side(after)}`;
+}

package/package.json

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