@reticlehq/server 2.4.0 → 2.6.0

package/dist/{mcp.d.ts → mcp/mcp.d.ts}

@@ -1,8 +1,8 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { type ToolDeps } from './tools/tools.js';
-import type { ToolDef } from './tools/tools.js';
-import { type ToolProfile } from './tools/profiles.js';
+import { type ToolDeps } from '../tools/tools.js';
+import type { ToolDef } from '../tools/tools.js';
+import { type ToolSurface } from '../tools/tool-surface.js';
 /**
  * Merge the runtime-spliced envelope (health/lease/age/control) into a session-bound tool's declared
  * outputSchema so structuredContent validation keeps those fields instead of dropping them. The tool's
@@ -27,12 +27,15 @@ export declare function encodeResult(result: unknown, encoding: string): string;
  * therefore insensitive to it — every profile appeared to reach every tool, so reverting the fix here
  * left the suite green. Exercise the real function or the guard is theatre.
  *
- * Every TRIMMED profile keeps the meta-tools, so a tool that is not advertised is still reachable via
- * reticle_run. Without them a trim is not a trim but a hard removal: under `standard`, 11 tools were
- * uncallable — including reticle_annotate, which reticle_flow_save's own description tells the agent to
- * call. `full` advertises everything and needs no hatch.
+ * Both surfaces keep the meta-tools. On the default that is what makes a trim a trim rather than a
+ * hard removal — an unadvertised tool is still reachable through reticle_run; under the old
+ * `standard` profile 11 tools were uncallable, including reticle_annotate, which reticle_flow_save's
+ * own description tells the agent to call. On ALL they are kept too: `reticle_tools` is not an
+ * escape hatch there, it is parameter lookup, and every recovery message this server emits says
+ * "Call reticle_tools { names: [...] } for its parameters" — leaving it out made our own advice a
+ * dead end on the one surface that advertises everything.
  */
-export declare function advertisedTools(profile: ToolProfile): ToolDef[];
+export declare function advertisedTools(surface: ToolSurface): ToolDef[];
 /**
  * Exactly what gets advertised for one tool under a profile: trimmed description, lean input shape,
  * and (non-lean only) the output schema.
@@ -41,10 +44,10 @@ export declare function advertisedTools(profile: ToolProfile): ToolDef[];
  * are trimmed later and would make a guard that cannot fail — a mistake already made once here, with
  * an abbreviation test that read raw defs and would have passed with the bug fully present.
  */
-export declare function advertisedConfig(tool: ToolDef, advertised: readonly ToolDef[], profile: ToolProfile): {
+export declare function advertisedConfig(tool: ToolDef, advertised: readonly ToolDef[], profile: ToolSurface): {
     description: string;
     inputSchema: z.ZodRawShape;
     outputSchema?: z.ZodRawShape;
 };
 export declare function installFriendlyArgErrors(server: McpServer, examples: Map<string, string>, allowedKeys?: Map<string, ReadonlySet<string>>): void;
-export declare function createMcpServer(deps: ToolDeps, profile?: ToolProfile): McpServer;
+export declare function createMcpServer(deps: ToolDeps, profile?: ToolSurface): McpServer;

package/dist/{mcp.js → mcp/mcp.js}

@@ -1,18 +1,23 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
+import { PredicateSchema } from '../events/predicate.js';
 import { isToonable, resultToToon } from '@reticlehq/core';
-import { TOOLS } from './tools/tools.js';
-import { filterTools, TOOL_PROFILE } from './tools/profiles.js';
-import { buildDynamicTools } from './tools/dynamic-tools.js';
-import { runTool, SESSION_BOUND_TOOLS } from './tools/invoke-tool.js';
-import { sessionEnvelopeShape } from './tools/tool-kit.js';
-import { buildErrorPayload } from './tools/error-recovery.js';
-import { log } from './log.js';
-import { SERVER_VERSION } from './server-version.js';
-import { MCP_SERVER_NAME } from './init/mcp.js';
-import { setMcpClientNameHook } from './telemetry/feedback-context.js';
-import { getSessionMetrics } from './telemetry/session-metrics.js';
+import { TOOLS } from '../tools/tools.js';
+import { filterTools, describeToolSurface, TOOL_SURFACE, } from '../tools/tool-surface.js';
+import { buildDynamicTools } from '../tools/dynamic-tools.js';
+import { runTool, SESSION_BOUND_TOOLS } from '../tools/invoke-tool.js';
+import { sessionEnvelopeShape } from '../tools/tool-kit.js';
+import { buildErrorPayload } from '../tools/error-recovery.js';
+import { resultIsError } from './mcp-is-error.js';
+import { unadvertisedToolHelp } from '../tools/unadvertised-help.js';
+/** The JSON-RPC method the SDK registers its tool dispatcher under. */
+const CALL_TOOL_METHOD = 'tools/call';
+import { log } from '../log.js';
+import { SERVER_VERSION } from '../version/server-version.js';
+import { MCP_SERVER_NAME } from '../init/mcp.js';
+import { setMcpClientNameHook } from '../telemetry/feedback-context.js';
+import { getSessionMetrics } from '../telemetry/session-metrics.js';
 /**
  * Merge the runtime-spliced envelope (health/lease/age/control) into a session-bound tool's declared
  * outputSchema so structuredContent validation keeps those fields instead of dropping them. The tool's
@@ -25,6 +30,27 @@ export function withSessionEnvelope(name, outputSchema) {
     return { ...sessionEnvelopeShape, ...outputSchema };
 }
 const SERVER_INFO = { name: MCP_SERVER_NAME, version: SERVER_VERSION };
+/**
+ * What every agent is told at `initialize`, before it has called a single tool.
+ *
+ * This is the only channel that reaches an agent with NO dependency on the project: no CLAUDE.md, no
+ * AGENTS.md, no pasted skill, no successful `reticle init`. An agent whose setup half-worked has read
+ * none of those files and is precisely the agent whose report we need — so the standing instruction
+ * to send feedback has to live here, where it arrives with the connection itself.
+ *
+ * Kept to a handful of lines: it is prepended to every session's context, so each sentence is paid
+ * for on every turn, forever.
+ */
+const SERVER_INSTRUCTIONS = `Reticle verifies a running web app from the inside: look (reticle_snapshot / reticle_query), act and prove in one hop (reticle_act_and_wait), observe (reticle_state / reticle_network / reticle_console), assert (reticle_assert). Verify a user-facing change against the real app before you call it done, and never weaken a check to make it pass.
+
+Only reticle_act_and_wait and reticle_assert produce a verdict. reticle_act and everything else move or read the app and prove nothing, so a drive that ends without one of those two has no result however many tools it used. Prefer reticle_act_and_wait({ ref, action, until }) — it names the expected consequence BEFORE the action, which is the difference between a check and a rationalisation. A verdict of verified:"unknown" is not a pass: it means Reticle drove the app and could not tell what happened. Report it as unknown.
+
+Feedback is first-class here, not a courtesy. Reticle is built FOR agents, so your experience is the only signal that decides what gets built or fixed — and it disappears when your context does. Send it with \`reticle_feedback\` the moment you notice, then carry on with your task:
+- Reticle broke, lied, or could not see something you needed (\`bug\` / \`gap\` / \`ambiguity\`).
+- You wished it could do something, or something works but costs too many calls (\`feature_request\` / \`improvement\`).
+- The install, the wiring, or the setup itself gave you trouble — including anything you had to work around by hand.
+
+Nothing is too minor, and a report costs one call. If the tools are unreachable (setup unfinished, daemon down), file the same report from the shell instead: \`reticle feedback --agent --kind <bug|gap|ambiguity|feature_request|improvement> "what happened"\`. Report defects in RETICLE — a bug you find in the app under test is Reticle working, and belongs in your answer to the user.`;
 /** First sentence of a description (purpose only) for lean profiles — keeps per-turn def cost
  * down. Cuts at the first sentence-ending period or newline; falls back to a 160-char cap. The
  * first clause retains the essentials (enum hints like "role | text | label" live there). */
@@ -65,7 +91,23 @@ export function firstSentence(description) {
  * Across the three tools that take a predicate that is 72% of the entire advertised input schema — a
  * cost re-sent on every request, forever, to describe a grammar most calls use one variant of.
  */
-const PREDICATE_PARAMS = new Set(['predicate', 'until']);
+/**
+ * Is this parameter ACTUALLY the predicate union?
+ *
+ * This used to be a name check — `new Set(['predicate', 'until'])` — and `until` is overloaded on
+ * this surface: the act/assert family means a predicate by it, while reticle_observe / _network /
+ * _console mean a NUMBER, an upper cursor bound. So all three had their numeric parameter advertised
+ * to the agent as `Predicate object: { kind, ...fields }`, typed as a record, under the DEFAULT
+ * profile. An agent believing the schema passes an object, `asNumber` yields undefined, the bound is
+ * silently dropped and the tool answers over the wrong window — a wrong answer wearing the shape of
+ * an answer.
+ *
+ * Keying on the schema cannot make that mistake: a parameter is compacted because it IS a predicate.
+ */
+function isPredicateParam(schema) {
+    const inner = schema instanceof z.ZodOptional ? schema.unwrap() : schema;
+    return inner === PredicateSchema || inner === PredicateSchema.optional();
+}
 /**
  * What a lean profile advertises in place of the full predicate union.
  *
@@ -113,17 +155,22 @@ const COMPACT_PREDICATE_DESCRIPTION = `${PREDICATE_KINDS}${PREDICATE_FIELD_GRAMM
  */
 function leanZodShape(shape, predicateAnchor) {
     const out = {};
+    // The navigation hint is said ONCE per turn, so it is anchored to one parameter — not one tool.
+    // A tool can carry two predicate parameters (a canonical name plus a neighbouring tool's alias),
+    // and anchoring per-tool spelled the hint out on both.
+    let hintSpent = predicateAnchor !== undefined;
     for (const [key, schema] of Object.entries(shape)) {
-        if (PREDICATE_PARAMS.has(key)) {
-            // Every tool keeps the kinds; only the navigation hint is anchored to one.
+        if (isPredicateParam(schema)) {
+            // Every tool keeps the kinds; only the navigation hint is anchored.
             const compact = z
                 .record(z.unknown())
-                .describe(predicateAnchor === undefined ? COMPACT_PREDICATE_DESCRIPTION : PREDICATE_KINDS);
+                .describe(hintSpent ? PREDICATE_KINDS : COMPACT_PREDICATE_DESCRIPTION);
+            hintSpent = true;
             out[key] = schema.isOptional() ? compact.optional() : compact;
             continue;
         }
         const desc = schema.description;
-        out[key] = typeof desc === 'string' ? schema.describe(firstSentence(desc)) : schema;
+        out[key] = 'string' === typeof desc ? schema.describe(firstSentence(desc)) : schema;
     }
     return out;
 }
@@ -151,18 +198,19 @@ export function encodeResult(result, encoding) {
  * therefore insensitive to it — every profile appeared to reach every tool, so reverting the fix here
  * left the suite green. Exercise the real function or the guard is theatre.
  *
- * Every TRIMMED profile keeps the meta-tools, so a tool that is not advertised is still reachable via
- * reticle_run. Without them a trim is not a trim but a hard removal: under `standard`, 11 tools were
- * uncallable — including reticle_annotate, which reticle_flow_save's own description tells the agent to
- * call. `full` advertises everything and needs no hatch.
+ * Both surfaces keep the meta-tools. On the default that is what makes a trim a trim rather than a
+ * hard removal — an unadvertised tool is still reachable through reticle_run; under the old
+ * `standard` profile 11 tools were uncallable, including reticle_annotate, which reticle_flow_save's
+ * own description tells the agent to call. On ALL they are kept too: `reticle_tools` is not an
+ * escape hatch there, it is parameter lookup, and every recovery message this server emits says
+ * "Call reticle_tools { names: [...] } for its parameters" — leaving it out made our own advice a
+ * dead end on the one surface that advertises everything.
  */
-export function advertisedTools(profile) {
-    if (profile === TOOL_PROFILE.DYNAMIC)
-        return buildDynamicTools(TOOLS);
-    if (profile === TOOL_PROFILE.FULL)
-        return TOOLS;
-    const base = filterTools(TOOLS, profile === TOOL_PROFILE.HYBRID ? TOOL_PROFILE.CORE : profile);
-    return [...base, ...buildDynamicTools(TOOLS)];
+export function advertisedTools(surface) {
+    // The catalog reports which surface is live and what chose it — the only way an agent can see that
+    // a setting did not take (the daemon read the value it started with).
+    const origin = describeToolSurface(surface);
+    return [...filterTools(TOOLS, surface), ...buildDynamicTools(TOOLS, origin)];
 }
 /**
  * Exactly what gets advertised for one tool under a profile: trimmed description, lean input shape,
@@ -173,11 +221,15 @@ export function advertisedTools(profile) {
  * an abbreviation test that read raw defs and would have passed with the bug fully present.
  */
 export function advertisedConfig(tool, advertised, profile) {
-    const terse = profile === TOOL_PROFILE.CORE ||
-        profile === TOOL_PROFILE.STANDARD ||
-        profile === TOOL_PROFILE.HYBRID;
+    // Hybrid is the terse one. NOT `profile !== FULL`, which reads equivalent and is not: it also
+    // trims `dynamic`, whose two meta-tools are the ONLY thing that profile advertises — so the
+    // instructions for using them (`names:[…]` loads full params on demand) would be cut to a first
+    // sentence and the agent would have nothing left to learn the surface from. Measured when it
+    // happened: dynamic's tools/list fell 1,543 -> 849 bytes, which looks like a saving and is a
+    // capability loss.
+    const terse = profile === TOOL_SURFACE.DEFAULT;
     // The first advertised tool carrying a predicate spells the grammar out; the rest point at it.
-    const anchor = advertised.find((t) => Object.keys(t.inputSchema).some((k) => PREDICATE_PARAMS.has(k)))?.name;
+    const anchor = advertised.find((t) => Object.values(t.inputSchema).some((schema) => isPredicateParam(schema)))?.name;
     const outputSchema = terse ? undefined : withSessionEnvelope(tool.name, tool.outputSchema);
     return {
         description: withExample(terse ? firstSentence(tool.description) : tool.description, tool.example),
@@ -189,7 +241,7 @@ export function advertisedConfig(tool, advertised, profile) {
 }
 /** Argument keys the tool never declared. Empty when the tool's shape is unknown to us. */
 function unknownKeys(args, allowed) {
-    if (allowed === undefined || typeof args !== 'object' || args === null)
+    if (allowed === undefined || typeof args !== 'object' || null === args)
         return [];
     return Object.keys(args).filter((key) => !allowed.has(key));
 }
@@ -207,7 +259,7 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
         const unknown = unknownKeys(args, allowedKeys.get(toolName));
         if (unknown.length > 0) {
             const example = examples.get(toolName);
-            throw new McpError(ErrorCode.InvalidParams, `Unknown ${unknown.length === 1 ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')}. ` +
+            throw new McpError(ErrorCode.InvalidParams, `Unknown ${1 === unknown.length ? 'parameter' : 'parameters'} for ${toolName}: ${unknown.join(', ')}. ` +
                 `They were NOT applied — a result computed without them would look like an answer. ` +
                 (example === undefined
                     ? `Call reticle_tools { names: ["${toolName}"] } for its parameters.`
@@ -228,9 +280,44 @@ export function installFriendlyArgErrors(server, examples, allowedKeys = new Map
         }
     };
 }
-export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
+/**
+ * Answer a call for a real-but-un-advertised tool with the way to make it work.
+ *
+ * Wraps the SDK's own `tools/call` handler rather than registering the missing tools: registering
+ * them would put their schemas back into `tools/list`, which is the exact cost the trim exists to
+ * avoid. Delegates untouched for every other name, so an advertised tool's errors stay the SDK's.
+ */
+function installUnadvertisedToolHelp(server, advertised, known) {
+    const inner = server.server;
+    const handlers = inner._requestHandlers;
+    const original = handlers?.get(CALL_TOOL_METHOD);
+    if (handlers === undefined || original === undefined)
+        return;
+    handlers.set(CALL_TOOL_METHOD, async (request, extra) => {
+        const name = toolNameOf(request);
+        const help = name === undefined ? undefined : unadvertisedToolHelp(name, advertised, known);
+        if (help !== undefined)
+            throw new McpError(ErrorCode.InvalidParams, help);
+        return original(request, extra);
+    });
+}
+/** The requested tool name, when the request has the shape we expect. */
+function toolNameOf(request) {
+    if (typeof request !== 'object' || null === request)
+        return undefined;
+    const params = request.params;
+    if (typeof params !== 'object' || null === params)
+        return undefined;
+    const name = params.name;
+    return 'string' === typeof name ? name : undefined;
+}
+export function createMcpServer(deps, profile = TOOL_SURFACE.DEFAULT) {
     const encoding = (process.env[ENCODING_ENV] ?? '').toLowerCase();
-    const server = new McpServer(SERVER_INFO);
+    // Which surface this daemon advertises. The 18-tool default and the 48-tool full surface are
+    // different products from inside an agent's context, so outcomes are only comparable when the
+    // session says which one it saw.
+    getSessionMetrics().recordSurface(profile);
+    const server = new McpServer(SERVER_INFO, { instructions: SERVER_INSTRUCTIONS });
     // Which agent is on the other end, taken from its own `initialize` handshake. Registered as a lazy
     // hook rather than read here: the handshake has not happened yet at construction time, and a
     // feedback report filed twenty tool calls later is exactly when we want the answer.
@@ -238,8 +325,10 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
         const info = server.server.getClientVersion();
         // Record it as a side effect of the first read so the session summary can report WHICH agents
         // drove this daemon — the multi-agent story, visible without a second plumbing path.
+        // Name AND version: the version was already in this handshake and was being dropped, so a
+        // regression in agent behaviour could never be attributed to a client build.
         if (info?.name !== undefined)
-            getSessionMetrics().recordClient(info.name);
+            getSessionMetrics().recordClient(info.name, info.version);
         return info === undefined ? undefined : { name: info.name, version: info.version };
     });
     // Cast once to our bridge type so every per-tool call site is typed without `any`.
@@ -285,13 +374,21 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
             try {
                 const result = await runTool(tool, deps, args);
                 const text = encodeResult(result, encoding);
+                // A tool that RETURNS `{ error, recovery }` refused just as surely as one that threw, and
+                // `isError` is the field a caller branches on. Without this it was set only on the throw
+                // path, so half the surface reported a refusal as a success. See mcp-is-error.
+                const isError = resultIsError(result);
                 if (tool.outputSchema !== undefined) {
                     return {
+                        ...(isError ? { isError: true } : {}),
                         content: [{ type: 'text', text }],
                         structuredContent: result,
                     };
                 }
-                return { content: [{ type: 'text', text }] };
+                return {
+                    ...(isError ? { isError: true } : {}),
+                    content: [{ type: 'text', text }],
+                };
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -308,5 +405,10 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
             }
         });
     }
+    // AFTER the registration loop, and that ordering is the whole trick: the SDK installs its
+    // `tools/call` dispatcher lazily on the FIRST registerTool, so wrapping before this point finds
+    // nothing to wrap and silently does nothing. Verified live rather than assumed — the first attempt
+    // sat here doing exactly that.
+    installUnadvertisedToolHelp(server, new Set(advertised.map((tool) => tool.name)), new Set(TOOLS.map((tool) => tool.name)));
     return server;
 }

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

@@ -0,0 +1,3 @@
+/** True when this queued client line is the handshake we answered ourselves. */
+export declare function isHandshakeLine(line: string): boolean;
+export declare function localInitializeResponse(line: string): string | null;

package/dist/mcp/proxy-handshake.js

@@ -0,0 +1,54 @@
+/**
+ * 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 { MCP_SERVER_NAME } from '../init/mcp.js';
+import { SERVER_VERSION } from '../version/server-version.js';
+/** The version we answer with if the client proposed none. */
+const FALLBACK_PROTOCOL_VERSION = '2024-11-05';
+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) {
+    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,
+            capabilities: { tools: {} },
+            serverInfo: { name: MCP_SERVER_NAME, version: SERVER_VERSION },
+        },
+    });
+}

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

@@ -0,0 +1,64 @@
+/**
+ * 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 74% of 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.
+ */
+/** 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.
+ */
+export declare function onStreamDrop(daemonListening: boolean): 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 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

@@ -0,0 +1,70 @@
+/**
+ * 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 74% of 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.
+ */
+/** 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.
+ */
+export function onStreamDrop(daemonListening) {
+    return daemonListening ? 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 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/tool-catalog-cache.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The tool catalog the proxy has already seen, so a locally-answered handshake is not toolless.
+ *
+ * When the daemon does not answer in time the proxy answers `initialize` itself — a hang gives the
+ * agent no tools AND no diagnosis, so that is right. But it left the client CONNECTED WITH NO TOOLS,
+ * because `tools/list` then had nothing behind it. Measured over one editor session: 25 stream drops,
+ * 11 dormant, 4 reconnects, 4 local handshakes — and each of those four is a state where a human has
+ * to notice and reconnect by hand.
+ *
+ * Every `tools/list` response the daemon has ever sent passes through this proxy, so the catalog is
+ * already in hand. Serving it back is the difference between "Reticle is here but useless" and
+ * "Reticle is here, and the first call will tell you what is wrong".
+ *
+ * In-memory and per-process on purpose: a catalog persisted from a different Reticle version would be
+ * its own confidently-wrong answer, and a proxy that has never seen one has nothing honest to serve —
+ * so it says nothing rather than inventing a list the agent would then call into.
+ */
+export declare class ToolCatalogCache {
+    #private;
+    /** Watch a line coming BACK from the daemon; remember it if it is a tool catalog. */
+    observe(line: string): void;
+    has(): boolean;
+    /**
+     * A response to `request` from the cached catalog, or null when this is not a tools/list request or
+     * nothing has been cached. The response carries the CALLER'S id — a JSON-RPC reply under any other
+     * id is not an answer, it is noise the client will never match.
+     */
+    answer(request: string): string | null;
+}

package/dist/mcp/tool-catalog-cache.js

@@ -0,0 +1,55 @@
+/**
+ * The tool catalog the proxy has already seen, so a locally-answered handshake is not toolless.
+ *
+ * When the daemon does not answer in time the proxy answers `initialize` itself — a hang gives the
+ * agent no tools AND no diagnosis, so that is right. But it left the client CONNECTED WITH NO TOOLS,
+ * because `tools/list` then had nothing behind it. Measured over one editor session: 25 stream drops,
+ * 11 dormant, 4 reconnects, 4 local handshakes — and each of those four is a state where a human has
+ * to notice and reconnect by hand.
+ *
+ * Every `tools/list` response the daemon has ever sent passes through this proxy, so the catalog is
+ * already in hand. Serving it back is the difference between "Reticle is here but useless" and
+ * "Reticle is here, and the first call will tell you what is wrong".
+ *
+ * In-memory and per-process on purpose: a catalog persisted from a different Reticle version would be
+ * its own confidently-wrong answer, and a proxy that has never seen one has nothing honest to serve —
+ * so it says nothing rather than inventing a list the agent would then call into.
+ */
+const LIST_METHOD = 'tools/list';
+function parse(line) {
+    try {
+        const value = JSON.parse(line);
+        return 'object' === typeof value && value !== null ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+export class ToolCatalogCache {
+    #tools;
+    /** Watch a line coming BACK from the daemon; remember it if it is a tool catalog. */
+    observe(line) {
+        const msg = parse(line);
+        const tools = msg?.result?.tools;
+        if (Array.isArray(tools) && tools.length > 0)
+            this.#tools = tools;
+    }
+    has() {
+        return this.#tools !== undefined;
+    }
+    /**
+     * A response to `request` from the cached catalog, or null when this is not a tools/list request or
+     * nothing has been cached. The response carries the CALLER'S id — a JSON-RPC reply under any other
+     * id is not an answer, it is noise the client will never match.
+     */
+    answer(request) {
+        if (this.#tools === undefined)
+            return null;
+        const msg = parse(request);
+        if (msg?.method !== LIST_METHOD)
+            return null;
+        if (msg.id === undefined || null === msg.id)
+            return null;
+        return JSON.stringify({ jsonrpc: '2.0', id: msg.id, result: { tools: this.#tools } });
+    }
+}

package/dist/oracles/propose-consequences.d.ts

@@ -7,7 +7,7 @@ import { type ReticleEvent } from '@reticlehq/core';
  * proposal is one existing-tool call. The learned RANKING across projects is the paid layer
  * (OSS-VS-SERVER); these local rules are OSS.
  */
-export interface ProposedConsequence {
+interface ProposedConsequence {
     /** A predicate object, directly usable as a mustHold. */
     predicate: Record<string, unknown>;
     /** Ranking tier: 0 strongest (signal) … 2 weakest (presence). */
@@ -19,3 +19,4 @@ export interface ProposedConsequence {
 }
 /** Propose ranked consequences from a recorded event window. Deduped; strongest first. */
 export declare function proposeConsequences(events: readonly ReticleEvent[]): ProposedConsequence[];
+export {};