@reticlehq/server 2.14.0 → 3.2.0

package/dist/mcp/proxy-daemon-probe.js

@@ -1,54 +0,0 @@
-import * as net from 'node:net';
-import { LOOPBACK_HOST } from '@reticlehq/core';
-const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
-/**
- * How long to wait for the spawned daemon's port to accept connections before giving up. The default
- * suits a normal machine; a slow CI/VM (heavy headless-browser launch) can raise it via the
- * RETICLE_DAEMON_READY_TIMEOUT_MS env var. Invalid/absent values fall back to the default.
- */
-const envDaemonReadyTimeoutMs = Number(process.env['RETICLE_DAEMON_READY_TIMEOUT_MS']);
-const DAEMON_READY_TIMEOUT_MS = Number.isFinite(envDaemonReadyTimeoutMs) && envDaemonReadyTimeoutMs > 0
-    ? envDaemonReadyTimeoutMs
-    : DEFAULT_DAEMON_READY_TIMEOUT_MS;
-const DAEMON_POLL_INTERVAL_MS = 100;
-const DAEMON_POLL_MAX_INTERVAL_MS = 1_000;
-function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-export function daemonPollDelayMs(attempt) {
-    return Math.min(DAEMON_POLL_INTERVAL_MS * attempt, DAEMON_POLL_MAX_INTERVAL_MS);
-}
-/**
- * Returns true if something is already listening on the reticle port.
- * Uses a plain TCP probe so we don't create a side-effectful SSE session
- * inside the daemon just to check reachability.
- */
-export function probeDaemon(port) {
-    return new Promise((resolve) => {
-        const socket = new net.Socket();
-        socket.setTimeout(500);
-        socket.on('connect', () => {
-            socket.destroy();
-            resolve(true);
-        });
-        socket.on('error', () => resolve(false));
-        socket.on('timeout', () => {
-            socket.destroy();
-            resolve(false);
-        });
-        socket.connect(port, LOOPBACK_HOST);
-    });
-}
-/** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
-export async function waitForDaemon(port) {
-    const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
-    let attempt = 0;
-    while (Date.now() < deadline) {
-        const reachable = await probeDaemon(port);
-        if (reachable)
-            return;
-        attempt++;
-        await delay(daemonPollDelayMs(attempt));
-    }
-    throw new Error(`reticle daemon did not become ready on port ${port} within ${DAEMON_READY_TIMEOUT_MS}ms`);
-}

package/dist/mcp/proxy-handshake.js

@@ -1,192 +0,0 @@
-/**
- * Answer `initialize` when the daemon cannot.
- *
- * The proxy queues every client message until the daemon's SSE endpoint frame arrives. `initialize`
- * is a client message, so when the daemon port is held by something that accepts connections and
- * never serves SSE — a wedged daemon, a foreign process, a daemon leaked by another project — the
- * handshake waits on a thing that is never coming. Reported from the field as "initialize never
- * answers, no tools run at all"; reproduced with a listener that simply never responds.
- *
- * A hang is the worst possible outcome here: no tools, no diagnosis, nothing to retry. Completing
- * the handshake locally gives the agent a working surface whose FIRST tool call reports the real
- * problem through the no-session diagnostics that already exist.
- *
- * Safe because the proxy replays the client's own `initialize` to the daemon whenever a session is
- * finally established (see `replayLines`), so the daemon still gets its handshake in order.
- */
-import { SERVER_VERSION } from '../version/server-version.js';
-import { MCP_SERVER_NAME } from '@reticlehq/core';
-/** The version we answer with if the client proposed none. */
-const FALLBACK_PROTOCOL_VERSION = '2024-11-05';
-/**
- * The protocol's own way to say "the tool list you have is out of date, fetch it again".
- *
- * Load-bearing here rather than a nicety. When we answer `initialize` ourselves the catalog we serve
- * is one we made up, and it is usually empty. Nothing else in the protocol ever corrects that: a
- * client re-lists only when told to, and every other recovery path in the proxy is driven by the
- * NEXT client request, which a client holding no tools never makes. Without this the session is
- * connected, initialized and toolless until a human notices.
- */
-export const TOOLS_CHANGED_NOTIFICATION = 'notifications/tools/list_changed';
-function parseLine(line) {
-    try {
-        const parsed = JSON.parse(line);
-        return 'object' === typeof parsed && parsed !== null ? parsed : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** True when this queued client line is the handshake we answered ourselves. */
-export function isHandshakeLine(line) {
-    const msg = parseLine(line);
-    return 'initialize' === msg?.method || 'notifications/initialized' === msg?.method;
-}
-export function localInitializeResponse(line, 
-/**
- * What the daemon would have advertised, so the client is not left with none.
- *
- * A client reads `instructions` ONCE, at initialize, and this response is sent precisely when no
- * daemon is up to send its own — which is the first run of a fresh install. So the block telling
- * someone that having these tools is not the same as being set up was permanently absent for the
- * exact population it addresses, and the daemon's later correct instructions arrive at a client
- * that will never read the field again.
- *
- * Empty means "nothing to say", and the field is then omitted rather than sent blank.
- */
-instructions = '') {
-    const msg = parseLine(line);
-    if (null === msg || msg.method !== 'initialize')
-        return null;
-    // A notification carries no id and expects no reply; answering one is a protocol error.
-    if (msg.id === undefined || null === msg.id)
-        return null;
-    const proposed = msg.params?.protocolVersion;
-    return JSON.stringify({
-        jsonrpc: '2.0',
-        id: msg.id,
-        result: {
-            // Echo what the client asked for: answering with a version it did not offer is its own
-            // handshake failure.
-            protocolVersion: 'string' === typeof proposed ? proposed : FALLBACK_PROTOCOL_VERSION,
-            // `listChanged` is not decoration: a client that was not told the list can change has no
-            // reason to honour the notification we send when the daemon finally arrives, and declaring a
-            // capability we then rely on is the difference between a fix and a message into the void.
-            capabilities: { tools: { listChanged: true } },
-            serverInfo: { name: MCP_SERVER_NAME, version: SERVER_VERSION },
-            ...('' === instructions ? {} : { instructions }),
-        },
-    });
-}
-/**
- * The line that tells a client its tool list is stale, or null when there is nothing to correct.
- *
- * When a daemon arrives after we answered the handshake ourselves, the client is holding a tool list
- * we invented, and on a cold start that list is empty. Nothing else in this protocol corrects it: a
- * client re-lists only when told to, and every other recovery path in the proxy is driven by the
- * NEXT client request, which a client holding no tools never makes. Connected, initialized and
- * toolless for the rest of the session, with a human required to notice and reconnect by hand.
- *
- * Sent only when the catalog was ours. A client that completed a real handshake with the daemon
- * already has the true list, and telling it to refetch would be a round trip for nothing.
- *
- * Lives here rather than in the proxy because it belongs to the locally-answered handshake, which is
- * this module's subject.
- *
- * Worth knowing before relying on it: this is a best-effort correction, not the mechanism. Research
- * into the four clients we target found that only some honour `notifications/tools/list_changed` at
- * all, so the catalog still has to be right in the FIRST answer for the rest. This closes the gap
- * where it is honoured and costs one line where it is not.
- */
-export function toolsChangedNotification(catalogWasLocal) {
-    if (!catalogWasLocal)
-        return null;
-    return JSON.stringify({ jsonrpc: '2.0', method: TOOLS_CHANGED_NOTIFICATION });
-}
-/**
- * What a locally-answered handshake must say about itself.
- *
- * The proxy answering `initialize` is right — a hang gives the agent no tools AND no diagnosis — but
- * the response it sent was INDISTINGUISHABLE from a daemon's. Same `serverInfo`, same capabilities,
- * same `instructions`. So the client marked the server installed and enabled, the agent got a tool
- * list that was cached at best and empty at worst, and nothing anywhere connected the two facts.
- *
- * Reported from the field, from two different agent hosts at once: the marketplace showed Reticle
- * installed with the whole tool surface enabled, and the agent asked to verify a flow reported that
- * RETICLE WAS NOT PRESENT ON THE MACHINE — while the daemon was running and a browser session was
- * live. That conclusion is the reasonable reading of an empty surface with no explanation attached,
- * and it is unrecoverable: the proxy's own recovery is "the next client request re-probes the port",
- * and a client holding zero tools never makes another request.
- *
- * `instructions` is the channel because it is the only one that survives an empty catalog. It rides
- * on the initialize result, which SUCCEEDED, and every host we target puts it in front of the model.
- * A tool description cannot reach an agent that was handed no tools.
- *
- * The healthy block is kept underneath rather than replaced: an agent that IS about to get a working
- * surface (the common case — the first call wakes a daemon) still needs to know how to drive it.
- */
-export function degradedInstructions(healthy, port, reason) {
-    return `DEGRADED SURFACE — READ THIS BEFORE ANY reticle_* CALL: no Reticle daemon answered on port ${String(port)} (${reason}), so this handshake was completed by the Reticle MCP proxy itself, not by Reticle's daemon. Any tool list you were handed came from a cache or is empty — it is not evidence that anything is behind it.
-
-Reticle IS installed: this process is Reticle. Do NOT report it as missing, not present, or not installed — that is the wrong diagnosis and it is the one this state reliably produces. The right one is that the daemon is not reachable yet.
-
-Your next reticle_* call starts a daemon and then either works or fails with the specific reason. If you have NO reticle_* tools at all, say exactly that to the user and tell them to run \`reticle doctor\` in a terminal — it reports what is holding port ${String(port)} and whether a daemon can start at all.
-
-${healthy}`;
-}
-/**
- * The largest single JSON-RPC line the proxy will accumulate from a client.
- *
- * Generous — a tool call with a big argument payload is legitimate — but finite, because without a
- * ceiling the buffer grows to whatever is sent and the process is one `cat bigfile` away from an
- * out-of-memory exit that would take the agent's whole tool surface with it.
- */
-export const MAX_STDIN_LINE_BYTES = 16 * 1024 * 1024;
-/**
- * Append a chunk and split off whatever complete lines it produced.
- *
- * The reason this is not `(buffer + chunk).split('\n')` inline: that re-scans the WHOLE accumulated
- * buffer on every chunk, so a single large line costs O(n²) in the size of the line. Measured
- * against the real proxy, a 32 MB line took ~8s and a 50 MB line ~35s — with the event loop pinned
- * throughout, so every other tool call on that link was frozen with no response and no error. The
- * client sees the whole MCP surface hang.
- *
- * A chunk with no newline in it cannot complete a line, so there is nothing to split and the cost is
- * the concatenation alone. Only a chunk that actually carries a newline pays for a scan.
- */
-export function drainLines(buffer, chunk, maxLineBytes = MAX_STDIN_LINE_BYTES, discarding = false) {
-    // Finish discarding first. Everything up to and including the next newline belongs to the line
-    // that was already dropped, and only what follows it is a message again.
-    if (discarding) {
-        const cut = chunk.indexOf('\n');
-        if (-1 === cut)
-            return { lines: [], rest: '', overflowed: true, discarding: true };
-        return {
-            ...drainLines('', chunk.slice(cut + 1), maxLineBytes),
-            overflowed: true,
-        };
-    }
-    const next = buffer + chunk;
-    if (!chunk.includes('\n')) {
-        // Nothing can be complete yet. Cap here rather than on the split path: this is the branch an
-        // oversized line stays on, so it is the only one that can grow without bound. Dropping the
-        // buffer is half the job — the rest of that line is still coming, hence `discarding`.
-        if (next.length > maxLineBytes) {
-            return { lines: [], rest: '', overflowed: true, discarding: true };
-        }
-        return { lines: [], rest: next, overflowed: false, discarding: false };
-    }
-    const parts = next.split('\n');
-    const rest = parts.pop() ?? '';
-    // A completed line over the cap is dropped, not truncated: half a JSON-RPC message is not a
-    // message, and forwarding a prefix would be a parse error attributed to the client. Its newline
-    // has already arrived, so there is nothing left to swallow for it.
-    const oversizedLine = parts.some((line) => line.length > maxLineBytes);
-    const restOversized = rest.length > maxLineBytes;
-    return {
-        lines: oversizedLine ? parts.filter((line) => line.length <= maxLineBytes) : parts,
-        rest: restOversized ? '' : rest,
-        overflowed: oversizedLine || restOversized,
-        discarding: restOversized,
-    };
-}

package/dist/mcp/proxy-lifecycle.d.ts

@@ -1,92 +0,0 @@
-/**
- * When the proxy may start a daemon — the rule that keeps an idle install from looping forever.
- *
- * Two changes collided to produce a real regression, and this is the seam that prevents it coming
- * back. A daemon may now shut itself down when it has served nothing and no browser ever connected
- * (see daemon-usefulness.ts). The proxy separately learned to respawn a dead daemon, because one
- * that crashed or was stopped used to take the agent's whole Reticle surface with it. Together they
- * loop: the daemon exits as useless, the proxy immediately brings back a daemon that is equally
- * useless, which exits, forever. Measured with a 4s grace: four processes in 200 seconds. At the
- * real 300s grace that is a new process every five minutes for the many installs that never call a
- * tool, for as long as the editor is open.
- *
- * The rule that resolves it: a dropped stream is not demand. Reattach to a daemon that is already
- * there; otherwise go dormant and let the next thing the CLIENT asks for bring Reticle back.
- *
- * Extracted as pure functions because the decision used to live inside a closure where no test could
- * reach it — and a guard that re-implements the decision instead of calling it is insensitive to the
- * thing it claims to guard.
- */
-import { PortPresence } from '../daemon/port-presence.js';
-/** What to do when the SSE stream drops. */
-export declare const OnDrop: {
-    /** A daemon is listening — reattach to it. */
-    readonly REATTACH: "reattach";
-    /** Nothing is listening. Do NOT spawn: wait to be needed. */
-    readonly DORMANT: "dormant";
-};
-export type OnDrop = (typeof OnDrop)[keyof typeof OnDrop];
-/**
- * A stream drop only ever justifies reattaching, never spawning. This is the whole fix: the proxy
- * used to spawn here, which turned a daemon's own idle shutdown into a permanent respawn loop.
- *
- * It takes the PRESENCE, not a boolean. It used to take `daemonListening`, filled from a bare TCP
- * connect — a probe that cannot tell a Reticle daemon from anything else that accepts a socket. A
- * stranger on the bridge port therefore read as "a daemon is there", and since a stranger answers
- * and closes, every reattach dropped and reattached again: measured at nineteen reconnects in
- * forty-eight seconds, each logged as `reticle_mcp_proxy_reconnected`, forever. `probePresence`
- * already asks the second question and every human-facing command already uses it; this was the last
- * decision point still guessing from the first.
- */
-export declare function onStreamDrop(presence: PortPresence): OnDrop;
-/**
- * What to do when the reconnect budget runs out. Always DORMANT — never exit.
- *
- * The proxy used to `process.exit(1)` here, justified as "let the agent host respawn the proxy". No
- * host does that: a stdio MCP server that exits is marked DISCONNECTED, its tools disappear from the
- * session, and a human has to open /mcp and reconnect by hand. That is the worst thing this product
- * does to anyone, and it was deliberate.
- *
- * Exiting bought nothing. Dormant already covers every case exit was meant to: the handshake is
- * answered locally, `tools/list` is answered from the catalog cache, and the next client request
- * WAKES a daemon. The budget still exists — it decides when to stop burning CPU on retries, not
- * whether the server survives.
- */
-export declare function onReconnectBudgetSpent(): OnDrop;
-/**
- * What to do when queued requests expire with nothing connected. Always DORMANT.
- *
- * This is the hole that produced the worst report we have had: a first-run daemon came up wedged, the
- * proxy spent its budget against it, and from then on every call returned −32001 — including after
- * the human killed the wedged process and started a healthy daemon on the same port. The proxy never
- * looked again.
- *
- * The cause is a state that lies. `WAKE` clears `dormant` and starts a reconnect; if that reconnect
- * neither resolves nor rejects (exactly what a wedged port does — it accepts the socket and never
- * serves SSE), `dormant` stays false forever. Every later request then reads as "a reconnect is
- * already coming" and QUEUEs, the queue expires, and the request is answered with a failure. Nothing
- * in that loop ever re-probes the port, so a daemon that appears afterwards is invisible.
- *
- * Expiring the queue is the proof that the in-flight reconnect is not coming. Going dormant makes the
- * NEXT client request wake and re-probe — which is the only thing that can discover a daemon that
- * arrived late, and it costs nothing when one has not.
- */
-export declare function onQueueExpired(): OnDrop;
-/** What to do with a client message. */
-export declare const OnRequest: {
-    /** Connected — post it straight through. */
-    readonly SEND: "send";
-    /** Reconnecting already; hold it until the endpoint arrives. */
-    readonly QUEUE: "queue";
-    /** Dormant: this is demand. Start a daemon, reattach, then flush. */
-    readonly WAKE: "wake";
-};
-export type OnRequest = (typeof OnRequest)[keyof typeof OnRequest];
-/**
- * The client asking for something is the ONLY event that may start a daemon.
- *
- * `connected` means a session endpoint is in hand. When it is not, a dormant proxy wakes (spawning
- * if needed) and a merely-reconnecting one queues — the difference between "nothing is coming back
- * on its own" and "something already is".
- */
-export declare function onClientRequest(connected: boolean, dormant: boolean): OnRequest;

package/dist/mcp/proxy-lifecycle.js

@@ -1,100 +0,0 @@
-/**
- * When the proxy may start a daemon — the rule that keeps an idle install from looping forever.
- *
- * Two changes collided to produce a real regression, and this is the seam that prevents it coming
- * back. A daemon may now shut itself down when it has served nothing and no browser ever connected
- * (see daemon-usefulness.ts). The proxy separately learned to respawn a dead daemon, because one
- * that crashed or was stopped used to take the agent's whole Reticle surface with it. Together they
- * loop: the daemon exits as useless, the proxy immediately brings back a daemon that is equally
- * useless, which exits, forever. Measured with a 4s grace: four processes in 200 seconds. At the
- * real 300s grace that is a new process every five minutes for the many installs that never call a
- * tool, for as long as the editor is open.
- *
- * The rule that resolves it: a dropped stream is not demand. Reattach to a daemon that is already
- * there; otherwise go dormant and let the next thing the CLIENT asks for bring Reticle back.
- *
- * Extracted as pure functions because the decision used to live inside a closure where no test could
- * reach it — and a guard that re-implements the decision instead of calling it is insensitive to the
- * thing it claims to guard.
- */
-import { PortPresence } from '../daemon/port-presence.js';
-/** What to do when the SSE stream drops. */
-export const OnDrop = {
-    /** A daemon is listening — reattach to it. */
-    REATTACH: 'reattach',
-    /** Nothing is listening. Do NOT spawn: wait to be needed. */
-    DORMANT: 'dormant',
-};
-/**
- * A stream drop only ever justifies reattaching, never spawning. This is the whole fix: the proxy
- * used to spawn here, which turned a daemon's own idle shutdown into a permanent respawn loop.
- *
- * It takes the PRESENCE, not a boolean. It used to take `daemonListening`, filled from a bare TCP
- * connect — a probe that cannot tell a Reticle daemon from anything else that accepts a socket. A
- * stranger on the bridge port therefore read as "a daemon is there", and since a stranger answers
- * and closes, every reattach dropped and reattached again: measured at nineteen reconnects in
- * forty-eight seconds, each logged as `reticle_mcp_proxy_reconnected`, forever. `probePresence`
- * already asks the second question and every human-facing command already uses it; this was the last
- * decision point still guessing from the first.
- */
-export function onStreamDrop(presence) {
-    return PortPresence.DAEMON === presence ? OnDrop.REATTACH : OnDrop.DORMANT;
-}
-/**
- * What to do when the reconnect budget runs out. Always DORMANT — never exit.
- *
- * The proxy used to `process.exit(1)` here, justified as "let the agent host respawn the proxy". No
- * host does that: a stdio MCP server that exits is marked DISCONNECTED, its tools disappear from the
- * session, and a human has to open /mcp and reconnect by hand. That is the worst thing this product
- * does to anyone, and it was deliberate.
- *
- * Exiting bought nothing. Dormant already covers every case exit was meant to: the handshake is
- * answered locally, `tools/list` is answered from the catalog cache, and the next client request
- * WAKES a daemon. The budget still exists — it decides when to stop burning CPU on retries, not
- * whether the server survives.
- */
-export function onReconnectBudgetSpent() {
-    return OnDrop.DORMANT;
-}
-/**
- * What to do when queued requests expire with nothing connected. Always DORMANT.
- *
- * This is the hole that produced the worst report we have had: a first-run daemon came up wedged, the
- * proxy spent its budget against it, and from then on every call returned −32001 — including after
- * the human killed the wedged process and started a healthy daemon on the same port. The proxy never
- * looked again.
- *
- * The cause is a state that lies. `WAKE` clears `dormant` and starts a reconnect; if that reconnect
- * neither resolves nor rejects (exactly what a wedged port does — it accepts the socket and never
- * serves SSE), `dormant` stays false forever. Every later request then reads as "a reconnect is
- * already coming" and QUEUEs, the queue expires, and the request is answered with a failure. Nothing
- * in that loop ever re-probes the port, so a daemon that appears afterwards is invisible.
- *
- * Expiring the queue is the proof that the in-flight reconnect is not coming. Going dormant makes the
- * NEXT client request wake and re-probe — which is the only thing that can discover a daemon that
- * arrived late, and it costs nothing when one has not.
- */
-export function onQueueExpired() {
-    return OnDrop.DORMANT;
-}
-/** What to do with a client message. */
-export const OnRequest = {
-    /** Connected — post it straight through. */
-    SEND: 'send',
-    /** Reconnecting already; hold it until the endpoint arrives. */
-    QUEUE: 'queue',
-    /** Dormant: this is demand. Start a daemon, reattach, then flush. */
-    WAKE: 'wake',
-};
-/**
- * The client asking for something is the ONLY event that may start a daemon.
- *
- * `connected` means a session endpoint is in hand. When it is not, a dormant proxy wakes (spawning
- * if needed) and a merely-reconnecting one queues — the difference between "nothing is coming back
- * on its own" and "something already is".
- */
-export function onClientRequest(connected, dormant) {
-    if (connected)
-        return OnRequest.SEND;
-    return dormant ? OnRequest.WAKE : OnRequest.QUEUE;
-}

package/dist/mcp/proxy-log.d.ts

@@ -1,63 +0,0 @@
-/**
- * The MCP proxy's own log file: where it lives, what bounds it, and how it is written.
- *
- * Split out of mcp-proxy.ts, which is the transport. This is housekeeping for a file, and the two
- * share nothing but a port number — the proxy calls `proxyLog`, and everything else here exists to
- * keep that file from becoming the largest thing on the user's disk.
- */
-/**
- * How much the proxy may append between size checks.
- *
- * Statting the file on every line would be a syscall per log line on a process that logs from a
- * reconnect loop. Counting what we wrote costs nothing and is exact enough, because this process is
- * the only writer of its own log. Well under the cap, so the cap is a cap rather than a suggestion.
- */
-export declare const PROXY_LOG_CHECK_BYTES: number;
-/**
- * Keep the proxy log under the same cap as the daemon log, without a stat per write.
- *
- * Returns the new "bytes since the last check" counter, so the accounting is testable without a
- * filesystem. Rotation itself is `rotateDaemonLog` — the proxy log had no cap at all while the
- * daemon log on the SAME machine stayed small, which is the whole of this defect.
- */
-export declare function accountProxyLogWrite(bytesSinceCheck: number, written: number, path: string, deps: {
-    fileSize(p: string): number;
-    renameFile(from: string, to: string): void;
-}): number;
-/**
- * Reclaim a proxy log that a previous process already let run away. Returns the bytes reclaimed.
- *
- * Reported from the field: one machine's `proxy-4400.log` reached a third of a 460GB disk and broke
- * builds, Docker and ordinary shell commands with ENOSPC. Nothing in Reticle degraded first, so the
- * failure surfaced as the operating system refusing to write files. Files like that exist on real
- * machines now, and the cap alone does not help them: the user should not have to find one with `du`.
- *
- * TRUNCATED IN PLACE, never renamed or unlinked. A rename moves the bytes without reclaiming a byte,
- * and a file that a running process still holds open keeps its blocks allocated after an unlink
- * until that handle closes — which is why the reporter recovered with `: > ~/.reticle/proxy-4400.log`
- * and why that is the operation to copy here.
- *
- * Best-effort, in the same spirit as `rotateDaemonLog`: refusing to start the MCP server over
- * housekeeping is strictly worse than a large file.
- */
-export declare function recoverOversizedProxyLog(path: string, deps: {
-    fileSize(p: string): number;
-    truncateFile(p: string): void;
-}, max?: number): number;
-/** Name the proxy log after the port it serves. Called before anything can log. */
-export declare function setProxyLogPort(port: number): void;
-/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
-export declare function proxyLogPath(port?: number | undefined): string;
-/**
- * Log to stderr (which the agent host usually swallows) AND to ~/.reticle/proxy-<port>.log, which it
- * does not. A dropped MCP connection is invisible from the agent's side — no message, no exit code —
- * so the one thing that makes it diagnosable at all is a file somebody can read afterwards.
- *
- * EXPORTED because the crash handlers need it. `installProxyResilience` was wired to the bare stderr
- * logger, so the proxy's own uncaught exceptions and unhandled rejections — the exact events that
- * present to a human as "the MCP server disconnected" — were written to a stream the editor throws
- * away. The handler ran, the process kept serving, and the reason went nowhere. Reported as "the
- * proxy has no log file… when it dies the diagnostic dies with it", which was half right: the file
- * existed, and the one path that most needed it was not using it.
- */
-export declare function proxyLog(event: string, fields?: Record<string, unknown>): void;

package/dist/mcp/proxy-log.js

@@ -1,132 +0,0 @@
-/**
- * The MCP proxy's own log file: where it lives, what bounds it, and how it is written.
- *
- * Split out of mcp-proxy.ts, which is the transport. This is housekeeping for a file, and the two
- * share nothing but a port number — the proxy calls `proxyLog`, and everything else here exists to
- * keep that file from becoming the largest thing on the user's disk.
- */
-import { appendFileSync, mkdirSync, renameSync, statSync, truncateSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { ReticleDir } from '@reticlehq/core';
-import { log } from '../log.js';
-import { MAX_DAEMON_LOG_BYTES, rotateDaemonLog } from '../daemon/daemon.js';
-/**
- * Which port this proxy serves, for the log file name. Set once at startup.
- *
- * One file per port, matching `daemon-<port>.log`. A single shared file interleaved every proxy on
- * the machine into one stream, so the first question anyone asks of it — "what happened to MY
- * session?" — needed a filter before it could be answered.
- */
-let logPort;
-/**
- * How much the proxy may append between size checks.
- *
- * Statting the file on every line would be a syscall per log line on a process that logs from a
- * reconnect loop. Counting what we wrote costs nothing and is exact enough, because this process is
- * the only writer of its own log. Well under the cap, so the cap is a cap rather than a suggestion.
- */
-export const PROXY_LOG_CHECK_BYTES = 256 * 1024;
-/** Appended since the last real size check. Reset by every check, whatever the check decides. */
-let bytesSinceProxyLogCheck = 0;
-/**
- * Keep the proxy log under the same cap as the daemon log, without a stat per write.
- *
- * Returns the new "bytes since the last check" counter, so the accounting is testable without a
- * filesystem. Rotation itself is `rotateDaemonLog` — the proxy log had no cap at all while the
- * daemon log on the SAME machine stayed small, which is the whole of this defect.
- */
-export function accountProxyLogWrite(bytesSinceCheck, written, path, deps) {
-    const total = bytesSinceCheck + written;
-    if (PROXY_LOG_CHECK_BYTES > total)
-        return total;
-    rotateDaemonLog(path, deps);
-    return 0;
-}
-/**
- * Reclaim a proxy log that a previous process already let run away. Returns the bytes reclaimed.
- *
- * Reported from the field: one machine's `proxy-4400.log` reached a third of a 460GB disk and broke
- * builds, Docker and ordinary shell commands with ENOSPC. Nothing in Reticle degraded first, so the
- * failure surfaced as the operating system refusing to write files. Files like that exist on real
- * machines now, and the cap alone does not help them: the user should not have to find one with `du`.
- *
- * TRUNCATED IN PLACE, never renamed or unlinked. A rename moves the bytes without reclaiming a byte,
- * and a file that a running process still holds open keeps its blocks allocated after an unlink
- * until that handle closes — which is why the reporter recovered with `: > ~/.reticle/proxy-4400.log`
- * and why that is the operation to copy here.
- *
- * Best-effort, in the same spirit as `rotateDaemonLog`: refusing to start the MCP server over
- * housekeeping is strictly worse than a large file.
- */
-export function recoverOversizedProxyLog(path, deps, max = MAX_DAEMON_LOG_BYTES) {
-    try {
-        const size = deps.fileSize(path);
-        if (max >= size)
-            return 0;
-        deps.truncateFile(path);
-        return size;
-    }
-    catch {
-        return 0;
-    }
-}
-/** The real filesystem behind the two rotation helpers. */
-const proxyLogFileOps = {
-    fileSize: (p) => statSync(p).size,
-    renameFile: (from, to) => renameSync(from, to),
-    truncateFile: (p) => truncateSync(p, 0),
-};
-/** Name the proxy log after the port it serves. Called before anything can log. */
-export function setProxyLogPort(port) {
-    logPort = port;
-    // The one moment we know a size check is worth its syscall, and the only place a file inherited
-    // from an older build can be brought back under control.
-    const reclaimed = recoverOversizedProxyLog(proxyLogPath(port), proxyLogFileOps);
-    if (0 < reclaimed) {
-        proxyLog('reticle_mcp_proxy_log_truncated', {
-            port,
-            reclaimedBytes: reclaimed,
-            note: 'the proxy log had grown past its cap and was truncated in place to reclaim the space',
-        });
-    }
-}
-/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
-export function proxyLogPath(port = logPort) {
-    const name = port === undefined ? 'mcp-proxy.log' : `proxy-${String(port)}.log`;
-    return join(homedir(), ReticleDir.ROOT, name);
-}
-/**
- * Log to stderr (which the agent host usually swallows) AND to ~/.reticle/proxy-<port>.log, which it
- * does not. A dropped MCP connection is invisible from the agent's side — no message, no exit code —
- * so the one thing that makes it diagnosable at all is a file somebody can read afterwards.
- *
- * EXPORTED because the crash handlers need it. `installProxyResilience` was wired to the bare stderr
- * logger, so the proxy's own uncaught exceptions and unhandled rejections — the exact events that
- * present to a human as "the MCP server disconnected" — were written to a stream the editor throws
- * away. The handler ran, the process kept serving, and the reason went nowhere. Reported as "the
- * proxy has no log file… when it dies the diagnostic dies with it", which was half right: the file
- * existed, and the one path that most needed it was not using it.
- */
-export function proxyLog(event, fields = {}) {
-    log(event, fields);
-    try {
-        const dir = join(homedir(), ReticleDir.ROOT);
-        mkdirSync(dir, { recursive: true });
-        // WITH A TIMESTAMP. This file is the only record of an outage that survives the session, and
-        // without one it cannot answer the two questions anyone brings to it: when did this happen, and
-        // how often. A real 3,283-line log on a dev machine held a `gave_up` — the exact event that used
-        // to precede `process.exit(1)` and cost the human a manual /mcp reconnect — and it was
-        // impossible to tell whether it happened during that person's work or a test run hours earlier.
-        // Evidence you cannot place in time is an anecdote.
-        const path = proxyLogPath();
-        const line = `${JSON.stringify({ t: new Date().toISOString(), event, ...fields })}\n`;
-        appendFileSync(path, line, 'utf8');
-        // A single proxy process is long-lived and logs from a reconnect loop, so rotating only at
-        // startup would leave the growth this file is capable of entirely unchecked while it runs.
-        bytesSinceProxyLogCheck = accountProxyLogWrite(bytesSinceProxyLogCheck, Buffer.byteLength(line, 'utf8'), path, proxyLogFileOps);
-    }
-    catch {
-        // Logging must never be the thing that kills the proxy.
-    }
-}

package/dist/mcp/server-instructions.d.ts

@@ -1,18 +0,0 @@
-interface InstructionState {
-    /**
-     * Has an app ever connected to Reticle for this project, on this port?
-     *
-     * Read from the durable connection memory rather than from the live session list: a daemon four
-     * seconds old has no sessions and that says nothing about whether the app is wired. The question
-     * is whether this install has EVER worked, not whether it is working this second.
-     */
-    previouslyConnected: boolean;
-}
-/** The instructions this daemon should advertise, given what it knows about the project. */
-/**
- * Instructions are sent ONCE at initialize; the tool surface is re-sent every turn. Measured on this
- * server: 621 tokens here against 5,480 per turn there, so anything true of every tool belongs in
- * this block rather than repeated across sixteen parameter descriptions. See shared-params.ts.
- */
-export declare function buildServerInstructions(state: InstructionState): string;
-export {};