@cosmovex/agentpager 0.1.1 → 0.1.2

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 = [];
@@ -187,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') {
@@ -232,6 +268,18 @@ export class ClaudeAgent {
                     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)
@@ -264,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);
+                                }
                             }
                         }
                     }

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;
@@ -87,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.
@@ -114,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;
@@ -360,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);
@@ -488,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) => {

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

@@ -68,6 +68,9 @@ export function describe(tool, input) {
                 // 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': {
@@ -78,6 +81,7 @@ export function describe(tool, input) {
                 // 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':

package/package.json

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