@1presence/bridge 0.45.0 → 0.50.0

package/README.md

@@ -32,7 +32,7 @@ Your OAuth tokens and vault data stay server-side — nothing sensitive is store
 
 ## Model
 
-On first run the bridge asks which Claude model you want it to use. Leave the prompt blank to defer to your local Claude Code default (recommended — typically Sonnet on a Pro subscription), or type a specific model id to pin it (e.g. `claude-opus-4-7`, `claude-sonnet-4-5`, `claude-haiku-4-5`). The choice is saved to `~/.1presence/config.json` and reused on every subsequent run.
+On first run the bridge asks which Claude model you want it to use. Pick "Use Claude Code default" to defer to your local Claude Code default, or choose a specific model id to pin it (e.g. `claude-opus-4-8[1m]`, `claude-opus-4-8`, `claude-sonnet-4-6`, `claude-haiku-4-5`). The default selection (auto-chosen if the prompt times out) is `claude-opus-4-8[1m]` — the latest Opus with a 1M-token context window. The choice is saved to `~/.1presence/config.json` and reused on every subsequent run.
 
 The first reply each session prints the model and credential source so you can confirm what's running. To change your pick later, edit or delete `~/.1presence/config.json` — the bridge will prompt again on the next start.
 

package/dist/auth.js

@@ -190,6 +190,21 @@ export async function ensureFreshToken(auth) {
     const newToken = await refreshIdToken(auth.refreshToken);
     return { ...auth, token: newToken };
 }
+/**
+ * Mints a fresh ID token unconditionally, ignoring local expiry. Used on the
+ * reconnect path after the gateway has *rejected* our token (WS close 4001):
+ * the gateway's verdict beats our own clock, so we always refresh rather than
+ * trusting a token that still looks valid locally (e.g. clock skew). Returns
+ * the refreshed auth, or null when there is no refresh token to mint from —
+ * the caller must then fall back to an interactive re-sign-in. Throws only if
+ * the refresh endpoint itself rejects (refresh token revoked/expired).
+ */
+export async function forceRefreshToken(auth) {
+    if (!auth.refreshToken)
+        return null;
+    const newToken = await refreshIdToken(auth.refreshToken);
+    return { ...auth, token: newToken };
+}
 // ─── Public API ───────────────────────────────────────────────────────────────
 // No cache — every bridge launch goes through the browser flow. This means
 // permission revocations take effect on the next restart, and the PWA's

package/dist/claude.js

@@ -1,7 +1,9 @@
 import { mkdirSync, writeFileSync, readFileSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
-import { query } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { query, createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { resolveSessionFilePath } from './sessionPath.js';
 // ─── Engine ────────────────────────────────────────────────────────────────────
 //
 // The bridge drives the local Claude Code install through the Claude Agent SDK's
@@ -161,6 +163,27 @@ function describeCliFailure(apiErrorText, authFailure) {
     }
     return 'Local Mode stopped unexpectedly. Please try again.';
 }
+/**
+ * Copy for an actionable rate-limit notice. The SDK emits `rate_limit_event`
+ * whenever rate-limit info CHANGES — including the routine `allowed` case on
+ * (nearly) every turn — so the caller must drop `allowed` and only invoke this
+ * for `allowed_warning` / `rejected`. `resetsAt` is a Unix timestamp; the SDK
+ * uses seconds, but we accept ms too in case that changes upstream.
+ */
+function formatRateLimitNotice(status, resetsAt) {
+    const when = typeof resetsAt === 'number' && resetsAt > 0
+        ? new Date(resetsAt < 1e12 ? resetsAt * 1000 : resetsAt)
+            .toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })
+        : null;
+    if (status === 'rejected') {
+        return when
+            ? `Pausing for an upstream rate limit — resumes around ${when}.`
+            : 'Pausing briefly for an upstream rate limit, then continuing…';
+    }
+    return when
+        ? `Approaching your usage limit — window resets around ${when}.`
+        : 'Approaching your usage limit for this period.';
+}
 // ─── Prompt construction ─────────────────────────────────────────────────────────
 //
 // The gateway pushes the FULL conversation (sanitised via @presence/shared
@@ -274,6 +297,11 @@ export function spawnClaude(params) {
     // line's 🧠 segment reports against the model's window.
     let lastContextTokens = 0;
     let extractedModel = null;
+    // Captured from the SDK's system/init event; gates read_session_file so it can
+    // only reach files under THIS session's folder. Read by the in-process tool
+    // handler, which fires later (when the model invokes it), by which time init
+    // has arrived.
+    let currentSessionId = null;
     let killedForViolation = false;
     let sawApiError = false;
     let sawAuthFailure = false;
@@ -284,22 +312,28 @@ export function spawnClaude(params) {
     // runs before any execution) for anything that slips past. Our MCP tools are
     // auto-approved via allowedTools, so this callback only ever fires to deny.
     const canUseTool = async (toolName, input) => {
-        if (toolName.startsWith('mcp__1presence__'))
+        // mcp__local__ is the in-process server (read_session_file) — local-only,
+        // mechanical, no network/pod hop. Everything else must be a 1Presence tool.
+        if (toolName.startsWith('mcp__1presence__') || toolName.startsWith('mcp__local__')) {
             return { behavior: 'allow', updatedInput: input };
+        }
         return { behavior: 'deny', message: `Tool ${toolName} is not allowed in Local Mode`, interrupt: true };
     };
     // Strip API key so Claude Code uses the user's claude.ai subscription (OAuth
     // credentials in the Keychain), not an API key that would bill a separate
     // account. Options.env REPLACES the subprocess env, so spread the rest through.
     const { ANTHROPIC_API_KEY: _stripped, ...safeEnv } = process.env;
-    // Raise Claude Code's MCP tool-result token cap (default 25,000). Over the cap,
-    // the CLI saves the result to a tool-results/*.txt file and returns a stub that
-    // says "read it with Read" — but Local Mode disables every built-in tool
-    // (`tools: []` below), so the model has no Read tool and stalls. Hosted mode has
-    // no such cap (results go straight to the Anthropic SDK), so a large skill body
-    // or vault read breaks Local Mode only — a parity bug. Lifting the cap lets
-    // legitimate 1Presence MCP results pass inline, matching hosted. An operator
-    // override (env already set) wins. Bounded by the model's context window anyway.
+    // When an MCP tool result is "large", Claude Code spills the full result to a
+    // tool-results/*.json file under the session folder and hands the model a
+    // `<persisted-output>` stub telling it to read that file. Local Mode disables
+    // every built-in tool (`tools: []` below), so there is no Read — historically
+    // the model reached for vault_read (which reads the cloud vault, not local
+    // disk) and stalled. The fix is the in-process read_session_file tool (see the
+    // `local` MCP server below), which reads the spilled file directly. We also
+    // best-effort raise MAX_MCP_OUTPUT_TOKENS so smaller large-ish results pass
+    // inline and never spill in the first place — but treat it as advisory: the
+    // env var is not honoured by every SDK version (it was a no-op on 0.3.x, which
+    // is what made read_session_file necessary). Operator override wins.
     if (!safeEnv['MAX_MCP_OUTPUT_TOKENS']) {
         safeEnv['MAX_MCP_OUTPUT_TOKENS'] = '200000';
     }
@@ -313,6 +347,9 @@ export function spawnClaude(params) {
         if (!sessionIdExtracted && type === 'system' && event['subtype'] === 'init') {
             const keySource = event['apiKeySource'];
             const model = event['model'];
+            const sid = event['session_id'];
+            if (sid)
+                currentSessionId = sid;
             if (model)
                 extractedModel = model;
             if (!modelAnnounced) {
@@ -367,8 +404,9 @@ export function spawnClaude(params) {
                         // make a non-1Presence tool unreachable. If one appears anyway, kill
                         // the turn so any side effect in flight is the only damage done.
                         const isMcp1presence = toolName.startsWith('mcp__1presence__');
+                        const isMcpLocal = toolName.startsWith('mcp__local__');
                         const isBareName = /^[a-z][a-z0-9_]*$/.test(toolName);
-                        if (!isMcp1presence && !isBareName) {
+                        if (!isMcp1presence && !isMcpLocal && !isBareName) {
                             killedForViolation = true;
                             const violation = `bridge tool violation: ${toolName} is not allowed in Local Mode`;
                             process.stderr.write(`[bridge] FATAL ${violation} — aborting\n`);
@@ -481,12 +519,48 @@ export function spawnClaude(params) {
             onError(`Local Mode setup files unavailable: ${err.message}`, null, null);
             return;
         }
+        // In-process MCP server for purely-LOCAL operations that cannot run in the
+        // pod (the file lives on this machine, not the agent pod). Currently one
+        // tool: read_session_file, the recovery path for the SDK's large-output
+        // spill (see resolveSessionFilePath above). It is the ONLY way to read a
+        // file on the bridge host — built-ins stay disabled (`tools: []`). The tool
+        // body is mechanical (read a confined file); no product logic or secrets, so
+        // it is safe in this public package. alwaysLoad keeps it in the turn-1
+        // prompt instead of behind tool-search, so the model can use it the moment
+        // it is handed a persisted-output stub.
+        {
+            const localServer = createSdkMcpServer({
+                name: 'local',
+                version: '1.0.0',
+                tools: [
+                    tool('read_session_file', 'Read a file from THIS Local Mode session\'s own working folder — e.g. a large tool result the runtime saved to a tool-results/*.json file and asked you to read. Read-only and confined to the current session directory. Use this (never vault_read, which reads your cloud vault) for any absolute local path the runtime hands you.', { path: z.string().describe('Absolute path to the file, exactly as the runtime gave it to you.') }, async (args) => {
+                        const safe = resolveSessionFilePath(args.path, currentSessionId);
+                        if (!safe) {
+                            return {
+                                content: [{ type: 'text', text: `Refused: "${args.path}" is outside this session's directory. Only files under the current session folder can be read.` }],
+                                isError: true,
+                            };
+                        }
+                        try {
+                            return { content: [{ type: 'text', text: readFileSync(safe, 'utf-8') }] };
+                        }
+                        catch (err) {
+                            return {
+                                content: [{ type: 'text', text: `Could not read ${safe}: ${err.message}` }],
+                                isError: true,
+                            };
+                        }
+                    }, { alwaysLoad: true }),
+                ],
+            });
+            mcpServers = { ...mcpServers, local: localServer };
+        }
         const options = {
             systemPrompt, // custom string → replaces the default Claude Code prompt
             mcpServers: mcpServers,
             strictMcpConfig: true, // only our MCP server, ignore project/user/plugin MCP
             settingSources: [], // no user/project settings or memory
-            allowedTools: ['mcp__1presence__*'], // auto-approve our MCP surface (no prompt)
+            allowedTools: ['mcp__1presence__*', 'mcp__local__read_session_file'], // auto-approve our MCP surface (no prompt)
             canUseTool, // hard deny anything else
             tools: [], // disable ALL built-in tools; MCP tools come via mcpServers and survive.
             // (The old `extraArgs: { tools: '' }` passed a malformed --tools "" that
@@ -568,9 +642,16 @@ export function spawnClaude(params) {
                         break;
                     }
                     case 'rate_limit_event': {
-                        // SDK surfaces upstream rate-limit pauses; it retries internally.
-                        // Admin-only ephemeral notice — jargon is fine in Local Mode.
-                        onNotice?.('Claude Code is pausing briefly for an upstream rate limit, then continuing…');
+                        // The SDK emits this whenever rate-limit info CHANGES — including the
+                        // routine `allowed` case on (nearly) every turn, which previously
+                        // spammed a phantom "pausing" notice (see vault/Bugs.md). Only surface
+                        // a notice when the user is actually warned or throttled.
+                        const info = m.rate_limit_info;
+                        const status = info?.status;
+                        if (status === 'allowed_warning' || status === 'rejected') {
+                            // Admin-only ephemeral notice — jargon is fine in Local Mode.
+                            onNotice?.(formatRateLimitNotice(status, info?.resetsAt));
+                        }
                         break;
                     }
                     // Everything else (partial messages, status, hooks, notifications,

package/dist/config.js

@@ -78,10 +78,11 @@ function detectClaudeDefaultModel() {
 // `--model` flag passed to the subprocess).
 const MODEL_OPTIONS = [
     { num: 1, model: null, label: 'Use Claude Code default' },
-    { num: 2, model: 'claude-opus-4-8', label: 'claude-opus-4-8' },
-    { num: 3, model: 'claude-opus-4-7', label: 'claude-opus-4-7' },
-    { num: 4, model: 'claude-sonnet-4-6', label: 'claude-sonnet-4-6' },
-    { num: 5, model: 'claude-haiku-4-5', label: 'claude-haiku-4-5' },
+    { num: 2, model: 'claude-opus-4-8[1m]', label: 'claude-opus-4-8[1m]  (1M context)' },
+    { num: 3, model: 'claude-opus-4-8', label: 'claude-opus-4-8' },
+    { num: 4, model: 'claude-opus-4-7', label: 'claude-opus-4-7' },
+    { num: 5, model: 'claude-sonnet-4-6', label: 'claude-sonnet-4-6' },
+    { num: 6, model: 'claude-haiku-4-5', label: 'claude-haiku-4-5' },
 ];
 const PROMPT_TIMEOUT_MS = 10_000;
 const DEFAULT_OPTION_NUM = 2;

package/dist/index.js

@@ -5,7 +5,7 @@ import { tmpdir } from 'os';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
-import { getValidAuth, ensureFreshToken, isTokenValid, AuthCancelledError } from './auth.js';
+import { getValidAuth, ensureFreshToken, forceRefreshToken, isTokenValid, AuthCancelledError } from './auth.js';
 import { spawnClaude, killAll, cancelConversation, setVerbose, setDebug, paint, SECTION_COLORS } from './claude.js';
 import { ensureModelChoice } from './config.js';
 import { checkAndUpdate } from './update.js';
@@ -49,6 +49,15 @@ let currentWs = null;
 // of the per-turn status line. On a pure subscription the CLI often reports a
 // per-turn cost of 0, in which case this stays at 0 and reads as "plan usage".
 let sessionCostUsd = 0;
+// Consecutive gateway auth rejections (WS close 4001) since the last good
+// connection. Reset on every successful `open`. A 4001 is almost always a
+// Firebase ID token that expired while the bridge sat idle and a deploy/restart
+// dropped the socket — recoverable by minting a fresh token. But if freshly
+// minted tokens *keep* being rejected, the account itself is the problem
+// (disabled/permission revoked): stop the refresh-and-retry loop and ask the
+// user to sign in again rather than spinning forever.
+let authRejections = 0;
+const MAX_AUTH_REJECTIONS = 3;
 // ─── Status line ──────────────────────────────────────────────────────────────
 //
 // A compact line printed after each completed turn echoing the segments local
@@ -327,6 +336,8 @@ async function handleMessage(conversationId, text, sessionId, history, auth, vau
             // Ephemeral, non-persisted thread notice (admin-only Local Mode). Relayed
             // by the gateway to the PWA SSE stream as a `notice` AgentEvent; it does
             // NOT go through the turn accumulator, so it never lands in history.
+            // Log it too: anything the user sees in chat must have a bridge-log trail.
+            console.log(`[${new Date().toLocaleTimeString()}] ⚠ notice: ${message}`);
             if (currentWs?.readyState === WebSocket.OPEN) {
                 currentWs.send(JSON.stringify({ type: 'notice', conversationId, message }));
             }
@@ -448,6 +459,9 @@ function connect(auth, retryDelay = 1000) {
         // Reset backoff so that a disconnect after a long-stable session
         // reconnects quickly instead of waiting at the 30s cap.
         retryDelay = 1000;
+        // A clean connection means whatever token we hold is accepted — clear the
+        // 4001 refresh-retry budget so a future expiry gets the full allowance.
+        authRejections = 0;
         console.log('✓ Bridge connected. Local Mode active on all your devices.\n');
         startPing();
         // Drain any save records left behind by an earlier crashed/dropped session.
@@ -498,32 +512,17 @@ function connect(auth, retryDelay = 1000) {
     });
     ws.on('close', (code) => {
         stopPing();
-        if (code === 4001) {
-            console.error('Authentication failed. Please restart the bridge to sign in again.');
-            process.exit(1);
-        }
+        // Permission genuinely not granted — no token refresh can fix this, so it
+        // stays terminal.
         if (code === 4003) {
             console.error('Local Claude Code is not enabled for your account. To request access, email hello@1presence.com.');
             process.exit(1);
         }
-        const delay = Math.min(retryDelay, 30_000);
-        console.log(`Bridge disconnected (${code}). Reconnecting in ${delay / 1000}s…`);
-        setTimeout(async () => {
-            try {
-                // Refresh setup files on reconnect in case token was refreshed.
-                // If /system-prompt-for-bridge is down this throws — log and retry; the bridge
-                // is useless without a current prompt so don't paper over it.
-                if (currentAuth)
-                    await writeSetupFiles(currentAuth);
-                connect(currentAuth, Math.min(retryDelay * 2, 30_000));
-            }
-            catch (err) {
-                console.error(`[bridge] reconnect setup failed: ${err.message}`);
-                console.error('[bridge] will retry connection anyway — system prompt may be stale until next refresh');
-                if (currentAuth)
-                    connect(currentAuth, Math.min(retryDelay * 2, 30_000));
-            }
-        }, delay);
+        // Everything else — including 4001 (gateway rejected the JWT) — is handled
+        // by scheduleReconnect, which refreshes the token before reconnecting so an
+        // expired-token disconnect recovers on its own instead of forcing a manual
+        // bridge restart.
+        scheduleReconnect(code, retryDelay);
     });
     ws.on('error', (err) => {
         // close event fires after error — reconnect handled there
@@ -533,6 +532,78 @@ function connect(auth, retryDelay = 1000) {
     });
     return ws;
 }
+// ─── Reconnect with token refresh ──────────────────────────────────────────────
+//
+// Schedules a reconnect after any non-terminal disconnect. The job this does
+// that the old inline handler didn't: it mints a fresh ID token BEFORE
+// reconnecting. Firebase ID tokens last ~1h, and the only place the bridge
+// previously refreshed was per-turn (handleMessage). So an idle bridge whose
+// socket dropped during a deploy/restart would reconnect carrying an expired
+// token → 401 on the system-prompt fetch and 4001 on the new socket → the old
+// handler then hard-exited with "please restart the bridge". Now it self-heals.
+//
+//  • 4001 (gateway rejected the JWT): force a refresh — the gateway's verdict
+//    beats our local clock. Bounded by MAX_AUTH_REJECTIONS so a genuinely dead
+//    account (revoked permission, no refresh token) still exits instead of
+//    looping. Exits only when refresh is impossible or repeatedly rejected.
+//  • Any other code (1006 abnormal close, 1001 going-away on pod restart, …):
+//    refresh only if near expiry (ensureFreshToken). A transient refresh
+//    failure here is non-fatal — reconnect with the current token; if it's
+//    truly expired the gateway returns 4001 and the branch above handles it.
+function scheduleReconnect(closeCode, retryDelay) {
+    const authFailure = closeCode === 4001;
+    const delay = Math.min(retryDelay, 30_000);
+    console.log(authFailure
+        ? `Authentication expired (${closeCode}). Refreshing token and reconnecting in ${delay / 1000}s…`
+        : `Bridge disconnected (${closeCode}). Reconnecting in ${delay / 1000}s…`);
+    setTimeout(async () => {
+        if (!currentAuth)
+            return;
+        const nextDelay = Math.min(retryDelay * 2, 30_000);
+        if (authFailure) {
+            authRejections++;
+            if (authRejections > MAX_AUTH_REJECTIONS) {
+                console.error('Authentication keeps being rejected even after refreshing — please restart the bridge to sign in again.');
+                process.exit(1);
+            }
+            try {
+                const refreshed = await forceRefreshToken(currentAuth);
+                if (!refreshed) {
+                    console.error('Authentication failed and no refresh token is available — please restart the bridge to sign in again.');
+                    process.exit(1);
+                }
+                currentAuth = refreshed;
+                console.log(`[bridge] token refreshed (attempt ${authRejections}/${MAX_AUTH_REJECTIONS}) — reconnecting with a new token.`);
+            }
+            catch (err) {
+                // Refresh endpoint rejected us — the refresh token is revoked/expired.
+                // No silent recovery is possible; the user must sign in again.
+                console.error(`[bridge] token refresh failed: ${err.message}`);
+                console.error('Please restart the bridge to sign in again.');
+                process.exit(1);
+            }
+        }
+        else {
+            try {
+                currentAuth = await ensureFreshToken(currentAuth);
+            }
+            catch (err) {
+                console.warn(`[bridge] token refresh on reconnect failed (proceeding with current token): ${err.message}`);
+            }
+        }
+        // Token is as fresh as we can make it — write setup files and reconnect.
+        // If /system-prompt-for-bridge is still 503/down (gateway waking) we
+        // reconnect anyway; handleMessage refreshes the prompt on the next turn.
+        try {
+            await writeSetupFiles(currentAuth);
+        }
+        catch (err) {
+            console.error(`[bridge] reconnect setup failed: ${err.message}`);
+            console.error('[bridge] will retry connection anyway — system prompt may be stale until next refresh');
+        }
+        connect(currentAuth, nextDelay);
+    }, delay);
+}
 // ─── Main ─────────────────────────────────────────────────────────────────────
 async function main() {
     console.log(`1Presence Bridge v${version}\n`);

package/dist/sessionPath.js

@@ -0,0 +1,31 @@
+import { homedir } from 'os';
+import { join, resolve, sep } from 'path';
+// Confinement guard for read_session_file (the in-process `local` MCP server in
+// claude.ts). The Agent SDK occasionally spills a large MCP tool result to a
+// local file under ~/.claude/projects/<cwd-slug>/<session-id>/ and hands the
+// model a stub telling it to read the file. Local Mode disables every built-in
+// tool, so the model has no Read — read_session_file is the recovery path. It
+// MUST stay read-only and confined to the CURRENT session's own folder: file
+// contents read here flow up through the gateway into the model and session
+// history, so an unrestricted reader would leak the operator's machine
+// (~/.ssh, other projects) into the transcript.
+//
+// We deliberately do NOT reconstruct Claude Code's lossy cwd-slug. Instead we
+// require (a) the resolved path to live under ~/.claude/projects/ and (b) the
+// current session UUID to appear as a discrete path segment. The UUID is
+// unguessable, so this pins reads to this session alone while staying robust to
+// changes in how Claude Code encodes the cwd.
+//
+// Returns the resolved absolute path when safe, or null when it must be refused.
+export function resolveSessionFilePath(requestedPath, sessionId, home = homedir()) {
+    if (!sessionId || !requestedPath)
+        return null;
+    const projectsRoot = join(home, '.claude', 'projects');
+    const resolved = resolve(requestedPath); // normalises away `..`
+    const underProjects = resolved === projectsRoot || resolved.startsWith(projectsRoot + sep);
+    if (!underProjects)
+        return null;
+    if (!resolved.split(sep).includes(sessionId))
+        return null;
+    return resolved;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1presence/bridge",
-  "version": "0.45.0",
+  "version": "0.50.0",
   "description": "Run 1Presence on your Mac and use your Claude.ai Pro subscription from any device",
   "type": "module",
   "bin": {
@@ -20,12 +20,13 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.153",
-    "ws": "^8.20.0"
+    "ws": "^8.20.0",
+    "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "@types/ws": "^8.18.1",
     "tsx": "^4.22.3",
-    "typescript": "^5.5.0"
+    "typescript": "^6.0.3"
   }
 }