@reticlehq/server 2.2.1 → 2.3.0

package/dist/tools/coverage-tools.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { ReticleCommand, SnapshotMode } from '@reticlehq/core';
+import { ReticleTool } from './tool-names.js';
+import { asString } from './tools-helpers.js';
+import { commandOrThrow, sessionIdShape } from './tool-kit.js';
+/**
+ * `reticle_coverage` — which interactive controls this session has driven, and which it has not.
+ *
+ * Every other read here answers a question the agent already thought to ask, which bounds
+ * verification by the agent's imagination — the documented weak link. This answers the one question
+ * that tells the agent whether to STOP: an agent that exercised 4 of 17 controls and believes it
+ * verified the page is exactly the confident-and-wrong case Reticle exists to prevent, and nothing
+ * in the tool surface previously contradicted it.
+ *
+ * Note this is NOT the existing `blindSpots` coverage, which is about what the layer could not SEE
+ * (closed shadow roots, cross-origin frames). This is about what the agent did not TOUCH. Both are
+ * honesty signals; they answer different questions and neither substitutes for the other.
+ *
+ * Unadvertised by every profile: it costs nothing per turn and is reached through `reticle_run`.
+ */
+/** Refs as the snapshot tree spells them: `(ref=e12)`. The tree format is ours, so this is exact. */
+const REF_IN_TREE = /\(ref=(e\d+)\)/g;
+/** The label a tree line carries before its ref, e.g. `- button "Archive" (ref=e9)`. */
+const LINE_WITH_REF = /^\s*-\s*(.+?)\s*\(ref=(e\d+)\)/;
+/** Parse the interactive snapshot into {ref,label} controls, preserving document order. */
+export function parseControls(tree) {
+    const controls = [];
+    const seen = new Set();
+    for (const line of tree.split('\n')) {
+        const match = LINE_WITH_REF.exec(line);
+        if (match === null)
+            continue;
+        const [, label, ref] = match;
+        if (label === undefined || ref === undefined || seen.has(ref))
+            continue;
+        seen.add(ref);
+        controls.push({ ref, label });
+    }
+    // A ref can appear on a line this regex does not shape (nested formatting); count it regardless,
+    // because under-reporting the denominator would overstate coverage — the one direction that lies.
+    for (const match of tree.matchAll(REF_IN_TREE)) {
+        const ref = match[1];
+        if (ref !== undefined && !seen.has(ref)) {
+            seen.add(ref);
+            controls.push({ ref, label: '' });
+        }
+    }
+    return controls;
+}
+export const COVERAGE_TOOLS = [
+    {
+        name: ReticleTool.COVERAGE,
+        description: 'Which interactive controls you have driven this session, and which you have NOT. Returns { total, exercised, untouched:[{ref,label}], alsoDroveGone? } over the controls currently on the page. Use it to decide whether verification is finished: an untouched list that still holds the controls your change affects means you are not done. This is about what you did not TOUCH — distinct from the `coverage` field on an action result, which reports what the layer could not SEE.',
+        example: {},
+        inputSchema: { ...sessionIdShape },
+        outputSchema: {
+            total: z.number(),
+            exercised: z.number(),
+            untouched: z.array(z.object({ ref: z.string(), label: z.string() })),
+            alsoDroveGone: z
+                .number()
+                .optional()
+                .describe('Controls you drove that are no longer on the page — usually because the action SUCCEEDED and removed them (archive/delete/submit/navigate). Counted separately so `exercised: 0` never appears immediately after real work.'),
+        },
+        handler: async (deps, args) => {
+            const sessionId = asString(args['sessionId']);
+            const session = deps.sessions.resolve(sessionId);
+            // INTERACTIVE mode is already the "controls only" view, so the denominator is the page's own
+            // notion of what can be driven rather than a second, drifting definition maintained here.
+            const result = await commandOrThrow(deps, sessionId, ReticleCommand.SNAPSHOT, {
+                mode: SnapshotMode.INTERACTIVE,
+            });
+            const tree = asString(result['tree']) ?? '';
+            const acted = session.actedRefs();
+            const controls = parseControls(tree);
+            const present = new Set(controls.map((control) => control.ref));
+            const untouched = controls.filter((control) => !acted.has(control.ref));
+            // Drives that landed on controls no longer in the DOM. Without this the number is biased
+            // against the actions that WORKED: archive, delete, submit and navigate all remove their own
+            // control, so clicking one and asking again reported `exercised: 0` — measured on the Electron
+            // demo right after a successful archive. An agent reading "0" concludes it has done nothing
+            // and re-drives ground it already covered.
+            const drovenGone = [...acted].filter((ref) => !present.has(ref)).length;
+            return {
+                total: controls.length,
+                exercised: controls.length - untouched.length,
+                untouched,
+                ...(drovenGone > 0 ? { alsoDroveGone: drovenGone } : {}),
+            };
+        },
+    },
+];

package/dist/tools/dynamic-tools.d.ts

@@ -4,4 +4,3 @@ import type { ToolDef } from './tools.js';
  * `runTool` chokepoint as a direct call, so session-health splicing and every other invariant hold.
  */
 export declare function buildDynamicTools(allTools: ToolDef[]): ToolDef[];
-//# sourceMappingURL=dynamic-tools.d.ts.map

package/dist/tools/dynamic-tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { runTool } from './invoke-tool.js';
 import { ReticleTool } from './tool-names.js';
+import { getSessionMetrics } from '../telemetry/session-metrics.js';
 /**
  * On-demand tool loading for MCP — the answer to the per-turn tool-definition tax.
  *
@@ -43,7 +44,7 @@ export function buildDynamicTools(allTools) {
     const byName = new Map(allTools.map((t) => [t.name, t]));
     const reticleTools = {
         name: ReticleTool.TOOLS,
-        description: 'Discover Reticle tools on demand. Call with no arguments to list every tool (name + one-line summary); call with names:["reticle_network", …] to load full descriptions and parameters for specific tools. Then invoke them with reticle_run. This avoids paying for every tool definition on every turn. To make a verification REUSABLE (record once, replay free forever), the flow workflow lives here: reticle_record_start → act → reticle_flow_save → reticle_flow_verify (and reticle_flow_heal on drift). Load those names when you want to save or re-run a flow.',
+        description: 'Discover Reticle tools on demand. Call with no arguments to list every tool (name + one-line summary); call with names:["reticle_network", …] to load full descriptions and parameters for specific tools. Then invoke them with reticle_run. This avoids paying for every tool definition on every turn. To make a verification REUSABLE (record once, replay free forever), the flow workflow lives here: reticle_record{action:"start"} → act → reticle_flow_save → reticle_flow_verify (and reticle_flow_heal on drift). Load those names when you want to save or re-run a flow.',
         inputSchema: {
             names: z
                 .array(z.string())
@@ -84,8 +85,27 @@ export function buildDynamicTools(allTools) {
                 : {};
             const target = byName.get(name);
             if (target === undefined) {
+                // A non-zero count here means our advertised surface is confusing the agent — it reached for
+                // something it believed existed. That is a docs/naming defect, and it was invisible.
+                getSessionMetrics().recordUnknownTool();
                 return { error: `unknown tool '${name}'`, available: allTools.map((t) => t.name) };
             }
+            // The escape hatch is where a typo is MOST likely, because an unadvertised tool's parameters
+            // are not in front of the agent at all — and it is the one path the SDK's own validation never
+            // sees, since `reticle_run`'s own args (`tool`, `args`) are perfectly valid. Left unchecked,
+            // `reticle_run { tool: "reticle_clock", args: { action: "freeze" } }` returned
+            // `{"frozen":false}`: a well-formed answer to a question nobody asked.
+            const declared = new Set(Object.keys(target.inputSchema));
+            const unknown = Object.keys(callArgs).filter((key) => !declared.has(key));
+            if (unknown.length > 0) {
+                return {
+                    error: `unknown ${unknown.length === 1 ? 'parameter' : 'parameters'} for ${name}: ${unknown.join(', ')} — NOT applied, so any result would be an answer to a different question`,
+                    tool: name,
+                    params: paramInfo(target.inputSchema),
+                    ...(target.example === undefined ? {} : { example: target.example }),
+                    hint: 'fix the arguments and call reticle_run again',
+                };
+            }
             try {
                 return await runTool(target, deps, callArgs);
             }
@@ -101,4 +121,3 @@ export function buildDynamicTools(allTools) {
     };
     return [reticleTools, reticleRun];
 }
-//# sourceMappingURL=dynamic-tools.js.map

package/dist/tools/error-recovery.d.ts

@@ -16,16 +16,32 @@ export declare const RECOVERY: {
     readonly THROTTLED: string;
     readonly MISSING_BASELINE: string;
     readonly MISSING_RECORDING: string;
+    readonly STALE_REF: string;
+    readonly BAD_ARGUMENTS: string;
     readonly TOKEN_REQUIRED: string;
 };
 /** The actionable next move for a known error message, or undefined when none is recognized. */
 export declare function recoveryFor(message: string): string | undefined;
+/**
+ * The ask attached to errors we do NOT recognize. An unrecognized error is, by definition, the case
+ * where Reticle failed in a way nobody anticipated — the single highest-value moment to hear from the
+ * agent, and until now the moment where the agent worked around us in silence and we learned nothing.
+ *
+ * Deliberately NOT attached when a recovery hint matched: there the agent has a concrete next move,
+ * and diverting it into filing a report about a failure we already understand costs a turn and tells
+ * us nothing new.
+ */
+export declare const FEEDBACK_ASK: string;
 /** The error envelope sent to the agent: the message, plus a recovery hint when one is known. */
 interface ErrorPayload {
     error: string;
     recovery?: string;
+    feedback?: string;
 }
-/** Build the tool-error payload spliced at the MCP boundary — `recovery` is added only when known. */
+/**
+ * Build the tool-error payload spliced at the MCP boundary. `recovery` is added when the error is
+ * known; the feedback ask is added when it is NOT — the two are mutually exclusive by design, so the
+ * agent always gets exactly one next move.
+ */
 export declare function buildErrorPayload(message: string): ErrorPayload;
 export {};
-//# sourceMappingURL=error-recovery.d.ts.map

package/dist/tools/error-recovery.js

@@ -19,10 +19,18 @@ export const RECOVERY = {
     UNKNOWN_SESSION: 'That sessionId is not connected. Call reticle_sessions for the current ids and retry with a valid one.',
     THROTTLED: 'The target tab is backgrounded/throttled, so actions may silently no-op. Ask the human to bring ' +
         'the tab to the front, or run `reticle drive <url>` for a guaranteed scriptable context.',
-    MISSING_BASELINE: 'That baseline does not exist yet. Call reticle_baseline_list to see saved names, or reticle_baseline_save ' +
-        'to capture one before diffing against it.',
-    MISSING_RECORDING: 'No recording by that name is in progress. Start one with reticle_record_start before annotating, ' +
-        'stopping, or saving it.',
+    MISSING_BASELINE: 'That baseline does not exist yet. Call reticle_baseline { action: "list" } to see saved names, or ' +
+        'reticle_baseline { action: "save", name } to capture one before diffing against it.',
+    MISSING_RECORDING: 'No recording by that name is in progress. Start one with reticle_record { action: "start", name } ' +
+        'before annotating, stopping, or saving it.',
+    STALE_REF: 'That ref is stale: refs are invalidated whenever the DOM re-renders, so any action that ' +
+        'navigated, opened a modal, re-sorted a list or changed the page invalidates every ref taken ' +
+        'before it. Reticle refuses here rather than clicking whatever now occupies that slot. Call ' +
+        'reticle_query again for a fresh ref and retry the action — and prefer reticle_act_and_wait ' +
+        '{ until } when an action changes the page, so the next ref is taken after it settles.',
+    BAD_ARGUMENTS: "That call did not match the tool's schema — the message above names the tool and the exact " +
+        "argument it wanted. Re-read that tool's parameters and retry with the missing or corrected " +
+        'argument. This is an invalid call, not a Reticle defect: there is nothing to report.',
     TOKEN_REQUIRED: 'The bridge binds beyond localhost and requires a pairing token. Set the same token in the SDK ' +
         'init (@reticlehq/core) and the Reticle server config, then reconnect.',
 };
@@ -35,6 +43,16 @@ const RULES = [
     { match: /no baseline named/i, hint: RECOVERY.MISSING_BASELINE },
     { match: /no (?:active|compiled) recording named/i, hint: RECOVERY.MISSING_RECORDING },
     { match: /pairing token is required/i, hint: RECOVERY.TOKEN_REQUIRED },
+    // The commonest post-action condition there is. Unmatched, it fell through to FEEDBACK_ASK and
+    // told the agent a successful click's aftermath might be a bug in Reticle.
+    { match: /no longer resolves to an element/i, hint: RECOVERY.STALE_REF },
+    // A message naming a `reticle_*` tool is one WE authored about our own API — an invalid call, not
+    // an unanticipated failure. Left unmatched it collected the feedback ask, which pushed agents to
+    // file reports about their own bad arguments. Kept LAST so a specific rule above always wins.
+    {
+        match: /reticle_[a-z_]+\s*\{[^}]*\}.*\b(requires|must|expected)\b/i,
+        hint: RECOVERY.BAD_ARGUMENTS,
+    },
 ];
 /** The actionable next move for a known error message, or undefined when none is recognized. */
 export function recoveryFor(message) {
@@ -44,9 +62,26 @@ export function recoveryFor(message) {
     }
     return undefined;
 }
-/** Build the tool-error payload spliced at the MCP boundary — `recovery` is added only when known. */
+/**
+ * The ask attached to errors we do NOT recognize. An unrecognized error is, by definition, the case
+ * where Reticle failed in a way nobody anticipated — the single highest-value moment to hear from the
+ * agent, and until now the moment where the agent worked around us in silence and we learned nothing.
+ *
+ * Deliberately NOT attached when a recovery hint matched: there the agent has a concrete next move,
+ * and diverting it into filing a report about a failure we already understand costs a turn and tells
+ * us nothing new.
+ */
+export const FEEDBACK_ASK = 'This error is not one Reticle recognizes, which means it may be a defect in Reticle rather than in ' +
+    'the app. If you believe Reticle misbehaved, call reticle_feedback with a root-cause analysis and ' +
+    'the call trace before moving on — that report is the only way this gets fixed.';
+/**
+ * Build the tool-error payload spliced at the MCP boundary. `recovery` is added when the error is
+ * known; the feedback ask is added when it is NOT — the two are mutually exclusive by design, so the
+ * agent always gets exactly one next move.
+ */
 export function buildErrorPayload(message) {
     const recovery = recoveryFor(message);
-    return recovery !== undefined ? { error: message, recovery } : { error: message };
+    return recovery !== undefined
+        ? { error: message, recovery }
+        : { error: message, feedback: FEEDBACK_ASK };
 }
-//# sourceMappingURL=error-recovery.js.map

package/dist/tools/feedback-tools.d.ts

@@ -0,0 +1,24 @@
+import type { ToolDef } from './tools.js';
+export declare const FEEDBACK_TOOLS: ToolDef[];
+/**
+ * The human-facing prompt, delivered to the agent so it can relay the ask at the natural moment —
+ * right after a verification lands, when the experience is fresh. MCP has no channel from the server
+ * to the person, so the agent is the channel.
+ *
+ * Delivered ONCE per server process. A prompt on every verification would be nagging, and a nagged
+ * user opts out of telemetry entirely, which costs us the counters too.
+ */
+export declare const FEEDBACK_PROMPT: {
+    readonly ask: "Ask the human, in your own words and only once: how did this verification go, and what would have made Reticle more useful? If they answer, file it with `reticle feedback` (they run it) or relay it yourself.";
+    readonly command: "reticle feedback";
+};
+/** Tools whose completion means "a verification just happened" — the only moment worth asking at. */
+export declare const VERIFICATION_TOOLS: ReadonlySet<string>;
+/**
+ * The human prompt, when one is due. Resettable for tests.
+ *
+ * Silent when the channel is off. Asking someone for feedback we have already been told not to
+ * collect is worse than not asking: it spends their attention on a message with nowhere to go.
+ */
+export declare function takeFeedbackPrompt(toolName: string): typeof FEEDBACK_PROMPT | undefined;
+export declare function resetFeedbackPrompt(): void;

package/dist/tools/feedback-tools.js

@@ -0,0 +1,180 @@
+/**
+ * `reticle_feedback` — the agent's return path.
+ *
+ * Reticle is built for agents, but the agent has always been the one party that knows a verification
+ * went wrong and has had no way to say so. It sees the tool that returned nonsense, the observer that
+ * missed the event, the verdict it could not act on — and then that context is discarded at the end of
+ * the turn. This tool is where that knowledge goes instead.
+ *
+ * It is deliberately shaped to demand an RCA rather than a complaint. `text` asks what the agent
+ * expected, what it got, and why it believes Reticle is at fault; `trace` asks for the call trail that
+ * proves it. A report we cannot reproduce is a report we cannot fix, so the description spends its
+ * tokens on that and not on politeness.
+ */
+import { z } from 'zod';
+import { FeedbackKind, FeedbackSource } from '@reticlehq/core';
+import { ReticleTool } from './tool-names.js';
+import { asString } from './tools-helpers.js';
+import { submitFeedback, feedbackDisabled } from '../telemetry/feedback.js';
+import { getTelemetry } from '../telemetry/telemetry.js';
+/** One optional string arg, present only when the agent actually supplied it. */
+function optionalText(args, key) {
+    const value = asString(args[key]);
+    return value !== undefined && value !== '' ? { [key]: value } : {};
+}
+/** Read the connected session's self-reported facts, or nothing when no app is attached. */
+function sessionFacts(deps, sessionId) {
+    const driven = deps.realInput !== undefined;
+    try {
+        const session = deps.sessions.resolve(sessionId);
+        return {
+            ...(session.runtime !== undefined ? { runtime: session.runtime } : {}),
+            ...(session.engine !== undefined ? { engine: session.engine } : {}),
+            driven,
+        };
+    }
+    catch {
+        // Feedback about "no session could ever connect" is some of the most valuable feedback there is.
+        // Refusing to file it without a session would silence exactly the failure we most need to hear.
+        return { driven };
+    }
+}
+export const FEEDBACK_TOOLS = [
+    {
+        name: ReticleTool.FEEDBACK,
+        description: "Tell the Reticle maintainers something — a failure, OR a feature you wish existed. Reticle is built FOR agents, so your experience is the one that decides what gets built, and this is the only channel that reaches us. File a `bug` when a tool returned something wrong, a `gap` when Reticle could not observe what you needed, an `ambiguity` when a verdict was not decidable, a `feature_request` when you thought 'I wish Reticle could do X', or an `improvement` when something works but is awkward (too many calls, a confusing shape, a slow path). Do not save these up or judge them as too minor — file it the moment you notice, then carry on with your task. For a failure, write `text` as a root-cause analysis (what you called, expected, got). For a request, write what you want and use `need` for the GOAL behind it, `impact` for what gets better, and `currentApproach` for how you are working around it today — that workaround is usually the most useful thing in the report. Set `model` to the model you are running. Never include app source, secrets, user data, or customer records. Do NOT use this for bugs you found in the app under test — that is a successful verification, which is Reticle working.",
+        inputSchema: {
+            kind: z
+                .enum([
+                FeedbackKind.BUG,
+                FeedbackKind.GAP,
+                FeedbackKind.AMBIGUITY,
+                FeedbackKind.FEATURE_REQUEST,
+                FeedbackKind.IMPROVEMENT,
+            ])
+                .describe('bug = a Reticle tool returned a wrong or broken result; gap = Reticle could not observe something you needed at all; ambiguity = the verification ran but you could not tell pass from fail; feature_request = something that does not exist and would have helped; improvement = something that exists but is awkward or inefficient.'),
+            text: z
+                .string()
+                .min(1)
+                .describe('For a failure: the root-cause analysis — the call you made, what you expected, what you got, and why Reticle is at fault. For a request: what you want, in your own words.'),
+            need: z
+                .string()
+                .optional()
+                .describe('The GOAL behind a request, not the request itself. "I need to know the page stopped changing before I assert" is a requirement we can solve; "add a waitForIdle tool" is a guess at the solution that may already have an answer.'),
+            impact: z
+                .string()
+                .optional()
+                .describe('What measurably improves — fewer tool calls, fewer retries, a verdict that stops being ambiguous, a flow you currently cannot verify at all.'),
+            currentApproach: z
+                .string()
+                .optional()
+                .describe('How you work around it TODAY. Usually the most useful field in the report: it proves the need is real, and often shows a cheaper fix than the feature being asked for.'),
+            model: z
+                .string()
+                .optional()
+                .describe('The model you are running (e.g. "claude-opus-4", "gpt-5"). We cannot detect this — MCP tells us the client name but has no concept of a model — and it changes how a report is read: a limitation that blocks a smaller model is often a docs problem, while the same one from a frontier model means the surface is genuinely short.'),
+            trace: z
+                .string()
+                .optional()
+                .describe('The literal tool calls and responses that led here, so the failure can be reproduced without guessing.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Only to attach a specific tab s runtime/engine context. Omit it — a report about a session that never connected is still worth filing.'),
+        },
+        outputSchema: {
+            sent: z.boolean(),
+            reason: z.string().optional(),
+            redacted: z.array(z.string()),
+            context: z.unknown(),
+            note: z.string(),
+        },
+        example: {
+            kind: FeedbackKind.FEATURE_REQUEST,
+            text: 'A way to assert that no request fired at all during an action.',
+            need: 'Verifying that a debounced search does NOT call the API on every keystroke.',
+            currentApproach: 'Calling reticle_network before and after and diffing the counts by hand.',
+            model: 'claude-opus-4',
+        },
+        handler: async (deps, args) => {
+            const receipt = await submitFeedback({
+                source: FeedbackSource.AGENT,
+                kind: asString(args['kind']),
+                text: asString(args['text']) ?? '',
+                ...optionalText(args, 'trace'),
+                ...optionalText(args, 'need'),
+                ...optionalText(args, 'impact'),
+                ...optionalText(args, 'currentApproach'),
+                ...optionalText(args, 'model'),
+            }, { session: sessionFacts(deps, asString(args['sessionId'])) });
+            return {
+                ...receipt,
+                note: receipt.sent
+                    ? 'Filed — thank you. Continue your task; do not retry a failing call just to re-report it.'
+                    : 'NOT sent (see reason). Tell the human what you found so it is not lost.',
+            };
+        },
+    },
+];
+/**
+ * The human-facing prompt, delivered to the agent so it can relay the ask at the natural moment —
+ * right after a verification lands, when the experience is fresh. MCP has no channel from the server
+ * to the person, so the agent is the channel.
+ *
+ * Delivered ONCE per server process. A prompt on every verification would be nagging, and a nagged
+ * user opts out of telemetry entirely, which costs us the counters too.
+ */
+export const FEEDBACK_PROMPT = {
+    ask: 'Ask the human, in your own words and only once: how did this verification go, and what would have made Reticle more useful? If they answer, file it with `reticle feedback` (they run it) or relay it yourself.',
+    command: 'reticle feedback',
+};
+/** Tools whose completion means "a verification just happened" — the only moment worth asking at. */
+export const VERIFICATION_TOOLS = new Set([
+    ReticleTool.ASSERT,
+    ReticleTool.FLOW_VERIFY,
+    ReticleTool.VERIFY_CHANGE,
+    ReticleTool.RECONCILE,
+]);
+/**
+ * Verifications between re-offers of the prompt, and how many times we will ever offer it.
+ *
+ * Strictly-once was the first design and it was too fragile. A daemon lives for days; the prompt
+ * lands on the FIRST verification, which is often several hours before the human is in a position to
+ * answer, and if the agent does not relay it in that turn it is gone for the rest of the process.
+ * The signal quietly went to zero and nothing would have told us.
+ *
+ * Re-arming after a run of verifications fixes that without becoming nagging, and the hard cap is
+ * what keeps it honest: at most three asks per daemon, ever. A tool that pesters gets muted, and a
+ * muted tool collects nothing — the same outcome as never asking, reached more annoyingly.
+ */
+const PROMPT_REARM_AFTER_VERIFICATIONS = 25;
+const MAX_PROMPTS_PER_PROCESS = 3;
+let promptsDelivered = 0;
+let verificationsSincePrompt = 0;
+/**
+ * The human prompt, when one is due. Resettable for tests.
+ *
+ * Silent when the channel is off. Asking someone for feedback we have already been told not to
+ * collect is worse than not asking: it spends their attention on a message with nowhere to go.
+ */
+export function takeFeedbackPrompt(toolName) {
+    if (!VERIFICATION_TOOLS.has(toolName))
+        return undefined;
+    if (feedbackDisabled() || !getTelemetry().enabled)
+        return undefined;
+    if (promptsDelivered >= MAX_PROMPTS_PER_PROCESS)
+        return undefined;
+    // The very first verification asks immediately; later ones only after another run of work, so the
+    // ask always arrives attached to something the human just saw happen.
+    if (promptsDelivered > 0 && verificationsSincePrompt < PROMPT_REARM_AFTER_VERIFICATIONS) {
+        verificationsSincePrompt += 1;
+        return undefined;
+    }
+    promptsDelivered += 1;
+    verificationsSincePrompt = 0;
+    return FEEDBACK_PROMPT;
+}
+export function resetFeedbackPrompt() {
+    promptsDelivered = 0;
+    verificationsSincePrompt = 0;
+}

package/dist/tools/invoke-tool.d.ts

@@ -20,4 +20,3 @@ export declare const SESSION_EXEMPT_TOOLS: ReadonlySet<string>;
  * (handlers that already add health are left untouched) and never alters non-object results.
  */
 export declare function runTool(tool: ToolDef, deps: ToolDeps, args: Record<string, unknown>): Promise<unknown>;
-//# sourceMappingURL=invoke-tool.d.ts.map

package/dist/tools/invoke-tool.js

@@ -1,7 +1,13 @@
 import { healthEnvelope } from '../session/session-health.js';
-import { getTelemetry, TelemetryEventKind } from '../telemetry/telemetry.js';
+import { TelemetryActor, TelemetryEventKind } from '@reticlehq/core';
+import { getSessionMetrics } from '../telemetry/session-metrics.js';
+import { getTelemetry } from '../telemetry/telemetry.js';
+import { VERIFICATION_TOOLS } from './feedback-tools.js';
+import { takeUpdateNudge } from '../update/update-nudge.js';
+import { bugsInResult } from '../telemetry/bug-found.js';
 import { asString } from './tools-helpers.js';
 import { ReticleTool } from './tool-names.js';
+import { takeFeedbackPrompt } from './feedback-tools.js';
 /**
  * The live-session tools whose result MUST carry the
  * session-health envelope. Owned in ONE place — not retrofitted per handler — so a throttled tab
@@ -12,12 +18,17 @@ export const SESSION_BOUND_TOOLS = new Set([
     ReticleTool.SNAPSHOT,
     ReticleTool.QUERY,
     ReticleTool.INSPECT,
+    ReticleTool.COVERAGE,
+    ReticleTool.VERIFY_CHANGE,
     ReticleTool.ACT,
     ReticleTool.ACT_SEQUENCE,
     ReticleTool.ACT_AND_WAIT,
     ReticleTool.OBSERVE,
     ReticleTool.WAIT_FOR,
     ReticleTool.ASSERT,
+    // Reads the live page as well as the event window, so a throttled tab can make it compare a stale
+    // render against fresh data — exactly the case the health envelope exists to disclose.
+    ReticleTool.RECONCILE,
     ReticleTool.NETWORK,
     ReticleTool.CONSOLE,
     ReticleTool.ANIMATIONS,
@@ -56,10 +67,74 @@ export const SESSION_EXEMPT_TOOLS = new Set([
     ReticleTool.VIEWPORT, // own contract (applied/width/height); provider-driven, not a live-DOM read
     ReticleTool.ANNOTATE, // annotates a recording's steps; pure disk-side metadata, no live DOM read
     ReticleTool.LEASE, // merged acquire/release — its sessionId is a pool lease id, not a live session
+    // Its sessionId only enriches the report with the tab's runtime/engine, and it must stay callable
+    // when NO session exists — "nothing ever connected" is feedback we especially want.
+    ReticleTool.FEEDBACK,
 ]);
 function isPlainObject(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Emit `verification_completed` when a verification tool produced a verdict.
+ *
+ * Read off the RESULT here rather than emitted from `decideVerified`, which is where the verdict is
+ * actually decided: that function is pure, and the repo's rules keep clocks, IO and side effects out
+ * of pure logic for good reason. Reading the result also means all four verification tools are covered
+ * by one site instead of four handler edits, and a fifth is covered the moment it joins the set.
+ *
+ * `falseGreenCaught` is the one that matters: the assertion PASSED and Reticle still refused to call
+ * it verified. That is the product's entire thesis reduced to a boolean, and it is the number worth
+ * putting in front of an investor — not "tools were called" but "this many greens were caught lying".
+ */
+function recordVerification(toolName, result, durationMs) {
+    if (!VERIFICATION_TOOLS.has(toolName))
+        return;
+    const verified = typeof result['verified'] === 'string' ? result['verified'] : undefined;
+    // flow_verify reports `status: pass|fail`; assert reports a boolean `pass`. Accept either shape so
+    // the whole family is covered without normalizing four tools' contracts for a metric's convenience.
+    const passed = typeof result['pass'] === 'boolean'
+        ? result['pass']
+        : result['status'] === 'pass'
+            ? true
+            : undefined;
+    if (verified === undefined && passed === undefined)
+        return; // not a verdict-bearing result
+    const metrics = getSessionMetrics();
+    metrics.recordVerification();
+    void getTelemetry().emit(TelemetryEventKind.VERIFICATION_COMPLETED, {
+        actor: TelemetryActor.AGENT,
+        verification: {
+            via: toolName,
+            verified: verified ?? (passed === true ? 'yes' : 'no'),
+            passed: passed ?? verified === 'yes',
+            falseGreenCaught: passed === true && verified === 'no',
+            durationMs,
+        },
+    });
+}
+/**
+ * Emit one `bug_found` per defect in a tool result, and count it into the session.
+ *
+ * The outcome metric: everything else measures whether Reticle is used, this measures whether it
+ * works. Discrete events rather than only a counter, because the KIND distribution is the argument —
+ * "we found 4,000 bugs" is a claim, "1,200 were greens that lied" is evidence.
+ */
+function reportBugsFound(toolName, result) {
+    const bugs = bugsInResult(toolName, result);
+    if (bugs.length === 0)
+        return;
+    const metrics = getSessionMetrics();
+    for (const bug of bugs) {
+        // `recordBug` answers whether this kind is new to the session, which is the only thing that
+        // separates "another defect" from "the same defect again". Counting instances as defects is how
+        // a published number inflates itself.
+        const first = metrics.recordBug(bug.kind);
+        void getTelemetry().emit(TelemetryEventKind.BUG_FOUND, {
+            actor: TelemetryActor.AGENT,
+            bug: { ...bug, repeat: !first },
+        });
+    }
+}
 /**
  * The single entry point both the MCP server and the programmatic invoker call instead of
  * `tool.handler` directly. Runs the handler, then — for a live-session tool returning a plain
@@ -68,8 +143,16 @@ function isPlainObject(value) {
  */
 export async function runTool(tool, deps, args) {
     // Both dispatch paths (MCP + programmatic) pass through here — the one place "which tool is mostly
-    // used" can be counted. Fire-and-forget: telemetry never delays or fails a tool call.
-    void getTelemetry().emit(TelemetryEventKind.TOOL, { tool: tool.name });
+    // used" can be counted. This used to EMIT an event per call; it now increments an in-process counter
+    // that leaves once, with the session summary. A verification loop is 50–200 calls, and PostHog bills
+    // per event — so the old design made the telemetry bill scale with how hard people used the product,
+    // to answer a question the histogram answers better. Counting is also free: no network, no promise,
+    // nothing to fail on a tool call's hot path.
+    // Started/settled as a pair rather than a bare counter: several agents can be inside runTool at
+    // once, so a single "last start" field would attribute one tool's duration to another. The returned
+    // closure carries this call's own identity, which is also what makes peak-concurrency measurable.
+    const settleTiming = getSessionMetrics().startToolCall(tool.name, args);
+    const startedAt = Date.now();
     const rawSessionId = asString(args['sessionId']);
     const bound = SESSION_BOUND_TOOLS.has(tool.name);
     // Resolve the session identity ONCE, up front, for a live-session tool. The lease heartbeat must
@@ -90,7 +173,35 @@ export async function runTool(tool, deps, args) {
     const leaseId = session?.id ?? rawSessionId;
     if (leaseId !== undefined)
         deps.pool?.touch(leaseId);
-    const result = await tool.handler(deps, args);
+    let raw;
+    try {
+        raw = await tool.handler(deps, args);
+    }
+    finally {
+        // In a `finally` so a THROWN call still settles: otherwise every failing tool would leak a
+        // concurrency slot and peakConcurrentTools would climb forever on an unhealthy session.
+        settleTiming(Date.now() - startedAt);
+    }
+    // The human-feedback ask rides out on the first VERIFICATION that completes — the one moment the
+    // experience is fresh and there is something concrete to react to. It is spliced BEFORE the
+    // session-bound early return, because two of the four verification tools (flow_verify,
+    // verify_change) are session-EXEMPT and would otherwise never carry it.
+    if (isPlainObject(raw)) {
+        recordVerification(tool.name, raw, Date.now() - startedAt);
+        reportBugsFound(tool.name, raw);
+    }
+    const prompt = isPlainObject(raw) ? takeFeedbackPrompt(tool.name) : undefined;
+    // Same one-shot channel as the feedback ask: the agent is mid-task, so anything it would have to go
+    // and ASK for is something it will never ask for. Spliced on ANY tool result, not just a
+    // verification, because an out-of-date install is worth mentioning whatever the agent is doing.
+    const update = isPlainObject(raw) ? takeUpdateNudge() : undefined;
+    const result = prompt === undefined && update === undefined
+        ? raw
+        : {
+            ...raw,
+            ...(prompt !== undefined ? { feedback_prompt: prompt } : {}),
+            ...(update !== undefined ? { update_available: update } : {}),
+        };
     if (!bound || !isPlainObject(result))
         return result;
     // Reuse the session resolved above so the health envelope describes the SAME session the handler
@@ -112,4 +223,3 @@ export async function runTool(tool, deps, args) {
         envelope['session_age_warning'] = warning;
     return Object.keys(envelope).length > 0 ? { ...result, ...envelope } : result;
 }
-//# sourceMappingURL=invoke-tool.js.map

package/dist/tools/lease-tools.d.ts

@@ -44,4 +44,3 @@ export declare function acquireLeasedSession(pool: {
 }>;
 export declare function waitForLeasedSession(isConnected: () => boolean, sleeper?: (ms: number) => Promise<void>, attempts?: number, pollMs?: number): Promise<boolean>;
 export declare const LEASE_TOOLS: ToolDef[];
-//# sourceMappingURL=lease-tools.d.ts.map