@reticlehq/server 3.7.0 → 3.8.1

package/dist/telemetry/feedback.js

@@ -93,6 +93,11 @@ const COMMON_TLDS = new Set([
     'in',
     'eu',
 ]);
+/**
+ * One path separator in every spelling that a report can carry: `/` and `\`, and the JSON-escaped
+ * forms `\/`, `\\` and `\\/`. An agent that pastes a JSON string doubles each backslash.
+ */
+const PATH_SEP = String.raw `(?:\\{0,2}\/|\\{1,2})`;
 /**
  * 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.
@@ -117,22 +122,48 @@ const REDACTIONS = [
     // 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
     // only `\S+` after the separator ate the word "Bearer" and published the secret right behind it.
+    // A linking verb is skipped too: "my password is hunter2" lost the word "is" and kept hunter2.
+    {
+        pattern: /\b(authorization|api[-_]?key|secret|token|password|passwd|pwd)\b(?:\s*[:=]\s*|\s+(?:(?:is|was|=|:)\s+)?)(?:(?:bearer|basic|token|digest)\s+)?\S+/gi,
+        label: 'credential-assignment',
+    },
+    // An environment-style assignment: `STRIPE_SECRET_KEY=…`, `AWS_SECRET_ACCESS_KEY=…`, `DB_PASS: …`.
+    // `\b` does not end a word at `_`, so the rule above never saw these. The sensitive word must be
+    // one whole `_` segment of the name, so `PASSPORT_ID` or `TOKENIZER_MODE` stay.
     {
-        pattern: /\b(authorization|api[-_]?key|secret|token|password|passwd|pwd)\b(?:\s*[:=]\s*|\s+)(?:(?:bearer|basic|token|digest)\s+)?\S+/gi,
+        pattern: /\b((?:[A-Za-z0-9]+_)*(?:SECRET|TOKEN|PASS|PASSWORD|PASSWD|PWD|PASSPHRASE|API_?KEY|PRIVATE_?KEY|ACCESS_?KEY|AUTH|CREDENTIALS?)(?:_[A-Za-z0-9]+)*)\s*[:=]\s*\S+/gi,
         label: 'credential-assignment',
     },
-    // Vendor key formats that are self-identifying (sk-…, ghp_…, AKIA…, xoxb-…, eyJ… JWTs).
+    // Vendor key formats that are self-identifying (sk-…, sk_live_…, ghp_…, AKIA…, xoxb-…, eyJ… JWTs).
     { pattern: /\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}\b/g, label: 'vendor-key' },
+    { pattern: /\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{10,}\b/g, label: 'vendor-key' },
     { pattern: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, label: 'github-token' },
-    { pattern: /\bAKIA[0-9A-Z]{16}\b/g, label: 'aws-key' },
+    { pattern: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, label: 'github-token' },
+    { pattern: /\bglpat-[A-Za-z0-9_-]{20,}\b/g, label: 'gitlab-token' },
+    { pattern: /\bAIza[0-9A-Za-z_-]{35}\b/g, label: 'google-key' },
+    { pattern: /\b(?:AKIA|ASIA)[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' },
+    // A payment card: 13 to 19 digits, spaces or dashes allowed, that pass the Luhn check. An id or a
+    // millisecond timestamp rarely starts with 2 to 6 AND passes Luhn, so those stay.
+    {
+        pattern: /\b[2-6](?:[ -]?\d){12,18}\b/g,
+        label: 'card-number',
+        replace: (digits) => (luhnValid(digits.replace(/\D/g, '')) ? REDACTED : digits),
+    },
+    // A phone number: an international `+` number, or a ten-digit (123) 456-7890 shape.
+    {
+        pattern: /(?<![\w+])\+\d[\d ().-]{6,18}\d(?!\w)/g,
+        label: 'phone',
+        replace: (number) => (8 <= number.replace(/\D/g, '').length ? REDACTED : number),
+    },
+    { pattern: /(?<![\w(])\(?\d{3}\)?[ .-]\d{3}[ .-]\d{4}\b/g, label: 'phone' },
     // 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,
+        pattern: new RegExp(String.raw `(?:\\\\\?\\)?(?:${PATH_SEP}(?:Users|home)${PATH_SEP}|[A-Za-z]:${PATH_SEP}Users${PATH_SEP})[^\\/\r\n"'${'`'}]+(?:[\\/][^\s\\/"'${'`'}]*)*`, 'gi'),
         label: 'home-path',
     },
     // Any other absolute path: a Windows one (segments may hold spaces when a separator follows)...
@@ -164,6 +195,20 @@ const REDACTIONS = [
         },
     },
 ];
+/** The Luhn checksum every payment card number carries. */
+function luhnValid(digits) {
+    let sum = 0;
+    for (let i = 0; i < digits.length; i++) {
+        let d = Number(digits[digits.length - 1 - i]);
+        if (1 === i % 2) {
+            d *= 2;
+            if (9 < d)
+                d -= 9;
+        }
+        sum += d;
+    }
+    return 0 === sum % 10;
+}
 /** 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();
@@ -284,6 +329,8 @@ export async function submitFeedback(input, opts = {}) {
         ...Object.fromEntries([...redactions].filter(([, r]) => r.text !== '').map(([key, r]) => [key, r.text])),
         text: body.text,
         ...(input.rating !== undefined ? { rating: input.rating } : {}),
+        // Not redacted: the person gave this address so the maintainers can answer. Sent only then.
+        ...(input.contact !== undefined ? { contact: input.contact } : {}),
         ...context,
     });
     if (!parsed.success) {

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

@@ -1,4 +1,4 @@
-import { HarnessRunSource, type HarnessRun } from '@reticlehq/core/telemetry';
+import { HarnessRunReason, 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 {
@@ -8,11 +8,11 @@ export interface HarnessRunStart {
 /** 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'>;
+export declare function harnessRunEnd(status: DriveStatus, result: Record<string, unknown> | undefined, reason?: HarnessRunReason): Pick<HarnessRun, 'outcome' | 'journeys' | 'replayed' | 'reason'>;
 /** 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;
+export declare function reportHarnessBlocked(start: HarnessRunStart, reason: HarnessRunReason, telemetry?: Pick<Telemetry, 'emit'>): void;

package/dist/telemetry/harness-run.js

@@ -10,8 +10,8 @@
  */
 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 { HarnessRunOutcome, HarnessRunPhase, HarnessRunReason, HarnessRunSource, TelemetryEventKind, countBucket, } from '@reticlehq/core/telemetry';
+import { DriveOrigin, DriveRefusedError, DriveStatus } from '../features/harness/drive-runs.js';
 import { getTelemetry } from './telemetry.js';
 const SOURCE_OF = {
     [DriveOrigin.AGENT]: HarnessRunSource.AGENT,
@@ -24,7 +24,7 @@ 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) {
+export function harnessRunEnd(status, result, reason) {
     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
@@ -38,7 +38,18 @@ export function harnessRunEnd(status, result) {
                     : 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) };
+    // Why it did not drive: only a blocked or failed run has a reason, and a break names itself.
+    const why = HarnessRunOutcome.BLOCKED === outcome
+        ? (reason ?? HarnessRunReason.OTHER)
+        : HarnessRunOutcome.FAILED === outcome
+            ? (reason ?? HarnessRunReason.BROKEN)
+            : undefined;
+    return {
+        outcome,
+        journeys: countBucket(count),
+        replayed: countBucket(replayed),
+        ...(why === undefined ? {} : { reason: why }),
+    };
 }
 function emit(telemetry, harness) {
     try {
@@ -64,17 +75,17 @@ export async function reportHarnessRun(start, run, refused, telemetry = getTelem
         emit(telemetry, {
             phase: HarnessRunPhase.COMPLETED,
             ...start,
-            ...harnessRunEnd(refused(error) ? DriveStatus.REFUSED : DriveStatus.BROKEN, undefined),
+            ...harnessRunEnd(refused(error) ? DriveStatus.REFUSED : DriveStatus.BROKEN, undefined, error instanceof DriveRefusedError ? error.reason : undefined),
         });
         throw error;
     }
 }
 /** A run the gate refused before it could start: still somebody who asked for one. */
-export function reportHarnessBlocked(start, telemetry = getTelemetry()) {
+export function reportHarnessBlocked(start, reason, telemetry = getTelemetry()) {
     emit(telemetry, { phase: HarnessRunPhase.STARTED, ...start });
     emit(telemetry, {
         phase: HarnessRunPhase.COMPLETED,
         ...start,
-        ...harnessRunEnd(DriveStatus.REFUSED, undefined),
+        ...harnessRunEnd(DriveStatus.REFUSED, undefined, reason),
     });
 }

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

@@ -4,7 +4,7 @@
  * 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`.
+ * wire schema already narrowed. The dedupe (per daemon, per page or surface) lives in `HudMetrics`.
  */
 import type { HudUseData } from '@reticlehq/core';
 import { type Telemetry } from './telemetry.js';

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

@@ -26,13 +26,16 @@ export interface HudSummary {
     /** 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. */
+/**
+ * The same page opened again within this long is one view, not two. Per daemon, not per tab: a page
+ * reload makes a new tab id, and a page that reloads in a loop is still one person on one page.
+ */
 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. */
+    /** A page not opened within the dedupe window. */
     viewed?: HudPanel;
-    /** A sign-in prompt this tab had not shown before. */
+    /** A sign-in prompt this daemon had not shown before. */
     prompted?: HudPromptSurface;
     /** Tabs with a HUD right now. */
     tabs: number;

package/dist/telemetry/hud-metrics.js

@@ -16,7 +16,10 @@ export const HUD_JOURNEY_MAX = 60;
 /** Distinct slide ids counted per window; past this a broken notices file is not a dashboard. */
 const MAX_SLIDE_IDS = 20;
 const SLIDE_ID = /^[a-z0-9-]{1,56}$/;
-/** The same page opened again on the same tab within this long is one view, not two. */
+/**
+ * The same page opened again within this long is one view, not two. Per daemon, not per tab: a page
+ * reload makes a new tab id, and a page that reloads in a loop is still one person on one page.
+ */
 export const HUD_VIEW_DEDUPE_MS = 30_000;
 /** A tab whose page reported HUD use without saying which tab: an older caller, or a test. */
 const UNNAMED_TAB = '';
@@ -28,6 +31,10 @@ export class HudMetrics {
     #journey = [];
     #slides = new Map();
     #tabs = new Map();
+    /** When each page last counted as a view. Daemon-lifetime: a window reset keeps it. */
+    #viewedAt = new Map();
+    /** The prompts already reported. Daemon-lifetime, like the views. */
+    #prompted = new Set();
     #cut = false;
     /** Did anything happen this window. A HUD merely sitting open is not worth a flush of its own. */
     #changed = false;
@@ -37,8 +44,8 @@ export class HudMetrics {
     record(use, tabId = UNNAMED_TAB) {
         const tab = this.#tab(tabId);
         const signals = { tabs: this.#tabs.size };
-        if (use.prompt !== undefined && !tab.prompted.has(use.prompt)) {
-            tab.prompted.add(use.prompt);
+        if (use.prompt !== undefined && !this.#prompted.has(use.prompt)) {
+            this.#prompted.add(use.prompt);
             signals.prompted = use.prompt;
         }
         // A control the HUD never rendered is dropped here, the one place HUD use is counted, so free
@@ -53,6 +60,7 @@ export class HudMetrics {
             const key = use.toggle === undefined ? control : `${control}:${use.toggle}`;
             this.#controls.set(key, (this.#controls.get(key) ?? 0) + 1);
             this.#step(key);
+            tab.pressed = true;
         }
         const at = this.#now();
         const since = tab.hidden ? undefined : at;
@@ -62,13 +70,18 @@ export class HudMetrics {
             this.#step(`view:${use.view}`);
         }
         if (use.panel !== undefined && use.panel !== tab.panel?.value) {
+            // The HUD opens the Agent Log by itself when an agent acts, or on load when the person left it
+            // open. No press came first, so it is not a choice and not a view. Its time still counts in
+            // `hudPanelMs`.
+            const opensByItself = HudPanel.CHAT === use.panel && !tab.pressed;
+            tab.pressed = false;
             this.#close(tab.panel, this.#panelMs);
             tab.panel = { value: use.panel, since };
             if (use.panel !== HudPanel.NONE) {
                 this.#step(`panel:${use.panel}`);
-                const last = tab.viewedAt.get(use.panel);
-                if (last === undefined || at - last >= HUD_VIEW_DEDUPE_MS) {
-                    tab.viewedAt.set(use.panel, at);
+                const last = this.#viewedAt.get(use.panel);
+                if (!opensByItself && (last === undefined || at - last >= HUD_VIEW_DEDUPE_MS)) {
+                    this.#viewedAt.set(use.panel, at);
                     signals.viewed = use.panel;
                 }
             }
@@ -111,8 +124,7 @@ export class HudMetrics {
             view: undefined,
             panel: undefined,
             hidden: false,
-            viewedAt: new Map(),
-            prompted: new Set(),
+            pressed: false,
         };
         this.#tabs.set(tabId, tab);
         return tab;

package/dist/telemetry/install-source.js

@@ -11,7 +11,7 @@
  * WHICH CHANNELS ARE GENUINELY DETECTABLE TODAY, so nobody later reads a small `unknown` as success:
  *  - `plugin` — real. The Claude Code plugin registers the MCP server itself and can set the marker
  *    in that server's `env`, so it is carried by the process without anybody typing anything.
- *  - `skill_file` / `npx_skill` / `docs_site` / `readme` — real ONLY where that channel's own copy
+ *  - `skill_file` / `npx_skill` / `docs_site` / `readme` / `blog` — real ONLY where that channel's own copy
  *    of the install command carries the marker. Each is a separately published artifact, so a copy
  *    that has not been updated is indistinguishable from no channel at all.
  *  - `cli_direct` — NOT detectable. Nobody types a marker to say they typed a command. It exists so

package/dist/telemetry/mcp-connection.d.ts

@@ -1,4 +1,4 @@
 export declare function markDaemonStart(now: number): void;
-export declare function reportMcpConnected(client?: string, now?: () => number): void;
+export declare function reportMcpConnected(client?: string, attachId?: string, now?: () => number): void;
 /** Tests only. */
 export declare function resetMcpConnections(): void;

package/dist/telemetry/mcp-connection.js

@@ -13,11 +13,14 @@ import { TelemetryEventKind } from '@reticlehq/core/telemetry';
 import { getTelemetry } from './telemetry.js';
 import { appEverConnected } from './app-instrumented.js';
 let connectsSeen = 0;
+/** The proxies already reported. A proxy sends one id on every connect of its process. */
+const proxiesSeen = new Set();
 /** Set when the daemon starts, so the FIRST connect can report how long Reticle sat unused. */
 let daemonStartedAt;
 export function markDaemonStart(now) {
     daemonStartedAt = now;
     connectsSeen = 0;
+    proxiesSeen.clear();
 }
 /**
  * Report one client attaching, BY NAME. Best-effort; a metric must never affect whether a client
@@ -32,12 +35,24 @@ export function markDaemonStart(now) {
  * An unnamed call reports NOTHING. A stream that opens and never completes a handshake is a probe,
  * not a client attaching, and counting it was what put an unattributable row exactly where the name
  * belonged.
+ *
+ * ONCE per proxy. `attachId` is the proxy's own id, and the proxy sends the same id each time it
+ * reconnects. A reconnect of a known proxy is the same agent coming back, and an event for each one
+ * made this the largest event kind with no new fact in it. The proxy counts its own drops on
+ * `mcp_proxy_exited`. An older proxy sends no id, so each of its connects still reports.
  */
 /** `connection.client`'s wire cap. */
 const MAX_CLIENT_NAME = 64;
-export function reportMcpConnected(client, now = () => Date.now()) {
-    if (client === undefined)
+export function reportMcpConnected(client, attachId, now = () => Date.now()) {
+    if (client === undefined) {
         return;
+    }
+    if (attachId !== undefined) {
+        if (proxiesSeen.has(attachId)) {
+            return;
+        }
+        proxiesSeen.add(attachId);
+    }
     try {
         const reconnect = connectsSeen > 0;
         connectsSeen += 1;
@@ -56,6 +71,9 @@ export function reportMcpConnected(client, now = () => Date.now()) {
                 // `app_instrumented` sets, never a second counter, so the two halves of the funnel cannot
                 // disagree about one daemon run.
                 appConnected: appEverConnected(),
+                // The proxy that attached. Its `mcp_connection_lost` and `mcp_proxy_exited` rows carry the
+                // same id and no `sessionId`, so this row is how they join this daemon run.
+                ...(attachId === undefined ? {} : { proxyId: attachId }),
             },
         });
     }
@@ -66,5 +84,6 @@ export function reportMcpConnected(client, now = () => Date.now()) {
 /** Tests only. */
 export function resetMcpConnections() {
     connectsSeen = 0;
+    proxiesSeen.clear();
     daemonStartedAt = undefined;
 }

package/dist/telemetry/onboarding-firsts.d.ts

@@ -1,4 +1,4 @@
-import { type OnboardingStep } from '@reticlehq/core';
+import { NextStepOffered, type OnboardingStep } from '@reticlehq/core';
 /** Report `step` once per process, and only if this machine + project has never reported it. */
 export declare function reportFirstStep(step: OnboardingStep): void;
 /** A successful page read. The dispatcher calls this after excluding refusals and pauses. */
@@ -44,6 +44,11 @@ export declare function noteDriven(): void;
  * took: it fired on every verdict, so a busy session put hundreds of first-run steps in the funnel.
  */
 export declare function noteVerdictProduced(elapsedMs: number): void;
+export declare function noteNextStepOffered(offered: NextStepOffered, wired: () => boolean): void;
+/** Called on every agent call, before its handler runs. Closes an open offer, once. */
+export declare function noteNextCall(tool: string, args: Record<string, unknown>): void;
+/** Tests only: forget an open offer. */
+export declare function resetNextStepOffered(): void;
 /** Arm again for the next daemon run — the tests' seam, mirroring resetAppInstrumented. */
 export declare function resetOnboardingFirsts(): void;
 /**

package/dist/telemetry/onboarding-firsts.js

@@ -1,4 +1,4 @@
-import { ActionType, OnboardingPhase, OnboardingStepStatus, ReticleTool, } from '@reticlehq/core';
+import { ActionType, NextStepOffered, OnboardingPhase, OnboardingStepStatus, ReticleTool, } from '@reticlehq/core';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -124,6 +124,46 @@ export function noteVerdictProduced(elapsedMs) {
         elapsedMs: Math.max(0, Math.round(elapsedMs)),
     });
 }
+// ponytail: one pending offer per daemon, not per agent. Two agents in two unwired projects at the
+// same moment can close each other's offer. Key it by attach id if the data shows that case.
+let pending;
+const STEP = 'next_step_offered';
+const ACQUIRE = 'acquire';
+export function noteNextStepOffered(offered, wired) {
+    pending = { offered, wired };
+    void reportOnboardingStep({
+        phase: OnboardingPhase.FIRST_RUN,
+        step: STEP,
+        status: OnboardingStepStatus.STARTED,
+        offered,
+    });
+}
+/** Called on every agent call, before its handler runs. Closes an open offer, once. */
+export function noteNextCall(tool, args) {
+    const offer = pending;
+    if (offer === undefined) {
+        return;
+    }
+    pending = undefined;
+    void reportOnboardingStep({
+        phase: OnboardingPhase.FIRST_RUN,
+        step: STEP,
+        status: OnboardingStepStatus.COMPLETED,
+        offered: offer.offered,
+        nextFollowed: followed(offer, tool, args),
+    });
+}
+function followed(offer, tool, args) {
+    if (NextStepOffered.LEASE === offer.offered) {
+        return (ReticleTool.LEASE_ACQUIRE === tool ||
+            (ReticleTool.LEASE === tool && ACQUIRE === args['action']));
+    }
+    return offer.wired();
+}
+/** Tests only: forget an open offer. */
+export function resetNextStepOffered() {
+    pending = undefined;
+}
 /** Looking: the tools that read the page without changing it. */
 const LOOK_TOOLS = new Set([
     ReticleTool.SNAPSHOT,

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

@@ -1,3 +1,45 @@
+/**
+ * The MCP proxy's session rollup.
+ *
+ * POST socket failures (`ENOBUFS`, `EMFILE`, `ECONNREFUSED` before any bytes were sent) happen in
+ * this process, not the daemon's. `tool_refused` never fires (the handler never ran) and
+ * `mcp_connection_lost` never fires (the SSE stream is fine). Counts live on SessionMetrics here
+ * and leave as one `session_progress` — an existing kind, omitted when nothing happened.
+ *
+ * The send is awaited. Fire-and-forget microseconds before `process.exit` is how `daemon_stopped`
+ * never arrived: the POST was killed every time and nothing threw.
+ */
+import { type ProxyExitReason, type WakeRefusalPresence } from '@reticlehq/core/telemetry';
 import { type SessionMetrics } from './session-metrics.js';
 import { type Telemetry } from './telemetry.js';
 export declare function flushProxySessionMetrics(telemetry?: Telemetry, metrics?: SessionMetrics): Promise<void>;
+/**
+ * This proxy process's id. The proxy sends it to the daemon on every connect, and the daemon puts
+ * it on `mcp_client_connected`. The proxy's own events carry it too, so an outage or an exit joins
+ * the daemon run it served. A random UUID for each process: it names nothing on the machine.
+ */
+export declare const PROXY_ID: `${string}-${string}-${string}-${string}-${string}`;
+/** The proxy lost its daemon stream. */
+export declare function noteProxyDrop(): void;
+/** The client sent a `tools/call` through the proxy. */
+export declare function noteProxyToolCall(): void;
+/** Reset between tests. A real process reports each of these at most once. */
+export declare function resetProxyExitReporting(): void;
+/**
+ * Send `mcp_proxy_exited`, once per process. Awaited by the caller before it exits, because a send
+ * that is not awaited before `process.exit` does not arrive. `emit` bounds the send with its own
+ * timeout, and it never throws.
+ *
+ * Sent even when every count is zero: a proxy that left with nothing else to say is the case that
+ * was invisible.
+ */
+export declare function reportProxyExited(reason: ProxyExitReason, telemetry?: Telemetry, uptimeMs?: number): Promise<void>;
+/** Everything the proxy sends on its way out. Awaited, then the caller exits. */
+export declare function flushProxyExit(reason: ProxyExitReason): Promise<void>;
+/** Send `daemon_died_unclean`. Fire-and-forget is fine for callers: the process lives on. */
+export declare function reportDaemonDiedUnclean(ageMs: number, telemetry?: Telemetry): Promise<void>;
+/**
+ * Send `wake_refused`, once per process. A dormant proxy refuses again on every client request, and
+ * one event per request would count the client's retries, not the refusal.
+ */
+export declare function reportWakeRefused(presence: WakeRefusalPresence, telemetry?: Telemetry): Promise<void>;

package/dist/telemetry/proxy-telemetry.js

@@ -9,7 +9,8 @@
  * The send is awaited. Fire-and-forget microseconds before `process.exit` is how `daemon_stopped`
  * never arrived: the POST was killed every time and nothing threw.
  */
-import { TelemetryEventKind } from '@reticlehq/core/telemetry';
+import { TelemetryEventKind, } from '@reticlehq/core/telemetry';
+import { randomUUID } from 'node:crypto';
 import { getSessionMetrics } from './session-metrics.js';
 import { getTelemetry } from './telemetry.js';
 export async function flushProxySessionMetrics(telemetry = getTelemetry(), metrics = getSessionMetrics()) {
@@ -22,3 +23,71 @@ export async function flushProxySessionMetrics(telemetry = getTelemetry(), metri
         session: metrics.summarize(false),
     });
 }
+/**
+ * This proxy process's id. The proxy sends it to the daemon on every connect, and the daemon puts
+ * it on `mcp_client_connected`. The proxy's own events carry it too, so an outage or an exit joins
+ * the daemon run it served. A random UUID for each process: it names nothing on the machine.
+ */
+export const PROXY_ID = randomUUID();
+/** What this proxy process saw in its life, for `mcp_proxy_exited`. One proxy per process. */
+let drops = 0;
+let toolCalls = 0;
+let exitReported = false;
+let wakeRefusalReported = false;
+/** The proxy lost its daemon stream. */
+export function noteProxyDrop() {
+    drops += 1;
+}
+/** The client sent a `tools/call` through the proxy. */
+export function noteProxyToolCall() {
+    toolCalls += 1;
+}
+/** Reset between tests. A real process reports each of these at most once. */
+export function resetProxyExitReporting() {
+    drops = 0;
+    toolCalls = 0;
+    exitReported = false;
+    wakeRefusalReported = false;
+}
+/**
+ * Send `mcp_proxy_exited`, once per process. Awaited by the caller before it exits, because a send
+ * that is not awaited before `process.exit` does not arrive. `emit` bounds the send with its own
+ * timeout, and it never throws.
+ *
+ * Sent even when every count is zero: a proxy that left with nothing else to say is the case that
+ * was invisible.
+ */
+export async function reportProxyExited(reason, telemetry = getTelemetry(), 
+// The process clock, read at this boundary: the proxy's uptime IS the process's.
+uptimeMs = Math.round(process.uptime() * 1000)) {
+    if (exitReported) {
+        return;
+    }
+    exitReported = true;
+    await telemetry.emit(TelemetryEventKind.MCP_PROXY_EXITED, {
+        proxyExit: { reason, uptimeMs, drops, toolCalls, proxyId: PROXY_ID },
+    });
+}
+/** Everything the proxy sends on its way out. Awaited, then the caller exits. */
+export async function flushProxyExit(reason) {
+    await Promise.allSettled([flushProxySessionMetrics(), reportProxyExited(reason)]);
+}
+/** Send `daemon_died_unclean`. Fire-and-forget is fine for callers: the process lives on. */
+export async function reportDaemonDiedUnclean(ageMs, telemetry = getTelemetry()) {
+    await telemetry.emit(TelemetryEventKind.DAEMON_DIED_UNCLEAN, {
+        daemonDeath: { ageMs: Math.max(0, Math.round(ageMs)) },
+    });
+}
+/**
+ * Send `wake_refused`, once per process. A dormant proxy refuses again on every client request, and
+ * one event per request would count the client's retries, not the refusal.
+ */
+export async function reportWakeRefused(presence, telemetry = getTelemetry()) {
+    if (wakeRefusalReported) {
+        return;
+    }
+    wakeRefusalReported = true;
+    await telemetry.emit(TelemetryEventKind.WAKE_REFUSED, {
+        wakeRefusal: { presence },
+    });
+}

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

@@ -108,7 +108,7 @@ export declare class SessionMetrics {
      * Zero of these at shutdown means the daemon ran and no app ever connected — a broken install.
      * Non-zero with no tool calls is the opposite problem. See SessionSummary.appConnects.
      */
-    recordAppConnected(): void;
+    recordAppConnected(sdkVersion?: string): void;
     /** One action driven at the page. Settled by the next verdict; see #unsettledActions. */
     recordAction(): void;
     recordVerification(): void;
@@ -146,8 +146,6 @@ export declare class SessionMetrics {
     recordFeedbackPrompt(): void;
     /** An agent was shown a platform or Harness advisory. */
     recordNudge(kind: AgentNudgeKind): void;
-    /** A Harness drive was refused because the app's coverage is below the gate. */
-    recordHarnessRefused(percent: number): void;
     /** Which tool surface was advertised to agents this session. */
     recordSurface(surface: string): void;
     /**