@reticlehq/server 2.2.1 → 2.4.0

package/dist/mcp-proxy.js

@@ -1,6 +1,9 @@
 import * as http from 'node:http';
 import * as net from 'node:net';
-import { LOOPBACK_HOST, MCP_SSE_PATH } from '@reticlehq/core';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { LOOPBACK_HOST, MCP_SSE_PATH, ReticleDir } from '@reticlehq/core';
 import { log } from './log.js';
 const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
 /**
@@ -16,6 +19,99 @@ const DAEMON_POLL_INTERVAL_MS = 100;
 function delay(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/** Reconnect backoff: linear, capped, so a briefly-restarting daemon is picked up fast. */
+const RECONNECT_BASE_MS = 250;
+const RECONNECT_CAP_MS = 5_000;
+/**
+ * How many consecutive failed reconnects before the proxy gives up and exits. At the capped backoff
+ * this is a few minutes — long enough to ride out a daemon restart, short enough that a genuinely
+ * dead daemon lets the agent host respawn the proxy (which spawns a fresh daemon) instead of hanging.
+ */
+export const MAX_RECONNECT_ATTEMPTS = 60;
+export function reconnectDelayMs(attempt) {
+    return Math.min(RECONNECT_BASE_MS * attempt, RECONNECT_CAP_MS);
+}
+/** JSON-RPC id the proxy uses for its own replayed `initialize` — never one the client could send. */
+export const RECONNECT_INITIALIZE_ID = '__reticle_proxy_reinit';
+/** The proxy's own log file, so a silent drop leaves a readable trace the agent can go read. */
+export function proxyLogPath() {
+    return join(homedir(), ReticleDir.ROOT, 'mcp-proxy.log');
+}
+/**
+ * Log to stderr (which the agent host usually swallows) AND to ~/.reticle/mcp-proxy.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.
+ */
+function proxyLog(event, fields = {}) {
+    log(event, fields);
+    try {
+        const dir = join(homedir(), ReticleDir.ROOT);
+        mkdirSync(dir, { recursive: true });
+        appendFileSync(proxyLogPath(), `${JSON.stringify({ event, ...fields })}\n`, 'utf8');
+    }
+    catch {
+        // Logging must never be the thing that kills the proxy.
+    }
+}
+function parseJsonRpc(line) {
+    try {
+        const parsed = JSON.parse(line);
+        return typeof parsed === 'object' && parsed !== null ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+const INITIALIZE_METHOD = 'initialize';
+const INITIALIZED_METHOD = 'notifications/initialized';
+/**
+ * Makes a reconnect invisible to the client.
+ *
+ * The daemon builds a FRESH `McpServer` per SSE connection, so a reconnected session has never seen
+ * the client's `initialize` — every subsequent `tools/call` would hit an uninitialized server. The
+ * proxy therefore remembers the handshake the client sent once and replays it into each new session.
+ * The replay is re-issued under a reserved id so the daemon's response to it can be dropped rather
+ * than reaching the client's stdout, where a duplicate JSON-RPC id would be a protocol violation.
+ */
+export class HandshakeReplay {
+    #initialize = null;
+    #initialized = null;
+    #pendingReplayId = null;
+    /** Record one outbound client line. Cheap enough to call for every stdin message. */
+    observeOutbound(line) {
+        const msg = parseJsonRpc(line);
+        if (msg === null)
+            return;
+        // The first initialize is the session's identity; a client re-issuing one does not change it.
+        if (msg.method === INITIALIZE_METHOD && this.#initialize === null)
+            this.#initialize = line;
+        else if (msg.method === INITIALIZED_METHOD)
+            this.#initialized = line;
+    }
+    /** Lines to POST into a freshly-established session, before any queued client traffic. */
+    replayLines() {
+        if (this.#initialize === null)
+            return [];
+        const msg = parseJsonRpc(this.#initialize);
+        if (msg === null)
+            return [];
+        this.#pendingReplayId = RECONNECT_INITIALIZE_ID;
+        const reinit = { ...msg, id: RECONNECT_INITIALIZE_ID };
+        return this.#initialized === null
+            ? [JSON.stringify(reinit)]
+            : [JSON.stringify(reinit), this.#initialized];
+    }
+    /** True when this inbound daemon line is the echo of our replayed handshake and must not be forwarded. */
+    shouldSuppressInbound(line) {
+        if (this.#pendingReplayId === null)
+            return false;
+        const msg = parseJsonRpc(line);
+        if (msg === null || msg.id !== this.#pendingReplayId)
+            return false;
+        this.#pendingReplayId = null; // one response per replay — anything later is not ours to swallow
+        return true;
+    }
+}
 /**
  * Incremental SSE frame parser for the MCP front door.
  *
@@ -126,46 +222,92 @@ export function buildSessionUrl(rawData, port) {
 }
 /**
  * Bridge stdio ↔ SSE: connects to the running daemon's MCP endpoint and forwards
- * Claude Code's stdin/stdout JSON-RPC through it. Never resolves — runs until
- * stdin closes or the SSE stream ends (at which point the process exits so
- * Claude Code restarts the proxy fresh).
+ * Claude Code's stdin/stdout JSON-RPC through it. Never resolves — runs until stdin closes.
+ *
+ * A dropped SSE stream used to exit the process, which is what made the agent's `reticle_*` tools
+ * vanish mid-session with no message and no way for the agent to get them back — only a human running
+ * `/mcp` could. The daemon demonstrably stays up across these drops, so the stream ending is a
+ * transport event, not a shutdown: reconnect to it and replay the handshake instead of dying.
  */
 export function startMcpProxy(port) {
     return new Promise((_resolve, reject) => {
         let postUrl = null;
         const stdinQueue = [];
-        // ── SSE reader ──────────────────────────────────────────────────────────
-        const req = http.get({ host: LOOPBACK_HOST, port, path: MCP_SSE_PATH }, (res) => {
-            res.setEncoding('utf8');
-            const sse = new SseFrameParser();
-            res.on('data', (chunk) => {
-                for (const frame of sse.push(chunk))
-                    onSseEvent(frame.event, frame.data, port);
-            });
-            res.on('end', () => {
-                log('reticle_mcp_proxy_sse_ended', { port });
-                process.exit(0);
-            });
-            res.on('error', (err) => {
-                log('reticle_mcp_proxy_sse_error', { error: err.message });
-                process.exit(1);
-            });
-        });
-        req.on('error', (err) => reject(err));
+        const replay = new HandshakeReplay();
+        let stopped = false;
+        let attempts = 0;
         function onSseEvent(event, data, p) {
             if (event === 'endpoint') {
                 const url = buildSessionUrl(data, p);
                 postUrl = url;
-                // Flush messages that arrived before the session URL was known
-                for (const queued of stdinQueue.splice(0)) {
+                // The new session's McpServer has never seen the client's initialize — replay it first, then
+                // flush whatever the client sent while we were reconnecting.
+                for (const line of replay.replayLines())
+                    void postToSession(url, line);
+                for (const queued of stdinQueue.splice(0))
                     void postToSession(url, queued);
-                }
                 return;
             }
-            if (event === 'message') {
+            if (event === 'message' && !replay.shouldSuppressInbound(data)) {
                 process.stdout.write(`${data}\n`);
             }
         }
+        function scheduleReconnect(reason, detail) {
+            if (stopped)
+                return;
+            postUrl = null;
+            attempts++;
+            if (attempts > MAX_RECONNECT_ATTEMPTS) {
+                proxyLog('reticle_mcp_proxy_gave_up', {
+                    port,
+                    reason,
+                    attempts,
+                    ...(detail !== undefined ? { detail } : {}),
+                });
+                process.exit(1);
+            }
+            const wait = reconnectDelayMs(attempts);
+            proxyLog('reticle_mcp_proxy_reconnecting', {
+                port,
+                reason,
+                attempt: attempts,
+                retryInMs: wait,
+                ...(detail !== undefined ? { detail } : {}),
+            });
+            setTimeout(() => connect(false), wait).unref();
+        }
+        function connect(first) {
+            const req = http.get({ host: LOOPBACK_HOST, port, path: MCP_SSE_PATH }, (res) => {
+                attempts = 0; // a stream we actually established resets the budget
+                if (!first)
+                    proxyLog('reticle_mcp_proxy_reconnected', { port });
+                res.setEncoding('utf8');
+                // `end` and `error` can both fire on one response; only the first should drive a reconnect.
+                let settled = false;
+                const drop = (reason, detail) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    scheduleReconnect(reason, detail);
+                };
+                const sse = new SseFrameParser();
+                res.on('data', (chunk) => {
+                    for (const frame of sse.push(chunk))
+                        onSseEvent(frame.event, frame.data, port);
+                });
+                res.on('end', () => drop('sse_ended'));
+                res.on('error', (err) => drop('sse_error', err.message));
+                // A socket dying under us (daemon killed, network stack reset) emits NEITHER `end` nor
+                // `error` — only `aborted`/`close`. Listening for just the first two is why the proxy sat
+                // there afterwards holding a dead stream. `settled` keeps the clean case single-fire.
+                res.on('aborted', () => drop('sse_aborted'));
+                res.on('close', () => drop('sse_closed'));
+            });
+            // The very first connect failing means there is no daemon to talk to — that is a startup
+            // failure the caller handles. Later ones are just the daemon bouncing: keep retrying.
+            req.on('error', (err) => (first ? reject(err) : scheduleReconnect('connect_error', err.message)));
+        }
+        connect(true);
         // ── stdin reader ─────────────────────────────────────────────────────────
         process.stdin.setEncoding('utf8');
         let stdinBuffer = '';
@@ -177,6 +319,7 @@ export function startMcpProxy(port) {
                 const trimmed = line.trim();
                 if (trimmed === '')
                     continue;
+                replay.observeOutbound(trimmed);
                 if (postUrl === null) {
                     stdinQueue.push(trimmed);
                 }
@@ -185,7 +328,10 @@ export function startMcpProxy(port) {
                 }
             }
         });
-        process.stdin.on('end', () => process.exit(0));
+        // The client going away is the one clean shutdown — stop reconnecting and exit.
+        process.stdin.on('end', () => {
+            stopped = true;
+            process.exit(0);
+        });
     });
 }
-//# sourceMappingURL=mcp-proxy.js.map

package/dist/mcp.d.ts

@@ -10,6 +10,7 @@ import { type ToolProfile } from './tools/profiles.js';
  * Non-session-bound tools (and tools with no outputSchema) are returned unchanged.
  */
 export declare function withSessionEnvelope(name: string, outputSchema: z.ZodRawShape | undefined): z.ZodRawShape | undefined;
+export declare function firstSentence(description: string): string;
 /**
  * Serialize a tool result to the MCP `text` content block. The agent consumes this text — the
  * typed contract travels separately as `structuredContent`, unchanged by encoding — so the text
@@ -32,5 +33,18 @@ export declare function encodeResult(result: unknown, encoding: string): string;
  * call. `full` advertises everything and needs no hatch.
  */
 export declare function advertisedTools(profile: ToolProfile): ToolDef[];
+/**
+ * Exactly what gets advertised for one tool under a profile: trimmed description, lean input shape,
+ * and (non-lean only) the output schema.
+ *
+ * Exported so tests assert on the REAL advertised text rather than on the tool definitions, which
+ * 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): {
+    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;
-//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.js

@@ -1,4 +1,5 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { isToonable, resultToToon } from '@reticlehq/core';
 import { TOOLS } from './tools/tools.js';
@@ -10,6 +11,8 @@ 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';
 /**
  * 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,10 +28,31 @@ const SERVER_INFO = { name: MCP_SERVER_NAME, version: SERVER_VERSION };
 /** 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). */
-function firstSentence(description) {
+/**
+ * Append the tool's example call to whatever description survived trimming.
+ *
+ * Costs a handful of tokens per turn and buys back the failed round trips an agent spends guessing
+ * how the fields compose — which is a far worse trade in the other direction.
+ */
+function withExample(description, example) {
+    return example === undefined ? description : `${description} e.g. ${JSON.stringify(example)}`;
+}
+/**
+ * Abbreviations whose internal period is NOT a sentence end.
+ *
+ * The splitter looked for the first `". "`, which "e.g. " satisfies — so every lean-profile
+ * description containing one was cut off mid-abbreviation. `reticle_act`'s ref parameter reached the
+ * agent as "Element ref from reticle_snapshot or reticle_query (e.g." and stopped: the example gone,
+ * and any contract stated after it gone too. Silent, and it degraded the DEFAULT profile only, which
+ * is the one nobody reads the raw strings for.
+ */
+const ABBREVIATIONS = ['e.g.', 'i.e.', 'etc.', 'vs.', 'cf.'];
+export function firstSentence(description) {
     const nl = description.indexOf('\n');
     const base = nl >= 0 ? description.slice(0, nl) : description;
-    const dot = base.search(/\.\s/);
+    // Mask abbreviations with an equal-length filler so offsets stay valid in the original string.
+    const masked = ABBREVIATIONS.reduce((text, abbr) => text.split(abbr).join('\u0000'.repeat(abbr.length)), base);
+    const dot = masked.search(/\.\s/);
     const sentence = dot >= 0 ? base.slice(0, dot + 1) : base;
     return sentence.length > 160 ? `${sentence.slice(0, 159)}…` : sentence;
 }
@@ -52,9 +76,34 @@ const PREDICATE_PARAMS = new Set(['predicate', 'until']);
  * grammar up front versus letting the agent fetch it from `reticle_tools` when it needs a variant it
  * has not used before.
  */
-const COMPACT_PREDICATE_DESCRIPTION = 'Predicate object: { kind, ...fields }. kind is one of element | text | net | route | console | ' +
-    'animation | signal | state | settled | allOf | anyOf | not. Call reticle_tools for the full ' +
-    'field grammar of a kind.';
+/**
+ * The kind list — the part an agent needs to WRITE a predicate. Carried on every predicate parameter.
+ *
+ * An earlier version put this on one tool and pointed the other five at it ("same grammar as
+ * reticle_act_and_wait's"), which saved 790 B/turn. It was the wrong trade: it made writing a
+ * predicate require joining two tool descriptions, and accuracy is worth more here than the bytes.
+ * Only the "where to get field details" sentence is stated once now — that one IS a pointer, so
+ * making it a pointer costs nothing.
+ */
+const PREDICATE_KINDS = 'Predicate object: { kind, ...fields }. kind is one of element | text | net | route | console | ' +
+    'animation | signal | state | settled | allOf | anyOf | not.';
+/**
+ * Said once per turn: the bug-catching options, and where to get the rest of the field grammar.
+ *
+ * `net.count`, `console.absent` and `absent` are the three predicate options that catch a class of
+ * bug rather than confirm an expectation — a double-submit, an action that "worked" while logging a
+ * caught error, something that should have disappeared and did not. They sat behind a
+ * `reticle_tools` round trip, so an agent only found them if it already knew to look, which is the
+ * wrong way round for the checks most likely to catch what nobody suspected.
+ *
+ * Anchored to one tool rather than repeated on all six: these are ADDITIONAL capability, not what
+ * makes a basic predicate correct, so one mention per turn is enough to make them reachable without
+ * paying for six.
+ */
+const PREDICATE_FIELD_GRAMMAR_HINT = ' Bug-catching options: net.count (exact request count — catches double-submit), ' +
+    'console.absent:true (action completed with a CLEAN console), absent:true on element/text ' +
+    '(it should be gone). Call reticle_tools for the full field grammar of a kind.';
+const COMPACT_PREDICATE_DESCRIPTION = `${PREDICATE_KINDS}${PREDICATE_FIELD_GRAMMAR_HINT}`;
 /**
  * Lean copy of a tool's zod input shape for lean profiles: each parameter's description is
  * truncated to its first sentence via zod's own `.describe` (which returns a new schema, so the
@@ -62,11 +111,14 @@ const COMPACT_PREDICATE_DESCRIPTION = 'Predicate object: { kind, ...fields }. ki
  * schema cost; the first clause keeps each param's purpose and any enum hints. Params without a
  * description pass through unchanged. Predicate params are replaced wholesale — see above.
  */
-function leanZodShape(shape) {
+function leanZodShape(shape, predicateAnchor) {
     const out = {};
     for (const [key, schema] of Object.entries(shape)) {
         if (PREDICATE_PARAMS.has(key)) {
-            const compact = z.record(z.unknown()).describe(COMPACT_PREDICATE_DESCRIPTION);
+            // Every tool keeps the kinds; only the navigation hint is anchored to one.
+            const compact = z
+                .record(z.unknown())
+                .describe(predicateAnchor === undefined ? COMPACT_PREDICATE_DESCRIPTION : PREDICATE_KINDS);
             out[key] = schema.isOptional() ? compact.optional() : compact;
             continue;
         }
@@ -112,9 +164,84 @@ export function advertisedTools(profile) {
     const base = filterTools(TOOLS, profile === TOOL_PROFILE.HYBRID ? TOOL_PROFILE.CORE : profile);
     return [...base, ...buildDynamicTools(TOOLS)];
 }
+/**
+ * Exactly what gets advertised for one tool under a profile: trimmed description, lean input shape,
+ * and (non-lean only) the output schema.
+ *
+ * Exported so tests assert on the REAL advertised text rather than on the tool definitions, which
+ * 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 function advertisedConfig(tool, advertised, profile) {
+    const terse = profile === TOOL_PROFILE.CORE ||
+        profile === TOOL_PROFILE.STANDARD ||
+        profile === TOOL_PROFILE.HYBRID;
+    // 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 outputSchema = terse ? undefined : withSessionEnvelope(tool.name, tool.outputSchema);
+    return {
+        description: withExample(terse ? firstSentence(tool.description) : tool.description, tool.example),
+        inputSchema: terse
+            ? leanZodShape(tool.inputSchema, tool.name === anchor ? undefined : anchor)
+            : tool.inputSchema,
+        ...(outputSchema !== undefined ? { outputSchema } : {}),
+    };
+}
+/** 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)
+        return [];
+    return Object.keys(args).filter((key) => !allowed.has(key));
+}
+export function installFriendlyArgErrors(server, examples, allowedKeys = new Map()) {
+    const target = server;
+    const original = target.validateToolInput;
+    if (typeof original !== 'function')
+        return;
+    target.validateToolInput = async (tool, args, toolName) => {
+        // An UNKNOWN key is the failure zod cannot catch, because object schemas are non-strict: the key
+        // is silently dropped and the tool answers as if it had not been asked. Measured live —
+        // `reticle_clock { action: "freeze" }` returned `{"frozen":false}`, which reads as a fact about
+        // the app ("the clock is not frozen") when it means "you named the parameter wrong". That is a
+        // false NEGATIVE the caller cannot detect from the reply, in every tool at once.
+        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(', ')}. ` +
+                `They were NOT applied — a result computed without them would look like an answer. ` +
+                (example === undefined
+                    ? `Call reticle_tools { names: ["${toolName}"] } for its parameters.`
+                    : `A valid call looks like: ${toolName} ${example}`));
+        }
+        try {
+            return await original.call(server, tool, args, toolName);
+        }
+        catch (error) {
+            // McpError.message already carries "MCP error -32602: "; re-wrapping would print it twice.
+            const raw = error instanceof Error ? error.message : String(error);
+            const detail = raw.replace(/^MCP error -?\d+:\s*/, '');
+            const example = examples.get(toolName);
+            const help = example === undefined
+                ? ` Call reticle_tools { names: ["${toolName}"] } for its parameters.`
+                : ` A valid call looks like: ${toolName} ${example}`;
+            throw new McpError(ErrorCode.InvalidParams, `${detail}${help}`);
+        }
+    };
+}
 export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
     const encoding = (process.env[ENCODING_ENV] ?? '').toLowerCase();
     const server = new McpServer(SERVER_INFO);
+    // 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.
+    setMcpClientNameHook(() => {
+        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.
+        if (info?.name !== undefined)
+            getSessionMetrics().recordClient(info.name);
+        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`.
     const registerTool = server.registerTool.bind(server);
     // `dynamic` advertises only the 2 meta-tools (reticle_tools + reticle_run); real tools load on demand.
@@ -126,9 +253,12 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
     // reticle_flow_save's own description instructs the agent to call. `full` advertises everything
     // directly and needs no hatch.
     const advertised = advertisedTools(profile);
-    const terse = profile === TOOL_PROFILE.CORE ||
-        profile === TOOL_PROFILE.STANDARD ||
-        profile === TOOL_PROFILE.HYBRID;
+    installFriendlyArgErrors(server, new Map(advertised
+        .filter((tool) => tool.example !== undefined)
+        .map((tool) => [tool.name, JSON.stringify(tool.example)])), 
+    // Every tool in TOOLS, not just the advertised ones: reticle_run dispatches to the full table,
+    // so an unadvertised tool reached through the hatch must be just as strict.
+    new Map(TOOLS.map((tool) => [tool.name, new Set(Object.keys(tool.inputSchema))])));
     for (const tool of advertised) {
         // Output schemas are now the largest slice of the per-request tax (55.6% of the hybrid payload
         // after the predicate fix) and we are the only one of the three MCP servers that sends them.
@@ -150,12 +280,7 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
         // handler below is unchanged, so `full`/`dynamic` (non-terse) keep the schema for validating
         // clients. This removes the single largest remaining slice of the per-request tax (~36% of the
         // hybrid payload) with no loss the agent can observe.
-        const outputSchema = terse ? undefined : withSessionEnvelope(tool.name, tool.outputSchema);
-        const config = {
-            description: terse ? firstSentence(tool.description) : tool.description,
-            inputSchema: terse ? leanZodShape(tool.inputSchema) : tool.inputSchema,
-            ...(outputSchema !== undefined ? { outputSchema } : {}),
-        };
+        const config = advertisedConfig(tool, advertised, profile);
         registerTool(tool.name, config, async (args) => {
             try {
                 const result = await runTool(tool, deps, args);
@@ -171,6 +296,10 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 log('tool_error', { tool: tool.name, error: message });
+                // Counted by FINGERPRINT, never by message — see error-fingerprint.ts. This is the single
+                // boundary every agent-visible tool failure crosses, so it is the one place "which error is
+                // hurting people most" can be answered without instrumenting every handler.
+                getSessionMetrics().recordToolError(message, tool.name);
                 // Every error the agent hits should answer "what next?", not just "what broke".
                 return {
                     isError: true,
@@ -181,4 +310,3 @@ export function createMcpServer(deps, profile = TOOL_PROFILE.HYBRID) {
     }
     return server;
 }
-//# sourceMappingURL=mcp.js.map

package/dist/oracles/flow-instrument-gaps.d.ts

@@ -16,4 +16,3 @@ export declare function lastSource(steps: readonly FlowStep[]): {
  * source are skipped (no location to propose). The suggested signal name is `<flow>:done`.
  */
 export declare function instrumentationGapsForFlows(unassertedFlows: readonly string[], flowStepsByName: ReadonlyMap<string, readonly FlowStep[]>): InstrumentationGap[];
-//# sourceMappingURL=flow-instrument-gaps.d.ts.map

package/dist/oracles/flow-instrument-gaps.js

@@ -42,4 +42,3 @@ export function instrumentationGapsForFlows(unassertedFlows, flowStepsByName) {
     }
     return gaps;
 }
-//# sourceMappingURL=flow-instrument-gaps.js.map

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

@@ -19,4 +19,3 @@ export interface ProposedConsequence {
 }
 /** Propose ranked consequences from a recorded event window. Deduped; strongest first. */
 export declare function proposeConsequences(events: readonly ReticleEvent[]): ProposedConsequence[];
-//# sourceMappingURL=propose-consequences.d.ts.map

package/dist/oracles/propose-consequences.js

@@ -90,4 +90,3 @@ export function proposeConsequences(events) {
     }
     return proposals.sort((a, b) => a.tier - b.tier);
 }
-//# sourceMappingURL=propose-consequences.js.map

package/dist/oracles/self-instrument.d.ts

@@ -29,4 +29,3 @@ export interface InstrumentationProposal {
 }
 /** Turn located capability gaps into ready-to-apply instrumentation proposals. Deterministic. */
 export declare function proposeInstrumentation(gaps: readonly InstrumentationGap[]): InstrumentationProposal[];
-//# sourceMappingURL=self-instrument.d.ts.map

package/dist/oracles/self-instrument.js

@@ -41,4 +41,3 @@ export function proposeInstrumentation(gaps) {
         rationale: rationaleFor(gap),
     }));
 }
-//# sourceMappingURL=self-instrument.js.map

package/dist/pairing-token.d.ts

@@ -25,4 +25,3 @@ export declare function nodePairingTokenDeps(): PairingTokenDeps;
  * fails, so the caller degrades to the prior tokenless behavior rather than bricking the daemon.
  */
 export declare function readOrCreatePairingToken(dir: string, deps: PairingTokenDeps): Promise<string | undefined>;
-//# sourceMappingURL=pairing-token.d.ts.map

package/dist/pairing-token.js

@@ -59,4 +59,3 @@ export async function readOrCreatePairingToken(dir, deps) {
         return undefined;
     }
 }
-//# sourceMappingURL=pairing-token.js.map

package/dist/phenomena/phenomena.d.ts

@@ -24,4 +24,3 @@ export declare function detectPreHydrationClicks(events: readonly ReticleEvent[]
 export declare function detectSwallowedErrors(events: readonly ReticleEvent[]): Finding[];
 /** Run every journal-only matcher over a session's events + actions. */
 export declare function detectPhenomena(events: readonly ReticleEvent[], actions: readonly JournalAction[]): Finding[];
-//# sourceMappingURL=phenomena.d.ts.map

package/dist/phenomena/phenomena.js

@@ -99,4 +99,3 @@ export function detectPhenomena(events, actions) {
         ...detectSwallowedErrors(events),
     ];
 }
-//# sourceMappingURL=phenomena.js.map

package/dist/pool/browser-pool.d.ts

@@ -89,4 +89,3 @@ export declare class BrowserPool {
     shutdown(): Promise<void>;
 }
 export {};
-//# sourceMappingURL=browser-pool.d.ts.map

package/dist/pool/browser-pool.js

@@ -236,4 +236,3 @@ export class BrowserPool {
             waiter(); // let them re-claim + relaunch
     }
 }
-//# sourceMappingURL=browser-pool.js.map

package/dist/pool/lease-reaper.d.ts

@@ -13,4 +13,3 @@ export declare class LeaseReaper {
     start(): void;
     stop(): void;
 }
-//# sourceMappingURL=lease-reaper.d.ts.map

package/dist/pool/lease-reaper.js

@@ -38,4 +38,3 @@ export class LeaseReaper {
         this.#timer = undefined;
     }
 }
-//# sourceMappingURL=lease-reaper.js.map

package/dist/pool/playwright-launcher.d.ts

@@ -18,4 +18,3 @@ export declare function playwrightLauncher(opts?: {
  * Pure (env value + cpu count passed in) so it's testable.
  */
 export declare function resolveMaxContexts(envValue: string | undefined, cpuCount: number): number;
-//# sourceMappingURL=playwright-launcher.d.ts.map

package/dist/pool/playwright-launcher.js

@@ -5,6 +5,9 @@
  *
  * Headless by default — the pool exists for fault-tolerant headless multi-agent testing.
  */
+import { BrowserLaunchKind } from '@reticlehq/core';
+import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { classifyConnectFailure } from '../telemetry/connect-failure.js';
 function wrapBrowser(browser) {
     return {
         isConnected: () => browser.isConnected(),
@@ -38,10 +41,16 @@ export function playwrightLauncher(opts = {}) {
     // (where it's meaningful) instead of at import-time (where it kills unrelated features).
     return async () => {
         const { chromium } = await import('playwright');
+        // A pooled launch serves N parallel leases, so this counts BROWSERS, not contexts — which is the
+        // number that actually costs memory and the one that explains a slow machine.
+        const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.POOLED);
         try {
-            return wrapBrowser(await chromium.launch({ headless }));
+            const browser = wrapBrowser(await chromium.launch({ headless }));
+            settle();
+            return browser;
         }
         catch (err) {
+            settle(classifyConnectFailure(err));
             // Turn Playwright's raw "Executable doesn't exist" into the one command that fixes it.
             const msg = err instanceof Error ? err.message : String(err);
             if (/executable doesn.?t exist|playwright install|browsertype\.launch/i.test(msg)) {
@@ -74,4 +83,3 @@ export function resolveMaxContexts(envValue, cpuCount) {
     const byCpu = Math.max(MAX_CONTEXTS_FLOOR, cpuCount - 1);
     return Math.min(MAX_CONTEXTS_CEILING, byCpu);
 }
-//# sourceMappingURL=playwright-launcher.js.map

package/dist/project/baselines.d.ts

@@ -19,4 +19,3 @@ export declare class BaselineStore {
     list(): string[];
 }
 export {};
-//# sourceMappingURL=baselines.d.ts.map

package/dist/project/baselines.js

@@ -44,4 +44,3 @@ export class BaselineStore {
         return [...this.#map.keys()];
     }
 }
-//# sourceMappingURL=baselines.js.map