@reticlehq/server 2.14.0 → 3.2.0

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

@@ -0,0 +1,35 @@
+import type { ToolDef } from './tool-kit.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,
+ * and the set that decides what `verification_completed` counts.
+ *
+ * ACT_AND_WAIT belongs here and was missing for a long time. It declares `verified` in its
+ * outputSchema, returns the whole verdict block, and its own description calls it "one hop for the
+ * act->observe->assert loop" — it IS the verification path most agents take. The guard that should
+ * have caught the omission keyed on the tool NAME (/assert|verify/), which act_and_wait does not
+ * match, so it slipped through in silence. Measured over a day of real telemetry: act_and_wait 14
+ * calls, assert ZERO, verification_completed 2. Agents were verifying the entire time and the metric
+ * could not see it. The contract test now checks the SHAPE instead.
+ */
+export declare const VERDICT_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/surface/tools/feedback-tools.js

@@ -0,0 +1,280 @@
+/**
+ * `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, FEEDBACK_RATING_MAX, FEEDBACK_RATING_MIN, } from '@reticlehq/core/telemetry';
+import { ReticleTool } from '@reticlehq/core';
+import { asNumber, asString } from '@reticlehq/core';
+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 } : {};
+}
+/**
+ * The star rating, present only when the agent actually supplied one, and only when it is on the
+ * scale core defines. Bounds-checked HERE as well as in the schema because a number that survives
+ * to the wire off-scale is worse than an absent one: it still averages.
+ */
+function optionalRating(args) {
+    const value = asNumber(args['rating']);
+    if (value === undefined || !Number.isInteger(value))
+        return {};
+    if (value < FEEDBACK_RATING_MIN || value > FEEDBACK_RATING_MAX)
+        return {};
+    return { rating: 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 } : {}),
+            // The app's own account of what it is. Without this the reported stack came from the daemon's
+            // working directory, so feedback from one app was filed against another's framework.
+            ...(0 < session.adapters.length ? { adapters: session.adapters } : {}),
+            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 };
+    }
+}
+/** Said when a report arrives with no body at all. Names both accepted fields so the retry can work. */
+const NO_BODY_REASON = 'the report has no body — send it as `text` (or `summary`, which is the same field). Nothing was filed.';
+/** `text`, or the `summary` alias, whichever arrived. Empty when neither did — the handler refuses. */
+function feedbackBody(args) {
+    const text = asString(args['text'])?.trim();
+    if (text !== undefined && '' !== text)
+        return text;
+    return asString(args['summary'])?.trim() ?? '';
+}
+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', an `improvement` when something works but is awkward (too many calls, a confusing shape, a slow path), or an `experience` when something worked notably WELL (carry `rating` 1-5). File that one unprompted, when you actually notice it, and say which call and what it saved you — every other kind here is a complaint, so it is the only evidence for what is worth protecting when we change things. 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,
+                FeedbackKind.EXPERIENCE,
+            ])
+                .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; experience = something worked notably well and is worth keeping (pair it with `rating`).'),
+            text: z
+                .string()
+                .optional()
+                .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.'),
+            /**
+             * `text` under the name agents reach for unprompted.
+             *
+             * Incident: field reports of a call carrying a summary and a trace coming back
+             * "String must contain at least 1 character(s)" and being lost. The body had been put in
+             * `summary` — a field this tool never had. The MCP SDK validates input BEFORE the handler, so
+             * a required `text` made those calls unreachable and unanswerable: no handler ran, nothing
+             * could explain the rejection, and the report was dropped.
+             *
+             * So `text` is optional and this is its alias; the handler takes whichever arrived and refuses
+             * — with both names in the reason — only when neither did. Widening the schema is what buys
+             * the chance to say anything at all.
+             */
+            summary: z.string().optional().describe('Alias for `text`; send either.'),
+            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.'),
+            rating: z
+                .number()
+                .int()
+                .min(FEEDBACK_RATING_MIN)
+                .max(FEEDBACK_RATING_MAX)
+                .optional()
+                .describe(`How well it worked, ${FEEDBACK_RATING_MIN}-${FEEDBACK_RATING_MAX}, with an \`experience\`. Only when you formed the judgement while working, never because you were asked: an agreeable number and an earned one are indistinguishable once both sit in the same column. The \`text\` is the part we can act on.`),
+            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: {
+            /** Confirmed delivery. Always false here: the agent path queues and returns. */
+            sent: z.boolean(),
+            /** Validated, redacted and queued. This is the one to read. */
+            accepted: 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) => {
+            // Refuse here rather than in core's schema: core validates a REPORT, which has one body field
+            // and knows nothing about the `summary` alias, so its rejection reads "String must contain at
+            // least 1 character(s)" and names neither field. That sentence is what agents were given when
+            // their report was dropped, and it is unactionable — the agent cannot tell which of eight
+            // arguments was wrong.
+            const body = feedbackBody(args);
+            if ('' === body) {
+                return {
+                    sent: false,
+                    accepted: false,
+                    reason: NO_BODY_REASON,
+                    redacted: [],
+                    context: undefined,
+                    note: 'NOT accepted (see reason). Tell the human what you found so it is not lost.',
+                };
+            }
+            const receipt = await submitFeedback({
+                source: FeedbackSource.AGENT,
+                kind: asString(args['kind']),
+                text: body,
+                ...optionalText(args, 'trace'),
+                ...optionalText(args, 'need'),
+                ...optionalText(args, 'impact'),
+                ...optionalText(args, 'currentApproach'),
+                ...optionalText(args, 'model'),
+                ...optionalRating(args),
+            }, {
+                session: sessionFacts(deps, asString(args['sessionId'])),
+                // The AGENT does not wait for the network. `reticle feedback` (a human, at a terminal,
+                // watching for an answer) still does — see submitFeedback's `background`.
+                background: true,
+            });
+            return {
+                ...receipt,
+                note: receipt.accepted
+                    ? 'Accepted — thank you. It sends in the background so you are not kept waiting; if it fails you will be told on a later tool result. Continue your task; do not retry a failing call just to re-report it.'
+                    : 'NOT accepted (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,
+ * and the set that decides what `verification_completed` counts.
+ *
+ * ACT_AND_WAIT belongs here and was missing for a long time. It declares `verified` in its
+ * outputSchema, returns the whole verdict block, and its own description calls it "one hop for the
+ * act->observe->assert loop" — it IS the verification path most agents take. The guard that should
+ * have caught the omission keyed on the tool NAME (/assert|verify/), which act_and_wait does not
+ * match, so it slipped through in silence. Measured over a day of real telemetry: act_and_wait 14
+ * calls, assert ZERO, verification_completed 2. Agents were verifying the entire time and the metric
+ * could not see it. The contract test now checks the SHAPE instead.
+ */
+export const VERDICT_TOOLS = new Set([
+    ReticleTool.ACT_AND_WAIT,
+    // ACT_SEQUENCE joined the moment a planned step could carry its own `expect`. It now declares
+    // `verified` and grades the whole plan from what its steps declared, which is the same shape
+    // ACT_AND_WAIT has -- and the guard that checks SHAPE rather than tool NAME is what caught it
+    // here rather than six months from now in a metric that had quietly read low the whole time.
+    ReticleTool.ACT_SEQUENCE,
+    ReticleTool.ASSERT,
+    // Merged: `flow_verify` and `verify_change` are actions on this tool now. Naming the merged tool
+    // does NOT make every action a verification — `verificationOf` still requires the result to carry
+    // a `verified` or a pass/fail `status`, so `coverage` and `crawl` contribute nothing and cannot
+    // inflate the count.
+    ReticleTool.VERIFY,
+    ReticleTool.RECONCILE,
+    // Replaying ONE saved flow proves a journey still works, which is a verification by any reading a
+    // user would give the word — and it was in neither the numerator nor the denominator. It matched
+    // no name tripwire (`/assert|verify/`), it declares no `verified` field for the shape guard to
+    // catch, and its own status vocabulary spells itself `ok | drift | error`, so the three
+    // independent things that could have noticed all said nothing. `verificationOf` maps that
+    // vocabulary; `error` stays UNKNOWN, because a flow that could not load is not a verdict about
+    // anybody's app.
+    ReticleTool.FLOW_REPLAY,
+]);
+/**
+ * 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 (!VERDICT_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/surface/tools/first-sentence.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The opening sentence of a tool description, for the two surfaces that show a summary.
+ *
+ * There were two copies of this, and only one of them knew about abbreviations. The MCP surface's
+ * copy masks `e.g.` and friends before looking for a sentence end; the tool catalogue's private
+ * copy did not, so `reticle_session` reached every agent as
+ *
+ *   Drive or inspect the SESSION itself, chosen by action: "tune" adjusts the presenter session (e.g.
+ *
+ * and stopped there. Everything after the abbreviation was cut, including `"yield" hands the tab
+ * back to the human and is MANDATORY before you stop driving`. The catalogue is the surface an
+ * agent reads to find out what exists, so the one instruction the product calls mandatory was
+ * missing from the only place it would have been discovered.
+ *
+ * This is the same defect the MCP copy already carried a long comment about, reappearing in a
+ * second copy written without the fix. So there is one implementation now, and the thing the two
+ * callers genuinely disagree about -- how much room a line gets -- is a parameter rather than a
+ * reason to fork the logic again.
+ */
+/** What the MCP surface allows a one-line description. */
+export declare const MCP_SUMMARY_LENGTH = 160;
+/** What the catalogue allows, which is tighter: it prints one line per tool, for every tool. */
+export declare const CATALOGUE_SUMMARY_LENGTH = 140;
+export declare function firstSentence(description: string, maxLength?: number): string;

package/dist/surface/tools/gap-novelty.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Say each instrumentation gap's REMEDY once per session; keep its facts every time.
+ *
+ * `instrumentation-gap.ts` sets the rule this enforces: a gap fires only when an absence in the app
+ * changed the answer the agent just got, "never as a survey of everything uninstrumented on the
+ * page". The vocabulary honoured that. The emission did not — the same remedy shipped on every
+ * verdict that hit the same absence.
+ *
+ * Measured on a 61-call drive of a production-sized dashboard fixture: `no-source-mapping` was
+ * emitted **11 times, byte-identical, 365 B each**, and `instrumentationGaps` as a whole was 11.5%
+ * of the run's entire token cost, of which 17 occurrences were repeats of advice already given.
+ *
+ * The two halves have different shelf lives:
+ *   - `missing` / `cost` / `fix` — the REMEDY. Identical every time. Teaches once, then it is rent.
+ *   - `ref` / `source` — the FACTS. Different per element, and the reason a repeat is worth sending
+ *     at all: "this control too" is news; "here is what source mapping is" is not.
+ *
+ * So a repeat keeps the facts, drops the prose, and carries `repeat: true` so a reader knows the
+ * full text was given earlier in this session rather than withheld.
+ *
+ * Scoped per session id, because a new session is a new agent that has been told nothing.
+ */
+/** Just enough shape to route on. Deliberately NOT an index signature: `InstrumentationGap` is a
+ *  union of concrete object types and would not be assignable to one. */
+interface GapLike {
+    kind?: unknown;
+}
+/**
+ * Full text the first time a kind is seen in this session; facts-only afterwards.
+ *
+ * Returns a NEW array and never mutates its input — the same gap objects travel into telemetry and
+ * into the persisted capsule, and trimming those would lose the remedy where it is read cold.
+ */
+export declare function withGapNovelty<T extends GapLike>(sessionId: string | undefined, gaps: readonly T[]): T[];
+/** Forget a session. Called when a session ends so a long-lived daemon does not grow a map forever. */
+export declare function forgetGapNovelty(sessionId: string): void;
+/** Test seam: drop every session's memory. */
+export declare function resetGapNovelty(): void;
+export {};

package/dist/surface/tools/gap-novelty.js

@@ -0,0 +1,69 @@
+/**
+ * Say each instrumentation gap's REMEDY once per session; keep its facts every time.
+ *
+ * `instrumentation-gap.ts` sets the rule this enforces: a gap fires only when an absence in the app
+ * changed the answer the agent just got, "never as a survey of everything uninstrumented on the
+ * page". The vocabulary honoured that. The emission did not — the same remedy shipped on every
+ * verdict that hit the same absence.
+ *
+ * Measured on a 61-call drive of a production-sized dashboard fixture: `no-source-mapping` was
+ * emitted **11 times, byte-identical, 365 B each**, and `instrumentationGaps` as a whole was 11.5%
+ * of the run's entire token cost, of which 17 occurrences were repeats of advice already given.
+ *
+ * The two halves have different shelf lives:
+ *   - `missing` / `cost` / `fix` — the REMEDY. Identical every time. Teaches once, then it is rent.
+ *   - `ref` / `source` — the FACTS. Different per element, and the reason a repeat is worth sending
+ *     at all: "this control too" is news; "here is what source mapping is" is not.
+ *
+ * So a repeat keeps the facts, drops the prose, and carries `repeat: true` so a reader knows the
+ * full text was given earlier in this session rather than withheld.
+ *
+ * Scoped per session id, because a new session is a new agent that has been told nothing.
+ */
+/** The fields worth repeating. Everything else on a gap is the remedy, said once. */
+const FACT_KEYS = ['kind', 'ref', 'source'];
+/** Sessions that have already been given the full text, by gap kind. */
+const toldBySession = new Map();
+/**
+ * Full text the first time a kind is seen in this session; facts-only afterwards.
+ *
+ * Returns a NEW array and never mutates its input — the same gap objects travel into telemetry and
+ * into the persisted capsule, and trimming those would lose the remedy where it is read cold.
+ */
+export function withGapNovelty(sessionId, gaps) {
+    if (0 === gaps.length)
+        return [];
+    // No session id means no memory to check against, so nothing can be a repeat. Sending the full
+    // text is the safe direction: a reader who has seen it skims, a reader who has not is stuck.
+    if (sessionId === undefined)
+        return [...gaps];
+    let told = toldBySession.get(sessionId);
+    if (told === undefined) {
+        told = new Set();
+        toldBySession.set(sessionId, told);
+    }
+    return gaps.map((gap) => {
+        const kind = 'string' === typeof gap.kind ? gap.kind : undefined;
+        if (kind === undefined)
+            return gap;
+        if (!told.has(kind)) {
+            told.add(kind);
+            return gap;
+        }
+        const source = gap;
+        const compact = { repeat: true };
+        for (const key of FACT_KEYS) {
+            if (source[key] !== undefined)
+                compact[key] = source[key];
+        }
+        return compact;
+    });
+}
+/** Forget a session. Called when a session ends so a long-lived daemon does not grow a map forever. */
+export function forgetGapNovelty(sessionId) {
+    toldBySession.delete(sessionId);
+}
+/** Test seam: drop every session's memory. */
+export function resetGapNovelty() {
+    toldBySession.clear();
+}

package/dist/surface/tools/gaps/capability-absences.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What this session CANNOT see, said up front.
+ *
+ * An agent asking "what can I do here?" gets the app's testable surface: its testids, signals, stores
+ * and flows. That answers what the app OFFERS. It says nothing about what the instrumentation in the
+ * page is switched off from watching.
+ *
+ * So an agent could plan a verification around a request body, spend an action on it, and only then
+ * be told that this session does not record bodies. The refusal it eventually meets is good and
+ * arrives before the action is spent. It is still late: the plan was already built around something
+ * that was never going to work, and the agent paid to find out.
+ *
+ * The rule this follows, and the reason for the `false !==` checks below: an absence is only reported
+ * when the page DECLARED the feature off. An older SDK sends nothing at all, and reading silence as
+ * "off" would announce a missing capability to every session that predates the announcement and can
+ * satisfy the clause perfectly well. Silence means unknown, never no.
+ */
+/** One thing this session cannot do, why it matters, and how to turn it on. */
+export interface CapabilityAbsence {
+    /** Stable name, so an agent can branch on it without reading prose. */
+    capability: string;
+    /** What is lost. Written for whoever has to decide what to do instead. */
+    meaning: string;
+    /** How to get it back, or why you might not want to. */
+    remedy: string;
+}
+/** The parts of a session this reads. Narrow on purpose, so a fake in a test is three fields. */
+export interface CapabilityFacts {
+    captureBodies?: boolean | undefined;
+    sourceMapping?: boolean | undefined;
+}
+/**
+ * Every capability this session has declared switched OFF.
+ *
+ * Empty when nothing is declared off, which is the normal case. Callers omit the field entirely when
+ * it is empty rather than sending `[]`, so that an empty answer keeps meaning "nothing is missing"
+ * instead of becoming a line on every healthy response that people learn to skip.
+ */
+export declare function capabilityAbsences(session: CapabilityFacts): CapabilityAbsence[];

package/dist/surface/tools/gaps/capability-absences.js

@@ -0,0 +1,46 @@
+/**
+ * What this session CANNOT see, said up front.
+ *
+ * An agent asking "what can I do here?" gets the app's testable surface: its testids, signals, stores
+ * and flows. That answers what the app OFFERS. It says nothing about what the instrumentation in the
+ * page is switched off from watching.
+ *
+ * So an agent could plan a verification around a request body, spend an action on it, and only then
+ * be told that this session does not record bodies. The refusal it eventually meets is good and
+ * arrives before the action is spent. It is still late: the plan was already built around something
+ * that was never going to work, and the agent paid to find out.
+ *
+ * The rule this follows, and the reason for the `false !==` checks below: an absence is only reported
+ * when the page DECLARED the feature off. An older SDK sends nothing at all, and reading silence as
+ * "off" would announce a missing capability to every session that predates the announcement and can
+ * satisfy the clause perfectly well. Silence means unknown, never no.
+ */
+/**
+ * Every capability this session has declared switched OFF.
+ *
+ * Empty when nothing is declared off, which is the normal case. Callers omit the field entirely when
+ * it is empty rather than sending `[]`, so that an empty answer keeps meaning "nothing is missing"
+ * instead of becoming a line on every healthy response that people learn to skip.
+ */
+export function capabilityAbsences(session) {
+    const absences = [];
+    if (false === session.captureBodies) {
+        absences.push({
+            capability: 'network-bodies',
+            meaning: 'request and response bodies are not recorded, so an assertion that reads one cannot be ' +
+                'answered here and will be refused before it spends an action',
+            remedy: "pass captureBodies: true to connect() in this app's Reticle setup, then reload the page. " +
+                'Bodies can carry personal data, so this is off unless a project asks for it.',
+        });
+    }
+    if (false === session.sourceMapping) {
+        absences.push({
+            capability: 'source-mapping',
+            meaning: 'elements do not carry a source stamp, so a failing verdict can say what went wrong but ' +
+                'not which file and line to open',
+            remedy: 'this is often deliberate: some renderers reject unknown DOM attributes, so setups that ' +
+                'need it switch the stamp off on purpose. Verdicts stay correct without it.',
+        });
+    }
+    return absences;
+}