@reticlehq/server 3.5.0 → 3.7.0

package/dist/telemetry/feedback.js

@@ -22,18 +22,77 @@
  *      disables it too, since it rides the same emitter.
  */
 import { FeedbackSchema, FEEDBACK_TEXT_MAX, FEEDBACK_TRACE_MAX, FEEDBACK_FIELD_MAX, TelemetryEventKind, } from '@reticlehq/core/telemetry';
-import { platform } from 'node:os';
+import { homedir, platform } from 'node:os';
 import { getTelemetry } from './telemetry.js';
 import { noteFeedbackUndelivered } from './feedback-delivery.js';
 import { isReticleSourceCheckout } from './dev-repo.js';
 import { saveFeedbackLocally } from './feedback-local.js';
 import { SERVER_VERSION } from '../command/version/identity/server-version.js';
 import { feedbackContext } from './feedback-context.js';
-import { markDelivered, outboxPath, queueFeedback } from './feedback-outbox.js';
+import { markDelivered, outboxPath, queueFeedback, readOutbox } from './feedback-outbox.js';
 /** Kills the feedback channel ONLY — adoption counters keep flowing. */
 export const FEEDBACK_ENV = 'RETICLE_FEEDBACK';
 /** What replaces a redacted match. Visible on purpose: a reader must see that something was removed. */
 export const REDACTED = '[redacted]';
+/** This machine, as a host: the app under test, never anybody's infrastructure. Port allowed. */
+const LOCAL_HOST = /^(?:localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|0\.0\.0\.0|\[::1\])(?::\d+)?$/i;
+/** A dotted name ending in one of these is a source file, not a host. */
+const FILE_EXTENSIONS = new Set([
+    'ts',
+    'tsx',
+    'mts',
+    'cts',
+    'js',
+    'jsx',
+    'mjs',
+    'cjs',
+    'json',
+    'md',
+    'mdx',
+    'css',
+    'scss',
+    'html',
+    'vue',
+    'svelte',
+    'astro',
+    'py',
+    'rs',
+    'go',
+    'yml',
+    'yaml',
+    'toml',
+    'lock',
+    'log',
+    'txt',
+    'map',
+    'sh',
+    'env',
+    'd',
+]);
+/** Top-level domains common enough that a one-dot name ending in one is a host. */
+const COMMON_TLDS = new Set([
+    'com',
+    'net',
+    'org',
+    'io',
+    'dev',
+    'app',
+    'co',
+    'ai',
+    'cloud',
+    'internal',
+    'local',
+    'corp',
+    'lan',
+    'site',
+    'tech',
+    'xyz',
+    'us',
+    'uk',
+    'de',
+    'in',
+    'eu',
+]);
 /**
  * The shapes that leak. Ordered most-specific first — a URL carrying inline credentials must be
  * caught as a URL before the bare-token rule chews the middle out of it.
@@ -45,6 +104,15 @@ export const REDACTED = '[redacted]';
 const REDACTIONS = [
     // scheme://user:pass@host — the credential is in the authority section.
     { pattern: /\b([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+:[^\s/@]+@/gi, label: 'url-credentials' },
+    // A URL keeps its scheme, and its host and path ONLY when the host is this machine (the app under
+    // test, which is what a report is about). Any other host is a staging site, a customer's domain
+    // or an internal service, so it goes with its path. The query and fragment always go: that is
+    // where ids, emails and tokens ride.
+    {
+        pattern: /\b([a-z][a-z0-9+.-]*:\/\/)([^\s/?#"'<>`]+)([^\s?#"'<>`]*)(?:[?#][^\s"'<>`]*)?/gi,
+        label: 'url',
+        replace: (_m, scheme = '', host = '', path = '') => LOCAL_HOST.test(host) ? `${scheme}${host}${path}` : `${scheme}${REDACTED}`,
+    },
     { pattern: /\b[\w.%+-]+@[\w.-]+\.[a-z]{2,}\b/gi, label: 'email' },
     // Credential assignments: the KEY stays (it is the useful part), the VALUE goes. The auth SCHEME
     // (`Bearer`, `Basic`, `Token`) is consumed as part of the value, not left as the value — matching
@@ -59,24 +127,72 @@ const REDACTIONS = [
     { pattern: /\bAKIA[0-9A-Z]{16}\b/g, label: 'aws-key' },
     { pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, label: 'slack-token' },
     { pattern: /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, label: 'jwt' },
-    // Home directories carry the account name, and a trace is full of them.
-    { pattern: /(?:\/Users\/|\/home\/|[A-Z]:\\Users\\)[^\s/\\:"']+/g, label: 'home-path' },
+    // Home directories carry the account name, and a trace is full of them. The name runs to the next
+    // separator, quote or line end, NOT the next space: `C:\Users\Jane Doe\…` stopped at the space and
+    // sent the surname. Then the rest of the path goes with it. Over-redacting a sentence that follows
+    // a bare home directory is the price, and it is the right way round.
+    {
+        pattern: /(?:\\\\\?\\)?(?:\/Users\/|\/home\/|[A-Za-z]:[\\/]Users[\\/])[^\\/\r\n"'`]+(?:[\\/][^\s\\/"'`]*)*/g,
+        label: 'home-path',
+    },
+    // Any other absolute path: a Windows one (segments may hold spaces when a separator follows)...
+    {
+        pattern: /(?:\\\\\?\\)?\b[A-Za-z]:[\\/](?:[^\\/\r\n"'`<>|*?]+[\\/])*[^\s\\/"'`<>|*?]*/g,
+        label: 'path',
+    },
+    // ...a home-relative one, and a POSIX one of two or more segments. A path is a directory layout,
+    // and a directory layout names clients, projects and people.
+    { pattern: /~[\\/][^\s"'`]*/g, label: 'path' },
+    { pattern: /(?<![\w.~])\/[\w.@+-]+(?:\/[\w.@+-]+)+\/?/g, label: 'path' },
+    {
+        pattern: /\b\d{1,3}(?:\.\d{1,3}){3}\b/g,
+        label: 'ip',
+        replace: (ip) => (LOCAL_HOST.test(ip) ? ip : REDACTED),
+    },
+    // Hostnames: a staging site, an internal service, a customer's domain. A dotted name is a host when
+    // it has two or more dots or ends in a common top-level domain, and never when it ends in a source
+    // file's extension — `vite.config.ts` is what a report is about, `db.internal.acme.com` is not.
+    {
+        pattern: /\b(?:[a-z0-9-]+\.)+[a-z][a-z0-9-]*\b/gi,
+        label: 'hostname',
+        replace: (name) => {
+            const labels = name.toLowerCase().split('.');
+            const last = labels[labels.length - 1] ?? '';
+            if (FILE_EXTENSIONS.has(last))
+                return name;
+            return labels.length > 2 || COMMON_TLDS.has(last) ? REDACTED : name;
+        },
+    },
 ];
 /** Strip credential/PII shapes and cap the length. Pure — the tests read like a spec of what leaks. */
 export function redactFeedbackText(input, max) {
     const removed = new Set();
     let text = input;
-    for (const { pattern, label } of REDACTIONS) {
-        text = text.replace(pattern, (_match, ...groups) => {
-            removed.add(label);
+    for (const { pattern, label, replace } of REDACTIONS) {
+        text = text.replace(pattern, (match, ...groups) => {
+            const captures = groups.map((g) => ('string' === typeof g ? g : ''));
             // A rule with a leading capture keeps it (the scheme, the `api_key=` key) so the reader still
             // sees WHAT was removed, not just that something was.
-            const prefix = 'string' === typeof groups[0] ? groups[0] : '';
-            return `${prefix}${REDACTED}`;
+            const out = replace === undefined ? `${captures[0] ?? ''}${REDACTED}` : replace(match, ...captures);
+            if (out !== match)
+                removed.add(label);
+            return out;
         });
     }
     return { text: text.slice(0, max), removed: [...removed] };
 }
+/** Our words in a trace: tool names and the verdict vocabulary. Nothing else is kept. */
+const TRACE_WORDS = /\breticle_[a-z_]+\b|\b(?:verified|yes|no|unknown|no-fault|ok|passed|failed|refused|error|timeout)\b/gi;
+/**
+ * A trace reduced to Reticle's own words, in order: which tools were called and what verdict each
+ * gave. The raw trace is the call/response trail, and the responses carry the page's text and what
+ * was typed into it, which no redaction rule can tell from prose. So nothing else is kept.
+ */
+export function summarizeTrace(trace) {
+    return (trace.match(TRACE_WORDS) ?? []).join(' ').slice(0, FEEDBACK_TRACE_MAX);
+}
+/** The removal label when a trace lost anything to `summarizeTrace`. */
+const TRACE_VALUES_LABEL = 'trace-values';
 /** True when the feedback channel is switched off on its own (the emitter's switches apply as well). */
 export function feedbackDisabled(env = process.env) {
     const value = (env[FEEDBACK_ENV] ?? '').toLowerCase();
@@ -98,6 +214,7 @@ const AUTHOR_WRITTEN_FIELDS = new Set([
     'currentApproach',
     'model',
 ]);
+const TRACE_FIELD = 'trace';
 /** Per-field caps; anything unlisted uses the standard field cap. */
 const FIELD_CAPS = {
     text: FEEDBACK_TEXT_MAX,
@@ -120,14 +237,7 @@ export async function submitFeedback(input, opts = {}) {
     // sk-…" would have shipped the token. Enumerating the fields to protect is the same class of
     // mistake as hand-copying an enum: correct on the day it is written, quietly wrong at the next
     // addition. Deriving the set means a sixth field is covered the moment it exists.
-    const redactions = new Map();
-    for (const [key, value] of Object.entries(input)) {
-        if (typeof value !== 'string' || '' === value)
-            continue;
-        if (!AUTHOR_WRITTEN_FIELDS.has(key))
-            continue;
-        redactions.set(key, redactFeedbackText(value, FIELD_CAPS[key] ?? FEEDBACK_FIELD_MAX));
-    }
+    const redactions = redactAuthorFields(input);
     const body = redactions.get('text') ?? { text: '', removed: [] };
     const redacted = [...new Set([...redactions.values()].flatMap((r) => r.removed))];
     if (feedbackDisabled(env)) {
@@ -231,6 +341,62 @@ export async function submitFeedback(input, opts = {}) {
         context,
     };
 }
+/**
+ * Every author-written field of a report, redacted under the CURRENT rules. One function for the
+ * send and for the outbox drain, so a report queued under older, weaker rules is re-redacted before
+ * it finally goes.
+ */
+function redactAuthorFields(input) {
+    const redactions = new Map();
+    for (const [key, value] of Object.entries(input)) {
+        if (typeof value !== 'string' || '' === value)
+            continue;
+        if (!AUTHOR_WRITTEN_FIELDS.has(key))
+            continue;
+        if (TRACE_FIELD === key) {
+            const summary = summarizeTrace(value);
+            redactions.set(key, {
+                text: summary,
+                removed: summary === value ? [] : [TRACE_VALUES_LABEL],
+            });
+            continue;
+        }
+        redactions.set(key, redactFeedbackText(value, FIELD_CAPS[key] ?? FEEDBACK_FIELD_MAX));
+    }
+    return redactions;
+}
+/** Reports one daemon start retries. A backlog drains over several starts, never in one burst. */
+const OUTBOX_DRAIN_MAX = 5;
+/**
+ * Retry what the outbox holds: the receipt for an undelivered report promises "It will be retried",
+ * and until this ran on daemon start nothing ever read the outbox back. Bounded, sequential, and
+ * best-effort; a report the endpoint does not accept stays queued. Returns how many were delivered.
+ */
+export async function drainFeedbackOutbox(telemetry = getTelemetry(), home = homedir()) {
+    if (!telemetry.enabled || feedbackDisabled())
+        return 0;
+    let delivered = 0;
+    for (const entry of readOutbox(home).slice(0, OUTBOX_DRAIN_MAX)) {
+        const queued = FeedbackSchema.safeParse(entry.payload);
+        // A payload that cannot pass the schema can never be sent; it stays where a person can read it.
+        if (!queued.success)
+            continue;
+        const fields = Object.fromEntries([...redactAuthorFields(queued.data)].map(([key, r]) => [key, r.text]));
+        const parsed = FeedbackSchema.safeParse({ ...queued.data, ...fields });
+        if (!parsed.success)
+            continue;
+        try {
+            if (await telemetry.emit(TelemetryEventKind.FEEDBACK_SUBMITTED, { feedback: parsed.data })) {
+                markDelivered(entry.id, home);
+                delivered += 1;
+            }
+        }
+        catch {
+            /* stays queued for the next start */
+        }
+    }
+    return delivered;
+}
 /**
  * The receipt's context PLUS the fields the emitter stamps on every event regardless of kind — the
  * reticle version, the OS, and whether this is CI. They are the single most-asked question of any bug

package/dist/telemetry/harness-run.d.ts

@@ -0,0 +1,18 @@
+import { HarnessRunSource, type HarnessRun } from '@reticlehq/core/telemetry';
+import { DriveOrigin, DriveStatus } from '../features/harness/drive-runs.js';
+import { type Telemetry } from './telemetry.js';
+export interface HarnessRunStart {
+    source: HarnessRunSource;
+    hosted: boolean;
+}
+/** Who started it. A saved plan is a plan whoever pressed Run. */
+export declare function harnessRunSource(origin: DriveOrigin, planId: string | undefined): HarnessRunSource;
+/** How a finished run ended, from what the registry recorded. */
+export declare function harnessRunEnd(status: DriveStatus, result: Record<string, unknown> | undefined): Pick<HarnessRun, 'outcome' | 'journeys' | 'replayed'>;
+/** Report the run's start, run it, report its end, and hand back exactly what it did. */
+export declare function reportHarnessRun<T extends {
+    status: DriveStatus;
+    result: Record<string, unknown>;
+}>(start: HarnessRunStart, run: () => Promise<T>, refused: (error: unknown) => boolean, telemetry?: Pick<Telemetry, 'emit'>): Promise<T>;
+/** A run the gate refused before it could start: still somebody who asked for one. */
+export declare function reportHarnessBlocked(start: HarnessRunStart, telemetry?: Pick<Telemetry, 'emit'>): void;

package/dist/telemetry/harness-run.js

@@ -0,0 +1,80 @@
+/**
+ * `harness_run`: the Harness funnel. One `started` and one `completed` per run, whoever started it.
+ *
+ * Emitted around the drive itself (`startDrive`'s run), not read off the tool answer: a drive started
+ * from the HUD is never polled by an agent, and a drive whose daemon is asked again later answers
+ * from disk, so only the run's own start and end see every run exactly once.
+ *
+ * A drive the gate refuses before it starts is still a run somebody asked for, and reports as a
+ * `started` + `completed: blocked` pair, so the funnel's denominator is everyone who pressed Run.
+ */
+import { asRecord } from '@reticlehq/core';
+import { JourneyBy } from '@reticlehq/core/artifacts';
+import { HarnessRunOutcome, HarnessRunPhase, HarnessRunSource, TelemetryEventKind, countBucket, } from '@reticlehq/core/telemetry';
+import { DriveOrigin, DriveStatus } from '../features/harness/drive-runs.js';
+import { getTelemetry } from './telemetry.js';
+const SOURCE_OF = {
+    [DriveOrigin.AGENT]: HarnessRunSource.AGENT,
+    [DriveOrigin.HUD]: HarnessRunSource.HUD,
+    [DriveOrigin.CHAT]: HarnessRunSource.DASHBOARD,
+    [DriveOrigin.TRY]: HarnessRunSource.CLI_TRY,
+};
+/** Who started it. A saved plan is a plan whoever pressed Run. */
+export function harnessRunSource(origin, planId) {
+    return planId === undefined ? SOURCE_OF[origin] : HarnessRunSource.PLAN;
+}
+/** How a finished run ended, from what the registry recorded. */
+export function harnessRunEnd(status, result) {
+    const journeys = Array.isArray(result?.['journeys']) ? result['journeys'] : undefined;
+    const replayed = (journeys ?? []).filter((j) => JourneyBy.REPLAY === asRecord(j)['by']).length;
+    const outcome = DriveStatus.REFUSED === status
+        ? HarnessRunOutcome.BLOCKED
+        : DriveStatus.BROKEN === status
+            ? HarnessRunOutcome.FAILED
+            : DriveStatus.STOPPED === status
+                ? HarnessRunOutcome.STOPPED
+                : true === result?.['proved']
+                    ? HarnessRunOutcome.PROVED
+                    : HarnessRunOutcome.NOT_PROVED;
+    // An unplanned drive is one journey; a refused one drove none.
+    const count = journeys?.length ?? (HarnessRunOutcome.BLOCKED === outcome ? 0 : 1);
+    return { outcome, journeys: countBucket(count), replayed: countBucket(replayed) };
+}
+function emit(telemetry, harness) {
+    try {
+        void telemetry.emit(TelemetryEventKind.HARNESS_RUN, { harness });
+    }
+    catch {
+        /* a metric may never change a drive */
+    }
+}
+/** Report the run's start, run it, report its end, and hand back exactly what it did. */
+export async function reportHarnessRun(start, run, refused, telemetry = getTelemetry()) {
+    emit(telemetry, { phase: HarnessRunPhase.STARTED, ...start });
+    try {
+        const done = await run();
+        emit(telemetry, {
+            phase: HarnessRunPhase.COMPLETED,
+            ...start,
+            ...harnessRunEnd(done.status, done.result),
+        });
+        return done;
+    }
+    catch (error) {
+        emit(telemetry, {
+            phase: HarnessRunPhase.COMPLETED,
+            ...start,
+            ...harnessRunEnd(refused(error) ? DriveStatus.REFUSED : DriveStatus.BROKEN, undefined),
+        });
+        throw error;
+    }
+}
+/** A run the gate refused before it could start: still somebody who asked for one. */
+export function reportHarnessBlocked(start, telemetry = getTelemetry()) {
+    emit(telemetry, { phase: HarnessRunPhase.STARTED, ...start });
+    emit(telemetry, {
+        phase: HarnessRunPhase.COMPLETED,
+        ...start,
+        ...harnessRunEnd(DriveStatus.REFUSED, undefined),
+    });
+}

package/dist/telemetry/hud-events.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The HUD's own events: `hud_viewed` when a page is opened, `hud_signin_prompted` when a sign-in or
+ * link ask is shown. The windowed summary (`hudPanelMs`, `hudJourney`) says how long and in what
+ * order; these say how often and by whom, which a window summed across a session cannot.
+ *
+ * Sent by the daemon, like every HUD measure, so every opt-out applies, and only from the names the
+ * wire schema already narrowed. The dedupe (per tab, per page or surface) lives in `HudMetrics`.
+ */
+import type { HudUseData } from '@reticlehq/core';
+import { type Telemetry } from './telemetry.js';
+/** Count one HUD use from one tab, and send the events it amounts to. */
+export declare function reportHudUse(use: HudUseData, tab: string, telemetry?: Pick<Telemetry, 'emit'>): void;
+/** The tab went into the background or came back: its HUD time pauses while it is hidden. */
+export declare function noteHudTabHidden(tab: string, hidden: boolean): void;
+/** The tab went away. */
+export declare function noteHudTabClosed(tab: string): void;

package/dist/telemetry/hud-events.js

@@ -0,0 +1,27 @@
+import { TelemetryEventKind, countBucket } from '@reticlehq/core/telemetry';
+import { getSessionMetrics } from './session-metrics.js';
+import { getTelemetry } from './telemetry.js';
+/** Count one HUD use from one tab, and send the events it amounts to. */
+export function reportHudUse(use, tab, telemetry = getTelemetry()) {
+    const signals = getSessionMetrics().recordHudUse(use, tab);
+    const tabs = countBucket(signals.tabs);
+    try {
+        if (signals.viewed !== undefined)
+            void telemetry.emit(TelemetryEventKind.HUD_VIEWED, { hud: { view: signals.viewed, tabs } });
+        if (signals.prompted !== undefined)
+            void telemetry.emit(TelemetryEventKind.HUD_SIGNIN_PROMPTED, {
+                hud: { surface: signals.prompted, tabs },
+            });
+    }
+    catch {
+        /* a metric may never change behaviour */
+    }
+}
+/** The tab went into the background or came back: its HUD time pauses while it is hidden. */
+export function noteHudTabHidden(tab, hidden) {
+    getSessionMetrics().setHudTabHidden(tab, hidden);
+}
+/** The tab went away. */
+export function noteHudTabClosed(tab) {
+    getSessionMetrics().closeHudTab(tab);
+}

package/dist/telemetry/hud-metrics.d.ts

@@ -1,32 +1,55 @@
-import { HudPanel, HudView, type HudUseData } from '@reticlehq/core';
+import { HudPanel, HudView, type HudPromptSurface, type HudUseData } from '@reticlehq/core';
 /**
  * How people use the in-page HUD, rolled into the session summary.
  *
  * Windowed like the tool histograms beside it: a periodic flush reports what happened since the
  * last one, so a dashboard sums across a session's events. Names only — every key is a control id
  * the wire schema already checked against core's closed list.
+ *
+ * Time is kept PER TAB and only while the tab is visible. Two tabs used to share one open view, so
+ * one tab's change closed the other's clock, and a hidden or closed tab kept accruing for as long as
+ * the daemon lived.
  */
 /** How many steps of the journey one window keeps. A journey longer than this is cut, and says so. */
 export declare const HUD_JOURNEY_MAX = 60;
 export interface HudSummary {
     /** Presses per control; a toggle counts under `id:on` / `id:off` so a switch reads both ways. */
     hudControls?: Record<string, number>;
-    /** Milliseconds the HUD spent in each view during the window. */
+    /** Milliseconds the HUD spent in each view during the window, summed over visible tabs. */
     hudViewMs?: Partial<Record<HudView, number>>;
-    /** Milliseconds each panel was showing during the window. */
+    /** Milliseconds each panel was showing during the window, summed over visible tabs. */
     hudPanelMs?: Partial<Record<HudPanel, number>>;
     /** The window's presses and view changes, in order, cut at HUD_JOURNEY_MAX. */
     hudJourney?: string[];
     /** Present, and true, only when the journey was cut. */
     hudJourneyCut?: true;
+    /** Times each rail slide became the visible one. Slide ids are Reticle's own, never page text. */
+    hudSlides?: Record<string, number>;
+}
+/** The same page opened again on the same tab within this long is one view, not two. */
+export declare const HUD_VIEW_DEDUPE_MS = 30000;
+/** What one HUD use means for the per-event signals, beside what it adds to the summary. */
+export interface HudSignals {
+    /** A page this tab had not opened within the dedupe window. */
+    viewed?: HudPanel;
+    /** A sign-in prompt this tab had not shown before. */
+    prompted?: HudPromptSurface;
+    /** Tabs with a HUD right now. */
+    tabs: number;
 }
 export declare class HudMetrics {
     #private;
     constructor(now: () => number);
-    record(use: HudUseData): void;
+    record(use: HudUseData, tabId?: string): HudSignals;
+    /** The tab went into the background: its HUD stops accruing time until it is shown again. */
+    hide(tabId: string): void;
+    /** The tab is in front again: its HUD's view and panel accrue from now. */
+    show(tabId: string): void;
+    /** The tab went away: whatever it had open is counted up to now and stops. */
+    close(tabId: string): void;
     get empty(): boolean;
-    /** The window so far. Open view and panel are counted up to now, and keep running after. */
+    /** The window so far. Open views and panels are counted up to now, and keep running after. */
     summarize(): HudSummary;
-    /** Start the next window. The current view and panel carry over, timed from now. */
+    /** Start the next window. Each visible tab's view and panel carry over, timed from now. */
     reset(): void;
 }