@reticlehq/server 3.6.0 → 3.7.0

package/dist/surface/tools/error-recovery.js

@@ -8,8 +8,9 @@
  * on stable, human-authored substrings of the thrown messages (see session-manager.ts, the flow/
  * baseline stores). No clock, no IO — unit-testable in isolation.
  */
-import { RefusalReason, ReticleEnv, TRANSPORT_LIMITS } from '@reticlehq/core';
+import { RefusalReason, ReticleEnv, TRANSPORT_LIMITS, UNISSUED_REF_REFUSAL } from '@reticlehq/core';
 import { SELF_RECOVERING_MARKER } from '../../portal/session/no-session-diagnosis.js';
+import { MSG_HARNESS_DISABLED, MSG_HARNESS_UNCLAIMED, MSG_HARNESS_UNCONFIRMED, PlatformRefusalCode, RefusalLead, } from '../../features/harness/platform/refusal.js';
 import { BODY_CLAUSE_REFUSAL_OPENING } from '@reticlehq/engine/evidence/body-capture-remedy.js';
 import { CHROMIUM_PATH_REFUSAL_PREFIX, chromiumInstallCommand, bundledPlaywrightVersion, } from '../../command/cli/doctor/browser/chromium-hint.js';
 /** Marks where an over-long message had its middle removed. Named so tests assert it by value. */
@@ -64,6 +65,16 @@ const SELF_RECOVERING = [
     // asked for a bug report about somebody's connect() options.
     { match: literally(BODY_CLAUSE_REFUSAL_OPENING), reason: RefusalReason.UNSUPPORTED },
 ];
+/**
+ * The refusal for a `ref` Reticle never minted — decided BEFORE every other rule, not by one inside
+ * the table. The message echoes the caller's own string, and every pattern below matches on words:
+ * a ref reading `Connected right now:` was read as a missing session, and one opening with the
+ * Chromium-path prefix as browser configuration. The marker is Reticle's own wording, so testing it
+ * first classifies the refusal by what it IS rather than by what the caller typed into it.
+ */
+function isUnissuedRefRefusal(message) {
+    return message.includes(UNISSUED_REF_REFUSAL);
+}
 /** A message that already carries its own concrete next action, so nothing should be appended. */
 function isSelfRecovering(message) {
     if (message.includes(SELF_RECOVERING_MARKER))
@@ -96,7 +107,16 @@ export const RECOVERY = {
         'navigated, opened a modal, re-sorted a list or changed the page invalidates every ref taken ' +
         'before it. Reticle refuses here rather than clicking whatever now occupies that slot. Call ' +
         'reticle_query again for a fresh ref and retry the action — and prefer reticle_act_and_wait ' +
-        '{ until } when an action changes the page, so the next ref is taken after it settles.',
+        '{ until } when an action changes the page, so the next ref is taken after it settles. On a ' +
+        'page that keeps re-rendering (a dashboard that refetches), skip the ref and pass ' +
+        '`target: { role, name }`, `{ label }` or `{ text }` instead: it is looked up in the same call ' +
+        'as the action, which shrinks the window a re-render can invalidate it in, though a render ' +
+        'landing between the lookup and the action can still refuse it — retry once if it does.',
+    UNISSUED_REF: 'The `ref` was not one Reticle handed out, so nothing was looked up and nothing was acted on. ' +
+        'Refs are minted by reticle_snapshot / reticle_query and look like e12. To name an element by ' +
+        'what it shows, pass `target` instead — { label }, { role, name }, { text } or { testid } — and ' +
+        'it is found in the same call. This is an invalid call, not a Reticle defect: there is nothing ' +
+        'to report.',
     STALE_REF_AFTER_EDIT: 'That ref went stale because YOUR OWN EDIT landed: the dev server hot-updated the module named ' +
         'in the message above and the framework re-rendered, so the node the ref pointed at was ' +
         'replaced. Nothing is wrong with the app and nothing is wrong with Reticle — this is the ' +
@@ -231,10 +251,22 @@ export const RECOVERY = {
      * agent that a perfectly understood refusal might be a defect in Reticle — which is how a person
      * who deliberately switched the harness off gets a bug report filed about their own decision.
      */
-    HARNESS_OFF: 'A human turned autonomous driving off for this project, or has not claimed the free harness ' +
-        'months. This is a deliberate refusal and there is nothing to report: drive the app yourself ' +
+    HARNESS_OFF: 'The Harness is off for this project (it is opt-in), or the workspace cannot drive it now. ' +
+        'This is a deliberate refusal and there is nothing to report: drive the app yourself ' +
         'through the MCP tools — reticle_navigate, then reticle_act_and_wait with an `until` — which is ' +
         'the same verification without a model driving it.',
+    /**
+     * The Harness asked for on a project that is not linked to the platform. The call was valid, and
+     * the refusal names reticle_act_and_wait as the alternative, which the catch-all below read as an
+     * agent's malformed call: it was then told to fix arguments that were never wrong.
+     */
+    HARNESS_LOCKED: 'The Harness unlocks once Reticle sees enough of this app; the refusal names what is missing ' +
+        'and how to close each gap. Nothing to report: close them, or drive the journey yourself with ' +
+        'reticle_act_and_wait and an `until` on its last step. Every other tool works at any coverage.',
+    HARNESS_NOT_LINKED: 'This project is not linked to the Reticle platform, where the Harness runs. The call itself was ' +
+        'valid. Either the human runs `npx @reticlehq/server connect` once in the app directory, or you ' +
+        'drive the journey yourself: reticle_navigate, then reticle_act_and_wait with an `until` on its ' +
+        'last step. There is nothing to report.',
 };
 /**
  * Which OWNER each recovery belongs to, for `tool_refused`.
@@ -260,6 +292,8 @@ const REASON_OF = {
     MISSING_RECORDING: RefusalReason.NO_MATCH,
     STALE_REF: RefusalReason.NO_MATCH,
     STALE_REF_AFTER_EDIT: RefusalReason.NO_MATCH,
+    // The caller passed something that was never a ref: a malformed call, not a page that moved.
+    UNISSUED_REF: RefusalReason.BAD_ARGS,
     NO_SUCH_OPTION: RefusalReason.NO_MATCH,
     TARGET_MISSED: RefusalReason.NO_MATCH,
     // Target resolution failed to name one element. NO_MATCH rather than BAD_ARGS: the arguments were
@@ -275,10 +309,17 @@ const REASON_OF = {
     INVALID_NAME: RefusalReason.BAD_ARGS,
     // Nothing about the app or the call is wrong; the feature is switched off or unpaid for.
     HARNESS_OFF: RefusalReason.UNSUPPORTED,
+    // Nothing about the call is wrong either; the project is not linked yet.
+    HARNESS_NOT_LINKED: RefusalReason.UNSUPPORTED,
+    // The call is valid; the app is not instrumented enough for the Harness yet.
+    HARNESS_LOCKED: RefusalReason.UNSUPPORTED,
 };
 /** Hint text back to its reason. The hints are distinct strings, so this inverts cleanly. */
 const REASON_BY_HINT = new Map(Object.entries(RECOVERY).map(([key, hint]) => [hint, REASON_OF[key]]));
 /** Ordered match rules; the first hit wins. Substrings track the thrown messages they recover. */
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** Matches a message that opens with any of these sentences (their first sentence, as said). */
+const startsWithAny = (sentences) => new RegExp(`^(?:${sentences.map((s) => escapeRegExp(s.split('. ')[0] ?? s)).join('|')})`);
 const RULES = [
     // First, because the message carries a path the user chose, and a path can hold any word a later
     // rule keys on. Without it the variable's name read as a `reticle_*` tool and the agent was told
@@ -293,9 +334,26 @@ const RULES = [
     { match: /no (?:active|compiled) recording named/i, hint: RECOVERY.MISSING_RECORDING },
     { match: /pairing token is required/i, hint: RECOVERY.TOKEN_REQUIRED },
     {
-        match: /Autonomous driving is turned OFF|no harness entitlement/i,
+        // Credits spent, not entitled, or the platform not answering: deliberate refusals, each naming
+        // its own way out, never "may be a defect in Reticle".
+        match: startsWithAny([
+            RefusalLead[PlatformRefusalCode.HARNESS_OFF],
+            RefusalLead[PlatformRefusalCode.NEEDS_CARD],
+            MSG_HARNESS_DISABLED,
+            MSG_HARNESS_UNCLAIMED,
+            MSG_HARNESS_UNCONFIRMED,
+        ]),
         hint: RECOVERY.HARNESS_OFF,
     },
+    // A credits sentence is core's own wording (core/src/artifacts/harness-credits.ts), not the
+    // platform's: matching it is matching ourselves.
+    { match: /credits are used\./, hint: RECOVERY.HARNESS_OFF },
+    {
+        // The gate's own words, and the platform's "locked: connect your app first": expected states.
+        match: new RegExp(`(?:^Harness unlocks at \\d+% instrumentation)|(?:^${escapeRegExp(RefusalLead[PlatformRefusalCode.HARNESS_LOCKED])})`),
+        hint: RECOVERY.HARNESS_LOCKED,
+    },
+    { match: /The Reticle Harness runs on the Reticle platform/, hint: RECOVERY.HARNESS_NOT_LINKED },
     // Three conditions the daemon understands perfectly and still asked for a bug report about. Each
     // needs its own rule: none of them contains "no browser session connected" (the scope miss is
     // "no browser session FOR project 'x'", which is the opposite claim — sessions exist).
@@ -397,6 +455,8 @@ const RULES = [
  * saying a server is running and the recovery saying to go start one.
  */
 export function recoveryFor(message) {
+    if (isUnissuedRefRefusal(message))
+        return RECOVERY.UNISSUED_REF;
     if (isSelfRecovering(message))
         return undefined;
     for (const rule of RULES) {
@@ -415,6 +475,8 @@ export function recoveryFor(message) {
  */
 export function refusalReasonFor(rawMessage) {
     const message = zodArrayAsSentence(rawMessage);
+    if (isUnissuedRefRefusal(message))
+        return RefusalReason.BAD_ARGS;
     // The no-session diagnosis inspected the machine and named the cause itself, so it never reaches
     // the recovery table. It is the single largest refusal there is; missing it would gut the metric.
     if (message.includes(SELF_RECOVERING_MARKER))
@@ -538,6 +600,8 @@ export function buildErrorPayload(rawMessage) {
     // Render the zod array BEFORE capping: the cap would otherwise truncate the JSON mid-issue and
     // leave an unparseable fragment as the agent's error text — the worst of both shapes.
     const message = capMessage(zodArrayAsSentence(rawMessage));
+    if (isUnissuedRefRefusal(message))
+        return { error: message, recovery: RECOVERY.UNISSUED_REF };
     // A self-diagnosing message gets NEITHER a generic recovery nor the feedback ask. It already
     // inspected the machine and named the cause; a second, contradictory hint is noise, and inviting a
     // bug report about a condition Reticle diagnosed itself is exactly backwards.

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

@@ -10,9 +10,28 @@
  * 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 type { ToolDef, ToolDeps } from './tool-kit.js';
+import type { ToolCall, ToolDef, ToolDeps } from './tool-kit.js';
+import { DriveStatus, type DriveControl } from '../../features/harness/drive-runs.js';
 import { type RemoteDriveOutcome } from '../../features/harness/platform/remote-drive.js';
+import type { ExploreResult } from './harness-explore.js';
+export declare const WAIT_MAX_S = 240;
 export declare const EXPLORE_TOOLS: ToolDef[];
+export declare const MSG_ALREADY_DRIVING = "A Harness drive is already running on this app; this is that drive. Poll it by runId; do not start another.";
+/** One drive, run to its end: the tool's own full answer, and how it ended. */
+export type ExploreDrive = (deps: ToolDeps, env: Record<string, string | undefined>, args: Record<string, unknown>, harness: string, control: DriveControl) => Promise<{
+    status: DriveStatus;
+    result: Record<string, unknown>;
+}>;
+/**
+ * Start a drive and wait on it for a while, or poll, stop or speak to one by `runId`.
+ *
+ * The drive itself never runs inside the call: it is started in the registry and the call waits up
+ * to `wait` seconds, so a client's timeout loses nothing. A second start on the same app answers
+ * with the drive already running rather than paying for another.
+ */
+export declare function answerExplore(deps: ToolDeps, args: Record<string, unknown>, call: ToolCall | undefined, drive: ExploreDrive): Promise<unknown>;
+/** The tool's answer for a finished drive. */
+export declare function exploreReport(explored: ExploreResult): Record<string, unknown>;
 /**
  * A drive the platform's chat asked for, run as the very tool an agent would call.
  *
@@ -20,4 +39,6 @@ export declare const EXPLORE_TOOLS: ToolDef[];
  * counted, and the chat's answer is then the same derived summary the agent would have read — never
  * a model's account of its own drive.
  */
-export declare function driveForChat(deps: ToolDeps, goal: string, sessionId?: string): Promise<RemoteDriveOutcome>;
+export declare function driveForChat(deps: ToolDeps, goal: string, sessionId?: string, planId?: string, 
+/** The person who started it acknowledged the saved flows' destructive steps. */
+confirmDangerous?: boolean): Promise<RemoteDriveOutcome>;