onepass-proxy 0.3.0

package/dist/main.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { createProxyServer } from "./server.js";
+import { newProxyLogPath } from "./log.js";
+if (process.argv.includes("--version")) {
+    const packageJson = createRequire(import.meta.url)("../package.json");
+    console.log(packageJson.version);
+    process.exit(0);
+}
+function envInt(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === "")
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0) {
+        console.error(`[onepass] ${name} must be a non-negative integer, got: ${raw}`);
+        process.exit(1);
+    }
+    return value;
+}
+// 0 asks the operating system for a free port. The eval starts a proxy child per case and per
+// tail, several at once, so it uses 0 and reads the port the child reports below.
+const port = envInt("ONEPASS_PORT", 3777);
+// Loopback only. Every request through here carries the user's Claude Code credentials upstream,
+// so a proxy bound to every interface is an open relay for anyone on the same café wifi.
+const host = process.env.ONEPASS_HOST ?? "127.0.0.1";
+const config = {
+    upstreamUrl: process.env.ONEPASS_UPSTREAM ?? "https://api.anthropic.com",
+    evictAfterAssistantTurns: envInt("ONEPASS_EVICT_AFTER_TURNS", 8),
+    protectLastAssistantTurns: envInt("ONEPASS_PROTECT_LAST_TURNS", 4),
+    // 80k, not the 110k this shipped with: with a batch minimum in front of it, a lower threshold
+    // buys a flatter curve for a handful of larger trips rather than a swarm of small ones
+    // (docs/findings.md §21). Below it the proxy is inert, so T is what decides when it starts.
+    tripThresholdTokens: envInt("ONEPASS_TRIP_TOKENS", 80_000),
+    batchMinTokens: envInt("ONEPASS_BATCH_MIN_TOKENS", 20_000),
+    minSavedChars: envInt("ONEPASS_MIN_SAVED_CHARS", 50),
+    logFilePath: newProxyLogPath(),
+    ...(process.env.ONEPASS_DUMP_DIR !== undefined && process.env.ONEPASS_DUMP_DIR !== ""
+        ? { dumpDir: process.env.ONEPASS_DUMP_DIR }
+        : {}),
+};
+const server = createProxyServer(config);
+server.on("error", (err) => {
+    if (err.code === "EADDRINUSE") {
+        console.error(`[onepass] port ${port} is already in use — is another onepass-proxy running?`);
+        process.exit(1);
+    }
+    throw err;
+});
+server.listen(port, host, () => {
+    // The requested port may be 0; what a caller has to connect to is the one that got bound.
+    const boundPort = server.address().port;
+    console.log(`[onepass] eviction proxy listening on http://${host}:${boundPort}`);
+    console.log(`[onepass] upstream: ${config.upstreamUrl}`);
+    console.log(`[onepass] evict after N=${config.evictAfterAssistantTurns} assistant turns, ` +
+        `protect last K=${config.protectLastAssistantTurns}, trip over T=${config.tripThresholdTokens} real tokens (live-calibrated), ` +
+        `min chars saved per stub ${config.minSavedChars}, batch min ${config.batchMinTokens} tokens`);
+    console.log(`[onepass] log: ${config.logFilePath}`);
+    // The flag keeps native-1M models at 1M: Claude Code caps them at 200k behind a non-api.anthropic.com host.
+    console.log(`[onepass] point Claude Code at it:  ` +
+        `ANTHROPIC_BASE_URL=http://${host}:${boundPort} _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL=1 claude`);
+});

package/dist/recall.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+// `onepass-recall` — the MCP server that reads this session's original history back off disk.
+//
+// Half of Onepass by itself: the proxy may only evict what can be recovered verbatim, and this
+// is what recovers it. Its `recall_search` description is also where the legend for the proxy's
+// stubs lives, so a stub does not have to repeat the recovery hint in every block.
+import { readFileSync, appendFileSync, mkdirSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { transcriptForSession } from "./transcript.js";
+const CALL_LOG = join(homedir(), ".onepass", "recall-calls.log");
+const MAX_RESULT_CHARS = 8000;
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function blockToText(block) {
+    const type = block.type;
+    if (type === "text" && typeof block.text === "string")
+        return block.text;
+    if (type === "thinking" && typeof block.thinking === "string")
+        return block.thinking;
+    if (type === "tool_use")
+        return JSON.stringify(block.input ?? {});
+    if (type === "tool_result")
+        return typeof block.content === "string" ? block.content : JSON.stringify(block.content ?? "");
+    return "";
+}
+function parseTranscript(path) {
+    const entries = [];
+    // tool_use carries the name and file path; the matching tool_result only carries an id.
+    const toolById = new Map();
+    for (const line of readFileSync(path, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(parsed))
+            continue;
+        const message = parsed.message;
+        if (!isRecord(message))
+            continue;
+        const content = message.content;
+        if (!Array.isArray(content))
+            continue;
+        const kind = typeof parsed.type === "string" ? parsed.type : "unknown";
+        const timestamp = typeof parsed.timestamp === "string" ? parsed.timestamp : "";
+        for (const block of content) {
+            if (!isRecord(block))
+                continue;
+            const body = blockToText(block);
+            if (!body.trim())
+                continue;
+            let toolName;
+            let filePath;
+            if (block.type === "tool_use") {
+                toolName = typeof block.name === "string" ? block.name : undefined;
+                const input = block.input;
+                if (isRecord(input) && typeof input.file_path === "string")
+                    filePath = input.file_path;
+                if (typeof block.id === "string")
+                    toolById.set(block.id, { name: toolName ?? "?", filePath });
+            }
+            else if (block.type === "tool_result" && typeof block.tool_use_id === "string") {
+                const origin = toolById.get(block.tool_use_id);
+                toolName = origin?.name;
+                filePath = origin?.filePath;
+            }
+            entries.push({
+                ref: entries.length,
+                kind: block.type === "tool_result" ? "tool_result" : `${kind}:${String(block.type)}`,
+                timestamp,
+                toolName,
+                filePath,
+                body,
+            });
+        }
+    }
+    return entries;
+}
+function truncate(text) {
+    if (text.length <= MAX_RESULT_CHARS)
+        return text;
+    return `${text.slice(0, MAX_RESULT_CHARS)}\n\n…[truncated ${text.length - MAX_RESULT_CHARS} chars — narrow your query for the rest]`;
+}
+function logCall(tool, args, outcome) {
+    const line = JSON.stringify({ at: new Date().toISOString(), tool, args, outcome });
+    try {
+        mkdirSync(dirname(CALL_LOG), { recursive: true });
+        appendFileSync(CALL_LOG, `${line}\n`);
+    }
+    catch {
+        // the log is spike instrumentation; never fail a recall because it could not be written
+    }
+    process.stderr.write(`[onepass-recall] ${line}\n`);
+}
+function loadEntries() {
+    const chosen = transcriptForSession(process.env, process.cwd());
+    if (chosen.path === null)
+        return { entries: [], error: chosen.reason };
+    return { entries: parseTranscript(chosen.path) };
+}
+const { version } = createRequire(import.meta.url)("../package.json");
+const server = new McpServer({ name: "onepass-recall", version });
+server.registerTool("recall_search", {
+    title: "Search the original conversation",
+    description: "Search the ORIGINAL, unmodified session history on disk — including turns that were removed from your context by compaction or tool-result clearing. " +
+        "Use this whenever you are about to state something about earlier work that you cannot actually see anymore: a file's contents, a command's output, a decision, or something that was tried and failed. " +
+        "The query is split on whitespace and each term matched separately — an entry matching only some terms is still returned, ranked below entries matching more. " +
+        "So throw several words at it rather than guessing one exact phrase. " +
+        "Returns matching entries with a `ref` — pass that ref to recall_get for the full content. " +
+        "Blocks marked `[onepass: evicted N chars]` were removed from your context by the Onepass proxy; the original is on disk and this tool finds it. " +
+        "A tool call whose `input` is an empty object was evicted the same way — its arguments are gone. " +
+        "To find one, search the path in the `call evicted, <path>` note on its result's stub, or the file names and error text around it. " +
+        "For an attached file, search the path from the `Called the Read tool` line beside it. " +
+        "For a task notification, search the task id. " +
+        "When you need the current state rather than what it was, read the file or re-run the command instead.",
+    inputSchema: {
+        query: z.string().describe("Words to look for, e.g. a filename, error message, or function name. Multiple words are matched independently, not as a phrase."),
+        limit: z.number().int().min(1).max(50).default(10).describe("Maximum matches to return"),
+    },
+}, async ({ query, limit }) => {
+    const { entries, error } = loadEntries();
+    if (error) {
+        logCall("recall_search", { query, limit }, "error");
+        return { content: [{ type: "text", text: error }] };
+    }
+    const terms = [...new Set(query.toLowerCase().split(/\s+/).filter(Boolean))];
+    if (!terms.length) {
+        logCall("recall_search", { query, limit }, "empty query");
+        return { content: [{ type: "text", text: "Empty query — pass at least one word." }] };
+    }
+    const scored = entries
+        .map((entry) => {
+        const haystack = `${entry.body}\n${entry.filePath ?? ""}`.toLowerCase();
+        return { entry, hits: terms.filter((term) => haystack.includes(term)) };
+    })
+        .filter(({ hits }) => hits.length > 0)
+        .sort((a, b) => b.hits.length - a.hits.length || b.entry.ref - a.entry.ref)
+        .slice(0, limit);
+    const matches = scored.map(({ entry, hits }) => {
+        // Anchor the snippet on the longest matched term: short terms like "ok" match everywhere
+        // and would centre the snippet on noise.
+        const anchor = hits.reduce((longest, term) => (term.length > longest.length ? term : longest));
+        const at = entry.body.toLowerCase().indexOf(anchor);
+        const from = Math.max(0, at - 100);
+        const snippet = entry.body.slice(from, from + 300).replace(/\s+/g, " ");
+        const label = [entry.kind, entry.toolName, entry.filePath].filter(Boolean).join(" ");
+        return `ref=${entry.ref}  ${label}  ${entry.timestamp}\n  matched ${hits.length}/${terms.length}: ${hits.join(", ")}\n  …${snippet}…`;
+    });
+    logCall("recall_search", { query, limit }, `${matches.length} matches of ${entries.length} entries`);
+    return {
+        content: [
+            {
+                type: "text",
+                text: matches.length
+                    ? `${matches.length} match(es) in the original history, best first:\n\n${matches.join("\n\n")}`
+                    : `No entry contains any of: ${terms.join(", ")} (searched ${entries.length} original entries).`,
+            },
+        ],
+    };
+});
+server.registerTool("recall_get", {
+    title: "Fetch one original entry",
+    description: "Fetch the full, original content of one entry by its `ref` (from recall_search). This is the unmodified text as it was at the time — not a summary.",
+    inputSchema: { ref: z.number().int().min(0).describe("The ref returned by recall_search") },
+}, async ({ ref }) => {
+    const { entries, error } = loadEntries();
+    if (error) {
+        logCall("recall_get", { ref }, "error");
+        return { content: [{ type: "text", text: error }] };
+    }
+    const entry = entries[ref];
+    if (!entry) {
+        logCall("recall_get", { ref }, "not found");
+        return { content: [{ type: "text", text: `No entry at ref=${ref}. Valid range 0..${entries.length - 1}.` }] };
+    }
+    logCall("recall_get", { ref }, `${entry.kind} ${entry.body.length} chars`);
+    const label = [entry.kind, entry.toolName, entry.filePath].filter(Boolean).join(" ");
+    return { content: [{ type: "text", text: `ref=${ref}  ${label}  ${entry.timestamp}\n\n${truncate(entry.body)}` }] };
+});
+await server.connect(new StdioServerTransport());

package/dist/report.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Reads a Claude Code session transcript (read-only) plus the proxy's JSONL log and prints:
+// compaction count, tokens evicted, tokens recalled, and per-request size over time.
+//
+//   npm run report -- <session-jsonl-path> [proxy-log-path]
+import { existsSync } from "node:fs";
+import { basename } from "node:path";
+import { formatThousands } from "./evict.js";
+import { latestProxyLogPath, proxyLogDir } from "./log.js";
+import { parseProxyLog, scanTranscript } from "./session.js";
+import { describeRebuild, formatDuration, GAUGE_MIN_ESTIMATED_TOKENS } from "./speed.js";
+const REBUILD_KINDS = ["first", "after-trip", "after-idle", "unexpected"];
+const BAR_WIDTH = 24;
+function timeOfDay(isoTimestamp) {
+    const timePart = isoTimestamp.split("T")[1];
+    return timePart === undefined ? isoTimestamp : timePart.slice(0, 8);
+}
+function collectDefined(requests, pick) {
+    return requests.map(pick).filter((value) => value !== undefined);
+}
+function median(values) {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((left, right) => left - right);
+    const middle = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[middle] : Math.round((sorted[middle - 1] + sorted[middle]) / 2);
+}
+function formatMedian(values) {
+    const middle = median(values);
+    return middle === null ? "n/a" : formatDuration(middle);
+}
+function formatMedianAndMax(values) {
+    const middle = median(values);
+    return middle === null ? "n/a" : `median ${formatDuration(middle)}, max ${formatDuration(Math.max(...values))}`;
+}
+/**
+ * A rebuild means Anthropic re-read the conversation instead of serving it from cache — a few
+ * extra seconds on that turn. It is normal on the session's first request, on the request
+ * where the proxy tripped, and after the cache expires. Anything else is a bug.
+ */
+function printSpeedSummary(requests) {
+    // Same floor the proxy applies: small side calls have their own cache prefix, so mixing them
+    // into the cached-versus-rebuilt comparison compares two different conversations.
+    const conversation = requests.filter((request) => (request.estimatedTokensSent ?? 0) >= GAUGE_MIN_ESTIMATED_TOKENS);
+    const rebuilt = conversation.filter((request) => request.rebuild !== undefined);
+    const cached = conversation.filter((request) => request.rebuild === undefined);
+    const byKind = REBUILD_KINDS.map((kind) => `${conversation.filter((request) => request.rebuild === kind).length} ${describeRebuild(kind)}`);
+    console.log("Speed:");
+    console.log(`  proxy's own time per request: ${formatMedianAndMax(collectDefined(requests, (r) => r.proxyMs))} ` +
+        `(over all ${requests.length} requests)`);
+    console.log(`  conversation requests, over ${formatThousands(GAUGE_MIN_ESTIMATED_TOKENS)} tokens ` +
+        `(smaller side calls are not gauged): ${conversation.length}`);
+    console.log(`    rebuilds: ${rebuilt.length} — ${byKind.join(", ")} (goal: 0 unexpected)`);
+    console.log(`    wait for the first byte: ${formatMedian(collectDefined(cached, (r) => r.upstreamFirstByteMs))} cached, ` +
+        `${formatMedian(collectDefined(rebuilt, (r) => r.upstreamFirstByteMs))} rebuilt`);
+    console.log("");
+}
+function ratioLine(tokensEvicted, tokensRecalled) {
+    if (tokensEvicted === 0)
+        return "n/a — nothing evicted";
+    if (tokensRecalled === 0)
+        return `${formatThousands(tokensEvicted)} : 0 — nothing recalled yet`;
+    return `${Math.round(tokensEvicted / tokensRecalled)} : 1`;
+}
+async function main() {
+    const [sessionPath, proxyLogArg] = process.argv.slice(2);
+    if (sessionPath === undefined) {
+        console.error("usage: onepass-report <session-jsonl-path> [proxy-log-path]");
+        process.exit(1);
+    }
+    if (!existsSync(sessionPath)) {
+        console.error(`no transcript at ${sessionPath}`);
+        process.exit(1);
+    }
+    const proxyLogPath = proxyLogArg ?? latestProxyLogPath();
+    const transcript = await scanTranscript(sessionPath);
+    const recalledTokens = Math.round(transcript.recallChars / 4);
+    console.log(`Onepass report — ${basename(sessionPath)}`);
+    console.log("");
+    console.log(`Transcript: ${sessionPath}`);
+    console.log(`  entries: ${transcript.entryCount}` +
+        (transcript.firstTimestamp !== null ? ` (${transcript.firstTimestamp} -> ${transcript.lastTimestamp})` : ""));
+    console.log(`  compactions: ${transcript.compactionCount}  (target: 0)`);
+    if (transcript.realUsageSamples > 0) {
+        console.log(`  peak real context (API-reported usage): ${formatThousands(transcript.realUsagePeak)} tokens ` +
+            `over ${transcript.realUsageSamples} assistant turns — ` +
+            `${transcript.realUsageTurnsAbove150k} above 150,000 (goal: 0)`);
+    }
+    console.log(`  recall results: ${transcript.recallResultCount} — ~${formatThousands(recalledTokens)} tokens recalled`);
+    console.log("");
+    if (proxyLogPath === null || !existsSync(proxyLogPath)) {
+        console.log(`Proxy log: none found at ${proxyLogPath ?? proxyLogDir} — start the proxy and run the session through it.`);
+        return;
+    }
+    const { requests, trips } = parseProxyLog(proxyLogPath);
+    const evictedIdCount = trips.reduce((sum, trip) => sum + trip.addedToolUseIds.length, 0);
+    const tripCharsRemoved = trips.reduce((sum, trip) => sum + trip.charsRemoved, 0);
+    const tokensEvictedOnce = Math.round(tripCharsRemoved / 4);
+    const cumulativeTokensKeptOut = requests.reduce((sum, request) => request.estimatedTokensBefore !== undefined && request.estimatedTokensSent !== undefined
+        ? sum + (request.estimatedTokensBefore - request.estimatedTokensSent)
+        : sum, 0);
+    console.log(`Proxy log: ${proxyLogPath}`);
+    console.log(`  /v1/messages requests: ${requests.length}`);
+    console.log(`  eviction trips: ${trips.length} — ${evictedIdCount} segments evicted, ` +
+        `${formatThousands(tripCharsRemoved)} chars removed`);
+    console.log(`  tokens evicted (one-time, chars/4): ${formatThousands(tokensEvictedOnce)}`);
+    console.log(`  tokens kept out of requests (cumulative over turns): ${formatThousands(cumulativeTokensKeptOut)}`);
+    console.log("");
+    console.log(`Product metric — tokens evicted : tokens recalled = ${ratioLine(tokensEvictedOnce, recalledTokens)}`);
+    console.log("");
+    if (requests.length === 0)
+        return;
+    printSpeedSummary(requests);
+    console.log("Per /v1/messages request (chart = estimated tokens sent; flat is good, unproxied it climbs):");
+    console.log(`  ${"#".padStart(4)}  ${"time".padEnd(8)}  ${"sent tok".padStart(9)}  ${"proxy".padStart(7)}  ` +
+        `${"1st byte".padStart(8)}  ${"cached".padStart(9)}  ${"new".padStart(7)}  chart`);
+    const maxSent = Math.max(...requests.map((request) => request.estimatedTokensSent ?? 0), 1);
+    const column = (value, format, width) => (value === undefined ? "-" : format(value)).padStart(width);
+    requests.forEach((request, index) => {
+        const sent = request.estimatedTokensSent ?? 0;
+        const before = request.estimatedTokensBefore ?? sent;
+        const bar = "#".repeat(Math.max(sent > 0 ? 1 : 0, Math.round((sent / maxSent) * BAR_WIDTH)));
+        const marks = [];
+        if ((request.newlyEvictedCount ?? 0) > 0)
+            marks.push("trip");
+        if (request.rebuild !== undefined) {
+            marks.push(request.rebuild === "unexpected" ? "REBUILD (unexpected)" : `rebuild (${describeRebuild(request.rebuild)})`);
+        }
+        console.log(`  ${String(index + 1).padStart(4)}  ${timeOfDay(request.timestamp)}  ${formatThousands(sent).padStart(9)}  ` +
+            `${column(request.proxyMs, formatDuration, 7)}  ${column(request.upstreamFirstByteMs, formatDuration, 8)}  ` +
+            `${column(request.cacheReadInputTokens, formatThousands, 9)}  ` +
+            `${column(request.cacheCreationInputTokens, formatThousands, 7)}  ` +
+            `${bar}${before !== sent ? `  (raw ${formatThousands(before)})` : ""}` +
+            `${marks.length === 0 ? "" : `  <- ${marks.join(", ")}`}`);
+    });
+}
+await main();