@reticlehq/server 2.2.0 → 2.3.0

package/dist/telemetry/connect-failure.js

@@ -0,0 +1,44 @@
+/**
+ * Classifying WHY a browser connection failed, into causes that each have a different fix.
+ *
+ * A raw error message cannot be sent — it carries CDP URLs, executable paths, and home directories —
+ * and would be useless if it could, because the same cause arrives worded five different ways from
+ * Playwright, Node and the OS. What we need is the small set of THINGS THAT ACTUALLY GO WRONG:
+ * a missing browser binary is a docs problem, a refused CDP endpoint is a configuration problem, a
+ * pool timeout is a capacity problem. Three very different responses from us.
+ *
+ * `OTHER` is the bucket to watch. A large `OTHER` count means the classifier has a blind spot and
+ * this list needs another entry — which is a signal in itself, and the reason it is never merged
+ * into one of the known causes.
+ */
+import { ConnectFailure } from '@reticlehq/core';
+/** Ordered most-specific first; the first match wins. Patterns track messages we have actually seen. */
+const RULES = [
+    // Playwright's own wording when the browser was never downloaded.
+    {
+        match: /executable doesn.?t exist|playwright install|browsertype\.launch/i,
+        cause: ConnectFailure.CHROMIUM_MISSING,
+    },
+    {
+        match: /cannot find module ['"]?playwright|playwright is not installed/i,
+        cause: ConnectFailure.PLAYWRIGHT_MISSING,
+    },
+    {
+        match: /econnrefused|connect over cdp|websocket error|failed to connect|enotfound|etimedout/i,
+        cause: ConnectFailure.CDP_UNREACHABLE,
+    },
+    {
+        match: /target (?:page|closed)|browser has been closed|browser has disconnected|crashed/i,
+        cause: ConnectFailure.BROWSER_CRASHED,
+    },
+    { match: /pool|lease.*timed out|timed out waiting/i, cause: ConnectFailure.POOL_TIMEOUT },
+];
+/** The cause behind a connection error, or `OTHER` when we do not recognize it. */
+export function classifyConnectFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    for (const rule of RULES) {
+        if (rule.match.test(message))
+            return rule.cause;
+    }
+    return ConnectFailure.OTHER;
+}

package/dist/telemetry/daemon-telemetry.d.ts

@@ -0,0 +1,19 @@
+/** Stops the timers this installed. Called from the daemon's shutdown path. */
+export interface DaemonTelemetry {
+    /**
+     * Emit the final, rich session summary and stop flushing. Safe to call more than once.
+     *
+     * AWAITABLE, and the daemon must await it. Every other send in the product is fire-and-forget
+     * because losing one counter never matters — but this one carries the whole session, and the
+     * process calls `process.exit(0)` immediately afterwards, which kills an in-flight POST. Verified
+     * against a local capture server: fire-and-forget lost the event every single time. A send that
+     * fails or hangs still cannot block the exit, because `emit` swallows its own errors and is bounded
+     * by its own request timeout.
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Report the daemon as started, profile the project once, and keep the session counters flushing.
+ * Every timer is `unref`'d so telemetry can never be the reason a daemon refuses to exit.
+ */
+export declare function installDaemonTelemetry(cwd: string, now?: () => number): DaemonTelemetry;

package/dist/telemetry/daemon-telemetry.js

@@ -0,0 +1,76 @@
+/**
+ * The daemon's telemetry lifecycle, in one place: start, the periodic flush that survives a kill, the
+ * one-shot project profile, and the rich summary on shutdown.
+ *
+ * Extracted from `cli.ts` because it is a cohesive unit with its own timers and its own failure rule
+ * (nothing here may ever be able to fail a daemon start), and because `cli.ts` is a dispatcher — the
+ * more of this that lives there, the harder it is to see what a command actually does.
+ */
+import { TelemetryEventKind } from '@reticlehq/core';
+import { getTelemetry } from './telemetry.js';
+import { getSessionMetrics } from './session-metrics.js';
+import { profileProject } from './project-profile.js';
+import { startUpdateCheck } from '../update/update-nudge.js';
+import { markDaemonStart } from './mcp-connection.js';
+/** Let the daemon finish coming up before walking the source tree for a profile. */
+const PROJECT_PROFILE_DELAY_MS = 5_000;
+/**
+ * How often a long-lived daemon flushes its counters.
+ *
+ * ponytail: coarse on purpose. A daemon that is SIGKILLed — OOM, a closed laptop, `kill -9` — never
+ * reaches its shutdown handler, so without this the whole session's counters die with it. Thirty
+ * minutes bounds that loss to one window while keeping the event volume near zero for the common case
+ * (most daemons stop cleanly and send exactly one summary). If the lost windows ever show up as a
+ * real gap, the upgrade is a small on-disk journal replayed at the next start, not a shorter timer.
+ */
+const SESSION_FLUSH_MS = 30 * 60 * 1000;
+/**
+ * Report the daemon as started, profile the project once, and keep the session counters flushing.
+ * Every timer is `unref`'d so telemetry can never be the reason a daemon refuses to exit.
+ */
+export function installDaemonTelemetry(cwd, now = () => Date.now()) {
+    const metrics = getSessionMetrics(now);
+    void getTelemetry().emit(TelemetryEventKind.DAEMON_STARTED);
+    // Ask npm whether a newer Reticle exists, so the agent can tell the human. Nothing checked before
+    // this, so a published fix was invisible until someone manually ran `reticle update`.
+    startUpdateCheck(now);
+    markDaemonStart(now());
+    // One profile per daemon start: what kind of project this is and how deeply Reticle is used in it.
+    // Deferred off the boot path — it walks the source tree, and nothing about a daemon coming up
+    // should wait on a filesystem scan.
+    setTimeout(() => {
+        try {
+            void getTelemetry().emit(TelemetryEventKind.PROJECT_PROFILED, {
+                project: profileProject(cwd, now()),
+            });
+        }
+        catch {
+            /* a profile is a nice-to-have; it must never touch the daemon */
+        }
+    }, PROJECT_PROFILE_DELAY_MS).unref();
+    const flush = setInterval(() => {
+        if (metrics.empty)
+            return; // an idle window is not worth an event
+        void getTelemetry().emit(TelemetryEventKind.DAEMON_STOPPED, {
+            session: metrics.summarize(false),
+        });
+        metrics.reset();
+    }, SESSION_FLUSH_MS);
+    flush.unref();
+    let stopped;
+    return {
+        shutdown() {
+            // Both SIGTERM and the idle-shutdown path can call this; the second caller awaits the first
+            // send rather than emitting a duplicate summary.
+            stopped ??= (async () => {
+                clearInterval(flush);
+                // The rich one: the whole session in a single event — duration, the tool histogram, error
+                // shapes, verifications, browser launches. This is what replaced the per-tool-call event.
+                await getTelemetry().emit(TelemetryEventKind.DAEMON_STOPPED, {
+                    session: metrics.summarize(true),
+                });
+            })();
+            return stopped;
+        },
+    };
+}

package/dist/telemetry/dev-repo.d.ts

@@ -0,0 +1,10 @@
+/** Walk up from `cwd` to the filesystem root, looking for a package.json that names this monorepo. */
+export declare function isReticleSourceCheckout(cwd: string): boolean;
+/**
+ * Load `<dir>/.env` into `env`. Best-effort and deliberately minimal — no expansion, no multiline.
+ *
+ * A variable already present in the environment ALWAYS wins. A .env that overrode an explicit
+ * `RETICLE_PORT` from the caller's shell would bind the daemon somewhere the caller never asked for,
+ * which is a worse surprise than the convenience is worth.
+ */
+export declare function loadDotEnv(dir: string, env?: NodeJS.ProcessEnv): void;

package/dist/telemetry/dev-repo.js

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, parse } from 'node:path';
+/**
+ * Two guards that keep Reticle's own development off its telemetry.
+ *
+ * `.env` is the convenient one and is useful to every user: put `RETICLE_TELEMETRY=0` in a project's
+ * `.env` and the daemon honours it. But `.env` is gitignored, so it exists only on the machine that
+ * created it — a fresh clone of this repo would phone home on the first `reticle serve` a
+ * contributor runs. `isReticleSourceCheckout` closes that: the marker is the committed root
+ * package.json, so the guarantee travels with the repository instead of with one developer's
+ * untracked file.
+ */
+/** The monorepo's root package name — the one committed marker that says "this IS Reticle". */
+const MONOREPO_NAME = 'reticle-monorepo';
+/** Walk up from `cwd` to the filesystem root, looking for a package.json that names this monorepo. */
+export function isReticleSourceCheckout(cwd) {
+    let dir = cwd;
+    const { root } = parse(cwd);
+    for (;;) {
+        const pkg = join(dir, 'package.json');
+        if (existsSync(pkg)) {
+            try {
+                const parsed = JSON.parse(readFileSync(pkg, 'utf8'));
+                const name = typeof parsed === 'object' && parsed !== null
+                    ? parsed.name
+                    : undefined;
+                if (name === MONOREPO_NAME)
+                    return true;
+            }
+            catch {
+                /* an unreadable/!JSON package.json simply is not the marker */
+            }
+        }
+        if (dir === root)
+            return false;
+        const next = dirname(dir);
+        if (next === dir)
+            return false;
+        dir = next;
+    }
+}
+/** Strip one layer of matching quotes from a .env value. */
+function unquote(value) {
+    const first = value[0];
+    if ((first === '"' || first === "'") && value.endsWith(first) && value.length >= 2) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/**
+ * Load `<dir>/.env` into `env`. Best-effort and deliberately minimal — no expansion, no multiline.
+ *
+ * A variable already present in the environment ALWAYS wins. A .env that overrode an explicit
+ * `RETICLE_PORT` from the caller's shell would bind the daemon somewhere the caller never asked for,
+ * which is a worse surprise than the convenience is worth.
+ */
+export function loadDotEnv(dir, env = process.env) {
+    const file = join(dir, '.env');
+    let text;
+    try {
+        if (!existsSync(file))
+            return;
+        text = readFileSync(file, 'utf8');
+    }
+    catch {
+        return;
+    }
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line.length === 0 || line.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq <= 0)
+            continue; // not a KEY=value pair — skip rather than fail the whole file
+        const key = line.slice(0, eq).trim();
+        if (key.length === 0 || env[key] !== undefined)
+            continue;
+        env[key] = unquote(line.slice(eq + 1).trim());
+    }
+}

package/dist/telemetry/error-fingerprint.d.ts

@@ -0,0 +1,24 @@
+/** The skeleton of a message: variable parts blanked, whitespace collapsed, length bounded. */
+export declare function errorSkeleton(message: string): string;
+/** A stable, opaque group key for an error message. Same defect ⇒ same key, on every machine. */
+export declare function fingerprintError(message: string): string;
+/**
+ * Frames from a stack trace that belong to RETICLE, reduced to `basename:line`.
+ *
+ * A crash stack is mostly the user's own application and node internals; neither is ours to collect,
+ * and the user's frames are the ones that would carry their directory layout and module names. Only
+ * frames inside a `@reticlehq/*` package or a `reticle` dist path survive, and even those keep just
+ * the file basename — enough to point a maintainer at the right file, never enough to describe
+ * anyone's machine.
+ */
+export declare function reticleFrames(stack: string): string[];
+/** How many of our own frames to carry. The innermost few are where the defect is. */
+export declare const MAX_REPORTED_FRAMES = 12;
+/**
+ * A crash fingerprint from the error's type and its Reticle-owned frames. Falls back to the message
+ * skeleton when a stack has no Reticle frames at all (a crash from deep inside a dependency), so a
+ * crash is never dropped for lack of a clean attribution.
+ */
+export declare function fingerprintCrash(errorType: string, stack: string, message: string): string;
+/** The error's constructor name (`TypeError`), or `Unknown` for a thrown non-Error. */
+export declare function errorTypeOf(error: unknown): string;

package/dist/telemetry/error-fingerprint.js

@@ -0,0 +1,88 @@
+/**
+ * Turning errors into something we can COUNT without carrying anything anyone wrote.
+ *
+ * An error message is the most tempting thing to send and the most dangerous: it is where a selector,
+ * a URL, a customer id, a file path, or a snippet of someone's app ends up. But "which error is
+ * hurting people most" is genuinely the highest-value product question we can ask, and it needs
+ * grouping — a thousand machines hitting the same defect have to collapse into one row before anyone
+ * can rank it.
+ *
+ * A fingerprint gives us the grouping without the content: strip every variable part, keep the
+ * skeleton, hash it. `no baseline named 'checkout-v3'` and `no baseline named 'login'` both become
+ * the same fingerprint, and neither flow name leaves the machine. The output is a short hex string,
+ * so even the skeleton is not readable on our side — it is an opaque group key, and its only power is
+ * that identical failures share it.
+ */
+import { createHash } from 'node:crypto';
+/**
+ * The variable parts, replaced before hashing. Order matters: quoted strings go first, because a
+ * quoted value often contains the very numbers and paths the later rules would only partly catch.
+ */
+const VARIABLE_PARTS = [
+    /"[^"]*"|'[^']*'|`[^`]*`/g, // quoted values — names, selectors, snippets
+    /\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, // URLs
+    /(?:\/[\w.-]+){2,}\/?/g, // POSIX-ish paths
+    /[A-Za-z]:\\[^\s]*/g, // Windows paths
+    /\b[0-9a-f]{8,}\b/gi, // hex ids, hashes, uuids-without-dashes
+    /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, // uuids
+    /\d+/g, // any remaining number — ports, counts, timeouts
+];
+/** The skeleton of a message: variable parts blanked, whitespace collapsed, length bounded. */
+export function errorSkeleton(message) {
+    let skeleton = message;
+    for (const pattern of VARIABLE_PARTS)
+        skeleton = skeleton.replace(pattern, '*');
+    return skeleton.replace(/\s+/g, ' ').trim().slice(0, 200);
+}
+/** A stable, opaque group key for an error message. Same defect ⇒ same key, on every machine. */
+export function fingerprintError(message) {
+    return createHash('sha256').update(errorSkeleton(message)).digest('hex').slice(0, 12);
+}
+/**
+ * Frames from a stack trace that belong to RETICLE, reduced to `basename:line`.
+ *
+ * A crash stack is mostly the user's own application and node internals; neither is ours to collect,
+ * and the user's frames are the ones that would carry their directory layout and module names. Only
+ * frames inside a `@reticlehq/*` package or a `reticle` dist path survive, and even those keep just
+ * the file basename — enough to point a maintainer at the right file, never enough to describe
+ * anyone's machine.
+ */
+export function reticleFrames(stack) {
+    const frames = [];
+    for (const line of stack.split('\n')) {
+        if (!/@reticlehq[/\\]|[/\\]reticle[/\\]dist[/\\]/.test(line))
+            continue;
+        const location = line.match(/([\w.-]+\.(?:js|mjs|cjs|ts)):(\d+)/);
+        if (location === null)
+            continue;
+        // `at Object.runTool (/path/to/invoke-tool.js:88:3)` → `runTool`. The function name is half the
+        // value of a frame in an RCA — "it died in act-tools.js" narrows to a file, "it died in
+        // resolveAnchor" names the thing that broke. Anonymous frames just report the location.
+        const fn = line.match(/at\s+(?:async\s+)?(?:new\s+)?([\w.$<>[\]]+)\s+\(/)?.[1];
+        const where = `${location[1] ?? ''}:${location[2] ?? ''}`;
+        // `Object.` / `Module.` prefixes are V8 noise that make the same function look like two.
+        const name = fn?.replace(/^(?:Object|Module|Function)\./, '');
+        frames.push(name === undefined || name === '' ? where : `${name}@${where}`);
+    }
+    return frames;
+}
+/** How many of our own frames to carry. The innermost few are where the defect is. */
+export const MAX_REPORTED_FRAMES = 12;
+/**
+ * A crash fingerprint from the error's type and its Reticle-owned frames. Falls back to the message
+ * skeleton when a stack has no Reticle frames at all (a crash from deep inside a dependency), so a
+ * crash is never dropped for lack of a clean attribution.
+ */
+export function fingerprintCrash(errorType, stack, message) {
+    const frames = reticleFrames(stack);
+    const basis = frames.length > 0
+        ? `${errorType}|${frames.join('|')}`
+        : `${errorType}|${errorSkeleton(message)}`;
+    return createHash('sha256').update(basis).digest('hex').slice(0, 12);
+}
+/** The error's constructor name (`TypeError`), or `Unknown` for a thrown non-Error. */
+export function errorTypeOf(error) {
+    if (error instanceof Error)
+        return error.constructor.name.slice(0, 64);
+    return 'Unknown';
+}

package/dist/telemetry/feedback-cli.d.ts

@@ -0,0 +1,31 @@
+import { TelemetryAction } from '../cli-parse.js';
+/**
+ * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the human half of the feedback channel.
+ *
+ * Kept to a single command with no prompts, no editor, and no account: the cost of telling us
+ * something has to be lower than the cost of shrugging and moving on, or we only ever hear from people
+ * angry enough to open an issue. A bare rating is a valid report; the words are optional garnish.
+ *
+ * What is sent is PRINTED before it goes, every time. A channel that carries free text and does not
+ * show you the payload is asking for trust it has not earned.
+ */
+export declare function handleFeedback(text: string, rating: number | undefined, bug: boolean): Promise<void>;
+/**
+ * `reticle identify` — opt-in, and it shows the consent notice before it sends anything.
+ *
+ * Deliberately NOT interactive: a prompt that appears in the middle of someone's work is pressure,
+ * and this is the one command where the user must be choosing freely. They type what they want to
+ * share, or they never run it at all.
+ */
+export declare function handleIdentify(parsed: {
+    context?: string;
+    company?: string;
+    email?: string;
+    forget: boolean;
+}): Promise<void>;
+/**
+ * `reticle telemetry [status|enable|disable]` — the user-facing control for anonymous usage metrics.
+ * `disable` persists a machine-wide opt-out (survives shells, unlike RETICLE_TELEMETRY=0); `status`
+ * says what's on, why, and where the full policy lives. Human-readable to stdout, like `doctor`.
+ */
+export declare function handleTelemetry(action: TelemetryAction): void;

package/dist/telemetry/feedback-cli.js

@@ -0,0 +1,102 @@
+import { FeedbackKind, FeedbackSource } from '@reticlehq/core';
+import { BUG_FLAG, RATING_FLAG } from '../cli-parse.js';
+import { describeFeedbackPayload, submitFeedback } from './feedback.js';
+import { describeTelemetry, setTelemetryEnabled } from './telemetry.js';
+import { TelemetryAction } from '../cli-parse.js';
+import { clearIdentity, IDENTIFY_NOTICE, readIdentity, saveIdentity, submitIdentity, UsageContextKind, } from './identify.js';
+/**
+ * `reticle feedback [--rating 1-5] [--bug] "what happened"` — the human half of the feedback channel.
+ *
+ * Kept to a single command with no prompts, no editor, and no account: the cost of telling us
+ * something has to be lower than the cost of shrugging and moving on, or we only ever hear from people
+ * angry enough to open an issue. A bare rating is a valid report; the words are optional garnish.
+ *
+ * What is sent is PRINTED before it goes, every time. A channel that carries free text and does not
+ * show you the payload is asking for trust it has not earned.
+ */
+export async function handleFeedback(text, rating, bug) {
+    const line = (s) => {
+        process.stdout.write(`${s}\n`);
+    };
+    if (text === '' && rating === undefined) {
+        line(`usage: reticle feedback [${RATING_FLAG} 1-5] [${BUG_FLAG}] "what worked, what didn't"`);
+        line('       your words go to the maintainers; nothing from your app is ever included.');
+        process.exitCode = 1;
+        return;
+    }
+    const receipt = await submitFeedback({
+        source: FeedbackSource.HUMAN,
+        kind: bug ? FeedbackKind.BUG : FeedbackKind.EXPERIENCE,
+        // A rating with no words is a real report, but the schema wants text — say what the rating means.
+        text: text === '' ? `rated ${String(rating)}/5 with no comment` : text,
+        ...(rating !== undefined ? { rating } : {}),
+    });
+    line(`sending      ${JSON.stringify(describeFeedbackPayload(receipt.context))}`);
+    if (receipt.redacted.length > 0) {
+        line(`redacted     ${receipt.redacted.join(', ')} (removed before sending)`);
+    }
+    line(receipt.sent
+        ? 'thanks       your feedback is in. it genuinely changes what gets built next.'
+        : `not sent     ${receipt.reason ?? 'unknown reason'}`);
+}
+/**
+ * `reticle identify` — opt-in, and it shows the consent notice before it sends anything.
+ *
+ * Deliberately NOT interactive: a prompt that appears in the middle of someone's work is pressure,
+ * and this is the one command where the user must be choosing freely. They type what they want to
+ * share, or they never run it at all.
+ */
+export async function handleIdentify(parsed) {
+    const line = (s) => {
+        process.stdout.write(`${s}\n`);
+    };
+    if (parsed.forget) {
+        clearIdentity();
+        line('forgotten    the local identity file is deleted; nothing further is sent.');
+        line('             to have what was already sent removed, email support@reticlehq.com');
+        return;
+    }
+    const context = Object.values(UsageContextKind).find((k) => k === parsed.context);
+    if (context === undefined) {
+        const existing = readIdentity();
+        if (existing !== undefined)
+            line(`current      ${JSON.stringify(existing)}`);
+        line(`usage: reticle identify --context <${Object.values(UsageContextKind).join('|')}>`);
+        line('       [--company "Acme"] [--email you@acme.com] [--forget]');
+        line('');
+        line(IDENTIFY_NOTICE);
+        process.exitCode = existing === undefined ? 1 : 0;
+        return;
+    }
+    const identity = {
+        context,
+        ...(parsed.company !== undefined ? { company: parsed.company } : {}),
+        ...(parsed.email !== undefined ? { email: parsed.email } : {}),
+    };
+    line(IDENTIFY_NOTICE);
+    line('');
+    line(`sending      ${JSON.stringify(identity)}`);
+    saveIdentity(identity);
+    const sent = await submitIdentity(identity);
+    line(sent
+        ? 'thanks       saved and sent. we may reach out; `reticle identify --forget` undoes this.'
+        : 'not sent     telemetry is disabled on this machine, so it was saved locally only.');
+}
+/**
+ * `reticle telemetry [status|enable|disable]` — the user-facing control for anonymous usage metrics.
+ * `disable` persists a machine-wide opt-out (survives shells, unlike RETICLE_TELEMETRY=0); `status`
+ * says what's on, why, and where the full policy lives. Human-readable to stdout, like `doctor`.
+ */
+export function handleTelemetry(action) {
+    const line = (s) => {
+        process.stdout.write(`${s}\n`);
+    };
+    if (action !== TelemetryAction.STATUS) {
+        setTelemetryEnabled(action === TelemetryAction.ENABLE);
+    }
+    const state = describeTelemetry();
+    line(`telemetry    ${state.enabled ? 'enabled' : 'disabled'}  (${state.reason})`);
+    line(`policy       ${state.policyUrl}`);
+    if (state.enabled)
+        line('opt out      reticle telemetry disable  (or RETICLE_TELEMETRY=0 / DO_NOT_TRACK=1)');
+}

package/dist/telemetry/feedback-context.d.ts

@@ -0,0 +1,32 @@
+import { McpScope, type Feedback } from '@reticlehq/core';
+/** The context fields — the whole `Feedback` shape minus what the author supplies. */
+export type FeedbackContext = Pick<Feedback, 'stack' | 'stackMajor' | 'runtime' | 'engine' | 'driver' | 'client' | 'clientVersion' | 'mcpScope'>;
+/**
+ * The project's framework and its MAJOR version, or `{}` when package.json is absent, unreadable, or
+ * names nothing we recognize. The major comes from `parseMajor` — the same range parser `reticle init`
+ * uses to decide React 19 source mapping — so a range like `^15.0.0-canary.3` narrows the same way in
+ * both places instead of via a second, subtly different reader.
+ */
+export declare function detectStack(cwd: string, read?: (path: string) => string): {
+    stack?: string;
+    stackMajor?: number;
+};
+/**
+ * User scope unless the project checks in its own MCP registration. `reticle init` deliberately
+ * registers ONCE at user scope, so `project` here means the team wired it up by hand — which is
+ * itself the interesting signal.
+ */
+export declare function detectMcpScope(cwd: string, exists?: (path: string) => boolean): McpScope;
+export declare function setMcpClientNameHook(hook: () => {
+    name?: string;
+    version?: string;
+} | undefined): void;
+/** What the connected session knows about itself — the shell it runs in and its rendering engine. */
+export interface SessionFacts {
+    runtime?: string;
+    engine?: string;
+    /** True when Reticle drives the page over CDP rather than observing the human's own browser. */
+    driven?: boolean;
+}
+/** Assemble the full context. Every field independently optional — a partial context still ships. */
+export declare function feedbackContext(cwd: string, session?: SessionFacts): FeedbackContext;

package/dist/telemetry/feedback-context.js

@@ -0,0 +1,143 @@
+/**
+ * The environment context stapled to every feedback report. Feedback without it is a complaint;
+ * feedback with it is a work item — "reticle_act misses the click" is unactionable, "reticle_act
+ * misses the click on Tauri + SvelteKit under a CDP driver" names the bug.
+ *
+ * Everything here is detected LOCALLY from files and env already on the machine, and every field is
+ * low-cardinality by construction (an enum, or a framework name off a fixed list). No paths, no repo
+ * names, no dependency inventory, no UA string — the same non-identifying bar the rest of telemetry
+ * holds to. Detection is entirely best-effort: an unreadable package.json or an SDK too old to report
+ * its runtime yields `undefined`, never a throw and never a guess.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { AppRuntime, McpScope, PageDriver } from '@reticlehq/core';
+import { parseMajor } from '../init/detect.js';
+/**
+ * Dependency → reported stack, in resolution order. Meta-frameworks come FIRST: a Next app also
+ * depends on react, and reporting `react` for it would collapse the single most important segment
+ * we have into the generic bucket.
+ *
+ * Deliberately NOT reusing `init/detect.ts`. That module answers a different question — "which build
+ * integration do I install?" — so its enum stops at next/vite/sveltekit/html. Widening it to carry
+ * vue/astro/solid would make `reticle init` branch on frameworks it has no install path for.
+ */
+const STACK_BY_DEP = [
+    ['next', 'next'],
+    ['@sveltejs/kit', 'sveltekit'],
+    ['nuxt', 'nuxt'],
+    ['astro', 'astro'],
+    ['@remix-run/react', 'remix'],
+    ['@angular/core', 'angular'],
+    ['react', 'react'],
+    ['vue', 'vue'],
+    ['svelte', 'svelte'],
+    ['solid-js', 'solid'],
+    ['vite', 'vite'],
+];
+const PACKAGE_JSON = 'package.json';
+/** A project-scoped MCP registration lives in one of these; `reticle init` writes user scope instead. */
+const PROJECT_MCP_FILES = ['.mcp.json', join('.cursor', 'mcp.json'), join('.vscode', 'mcp.json')];
+/**
+ * The project's framework and its MAJOR version, or `{}` when package.json is absent, unreadable, or
+ * names nothing we recognize. The major comes from `parseMajor` — the same range parser `reticle init`
+ * uses to decide React 19 source mapping — so a range like `^15.0.0-canary.3` narrows the same way in
+ * both places instead of via a second, subtly different reader.
+ */
+export function detectStack(cwd, read = readFile) {
+    let pkg;
+    try {
+        pkg = JSON.parse(read(join(cwd, PACKAGE_JSON)));
+    }
+    catch {
+        return {};
+    }
+    const deps = { ...pkg.devDependencies, ...pkg.dependencies };
+    for (const [dep, stack] of STACK_BY_DEP) {
+        const range = deps[dep];
+        if (range === undefined)
+            continue;
+        const stackMajor = parseMajor(range);
+        return { stack, ...(stackMajor !== undefined ? { stackMajor } : {}) };
+    }
+    return {};
+}
+/**
+ * User scope unless the project checks in its own MCP registration. `reticle init` deliberately
+ * registers ONCE at user scope, so `project` here means the team wired it up by hand — which is
+ * itself the interesting signal.
+ */
+export function detectMcpScope(cwd, exists = fileExists) {
+    return PROJECT_MCP_FILES.some((file) => exists(join(cwd, file)))
+        ? McpScope.PROJECT
+        : McpScope.USER;
+}
+function readFile(path) {
+    return readFileSync(path, 'utf8');
+}
+function fileExists(path) {
+    try {
+        readFileSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The MCP client on the other end, self-reported in its `initialize` handshake (`claude-code`,
+ * `cursor-vscode`, …). Read through a HOOK rather than sniffing env vars: the handshake is the
+ * client's own claim about itself, while an env-var table is a guess that silently rots every time a
+ * vendor renames a variable. Unset (a CLI run with no MCP peer) simply reports no client.
+ */
+let clientNameHook;
+export function setMcpClientNameHook(hook) {
+    clientNameHook = hook;
+}
+/**
+ * The client's own name and version from its handshake.
+ *
+ * Note what is NOT here and cannot be: the MODEL. MCP's `clientInfo` carries a name, a title and a
+ * version and has no concept of a model, so the transport genuinely cannot tell us. The agent
+ * self-reports it on the feedback itself, which is the only mechanism available and a reliable one
+ * given the report is already something the agent authored.
+ */
+function detectClient() {
+    try {
+        const info = clientNameHook?.();
+        const name = info?.name;
+        const version = info?.version;
+        return {
+            ...(name !== undefined && name !== '' ? { client: name.slice(0, 64) } : {}),
+            ...(version !== undefined && version !== '' ? { clientVersion: version.slice(0, 32) } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+function asRuntime(value) {
+    return Object.values(AppRuntime).find((known) => known === value);
+}
+function asEngine(value) {
+    // The SDK already narrows to blink/gecko/webkit before it reports, so anything else is a stale or
+    // hand-forged payload — drop it rather than widen the enum at the boundary.
+    const known = ['blink', 'gecko', 'webkit'];
+    return known.find((engine) => engine === value);
+}
+/** Assemble the full context. Every field independently optional — a partial context still ships. */
+export function feedbackContext(cwd, session) {
+    const runtime = asRuntime(session?.runtime);
+    const engine = asEngine(session?.engine);
+    const client = detectClient();
+    return {
+        ...detectStack(cwd),
+        ...client,
+        ...(runtime !== undefined ? { runtime } : {}),
+        ...(engine !== undefined ? { engine } : {}),
+        ...(session?.driven !== undefined
+            ? { driver: session.driven ? PageDriver.CDP : PageDriver.SDK }
+            : {}),
+        mcpScope: detectMcpScope(cwd),
+    };
+}