@reticlehq/server 2.14.0 → 3.2.0

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

@@ -1,48 +0,0 @@
-/**
- * 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: **14 reports over two days produced
- * roughly 11 of the fixes in 2.6.0**, against ~6,100 numeric events that produced a funnel which
- * turned out to be broken. Prose from an agent at the moment of friction beats any structured field
- * we could add.
- *
- * It reached those 14 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. ~12 tokens against a ~4,546 tok/turn surface.
- *
- * 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/tools/feedback-invite.js

@@ -1,71 +0,0 @@
-/**
- * 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: **14 reports over two days produced
- * roughly 11 of the fixes in 2.6.0**, against ~6,100 numeric events that produced a funnel which
- * turned out to be broken. Prose from an agent at the moment of friction beats any structured field
- * we could add.
- *
- * It reached those 14 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. ~12 tokens against a ~4,546 tok/turn surface.
- *
- * 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` led the field data at 110 consecutive-repeat
- * runs, 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];
-}

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

@@ -1,35 +0,0 @@
-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,
- * 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/tools/feedback-tools.js

@@ -1,228 +0,0 @@
-/**
- * `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 './tool-names.js';
-import { asNumber, 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 } : {};
-}
-/**
- * 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 };
-    }
-}
-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()
-                .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.'),
-            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) => {
-            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'),
-                ...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,
-    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,
-]);
-/**
- * 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/tools/invoke-tool.d.ts

@@ -1,10 +0,0 @@
-import type { ToolDef, ToolDeps } from './tools.js';
-export declare const SESSION_BOUND_TOOLS: ReadonlySet<string>;
-/**
- * Tools that carry a `sessionId` arg but are NOT live-session-health tools — they read/write
- * disk (capabilities/contract/flow/project), drain a buffer, or steer session lifecycle. They are
- * exempt from the health splice ON PURPOSE. Kept explicit so the guard test can force every new
- * `sessionId`-bearing tool to be classified into exactly one set (bound XOR exempt).
- */
-export declare const SESSION_EXEMPT_TOOLS: ReadonlySet<string>;
-export declare function runTool<Ext>(tool: ToolDef<Ext>, deps: ToolDeps<Ext>, args: Record<string, unknown>): Promise<unknown>;