@reticlehq/server 2.2.1 → 2.3.0

package/dist/init/snippets.js

@@ -86,6 +86,11 @@ export function htmlManual(port, projectId) {
 }
 export const NEXT_RETICLE_DEV_PATH = 'app/reticle-dev.tsx';
 export const SVELTEKIT_HOOKS_PATH = 'src/hooks.client.ts';
+/**
+ * Said to the user's face rather than discovered later. React, Next, Remix and Astro each have an
+ * app and a CI gate; SvelteKit has neither, so "it generated some wiring" is not evidence it works.
+ */
+export const UNVERIFIED_FRAMEWORK_NOTE = 'Reticle has no SvelteKit app and no CI gate for one, so this wiring is untested — it may work, but nothing proves it and nothing will tell us if it breaks. Supported and gated today: Vite + React, Next.js, Remix, Astro, and plain HTML. If the hook does not register a session, please open an issue.';
 /**
  * Dev-only client hook that connects Reticle in a SvelteKit app. SvelteKit renders through app.html and
  * never triggers Vite's index.html injection (verified), so the standard plugin can't auto-connect —
@@ -114,4 +119,3 @@ export function reticleConfigContent(framework, port, projectId) {
         fields['port'] = port;
     return `${JSON.stringify(fields, null, 2)}\n`;
 }
-//# sourceMappingURL=snippets.js.map

package/dist/init/vite-config.d.ts

@@ -22,4 +22,3 @@ type VitePatch = {
 };
 export declare function patchViteConfig(source: string, port?: number): VitePatch;
 export {};
-//# sourceMappingURL=vite-config.d.ts.map

package/dist/init/vite-config.js

@@ -42,4 +42,3 @@ export function patchViteConfig(source, port) {
     }
     return { kind: VitePatchKind.APPLY, code: insertImport(insertPlugin(source, port)) };
 }
-//# sourceMappingURL=vite-config.js.map

package/dist/input/network-detail.d.ts

@@ -71,4 +71,3 @@ export interface PageLike {
  * over Playwright's event surface — the daemon routes `emit` to the driven session's pushEvent.
  */
 export declare function attachNetworkDetail(page: PageLike, emit: (detail: NetworkDetail) => void): void;
-//# sourceMappingURL=network-detail.d.ts.map

package/dist/input/network-detail.js

@@ -157,4 +157,3 @@ export function attachNetworkDetail(page, emit) {
         void detailPromise.catch(() => undefined);
     });
 }
-//# sourceMappingURL=network-detail.js.map

package/dist/input/network-mock-tools.d.ts

@@ -1,3 +1,2 @@
 import type { ToolDef } from '../tools/tools.js';
 export declare const NETWORK_MOCK_TOOLS: ToolDef[];
-//# sourceMappingURL=network-mock-tools.d.ts.map

package/dist/input/network-mock-tools.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason } from '@reticlehq/core';
+import { CDP_NO_PROVIDER_REASON, CDP_NO_PROVIDER_RECOMMENDATION } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
 import { asString } from '../tools/tools-helpers.js';
@@ -75,8 +75,8 @@ export const NETWORK_MOCK_TOOLS = [
                     applied: false,
                     count: 0,
                     ok: false,
-                    reason: VisualReason.NO_PROVIDER,
-                    recommendation: VISUAL_NO_PROVIDER_RECOMMENDATION,
+                    reason: CDP_NO_PROVIDER_REASON,
+                    recommendation: CDP_NO_PROVIDER_RECOMMENDATION,
                 };
             }
             const session = deps.sessions.resolve(asString(args['sessionId']));
@@ -86,4 +86,3 @@ export const NETWORK_MOCK_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=network-mock-tools.js.map

package/dist/input/network-mock.d.ts

@@ -52,4 +52,3 @@ export declare function applyOutcome(route: Route, outcome: MockOutcome, sleep:
  */
 export declare function installNetworkMocks(page: Page, rules: MockRule[], sleep?: (ms: number) => Promise<void>): Promise<void>;
 export {};
-//# sourceMappingURL=network-mock.d.ts.map

package/dist/input/network-mock.js

@@ -59,4 +59,3 @@ export async function installNetworkMocks(page, rules, sleep = realSleep) {
         void applyOutcome(route, outcome, sleep);
     });
 }
-//# sourceMappingURL=network-mock.js.map

package/dist/input/real-input.d.ts

@@ -183,6 +183,20 @@ export declare class LaunchedRealInputProvider implements OwnedRealInputProvider
     perform(_sessionUrl: string, action: ActionType, box: ElementBox, args: RealInputArgs): Promise<RealInputResult>;
     /** PNG of the owned page, or undefined before navigate / after dispose. */
     screenshot(_sessionUrl: string, opts: ScreenshotOpts): Promise<Uint8Array | undefined>;
+    /**
+     * Pin the owned page's viewport; false before navigate / after dispose.
+     *
+     * `CdpRealInputProvider` has had this since it shipped and THIS provider did not, so
+     * `reticle_viewport` refused with `no-cdp-provider` under `reticle drive` — while recommending
+     * `reticle drive` as the fix. Same for `setMocks` below. A driven browser was attached and taking
+     * screenshots the whole time; only these two methods were missing.
+     */
+    setViewport(_sessionUrl: string, size: {
+        width: number;
+        height: number;
+    }): Promise<boolean>;
+    /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
+    setMocks(_sessionUrl: string, rules: MockRule[]): Promise<boolean>;
     /** Close the owned browser once. Idempotent and safe before navigate. */
     dispose(): Promise<void>;
 }
@@ -204,4 +218,3 @@ export declare function selectPage<T extends {
     url(): string;
 }>(pages: readonly T[], sessionUrl: string): T | undefined;
 export {};
-//# sourceMappingURL=real-input.d.ts.map

package/dist/input/real-input.js

@@ -1,3 +1,6 @@
+import { BrowserLaunchKind } from '@reticlehq/core';
+import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { classifyConnectFailure } from '../telemetry/connect-failure.js';
 import { ActionType, DriveErrorCode, DRIVE_PLAYWRIGHT_MISSING_MSG } from '@reticlehq/core';
 import { installNetworkMocks } from './network-mock.js';
 import { attachNetworkDetail } from './network-detail.js';
@@ -100,7 +103,20 @@ const nodeSleep = (ms) => new Promise((resolve) => {
 });
 const cdpConnect = async (url) => {
     const { chromium } = await import('playwright');
-    return chromium.connectOverCDP(url);
+    // Attaching to someone's already-running browser is the fragile path — a stale CDP url, a browser
+    // that was closed — so its FAILURE rate is the number worth watching. Settled with the outcome
+    // rather than counted up front, which is what the first version got wrong: it incremented before
+    // the await, so it silently reported attempts while the other paths reported successes.
+    const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.ATTACHED);
+    try {
+        const browser = await chromium.connectOverCDP(url);
+        settle();
+        return browser;
+    }
+    catch (error) {
+        settle(classifyConnectFailure(error));
+        throw error;
+    }
 };
 /** CDP-backed real-input provider. Lazily connects on first availability check / perform. */
 export class CdpRealInputProvider {
@@ -211,10 +227,14 @@ const launchedChromium = async (headless) => {
     catch {
         throw new DriveError(DriveErrorCode.PLAYWRIGHT_MISSING, DRIVE_PLAYWRIGHT_MISSING_MSG);
     }
+    const settle = getSessionMetrics().recordConnectAttempt(BrowserLaunchKind.LAUNCHED);
     try {
-        return await mod.chromium.launch({ headless });
+        const browser = await mod.chromium.launch({ headless });
+        settle();
+        return browser;
     }
     catch (e) {
+        settle(classifyConnectFailure(e));
         throw new DriveError(DriveErrorCode.LAUNCH_FAILED, e instanceof Error ? e.message : String(e));
     }
 };
@@ -297,6 +317,29 @@ export class LaunchedRealInputProvider {
             return Promise.resolve(undefined);
         return capturePage(page, opts);
     }
+    /**
+     * Pin the owned page's viewport; false before navigate / after dispose.
+     *
+     * `CdpRealInputProvider` has had this since it shipped and THIS provider did not, so
+     * `reticle_viewport` refused with `no-cdp-provider` under `reticle drive` — while recommending
+     * `reticle drive` as the fix. Same for `setMocks` below. A driven browser was attached and taking
+     * screenshots the whole time; only these two methods were missing.
+     */
+    async setViewport(_sessionUrl, size) {
+        const page = this.#page;
+        if (page === undefined)
+            return false;
+        await page.setViewportSize({ width: size.width, height: size.height });
+        return true;
+    }
+    /** Apply network-mock rules to the owned page; false before navigate / after dispose. */
+    async setMocks(_sessionUrl, rules) {
+        const page = this.#page;
+        if (page === undefined)
+            return false;
+        await installNetworkMocks(page, rules);
+        return true;
+    }
     /** Close the owned browser once. Idempotent and safe before navigate. */
     async dispose() {
         const browser = this.#browser;
@@ -334,4 +377,3 @@ function stripVolatile(url) {
     const query = base.indexOf('?');
     return query >= 0 ? base.slice(0, query) : base;
 }
-//# sourceMappingURL=real-input.js.map

package/dist/input/scroll-find.d.ts

@@ -38,4 +38,3 @@ export interface ScrollFindResult {
 export declare function scrollToFind(session: ScrollFindSession, q: ScrollFindQuery, opts?: {
     maxScrolls?: number;
 }): Promise<ScrollFindResult>;
-//# sourceMappingURL=scroll-find.d.ts.map

package/dist/input/scroll-find.js

@@ -56,4 +56,3 @@ export async function scrollToFind(session, q, opts = {}) {
     }
     return { found: false, scrolls, exhausted: false }; // spent the budget; more may lie further down
 }
-//# sourceMappingURL=scroll-find.js.map

package/dist/input/scroll-tools.d.ts

@@ -5,4 +5,3 @@ import type { ToolDef } from '../tools/tools.js';
  * nothing. This scrolls the container until the row mounts, then returns its ref.
  */
 export declare const SCROLL_TOOLS: ToolDef[];
-//# sourceMappingURL=scroll-tools.d.ts.map

package/dist/input/scroll-tools.js

@@ -65,4 +65,3 @@ export const SCROLL_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=scroll-tools.js.map

package/dist/input/viewport-tools.d.ts

@@ -1,3 +1,2 @@
 import type { ToolDef } from '../tools/tools.js';
 export declare const VIEWPORT_TOOLS: ToolDef[];
-//# sourceMappingURL=viewport-tools.d.ts.map

package/dist/input/viewport-tools.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { VISUAL_NO_PROVIDER_RECOMMENDATION, VisualReason } from '@reticlehq/core';
+import { CDP_NO_PROVIDER_REASON, CDP_NO_PROVIDER_RECOMMENDATION } from '@reticlehq/core';
 import { ReticleTool } from '../tools/tool-names.js';
 import { sessionIdShape } from '../tools/tool-kit.js';
 import { asString } from '../tools/tools-helpers.js';
@@ -40,8 +40,8 @@ export const VIEWPORT_TOOLS = [
                     width: 0,
                     height: 0,
                     ok: false,
-                    reason: VisualReason.NO_PROVIDER,
-                    recommendation: VISUAL_NO_PROVIDER_RECOMMENDATION,
+                    reason: CDP_NO_PROVIDER_REASON,
+                    recommendation: CDP_NO_PROVIDER_RECOMMENDATION,
                 };
             }
             const width = clampDim(args['width']);
@@ -57,4 +57,3 @@ function clampDim(value) {
     const n = typeof value === 'number' && Number.isFinite(value) ? Math.round(value) : MIN_DIM;
     return Math.max(MIN_DIM, Math.min(n, MAX_DIM));
 }
-//# sourceMappingURL=viewport-tools.js.map

package/dist/journal/ambient-store.d.ts

@@ -13,4 +13,3 @@ export declare class AmbientStore {
     load(): Promise<AmbientCounts>;
     save(counts: AmbientCounts): Promise<void>;
 }
-//# sourceMappingURL=ambient-store.d.ts.map

package/dist/journal/ambient-store.js

@@ -43,4 +43,3 @@ export class AmbientStore {
         await this.#fs.rename(tmp, this.#path);
     }
 }
-//# sourceMappingURL=ambient-store.js.map

package/dist/journal/ambient.d.ts

@@ -45,4 +45,3 @@ export declare function isAmbient(counts: AmbientCounts, ref: string | undefined
  * it is signal, not background churn.
  */
 export declare function excludeAmbient(counts: AmbientCounts, events: readonly ReticleEvent[], threshold?: number): ReticleEvent[];
-//# sourceMappingURL=ambient.d.ts.map

package/dist/journal/ambient.js

@@ -45,4 +45,3 @@ export function isAmbient(counts, ref, threshold = DEFAULT_AMBIENT_THRESHOLD) {
 export function excludeAmbient(counts, events, threshold) {
     return events.filter((event) => event.actionId !== undefined || !isAmbient(counts, event.ref, threshold));
 }
-//# sourceMappingURL=ambient.js.map

package/dist/journal/attach-journal.d.ts

@@ -19,4 +19,3 @@ export interface JournalAttachDeps {
  * journaling concern). The recorder's clock is the session's own elapsed time.
  */
 export declare function makeJournalAttach(deps: JournalAttachDeps): (session: JournalTarget) => void;
-//# sourceMappingURL=attach-journal.d.ts.map

package/dist/journal/attach-journal.js

@@ -17,4 +17,3 @@ export function makeJournalAttach(deps) {
         session.setJournal(new JournalRecorder(journal, { now: () => session.elapsed() }), journal);
     };
 }
-//# sourceMappingURL=attach-journal.js.map

package/dist/journal/deviation-report.d.ts

@@ -25,4 +25,3 @@ export interface DeviationReport {
  * envelope is too green, are counted as unjudged rather than silently passed.
  */
 export declare function buildDeviationReport(envelopes: ReadonlyMap<string, RouteEnvelope>, segments: readonly SegmentRollup[], zThreshold?: number): DeviationReport;
-//# sourceMappingURL=deviation-report.d.ts.map

package/dist/journal/deviation-report.js

@@ -51,4 +51,3 @@ export function buildDeviationReport(envelopes, segments, zThreshold) {
     };
     return { ...base, headline: headlineFor(base) };
 }
-//# sourceMappingURL=deviation-report.js.map

package/dist/journal/deviation-service.d.ts

@@ -9,4 +9,3 @@ import type { SegmentRollup } from './rollups.js';
  * caller shows the causal summary instead.
  */
 export declare function reportAndAccumulate(store: EnvelopeStore, segments: readonly SegmentRollup[], zThreshold?: number): Promise<DeviationReport>;
-//# sourceMappingURL=deviation-service.d.ts.map

package/dist/journal/deviation-service.js

@@ -29,4 +29,3 @@ export async function reportAndAccumulate(store, segments, zThreshold) {
         return report;
     });
 }
-//# sourceMappingURL=deviation-service.js.map

package/dist/journal/envelope-store.d.ts

@@ -16,4 +16,3 @@ export declare class EnvelopeStore {
     load(): Promise<Map<string, RouteEnvelope>>;
     save(envelopes: ReadonlyMap<string, RouteEnvelope>): Promise<void>;
 }
-//# sourceMappingURL=envelope-store.d.ts.map

package/dist/journal/envelope-store.js

@@ -59,4 +59,3 @@ export class EnvelopeStore {
         await this.#fs.rename(tmp, this.#path);
     }
 }
-//# sourceMappingURL=envelope-store.js.map

package/dist/journal/envelope.d.ts

@@ -103,13 +103,13 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: number;
         }>;
     }, "strip", z.ZodTypeAny, {
-        net: {
+        durationMs: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        durationMs: {
+        net: {
             count: number;
             mean: number;
             m2: number;
@@ -128,13 +128,13 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
             max: number;
         };
     }, {
-        net: {
+        durationMs: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        durationMs: {
+        net: {
             count: number;
             mean: number;
             m2: number;
@@ -157,13 +157,13 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
     route: string;
     samples: number;
     stats: {
-        net: {
+        durationMs: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        durationMs: {
+        net: {
             count: number;
             mean: number;
             m2: number;
@@ -186,13 +186,13 @@ export declare const RouteEnvelopeSchema: z.ZodObject<{
     route: string;
     samples: number;
     stats: {
-        net: {
+        durationMs: {
             count: number;
             mean: number;
             m2: number;
             max: number;
         };
-        durationMs: {
+        net: {
             count: number;
             mean: number;
             m2: number;
@@ -229,4 +229,3 @@ export interface Deviation {
  * falls back to the causal summary in that case.
  */
 export declare function compareSegment(envelope: RouteEnvelope, segment: SegmentRollup, zThreshold?: number): Deviation[];
-//# sourceMappingURL=envelope.d.ts.map

package/dist/journal/envelope.js

@@ -91,4 +91,3 @@ export function compareSegment(envelope, segment, zThreshold = DEFAULT_Z_THRESHO
     }
     return deviations.sort((a, b) => b.z - a.z);
 }
-//# sourceMappingURL=envelope.js.map

package/dist/journal/journal-query.d.ts

@@ -17,4 +17,3 @@ export interface EventQueryOptions {
 export declare function mergeEventsBySeq(journal: readonly ReticleEvent[], buffer: readonly ReticleEvent[]): ReticleEvent[];
 /** Apply since/until/actionId bounds to an event list. */
 export declare function filterEvents(events: readonly ReticleEvent[], options: EventQueryOptions): ReticleEvent[];
-//# sourceMappingURL=journal-query.d.ts.map

package/dist/journal/journal-query.js

@@ -25,4 +25,3 @@ export function filterEvents(events, options) {
         (options.until === undefined || event.t <= options.until) &&
         (options.actionId === undefined || event.actionId === options.actionId));
 }
-//# sourceMappingURL=journal-query.js.map

package/dist/journal/journal-recorder.d.ts

@@ -35,4 +35,3 @@ export declare class JournalRecorder {
     /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
     flush(): Promise<void>;
 }
-//# sourceMappingURL=journal-recorder.d.ts.map

package/dist/journal/journal-recorder.js

@@ -78,4 +78,3 @@ export class JournalRecorder {
         this.#chain = this.#chain.then(() => this.#sink.appendEvents(batch)).catch(() => undefined);
     }
 }
-//# sourceMappingURL=journal-recorder.js.map

package/dist/journal/retention.d.ts

@@ -18,4 +18,3 @@ export declare function selectPrunable(dirs: readonly DatedDir[], retention: num
  */
 export declare function pruneSessions(fs: FileSystemPort, root: string, retention?: number): Promise<void>;
 export {};
-//# sourceMappingURL=retention.d.ts.map

package/dist/journal/retention.js

@@ -47,4 +47,3 @@ export async function pruneSessions(fs, root, retention = DEFAULT_SESSION_RETENT
         }
     }
 }
-//# sourceMappingURL=retention.js.map

package/dist/journal/rollups.d.ts

@@ -46,4 +46,3 @@ export interface SegmentRollup {
  * the events carry their own `t`. The events must be in journal order (seq/t ascending).
  */
 export declare function computeSegments(events: readonly ReticleEvent[]): SegmentRollup[];
-//# sourceMappingURL=rollups.d.ts.map

package/dist/journal/rollups.js

@@ -80,4 +80,3 @@ export function computeSegments(events) {
         segments.push(finalize(acc));
     return segments;
 }
-//# sourceMappingURL=rollups.js.map

package/dist/journal/session-end.d.ts

@@ -29,4 +29,3 @@ export interface SessionEndDeps {
  * starts already knowing which regions churn.
  */
 export declare function makeSessionEnd(deps: SessionEndDeps): (session: SessionEndTarget) => Promise<void>;
-//# sourceMappingURL=session-end.d.ts.map

package/dist/journal/session-end.js

@@ -49,4 +49,3 @@ export function makeSessionEnd(deps) {
         }
     };
 }
-//# sourceMappingURL=session-end.js.map

package/dist/journal/session-journal.d.ts

@@ -22,4 +22,3 @@ export declare class SessionJournal {
     readEvents(): Promise<ReticleEvent[]>;
     readActions(): Promise<JournalAction[]>;
 }
-//# sourceMappingURL=session-journal.d.ts.map

package/dist/journal/session-journal.js

@@ -165,4 +165,3 @@ export class SessionJournal {
         return out;
     }
 }
-//# sourceMappingURL=session-journal.js.map

package/dist/license/license.d.ts

@@ -110,4 +110,3 @@ export declare function describeLicense(now: number, env?: NodeJS.ProcessEnv, ba
  */
 export declare function assertEnterpriseFromEnv(feature: string, now: number, env?: NodeJS.ProcessEnv, baked?: string): void;
 export {};
-//# sourceMappingURL=license.d.ts.map

package/dist/license/license.js

@@ -223,4 +223,3 @@ export function assertEnterpriseFromEnv(feature, now, env = process.env, baked =
         publicKey,
     });
 }
-//# sourceMappingURL=license.js.map

package/dist/log.d.ts

@@ -3,4 +3,3 @@
  * write logs there.
  */
 export declare function log(event: string, fields?: Record<string, unknown>): void;
-//# sourceMappingURL=log.d.ts.map

package/dist/log.js

@@ -6,4 +6,3 @@ export function log(event, fields = {}) {
     const line = JSON.stringify({ event, ...fields });
     process.stderr.write(`${line}\n`);
 }
-//# sourceMappingURL=log.js.map

package/dist/mcp-proxy.d.ts

@@ -33,4 +33,3 @@ export declare function buildSessionUrl(rawData: string, port: number): string;
  * Claude Code restarts the proxy fresh).
  */
 export declare function startMcpProxy(port: number): Promise<never>;
-//# sourceMappingURL=mcp-proxy.d.ts.map

package/dist/mcp-proxy.js

@@ -188,4 +188,3 @@ export function startMcpProxy(port) {
         process.stdin.on('end', () => 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