@reticlehq/server 3.8.2 → 3.10.0

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

@@ -15,7 +15,7 @@
  * URLs, no error messages — the accumulator has no way to hold them, which is a stronger guarantee
  * than a rule saying it shouldn't.
  */
-import { BrowserLaunchKind, type AgentNudgeKind, type ConnectFailure, type SessionSummary } from '@reticlehq/core/telemetry';
+import { BrowserLaunchKind, ConnectFailure, type AgentNudgeKind, type SessionSummary } from '@reticlehq/core/telemetry';
 import type { HudUseData } from '@reticlehq/core';
 import { type HudSignals } from './hud-metrics.js';
 /**

package/dist/telemetry/session-metrics.js

@@ -15,12 +15,13 @@
  * URLs, no error messages — the accumulator has no way to hold them, which is a stronger guarantee
  * than a rule saying it shouldn't.
  */
-import { BrowserLaunchKind, } from '@reticlehq/core/telemetry';
+import { BrowserLaunchKind, ConnectFailure, OnboardingPhase, OnboardingStop, } from '@reticlehq/core/telemetry';
 import { errorSkeleton, fingerprintError } from './error-fingerprint.js';
 import { describeToolParams } from './argument-shape.js';
 import { machineSnapshot } from './machine-snapshot.js';
 import { classifyError } from './error-class.js';
 import { HudMetrics } from './hud-metrics.js';
+import { reportOnboardingStop } from './onboarding-funnel.js';
 import { releaseVersionOf } from '../command/update/version-seen.js';
 /** Cap the distinct error shapes held in memory — a pathological loop must not grow unbounded. */
 const MAX_ERROR_KINDS = 40;
@@ -58,6 +59,12 @@ const BREADCRUMB_LENGTH = 12;
  * never fires for the sessions that need it most.
  */
 const UNVERIFIED_ACTION_NUDGE_AT = 3;
+/** The launch failures that leave no browser to drive: a stop on the path to a first verdict. */
+const CHROMIUM_UNAVAILABLE = new Set([
+    ConnectFailure.CHROMIUM_MISSING,
+    ConnectFailure.PLAYWRIGHT_MISSING,
+]);
+const DRIVEN_STEP = 'driven';
 /**
  * Mutable counters for one daemon lifetime. A plain class, not a store: it is process-local, it never
  * persists, and it dies with the daemon.
@@ -187,10 +194,12 @@ export class SessionMetrics {
     }
     /** A tab went into the background (true) or came back (false): its HUD time pauses meanwhile. */
     setHudTabHidden(tab, hidden) {
-        if (hidden)
+        if (hidden) {
             this.#hud.hide(tab);
-        else
+        }
+        else {
             this.#hud.show(tab);
+        }
     }
     /** A tab went away: its HUD stops accruing time. */
     closeHudTab(tab) {
@@ -204,12 +213,14 @@ export class SessionMetrics {
     startToolCall(tool, args) {
         this.recordToolCall(tool, args);
         this.#concurrent += 1;
-        if (this.#concurrent > this.#peakConcurrent)
+        if (this.#concurrent > this.#peakConcurrent) {
             this.#peakConcurrent = this.#concurrent;
+        }
         let settled = false;
         return (durationMs) => {
-            if (settled)
-                return; // a double-settle would corrupt the concurrency count
+            if (settled) {
+                return;
+            } // a double-settle would corrupt the concurrency count
             settled = true;
             this.#concurrent = Math.max(0, this.#concurrent - 1);
             this.#busyMs += durationMs;
@@ -243,8 +254,9 @@ export class SessionMetrics {
      */
     recordUnknownTool(name) {
         this.#unknownToolCalls += 1;
-        if (name === undefined || 0 === name.length)
+        if (name === undefined || 0 === name.length) {
             return;
+        }
         const key = name.slice(0, 64);
         const seen = this.#unknownTools.get(key);
         if (seen !== undefined) {
@@ -253,8 +265,9 @@ export class SessionMetrics {
         }
         // Stop growing once full: a pathological loop must not balloon the payload. The head is what
         // gets built; the tail is noise.
-        if (this.#unknownTools.size >= MAX_ERROR_KINDS)
+        if (this.#unknownTools.size >= MAX_ERROR_KINDS) {
             return;
+        }
         this.#unknownTools.set(key, 1);
     }
     recordToolCall(tool, args) {
@@ -269,8 +282,9 @@ export class SessionMetrics {
         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.has(tool) || this.#repeatRuns.size < MAX_REPEAT_TOOLS)) {
                 this.#repeatRuns.set(tool, this.#currentRun);
+            }
         }
         this.#toolCalls += 1;
         this.#lifetimeToolCalls += 1;
@@ -280,23 +294,27 @@ export class SessionMetrics {
         bump(this.#toolCounts, tool);
         this.#inFlight = tool;
         this.#breadcrumb.push(tool);
-        if (this.#breadcrumb.length > BREADCRUMB_LENGTH)
+        if (this.#breadcrumb.length > BREADCRUMB_LENGTH) {
             this.#breadcrumb.shift();
-        if (args === undefined)
+        }
+        if (args === undefined) {
             return;
+        }
         // Which PARAMETERS get used, per tool — names only (plus a short allowlist of our own enums).
         // Bounded by our own schemas: a tool has a fixed handful of declared parameters, so this map
         // cannot grow with traffic the way a value-carrying one would.
         let perTool = this.#toolParams.get(tool);
         if (perTool === undefined) {
-            if (this.#toolParams.size >= MAX_PARAM_TOOLS)
+            if (this.#toolParams.size >= MAX_PARAM_TOOLS) {
                 return;
+            }
             perTool = new Map();
             this.#toolParams.set(tool, perTool);
         }
         for (const param of describeToolParams(args)) {
-            if (perTool.size < MAX_PARAMS_PER_TOOL || perTool.has(param))
+            if (perTool.size < MAX_PARAMS_PER_TOOL || perTool.has(param)) {
                 bump(perTool, param);
+            }
         }
     }
     /**
@@ -310,8 +328,9 @@ export class SessionMetrics {
         // indistinguishable from the rest inside one `toolErrors` count.
         bump(this.#errorClasses, classifyError(message));
         this.#currentCallErrored = true;
-        if (NO_SESSION_ERROR.test(message))
+        if (NO_SESSION_ERROR.test(message)) {
             this.#noSessionErrors += 1;
+        }
         const fingerprint = fingerprintError(message);
         const existing = this.#errorKinds.get(fingerprint);
         if (existing !== undefined) {
@@ -319,8 +338,9 @@ export class SessionMetrics {
             return;
         }
         // Stop growing once the cap is hit; the tail is noise and the head is what gets fixed.
-        if (this.#errorKinds.size >= MAX_ERROR_KINDS)
+        if (this.#errorKinds.size >= MAX_ERROR_KINDS) {
             return;
+        }
         this.#errorKinds.set(fingerprint, {
             fingerprint,
             count: 1,
@@ -343,8 +363,9 @@ export class SessionMetrics {
             existing.count += 1;
             return;
         }
-        if (this.#sdkFailureKinds.size >= MAX_ERROR_KINDS)
+        if (this.#sdkFailureKinds.size >= MAX_ERROR_KINDS) {
             return;
+        }
         this.#sdkFailureKinds.set(fingerprint, {
             fingerprint,
             count: 1,
@@ -428,8 +449,9 @@ export class SessionMetrics {
     /** The 1-based occurrence of this finding in the session, or undefined past the cap. */
     recordBugOccurrence(fingerprint) {
         const seen = this.#bugOccurrences.get(fingerprint);
-        if (seen === undefined && this.#bugOccurrences.size >= MAX_BUG_FINGERPRINTS)
+        if (seen === undefined && this.#bugOccurrences.size >= MAX_BUG_FINGERPRINTS) {
             return undefined;
+        }
         const occurrence = (seen ?? 0) + 1;
         this.#bugOccurrences.set(fingerprint, occurrence);
         return occurrence;
@@ -437,8 +459,9 @@ export class SessionMetrics {
     recordBug(kind) {
         this.#bugsFound += 1;
         this.#lifetimeBugsFound += 1;
-        if (this.#bugKinds.size < MAX_ERROR_KINDS || this.#bugKinds.has(kind))
+        if (this.#bugKinds.size < MAX_ERROR_KINDS || this.#bugKinds.has(kind)) {
             bump(this.#bugKinds, kind);
+        }
         const first = !this.#seenBugKinds.has(kind);
         this.#seenBugKinds.add(kind);
         return first;
@@ -457,8 +480,9 @@ export class SessionMetrics {
         this.#connections.set(kind, stats);
         let settled = false;
         return (failure) => {
-            if (settled)
+            if (settled) {
                 return;
+            }
             settled = true;
             if (failure === undefined) {
                 stats.successes += 1;
@@ -466,12 +490,21 @@ export class SessionMetrics {
             }
             stats.failures ??= {};
             stats.failures[failure] = (stats.failures[failure] ?? 0) + 1;
+            if (CHROMIUM_UNAVAILABLE.has(failure)) {
+                reportOnboardingStop({
+                    phase: OnboardingPhase.FIRST_RUN,
+                    step: DRIVEN_STEP,
+                    reason: failure,
+                    stop: OnboardingStop.CHROMIUM_UNAVAILABLE,
+                });
+            }
         };
     }
     recordClient(name, version) {
         const key = name.slice(0, 64);
-        if (this.#clients.size < MAX_CLIENTS)
+        if (this.#clients.size < MAX_CLIENTS) {
             this.#clients.add(key);
+        }
         // The version was already in the handshake and was being dropped. A regression in agent
         // behaviour is usually a client version, and without this it is unattributable.
         if (version !== undefined && '' !== version && this.#clientVersions.size < MAX_CLIENTS) {
@@ -511,8 +544,9 @@ export class SessionMetrics {
     summarize(final, exit) {
         // The last call has no successor to resolve it, so resolve it here. Only on a FINAL summary:
         // a periodic flush is not the end of anything and would resolve a call still in flight.
-        if (final)
+        if (final) {
             this.#resolveRecovery();
+        }
         const machine = machineSnapshot();
         // EVERY event reports its own window, the final one included: summing a session's
         // `session_progress` + `daemon_stopped` rows is then its total. The final event used to swap in
@@ -612,10 +646,12 @@ export class SessionMetrics {
      */
     #resolveRecovery() {
         if (this.#priorCallErrored) {
-            if (this.#currentCallErrored)
+            if (this.#currentCallErrored) {
                 this.#errorsRepeated += 1;
-            else
+            }
+            else {
                 this.#errorsRecovered += 1;
+            }
         }
         this.#priorCallErrored = this.#currentCallErrored;
         this.#currentCallErrored = false;
@@ -625,14 +661,18 @@ export class SessionMetrics {
      * that left explains everything after it, and a verdict settles whatever preceded it.
      */
     #endReason() {
-        if (0 === this.#lifetimeToolCalls)
+        if (0 === this.#lifetimeToolCalls) {
             return 'never_used';
-        if (this.#clientLeft)
+        }
+        if (this.#clientLeft) {
             return 'client_left';
-        if (this.#unsettledActions > 0)
+        }
+        if (this.#unsettledActions > 0) {
             return 'abandoned';
-        if (this.#lifetimeVerifications > 0)
+        }
+        if (this.#lifetimeVerifications > 0) {
             return 'verified';
+        }
         return 'explored';
     }
     /**

package/dist/telemetry/telemetry.d.ts

@@ -1,4 +1,4 @@
-import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type OnboardingStep, type InstallSource, type McpConnection, type McpOutage, type DaemonDeath, type ProxyExit, type WakeRefusal, type DaemonSpawnMethod, type ToolRefusal, type AppInstrumentation, type HarnessRun, type HudEvent, type PlatformLink, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
+import { TelemetryEventKind, ProjectIdSource, type Crash, type Feedback, type Identity, type BugFound, type InitOutcome, type OnboardingStep, type InstallSource, type McpConnection, type McpOutage, type DaemonDeath, type GateCompleted, type ProxyExit, type WakeRefusal, type DaemonSpawnMethod, type ToolRefusal, type AppInstrumentation, type HarnessRun, type HudEvent, type PlatformLink, type ProjectProfile, type SessionSummary, type TelemetryActor, type Verification, type VersionChange } from '@reticlehq/core/telemetry';
 /**
  * Presence of this file marks the MACHINE as the Reticle team's own: every event carries
  * `internal: true`. The persistent twin of `RETICLE_INTERNAL=1`, for a dev machine where setting a
@@ -113,6 +113,8 @@ export interface TelemetryExtra {
     daemonDeath?: DaemonDeath;
     /** `wake_refused`: what held the port. */
     wakeRefusal?: WakeRefusal;
+    /** `gate_completed`: how `reticle gate` ended. */
+    gate?: GateCompleted;
     /** `daemon_started`: how the parent started the daemon. */
     spawnMethod?: DaemonSpawnMethod;
     /**

package/dist/telemetry/telemetry.js

@@ -138,20 +138,24 @@ const Env = {
 };
 const isDisabled = (env, cwd = process.cwd()) => {
     const off = new Set(['0', 'false', 'off', 'no']);
-    if (off.has((env[Env.DISABLE] ?? '').toLowerCase()))
+    if (off.has((env[Env.DISABLE] ?? '').toLowerCase())) {
         return true;
+    }
     // Recording to a local file is not "phoning home", and the guards below exist to stop us phoning
     // home. Chief among them is the source-checkout rule — which is exactly where a release sweep is
     // driven from, so a sink that inherited it would record nothing and look like it had worked.
-    if ((env[Env.FILE] ?? '') !== '')
+    if ((env[Env.FILE] ?? '') !== '') {
         return false;
-    if (env[Env.VITEST] !== undefined)
-        return true; // a test run is not a user
+    }
+    if (env[Env.VITEST] !== undefined) {
+        return true;
+    } // a test run is not a user
     // Developing Reticle is not using Reticle. The `.env` carrying RETICLE_TELEMETRY=0 is gitignored,
     // so it only exists on the machine that made it — a fresh clone would phone home on a
     // contributor's first `reticle serve`. The repo marker is committed, so this guarantee travels.
-    if (isReticleSourceCheckout(cwd))
+    if (isReticleSourceCheckout(cwd)) {
         return true;
+    }
     const dnt = env[Env.DO_NOT_TRACK];
     return 'string' === typeof dnt && dnt !== '' && dnt !== '0';
 };
@@ -191,19 +195,22 @@ const readIdFile = (file) => {
 export const resolveIdentity = (file = ID_FILE) => {
     try {
         const existing = readIdFile(file);
-        if (existing !== undefined)
+        if (existing !== undefined) {
             return { anonymousId: existing, firstRun: false };
+        }
         const id = randomUUID();
         mkdirSync(dirname(file), { recursive: true });
         try {
             writeFileSync(file, id, { encoding: 'utf8', flag: 'wx' });
         }
         catch (error) {
-            if (!isAlreadyThere(error))
+            if (!isAlreadyThere(error)) {
                 throw error;
+            }
             const raced = readIdFile(file);
-            if (raced !== undefined)
+            if (raced !== undefined) {
                 return { anonymousId: raced, firstRun: false };
+            }
             // An empty file left by a crash: replace it, as the old code did.
             writeFileSync(file, id, 'utf8');
         }
@@ -235,30 +242,40 @@ export const projectFingerprint = (cwd) => {
     // stable across every directory inside one machine's checkout, a package.json root is the same for
     // a non-git project — and the raw cwd is stable across nothing, which is why it is last. See
     // `project-identity.test.ts` for what a wrong order costs.
-    const { key, source } = origin !== undefined
-        ? { key: origin, source: ProjectIdSource.GIT_ORIGIN }
-        : root !== undefined
-            ? { key: root, source: ProjectIdSource.GIT_ROOT }
-            : packageRoot(cwd) !== null
-                ? { key: packageRoot(cwd) ?? cwd, source: ProjectIdSource.PACKAGE_ROOT }
-                : { key: cwd, source: ProjectIdSource.CWD };
+    const { key, source } = projectKey(cwd, origin, root);
     return {
         projectId: createHash('sha256').update(key).digest('hex').slice(0, 32),
         // Reported alongside so the analytics knows whether this id is comparable to another machine's.
         source,
     };
 };
+/** The most stable key this directory has, and what it came from. */
+function projectKey(cwd, origin, root) {
+    if (origin !== undefined) {
+        return { key: origin, source: ProjectIdSource.GIT_ORIGIN };
+    }
+    if (root !== undefined) {
+        return { key: root, source: ProjectIdSource.GIT_ROOT };
+    }
+    const pkg = packageRoot(cwd);
+    if (pkg !== null) {
+        return { key: pkg, source: ProjectIdSource.PACKAGE_ROOT };
+    }
+    return { key: cwd, source: ProjectIdSource.CWD };
+}
 /** Nearest ancestor holding a package.json — the project boundary when there is no git. */
 const packageRoot = (cwd) => {
     let dir = cwd;
     // Same bound as the git walk: deep monorepos are well inside 20, and an unbounded loop on a
     // pathological path would hang the CLI's startup.
     for (let depth = 0; depth < 20; depth += 1) {
-        if (existsSync(join(dir, 'package.json')))
+        if (existsSync(join(dir, 'package.json'))) {
             return dir;
+        }
         const parent = dirname(dir);
-        if (parent === dir)
+        if (parent === dir) {
             return null;
+        }
         dir = parent;
     }
     return null;
@@ -329,18 +346,21 @@ export const createTelemetry = (opts) => {
     const cwd = opts.cwd ?? process.cwd();
     // A source checkout silences metrics but must not silence FEEDBACK — see onlyBlockedBySourceCheckout.
     const feedbackOnly = onlyBlockedBySourceCheckout(env, cwd);
-    if (isDisabled(env, cwd) && !feedbackOnly)
+    if (isDisabled(env, cwd) && !feedbackOnly) {
         return NOOP;
+    }
     try {
-        if (existsSync(join(reticleDir, OPT_OUT_FILE_NAME)))
-            return NOOP; // the persistent `reticle telemetry disable` opt-out
+        if (existsSync(join(reticleDir, OPT_OUT_FILE_NAME))) {
+            return NOOP;
+        } // the persistent `reticle telemetry disable` opt-out
     }
     catch {
         /* unreadable home dir — fall through; the env-var opt-outs above still apply */
     }
     const apiKey = env[Env.KEY] ?? POSTHOG_KEY;
-    if ('' === apiKey)
-        return NOOP; // no key baked in (dev/test build) — nowhere to send, stay silent
+    if ('' === apiKey) {
+        return NOOP;
+    } // no key baked in (dev/test build) — nowhere to send, stay silent
     const now = opts.now ?? (() => Date.now());
     const doFetch = opts.fetchImpl ?? fetch;
     const url = `${(env[Env.URL] ?? DEFAULT_URL).replace(/\/+$/, '')}${TELEMETRY_PATH}`;
@@ -375,8 +395,9 @@ export const createTelemetry = (opts) => {
     // How this process was launched: a property of the process, so read once. Only the bucket leaves.
     const launch = launchMethodOf(process.argv[1]);
     const home = opts.home ?? homedir();
-    if (!feedbackOnly)
+    if (!feedbackOnly) {
         showNoticeOnce(reticleDir);
+    }
     const spawnDetached = opts.spawnImpl ??
         ((command, args, input) => {
             const bodyFile = join(tmpdir(), `reticle-telemetry-${randomUUID()}.json`);
@@ -397,8 +418,9 @@ export const createTelemetry = (opts) => {
     const emit = async (kind, extra) => {
         // In a Reticle source checkout the emitter carries FEEDBACK and nothing else: somebody typed the
         // feedback, and no metric is worth phoning home from a contributor's clone.
-        if (feedbackOnly && TelemetryEventKind.FEEDBACK_SUBMITTED !== kind)
+        if (feedbackOnly && TelemetryEventKind.FEEDBACK_SUBMITTED !== kind) {
             return false;
+        }
         // One clock read for the whole event: `ts` and the licence check must agree, and two calls to
         // now() can straddle an expiry.
         const eventTs = now();
@@ -470,6 +492,7 @@ export const createTelemetry = (opts) => {
             ...(extra?.proxyExit !== undefined ? { proxyExit: extra.proxyExit } : {}),
             ...(extra?.daemonDeath !== undefined ? { daemonDeath: extra.daemonDeath } : {}),
             ...(extra?.wakeRefusal !== undefined ? { wakeRefusal: extra.wakeRefusal } : {}),
+            ...(extra?.gate !== undefined ? { gate: extra.gate } : {}),
             // A SCALAR: the event build and the wire schema, no `blocks` entry.
             ...(extra?.spawnMethod !== undefined ? { spawnMethod: extra.spawnMethod } : {}),
         };
@@ -484,7 +507,7 @@ export const createTelemetry = (opts) => {
         // PostHog filters and breakdowns operate on top-level properties, so a nested `feedback.stack`
         // would be invisible to the exact "which stacks report the most bugs" question this exists to
         // answer. One prefix keeps them grouped in the UI without a nested path.
-        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, onboarding, bug, refusal, outage, instrumentation, hud, link, harness, proxyExit, daemonDeath, wakeRefusal, ...rest } = event;
+        const { anonymousId: distinctId, event: name, ts, sessionId: eventSessionId, feedback, session, project, verification, versionChange, crash, identity, connection, init, onboarding, bug, refusal, outage, instrumentation, hud, link, harness, proxyExit, daemonDeath, wakeRefusal, gate, ...rest } = event;
         // `$session_id` is PostHog's OWN session property, so sending ours under that name lights up
         // its built-in session views and funnels for free rather than requiring custom HogQL everywhere.
         // `sessionId` rides only on events that happened inside a daemon run. A one-shot CLI command
@@ -522,6 +545,7 @@ export const createTelemetry = (opts) => {
             proxyExit,
             daemonDeath,
             wakeRefusal,
+            gate,
         };
         for (const [prefix, block] of Object.entries(blocks)) {
             for (const [key, value] of Object.entries(block ?? {})) {
@@ -583,8 +607,9 @@ export const createTelemetry = (opts) => {
                     return response.ok !== false;
                 }
                 catch (error) {
-                    if (attempt === attempts - 1)
+                    if (attempt === attempts - 1) {
                         throw error;
+                    }
                 }
             }
             return false;
@@ -602,10 +627,17 @@ export const createTelemetry = (opts) => {
  */
 let invalidDropped = 0;
 export const droppedInvalidEvents = () => invalidDropped;
-/** `RETICLE_INTERNAL=1`, or the machine-wide marker file. Unreadable home → not internal. */
+/** The values of `RETICLE_INTERNAL` that mark a run, after trim and lower case. Anything else is not. */
+const INTERNAL_ON = new Set(['1', 'true', 'yes', 'on']);
+/**
+ * The one decision for the `internal` field on every event: `RETICLE_INTERNAL` set to an "on" value,
+ * or the machine-wide marker file. An explicit signal only, never read from a name, email or path.
+ * Unreadable home → not internal.
+ */
 const isInternal = (env, dir) => {
-    if ('1' === env[Env.INTERNAL] || 'true' === env[Env.INTERNAL])
+    if (INTERNAL_ON.has((env[Env.INTERNAL] ?? '').trim().toLowerCase())) {
         return true;
+    }
     try {
         return existsSync(join(dir, INTERNAL_MARKER_FILE));
     }

package/dist/telemetry/tool-refused.d.ts

@@ -10,12 +10,15 @@
  * Emitted from `runTool`, which is the one place both dispatch paths cross, so a tool added later is
  * covered without anybody remembering to cover it.
  */
-import { RefusalReason, type NoSessionReason } from '@reticlehq/core/telemetry';
+import { RefusalReason, type NoSessionReason, type RefusalDetail } from '@reticlehq/core/telemetry';
 /** Record the branch code for the no-session error being thrown right now. */
 export declare function notePendingNoSessionReason(reason: NoSessionReason | undefined): void;
 /** A call that was served. Breaks the retry chain: what follows it is not a retry of anything. */
 export declare function noteToolServed(): void;
-/** One refused call, reported with its cause and whether it was itself a retry. */
-export declare function reportToolRefused(tool: string, reason: RefusalReason): void;
+/**
+ * One refused call, reported with its cause, whether it was a retry, and the names of its arguments.
+ * `detail` is the cause inside `reason`, when the recovery table names one.
+ */
+export declare function reportToolRefused(tool: string, reason: RefusalReason, args?: Record<string, unknown>, detail?: RefusalDetail): void;
 /** Tests only — the counters are process-lifetime, so each case has to start from zero. */
 export declare function resetToolRefusals(): void;

package/dist/telemetry/tool-refused.js

@@ -11,6 +11,7 @@
  * covered without anybody remembering to cover it.
  */
 import { RefusalReason, TelemetryActor, TelemetryEventKind, } from '@reticlehq/core/telemetry';
+import { describeToolParams } from './argument-shape.js';
 import { getTelemetry } from './telemetry.js';
 /**
  * Refusal events one daemon run will send.
@@ -54,16 +55,22 @@ export function notePendingNoSessionReason(reason) {
 export function noteToolServed() {
     lastRefusedTool = undefined;
 }
-/** One refused call, reported with its cause and whether it was itself a retry. */
-export function reportToolRefused(tool, reason) {
+/** How many argument names one refusal carries. A call with more is malformed in its own way. */
+const MAX_REFUSAL_PARAMS = 16;
+/**
+ * One refused call, reported with its cause, whether it was a retry, and the names of its arguments.
+ * `detail` is the cause inside `reason`, when the recovery table names one.
+ */
+export function reportToolRefused(tool, reason, args = {}, detail) {
     const retried = lastRefusedTool === tool;
     lastRefusedTool = tool;
     // Read and clear whatever the throw left, whether or not this refusal can use it: a reason left
     // sitting would attach itself to an unrelated refusal later in the session.
     const noSessionReason = pendingNoSessionReason;
     pendingNoSessionReason = undefined;
-    if (sent >= MAX_REFUSALS_PER_SESSION)
+    if (sent >= MAX_REFUSALS_PER_SESSION) {
         return;
+    }
     sent += 1;
     void getTelemetry().emit(TelemetryEventKind.TOOL_REFUSED, {
         actor: TelemetryActor.AGENT,
@@ -71,11 +78,16 @@ export function reportToolRefused(tool, reason) {
             tool,
             reason,
             retried,
+            ...(() => {
+                const params = describeToolParams(args).slice(0, MAX_REFUSAL_PARAMS);
+                return 0 === params.length ? {} : { params };
+            })(),
             // Only where it means something. On any other refusal reason this field would be answering
             // a question nobody asked of it.
             ...(RefusalReason.NO_SESSION === reason && noSessionReason !== undefined
                 ? { noSessionReason }
                 : {}),
+            ...(detail === undefined ? {} : { detail }),
         },
     });
 }

package/docs/actions.mdx

@@ -22,13 +22,13 @@ Every action Reticle can perform takes the same shape: an element, an `action` n
 | `select` | `{ value }` | For `<select>` |
 | `check` / `uncheck` | none | Checkbox and radio, or a `role="checkbox"`/`role="switch"` element (fails if `aria-checked` does not change) |
 | `submit` | none | Submits the element's `<form>` |
-| `press` | `{ text, modifiers?, holdMs?, keys?, code? }` | `text` is the key **name**: `Escape`, `Tab`, `Enter`. `key` is an accepted alias. `modifiers` is an array of `Meta`, `Control`, `Shift`, `Alt`. `holdMs` holds the key down; `keys` holds several together; `code` names the physical key |
+| `press` | `{ text, modifiers?, holdMs?, keys?, code?, document? }` | `text` is the key **name**: `Escape`, `Tab`, `Enter`. `key` is an accepted alias. `document: true` sends any key to the focused element or the document with no `ref` (a canvas game reads WASD and Space from the page). `modifiers` is an array of `Meta`, `Control`, `Shift`, `Alt`. `holdMs` holds the key down; `keys` holds several together; `code` names the physical key |
 | `scrollIntoView` | none |  |
-| `scroll` | `{ dy?, dx?, fraction? }` | Scrolls the nearest scrollable container (or the page, with no `ref`) by `dy`/`dx` pixels, either direction. `fraction` (0 to 1) jumps to that point of the height. No args steps down most of a screen |
+| `scroll` | `{ dy?, dx?, fraction?, wheel? }` | Scrolls the nearest scrollable container (or the page, with no `ref`) by `dy`/`dx` pixels, either direction. `fraction` (0 to 1) jumps to that point of the height. `wheel: true` sends a cancelable `wheel` event and leaves the movement to the page, for apps that scroll from a wheel listener. No args steps down most of a screen |
 | `tap` | `{ holdMs? }` | A touch tap: pointer and touch events, then `click`. `holdMs` makes it a long press |
 | `zoom` | none | Page zoom. Refused inside the page, because CSS zoom changes how a page looks without changing its layout, and a passing check on it would be false |
 | `upload` | `{ content?, name?, type?, path? }` | Sets a file on `<input type="file">`. Inline bytes default to `"reticle test file"` / `"file.txt"` / `"text/plain"`. `path` reads a file from disk, scoped to the project root plus any opt-in directories listed in `.reticle.json` as `"uploadRoots": ["~/Downloads", "/Volumes/fixtures"]`. A refusal names every allowed root. |
-| `drag` | `{ toRef }` | Pointer-based drag (dnd-kit, react-beautiful-dnd) plus HTML5 DnD. `target` is an alias |
+| `drag` | `{ toRef, at?, to?, modifiers? }` | Pointer-based drag (dnd-kit, react-beautiful-dnd) plus HTML5 DnD. `target` is an alias. `modifiers` (for example `["Shift"]`) are held for the whole drag, so a canvas editor sees `shiftKey` on every pointer event |
 
 ### Arguments that are not actions
 

package/docs/agent-cheatsheet.md

@@ -126,7 +126,7 @@ Call an old name and you are told the new one. `reticle_tools` prints the live s
 
 Not on this surface at all, but one hop away: `reticle_run { tool, args }` calls any registered tool by name, advertised or not, and `reticle_tools { names: [...] }` loads its arguments. That reaches `reticle_capabilities` (the app's whole testable surface in one call), `reticle_domain` (learn the app + gaps), `reticle_run { tool: "reticle_baseline", args: { action: "diff" } }`, `reticle_project` (run history), `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock` and `reticle_clock`. A daemon started with `RETICLE_ADVERTISE_ALL_TOOLS=1` advertises some of these directly (`reticle_capabilities`, `reticle_screenshot`, `reticle_visual_diff`, `reticle_storage`, `reticle_network_mock`, `reticle_clock`, plus `reticle_record`, `reticle_flow_save`, `reticle_flow_replay`, `reticle_intent` and `reticle_context`); the rest stay behind `reticle_run`. It also switches to the unmerged spelling: `reticle_snapshot`/`reticle_query`/`reticle_inspect`/`reticle_state` replace `reticle_look`, `reticle_network`/`reticle_console` replace `reticle_observe { action }`, `reticle_wait_for` replaces `reticle_assert { action: "wait" }`, `reticle_sessions`/`reticle_feedback` replace `reticle_session` list/feedback, and `reticle_act_sequence` replaces `reticle_act { steps }`. Examples on this page use the default spelling.
 
-**What the wider surface adds, through `reticle_run` (a few are also advertised directly with `RETICLE_ADVERTISE_ALL_TOOLS=1`):** record/replay a journey (`reticle_run { tool: "reticle_record", args: { action: "start" } }/stop`, `reticle_replay`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_verify { action: "heal" }`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_explore` lists controls; `reticle_verify { action: "crawl" }` is now advertised directly, clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_look { action: "find" }` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, driven or leased), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session { action: "end" }` / `reticle_session { action: "resume" }` / `reticle_session { action: "messages" }`, and **`reticle_session { action: "review" }`** to drain + fix the bugs the human flagged from the panel).
+**What the wider surface adds, through `reticle_run` (a few are also advertised directly with `RETICLE_ADVERTISE_ALL_TOOLS=1`):** record/replay a journey (`reticle_run { tool: "reticle_record", args: { action: "start" } }/stop`, then `{ action: "replay" }`), persist a self-healing golden flow (`reticle_flow_save*` / `reticle_flow_replay` / `reticle_verify { action: "heal" }`), compile annotations (`reticle_annotate`), explore autonomously (`reticle_look { action: "page", mode: "interactive" }` lists controls; `reticle_verify { action: "crawl" }` is now advertised directly, clicks them all and reports anomalies, and is **destructive**), reveal a virtualized off-screen row (`reticle_scroll_to`, for when `reticle_look { action: "find" }` finds nothing because a windowed list hasn't rendered it yet), visual-check (`reticle_screenshot` / `reticle_visual_diff`, pinned with `reticle_viewport` for reproducible baselines), test error/edge states by stubbing the network (`reticle_network_mock`: 500 / offline / delay, or `forwardTo` another origin, driven or leased), control time for toasts/debounces/auto-dismiss (`reticle_clock { freeze | advanceMs | reset }`), or work with a human (`reticle_session { action: "end" }` / `reticle_session { action: "resume" }` / `reticle_session { action: "messages" }`, and **`reticle_session { action: "review" }`** to drain + fix the bugs the human flagged from the panel).
 
 ## flows vs baselines vs project.json (the persistence layers)
 

package/docs/architecture.md

@@ -115,14 +115,11 @@ This is plain, reviewable, version-controllable data, not a black box.
 
 ---
 
-## Open-core licensing (what's free, what's protected)
+## Licensing
 
-- The **protocol and the rules** (`open-verification`, `@reticlehq/core`, `@reticlehq/engine`) are **Apache-2.0**. The part that decides a verdict is the part a sceptical reader most wants to audit, so it is the part with no licence in the way.
-- The embeddable **SDK** (`@reticlehq/browser`, `@reticlehq/react` and the build adapters) is **Apache-2.0**, safe to ship inside your own app.
-- The **server / CLI** is under the **Functional Source License (FSL-1.1, Apache-2.0 future)**: source-available, converts to Apache-2.0 over time.
-- Enterprise-only features live behind a license gate and are clearly separated.
+Every npm package is **Apache-2.0**: the protocol and the rules (`open-verification`, `@reticlehq/core`, `@reticlehq/engine`), the embeddable SDK and its adapters, and the server, CLI, `init` and spec runner. The `reticle-tauri` crate is MIT.
 
-See [LICENSE](https://github.com/reticlehq/reticle/blob/main/LICENSE) and each package's own `LICENSE` file. The licensing _mechanism_ is open and inspectable; activation is offline (no phone-home).
+See [LICENSE](https://github.com/reticlehq/reticle/blob/main/LICENSE) and each package's own `LICENSE` file.
 
 ---