@reticlehq/server 2.11.0 → 2.13.0

package/dist/license/license-env.js

@@ -0,0 +1,148 @@
+/**
+ * Find an enterprise licence key the customer actually placed, wherever they reasonably placed it.
+ *
+ * The daemon folded in `<cwd>/.env` and nothing else. It is spawned without an explicit `cwd`, so it
+ * inherits whatever directory the editor launched the MCP server from — in a monorepo that is the
+ * workspace root while the key sits in the app's own `.env`, and under some editors it is the user's
+ * home. The key was never read, `describeLicense` reported `missing`, and every event that customer
+ * produced said they had no licence, which is indistinguishable from a customer who has none.
+ *
+ * That is the worst shape a licensing bug can take. A key that fails LOUDLY gets reported by the
+ * customer within the hour. A key that silently fails to register leaves them believing they are
+ * licensed and us believing they are not, and neither side finds out.
+ *
+ * Two directions, because the field hits both: DOWN one level into app directories (the daemon
+ * starts at the workspace root) and UP to the project root (the editor starts inside the app).
+ *
+ * ONLY the licence key is ever taken out of a file found this way, and that restriction is the point
+ * rather than an optimisation. Bulk-importing a `.env` discovered by walking would let a directory
+ * the caller never named rebind the daemon's port, its telemetry gate or its allowed origins — a far
+ * worse bug than the one this fixes. `loadDotEnv` still owns the local file, where importing
+ * everything is what the caller asked for.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { LICENSE_KEY_ENV } from './license.js';
+import { discoverProjectConfigs } from '../cli/config-discovery.js';
+/** The files a framework tells people to put secrets in, most specific first. */
+const ENV_FILES = ['.env.local', '.env'];
+/** Stop the upward walk here: a licence belongs to a project, not to a machine. */
+const ROOT_MARKERS = ['.git', 'package.json', 'pnpm-workspace.yaml'];
+/** A bound on the upward walk, so a pathological path cannot spin. */
+const MAX_DEPTH = 12;
+function readKey(file) {
+    try {
+        if (!existsSync(file))
+            return undefined;
+        for (const raw of readFileSync(file, 'utf8').split('\n')) {
+            const line = raw.trim();
+            if (0 === line.length || line.startsWith('#'))
+                continue;
+            const eq = line.indexOf('=');
+            if (eq <= 0)
+                continue;
+            if (line.slice(0, eq).trim() !== LICENSE_KEY_ENV)
+                continue;
+            const value = line.slice(eq + 1).trim();
+            const first = value[0];
+            const unquoted = ('"' === first || "'" === first) && value.endsWith(first) && value.length >= 2
+                ? value.slice(1, -1)
+                : value;
+            if (unquoted.length > 0)
+                return unquoted;
+        }
+    }
+    catch {
+        // A licence probe may never take the daemon down, and an unreadable file is not an error here.
+    }
+    return undefined;
+}
+function inDir(dir) {
+    for (const name of ENV_FILES) {
+        const found = readKey(join(dir, name));
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+function isRoot(dir) {
+    return ROOT_MARKERS.some((marker) => existsSync(join(dir, marker)));
+}
+/**
+ * The directories that hold a `.reticle.json`: the apps that were actually instrumented.
+ *
+ * This is the closest thing the daemon has to "the session's project directory", and it is the same
+ * discovery the no-session diagnosis uses to tell an agent where the app really is. Reusing it means
+ * the licence search and that diagnosis can never disagree about where the project lives.
+ *
+ * It replaced a guess at `apps/*` and `packages/*`, which missed exactly the repo shape
+ * `findWorkspaceApps` was written for: three apps at `web/`, `admin/` and `space/`.
+ */
+/**
+ * The conventional layout, kept as a fallback beside the declaration-driven search above.
+ *
+ * `discoverProjectConfigs` descends only into DECLARED workspaces, which is right and is what a real
+ * monorepo has. But `apps/web` with no `workspaces` entry is a shape people genuinely ship, and for
+ * a licence key the cost of one extra `readdir` is nothing against reporting a paying customer as
+ * unlicensed. Strictly widens coverage; it can never contradict the discovery, only add to it.
+ */
+const CONVENTIONAL_DIRS = ['apps', 'packages'];
+function inConventionalChildren(dir) {
+    for (const group of CONVENTIONAL_DIRS) {
+        const base = join(dir, group);
+        let entries;
+        try {
+            if (!existsSync(base) || !statSync(base).isDirectory())
+                continue;
+            entries = readdirSync(base);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const found = inDir(join(base, entry));
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return undefined;
+}
+function inDiscoveredProjects(dir) {
+    let found;
+    try {
+        found = discoverProjectConfigs(dir).found;
+    }
+    catch {
+        return undefined;
+    }
+    for (const config of found) {
+        const key = inDir(config.directory);
+        if (key !== undefined)
+            return key;
+    }
+    return undefined;
+}
+/**
+ * The key, or undefined. Never throws, never mutates anything the caller did not ask it to.
+ *
+ * A key already present in `env` always wins: that is the operator stating it explicitly, and a file
+ * silently overriding it is the surprise `loadDotEnv` already refuses to cause.
+ */
+export function licenseKeyFromEnvFiles(startDir, env = process.env) {
+    const existing = env[LICENSE_KEY_ENV];
+    if (existing !== undefined && existing.length > 0)
+        return existing;
+    let dir = startDir;
+    for (let depth = 0; depth < MAX_DEPTH; depth++) {
+        const here = inDir(dir) ?? inDiscoveredProjects(dir) ?? inConventionalChildren(dir);
+        if (here !== undefined)
+            return here;
+        if (isRoot(dir))
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}

package/dist/loopback-agent.d.ts

@@ -0,0 +1,31 @@
+import * as http from 'node:http';
+/**
+ * The one HTTP agent every loopback call in this process goes through.
+ *
+ * Without an `agent:`, Node hands the request to `http.globalAgent`, whose idle timeout is 5
+ * seconds. The MCP proxy's POST leg is one request per JSON-RPC message and an agent thinks for
+ * longer than five seconds between tool calls essentially always — so every single tool call opened
+ * a fresh TCP socket. On Windows that is the ephemeral-port / non-paged-pool exhaustion pattern, and
+ * the `ENOBUFS` it eventually raises killed the call outright.
+ *
+ * The numbers, each one a decision and not a taste:
+ *
+ * - `keepAlive: true` — the whole point: hold the socket open between calls so there is no churn to
+ *   exhaust anything with.
+ * - `timeout: LOOPBACK_IDLE_MS` (45s) — how long an idle socket is kept for reuse. It has to outlast
+ *   a model's think-time between two tool calls (which is what 5s failed to do) and it has to stay
+ *   BELOW the daemon's own keep-alive timeout, so that the client is always the side that retires a
+ *   socket. If the server closed first we would keep picking up sockets it had already closed, and
+ *   that failure looks exactly like the one case we refuse to retry (see `isRetryableConnectError`).
+ *   The daemon's side of that pact is `HTTP_KEEP_ALIVE_TIMEOUT_MS` in `http-server.ts`.
+ * - `keepAliveMsecs: 10_000` — TCP-level keep-alive probes on an idle socket, so a daemon that died
+ *   without a FIN is noticed rather than handed back out as a live connection.
+ * - `maxSockets: 8` — the proxy multiplexes ONE MCP client, whose calls are near enough serial; 8 is
+ *   generous headroom for overlapping notifications while capping the worst case far below anything
+ *   a port table would notice. Exceeding it queues rather than fails.
+ */
+export declare const LOOPBACK_IDLE_MS = 45000;
+/** Named separately because `http.Agent` does not expose its options back to a caller (or a test). */
+export declare const LOOPBACK_AGENT_OPTIONS: http.AgentOptions;
+export declare const loopbackAgent: http.Agent;
+export declare function isRetryableConnectError(err: unknown): boolean;

package/dist/loopback-agent.js

@@ -0,0 +1,57 @@
+import * as http from 'node:http';
+/**
+ * The one HTTP agent every loopback call in this process goes through.
+ *
+ * Without an `agent:`, Node hands the request to `http.globalAgent`, whose idle timeout is 5
+ * seconds. The MCP proxy's POST leg is one request per JSON-RPC message and an agent thinks for
+ * longer than five seconds between tool calls essentially always — so every single tool call opened
+ * a fresh TCP socket. On Windows that is the ephemeral-port / non-paged-pool exhaustion pattern, and
+ * the `ENOBUFS` it eventually raises killed the call outright.
+ *
+ * The numbers, each one a decision and not a taste:
+ *
+ * - `keepAlive: true` — the whole point: hold the socket open between calls so there is no churn to
+ *   exhaust anything with.
+ * - `timeout: LOOPBACK_IDLE_MS` (45s) — how long an idle socket is kept for reuse. It has to outlast
+ *   a model's think-time between two tool calls (which is what 5s failed to do) and it has to stay
+ *   BELOW the daemon's own keep-alive timeout, so that the client is always the side that retires a
+ *   socket. If the server closed first we would keep picking up sockets it had already closed, and
+ *   that failure looks exactly like the one case we refuse to retry (see `isRetryableConnectError`).
+ *   The daemon's side of that pact is `HTTP_KEEP_ALIVE_TIMEOUT_MS` in `http-server.ts`.
+ * - `keepAliveMsecs: 10_000` — TCP-level keep-alive probes on an idle socket, so a daemon that died
+ *   without a FIN is noticed rather than handed back out as a live connection.
+ * - `maxSockets: 8` — the proxy multiplexes ONE MCP client, whose calls are near enough serial; 8 is
+ *   generous headroom for overlapping notifications while capping the worst case far below anything
+ *   a port table would notice. Exceeding it queues rather than fails.
+ */
+export const LOOPBACK_IDLE_MS = 45_000;
+/** Named separately because `http.Agent` does not expose its options back to a caller (or a test). */
+export const LOOPBACK_AGENT_OPTIONS = {
+    keepAlive: true,
+    keepAliveMsecs: 10_000,
+    timeout: LOOPBACK_IDLE_MS,
+    maxSockets: 8,
+};
+export const loopbackAgent = new http.Agent(LOOPBACK_AGENT_OPTIONS);
+/**
+ * Socket-level failures worth another attempt — every one of them a statement about this machine's
+ * networking stack, not about the request.
+ *
+ * The list is deliberately narrow. It is not the retry decision on its own: the caller must ALSO
+ * know the request never reached the daemon. What the code check buys is that a programming error
+ * (`ERR_INVALID_URL`, a bad argument) cannot be retried — those fail before a socket too, and would
+ * otherwise burn the whole attempt budget on a bug that will never succeed.
+ */
+const RETRYABLE_CODES = new Set([
+    'ENOBUFS', // Windows: non-paged pool / ephemeral port exhaustion — the reported failure
+    'EADDRNOTAVAIL', // no ephemeral port left to bind
+    'EMFILE', // per-process fd limit
+    'ENFILE', // system-wide fd limit
+    'ECONNREFUSED', // daemon restarting, listener not back yet
+    'ECONNRESET', // peer closed the connection
+    'ETIMEDOUT', // connect never completed
+]);
+export function isRetryableConnectError(err) {
+    const code = err?.code;
+    return 'string' === typeof code && RETRYABLE_CODES.has(code);
+}

package/dist/mcp/attach-memory.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Two durable bits about the CLIENT side of the install: has an MCP client ever started Reticle's
+ * MCP server on this port, and has one ever asked it for the tool list.
+ *
+ * Some hosts register the server, start it, and then never send `tools/list` until the client is
+ * restarted. The agent has no Reticle tools, the user has no message, and from our side that install
+ * is byte-identical to one somebody wired and abandoned: daemon idle, no sessions, nothing to say.
+ * `status` could report "registered" and "connected"; it could not report the state in between,
+ * which is the one with an answer ("restart your client").
+ *
+ * Both bits record something that HAPPENED — the proxy ran, a `tools/list` arrived — never an
+ * inference from a config file. A config entry proves somebody wrote a line of JSON; it does not
+ * prove a client ever read it, which is precisely the thing in question here.
+ *
+ * Deliberately the same shape as `connection-memory.ts`: one small JSON file per port under the
+ * daemon's state home, best-effort in both directions. It is a HINT, so every failure degrades to
+ * "we do not know" rather than throwing — a diagnostic that can crash the process it is diagnosing
+ * is worse than no diagnostic at all.
+ *
+ * KNOWN LIMIT, and why the messages below say so out loud: the record is per PORT, not per client.
+ * Two clients on one machine share it, so a healthy one masks a broken one, and the record itself
+ * only begins on the version that introduced it — a long-working install reads as never attached
+ * until its client next starts the server. Both limits are stated in the text the user reads,
+ * because an honest "here is what I can see, here is what to check" beats a confident wrong no.
+ */
+/** What the client side of this install has been observed doing on this port. */
+export declare const AttachState: {
+    /** No client has started Reticle's MCP server here, as far as this record goes. */
+    readonly NEVER_ATTACHED: "never-attached";
+    /** A client started it and never asked for the tool list — the state that needs a restart. */
+    readonly NEVER_ENUMERATED: "never-enumerated";
+    /**
+     * The catalogue was read and no tool was ever called: both ends healthy, nothing crossing.
+     *
+     * Reported from the field as the hardest state to diagnose, and it is the one every component
+     * check passes. The browser SDK is injected, the daemon has a live session, the client lists all
+     * the tools, and the agent still reports Reticle as absent. `enumerated` used to cover this, which
+     * meant the most-broken install we know of read identically to a perfect one.
+     */
+    readonly NEVER_CALLED: "never-called";
+    /** Started, enumerated, and actually used. Nothing to say. */
+    readonly ENUMERATED: "enumerated";
+};
+export type AttachState = (typeof AttachState)[keyof typeof AttachState];
+/** Record that an MCP client started the proxy on this port. */
+export declare function rememberProxyStarted(stateDir: string, port: number): void;
+/**
+ * Record that a client actually CALLED a tool here, not merely listed them.
+ *
+ * Written once and then skipped, like the other two: this runs on the hot path of every tool call,
+ * and a diagnostic that writes a file per call would cost more than it tells anybody.
+ */
+export declare function rememberToolCalled(stateDir: string, port: number): void;
+/**
+ * Record that a client asked for the tool list on this port.
+ *
+ * Enumeration implies attachment — a `tools/list` cannot arrive at a server nobody started — so this
+ * sets both bits, and a record written by an older proxy that only ever set one is still read
+ * correctly.
+ */
+export declare function rememberEnumerated(stateDir: string, port: number): void;
+/** Which of the four client-side states this port is in. */
+export declare function attachState(stateDir: string, port: number): AttachState;
+/**
+ * The sentence to print for a state, or `undefined` when there is nothing to fix.
+ *
+ * The healthy case has to stay silent: advice printed beside a working client reads as though
+ * something is still wrong, which is its own kind of lie.
+ */
+export declare function describeAttachState(state: AttachState): string | undefined;
+/** What `reticle status` reports about the client side of the install. */
+export interface AttachStatusFields {
+    mcpClient: AttachState;
+    mcpClientAction?: string;
+}
+/**
+ * The client-side fields for one `status` run.
+ *
+ * The state is reported on EVERY run, healthy included — "the client has read the tools" is the
+ * fact that was missing, and reporting it only when broken leaves the reader unable to tell a
+ * healthy client from a version too old to look. The advice rides along only when there is any.
+ */
+export declare function attachStatusFields(stateDir: string, port: number): AttachStatusFields;

package/dist/mcp/attach-memory.js

@@ -0,0 +1,185 @@
+/**
+ * Two durable bits about the CLIENT side of the install: has an MCP client ever started Reticle's
+ * MCP server on this port, and has one ever asked it for the tool list.
+ *
+ * Some hosts register the server, start it, and then never send `tools/list` until the client is
+ * restarted. The agent has no Reticle tools, the user has no message, and from our side that install
+ * is byte-identical to one somebody wired and abandoned: daemon idle, no sessions, nothing to say.
+ * `status` could report "registered" and "connected"; it could not report the state in between,
+ * which is the one with an answer ("restart your client").
+ *
+ * Both bits record something that HAPPENED — the proxy ran, a `tools/list` arrived — never an
+ * inference from a config file. A config entry proves somebody wrote a line of JSON; it does not
+ * prove a client ever read it, which is precisely the thing in question here.
+ *
+ * Deliberately the same shape as `connection-memory.ts`: one small JSON file per port under the
+ * daemon's state home, best-effort in both directions. It is a HINT, so every failure degrades to
+ * "we do not know" rather than throwing — a diagnostic that can crash the process it is diagnosing
+ * is worse than no diagnostic at all.
+ *
+ * KNOWN LIMIT, and why the messages below say so out loud: the record is per PORT, not per client.
+ * Two clients on one machine share it, so a healthy one masks a broken one, and the record itself
+ * only begins on the version that introduced it — a long-working install reads as never attached
+ * until its client next starts the server. Both limits are stated in the text the user reads,
+ * because an honest "here is what I can see, here is what to check" beats a confident wrong no.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** What the client side of this install has been observed doing on this port. */
+export const AttachState = {
+    /** No client has started Reticle's MCP server here, as far as this record goes. */
+    NEVER_ATTACHED: 'never-attached',
+    /** A client started it and never asked for the tool list — the state that needs a restart. */
+    NEVER_ENUMERATED: 'never-enumerated',
+    /**
+     * The catalogue was read and no tool was ever called: both ends healthy, nothing crossing.
+     *
+     * Reported from the field as the hardest state to diagnose, and it is the one every component
+     * check passes. The browser SDK is injected, the daemon has a live session, the client lists all
+     * the tools, and the agent still reports Reticle as absent. `enumerated` used to cover this, which
+     * meant the most-broken install we know of read identically to a perfect one.
+     */
+    NEVER_CALLED: 'never-called',
+    /** Started, enumerated, and actually used. Nothing to say. */
+    ENUMERATED: 'enumerated',
+};
+/**
+ * What to do about a client that started Reticle and never listed its tools.
+ *
+ * Names the cause AND the action, like the rest of the doctor/status vocabulary, and names its own
+ * blind spot: this record cannot see WHICH client asked, so it must not tell somebody running two
+ * of them that the one in front of them is the broken one.
+ */
+const NEVER_ENUMERATED_ACTION = 'an MCP client started Reticle on this port and never asked for the tool list, so the tools are ' +
+    'here and your client has not read them — restart your MCP client, which is what makes it list ' +
+    'them again. This record is per port, not per client, so with more than one client registered ' +
+    'the one that never listed may not be the one you are looking at.';
+/**
+ * What to do when nothing has ever attached.
+ *
+ * The hedge is not padding. This record begins the first time a client starts the server on a
+ * version that keeps it, so an install that has worked for months reads as never attached until its
+ * client next starts Reticle — and telling that user their server is unregistered would send them
+ * to re-run `init` over a working setup.
+ */
+/**
+ * The link that is broken, named as a link rather than as a component.
+ *
+ * Every other check in this product is about a PIECE: is the daemon up, is the SDK injected, is a
+ * session live, are the tools registered. This state is the one where every piece passes and the
+ * chain still does not carry anything, so the message has to say which hop failed and what to do
+ * about it, not repeat that the pieces are fine.
+ */
+const NEVER_CALLED_ACTION = "an MCP client listed Reticle's tools on this port and has never called one, so the tools are " +
+    'registered and no request has reached the daemon. That is the agent-to-daemon hop, not the ' +
+    'browser or the daemon: both of those can look healthy while this one is broken. Ask your agent ' +
+    'to run `reticle_sessions` explicitly. If it answers, the link is fine and the agent simply had ' +
+    'no reason to call it; if it says Reticle is unavailable, the client is talking to a different ' +
+    'server than the one this record belongs to, so re-check which command and port it launches. ' +
+    'This record is per port, not per client.';
+const NEVER_ATTACHED_ACTION = 'no MCP client has started Reticle on this port, so either the server is not registered with your ' +
+    'client or nothing has attached since this record began — register it with `npx ' +
+    '@reticlehq/server init`, then restart your MCP client and run status again.';
+const EMPTY = { attached: false, enumerated: false, called: false };
+function memoryPath(stateDir, port) {
+    return join(stateDir, `attach-${String(port)}.json`);
+}
+/** The record for a port. Empty on absent, unreadable, or malformed state. */
+function read(stateDir, port) {
+    try {
+        const parsed = JSON.parse(readFileSync(memoryPath(stateDir, port), 'utf8'));
+        if ('object' !== typeof parsed || null === parsed)
+            return EMPTY;
+        const record = parsed;
+        return {
+            attached: true === record.attached,
+            enumerated: true === record.enumerated,
+            called: true === record.called,
+        };
+    }
+    catch {
+        return EMPTY;
+    }
+}
+/** Write the record back, best-effort. A hint must never be the reason a proxy fails to serve. */
+function write(stateDir, port, record) {
+    try {
+        mkdirSync(stateDir, { recursive: true });
+        writeFileSync(memoryPath(stateDir, port), JSON.stringify(record), 'utf8');
+    }
+    catch {
+        // An unwritable state home is already reported elsewhere; it must not break the client path.
+    }
+}
+/** Record that an MCP client started the proxy on this port. */
+export function rememberProxyStarted(stateDir, port) {
+    const known = read(stateDir, port);
+    if (known.attached)
+        return;
+    write(stateDir, port, { ...known, attached: true });
+}
+/**
+ * Record that a client actually CALLED a tool here, not merely listed them.
+ *
+ * Written once and then skipped, like the other two: this runs on the hot path of every tool call,
+ * and a diagnostic that writes a file per call would cost more than it tells anybody.
+ */
+export function rememberToolCalled(stateDir, port) {
+    const known = read(stateDir, port);
+    if (known.called)
+        return;
+    write(stateDir, port, { ...known, called: true });
+}
+/**
+ * Record that a client asked for the tool list on this port.
+ *
+ * Enumeration implies attachment — a `tools/list` cannot arrive at a server nobody started — so this
+ * sets both bits, and a record written by an older proxy that only ever set one is still read
+ * correctly.
+ */
+export function rememberEnumerated(stateDir, port) {
+    const known = read(stateDir, port);
+    if (known.enumerated)
+        return;
+    write(stateDir, port, { ...known, attached: true, enumerated: true });
+}
+/** Which of the four client-side states this port is in. */
+export function attachState(stateDir, port) {
+    const known = read(stateDir, port);
+    // Ordered outward along the chain: attached, then listed, then actually used. The last hop is
+    // the one every component check misses, so it is asked last and answered explicitly.
+    if (!known.attached)
+        return AttachState.NEVER_ATTACHED;
+    if (!known.enumerated)
+        return AttachState.NEVER_ENUMERATED;
+    return known.called ? AttachState.ENUMERATED : AttachState.NEVER_CALLED;
+}
+/**
+ * The sentence to print for a state, or `undefined` when there is nothing to fix.
+ *
+ * The healthy case has to stay silent: advice printed beside a working client reads as though
+ * something is still wrong, which is its own kind of lie.
+ */
+export function describeAttachState(state) {
+    if (state === AttachState.NEVER_ENUMERATED)
+        return NEVER_ENUMERATED_ACTION;
+    if (state === AttachState.NEVER_ATTACHED)
+        return NEVER_ATTACHED_ACTION;
+    if (state === AttachState.NEVER_CALLED)
+        return NEVER_CALLED_ACTION;
+    return undefined;
+}
+/**
+ * The client-side fields for one `status` run.
+ *
+ * The state is reported on EVERY run, healthy included — "the client has read the tools" is the
+ * fact that was missing, and reporting it only when broken leaves the reader unable to tell a
+ * healthy client from a version too old to look. The advice rides along only when there is any.
+ */
+export function attachStatusFields(stateDir, port) {
+    const state = attachState(stateDir, port);
+    const action = describeAttachState(state);
+    // OMITTED rather than undefined: `exactOptionalPropertyTypes` is on, and an absent key is also
+    // what keeps the healthy line to one fact.
+    return { mcpClient: state, ...(action === undefined ? {} : { mcpClientAction: action }) };
+}

package/dist/mcp/client-identity.d.ts

@@ -0,0 +1,31 @@
+/**
+ * WHICH agent is on the other end of this daemon.
+ *
+ * MCP clients announce themselves in the `initialize` handshake — `claude-code`, `cursor-vscode`,
+ * `windsurf`, and so on. That claim is the ONLY honest source for this: an env-var table
+ * (`CLAUDECODE`, `CURSOR_TRACE_ID`, …) is a guess that silently rots every time a vendor renames a
+ * variable, and it cannot see a client nobody has added to the table yet.
+ *
+ * Read through a hook rather than a stored value because the handshake happens after the server is
+ * constructed, and a session can reconnect under a different client entirely.
+ *
+ * Lives here, not in telemetry, because it stopped being a telemetry detail the moment a
+ * verification RUN needed to record which agent produced it — and `runs/` must not import
+ * `telemetry/` to find out.
+ *
+ * Note what is NOT available and cannot be: the MODEL. `clientInfo` carries a name, a title and a
+ * version; MCP has no concept of a model, so the transport genuinely cannot tell us. Anything
+ * claiming to know it would be inventing it.
+ */
+export interface McpClientIdentity {
+    name?: string;
+    version?: string;
+}
+export declare function setMcpClientIdentityHook(next: () => McpClientIdentity | undefined): void;
+/** For tests, and for a daemon that is reused across transports. */
+export declare function clearMcpClientIdentityHook(): void;
+/**
+ * The client's own name and version, trimmed and bounded. Empty object when no MCP peer has
+ * introduced itself — a plain CLI run has no client, and reporting one would be a fabrication.
+ */
+export declare function mcpClientIdentity(): McpClientIdentity;

package/dist/mcp/client-identity.js

@@ -0,0 +1,51 @@
+/**
+ * WHICH agent is on the other end of this daemon.
+ *
+ * MCP clients announce themselves in the `initialize` handshake — `claude-code`, `cursor-vscode`,
+ * `windsurf`, and so on. That claim is the ONLY honest source for this: an env-var table
+ * (`CLAUDECODE`, `CURSOR_TRACE_ID`, …) is a guess that silently rots every time a vendor renames a
+ * variable, and it cannot see a client nobody has added to the table yet.
+ *
+ * Read through a hook rather than a stored value because the handshake happens after the server is
+ * constructed, and a session can reconnect under a different client entirely.
+ *
+ * Lives here, not in telemetry, because it stopped being a telemetry detail the moment a
+ * verification RUN needed to record which agent produced it — and `runs/` must not import
+ * `telemetry/` to find out.
+ *
+ * Note what is NOT available and cannot be: the MODEL. `clientInfo` carries a name, a title and a
+ * version; MCP has no concept of a model, so the transport genuinely cannot tell us. Anything
+ * claiming to know it would be inventing it.
+ */
+/** Caps, so a hostile or broken client cannot write unbounded strings into an artifact. */
+const MAX_NAME = 64;
+const MAX_VERSION = 32;
+let hook;
+export function setMcpClientIdentityHook(next) {
+    hook = next;
+}
+/** For tests, and for a daemon that is reused across transports. */
+export function clearMcpClientIdentityHook() {
+    hook = undefined;
+}
+/**
+ * The client's own name and version, trimmed and bounded. Empty object when no MCP peer has
+ * introduced itself — a plain CLI run has no client, and reporting one would be a fabrication.
+ */
+export function mcpClientIdentity() {
+    try {
+        const info = hook?.();
+        const name = info?.name;
+        const version = info?.version;
+        return {
+            ...(name !== undefined && '' !== name ? { name: name.slice(0, MAX_NAME) } : {}),
+            ...(version !== undefined && '' !== version
+                ? { version: version.slice(0, MAX_VERSION) }
+                : {}),
+        };
+    }
+    catch {
+        // A hook that throws must never fail the thing that asked — this is descriptive, not load-bearing.
+        return {};
+    }
+}

package/dist/mcp/mcp-post-transport.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The MCP proxy's POST leg: its own socket pool, and the one retry that is safe to make.
+ *
+ * Split out of `mcp-proxy.ts` when that file passed the 1000-line backstop after two independent
+ * hardenings of this path met in a merge. It earns its own module rather than being an arbitrary
+ * slice: everything here is about ONE thing — getting a single JSON-RPC line into the daemon, or
+ * saying honestly that it never arrived — and the file it came from is about the SSE stream.
+ */
+import * as http from 'node:http';
+/** One bounded pool for the short-lived POST side of each MCP SSE session. */
+export declare const MCP_PROXY_HTTP_AGENT_OPTIONS: {
+    readonly keepAlive: true;
+    readonly keepAliveMsecs: 30000;
+    readonly timeout: 60000;
+    readonly maxSockets: 8;
+    readonly scheduling: "lifo";
+};
+export declare function shouldRetryUnsentPost(error: unknown, bytesWritten: number, retryCount: number): boolean;
+export interface PostFailure {
+    reason: string;
+    transport: boolean;
+    attempts: number;
+}
+type HttpRequest = (options: http.RequestOptions, callback: (response: http.IncomingMessage) => void) => http.ClientRequest;
+export declare function postToSession(url: string, body: string, request?: HttpRequest): Promise<PostFailure | null>;
+export {};