@reticlehq/server 2.3.0 → 2.5.0

package/dist/telemetry/feedback-outbox.js

@@ -0,0 +1,87 @@
+/**
+ * A durable outbox for feedback, written BEFORE the network is touched.
+ *
+ * Feedback is the only qualitative channel this product has, and it carries an agent's whole
+ * root-cause analysis — often an hour of driving distilled into one payload. It was sent with the
+ * same 2-second fire-and-forget budget as a usage counter, with no retry and no persistence, so a
+ * 1.3-second network hiccup destroyed the report outright. Measured to the collector from one
+ * machine with a WARM DNS cache: dns 0.003s, connect 0.233s, tls 0.467s, total 0.694s — roughly a
+ * third of the entire budget spent before a byte of payload moves, and that is the good case. A
+ * fresh short-lived CLI process pays cold DNS and a cold route on top.
+ *
+ * So the order is inverted: write it down first, then try to send. A failed send is then a queued
+ * report rather than a lost one, and `sent: false` becomes a statement about the network instead of
+ * an epitaph.
+ *
+ * JSONL, appended, one payload per line. Append-only is the point — a crash mid-write costs at most
+ * the line being written, never the ones already there.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { ReticleDir } from '@reticlehq/core';
+export function outboxPath(home = homedir()) {
+    return join(home, ReticleDir.ROOT, 'feedback-outbox.jsonl');
+}
+/**
+ * Persist a report and return its id. Never throws: failing to queue must not also fail the send
+ * that was about to happen anyway.
+ */
+export function queueFeedback(payload, now = () => new Date(), home = homedir()) {
+    const id = randomUUID();
+    try {
+        mkdirSync(join(home, ReticleDir.ROOT), { recursive: true });
+        const entry = { id, t: now().toISOString(), payload };
+        appendFileSync(outboxPath(home), `${JSON.stringify(entry)}\n`, 'utf8');
+        return id;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read every queued report. A malformed line is skipped, never fatal — the rest still matter. */
+export function readOutbox(home = homedir()) {
+    try {
+        const path = outboxPath(home);
+        if (!existsSync(path))
+            return [];
+        return readFileSync(path, 'utf8')
+            .split('\n')
+            .filter((line) => 0 < line.trim().length)
+            .flatMap((line) => {
+            try {
+                return [JSON.parse(line)];
+            }
+            catch {
+                return [];
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Drop a report that was delivered. Rewrites the file without it.
+ *
+ * A rewrite rather than a tombstone because the file's whole purpose is "what still needs sending" —
+ * a reader should be able to `cat` it and see exactly the backlog, with no filtering rule to learn.
+ * Volume is a handful of lines a week, so the cost is irrelevant.
+ */
+export function markDelivered(id, home = homedir()) {
+    if (null === id)
+        return;
+    try {
+        const remaining = readOutbox(home).filter((entry) => entry.id !== id);
+        const path = outboxPath(home);
+        if (0 === remaining.length) {
+            writeFileSync(path, '', 'utf8');
+            return;
+        }
+        writeFileSync(path, `${remaining.map((entry) => JSON.stringify(entry)).join('\n')}\n`, 'utf8');
+    }
+    catch {
+        // A report that stays queued after a successful send is a duplicate at worst. Losing one is not.
+    }
+}

package/dist/telemetry/feedback.d.ts

@@ -39,8 +39,21 @@ export declare function feedbackDisabled(env?: NodeJS.ProcessEnv): boolean;
 /** What the author supplies; the environment context is detected, never asked for. */
 export type FeedbackInput = Pick<Feedback, 'source' | 'kind' | 'text' | 'trace' | 'rating' | 'need' | 'impact' | 'currentApproach' | 'model'>;
 export interface FeedbackReceipt {
-    /** False when a kill switch is on — the report was DROPPED, and the caller is told so plainly. */
+    /**
+     * DELIVERY confirmed. Only ever true when the send was awaited and the endpoint accepted it —
+     * never as an optimistic stand-in for "we handed it to the emitter". That distinction is the whole
+     * value of this field: it was once unconditional, so a DNS miss and a 4xx both reported "filed".
+     *
+     * A backgrounded send (the agent tool) therefore returns `sent: false` with `accepted: true` —
+     * see below. It is not a failure, and the note says so.
+     */
     sent: boolean;
+    /**
+     * Validated, redacted and handed to the emitter. TRUE says the report is well-formed and on its
+     * way; it does NOT say it arrived. If a backgrounded send then fails, the reporter is told on its
+     * next tool result — see feedback-delivery.ts.
+     */
+    accepted: boolean;
     reason?: string;
     /** Which redaction rules fired. Empty when nothing needed removing. */
     redacted: string[];
@@ -56,6 +69,14 @@ export declare function submitFeedback(input: FeedbackInput, opts?: {
     cwd?: string;
     session?: SessionFacts;
     env?: NodeJS.ProcessEnv;
+    /**
+     * Return as soon as the report is validated and queued, instead of waiting out the POST.
+     *
+     * Used by the AGENT tool: ~340ms of network on a call made mid-task is the product blocking the
+     * user's work to talk about itself. NOT used by `reticle feedback`, where a human typed the
+     * command and is waiting for an answer — there, confirmed delivery is the answer.
+     */
+    background?: boolean;
 }): Promise<FeedbackReceipt>;
 /**
  * The receipt's context PLUS the fields the emitter stamps on every event regardless of kind — the

package/dist/telemetry/feedback.js

@@ -24,8 +24,11 @@
 import { FeedbackSchema, FEEDBACK_TEXT_MAX, FEEDBACK_TRACE_MAX, FEEDBACK_FIELD_MAX, TelemetryEventKind, } from '@reticlehq/core';
 import { platform } from 'node:os';
 import { getTelemetry } from './telemetry.js';
-import { SERVER_VERSION } from '../server-version.js';
+import { noteFeedbackUndelivered } from './feedback-delivery.js';
+import { isReticleSourceCheckout } from './dev-repo.js';
+import { SERVER_VERSION } from '../version/server-version.js';
 import { feedbackContext } from './feedback-context.js';
+import { markDelivered, outboxPath, queueFeedback } 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. */
@@ -67,7 +70,7 @@ export function redactFeedbackText(input, max) {
             removed.add(label);
             // 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 = typeof groups[0] === 'string' ? groups[0] : '';
+            const prefix = 'string' === typeof groups[0] ? groups[0] : '';
             return `${prefix}${REDACTED}`;
         });
     }
@@ -76,7 +79,7 @@ export function redactFeedbackText(input, max) {
 /** 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();
-    return value === '0' || value === 'false' || value === 'off' || value === 'no';
+    return '0' === value || 'false' === value || 'off' === value || 'no' === value;
 }
 /**
  * The fields an author writes, and therefore the fields that must be redacted. ONE list, used both to
@@ -118,7 +121,7 @@ export async function submitFeedback(input, opts = {}) {
     // 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 === '')
+        if (typeof value !== 'string' || '' === value)
             continue;
         if (!AUTHOR_WRITTEN_FIELDS.has(key))
             continue;
@@ -127,13 +130,25 @@ export async function submitFeedback(input, opts = {}) {
     const body = redactions.get('text') ?? { text: '', removed: [] };
     const redacted = [...new Set([...redactions.values()].flatMap((r) => r.removed))];
     if (feedbackDisabled(env)) {
-        return { sent: false, reason: `feedback is disabled by ${FEEDBACK_ENV}`, redacted, context };
+        return {
+            sent: false,
+            accepted: false,
+            reason: `feedback is disabled by ${FEEDBACK_ENV}`,
+            redacted,
+            context,
+        };
     }
     const telemetry = getTelemetry();
     if (!telemetry.enabled) {
         return {
             sent: false,
-            reason: 'telemetry is disabled on this machine, so feedback has nowhere to go',
+            accepted: false,
+            // Named precisely, because the commonest cause is not what the old wording suggested: a
+            // Reticle SOURCE CHECKOUT disables telemetry by cwd, and that is exactly where release runs and
+            // contributor sessions happen — so the reports most worth having were the ones silently lost.
+            reason: isReticleSourceCheckout(opts.cwd ?? process.cwd())
+                ? 'this is a Reticle source checkout, where telemetry is disabled by design — so feedback has nowhere to go. Open an issue at https://github.com/reticlehq/reticle/issues instead, or run from the app you are verifying.'
+                : `telemetry is disabled on this machine, so feedback has nowhere to go. Re-enable with \`reticle telemetry enable\`, or open an issue at https://github.com/reticlehq/reticle/issues.`,
             redacted,
             context,
         };
@@ -151,13 +166,57 @@ export async function submitFeedback(input, opts = {}) {
     if (!parsed.success) {
         return {
             sent: false,
+            accepted: false,
             reason: parsed.error.issues[0]?.message ?? 'invalid feedback',
             redacted,
             context,
         };
     }
-    await telemetry.emit(TelemetryEventKind.FEEDBACK_SUBMITTED, { feedback: parsed.data });
-    return { sent: true, redacted, context };
+    // BACKGROUND: return now, deliver after. The agent calls this mid-task and a ~340ms POST is the
+    // product blocking the user's work to talk about itself. The honesty that the awaited version was
+    // written for is kept elsewhere: `sent` stays false (nothing is confirmed yet), `accepted` says
+    // the report is well-formed and queued, and a send that then fails reaches the reporter on its
+    // next tool result instead of vanishing.
+    // Written down BEFORE the network is touched, on both paths. A failed send is then a queued report
+    // rather than a lost one — see feedback-outbox. Reported from the field: a 1.3s hiccup destroyed a
+    // root-cause analysis that took an hour of driving to produce, and it survived only because the
+    // reporter happened to have written the markdown by hand first.
+    const queued = queueFeedback(parsed.data);
+    if (true === opts.background) {
+        void telemetry
+            .emit(TelemetryEventKind.FEEDBACK_SUBMITTED, { feedback: parsed.data })
+            .then((ok) => {
+            if (ok)
+                markDelivered(queued);
+            else
+                noteFeedbackUndelivered('the telemetry endpoint did not accept it');
+        })
+            .catch((error) => {
+            noteFeedbackUndelivered(error instanceof Error ? error.message : String(error));
+        });
+        return { sent: false, accepted: true, redacted, context };
+    }
+    // `sent` reflects DELIVERY, not handing the payload to the emitter. It was unconditional, so a DNS
+    // miss or a 4xx both reported "filed" — and this is the only qualitative channel the product has,
+    // so a silent failure here loses the report AND tells the reporter it worked.
+    const delivered = await telemetry.emit(TelemetryEventKind.FEEDBACK_SUBMITTED, {
+        feedback: parsed.data,
+    });
+    if (delivered) {
+        markDelivered(queued);
+        return { sent: true, accepted: true, redacted, context };
+    }
+    // Undelivered, but no longer lost. `accepted` is true when it reached the outbox: the report is
+    // well-formed and on disk, which is a materially different situation from "it is gone".
+    return {
+        sent: false,
+        accepted: queued !== null,
+        reason: queued !== null
+            ? `the report could not be delivered (the network call failed or was rejected), but it is SAVED at ${outboxPath()} and nothing was lost. It will be retried; you can also open an issue at https://github.com/reticlehq/reticle/issues with the same detail.`
+            : 'the report could not be delivered and could not be saved locally either — it was NOT filed. Retry, or open an issue at https://github.com/reticlehq/reticle/issues with the same detail.',
+        redacted,
+        context,
+    };
 }
 /**
  * The receipt's context PLUS the fields the emitter stamps on every event regardless of kind — the

package/dist/telemetry/git-facts.js

@@ -96,7 +96,7 @@ export function gitFacts(cwd, read = defaultRead, exists = defaultExists) {
             if (url === undefined)
                 return { state: GitState.LOCAL_ONLY };
             const origin = normalizeGitOrigin(url);
-            if (origin === '')
+            if ('' === origin)
                 return { state: GitState.LOCAL_ONLY };
             return { state: GitState.REMOTE, origin, forge: forgeOf(origin) };
         }

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

@@ -62,6 +62,8 @@ export declare class SessionMetrics {
         breadcrumb: string[];
         inFlight: string | undefined;
     };
+    /** One action driven at the page. Settled by the next verdict; see #unsettledActions. */
+    recordAction(): void;
     recordVerification(): void;
     /**
      * One defect found in the app under test — the outcome number, kept broken down by kind.

package/dist/telemetry/session-metrics.js

@@ -21,6 +21,17 @@ import { describeToolParams } from './argument-shape.js';
 import { machineSnapshot } from './machine-snapshot.js';
 /** Cap the distinct error shapes held in memory — a pathological loop must not grow unbounded. */
 const MAX_ERROR_KINDS = 40;
+/** Distinct tool names whose repeat-runs are tracked. Its own cap: the tool surface, not error shapes. */
+const MAX_REPEAT_TOOLS = 64;
+/**
+ * Tool errors that all mean the same thing to a user: the agent asked, and there was no app it could
+ * reach. Three different messages, one experience — "nothing is connected" — and it is the error
+ * that ends most sessions before a single verification happens.
+ *
+ * `multiple sessions connected` belongs here too: the agent could not reach AN app because it could
+ * not tell which one, and the outcome is identical.
+ */
+const NO_SESSION_ERROR = /no browser session connected|no connected session with id|multiple sessions connected/i;
 /** Cap distinct MCP clients recorded; more than a handful on one daemon is already the story. */
 const MAX_CLIENTS = 8;
 /** Bounds on the parameter map. Our own schemas are already finite; these are a belt-and-braces cap. */
@@ -71,6 +82,25 @@ export class SessionMetrics {
      * capped: the kind vocabulary is a bounded enum plus oracle names, not user data.
      */
     #seenBugKinds = new Set();
+    /**
+     * Tool errors meaning "the agent could not reach an app at all" — the single biggest drop-off in
+     * the funnel, and until now reachable only by unpacking `errors[]` in HogQL. 74% of daemons never
+     * call a tool, and of the sessions that made exactly one call, most bounced on this.
+     */
+    #noSessionErrors = 0;
+    /** Longest back-to-back run per tool — a retry loop, which `toolCounts` cannot distinguish. */
+    #repeatRuns = new Map();
+    #lastTool;
+    #currentRun = 0;
+    /**
+     * Actions driven since the last verdict — the run that is left hanging if the loop stops here.
+     *
+     * NOT `actions - verifications`. That difference ignores ORDER, so a verdict that drove nothing
+     * (a `flow_verify` over saved flows) silently paid for a genuinely abandoned action elsewhere, and
+     * a session could verify first and act after and look settled. What is abandoned is the trailing
+     * run, which is exactly what the field claims to mean.
+     */
+    #unsettledActions = 0;
     #clients = new Set();
     #startedAt;
     #now;
@@ -120,6 +150,16 @@ export class SessionMetrics {
         this.#unknownToolCalls += 1;
     }
     recordToolCall(tool, args) {
+        // A run of the same tool back to back. Five calls to reticle_act is engagement; five in a row
+        // after four failures is an agent stuck, and toolCounts reports both as "5".
+        this.#currentRun = tool === this.#lastTool ? this.#currentRun + 1 : 1;
+        this.#lastTool = tool;
+        if (this.#currentRun > 1) {
+            const best = this.#repeatRuns.get(tool) ?? 0;
+            if (this.#currentRun > best &&
+                (this.#repeatRuns.has(tool) || this.#repeatRuns.size < MAX_REPEAT_TOOLS))
+                this.#repeatRuns.set(tool, this.#currentRun);
+        }
         this.#toolCalls += 1;
         bump(this.#toolCounts, tool);
         this.#inFlight = tool;
@@ -150,6 +190,8 @@ export class SessionMetrics {
      */
     recordToolError(message, tool) {
         this.#toolErrors += 1;
+        if (NO_SESSION_ERROR.test(message))
+            this.#noSessionErrors += 1;
         const fingerprint = fingerprintError(message);
         const existing = this.#errorKinds.get(fingerprint);
         if (existing !== undefined) {
@@ -194,8 +236,14 @@ export class SessionMetrics {
     get trail() {
         return { breadcrumb: [...this.#breadcrumb], inFlight: this.#inFlight };
     }
+    /** One action driven at the page. Settled by the next verdict; see #unsettledActions. */
+    recordAction() {
+        this.#unsettledActions += 1;
+    }
     recordVerification() {
         this.#verifications += 1;
+        // A verdict settles whatever was outstanding, however many actions it took to get there.
+        this.#unsettledActions = 0;
     }
     /**
      * One defect found in the app under test — the outcome number, kept broken down by kind.
@@ -258,6 +306,12 @@ export class SessionMetrics {
             verifications: this.#verifications,
             bugsFound: this.#bugsFound,
             ...(this.#bugKinds.size > 0 ? { bugKinds: Object.fromEntries(this.#bugKinds) } : {}),
+            ...(this.#noSessionErrors > 0 ? { noSessionErrors: this.#noSessionErrors } : {}),
+            ...(this.#repeatRuns.size > 0
+                ? { consecutiveRepeats: Object.fromEntries(this.#repeatRuns) }
+                : {}),
+            // Absent rather than zero, so the PRESENCE of the field is the signal on a dashboard.
+            ...(this.#unsettledActions > 0 ? { abandonedActions: this.#unsettledActions } : {}),
             ...(this.#toolParams.size > 0
                 ? {
                     toolParams: Object.fromEntries([...this.#toolParams].map(([tool, params]) => [tool, Object.fromEntries(params)])),
@@ -277,17 +331,22 @@ export class SessionMetrics {
     }
     /** True when nothing at all happened — a flush of an idle daemon is not worth an event. */
     get empty() {
-        return (this.#toolCalls === 0 &&
-            this.#verifications === 0 &&
-            this.#toolErrors === 0 &&
-            this.#bugsFound === 0 &&
-            this.#sdkFailures === 0);
+        return (0 === this.#toolCalls &&
+            0 === this.#verifications &&
+            0 === this.#toolErrors &&
+            0 === this.#bugsFound &&
+            0 === this.#sdkFailures);
     }
     /** Zero the counters after a non-final flush so the next flush reports the NEXT window, not a total. */
     reset() {
         this.#toolCalls = 0;
         this.#toolErrors = 0;
         this.#verifications = 0;
+        this.#noSessionErrors = 0;
+        this.#repeatRuns.clear();
+        this.#lastTool = undefined;
+        this.#currentRun = 0;
+        this.#unsettledActions = 0;
         this.#toolCounts.clear();
         this.#toolParams.clear();
         this.#errorKinds.clear();
@@ -302,7 +361,10 @@ export class SessionMetrics {
         this.#unknownToolCalls = 0;
         this.#bugsFound = 0;
         this.#bugKinds.clear();
-        this.#seenBugKinds.clear();
+        // #seenBugKinds is deliberately NOT cleared. It is not a window counter — it is the
+        // session-lifetime memory behind `repeat` on bug_found, and zeroing it made the same defect,
+        // found again after a flush, report as a newly distinct one. Sessions run to 11.5 hours in the
+        // data, so that was up to 23 chances to count one defect many times.
     }
 }
 function bump(map, key) {

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,20 @@
-import { TelemetryEventKind, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type McpConnection, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
+import { TelemetryEventKind, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type McpConnection, type McpOutage, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core';
+/**
+ * Feedback gets its own, much larger budget — and a retry.
+ *
+ * 2s + drop is right for a usage counter: the metric is worthless if it costs the user latency, and
+ * losing one changes nothing. Feedback is the opposite on both counts. It is the only qualitative
+ * channel the product has, it carries an agent's entire root-cause analysis, and losing one loses
+ * work that cannot be reconstructed.
+ *
+ * Measured to the collector with a WARM DNS cache: dns 0.003s, connect 0.233s, tls 0.467s, total
+ * 0.694s — a third of the old budget gone before any payload moves, on the good path. A fresh
+ * short-lived CLI process pays cold DNS and a cold route on top, which is exactly the case that
+ * failed in the field and then succeeded on retry from a warmer process.
+ */
+export declare const FEEDBACK_TIMEOUT_MS = 15000;
+export declare const FEEDBACK_RETRIES = 1;
+export declare const FEEDBACK_RETRY_BACKOFF_MS = 750;
 /** The current telemetry state and which control set it — what `reticle telemetry status` prints. */
 export declare const describeTelemetry: (env?: NodeJS.ProcessEnv, dir?: string, cwd?: string) => {
     enabled: boolean;
@@ -38,6 +54,8 @@ export interface TelemetryExtra {
     init?: InitOutcome;
     /** `bug_found`: one defect Reticle found in the app under test. */
     bug?: BugFound;
+    /** `mcp_connection_lost`: the agent lost its tools — which stage, and why. */
+    outage?: McpOutage;
 }
 export interface Telemetry {
     /**
@@ -45,7 +63,14 @@ export interface Telemetry {
      * CLI process can exit immediately instead of waiting out the POST (use it from command entry
      * points; daemon-side events send in-process).
      */
-    emit(kind: TelemetryEventKind, extra?: TelemetryExtra): Promise<void>;
+    /**
+     * Send one event. Resolves to whether it was DELIVERED.
+     *
+     * Almost every caller ignores the result and should — a lost metric must never surface to a user.
+     * `reticle_feedback` is the exception: it hands a receipt to an agent, and reporting "filed" for a
+     * send that failed loses the report and lies about it in the same breath.
+     */
+    emit(kind: TelemetryEventKind, extra?: TelemetryExtra): Promise<boolean>;
     readonly enabled: boolean;
     /** True the very first run on this machine — the CLI emits INSTALL alongside the first INVOKE. */
     readonly firstRun: boolean;