@reticlehq/server 2.13.1 → 2.14.0

package/dist/mcp/mcp-proxy.js

@@ -32,6 +32,7 @@ import { proxyLog } from './proxy-log.js';
 import { OutageReason, OutageStage, reportMcpOutage } from './mcp-outage.js';
 import { postToSession } from './mcp-post-transport.js';
 import { reconnectDelayMs } from './proxy-backoff.js';
+import { PROXY_IDLE_EXIT_EVENT, ProxyIdleExit, resolveProxyIdleExitMs } from './proxy-idle-exit.js';
 export { reconnectDelayMs, RECONNECT_BASE_MS, RECONNECT_CAP_MS } from './proxy-backoff.js';
 export { MCP_PROXY_HTTP_AGENT_OPTIONS, postToSession, shouldRetryUnsentPost, } from './mcp-post-transport.js';
 /**
@@ -301,7 +302,9 @@ export function startMcpProxy(port,
  * budget ran out and then killed itself, taking the agent's whole Reticle surface with it — the
  * failure mode for a daemon that crashed, was stopped, or shut itself down as idle.
  */
-ensureDaemon) {
+ensureDaemon, 
+/** Observe the real shutdown boundary in transport tests without terminating their worker. */
+exitProcess = (code) => process.exit(code)) {
     return new Promise((_resolve, reject) => {
         // A client just started us, which is the only honest evidence that Reticle is registered with
         // one at all: a config entry proves somebody wrote JSON, not that a client ever read it. Paired
@@ -313,6 +316,7 @@ ensureDaemon) {
         // a runtime throw, not a type error.
         const catalog = new ToolCatalogCache();
         let postUrl = null;
+        let stopped = false;
         /**
          * No daemon is listening and the proxy has stopped chasing one.
          *
@@ -383,12 +387,33 @@ ensureDaemon) {
         };
         const replay = new HandshakeReplay();
         const pending = new PendingRequests();
+        const quit = (code) => {
+            if (stopped)
+                return;
+            stopped = true;
+            idleExit.stop();
+            // Await: fire-and-forget here is how daemon_stopped never arrived.
+            void flushProxySessionMetrics().finally(() => exitProcess(code));
+        };
+        const idleExit = new ProxyIdleExit({
+            graceMs: resolveProxyIdleExitMs(process.env[ReticleEnv.MCP_PROXY_IDLE]),
+            isBusy: () => pending.unanswered.length > 0 || stdinQueue.length > 0,
+            onExit: (idleMs) => {
+                proxyLog(PROXY_IDLE_EXIT_EVENT, {
+                    port,
+                    idleMs,
+                    note: 'the client link was quiet for the configured idle window with no work in flight; exiting the abandoned proxy',
+                });
+                quit(0);
+            },
+        });
+        idleExit.start();
         /** The ONE way a line reaches the client — so nothing can be answered without clearing the debt. */
         const emit = (line) => {
+            idleExit.noteTraffic();
             pending.observeInbound(line);
             process.stdout.write(`${line}\n`);
         };
-        let stopped = false;
         let attempts = 0;
         /** The daemon announced a planned shutdown; the next drop is that, not a fault. */
         let daemonRetiring = false;
@@ -736,6 +761,9 @@ ensureDaemon) {
         let stdinBuffer = '';
         let stdinDiscarding = false;
         process.stdin.on('data', (chunk) => {
+            if (stopped)
+                return;
+            idleExit.noteTraffic();
             // Not `(buffer + chunk).split()` inline — that rescans everything held on every chunk, so one
             // large line cost O(n²) in its own size and pinned the event loop for tens of seconds, during
             // which every other tool call on this link hung with no response and no error. See drainLines.
@@ -819,11 +847,8 @@ ensureDaemon) {
         // between the writes made it "work", which is the signature of a teardown race, not of a client
         // that asked for too much. Drain first, and let the exit status carry the truth if it fails.
         process.stdin.on('end', () => {
-            const quit = (code) => {
-                stopped = true;
-                // Await: fire-and-forget here is how daemon_stopped never arrived.
-                void flushProxySessionMetrics().finally(() => process.exit(code));
-            };
+            if (stopped)
+                return;
             if (0 === pending.unanswered.length) {
                 quit(0);
                 return;

package/dist/mcp/mcp.js

@@ -122,7 +122,9 @@ const PREDICATE_KINDS = 'Predicate object: { kind, ...fields }. kind is one of e
  */
 const PREDICATE_FIELD_GRAMMAR_HINT = ' Bug-catching options: net.count (exact request count — catches double-submit), ' +
     'net.bodyContains (a substring of what the SERVER answered — catches a UI that echoes the input ' +
-    'it sent instead of the result it got back), console.absent:true (action completed with a CLEAN ' +
+    'it sent instead of the result it got back), net.requestBodyMatches (a shallow JSON match on what ' +
+    'the UI SENT — the verdict for "applying this filter actually puts it in the payload"), ' +
+    '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}`;

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

@@ -75,7 +75,7 @@ export declare function degradedInstructions(healthy: string, port: number, reas
  * out-of-memory exit that would take the agent's whole tool surface with it.
  */
 export declare const MAX_STDIN_LINE_BYTES: number;
-export interface DrainedLines {
+interface DrainedLines {
     /** Complete lines, in order. Empty when the chunk carried no newline. */
     lines: string[];
     /** The trailing partial line, carried into the next chunk. */
@@ -105,3 +105,4 @@ export interface DrainedLines {
  * the concatenation alone. Only a chunk that actually carries a newline pays for a scan.
  */
 export declare function drainLines(buffer: string, chunk: string, maxLineBytes?: number, discarding?: boolean): DrainedLines;
+export {};

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

@@ -0,0 +1,45 @@
+/**
+ * A live proxy is more valuable than a reclaimed one: unlike the daemon, no client automatically
+ * respawns the stdio server after it exits. Give a quiet but still-open client a full day before
+ * deciding it was abandoned. That is deliberately much longer than the daemon's attached grace,
+ * while still bounding the process pairs that were observed surviving for several days.
+ *
+ * Kept independent of the daemon's configured grace: changing how soon an unused daemon retires
+ * must not silently change how soon an editor loses its MCP server.
+ */
+export declare const PROXY_IDLE_EXIT_MS: number;
+/** The local diagnostic emitted before an abandoned proxy exits. */
+export declare const PROXY_IDLE_EXIT_EVENT = "reticle_mcp_proxy_idle_exit";
+export interface ProxyIdleExitOptions {
+    /** Called once after the client link has stayed quiet for the whole grace. */
+    onExit: (idleMs: number) => void;
+    /** True while a request or queued message still needs an answer. */
+    isBusy?: () => boolean;
+    /** Continuous quiet window before exit. A non-positive value disables the watcher. */
+    graceMs?: number;
+    /** How often to re-check the link. */
+    checkIntervalMs?: number;
+    /** Injected clock for deterministic tests. */
+    clock?: () => number;
+}
+/**
+ * Reaps an abandoned MCP stdio proxy without mistaking a thinking pause or an in-flight call for an
+ * abandoned client. Client traffic restarts the grace, and active work starts a fresh grace only
+ * after it has settled. The interval is unref'd so this watcher can never keep the process alive by
+ * itself.
+ */
+export declare class ProxyIdleExit {
+    #private;
+    constructor(opts: ProxyIdleExitOptions);
+    /** Record bytes moving across the client-facing stdio link. */
+    noteTraffic(): void;
+    /** Run one idle check. Exposed so tests can drive the decision with an injected clock. */
+    check(): void;
+    start(): void;
+    stop(): void;
+}
+/**
+ * Resolve the proxy-idle environment control: a non-negative quiet window in milliseconds, with
+ * zero as the explicit opt-out. Invalid values retain the conservative one-day default.
+ */
+export declare function resolveProxyIdleExitMs(raw: string | undefined): number;

package/dist/mcp/proxy-idle-exit.js

@@ -0,0 +1,94 @@
+import { SESSION_LIFECYCLE } from '@reticlehq/core';
+/**
+ * A live proxy is more valuable than a reclaimed one: unlike the daemon, no client automatically
+ * respawns the stdio server after it exits. Give a quiet but still-open client a full day before
+ * deciding it was abandoned. That is deliberately much longer than the daemon's attached grace,
+ * while still bounding the process pairs that were observed surviving for several days.
+ *
+ * Kept independent of the daemon's configured grace: changing how soon an unused daemon retires
+ * must not silently change how soon an editor loses its MCP server.
+ */
+export const PROXY_IDLE_EXIT_MS = 24 * 60 * 60_000;
+/** The local diagnostic emitted before an abandoned proxy exits. */
+export const PROXY_IDLE_EXIT_EVENT = 'reticle_mcp_proxy_idle_exit';
+/**
+ * Reaps an abandoned MCP stdio proxy without mistaking a thinking pause or an in-flight call for an
+ * abandoned client. Client traffic restarts the grace, and active work starts a fresh grace only
+ * after it has settled. The interval is unref'd so this watcher can never keep the process alive by
+ * itself.
+ */
+export class ProxyIdleExit {
+    #timer;
+    #lastTrafficAt;
+    #wasBusy = false;
+    #fired = false;
+    #onExit;
+    #isBusy;
+    #graceMs;
+    #checkIntervalMs;
+    #clock;
+    constructor(opts) {
+        this.#onExit = opts.onExit;
+        this.#isBusy = opts.isBusy ?? (() => false);
+        this.#graceMs = opts.graceMs ?? PROXY_IDLE_EXIT_MS;
+        this.#checkIntervalMs =
+            opts.checkIntervalMs ??
+                Math.min(SESSION_LIFECYCLE.DAEMON_IDLE_CHECK_MS, Math.max(1, this.#graceMs));
+        this.#clock = opts.clock ?? (() => Date.now());
+        this.#lastTrafficAt = this.#clock();
+    }
+    /** Record bytes moving across the client-facing stdio link. */
+    noteTraffic() {
+        if (this.#fired)
+            return;
+        this.#lastTrafficAt = this.#clock();
+    }
+    /** Run one idle check. Exposed so tests can drive the decision with an injected clock. */
+    check() {
+        if (this.#fired || this.#graceMs <= 0)
+            return;
+        const now = this.#clock();
+        const busy = this.#isBusy();
+        if (busy) {
+            this.#wasBusy = true;
+            this.#lastTrafficAt = now;
+            return;
+        }
+        // A queued message can become settled between checks without producing client-facing traffic.
+        // Start a complete grace window at that transition instead of measuring from the last busy poll.
+        if (this.#wasBusy) {
+            this.#wasBusy = false;
+            this.#lastTrafficAt = now;
+            return;
+        }
+        const idleMs = now - this.#lastTrafficAt;
+        if (idleMs < this.#graceMs)
+            return;
+        this.#fired = true;
+        this.#onExit(idleMs);
+    }
+    start() {
+        if (this.#graceMs <= 0 || this.#timer !== undefined)
+            return;
+        this.#timer = setInterval(() => this.check(), this.#checkIntervalMs);
+        this.#timer.unref();
+    }
+    stop() {
+        if (this.#timer === undefined)
+            return;
+        clearInterval(this.#timer);
+        this.#timer = undefined;
+    }
+}
+/**
+ * Resolve the proxy-idle environment control: a non-negative quiet window in milliseconds, with
+ * zero as the explicit opt-out. Invalid values retain the conservative one-day default.
+ */
+export function resolveProxyIdleExitMs(raw) {
+    if (raw === undefined || '' === raw.trim())
+        return PROXY_IDLE_EXIT_MS;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0)
+        return PROXY_IDLE_EXIT_MS;
+    return Math.floor(value);
+}

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

@@ -1,4 +1,4 @@
-export interface InstructionState {
+interface InstructionState {
     /**
      * Has an app ever connected to Reticle for this project, on this port?
      *
@@ -15,3 +15,4 @@ export interface InstructionState {
  * this block rather than repeated across sixteen parameter descriptions. See shared-params.ts.
  */
 export declare function buildServerInstructions(state: InstructionState): string;
+export {};

package/dist/memory/project-memory.d.ts

@@ -1,6 +1,4 @@
 import type { FileSystemPort } from '../project/fs-port.js';
-/** Named so a read from the tool surface is distinguishable from the CLI's and from replay's. */
-export declare const MCP_AGENT_ID = "reticle-mcp";
 /** Why a lookup returned nothing. Each one is a different thing for the agent to do next. */
 export declare const MemoryUnavailable: {
     /** No `.reticle/cloud.json` — this project has never been linked to a workspace. */
@@ -18,7 +16,7 @@ export interface KnownThing {
     sourceFile: string | null;
     subject: string;
 }
-export type ProjectMemoryResult = {
+type ProjectMemoryResult = {
     ok: true;
     subject: string | null;
     known: KnownThing[];
@@ -32,3 +30,4 @@ export declare function readProjectMemory(fs: FileSystemPort, root: string, home
     subject?: string | undefined;
     limit: number;
 }): Promise<ProjectMemoryResult>;
+export {};

package/dist/memory/project-memory.js

@@ -14,7 +14,7 @@
 import { cloudFetch } from '../cloud/cloud-sync.js';
 import { resolveProjectCloud } from '../cloud/cloud-config.js';
 /** Named so a read from the tool surface is distinguishable from the CLI's and from replay's. */
-export const MCP_AGENT_ID = 'reticle-mcp';
+const MCP_AGENT_ID = 'reticle-mcp';
 /** Why a lookup returned nothing. Each one is a different thing for the agent to do next. */
 export const MemoryUnavailable = {
     /** No `.reticle/cloud.json` — this project has never been linked to a workspace. */

package/dist/oracles/propose-consequences.js

@@ -1,5 +1,5 @@
 import { EventType, PredicateKind } from '@reticlehq/core';
-import { routePathOf } from '../events/predicate-route.js';
+import { routeOfEvent } from '../events/predicate-route.js';
 const TIER = { SIGNAL: 0, CONSEQUENCE: 1, PRESENCE: 2 };
 function pathname(url) {
     if (typeof url !== 'string')
@@ -67,16 +67,16 @@ export function proposeConsequences(events) {
                 break;
             }
             case EventType.ROUTE_CHANGE: {
-                const docPath = data['pathname'];
-                if ('string' === typeof docPath) {
+                const routed = routeOfEvent(data);
+                if (routed !== undefined) {
                     // `pathname`, not `to`: the evaluator has never accepted `to`, so this surface was handing
                     // the agent a predicate reticle_assert refuses with "unknown field to". A proposal that
                     // cannot be evaluated is worse than no proposal — see the schema check in the test.
                     //
                     // And the ROUTER's path, not the document's: under a hash router the document pathname is
                     // `/` on every page, so proposing it proposes an assertion that says nothing about where
-                    // the app went.
-                    const to = routePathOf(docPath, 'string' === typeof data['hash'] ? data['hash'] : '');
+                    // the app went. See routeOfEvent.
+                    const to = routed.routePath;
                     add(`route:${to}`, {
                         predicate: { kind: PredicateKind.ROUTE, pathname: to },
                         tier: TIER.CONSEQUENCE,

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

@@ -8,9 +8,9 @@
  * Kinds come from `@reticlehq/core`. A second enum here is how `reticle_domain` used to say
  * `missing-signal` while honesty said `no-signal-on-mutation` for the same absence.
  */
-import { InstrumentationGapKind } from '@reticlehq/core';
+import { InstrumentationGapKind } from '@reticlehq/core/artifacts';
 /** The three core kinds a located proposal can close. Other kinds are verdict-side, not insert-side. */
-export type LocatableGapKind = typeof InstrumentationGapKind.NO_SIGNAL_ON_MUTATION | typeof InstrumentationGapKind.NO_STORE_REGISTERED | typeof InstrumentationGapKind.MISSING_TESTID;
+type LocatableGapKind = typeof InstrumentationGapKind.NO_SIGNAL_ON_MUTATION | typeof InstrumentationGapKind.NO_STORE_REGISTERED | typeof InstrumentationGapKind.MISSING_TESTID;
 export interface LocatedGap {
     kind: LocatableGapKind;
     file: string;

package/dist/oracles/self-instrument.js

@@ -8,7 +8,7 @@
  * Kinds come from `@reticlehq/core`. A second enum here is how `reticle_domain` used to say
  * `missing-signal` while honesty said `no-signal-on-mutation` for the same absence.
  */
-import { InstrumentationGapKind } from '@reticlehq/core';
+import { InstrumentationGapKind } from '@reticlehq/core/artifacts';
 /** PascalCase a store name for a `useX.getState` hint (cart → Cart). */
 function pascal(name) {
     return 0 === name.length ? name : name[0]?.toUpperCase() + name.slice(1);

package/dist/platform.d.ts

@@ -8,9 +8,7 @@
  * simply never runs there.
  *
  * Node-side only, so deliberately NOT in `@reticlehq/core` — core is the wire contract, and a
- * platform name never crosses the wire.
+ * platform name never crosses the wire. It DEFINES in `@reticlehq/init` because the scaffolder needs
+ * it and may not import the daemon; re-exported here so every existing reader is unchanged.
  */
-export declare const NodePlatform: {
-    readonly WINDOWS: "win32";
-    readonly MACOS: "darwin";
-};
+export { NodePlatform } from '@reticlehq/init';

package/dist/platform.js

@@ -8,9 +8,7 @@
  * simply never runs there.
  *
  * Node-side only, so deliberately NOT in `@reticlehq/core` — core is the wire contract, and a
- * platform name never crosses the wire.
+ * platform name never crosses the wire. It DEFINES in `@reticlehq/init` because the scaffolder needs
+ * it and may not import the daemon; re-exported here so every existing reader is unchanged.
  */
-export const NodePlatform = {
-    WINDOWS: 'win32',
-    MACOS: 'darwin',
-};
+export { NodePlatform } from '@reticlehq/init';

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

@@ -9,6 +9,8 @@
  * The browser is injected via a `Launcher` so all lifecycle logic is testable without real Chromium;
  * the thin Playwright adapter that satisfies these interfaces lives separately.
  */
+/** The minimal page surface the pool drives. Real Playwright `Page` satisfies this. */
+import { type SeedStorage } from '@reticlehq/core';
 export interface PooledPage {
     goto(url: string, opts?: {
         timeoutMs?: number;
@@ -37,11 +39,75 @@ export interface PooledPage {
      * reports dispatched/settled while the styles never ran.
      */
     hover?(x: number, y: number): Promise<void>;
+    /** Add an init script to run after document creation but before any page scripts run. */
+    addInitScript?<Arg>(script: ((arg: Arg) => void) | string, arg?: Arg): Promise<InitScriptHandle | void>;
+    /**
+     * Install (or clear) network mocks on this page. OPTIONAL: a fake that does not implement it
+     * makes `reticle_network_mock` refuse rather than claiming it stubbed a request it cannot intercept.
+     */
+    installMocks?(rules: readonly PooledMockRule[]): Promise<void>;
+    /**
+     * Resize this page's viewport. OPTIONAL, like `installMocks`: a fake that does not implement it
+     * makes `reticle_viewport` refuse rather than claim a resize the page never took.
+     *
+     * A lease IS a real browser page, so the resize was always possible — the tool simply had no route
+     * to it and consulted only the driven-provider path. On an SDK-only install there is no such
+     * provider, so mobile-only UI (a `lg:hidden` hamburger, a drawer that only mounts under a
+     * breakpoint) could not be driven at all without installing Playwright separately.
+     */
+    setViewport?(size: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+    /**
+     * Fires when the page opens a native `window.confirm`/`alert`/`prompt`. OPTIONAL, like `onConsole`:
+     * a fake that does not implement it means the pool cannot see or arbitrate the dialog, and the
+     * page is left to whatever the underlying engine does with no listener attached.
+     *
+     * The pool always dismisses on this handler (see `acquire`) — a page blocked on a native dialog
+     * previously wedged the whole session (every subsequent tool call timed out and no recovery
+     * existed short of restarting the daemon), because nothing in the stack ever answered it.
+     */
+    onDialog?(handler: (dialog: PooledDialog) => void): void;
+}
+/** A native dialog the page opened, handed to the pool so it can be dismissed instead of left blocking. */
+export interface PooledDialog {
+    /** The dialog's message text — kept for diagnostics (`BrowserPool#lastDialogMessage`). */
+    readonly message: string;
+    dismiss(): Promise<void>;
+}
+export interface InitScriptHandle {
+    dispose(): Promise<void>;
+}
+export interface PooledCookie {
+    name: string;
+    value: string;
+    url?: string;
+    domain?: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/**
+ * One interception rule the pool can install. Same fields as the drive-path mock rule, kept here so
+ * the pool does not import Playwright.
+ */
+export interface PooledMockRule {
+    urlContains: string;
+    method?: string;
+    status?: number;
+    body?: string;
+    contentType?: string;
+    delayMs?: number;
+    abort?: boolean;
 }
 /** An isolated browsing context (cookies/storage). Real Playwright `BrowserContext` satisfies this. */
 export interface PooledContext {
     newPage(): Promise<PooledPage>;
     close(): Promise<void>;
+    addCookies?(cookies: PooledCookie[]): Promise<void>;
 }
 /** The launched browser. Real Playwright `Browser` satisfies this. */
 export interface PooledBrowser {
@@ -57,6 +123,7 @@ export type Launcher = () => Promise<PooledBrowser>;
 export interface Lease {
     readonly sessionId: string;
     readonly url: string;
+    readonly navStatus?: number;
     release(): Promise<void>;
 }
 /** Default lease time-to-live: a lease untouched for this long is presumed orphaned and reclaimed. */
@@ -147,6 +214,25 @@ export declare class BrowserPool {
      * Touches the lease like any other tool call, so hovering keeps it alive.
      */
     hoverLease(sessionId: string, x: number, y: number): Promise<boolean>;
+    /**
+     * Install network mocks on a leased page, or false when this session is not a lease or cannot
+     * intercept. Same optional-capability contract as screenshotLease: absence must read as "could not
+     * mock", never as a stub that applied to nothing.
+     *
+     * Touches the lease like any other tool call, so mocking keeps it alive.
+     */
+    /**
+     * Resize a leased page's viewport, or report that this page cannot be resized.
+     *
+     * Alias-resolved like every other agent-facing capability — see `#leaseIdOf`.
+     *
+     * Touches the lease like any other tool call, so resizing keeps it alive.
+     */
+    setViewportLease(sessionId: string, size: {
+        width: number;
+        height: number;
+    }): Promise<boolean>;
+    setMocksLease(sessionId: string, rules: readonly PooledMockRule[]): Promise<boolean>;
     sweepExpired(): Promise<string[]>;
     /**
      * How many leases this pool has reclaimed for going stale.
@@ -177,6 +263,7 @@ export declare class BrowserPool {
     acquire(url: string, opts?: {
         signal?: AbortSignal;
         sessionId?: string;
+        seedStorage?: SeedStorage;
     }): Promise<Lease>;
     /**
      * The websocket address this lease's page reported it could not reach, if it reported one.
@@ -184,6 +271,11 @@ export declare class BrowserPool {
      * Undefined means the page said nothing — never that it dialled the right place.
      */
     dialFailureUrl(sessionId: string): string | undefined;
+    /**
+     * The message of the most recent native dialog (`confirm`/`alert`/`prompt`) auto-dismissed on this
+     * lease, if any. Diagnostic only — the dialog itself is already gone by the time this is readable.
+     */
+    lastDialogMessage(sessionId: string): string | undefined;
     /** Close every context and the browser. Pending waiters are rejected (the pool is terminal now). */
     shutdown(): Promise<void>;
 }