@reticlehq/server 2.2.1 → 2.4.0

package/dist/tools/assert-verdict.js

@@ -0,0 +1,62 @@
+import { findContradictions } from '../events/contradictions.js';
+import { blindSpotsFromState, buildCoverageStatement, impeachesCapture, } from '../honesty/blind-spots.js';
+import { buildHonestyBlock } from '../honesty/honesty.js';
+import { hasAcceptedWrite } from '../honesty/accepted-write.js';
+import { hasUnreadWriteOutcome } from '../honesty/unread-outcome.js';
+import { decideVerified } from '../honesty/verified.js';
+import { gradeOfPredicate } from './assert-grade.js';
+/**
+ * The honesty verdict for a plain `reticle_assert`.
+ *
+ * This is the single field an agent reads, and it was missing from the most-used verdict path.
+ * `act_and_wait` has always returned it; `reticle_assert` returned a bare `pass: true`.
+ *
+ * Measured on a shipments console: a dispatch answered 202 Accepted, the row rendered "dispatched"
+ * optimistically, an assert taken right after the click returned `pass: true` with no caveat, and the
+ * server reverted the write to "held" 1.2s later. The 202 machinery that exists precisely to report
+ * that as `verified: "unknown"` was never reached, because the tool an agent actually calls did not
+ * consult it. Asserting a moment earlier — while the POST was still open — is the same story with a
+ * different name: `request-never-settled`, also unreported.
+ */
+export async function assertVerdict(session, predicate, pass, since) {
+    // Scope caveat, stated because it is a real limitation and not a bug: blind spots are tracked per
+    // SESSION, not per assertion window, so a cross-origin iframe seen once marks every later verdict
+    // in that session partial — including ones about a region it cannot affect. That errs toward
+    // over-warning, which is the correct direction here: the failure this guards against is a green
+    // that implies coverage it never had, and a needless caveat costs the agent a sentence.
+    const spots = blindSpotsFromState(session.blindSpots());
+    const statement = buildCoverageStatement(spots);
+    // Omitted entirely when coverage is full, so an intact page pays nothing and the field's PRESENCE
+    // is the warning.
+    const coverage = statement.coverage === 'partial'
+        ? {
+            coverage: statement.note ?? 'partial',
+            coverage_spots: statement.spots.map((sp) => ({ kind: sp.kind, count: sp.count })),
+        }
+        : {};
+    const windowEvents = await session.queryEvents({ since });
+    // Everything before the window, passed as LEARNING material only. A scale error disagrees with a
+    // value the API stated earlier in the session, which an action-scoped window can never contain —
+    // measured live, `observe` over a wide window reported `unit-mismatch` while `assert` on the same
+    // session reported none. Attribution is unchanged: findings still come only from windowEvents.
+    const prior = since > 0 ? (await session.queryEvents({ since: 0 })).filter((e) => e.t < since) : [];
+    const contradictions = findContradictions(windowEvents, { prior });
+    // Only a spot that IMPEACHES the capture downgrades a verdict. A structural boundary (virtualized
+    // rows, a cross-origin frame) is reported as coverage and must not impugn what WAS observed.
+    const impeaching = buildCoverageStatement(spots.filter((sp) => impeachesCapture(sp.kind)));
+    const outcomePending = hasAcceptedWrite(windowEvents);
+    const outcomeUnread = hasUnreadWriteOutcome(windowEvents);
+    const decision = decideVerified({
+        pass,
+        honesty: buildHonestyBlock({
+            grade: gradeOfPredicate(predicate),
+            attribution: 'window',
+            coveragePartial: statement.coverage === 'partial',
+            ...(impeaching.note === undefined ? {} : { blindSpots: [impeaching.note] }),
+        }),
+        contradictions,
+        ...(outcomePending ? { outcomePending } : {}),
+        ...(outcomeUnread ? { outcomeUnread } : {}),
+    });
+    return { decision: decision, contradictions, coverage };
+}

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

@@ -1,3 +1,2 @@
 import type { ToolDef } from './tools.js';
 export declare const BROWSER_TOOLS: ToolDef[];
-//# sourceMappingURL=browser-tools.d.ts.map

package/dist/tools/browser-tools.js

@@ -6,13 +6,14 @@ import { sessionIdShape, commandOrThrow } from './tool-kit.js';
 export const BROWSER_TOOLS = [
     {
         name: ReticleTool.NAVIGATE,
+        example: { url: '/settings' },
         description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). The SDK reconnects automatically after the page loads. Use reticle_sessions to confirm the new tab is connected before acting.',
         inputSchema: {
             url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
             reload: z
                 .boolean()
                 .optional()
-                .describe('Reload the current page instead of navigating (replaces reticle_refresh).'),
+                .describe('Reload the current page instead of navigating (replaces the former standalone refresh tool).'),
             hard: z
                 .boolean()
                 .optional()
@@ -73,4 +74,3 @@ export const BROWSER_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=browser-tools.js.map

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

@@ -5,4 +5,3 @@ import type { ToolDef } from './tools.js';
  * live registry to that file (pretty-printed, stable key order — diffable in PRs).
  */
 export declare const CONTRACT_TOOLS: ToolDef[];
-//# sourceMappingURL=contract-tools.d.ts.map

package/dist/tools/contract-tools.js

@@ -64,4 +64,3 @@ export const CONTRACT_TOOLS = [
         },
     },
 ];
-//# sourceMappingURL=contract-tools.js.map

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

@@ -0,0 +1,9 @@
+import type { ToolDef } from './tools.js';
+interface Control {
+    ref: string;
+    label: string;
+}
+/** Parse the interactive snapshot into {ref,label} controls, preserving document order. */
+export declare function parseControls(tree: string): Control[];
+export declare const COVERAGE_TOOLS: ToolDef[];
+export {};

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