@reticlehq/server 3.1.0 → 3.3.0

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

@@ -8,7 +8,7 @@ export declare const FEEDBACK_TOOLS: ToolDef[];
  * 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: {
+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";
 };
@@ -33,3 +33,4 @@ export declare const VERDICT_TOOLS: ReadonlySet<string>;
  */
 export declare function takeFeedbackPrompt(toolName: string): typeof FEEDBACK_PROMPT | undefined;
 export declare function resetFeedbackPrompt(): void;
+export {};

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

@@ -55,6 +55,15 @@ function sessionFacts(deps, sessionId) {
         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,
@@ -72,8 +81,22 @@ export const FEEDBACK_TOOLS = [
                 .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)
+                .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()
@@ -124,10 +147,26 @@ export const FEEDBACK_TOOLS = [
             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: asString(args['text']) ?? '',
+                text: body,
                 ...optionalText(args, 'trace'),
                 ...optionalText(args, 'need'),
                 ...optionalText(args, 'impact'),
@@ -157,7 +196,7 @@ export const FEEDBACK_TOOLS = [
  * 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 = {
+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',
 };
@@ -187,6 +226,14 @@ export const VERDICT_TOOLS = new Set([
     // 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.

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/harness-explore.d.ts

@@ -8,7 +8,9 @@
  * deterministically with no model in the loop at all.
  */
 import type { ToolDeps } from './tool-kit.js';
-import { type HarnessResult, type ModelDriver } from '../../features/harness/harness.js';
+import { type HarnessPlan } from './harness-plan.js';
+import { type ConfigFetch } from '../../features/harness/platform-config.js';
+import { type HarnessResult, type ModelDriver, type ToolOutcome } from '../../features/harness/harness.js';
 export interface ExploreOptions {
     /** Who to be, or what to accomplish. Appended to the standing instruction. */
     focus?: string;
@@ -16,13 +18,61 @@ export interface ExploreOptions {
     sessionId?: string;
     /** Hard ceiling on model turns. Bounds cost, not value — the drive is usable however it ends. */
     maxSteps?: number;
+    /**
+     * Which driver to use for THIS drive, overriding the environment.
+     *
+     * Per-call rather than only per-daemon because the question people actually have is comparative —
+     * "is the cheap driver good enough for my app?" — and answering it with an environment variable
+     * means restarting the daemon between arms, which is exactly the setup that let a stale daemon
+     * answer three runs of our own benchmark with one configuration.
+     */
+    driverName?: string;
     /** Injected for tests, and for anyone driving with a model this repo does not ship a binding for. */
     driver?: ModelDriver;
+    /**
+     * Skip asking the platform which driver this project prefers.
+     *
+     * Set by tests and by callers that have already decided. Not a user-facing switch: naming a
+     * driver explicitly already skips the lookup, which is the only reason anybody would want to.
+     */
+    skipPlatformConfig?: boolean;
+    /**
+     * The GET that asks the platform what this project wants. Injected ONLY by tests.
+     *
+     * It exists because the two things this answer decides — a driver preference and whether the drive
+     * may happen at all — were both unreachable without a network, and the refusal test that was
+     * supposed to cover the OFF switch was asserting on a path where the platform is never asked.
+     */
+    configFetch?: ConfigFetch;
 }
 export interface ExploreResult {
     drive: HarnessResult;
+    /** What the drive set out to do, read from `.reticle` before it started. */
+    plan: HarnessPlan;
     /** Flows that exist now and did not before — the part of a drive that is worth paying for twice. */
     savedFlows: readonly string[];
+    /**
+     * Flows that already existed and were written again by this drive.
+     *
+     * Split from `savedFlows` because the before/after name diff cannot see a rewrite, and read on its
+     * own it reported a drive that saved a perfectly good ten-step flow as having saved nothing — over
+     * which the caller was told "nothing is proved and nothing will replay". That sentence was false,
+     * and a false "nothing was verified" is the same class of mistake as a false "everything passed":
+     * the product exists to stop a drive lying about its own outcome, including to us.
+     *
+     * It happens on any SECOND drive, because a drive that covers the same app records the same
+     * journeys under the same names — so this is the ordinary case, not the corner one.
+     */
+    rewroteFlows: readonly string[];
+    /**
+     * Which driver actually drove.
+     *
+     * Reported rather than re-derived by the caller. A second copy of "which driver would be chosen"
+     * is a copy that can disagree with the one that chose, and the whole point of naming a driver is
+     * to attribute a result to it — a comparison that mislabels its own arms is worse than no
+     * comparison. `custom` is an injected driver, which is neither of ours to name.
+     */
+    driverName: string;
 }
 /**
  * Why the harness is unavailable, phrased as the way to make it available.
@@ -32,6 +82,29 @@ export interface ExploreResult {
  * print it, and two copies of this sentence would drift.
  */
 export declare const MSG_NO_HARNESS_KEY: string;
+/** Asked for Jev specifically and it is not configured. Distinct from having no model at all. */
+export declare const MSG_NO_JEV_KEY: string;
+/** Asked for OpenAI specifically and it is not configured. Never substituted, same as Jev. */
+export declare const MSG_NO_OPENAI_KEY: string;
+/**
+ * The environment, plus the credential this machine already has.
+ *
+ * `reticle link` mints a project-scoped key and files it in `~/.reticle/credentials.json`; the CLI
+ * has read it from there for as long as it has existed. The harness did not, and read only
+ * `process.env` — so somebody who had signed in, linked their project and been told they were
+ * connected still got "no model configured to drive the app", and the only way out was to find the
+ * key in the console and export it by hand. Five manual steps to reach a feature they had already
+ * finished setting up.
+ *
+ * Resolved into the env rather than threaded through four call sites: the drivers and the
+ * preference lookup all read an env record, and giving them a completed one leaves each of them
+ * exactly as simple as it was. An EXPLICIT variable still wins — someone who exported a key meant
+ * that key, and CI has no linked project to read.
+ *
+ * The credential arrives through `deps.linkedCloud`, a port, because resolving it here would make
+ * the tool surface reach into `memory/cloud` — a reach the directory guard refused, correctly.
+ */
+export declare function withLinkedCredential(deps: ToolDeps, env: Record<string, string | undefined>): Promise<Record<string, string | undefined>>;
 /** Is there a model the harness can drive with? A read, because "not configured" is not a failure. */
 export declare function harnessAvailable(env: Record<string, string | undefined>): boolean;
 /**
@@ -51,3 +124,54 @@ export declare function maxStepsFromEnv(env: Record<string, string | undefined>)
  * record and did not — and this product does not get to make that mistake about its own work.
  */
 export declare function exploreApp(deps: ToolDeps, env: Record<string, string | undefined>, options?: ExploreOptions): Promise<ExploreResult>;
+/**
+ * What a drive actually left behind, split into flows that are NEW and flows it wrote over.
+ *
+ * Pure, and exported, because it is the part that was wrong and the part worth pinning. The
+ * integration around it — a real toolset dispatching a real save — is covered by driving a real app;
+ * what a test can usefully hold still is the reconciliation itself.
+ *
+ * A rewrite is only counted when the drive claims the save AND the store lists the name afterwards.
+ * The claim on its own is not evidence, which is the rule this function existed to keep: a model
+ * that says it saved something it did not must not be believed. Requiring both is what lets a
+ * rewrite be seen at all, since a name that was already there cannot show up in a before/after diff.
+ */
+export declare function reconcileFlows(before: ReadonlySet<string>, after: readonly string[], toolCalls: readonly {
+    name: string;
+    args: Record<string, unknown>;
+    result: unknown;
+    isError: boolean;
+}[]): {
+    savedFlows: readonly string[];
+    rewroteFlows: readonly string[];
+};
+/**
+ * What a person said about autonomous driving on the platform, honoured here.
+ *
+ * The switch existed, persisted and round-tripped, and the daemon read it and threw it away — so
+ * turning the harness OFF changed a value in a database and nothing else. A control that does not
+ * control anything is worse than no control: somebody turns it off, watches Reticle drive their app
+ * anyway, and now correctly distrusts every other switch in the product.
+ *
+ * Absent means ON. The platform's own default is on, and a machine that cannot reach the platform —
+ * offline, CI, no link — must not silently lose a feature it was never told to stop using.
+ */
+export declare const MSG_HARNESS_DISABLED: string;
+/**
+ * The other reason a drive can be refused, and it is NOT the same reason.
+ *
+ * A drive through the platform spends Reticle's model budget. That is free for three months and
+ * included on a paid plan, and outside both it is somebody else's money being spent on nothing. The
+ * message says which of the two it is and what to do, because "the harness is off" told to a person
+ * who never turned anything off is a support ticket rather than an answer.
+ */
+export declare const MSG_HARNESS_UNCLAIMED: string;
+/**
+ * A stored preference, kept only if this build can actually honour it.
+ *
+ * Exported because it is the whole of the asymmetry with the per-call argument, and the asymmetry
+ * is the part somebody will later think is a bug.
+ */
+export declare function knownDriver(provider: string | undefined): string | undefined;
+/** The recording started and never stopped, if there is one. Exported because it is the decision. */
+export declare function openRecordingName(toolCalls: readonly ToolOutcome[]): string | undefined;