onepass-proxy 0.3.0

package/dist/evict.js

@@ -0,0 +1,416 @@
+// Pure transform over an Anthropic POST /v1/messages request body: replaces old, large,
+// recoverable context segments with short deterministic stubs. Four segment kinds by rule:
+//   - tool_result blocks (recover: re-run the tool / re-read the file, or recall)
+//   - tool_use inputs — the calls themselves (recover: the edit already landed on disk and the
+//     command already ran, so read the file or re-run it, or recall)
+//   - attached file content the harness injects as "<system-reminder>\nResult of calling the
+//     Read tool:" user text (recover: read the file from disk, or recall)
+//   - "<task-notification>" user text (recover: read the task's output file, or recall)
+// The whitelist is the whole of it: the user's own text is never touched, and neither is
+// anything else injected — CLAUDE.md instructions, skill and agent listings, compaction
+// summaries — which stay protected by omission.
+// No I/O — the caller owns the evicted-id set, the threshold state, and logging.
+import { createHash } from "node:crypto";
+/**
+ * The alarm line sits this far above T. Peaks already run ~30k over T and a held-back batch adds up
+ * to the batch minimum, so a request past it means the floor itself has grown too big. There is
+ * deliberately no line above which the minimum is waived: that would bring the tiny trips back in
+ * exactly the sessions where they cost most.
+ */
+export const ALARM_LINE_MARGIN_TOKENS = 40_000;
+export const STUB_PREFIX = "[onepass: evicted";
+// Wire formats measured from real Claude Code requests (docs/findings.md §13). Prefix-matched
+// exactly: any drift in the harness makes the proxy skip the segment, never mis-evict it.
+const ATTACHED_FILE_PREFIX = "<system-reminder>\nResult of calling the Read tool:";
+const TASK_NOTIFICATION_PREFIX = "<task-notification>";
+const READ_INPUT_PREFIX = "<system-reminder>\nCalled the Read tool with the following input:";
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** For each message, how many assistant messages follow it — the age every gate here reads. */
+function assistantTurnsAfterByMessage(messages) {
+    const turnsAfter = new Array(messages.length).fill(0);
+    let assistantsSeen = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        turnsAfter[i] = assistantsSeen;
+        const message = messages[i];
+        if (isRecord(message) && message.role === "assistant")
+            assistantsSeen++;
+    }
+    return turnsAfter;
+}
+export function formatThousands(n) {
+    return String(n).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+export function estimateTokens(value, charsPerToken = 4) {
+    try {
+        const json = JSON.stringify(value);
+        return json === undefined ? 0 : Math.round(json.length / charsPerToken);
+    }
+    catch {
+        return 0;
+    }
+}
+export function measureContentChars(content) {
+    if (typeof content === "string")
+        return content.length;
+    if (content === undefined || content === null)
+        return 0;
+    try {
+        const json = JSON.stringify(content);
+        return json === undefined ? 0 : json.length;
+    }
+    catch {
+        return 0;
+    }
+}
+function sanitizeForStub(text) {
+    return text.replace(/\s+/g, " ").replace(/"/g, "'").trim();
+}
+// Deterministic on purpose: the same request must always produce the same bytes, or the
+// stubs themselves would break the prompt-cache prefix they exist to protect.
+//
+// The stub names nothing on its own: the tool_use beside it still carries the call's `name`,
+// and where that call was stubbed too its path is appended here by
+// `nameEvictedCallsInResultStubs` — once, in the one block of the pair the model never writes.
+// How to get any of it back is one sentence in the recall tool's description
+// (spike/src/server.ts). Naming the target in every stub is what made stubs the largest thing
+// in the request they exist to shrink: 12% of the measured peak (docs/findings.md §15).
+function buildEvictedStub(originalChars) {
+    return `${STUB_PREFIX} ${formatThousands(originalChars)} chars]`;
+}
+// A stubbed call keeps nothing at all: the API rejects a tool_use whose `input` is not an
+// object, so `{}` is the smallest legal stub.
+//
+// The shape this replaced was `{ file_path | command, evicted }`, and the model copied it into
+// calls it meant to make — every Bash imitation truncating its own command at exactly the 80
+// chars this file used to truncate at, on commands the session had never run. Whatever sits in
+// this slot is written in the agent's own voice, which is why it gets copied; the identical
+// marker text in 361 tool *results* was copied zero times (docs/findings.md §18).
+//
+// Emptiness is copied too — run 6 imitated `{}` three times in 557 turns, at a higher share of
+// calls stubbed than run 5's 11. What it cannot do is become a valid call: every tool the agent
+// uses has a required parameter, so an imitated `{}` is rejected on the spot and costs one turn.
+// That is the property the old shape lacked, where a stubbed Bash call kept a truncated
+// `{ command }` that would have run.
+const EMPTY_CALL_INPUT_CHARS = measureContentChars({});
+/** File path from a call's input, when it has one. Moves to the paired result's stub. */
+function callPathFrom(input) {
+    if (typeof input.file_path === "string")
+        return input.file_path;
+    return typeof input.path === "string" ? input.path : undefined;
+}
+// Appended to the stub of a result whose own call was stubbed too, so the pair still says which
+// file it was. Safe here and not in the call: the model never writes a tool_result block.
+// A command is deliberately not carried over — a truncated one is no better a recall key than
+// the file paths and error text already in the request, and re-teaching truncation is the
+// failure this stub exists to avoid.
+function buildEvictedCallSuffix(callPath) {
+    return callPath === undefined ? "; call evicted" : `; call evicted, ${callPath}`;
+}
+/**
+ * Chars a stubbed call costs: its emptied input, plus the suffix its result's stub gains for it.
+ * Charged whole even when the result stays live and never gains the suffix, which only ever
+ * makes the size floor stricter.
+ */
+function evictedCallChars(callPath) {
+    return EMPTY_CALL_INPUT_CHARS + buildEvictedCallSuffix(callPath).length;
+}
+// Names no path either: the "Called the Read tool with the following input" marker beside the
+// attachment carries it, and that marker is never evicted.
+function buildAttachedFileStub(originalChars) {
+    return `${STUB_PREFIX} attached file, ${formatThousands(originalChars)} chars]`;
+}
+// The one stub that still names its target: nothing else in the request carries the task id or
+// the path its output was written to.
+function buildTaskNotificationStub(text, originalChars) {
+    const taskId = /<task-id>([^<]+)<\/task-id>/.exec(text)?.[1];
+    const outputFile = /<output-file>([^<]+)<\/output-file>/.exec(text)?.[1];
+    const idPart = taskId === undefined ? "" : ` ${sanitizeForStub(taskId)}`;
+    const outputPart = outputFile === undefined ? "" : `; output at ${sanitizeForStub(outputFile)}`;
+    return `${STUB_PREFIX} task notification${idPart}, ${formatThousands(originalChars)} chars${outputPart}]`;
+}
+/** Chars the segment costs once stubbed. */
+function stubbedChars(segment) {
+    return segment.kind === "call" ? evictedCallChars(segment.callPath) : segment.stubText.length;
+}
+/** Segment id for a text block: a content hash, so it re-matches when the client resends it. */
+export function textSegmentId(text) {
+    return `sha1:${createHash("sha1").update(text).digest("hex")}`;
+}
+/** Segment id for a tool_use input — distinct from the result's own `tool_use_id`. */
+export function callSegmentId(toolUseId) {
+    return `call:${toolUseId}`;
+}
+function collectSegments(messages) {
+    const assistantTurnsAfterIndex = assistantTurnsAfterByMessage(messages);
+    const segments = [];
+    const classifyText = (text, messageIndex, blockIndex) => {
+        // Never a segment: this marker is what names the path for the attached-file stub next to
+        // it, so evicting it would take the attachment's only remaining pointer with it.
+        if (text.startsWith(READ_INPUT_PREFIX))
+            return;
+        const id = textSegmentId(text);
+        let stubText;
+        if (text.startsWith(ATTACHED_FILE_PREFIX)) {
+            stubText = buildAttachedFileStub(text.length);
+        }
+        else if (text.startsWith(TASK_NOTIFICATION_PREFIX)) {
+            stubText = buildTaskNotificationStub(text, text.length);
+        }
+        else {
+            // Anything else in a user message is the user's own text, or something injected that no
+            // rule owns. Not a segment at all: the whitelist above is the whole of what may be evicted.
+            return;
+        }
+        segments.push({
+            kind: "text",
+            id,
+            messageIndex,
+            blockIndex,
+            contentChars: text.length,
+            assistantTurnsAfter: assistantTurnsAfterIndex[messageIndex] ?? 0,
+            alreadyStubShaped: text.startsWith(STUB_PREFIX),
+            stubText,
+        });
+    };
+    messages.forEach((message, messageIndex) => {
+        if (!isRecord(message))
+            return;
+        if (message.role === "assistant") {
+            if (!Array.isArray(message.content))
+                return;
+            message.content.forEach((block, blockIndex) => {
+                if (!isRecord(block) || block.type !== "tool_use" || typeof block.id !== "string")
+                    return;
+                const input = block.input;
+                if (!isRecord(input))
+                    return;
+                segments.push({
+                    kind: "call",
+                    id: callSegmentId(block.id),
+                    toolUseId: block.id,
+                    messageIndex,
+                    blockIndex,
+                    contentChars: measureContentChars(input),
+                    assistantTurnsAfter: assistantTurnsAfterIndex[messageIndex] ?? 0,
+                    // An empty input is the stub. A real call with no arguments reads the same, and gets
+                    // the same treatment either way: its stub would save nothing, so it is never a target.
+                    alreadyStubShaped: Object.keys(input).length === 0,
+                    callPath: callPathFrom(input),
+                });
+            });
+            return;
+        }
+        if (message.role !== "user")
+            return;
+        const content = message.content;
+        if (typeof content === "string") {
+            classifyText(content, messageIndex, null);
+            return;
+        }
+        if (!Array.isArray(content))
+            return;
+        content.forEach((block, blockIndex) => {
+            if (!isRecord(block))
+                return;
+            if (block.type === "tool_result" && typeof block.tool_use_id === "string") {
+                const contentChars = measureContentChars(block.content);
+                segments.push({
+                    kind: "tool_result",
+                    id: block.tool_use_id,
+                    messageIndex,
+                    blockIndex,
+                    contentChars,
+                    assistantTurnsAfter: assistantTurnsAfterIndex[messageIndex] ?? 0,
+                    alreadyStubShaped: typeof block.content === "string" && block.content.startsWith(STUB_PREFIX),
+                    stubText: buildEvictedStub(contentChars),
+                });
+            }
+            else if (block.type === "text" && typeof block.text === "string") {
+                classifyText(block.text, messageIndex, blockIndex);
+            }
+        });
+    });
+    return segments;
+}
+function applyStubs(messages, targets) {
+    if (targets.length === 0)
+        return { messages, charsRemoved: 0, stubbedIds: [] };
+    const targetsByMessage = new Map();
+    for (const target of targets) {
+        const forMessage = targetsByMessage.get(target.messageIndex);
+        if (forMessage === undefined)
+            targetsByMessage.set(target.messageIndex, [target]);
+        else
+            forMessage.push(target);
+    }
+    let charsRemoved = 0;
+    const stubbedIds = [];
+    const nextMessages = messages.map((message, messageIndex) => {
+        const forMessage = targetsByMessage.get(messageIndex);
+        if (forMessage === undefined || !isRecord(message))
+            return message;
+        // Only a text segment is ever a message's whole string content.
+        const wholeString = forMessage.find((target) => target.blockIndex === null);
+        if (wholeString !== undefined && wholeString.kind !== "call" && typeof message.content === "string") {
+            charsRemoved += wholeString.contentChars - stubbedChars(wholeString);
+            stubbedIds.push(wholeString.id);
+            return { ...message, content: wholeString.stubText };
+        }
+        if (!Array.isArray(message.content))
+            return message;
+        const targetByBlock = new Map();
+        for (const target of forMessage) {
+            if (target.blockIndex !== null)
+                targetByBlock.set(target.blockIndex, target);
+        }
+        const nextContent = message.content.map((block, blockIndex) => {
+            const target = targetByBlock.get(blockIndex);
+            if (target === undefined || !isRecord(block))
+                return block;
+            stubbedIds.push(target.id);
+            charsRemoved += target.contentChars - stubbedChars(target);
+            // A call stubs to a fresh empty input — never a shared one, since a body that stubs N
+            // calls to one aliased object is one stray write away from losing byte-determinism.
+            if (target.kind === "call")
+                return { ...block, input: {} };
+            return target.kind === "tool_result"
+                ? { ...block, content: target.stubText }
+                : { ...block, text: target.stubText };
+        });
+        return { ...message, content: nextContent };
+    });
+    return { messages: nextMessages, charsRemoved, stubbedIds };
+}
+/**
+ * Moves each stubbed call's path into the stub of its own result. Runs after the passes because
+ * only then is it known which calls were stubbed. Its cost is already charged to the call by
+ * `stubbedChars`, so there is nothing here to account for.
+ */
+function nameEvictedCallsInResultStubs(messages, 
+/** tool_use_id -> suffix, for pairs where this pass stubbed the call *and* its result. */
+suffixByToolUseId) {
+    if (suffixByToolUseId.size === 0)
+        return messages;
+    return messages.map((message) => {
+        if (!isRecord(message) || message.role !== "user" || !Array.isArray(message.content))
+            return message;
+        let changed = false;
+        const content = message.content.map((block) => {
+            if (!isRecord(block) || block.type !== "tool_result" || typeof block.tool_use_id !== "string")
+                return block;
+            const suffix = suffixByToolUseId.get(block.tool_use_id);
+            // An entry exists only where this pass stubbed this very result, so the content is a stub
+            // it just wrote and ends in the bracket being reopened. A live result has no entry.
+            if (suffix === undefined || typeof block.content !== "string")
+                return block;
+            changed = true;
+            return { ...block, content: `${block.content.slice(0, -1)}${suffix}]` };
+        });
+        return changed ? { ...message, content } : message;
+    });
+}
+export function evictContextSegments(body, alreadyEvictedIds, config) {
+    const estimatedTokensBefore = estimateTokens(body, config.charsPerToken);
+    const isAboveAlarmLine = (tokensSent) => tokensSent > config.tripThresholdTokens + ALARM_LINE_MARGIN_TOKENS;
+    const passthrough = {
+        body,
+        bodyChanged: false,
+        tripped: false,
+        newlyEvictedIds: [],
+        stubbedIds: [],
+        pressure: false,
+        charsRemoved: 0,
+        newlyEvictedCharsRemoved: 0,
+        estimatedTokensBefore,
+        estimatedTokensSent: estimatedTokensBefore,
+        aboveAlarmLine: isAboveAlarmLine(estimatedTokensBefore),
+    };
+    if (!isRecord(body) || !Array.isArray(body.messages))
+        return passthrough;
+    const messages = body.messages;
+    // A stub that saves too little is not worth the trip, and one no smaller than what it
+    // replaces would grow the request — with monotonic eviction re-paying that on every request
+    // after. A Read call is the case: emptying its input saves almost nothing, and most of that
+    // comes back as the path appended to its result's stub.
+    // Dropping the segment here keeps its id out of the evicted set entirely.
+    const candidates = collectSegments(messages).filter((segment) => !segment.alreadyStubShaped && segment.contentChars - stubbedChars(segment) >= config.minSavedChars);
+    // Monotonic: an id evicted on any earlier request is stubbed again on every request.
+    // The protected-window guard matters for text segments only: content re-attached after a
+    // fresh Read has the same hash, and stubbing the young copy would break the stub's own
+    // "read the file for current content" recovery path. (A tool_use_id never re-ages into
+    // the window, so the guard is a no-op for tool results.)
+    const existingTargets = candidates.filter((segment) => alreadyEvictedIds.has(segment.id) &&
+        segment.assistantTurnsAfter >= config.protectLastAssistantTurns);
+    const afterExisting = applyStubs(messages, existingTargets);
+    const estimatedTokensAfterExisting = afterExisting.stubbedIds.length > 0
+        ? estimateTokens({ ...body, messages: afterExisting.messages }, config.charsPerToken)
+        : estimatedTokensBefore;
+    const tripped = estimatedTokensAfterExisting > config.tripThresholdTokens;
+    const isNewTarget = (segment, minAge) => !alreadyEvictedIds.has(segment.id) &&
+        segment.assistantTurnsAfter >= minAge &&
+        segment.assistantTurnsAfter >= config.protectLastAssistantTurns;
+    const newTargets = tripped
+        ? candidates.filter((segment) => isNewTarget(segment, config.evictAfterAssistantTurns))
+        : [];
+    let afterNew = applyStubs(afterExisting.messages, newTargets);
+    // Pressure pass: a burst of fresh large results can leave the request above T with nothing
+    // aged past N yet. Rather than let the client cross its compaction threshold, relax the age
+    // gate down to K — the last K turns stay untouchable, everything older is fair game.
+    let pressure = false;
+    let afterPressure = { messages: afterNew.messages, charsRemoved: 0, stubbedIds: [] };
+    if (tripped) {
+        const stillOverThreshold = estimateTokens({ ...body, messages: afterNew.messages }, config.charsPerToken) > config.tripThresholdTokens;
+        if (stillOverThreshold) {
+            const alreadyTargeted = new Set(newTargets.map((target) => target.id));
+            const pressureTargets = candidates.filter((segment) => !alreadyTargeted.has(segment.id) && isNewTarget(segment, config.protectLastAssistantTurns));
+            if (pressureTargets.length > 0) {
+                pressure = true;
+                afterPressure = applyStubs(afterNew.messages, pressureTargets);
+            }
+        }
+    }
+    // The batch minimum, applied to the normal and pressure targets together: a trip rewrites the
+    // cached conversation from the first message it changes, so one that frees too little is held
+    // back whole. Nothing held back joins the evicted set, so all of it is a candidate again next
+    // request, when one more turn's worth may carry the batch over the line.
+    const batchChars = afterNew.charsRemoved + afterPressure.charsRemoved;
+    const heldBack = {};
+    if (batchChars > 0 && batchChars < config.batchMinTokens * config.charsPerToken) {
+        heldBack.heldBackTokens = Math.round(batchChars / config.charsPerToken);
+        pressure = false;
+        afterNew = { messages: afterExisting.messages, charsRemoved: 0, stubbedIds: [] };
+        afterPressure = afterNew;
+    }
+    const newlyEvictedIds = [...afterNew.stubbedIds, ...afterPressure.stubbedIds];
+    const stubbedIds = [...afterExisting.stubbedIds, ...newlyEvictedIds];
+    if (stubbedIds.length === 0)
+        return { ...passthrough, tripped, ...heldBack };
+    // A pair earns a suffix only when both halves were stubbed on this request: a live result
+    // still names its own file, and a live call still carries its own input.
+    const stubbed = new Set(stubbedIds);
+    const suffixByToolUseId = new Map();
+    for (const segment of candidates) {
+        if (segment.kind !== "call" || !stubbed.has(segment.id) || !stubbed.has(segment.toolUseId))
+            continue;
+        suffixByToolUseId.set(segment.toolUseId, buildEvictedCallSuffix(segment.callPath));
+    }
+    const namedMessages = nameEvictedCallsInResultStubs(afterPressure.messages, suffixByToolUseId);
+    const finalBody = { ...body, messages: namedMessages };
+    const estimatedTokensSent = estimateTokens(finalBody, config.charsPerToken);
+    return {
+        body: finalBody,
+        bodyChanged: true,
+        tripped,
+        newlyEvictedIds,
+        stubbedIds,
+        pressure,
+        charsRemoved: afterExisting.charsRemoved + afterNew.charsRemoved + afterPressure.charsRemoved,
+        newlyEvictedCharsRemoved: afterNew.charsRemoved + afterPressure.charsRemoved,
+        estimatedTokensBefore,
+        estimatedTokensSent,
+        ...heldBack,
+        aboveAlarmLine: isAboveAlarmLine(estimatedTokensSent),
+    };
+}

package/dist/launch.js

@@ -0,0 +1,176 @@
+// The decisions `claudep` makes before anything starts: what Claude Code is run with, which
+// transcript belongs to the session that just ended, and what the one-line summary says.
+//
+// Separated from `claudep.ts` so every decision here is testable without spawning anything.
+import { formatThousands } from "./evict.js";
+/**
+ * Claude Code's own subcommands. `claudep mcp list` is a question about the installation, not a
+ * session: starting a proxy for it would be pointless, and `--session-id` would be rejected.
+ * A subcommand is always the first argument, so a prompt that happens to read "doctor" is safe.
+ */
+const CLAUDE_SUBCOMMANDS = new Set([
+    "agents",
+    "attach",
+    "auth",
+    "auto-mode",
+    "doctor",
+    "gateway",
+    "import",
+    "install",
+    "kill",
+    "logs",
+    "mcp",
+    "plugin",
+    "plugins",
+    "project",
+    "respawn",
+    "rm",
+    "setup-token",
+    "stop",
+    "ultrareview",
+    "update",
+    "upgrade",
+]);
+/** Flags that answer and exit. Same reasoning as a subcommand: no session, so no proxy. */
+const INFO_FLAGS = new Set(["-v", "--version", "-h", "--help"]);
+/** Flags that mean the conversation already exists, so `claudep` must not name a new one. */
+const EXISTING_SESSION_FLAGS = new Set(["-c", "--continue", "-r", "--resume", "--session-id"]);
+/** True when these arguments ask Claude Code something instead of starting a session. */
+export function isPassthrough(args) {
+    const first = args[0];
+    if (first === undefined)
+        return false;
+    return CLAUDE_SUBCOMMANDS.has(first) || INFO_FLAGS.has(first);
+}
+/** True when the user is resuming: the session id is theirs to decide, not ours. */
+export function reusesExistingSession(args) {
+    return args.some((arg) => EXISTING_SESSION_FLAGS.has(arg) || arg.startsWith("--resume=") || arg.startsWith("--session-id="));
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * The session id the user named, when they named one. `--resume` with no value opens a picker
+ * and `--continue` names nothing, so both leave this null and the exit line says what it can.
+ */
+export function sessionIdFromArgs(args) {
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        for (const flag of ["--session-id", "--resume"]) {
+            if (arg === flag && UUID.test(args[index + 1] ?? ""))
+                return args[index + 1];
+            if (arg.startsWith(`${flag}=`)) {
+                const value = arg.slice(flag.length + 1);
+                if (UUID.test(value))
+                    return value;
+            }
+        }
+    }
+    return null;
+}
+/** Claude Code's arguments: ours first, then the user's, unchanged. */
+export function claudeArgs(userArgs, sessionId) {
+    return sessionId === null ? [...userArgs] : ["--session-id", sessionId, ...userArgs];
+}
+/**
+ * Claude Code's environment. The base URL is the proxy child; the first-party flag keeps a
+ * natively-1M model at 1M, which a non-`api.anthropic.com` base URL otherwise caps at 200k
+ * (README, "Known Claude Code interactions"). Gzip is dropped rather than overridden: a
+ * compressed body is forwarded untouched, so leaving it set would silently disable eviction.
+ */
+export function claudeEnv(base, port) {
+    const env = {
+        ...base,
+        ANTHROPIC_BASE_URL: `http://127.0.0.1:${port}`,
+        _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL: "1",
+    };
+    delete env.CLAUDE_CODE_GZIP_REQUEST_BODIES;
+    return env;
+}
+/**
+ * The proxy child's environment. `ONEPASS_*` settings pass through, so a user who wants a
+ * different threshold sets it in their shell as before. Two are pinned rather than passed:
+ * `ANTHROPIC_BASE_URL` is dropped, since in a shell that already has one, keeping it would chain
+ * this proxy through another one; and `ONEPASS_HOST` is forced to the loopback, because this
+ * child exists to serve the one session below it and nothing else should be able to reach it.
+ */
+export function proxyEnv(base) {
+    const env = { ...base, ONEPASS_PORT: "0", ONEPASS_HOST: "127.0.0.1" };
+    delete env.ANTHROPIC_BASE_URL;
+    return env;
+}
+/** Where the proxy forwards unless `ONEPASS_UPSTREAM` says otherwise (see main.ts). */
+const DEFAULT_UPSTREAM = "https://api.anthropic.com";
+/**
+ * `claudep` overwrites `ANTHROPIC_BASE_URL`, so a shell that pointed Claude Code at a gateway
+ * would silently lose it. Warn rather than obey: the fix is `ONEPASS_UPSTREAM`, which is what
+ * decides where the proxy forwards. Nothing is lost when the variable names the default
+ * upstream — that is where the proxy was going to send it anyway — so that case stays quiet.
+ */
+export function upstreamWarning(env) {
+    const base = env.ANTHROPIC_BASE_URL;
+    if (base === undefined || base === "")
+        return null;
+    if (env.ONEPASS_UPSTREAM !== undefined && env.ONEPASS_UPSTREAM !== "")
+        return null;
+    if (base.replace(/\/+$/, "") === DEFAULT_UPSTREAM)
+        return null;
+    return (`claudep: ignoring ANTHROPIC_BASE_URL=${base} — the proxy forwards to ${DEFAULT_UPSTREAM}. ` +
+        `Set ONEPASS_UPSTREAM to send it somewhere else.`);
+}
+/** The two lines of the child's banner `claudep` needs. Absent either, it is not ready yet. */
+export function parseBanner(text) {
+    const port = /listening on http:\/\/([^\s:]+):(\d+)/.exec(text);
+    const log = /^\[onepass\] log: (.+)$/m.exec(text);
+    if (port === null || log === null)
+        return null;
+    return { port: Number(port[2]), logFilePath: log[1].trim() };
+}
+/**
+ * Adds the recall MCP server to Claude Code's arguments, carrying this session's id so it reads
+ * this session's transcript and no other. Recall is half of Onepass: eviction is only safe
+ * because what it removes can be fetched back verbatim.
+ *
+ * A `--mcp-config` the user passed is extended rather than replaced — our entry is spliced in
+ * as one more value of their own flag. The `--mcp-config=x` spelling takes a single value and
+ * cannot be extended that way, and a second flag would replace theirs, so that one is declined
+ * out loud instead.
+ */
+export function withRecallMcp(args, recall) {
+    const config = JSON.stringify({
+        mcpServers: {
+            onepass: {
+                command: recall.node,
+                args: [recall.entry],
+                ...(recall.sessionId === null ? {} : { env: { ONEPASS_SESSION_ID: recall.sessionId } }),
+            },
+        },
+    });
+    const flagIndex = args.indexOf("--mcp-config");
+    if (flagIndex !== -1) {
+        return { args: [...args.slice(0, flagIndex + 1), config, ...args.slice(flagIndex + 1)], warning: null };
+    }
+    if (args.some((arg) => arg.startsWith("--mcp-config="))) {
+        return {
+            args: [...args],
+            warning: "claudep: --mcp-config=… keeps your servers but leaves out onepass recall, so evicted context " +
+                "cannot be fetched back. Use the spaced form (--mcp-config file.json) to get both.",
+        };
+    }
+    return { args: ["--mcp-config", config, ...args], warning: null };
+}
+/**
+ * The line printed after the session ends. One line, because it appears under a session the user
+ * has already finished reading; `onepass-report` is where the detail lives.
+ */
+export function summaryLine(summary) {
+    const { transcript, segmentsEvicted, tokensEvicted, peakSentTokens } = summary;
+    const peak = transcript?.peakContextTokens ?? peakSentTokens;
+    if (segmentsEvicted === 0) {
+        return `onepass: no eviction (peak ~${formatThousands(peak)} tokens)`;
+    }
+    const evicted = `onepass: evicted ${segmentsEvicted} segments (~${formatThousands(tokensEvicted)} tokens)`;
+    if (transcript === null) {
+        return `${evicted} — no transcript found, so recalls and compactions are unknown`;
+    }
+    return (`${evicted}, recalled ${transcript.recallResults}, compactions ${transcript.compactions} ` +
+        `(peak ~${formatThousands(peak)} tokens)`);
+}

package/dist/log.js

@@ -0,0 +1,53 @@
+import { createWriteStream, mkdirSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+export const proxyLogDir = join(homedir(), ".onepass");
+// One log file per proxy run, so a report never mixes metrics from unrelated runs.
+// The ISO timestamp in the name sorts lexically, so "latest" is a plain string max.
+const proxyLogFilePattern = /^proxy\.log\..+\.jsonl$/;
+export function newProxyLogPath() {
+    const startedAt = new Date().toISOString().replace(/[:.]/g, "-");
+    return join(proxyLogDir, `proxy.log.${startedAt}.jsonl`);
+}
+export function latestProxyLogPath() {
+    let names;
+    try {
+        names = readdirSync(proxyLogDir);
+    }
+    catch {
+        return null;
+    }
+    const logNames = names.filter((name) => proxyLogFilePattern.test(name)).sort();
+    const newest = logNames.at(-1);
+    return newest === undefined ? null : join(proxyLogDir, newest);
+}
+export function createProxyLogWriter(filePath) {
+    let stream = null;
+    let warned = false;
+    const warnOnce = (err) => {
+        if (warned)
+            return;
+        warned = true;
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[onepass] cannot write proxy log at ${filePath}: ${message}`);
+    };
+    return {
+        append(entry) {
+            try {
+                if (stream === null) {
+                    mkdirSync(dirname(filePath), { recursive: true });
+                    stream = createWriteStream(filePath, { flags: "a" });
+                    stream.on("error", warnOnce);
+                }
+                stream.write(`${JSON.stringify(entry)}\n`);
+            }
+            catch (err) {
+                warnOnce(err);
+            }
+        },
+        close() {
+            stream?.end();
+            stream = null;
+        },
+    };
+}