@reticlehq/server 2.9.0 → 2.11.0

package/dist/license/license.js

@@ -12,6 +12,7 @@
  */
 import { createPublicKey, sign as edSign, verify as edVerify } from 'node:crypto';
 import { z } from 'zod';
+import { LicenseActivation } from '@reticlehq/core';
 /** Outcome of verifying a license key. */
 export const LicenseStatus = {
     VALID: 'valid',
@@ -20,8 +21,19 @@ export const LicenseStatus = {
     BAD_SIGNATURE: 'bad-signature',
     EXPIRED: 'expired',
 };
-/** The signed claims inside a key. `exp` is epoch ms; `features` (optional) scopes which ee features unlock. */
+/**
+ * The signed claims inside a key. `exp` is epoch ms; `features` (optional) scopes which ee features
+ * unlock.
+ *
+ * `lid` is the STABLE LICENSE ID and the only safe join key for per-customer usage: `org` is a display
+ * name a human typed at signing time, so two customers called "Acme" merge into one and a customer who
+ * renames splits into two. Every key carries one (minted by the issuer, `scripts/issue-license.mjs`),
+ * which is why it is required rather than optional — an optional id is one that goes missing on exactly
+ * the keys somebody later needs to attribute, and a key without it should be re-issued, not silently
+ * counted as nobody.
+ */
 const LicensePayloadSchema = z.object({
+    lid: z.string().min(1),
     org: z.string(),
     plan: z.string(),
     exp: z.number(),
@@ -68,40 +80,52 @@ export function verifyLicenseKey(key, publicKey, now) {
     if (!signatureOk)
         return { status: LicenseStatus.BAD_SIGNATURE };
     if (payload.exp <= now)
-        return { status: LicenseStatus.EXPIRED };
+        return { status: LicenseStatus.EXPIRED, payload };
     return { status: LicenseStatus.VALID, payload };
 }
+/**
+ * Where to get a key. A named constant because it appears in the gate's error AND in what
+ * `reticle license` prints, and a contact address that drifts between the two is a support request
+ * that reaches nobody.
+ */
+export const LICENSE_CONTACT = 'hey@reticle.sh';
+/**
+ * The features a licence gates in THIS build. The single source: `assertEnterprise` callers name a
+ * member rather than a string literal, and `reticle license` reports the list, so what the CLI claims
+ * is gated is derived from what is actually gated rather than a second list somebody maintains.
+ *
+ * It is deliberately short. Reticle's roadmap for enterprise is longer (SSO, SCIM, RBAC, multi-org,
+ * policy gates), and none of it is here yet — printing a roadmap as though it were shipped is how a
+ * buyer discovers on day two that the thing they paid for does not exist. What is listed is what the
+ * running build will actually refuse without a key.
+ */
+export const EnterpriseFeature = {
+    /** Recording an audit event. */
+    AUDIT_LOG: 'audit-log',
+};
 /** Thrown when a production-mode enterprise feature is used without a valid license. */
 export class EnterpriseLicenseError extends Error {
     feature;
     reason;
     constructor(feature, reason) {
-        super(`Reticle Enterprise feature "${feature}" requires a valid license (${reason}). Contact hey@reticle.sh.`);
+        super(`Reticle Enterprise feature "${feature}" requires a valid license (${reason}). Contact ${LICENSE_CONTACT}.`);
         this.name = 'EnterpriseLicenseError';
         this.feature = feature;
         this.reason = reason;
     }
 }
-/** The issuer public key from the environment (set at release / by the operator); undefined if unset. */
-function issuerPublicKey() {
-    const pem = process.env[LICENSE_PUBLIC_KEY_ENV];
-    if (pem === undefined || 0 === pem.length)
-        return undefined;
-    try {
-        return createPublicKey(pem);
-    }
-    catch {
-        return undefined;
-    }
-}
 /**
  * Gate an enterprise feature. No-op in dev/eval (requireLicense:false). In production it throws
  * EnterpriseLicenseError unless a valid, unexpired key that covers `feature` is present.
  */
-export function assertEnterprise(feature, ctx) {
+export function assertEnterprise(feature, ctx, env = process.env, baked) {
     if (!ctx.requireLicense)
         return;
-    const publicKey = ctx.publicKey ?? issuerPublicKey();
+    // Resolved exactly as the env-entry point resolves it: BAKED first, env only as the dev/test
+    // hatch. This path used to read the environment alone, so on a real release, where the key is
+    // baked and no env var is set, it denied every valid licence with `no-issuer-key` while
+    // assertEnterpriseFromEnv allowed the same key on the same build. Two gates, one truth.
+    const publicKey = ctx.publicKey ?? loadPublicKey(resolveIssuerPublicKeyPem(env, baked));
     if (publicKey === undefined)
         throw new EnterpriseLicenseError(feature, 'no-issuer-key');
     const check = verifyLicenseKey(ctx.key, publicKey, ctx.now());
@@ -122,7 +146,7 @@ export const LICENSE_PUBLIC_KEY_ENV = 'RETICLE_LICENSE_PUBLIC_KEY';
  * never setting RETICLE_LICENSE_PUBLIC_KEY, because the baked key takes precedence. The public key is
  * safe to ship openly — it can only verify licenses, never mint them (that needs the private key).
  */
-const BAKED_ISSUER_PUBLIC_KEY_PEM = '';
+const BAKED_ISSUER_PUBLIC_KEY_PEM = "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAcg+u61Fs5pwDHcYxFGhaxVaQoUbAdyl+RUdSViZyxDY=\n-----END PUBLIC KEY-----";
 /**
  * Resolve the issuer public-key PEM enforcement uses: the baked-in release key wins, so it can't be
  * turned off from the environment. Only when nothing is baked (dev/repo) does the env var apply — that
@@ -134,6 +158,15 @@ function resolveIssuerPublicKeyPem(env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
     const envPem = env[LICENSE_PUBLIC_KEY_ENV];
     return envPem !== undefined && envPem.length > 0 ? envPem : undefined;
 }
+/**
+ * The two fields every report carries, spread into each branch. One object rather than a field on each
+ * return, because the value that must never go missing is the one on the branch nobody was thinking
+ * about — and the branch an unlicensed reader lands on is exactly that branch.
+ */
+const LICENSE_OFFER = {
+    gated: Object.values(EnterpriseFeature),
+    contact: LICENSE_CONTACT,
+};
 function loadPublicKey(pem) {
     if (pem === undefined || 0 === pem.length)
         return undefined;
@@ -156,42 +189,73 @@ export function describeLicense(now, env = process.env, baked = BAKED_ISSUER_PUB
         // is off, and assertEnterpriseFromEnv now denies rather than unlocking. Say so loudly here too.
         return isProductionEnv(env)
             ? {
-                status: 'invalid',
+                ...LICENSE_OFFER,
+                status: LicenseActivation.INVALID,
                 detail: 'MISCONFIGURED — running in production with no issuer key baked; enterprise features are DENIED (rebuild with BAKED_ISSUER_PUBLIC_KEY_PEM stamped in)',
             }
             : {
-                status: 'eval',
+                ...LICENSE_OFFER,
+                status: LicenseActivation.EVAL,
                 detail: 'evaluation mode: enterprise features run free (no issuer key configured)',
             };
     }
     const publicKey = loadPublicKey(pem);
     if (publicKey === undefined)
-        return { status: 'invalid', detail: `${LICENSE_PUBLIC_KEY_ENV} is not a valid public key` };
+        return {
+            ...LICENSE_OFFER,
+            status: LicenseActivation.INVALID,
+            detail: `${LICENSE_PUBLIC_KEY_ENV} is not a valid public key`,
+        };
     const check = verifyLicenseKey(env[LICENSE_KEY_ENV], publicKey, now);
     if (check.status === LicenseStatus.VALID) {
-        const { org, plan, exp, features } = check.payload;
+        const { lid, org, plan, exp, features } = check.payload;
+        // A key scoped to features this build does not gate is `active` and unlocks nothing. Both halves
+        // were already on screen (`features` against `gated`) and nothing joined them, so the one word a
+        // customer actually reads told them they were fine while every gated call refused them.
+        const coversNothingHere = features !== undefined && !features.some((f) => LICENSE_OFFER.gated.includes(f));
+        const detail = coversNothingHere
+            ? `licensed to ${org} (${plan}), expires ${new Date(exp).toISOString()}. This key covers ${features?.join(', ')}, and nothing this build gates (${LICENSE_OFFER.gated.join(', ')}) is included. Contact ${LICENSE_CONTACT}`
+            : `licensed to ${org} (${plan}), expires ${new Date(exp).toISOString()}`;
         return {
-            status: 'active',
+            contact: LICENSE_CONTACT,
+            // The one active case that still needs the list: a key covering nothing this build gates is
+            // reported here, and the sentence explaining it is unreadable without both sides named.
+            ...(coversNothingHere ? { gated: LICENSE_OFFER.gated } : {}),
+            status: LicenseActivation.ACTIVE,
+            licenseId: lid,
             org,
             plan,
             expiresAt: exp,
             ...(features !== undefined ? { features } : {}),
-            detail: `licensed to ${org} (${plan}), expires ${new Date(exp).toISOString()}`,
+            ...(coversNothingHere ? { coversNothingHere } : {}),
+            detail,
         };
     }
     if (check.status === LicenseStatus.MISSING) {
         return {
-            status: 'missing',
-            detail: `set ${LICENSE_KEY_ENV} to activate enterprise features in production`,
+            ...LICENSE_OFFER,
+            status: LicenseActivation.MISSING,
+            detail: `set ${LICENSE_KEY_ENV} to activate enterprise features in production. ` +
+                `Request a key from ${LICENSE_CONTACT}`,
         };
     }
     if (check.status === LicenseStatus.EXPIRED) {
+        // The id rides an expired key so a lapse can be attributed to a CUSTOMER. Without it, telemetry
+        // reports that somebody's licence ran out and cannot say whose, which is not a renewal signal.
         return {
-            status: 'expired',
-            detail: 'license expired — renew to keep using enterprise features',
+            ...LICENSE_OFFER,
+            status: LicenseActivation.EXPIRED,
+            licenseId: check.payload.lid,
+            org: check.payload.org,
+            expiresAt: check.payload.exp,
+            detail: `license expired. Renew with ${LICENSE_CONTACT} to keep using enterprise features`,
         };
     }
-    return { status: 'invalid', detail: `license key rejected (${check.status})` };
+    return {
+        ...LICENSE_OFFER,
+        status: LicenseActivation.INVALID,
+        detail: `license key rejected (${check.status}). ${LICENSE_CONTACT} can re-issue it`,
+    };
 }
 /** True in a production runtime (NODE_ENV=production) — where a missing issuer key is a mis-built
  *  release, not an eval session, so the gate must fail CLOSED rather than run features free. */

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

@@ -1,3 +1,5 @@
+export { SseFrameParser, type SseFrame } from './sse-frame-parser.js';
+export { probeDaemon, waitForDaemon } from './proxy-daemon-probe.js';
 /**
  * Re-exported so every existing caller (and every spec) keeps importing the proxy's log from the
  * proxy. Where the code lives is a file-size decision; where it is imported from is an API.
@@ -92,33 +94,6 @@ export declare class HandshakeReplay {
     /** True when this inbound daemon line is the echo of our replayed handshake and must not be forwarded. */
     shouldSuppressInbound(line: string): boolean;
 }
-/** One parsed Server-Sent-Events frame: the event name (defaulted to "message") and its data. */
-interface SseFrame {
-    event: string;
-    data: string;
-}
-/**
- * Incremental SSE frame parser for the MCP front door.
- *
- * A single SSE field can split across TCP reads (`da` in one chunk, `ta: {...}` in the next), and a
- * server may send CRLF or bare CR line endings — so the framing is stateful and edge-case-prone, yet it
- * carried every MCP message the agent sends and was only ever exercised end-to-end. Pulled out of the
- * socket handler as a pure, chunk-fed parser so those boundaries are unit-testable: feed raw chunks,
- * get back each complete frame (a blank line terminates a frame; `event:` names it, `data:` lines
- * accumulate newline-joined; `id:`/`retry:`/comments are ignored — not needed for the bridge).
- */
-export declare class SseFrameParser {
-    #private;
-    push(chunk: string): SseFrame[];
-}
-/**
- * Returns true if something is already listening on the reticle port.
- * Uses a plain TCP probe so we don't create a side-effectful SSE session
- * inside the daemon just to check reachability.
- */
-export declare function probeDaemon(port: number): Promise<boolean>;
-/** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
-export declare function waitForDaemon(port: number): Promise<void>;
 /**
  * Turn an `endpoint` frame's data into a POST target, or null when there is nothing usable in it.
  *

package/dist/mcp/mcp-proxy.js

@@ -2,8 +2,11 @@ import * as http from 'node:http';
 import { localInitializeResponse, isHandshakeLine, drainLines, MAX_STDIN_LINE_BYTES, } from './proxy-handshake.js';
 import { ToolCatalogCache } from './tool-catalog-cache.js';
 import { toolsChangedNotification } from './proxy-handshake.js';
-import * as net from 'node:net';
 import { LOOPBACK_HOST, MCP_SSE_PATH, MCP_SHUTDOWN_EVENT, ReticleEnv, CONTRACT_FINGERPRINT, } from '@reticlehq/core';
+import { SseFrameParser } from './sse-frame-parser.js';
+export { SseFrameParser } from './sse-frame-parser.js';
+export { probeDaemon, waitForDaemon } from './proxy-daemon-probe.js';
+import { probeDaemon } from './proxy-daemon-probe.js';
 import { SERVER_VERSION } from '../version/server-version.js';
 import { buildServerInstructions } from './server-instructions.js';
 import { hasProjectConnectedBefore } from '../session/connection-memory.js';
@@ -26,20 +29,6 @@ export { accountProxyLogWrite, proxyLog, proxyLogPath, PROXY_LOG_CHECK_BYTES, re
 import { proxyLog } from './proxy-log.js';
 import { log } from '../log.js';
 import { OutageReason, OutageStage, reportMcpOutage } from './mcp-outage.js';
-const DEFAULT_DAEMON_READY_TIMEOUT_MS = 10_000;
-/**
- * How long to wait for the spawned daemon's port to accept connections before giving up. The default
- * suits a normal machine; a slow CI/VM (heavy headless-browser launch) can raise it via the
- * RETICLE_DAEMON_READY_TIMEOUT_MS env var. Invalid/absent values fall back to the default.
- */
-const envDaemonReadyTimeoutMs = Number(process.env['RETICLE_DAEMON_READY_TIMEOUT_MS']);
-const DAEMON_READY_TIMEOUT_MS = Number.isFinite(envDaemonReadyTimeoutMs) && envDaemonReadyTimeoutMs > 0
-    ? envDaemonReadyTimeoutMs
-    : DEFAULT_DAEMON_READY_TIMEOUT_MS;
-const DAEMON_POLL_INTERVAL_MS = 100;
-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;
@@ -264,79 +253,6 @@ export class HandshakeReplay {
         return true;
     }
 }
-/**
- * Incremental SSE frame parser for the MCP front door.
- *
- * A single SSE field can split across TCP reads (`da` in one chunk, `ta: {...}` in the next), and a
- * server may send CRLF or bare CR line endings — so the framing is stateful and edge-case-prone, yet it
- * carried every MCP message the agent sends and was only ever exercised end-to-end. Pulled out of the
- * socket handler as a pure, chunk-fed parser so those boundaries are unit-testable: feed raw chunks,
- * get back each complete frame (a blank line terminates a frame; `event:` names it, `data:` lines
- * accumulate newline-joined; `id:`/`retry:`/comments are ignored — not needed for the bridge).
- */
-export class SseFrameParser {
-    #buffer = '';
-    #event = '';
-    #data = '';
-    push(chunk) {
-        this.#buffer += chunk;
-        // Normalise CRLF/CR so the splitter only handles \n, then hold the trailing partial line for the
-        // next chunk (it may complete later).
-        const normalised = this.#buffer.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
-        const lines = normalised.split('\n');
-        this.#buffer = lines.pop() ?? '';
-        const frames = [];
-        for (const line of lines) {
-            if ('' === line) {
-                if (this.#data !== '') {
-                    frames.push({ event: this.#event !== '' ? this.#event : 'message', data: this.#data });
-                }
-                this.#event = '';
-                this.#data = '';
-            }
-            else if (line.startsWith('event:')) {
-                this.#event = line.slice(6).trim();
-            }
-            else if (line.startsWith('data:')) {
-                const val = line.slice(5).trim();
-                this.#data = this.#data !== '' ? `${this.#data}\n${val}` : val;
-            }
-        }
-        return frames;
-    }
-}
-/**
- * Returns true if something is already listening on the reticle port.
- * Uses a plain TCP probe so we don't create a side-effectful SSE session
- * inside the daemon just to check reachability.
- */
-export function probeDaemon(port) {
-    return new Promise((resolve) => {
-        const socket = new net.Socket();
-        socket.setTimeout(500);
-        socket.on('connect', () => {
-            socket.destroy();
-            resolve(true);
-        });
-        socket.on('error', () => resolve(false));
-        socket.on('timeout', () => {
-            socket.destroy();
-            resolve(false);
-        });
-        socket.connect(port, LOOPBACK_HOST);
-    });
-}
-/** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
-export async function waitForDaemon(port) {
-    const deadline = Date.now() + DAEMON_READY_TIMEOUT_MS;
-    while (Date.now() < deadline) {
-        const reachable = await probeDaemon(port);
-        if (reachable)
-            return;
-        await delay(DAEMON_POLL_INTERVAL_MS);
-    }
-    throw new Error(`reticle daemon did not become ready on port ${port} within ${DAEMON_READY_TIMEOUT_MS}ms`);
-}
 /**
  * POST one JSON-RPC line into the daemon's session. Resolves null on success, or a short reason
  * when the request never reached a server that will answer it.

package/dist/mcp/mcp.d.ts

@@ -35,7 +35,14 @@ export declare function encodeResult(result: unknown, encoding: string): string;
  * "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(surface: ToolSurface): ToolDef[];
+export declare function advertisedTools(surface: ToolSurface, 
+/**
+ * The full table to advertise from. Defaults to what this package ships.
+ *
+ * A consumer embedding the engine passes its own composition — ours plus its own — so its tools
+ * reach the wire without editing the shipped array.
+ */
+tools?: readonly ToolDef[]): ToolDef[];
 /**
  * Exactly what gets advertised for one tool under a profile: trimmed description, lean input shape,
  * and (non-lean only) the output schema.
@@ -59,4 +66,13 @@ export declare function createMcpServer(deps: ToolDeps, profile?: ToolSurface,
  * told to instrument a project that is already wired loses a paragraph, while an agent not told
  * loses the entire install — and the second is what the field overwhelmingly shows.
  */
-previouslyConnected?: boolean): McpServer;
+previouslyConnected?: boolean, 
+/**
+ * The full tool table this server serves. Defaults to what this package ships.
+ *
+ * Threaded rather than read from the module so a consumer can serve its own tools on one surface
+ * with ours. It reaches all three places that need the WHOLE table and not just the advertised
+ * slice: the profile filter, the `reticle_run` hatch, and the unadvertised-tool help — a consumer
+ * tool missing from either of the last two is a tool the agent is actively told does not exist.
+ */
+tools?: readonly ToolDef[]): McpServer;

package/dist/mcp/mcp.js

@@ -2,7 +2,7 @@ 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 { isToonable, resultToToon, MCP_SERVER_NAME } from '@reticlehq/core';
 import { TOOLS } from '../tools/tools.js';
 import { filterTools, describeToolSurface, TOOL_SURFACE, } from '../tools/tool-surface.js';
 import { ReticleTool } from '../tools/tool-names.js';
@@ -18,7 +18,6 @@ import { unadvertisedToolHelp } from '../tools/unadvertised-help.js';
 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';
 import { parsePredicate } from '../events/predicate-parse.js';
@@ -201,11 +200,24 @@ export function encodeResult(result, encoding) {
  * "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(surface) {
+export function advertisedTools(surface, 
+/**
+ * The full table to advertise from. Defaults to what this package ships.
+ *
+ * A consumer embedding the engine passes its own composition — ours plus its own — so its tools
+ * reach the wire without editing the shipped array.
+ */
+tools = TOOLS) {
     // 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)];
+    // The profile trims OUR table only. A tool this package does not ship was appended deliberately by
+    // whoever is embedding us, and our `CORE_TOOL_NAMES` was never going to contain its name — so
+    // filtering it would drop every consumer tool and look exactly like the feature not working.
+    const shipped = new Set(TOOLS.map((tool) => tool.name));
+    const ours = tools.filter((tool) => shipped.has(tool.name));
+    const theirs = tools.filter((tool) => !shipped.has(tool.name));
+    return [...filterTools([...ours], surface), ...theirs, ...buildDynamicTools([...tools], origin)];
 }
 /**
  * Exactly what gets advertised for one tool under a profile: trimmed description, lean input shape,
@@ -364,7 +376,16 @@ export function createMcpServer(deps, profile = TOOL_SURFACE.DEFAULT,
  * told to instrument a project that is already wired loses a paragraph, while an agent not told
  * loses the entire install — and the second is what the field overwhelmingly shows.
  */
-previouslyConnected = false) {
+previouslyConnected = false, 
+/**
+ * The full tool table this server serves. Defaults to what this package ships.
+ *
+ * Threaded rather than read from the module so a consumer can serve its own tools on one surface
+ * with ours. It reaches all three places that need the WHOLE table and not just the advertised
+ * slice: the profile filter, the `reticle_run` hatch, and the unadvertised-tool help — a consumer
+ * tool missing from either of the last two is a tool the agent is actively told does not exist.
+ */
+tools = TOOLS) {
     const encoding = (process.env[ENCODING_ENV] ?? '').toLowerCase();
     // 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
@@ -412,13 +433,13 @@ previouslyConnected = false) {
     // 11 tools were unreachable with no escape hatch — including reticle_annotate, which
     // reticle_flow_save's own description instructs the agent to call. `full` advertises everything
     // directly and needs no hatch.
-    const advertised = advertisedTools(profile);
+    const advertised = advertisedTools(profile, tools);
     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))])));
+    // Every tool in the table, 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.
@@ -480,6 +501,6 @@ previouslyConnected = false) {
     // `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)));
+    installUnadvertisedToolHelp(server, new Set(advertised.map((tool) => tool.name)), new Set(tools.map((tool) => tool.name)));
     return server;
 }

package/dist/mcp/proxy-daemon-probe.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Returns true if something is already listening on the reticle port.
+ * Uses a plain TCP probe so we don't create a side-effectful SSE session
+ * inside the daemon just to check reachability.
+ */
+export declare function probeDaemon(port: number): Promise<boolean>;
+/** Poll until the daemon's HTTP port accepts connections or the deadline is reached. */
+export declare function waitForDaemon(port: number): Promise<void>;

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

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

package/dist/mcp/proxy-handshake.js

@@ -14,8 +14,8 @@
  * 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';
+import { MCP_SERVER_NAME } from '@reticlehq/core';
 /** The version we answer with if the client proposed none. */
 const FALLBACK_PROTOCOL_VERSION = '2024-11-05';
 /**

package/dist/mcp/server-instructions.js

@@ -22,7 +22,7 @@ import { SHARED_PARAM_GUIDANCE } from './shared-params.js';
 /** The tools, and the rule that only two of them decide anything. Constant across both states. */
 const VERDICT_DISCIPLINE = `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.`;
+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. Only verified:"yes" is a pass — "unknown" means Reticle could not tell what happened, "no-fault" means nothing was declared to prove. Report either as not proved.`;
 /**
  * The first move, for a project no app has ever connected to.
  *
@@ -41,7 +41,7 @@ const FEEDBACK_ASK = `Feedback is first-class here, not a courtesy. Reticle is b
 - 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.`;
+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 <one of those kinds> "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.`;
 /** The instructions this daemon should advertise, given what it knows about the project. */
 /**
  * Instructions are sent ONCE at initialize; the tool surface is re-sent every turn. Measured on this

package/dist/mcp/sse-frame-parser.d.ts

@@ -0,0 +1,19 @@
+/** One parsed Server-Sent-Events frame: the event name (defaulted to "message") and its data. */
+export interface SseFrame {
+    event: string;
+    data: string;
+}
+/**
+ * Incremental SSE frame parser for the MCP front door.
+ *
+ * A single SSE field can split across TCP reads (`da` in one chunk, `ta: {...}` in the next), and a
+ * server may send CRLF or bare CR line endings — so the framing is stateful and edge-case-prone, yet it
+ * carried every MCP message the agent sends and was only ever exercised end-to-end. Pulled out of the
+ * socket handler as a pure, chunk-fed parser so those boundaries are unit-testable: feed raw chunks,
+ * get back each complete frame (a blank line terminates a frame; `event:` names it, `data:` lines
+ * accumulate newline-joined; `id:`/`retry:`/comments are ignored — not needed for the bridge).
+ */
+export declare class SseFrameParser {
+    #private;
+    push(chunk: string): SseFrame[];
+}

package/dist/mcp/sse-frame-parser.js

@@ -0,0 +1,41 @@
+/**
+ * Incremental SSE frame parser for the MCP front door.
+ *
+ * A single SSE field can split across TCP reads (`da` in one chunk, `ta: {...}` in the next), and a
+ * server may send CRLF or bare CR line endings — so the framing is stateful and edge-case-prone, yet it
+ * carried every MCP message the agent sends and was only ever exercised end-to-end. Pulled out of the
+ * socket handler as a pure, chunk-fed parser so those boundaries are unit-testable: feed raw chunks,
+ * get back each complete frame (a blank line terminates a frame; `event:` names it, `data:` lines
+ * accumulate newline-joined; `id:`/`retry:`/comments are ignored — not needed for the bridge).
+ */
+export class SseFrameParser {
+    #buffer = '';
+    #event = '';
+    #data = '';
+    push(chunk) {
+        this.#buffer += chunk;
+        // Normalise CRLF/CR so the splitter only handles \n, then hold the trailing partial line for the
+        // next chunk (it may complete later).
+        const normalised = this.#buffer.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+        const lines = normalised.split('\n');
+        this.#buffer = lines.pop() ?? '';
+        const frames = [];
+        for (const line of lines) {
+            if ('' === line) {
+                if (this.#data !== '') {
+                    frames.push({ event: this.#event !== '' ? this.#event : 'message', data: this.#data });
+                }
+                this.#event = '';
+                this.#data = '';
+            }
+            else if (line.startsWith('event:')) {
+                this.#event = line.slice(6).trim();
+            }
+            else if (line.startsWith('data:')) {
+                const val = line.slice(5).trim();
+                this.#data = this.#data !== '' ? `${this.#data}\n${val}` : val;
+            }
+        }
+        return frames;
+    }
+}