@reticlehq/server 2.14.0 → 3.2.0

package/dist/surface/tools/explore-tools.js

@@ -0,0 +1,162 @@
+/**
+ * `reticle_verify { action: "explore" }` — hand the driving back to Reticle.
+ *
+ * The tool exists because of where the cost of a verification actually sits. An agent that drives an
+ * app itself pays for every snapshot, every act result and every observation in ITS OWN context, on
+ * every subsequent turn, and then pays again on the next run because nothing was recorded. This call
+ * moves the whole drive into the daemon, where a small model does it against the same tool surface,
+ * and hands back a few lines: what was driven, and which flows now exist.
+ *
+ * Those flows are the point. From the second run onwards `reticle_verify { action: "flows" }` replays
+ * them deterministically with no model in the loop at all.
+ */
+import { z } from 'zod';
+import { ReticleTool, asRecord } from '@reticlehq/core';
+import { stepCountSchema } from './args/numeric-bounds.js';
+import { exploreApp, harnessAvailable, withLinkedCredential, MSG_NO_HARNESS_KEY, } from './harness-explore.js';
+import { DRIVER_NAMES } from '../../features/harness/drivers.js';
+import { describeDrive, replayedFlows } from '../../features/harness/drive-report.js';
+import { StopReason } from '../../features/harness/harness.js';
+export const EXPLORE_TOOLS = [
+    {
+        name: ReticleTool.VERIFY_EXPLORE,
+        description: 'Drive the app yourself? Do not — call this instead. A model inside the daemon drives it through this same tool surface, records what it drove as saved flows, and answers in a few lines, so the whole drive costs you one tool call instead of a context full of snapshots. Pass `persona` to say who to be or what to accomplish ("a returning customer checking out", "an admin revoking a seat") and it completes that whole journey rather than clicking at random. Returns { stopReason, steps, savedFlows, summary, usage }. The saved flows are the point: from the next run on, reticle_verify { action: "flows" } replays them deterministically with NO model in the loop. DESTRUCTIVE — it really drives the app, and it spends model budget. Needs ANTHROPIC_API_KEY in the daemon environment.',
+        inputSchema: {
+            persona: z
+                .string()
+                .optional()
+                .describe('Who to be, or what to accomplish. A journey ("sign up, then invite a teammate") drives far better than no focus at all.'),
+            maxSteps: stepCountSchema
+                .optional()
+                .describe('Ceiling on model turns. Bounds cost, not value — the drive is graded however it ends.'),
+            driver: z
+                .enum(DRIVER_NAMES)
+                .optional()
+                .describe('Which model drives. An unconfigured one is an error, never a substitution, so an A/B cannot measure the same driver twice. Omit for the default.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+        },
+        // Everything the handler returns has to be declared, or a schema-aware client never sees it.
+        outputSchema: {
+            stopReason: z.string(),
+            /** Which driver actually drove, so a comparison can never misattribute its own result. */
+            driver: z.string(),
+            steps: z.number(),
+            savedFlows: z.array(z.string()),
+            /** Flows that already existed and were driven and written again. A second run's ordinary result. */
+            rewroteFlows: z.array(z.string()),
+            /**
+             * What the drive set out to do, read from `.reticle` BEFORE it started — every recorded
+             * journey with the consequence that must still hold, and the declared intent nobody has
+             * tested. Returned so the caller can see the drive was aimed rather than wandering.
+             */
+            plan: z.object({ summary: z.string(), steps: z.array(z.unknown()) }),
+            /**
+             * What the drive did, derived from the calls it made and the verdicts the engine returned.
+             *
+             * Not the driver's narration. A driver that cannot write a sentence used to leave this empty,
+             * and a driver that can is the one witness with a reason to round "unknown" up to "worked".
+             */
+            summary: z.string(),
+            /** Present when the drive broke: a model that would not answer, a wedged browser. */
+            error: z.string().optional(),
+            /** What the drive cost, cache hits included, so an expensive run is visible rather than felt. */
+            usage: z.object({
+                input: z.number(),
+                output: z.number(),
+                cacheRead: z.number(),
+                cacheWrite: z.number(),
+            }),
+            /** Said out loud when a drive recorded nothing, because that is not a verified app. */
+            note: z.string().optional(),
+        },
+        handler: async (deps, args) => {
+            // The credential `reticle link` already filed counts as configured, so somebody who has
+            // signed in and linked does not also have to export a key by hand.
+            const env = await withLinkedCredential(deps, process.env);
+            if (!harnessAvailable(env))
+                throw new Error(MSG_NO_HARNESS_KEY);
+            const persona = args['persona'];
+            const maxSteps = args['maxSteps'];
+            const sessionId = args['sessionId'];
+            const driver = args['driver'];
+            const { drive, savedFlows, rewroteFlows, driverName, plan } = await exploreApp(deps, env, {
+                ...('string' === typeof persona ? { focus: persona } : {}),
+                ...('number' === typeof maxSteps ? { maxSteps } : {}),
+                ...('string' === typeof sessionId ? { sessionId } : {}),
+                ...('string' === typeof driver ? { driverName: driver } : {}),
+            });
+            return {
+                stopReason: drive.stopReason,
+                driver: driverName,
+                steps: drive.steps,
+                savedFlows: [...savedFlows],
+                rewroteFlows: [...rewroteFlows],
+                plan: { summary: plan.summary, steps: [...plan.steps] },
+                // Derived, not narrated. The driver's own `summary` is appended only when it said
+                // something — it is the one part of this a model authored, so it goes last and is labelled.
+                summary: [
+                    describeDrive(drive.toolCalls, [...savedFlows, ...rewroteFlows]),
+                    ...(0 === drive.summary.length ? [] : [`The driver's own account: ${drive.summary}`]),
+                ].join('\n'),
+                ...(drive.error === undefined ? {} : { error: drive.error }),
+                usage: drive.usage,
+                // The note only fires when the drive left NOTHING behind. A rewritten flow is a flow: it
+                // replays, it proves what it asserts, and telling its author that "nothing will replay" is
+                // a lie this tool used to tell on every second run.
+                /*
+                 * The note fires only when the run left NOTHING behind — and a run that REPLAYED left
+                 * plenty. Sixteen recorded journeys re-proved for zero model tokens is the cheap half of
+                 * the plan doing its job, and telling its author to "raise maxSteps" reads as a failure.
+                 */
+                ...(0 === savedFlows.length &&
+                    0 === rewroteFlows.length &&
+                    0 === replayedFlows(drive.toolCalls).length
+                    ? { note: `${NOTHING_RECORDED[drive.stopReason]}${failureDetail(drive)}` }
+                    : {}),
+            };
+        },
+    },
+];
+/**
+ * The tool failure behind an empty drive, when there was one.
+ *
+ * "The drive ran out of steps before saving a flow" is true of a drive that explored happily and ran
+ * long, and ALSO of one that reached its save and was refused — and those need opposite responses.
+ * Without this the two are indistinguishable from outside the daemon, which cost a full debugging
+ * session: a driver whose `reticle_record{stop}` was rejected for a missing argument retried until
+ * the budget ended, and the only thing the caller ever saw was the advice to raise `maxSteps`.
+ */
+function failureDetail(drive) {
+    const failed = drive.toolCalls.filter((call) => call.isError);
+    const last = failed[failed.length - 1];
+    if (last !== undefined) {
+        const message = asRecord(last.result)['error'];
+        return ` ${String(failed.length)} tool call(s) failed during the drive; the last was ${last.name}: ${'string' === typeof message ? message : 'no message'}`;
+    }
+    // Nothing threw, so the interesting case left is a save that was ACCEPTED and wrote nothing —
+    // an empty recording reports success, and from outside the daemon that is indistinguishable from
+    // a drive that never reached its save at all.
+    const saves = drive.toolCalls.filter((call) => ReticleTool.FLOW_SAVE === call.name);
+    const save = saves[saves.length - 1];
+    if (save !== undefined) {
+        const result = asRecord(save.result);
+        return ` The flow save was accepted but kept nothing: ${JSON.stringify({ stepCount: result['stepCount'], empty: result['empty'], warning: result['warning'] })}.`;
+    }
+    return ` The drive never reached a flow save (${String(drive.toolCalls.length)} tool calls made).`;
+}
+/**
+ * What an empty drive means, said rather than left for the caller to infer.
+ *
+ * A drive that saved no flows is not a verified app, and the four ways of getting there need
+ * different answers: a model that finished without recording needs a persona, one that ran out of
+ * budget needs more of it, one that stalled needs a look, and a broken one needs its error read.
+ */
+const NOTHING_RECORDED = {
+    [StopReason.FINISHED]: 'The drive finished without saving a flow, so nothing is proved and nothing will replay. Give it a `persona` — a journey to complete — and it will record one.',
+    [StopReason.BUDGET]: 'The drive ran out of steps before saving a flow. Raise `maxSteps`, or give it a narrower `persona` so it spends the budget on one journey.',
+    [StopReason.STALLED]: 'The drive stopped asking for tools without finishing. Nothing was saved, and nothing is proved.',
+    [StopReason.BROKEN]: 'The drive broke before saving anything — read `error`. Nothing is proved.',
+};

package/dist/surface/tools/feature-capture.d.ts

@@ -0,0 +1,151 @@
+import { type Intent, type JournalAction } from '@reticlehq/core/artifacts';
+/**
+ * Were `reticle_context` and `reticle_intent` used at all — and did using them change anything?
+ *
+ * Both shipped with the same pre-registered disproof: *if agents never call it, cut it*. Nothing
+ * recorded whether they were called, so the disproof could never be run, and a feature whose
+ * disproof cannot be run is one nobody can kill. This is the smallest thing that makes the question
+ * answerable, per session, locally — an instrument, not a scold. The numbers exist so a FEATURE can
+ * be removed, never so an agent can be blamed for how it drove.
+ *
+ * ## Fold first, record only what nothing records
+ *
+ * Three of the four questions are already answerable from what is on disk. The intent ledger says
+ * what was declared; the journal says what was driven and what verdicts were drawn. Those are folded
+ * here and never re-stored, for the reason `run-context.ts` gives at length: two ways to compute one
+ * number is worse than one way.
+ *
+ * The journal does NOT record read-only calls — it holds actions and verdicts only. So "was
+ * `reticle_context` called" has no ledger to fold, and that one thing is recorded, in memory, on the
+ * session, by `CaptureLedger`. It is the whole of the new state.
+ *
+ * ## Absent is not zero
+ *
+ * A session this daemon has recorded nothing for — journaling off, a session adopted after the fact
+ * — reports `observed: false` and states no counts at all. It has not established that the features
+ * went unused; it has established that it was not watching. This repo has shipped the other bug
+ * twice.
+ */
+/**
+ * The calls this instrument needs and the journal does not keep.
+ *
+ * Deliberately a short explicit list rather than "everything that is not an action". Under-inclusion
+ * is the safe direction: a read tool missing from here lowers the hit side and the miss side by the
+ * same call, so the comparison the disproof turns on stays fair. Over-inclusion is not — a lifecycle
+ * or disk-side tool landing in here would be counted as a "read" the agent made of the app, which it
+ * was not.
+ */
+export declare const CAPTURED_TOOLS: ReadonlySet<string>;
+/** One recorded call: which tool, what it was about, and how far into the run it happened. */
+export interface CapturedCall {
+    tool: string;
+    /** The ref or target the call named, when it named one. Absent for a whole-page read. */
+    subject?: string;
+    /**
+     * The session's dispatched-action count at the moment of the call — the same counter that mints
+     * journal action ids, so it lines up with `reticle_context`'s own `step` whenever the journal is on.
+     */
+    afterActions: number;
+}
+/**
+ * The one thing that is stored rather than folded: the read-only calls the journal never sees.
+ *
+ * In memory and per session, the same shape as `GapLedger`. It is not durable on purpose — the
+ * question is about one run, and a second file on disk would be a second thing to reconcile with the
+ * journal.
+ */
+export declare class CaptureLedger {
+    #private;
+    /**
+     * One call, under the name of the tool that RAN — every tool, not just the read set above.
+     *
+     * Separate from `note` because it answers a different question and is bounded differently: this
+     * map cannot outgrow the tool table however long the session runs, so it needs no cap and never
+     * has to report a floor. See surface/tools/tool-hit-rate.ts for what it feeds.
+     */
+    noteTool(tool: string): void;
+    /** How many times each tool was called this session, in first-call order. */
+    toolCalls(): ReadonlyMap<string, number>;
+    note(call: CapturedCall): void;
+    calls(): readonly CapturedCall[];
+    /** How many calls fell off the front. Non-zero means the counts below are a floor. */
+    get dropped(): number;
+}
+/**
+ * Record one captured call against the session that made it.
+ *
+ * Tolerates a session that carries no ledger, exactly as `noteSessionGaps` does and for the same
+ * reason: `Session` is satisfied structurally, and many specs — plus any consumer embedding this
+ * engine — build one as an object literal. Such a session is a real caller that simply keeps no
+ * ledger, and an instrument must never be the reason a tool call throws. Its calls are then absent
+ * rather than counted as zero, which is what `observed: false` exists to say.
+ */
+export declare function noteCapturedCall(session: {
+    capture?: CaptureLedger;
+    actionCount?: number;
+}, call: Omit<CapturedCall, 'afterActions'>): void;
+/**
+ * Count one call against the session that made it, whichever tool it was.
+ *
+ * Tolerant of a ledger-less session for exactly the reason `noteCapturedCall` is: its calls are then
+ * absent rather than counted as zero, which is what `observed: false` exists to say.
+ */
+export declare function noteToolDispatched(session: {
+    capture?: CaptureLedger;
+}, tool: string): void;
+/** What one session's use of the two features looks like. Everything but `observed` is omitted when nothing was recorded. */
+interface FeatureCapture {
+    /** False when this daemon recorded nothing for the session — "not watched", never "not used". */
+    observed: boolean;
+    /** The ledger dropped calls, so every count is a floor. Present only when true. */
+    truncated?: boolean;
+    context?: {
+        calls: number;
+        /** The dispatched-action count each call was made at, in order. */
+        atSteps: number[];
+        acted: number;
+        refetched: number;
+        readOther: number;
+        nothingAfter: number;
+    };
+    intents?: {
+        declared: number;
+        open: number;
+    };
+    missed?: {
+        verdictsWithNoIntentDeclared: number;
+        refetchedEstablished: number;
+    };
+}
+/**
+ * Did calling `reticle_context` change what happened next?
+ *
+ * The mechanical proxy, stated so it can be argued with: look at the very next recorded call. If an
+ * action was dispatched before it — the action counter moved — the agent ACTED, and the context
+ * plausibly helped. If instead the next call is a read of a subject the context had just supplied,
+ * the agent re-fetched what it had been handed, and the context did not help.
+ *
+ * ## What this proxy CANNOT see
+ *
+ *  - Whether the agent READ the response, reasoned over it, or wrote a better answer from it. There
+ *    is no signal for that anywhere, and this must not be mistaken for one.
+ *  - Anything that happens between two Reticle calls: source edits, calls to other MCP servers, a
+ *    turn ending, a human interrupting. A long gap is invisible and reads as adjacency.
+ *  - Reads that name no ref or target (a whole-page snapshot). They land in `readOther`, never in
+ *    `refetched`, so a snapshot that duplicated the context is under-counted, not over-counted.
+ *  - Causation. `acted` is proximity in a call sequence, nothing more. An agent that would have acted
+ *    anyway is indistinguishable from one the context unblocked.
+ *  - `reticle_context` called with no session connected — it answers there by design, and there is no
+ *    per-session ledger to record it against, so those calls are missing entirely.
+ *  - Two agents driving one session. Their calls interleave into one sequence and "next call" stops
+ *    meaning "next thing that agent did".
+ */
+export declare function foldFeatureCapture(input: {
+    calls: readonly CapturedCall[];
+    dropped: number;
+    actions: readonly JournalAction[];
+    intents: readonly Intent[];
+    /** The session's dispatched-action count now, so a run that ended on an action is not read as idle. */
+    finalActions: number;
+}): FeatureCapture;
+export {};

package/dist/surface/tools/feature-capture.js

@@ -0,0 +1,235 @@
+import { IntentState, JournalVerdictEffectSchema, RUN_ESTABLISHED_CAP, } from '@reticlehq/core/artifacts';
+import { subjectOf } from '../../judgement/runs/artifact/run-context.js';
+import { ReticleTool } from '@reticlehq/core';
+/**
+ * Were `reticle_context` and `reticle_intent` used at all — and did using them change anything?
+ *
+ * Both shipped with the same pre-registered disproof: *if agents never call it, cut it*. Nothing
+ * recorded whether they were called, so the disproof could never be run, and a feature whose
+ * disproof cannot be run is one nobody can kill. This is the smallest thing that makes the question
+ * answerable, per session, locally — an instrument, not a scold. The numbers exist so a FEATURE can
+ * be removed, never so an agent can be blamed for how it drove.
+ *
+ * ## Fold first, record only what nothing records
+ *
+ * Three of the four questions are already answerable from what is on disk. The intent ledger says
+ * what was declared; the journal says what was driven and what verdicts were drawn. Those are folded
+ * here and never re-stored, for the reason `run-context.ts` gives at length: two ways to compute one
+ * number is worse than one way.
+ *
+ * The journal does NOT record read-only calls — it holds actions and verdicts only. So "was
+ * `reticle_context` called" has no ledger to fold, and that one thing is recorded, in memory, on the
+ * session, by `CaptureLedger`. It is the whole of the new state.
+ *
+ * ## Absent is not zero
+ *
+ * A session this daemon has recorded nothing for — journaling off, a session adopted after the fact
+ * — reports `observed: false` and states no counts at all. It has not established that the features
+ * went unused; it has established that it was not watching. This repo has shipped the other bug
+ * twice.
+ */
+/**
+ * The calls this instrument needs and the journal does not keep.
+ *
+ * Deliberately a short explicit list rather than "everything that is not an action". Under-inclusion
+ * is the safe direction: a read tool missing from here lowers the hit side and the miss side by the
+ * same call, so the comparison the disproof turns on stays fair. Over-inclusion is not — a lifecycle
+ * or disk-side tool landing in here would be counted as a "read" the agent made of the app, which it
+ * was not.
+ */
+export const CAPTURED_TOOLS = new Set([
+    ReticleTool.CONTEXT,
+    ReticleTool.SNAPSHOT,
+    ReticleTool.QUERY,
+    ReticleTool.INSPECT,
+    ReticleTool.STATE,
+    // All four of the above, merged, on the `merged` surface. A read is a read under either name.
+    ReticleTool.LOOK,
+    ReticleTool.STORAGE,
+    ReticleTool.NETWORK,
+    ReticleTool.CONSOLE,
+    ReticleTool.OBSERVE,
+    ReticleTool.EXPLORE,
+]);
+/**
+ * How many calls the ledger holds before it starts dropping the oldest.
+ *
+ * A verification loop is 50–200 calls, so this is not reached in normal use; it exists so a runaway
+ * session cannot grow a per-session array without bound. When it IS reached the report says
+ * `truncated` rather than presenting a short count as a complete one.
+ */
+const CAPTURE_CAP = 2000;
+/**
+ * The one thing that is stored rather than folded: the read-only calls the journal never sees.
+ *
+ * In memory and per session, the same shape as `GapLedger`. It is not durable on purpose — the
+ * question is about one run, and a second file on disk would be a second thing to reconcile with the
+ * journal.
+ */
+export class CaptureLedger {
+    #calls = [];
+    #dropped = 0;
+    #tools = new Map();
+    /**
+     * One call, under the name of the tool that RAN — every tool, not just the read set above.
+     *
+     * Separate from `note` because it answers a different question and is bounded differently: this
+     * map cannot outgrow the tool table however long the session runs, so it needs no cap and never
+     * has to report a floor. See surface/tools/tool-hit-rate.ts for what it feeds.
+     */
+    noteTool(tool) {
+        this.#tools.set(tool, (this.#tools.get(tool) ?? 0) + 1);
+    }
+    /** How many times each tool was called this session, in first-call order. */
+    toolCalls() {
+        return this.#tools;
+    }
+    note(call) {
+        this.#calls.push(call);
+        if (this.#calls.length > CAPTURE_CAP) {
+            this.#calls.shift();
+            this.#dropped += 1;
+        }
+    }
+    calls() {
+        return this.#calls;
+    }
+    /** How many calls fell off the front. Non-zero means the counts below are a floor. */
+    get dropped() {
+        return this.#dropped;
+    }
+}
+/**
+ * Record one captured call against the session that made it.
+ *
+ * Tolerates a session that carries no ledger, exactly as `noteSessionGaps` does and for the same
+ * reason: `Session` is satisfied structurally, and many specs — plus any consumer embedding this
+ * engine — build one as an object literal. Such a session is a real caller that simply keeps no
+ * ledger, and an instrument must never be the reason a tool call throws. Its calls are then absent
+ * rather than counted as zero, which is what `observed: false` exists to say.
+ */
+export function noteCapturedCall(session, call) {
+    session.capture?.note({ ...call, afterActions: session.actionCount ?? 0 });
+}
+/**
+ * Count one call against the session that made it, whichever tool it was.
+ *
+ * Tolerant of a ledger-less session for exactly the reason `noteCapturedCall` is: its calls are then
+ * absent rather than counted as zero, which is what `observed: false` exists to say.
+ */
+export function noteToolDispatched(session, tool) {
+    session.capture?.noteTool(tool);
+}
+/**
+ * Every point in the run at which each subject became an established fact.
+ *
+ * "Established" is not a second definition: it is the rule `establishedFromJournal` folds by — an
+ * action with an observed settle outcome, filed under the ref or target it named — and `subjectOf`
+ * is imported from there rather than rewritten, so the two cannot drift apart.
+ */
+function establishedIndexes(actions) {
+    const out = new Map();
+    actions.forEach((action, index) => {
+        if (undefined === action.settled)
+            return;
+        const key = subjectOf(action);
+        if (undefined === key)
+            return;
+        const at = out.get(key);
+        if (at === undefined)
+            out.set(key, [index]);
+        else
+            at.push(index);
+    });
+    return out;
+}
+/** Was this subject already an established fact by the time a call at `afterActions` was made? */
+function wasEstablished(index, subject, afterActions) {
+    if (undefined === subject)
+        return false;
+    const at = index.get(subject);
+    if (at === undefined)
+        return false;
+    // Action `i` has been dispatched once the counter reads `i + 1`, so `i + 1 <= afterActions` is
+    // "already true when the call was made" — which is what keeps a FIRST look off this count. The
+    // lower bound is the run context's own window: a fact that has scrolled past RUN_ESTABLISHED_CAP
+    // is not something `reticle_context` would have handed back, so re-reading it is not a re-fetch.
+    return at.some((i) => i + 1 <= afterActions && i + 1 > afterActions - RUN_ESTABLISHED_CAP);
+}
+/**
+ * Did calling `reticle_context` change what happened next?
+ *
+ * The mechanical proxy, stated so it can be argued with: look at the very next recorded call. If an
+ * action was dispatched before it — the action counter moved — the agent ACTED, and the context
+ * plausibly helped. If instead the next call is a read of a subject the context had just supplied,
+ * the agent re-fetched what it had been handed, and the context did not help.
+ *
+ * ## What this proxy CANNOT see
+ *
+ *  - Whether the agent READ the response, reasoned over it, or wrote a better answer from it. There
+ *    is no signal for that anywhere, and this must not be mistaken for one.
+ *  - Anything that happens between two Reticle calls: source edits, calls to other MCP servers, a
+ *    turn ending, a human interrupting. A long gap is invisible and reads as adjacency.
+ *  - Reads that name no ref or target (a whole-page snapshot). They land in `readOther`, never in
+ *    `refetched`, so a snapshot that duplicated the context is under-counted, not over-counted.
+ *  - Causation. `acted` is proximity in a call sequence, nothing more. An agent that would have acted
+ *    anyway is indistinguishable from one the context unblocked.
+ *  - `reticle_context` called with no session connected — it answers there by design, and there is no
+ *    per-session ledger to record it against, so those calls are missing entirely.
+ *  - Two agents driving one session. Their calls interleave into one sequence and "next call" stops
+ *    meaning "next thing that agent did".
+ */
+export function foldFeatureCapture(input) {
+    const { calls, actions, intents } = input;
+    if (0 === calls.length && 0 === actions.length)
+        return { observed: false };
+    const established = establishedIndexes(actions);
+    const isRefetch = (call) => ReticleTool.CONTEXT !== call.tool &&
+        wasEstablished(established, call.subject, call.afterActions);
+    let acted = 0;
+    let refetched = 0;
+    let readOther = 0;
+    let nothingAfter = 0;
+    const atSteps = [];
+    calls.forEach((call, i) => {
+        if (ReticleTool.CONTEXT !== call.tool)
+            return;
+        atSteps.push(call.afterActions);
+        const next = calls[i + 1];
+        if (next === undefined) {
+            if (input.finalActions > call.afterActions)
+                acted += 1;
+            else
+                nothingAfter += 1;
+            return;
+        }
+        if (next.afterActions > call.afterActions)
+            acted += 1;
+        else if (isRefetch(next))
+            refetched += 1;
+        else
+            readOther += 1;
+    });
+    // A verdict is any journal action carrying the bounded verdict effect both verification tools
+    // write. Parsed with core's own schema rather than a local shape, for the usual reason.
+    const verdicts = actions.filter((a) => JournalVerdictEffectSchema.safeParse(a.effect).success);
+    return {
+        observed: true,
+        ...(input.dropped > 0 ? { truncated: true } : {}),
+        context: { calls: atSteps.length, atSteps, acted, refetched, readOther, nothingAfter },
+        intents: {
+            declared: intents.length,
+            open: intents.filter((it) => IntentState.PROVED !== it.state).length,
+        },
+        missed: {
+            // The coarse question, asked honestly. Nothing binds a verdict to a specific intent outside
+            // flow replay, so "covered" cannot mean "this intent proves this verdict" without inventing a
+            // link Reticle cannot observe — the same reason `undeclared-change.ts` asks only whether
+            // anything at all was declared. So this counts verdicts drawn against an EMPTY ledger, and
+            // stops at zero once anything is declared. That zero is not a claim that every verdict was
+            // covered; it is the end of what this can see.
+            verdictsWithNoIntentDeclared: 0 === intents.length ? verdicts.length : 0,
+            refetchedEstablished: calls.filter(isRefetch).length,
+        },
+    };
+}

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

@@ -0,0 +1,48 @@
+/**
+ * The one line that tells an agent it can push back — worded for what just happened.
+ *
+ * Feedback is the highest-yield channel this product has: a handful of reports from agents in the
+ * field produced most of a release's fixes, while the structured telemetry beside them produced a
+ * funnel that turned out to be broken. Prose from an agent at the moment of friction beats any
+ * structured field we could add.
+ *
+ * It reached those agents through a standing instruction in the MCP handshake — paid once at
+ * connect. The gap that leaves is the agent who hits something mid-task and is concentrating on the
+ * problem rather than on remembering that a feedback tool exists.
+ *
+ * So: invite at the moment of friction, and vary the wording. A fixed string repeated forty times
+ * is invisible by call five; a line that names what just went wrong is read because it is about the
+ * thing the agent is already looking at. A dozen tokens against a turn measured in thousands.
+ *
+ * Every invite is counted (`feedbackPrompted`). If `feedback_submitted ÷ feedbackPrompted` stays
+ * flat, this is decoration and should be deleted — instrumenting our own nudge is the difference
+ * between a designed system and a hope.
+ */
+/** What just happened, as far as the chokepoint can tell. Ordered most specific first. */
+export declare const FrictionKind: {
+    /** A tool that does not exist — the agent named a capability it expected us to have. */
+    readonly UNKNOWN_TOOL: "unknown_tool";
+    /** A verdict came back `unknown`: we drove the app and could not tell what happened. */
+    readonly UNKNOWN_VERDICT: "unknown_verdict";
+    /** The same tool, several times in a row. */
+    readonly REPEATING: "repeating";
+    /** The tool refused or errored. */
+    readonly REFUSED: "refused";
+};
+export type FrictionKind = (typeof FrictionKind)[keyof typeof FrictionKind];
+/**
+ * Which friction, if any, this result represents.
+ *
+ * Deliberately reads only what the chokepoint already has: no handler changes, and nothing here can
+ * see app data.
+ */
+export declare function frictionOf(facts: {
+    unknownTool: boolean;
+    verifiedUnknown: boolean;
+    repeatRun: number;
+    errored: boolean;
+    /** Did this call produce a verdict? A verdict is progress, and progress is not being stuck. */
+    producedVerdict: boolean;
+}): FrictionKind | undefined;
+/** The line for a friction kind. */
+export declare function inviteFor(kind: FrictionKind): string;

package/dist/surface/tools/feedback-invite.js

@@ -0,0 +1,71 @@
+/**
+ * The one line that tells an agent it can push back — worded for what just happened.
+ *
+ * Feedback is the highest-yield channel this product has: a handful of reports from agents in the
+ * field produced most of a release's fixes, while the structured telemetry beside them produced a
+ * funnel that turned out to be broken. Prose from an agent at the moment of friction beats any
+ * structured field we could add.
+ *
+ * It reached those agents through a standing instruction in the MCP handshake — paid once at
+ * connect. The gap that leaves is the agent who hits something mid-task and is concentrating on the
+ * problem rather than on remembering that a feedback tool exists.
+ *
+ * So: invite at the moment of friction, and vary the wording. A fixed string repeated forty times
+ * is invisible by call five; a line that names what just went wrong is read because it is about the
+ * thing the agent is already looking at. A dozen tokens against a turn measured in thousands.
+ *
+ * Every invite is counted (`feedbackPrompted`). If `feedback_submitted ÷ feedbackPrompted` stays
+ * flat, this is decoration and should be deleted — instrumenting our own nudge is the difference
+ * between a designed system and a hope.
+ */
+/** What just happened, as far as the chokepoint can tell. Ordered most specific first. */
+export const FrictionKind = {
+    /** A tool that does not exist — the agent named a capability it expected us to have. */
+    UNKNOWN_TOOL: 'unknown_tool',
+    /** A verdict came back `unknown`: we drove the app and could not tell what happened. */
+    UNKNOWN_VERDICT: 'unknown_verdict',
+    /** The same tool, several times in a row. */
+    REPEATING: 'repeating',
+    /** The tool refused or errored. */
+    REFUSED: 'refused',
+};
+/**
+ * Runs of one tool before it counts as being stuck.
+ *
+ * Three, matching the verdict nudge. `reticle_act` is the tool that repeats most in practice, and
+ * a run of three is where a deliberate retry becomes a loop.
+ */
+const REPEAT_INVITE_AT = 3;
+const LINES = {
+    [FrictionKind.UNKNOWN_TOOL]: 'no such tool — reticle_feedback tells us what you expected it to do, which is how it gets built',
+    [FrictionKind.UNKNOWN_VERDICT]: 'Reticle could not tell what happened here. If you expected otherwise, reticle_feedback. An ' +
+        'unknown verdict is our defect, not yours',
+    [FrictionKind.REPEATING]: 'stuck on the same call? reticle_feedback — say what you were trying to do and it gets fixed',
+    [FrictionKind.REFUSED]: 'if that diagnosis was wrong or unhelpful, reticle_feedback — error messages are a product ' +
+        'surface and we fix the ones that fail',
+};
+/**
+ * Which friction, if any, this result represents.
+ *
+ * Deliberately reads only what the chokepoint already has: no handler changes, and nothing here can
+ * see app data.
+ */
+export function frictionOf(facts) {
+    if (facts.unknownTool)
+        return FrictionKind.UNKNOWN_TOOL;
+    if (facts.verifiedUnknown)
+        return FrictionKind.UNKNOWN_VERDICT;
+    // Repetition is only friction when it is repetition WITHOUT PROGRESS. Found by driving the Tauri
+    // smoke app: three consecutive SUCCESSFUL act_and_wait calls, each producing a verdict, were
+    // answered with "stuck on the same call?" — nagging the exact loop this release exists to
+    // encourage. A verdict is progress.
+    if (facts.repeatRun >= REPEAT_INVITE_AT && !facts.producedVerdict)
+        return FrictionKind.REPEATING;
+    if (facts.errored)
+        return FrictionKind.REFUSED;
+    return undefined;
+}
+/** The line for a friction kind. */
+export function inviteFor(kind) {
+    return LINES[kind];
+}